@hyperframes/studio 0.8.54 → 0.8.56

package/src/player/components/Timeline.tsx

@@ -1,7 +1,6 @@
 import { useRef, useMemo, useCallback, useState, memo } from "react";
 import { useAdjustedBeatAnalysis, useMusicBeatAnalysis } from "../../hooks/useMusicBeatAnalysis";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
-import { useTimelineRowElements } from "../hooks/useTimelineRowElements";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
 import { usePublishRangeSelection } from "./usePublishRangeSelection";
@@ -113,7 +112,7 @@ export const Timeline = memo(function Timeline({
   const refreshAfterLaneMove = useTimelineLaneMoveRefresh();
   useMusicBeatAnalysis();
   const rawElements = usePlayerStore((s) => s.elements);
-  const expandedElements = useTimelineRowElements();
+  const timelineElements = rawElements;
   const adjustedBeatAnalysis = useAdjustedBeatAnalysis();
   const duration = usePlayerStore((s) => s.duration);
   const timeDisplayMode = usePlayerStore((s) => s.timeDisplayMode);
@@ -123,8 +122,8 @@ export const Timeline = memo(function Timeline({
   const focusedEaseSegment = usePlayerStore((s) => s.focusedEaseSegment);
   const gsapAnimations = usePlayerStore((s) => s.gsapAnimations);
   const labelMode = useMemo(
-    () => timelineNeedsLabelColumn(gsapAnimations, expandedElements),
-    [gsapAnimations, expandedElements],
+    () => timelineNeedsLabelColumn(gsapAnimations, timelineElements),
+    [gsapAnimations, timelineElements],
   );
   // The label column provides pre-t=0 space; otherwise keep TRACKS_LEFT_PAD after the gutter.
   const contentOrigin = labelMode ? LABEL_COL_W + GUTTER : GUTTER + TRACKS_LEFT_PAD;
@@ -163,13 +162,13 @@ export const Timeline = memo(function Timeline({
     groups,
     trackGroupOf,
   } = useTimelineTrackLayout(
-    expandedElements,
+    timelineElements,
     gsapAnimations,
     selectedElementId,
     selectedElementIds,
   );
-  const expandedElementsRef = useRef(expandedElements);
-  expandedElementsRef.current = expandedElements; // oxlint-disable-line react/refs -- event handlers read the latest elements
+  const timelineElementsRef = useRef(timelineElements);
+  timelineElementsRef.current = timelineElements; // oxlint-disable-line react/refs -- event handlers read the latest elements
   const ppsRef = useRef(100);
   const durationRef = useRef(effectiveDuration);
   durationRef.current = effectiveDuration; // oxlint-disable-line react/refs -- event handlers read the latest duration
@@ -198,7 +197,7 @@ export const Timeline = memo(function Timeline({
     onCompositionDrop,
   });
   const { readClipZIndex, applyStackingPatches, zSyncEnabled } = useTimelineStackingSync({
-    expandedElementsRef,
+    expandedElementsRef: timelineElementsRef,
   });
   const {
     gapMenuModel,
@@ -210,7 +209,7 @@ export const Timeline = memo(function Timeline({
     closeAllTrackGaps,
   } = useTrackGapMenu({
     tracks,
-    expandedElementsRef,
+    expandedElementsRef: timelineElementsRef,
     trackOrderRef,
     onMoveElement: pinnedOnMoveElement,
     onMoveElements: pinnedOnMoveElements,
@@ -259,14 +258,14 @@ export const Timeline = memo(function Timeline({
     resizingClip?.groupPreview?.map((change) => change.key) ??
     (resizingClip ? [getTimelineElementIdentity(resizingClip.element)] : undefined);
   const { recordTimelineScroll } = useTimelinePerformanceTelemetry({
-    totalClipCount: expandedElements.length,
+    totalClipCount: timelineElements.length,
     totalRowCount: displayLayout.displayTrackOrder.length,
     zoomMode,
   });
   const { viewport, showShortcutHint, setScrollRef, syncScrollViewport } =
     useTimelineScrollViewport(scrollRef, [
       timelineReady,
-      expandedElements.length,
+      timelineElements.length,
       displayLayout.totalH,
     ]);
   const { pps, fitPps, displayContentWidth, displayDuration, zoomModeRef, manualZoomPercentRef } =
@@ -279,7 +278,7 @@ export const Timeline = memo(function Timeline({
       fitPpsRef,
       draggedClip,
       resizingClip,
-      expandedElements,
+      expandedElements: timelineElements,
       isDragging,
       scrollRef,
       lastScrollLeftRef,
@@ -295,7 +294,7 @@ export const Timeline = memo(function Timeline({
     groups,
     trackGroupOf,
     gsapAnimations,
-    elements: expandedElements,
+    elements: timelineElements,
     pixelsPerSecond: pps,
     contentOrigin,
     allowHorizontal: zoomMode === "manual",
@@ -312,7 +311,7 @@ export const Timeline = memo(function Timeline({
   const toggleSelectedKeyframe = usePlayerStore((s) => s.toggleSelectedKeyframe);
   const { onClickKeyframe, onSelectSegment, onShiftClickKeyframe, onContextMenuKeyframe } =
     useTimelineKeyframeHandlers({
-      expandedElements,
+      expandedElements: timelineElements,
       keyframeCache,
       onSelectElement,
       onSeek,
@@ -343,14 +342,14 @@ export const Timeline = memo(function Timeline({
     scrollRef,
     currentTime,
     clipStateVersion: renderTimeRange,
-    elementStateVersion: expandedElements,
+    elementStateVersion: timelineElements,
   });
   const laneGapStrips = useTimelineGapHighlights({
     gapHighlight,
     tracks,
     selectedElementId,
     selectedElementIds,
-    expandedElements,
+    expandedElements: timelineElements,
     dragActive: draggedClip?.started === true || resizingClip != null,
     displayDuration,
   });
@@ -371,7 +370,7 @@ export const Timeline = memo(function Timeline({
     effectiveDuration,
     pps,
     timelineReady,
-    elementsLength: expandedElements.length,
+    elementsLength: timelineElements.length,
     setZoomMode,
     setManualZoomPercent,
     onSeek,
@@ -407,7 +406,7 @@ export const Timeline = memo(function Timeline({
     dragScrollRaf,
     isDragging,
     setShowPopover,
-    elementsRef: expandedElementsRef,
+    elementsRef: timelineElementsRef,
     clipIndex,
     rowGeometryRef,
     onSelectElement,
@@ -417,7 +416,7 @@ export const Timeline = memo(function Timeline({
   usePublishRangeSelection(rangeSelection, onRangeSelect);
   setRangeSelectionRef.current = setRangeSelection; // oxlint-disable-line react/refs -- stable ref consumed by useTimelineClipDrag
 
-  useTimelineSelectionLifecycle(expandedElements, selectedElementId, setShowPopover, () =>
+  useTimelineSelectionLifecycle(timelineElements, selectedElementId, setShowPopover, () =>
     setRangeSelection(null),
   );
 
@@ -433,7 +432,7 @@ export const Timeline = memo(function Timeline({
     [resizingClip],
   );
 
-  if (!timelineReady || expandedElements.length === 0) {
+  if (!timelineReady || timelineElements.length === 0) {
     return (
       <TimelineEmptyState
         isDragOver={assetDrop.isDragOver}
@@ -449,7 +448,7 @@ export const Timeline = memo(function Timeline({
     <div
       ref={setContainerRef}
       aria-label="Timeline track view"
-      data-timeline-element-count={expandedElements.length}
+      data-timeline-element-count={timelineElements.length}
       className={`relative border-t select-none h-full overflow-hidden ${assetDrop.isDragOver ? "ring-1 ring-inset ring-studio-accent/60" : ""} ${activeTool === "razor" ? "cursor-crosshair" : shiftHeld ? "cursor-crosshair" : "cursor-default"}`}
       onMouseMove={updateRazorGuide}
       onMouseLeave={clearRazorGuide}
@@ -566,8 +565,8 @@ export const Timeline = memo(function Timeline({
         {activeTool === "razor" && razorGuideX !== null && <TimelineRazorGuide x={razorGuideX} />}
       </div>
       <TimelineOverlays
-        elements={expandedElements}
-        elementsRef={expandedElementsRef}
+        elements={timelineElements}
+        elementsRef={timelineElementsRef}
         theme={theme}
         showShortcutHint={showShortcutHint}
         showPopover={showPopover}

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

@@ -6,6 +6,7 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 import type { TimelineElement } from "../store/playerStore";
 import { TimelineClip } from "./TimelineClip";
 import type { TimelineEditCapabilities } from "./timelineEditing";
+import { defaultTimelineTheme, type TimelineTheme } from "./timelineTheme";
 
 Object.defineProperty(globalThis, "IS_REACT_ACT_ENVIRONMENT", {
   configurable: true,
@@ -27,11 +28,13 @@ function renderClip({
   pps = 100,
   isSelected = false,
   hasCustomContent = true,
+  theme = defaultTimelineTheme,
 }: {
   element: TimelineElement;
   pps?: number;
   isSelected?: boolean;
   hasCustomContent?: boolean;
+  theme?: TimelineTheme;
 }) {
   const host = document.createElement("div");
   document.body.append(host);
@@ -48,6 +51,7 @@ function renderClip({
         isHovered={false}
         hasCustomContent={hasCustomContent}
         capabilities={capabilities}
+        theme={theme}
         isComposition={false}
         onHoverStart={vi.fn()}
         onHoverEnd={vi.fn()}
@@ -115,6 +119,54 @@ describe("TimelineClip", () => {
     act(() => root.unmount());
   });
 
+  it("passes clip and handle theme tokens to the rendered elements", () => {
+    const theme: TimelineTheme = {
+      ...defaultTimelineTheme,
+      clipBackground: "var(--test-clip-bg)",
+      clipBackgroundActive: "var(--test-clip-bg-active)",
+      clipBackgroundHover: "var(--test-clip-bg-hover)",
+      clipBackgroundDragging: "var(--test-clip-bg-dragging)",
+      clipBorder: "var(--test-clip-border)",
+      clipBorderHover: "var(--test-clip-border-hover)",
+      clipBorderActive: "var(--test-clip-border-active)",
+      handleColor: "var(--test-handle)",
+    };
+    const { host, root } = renderClip({
+      element: { id: "themed", label: "Themed", tag: "div", start: 0, duration: 1, track: 0 },
+      isSelected: true,
+      theme,
+    });
+    const clip = host.querySelector<HTMLElement>(".timeline-clip")!;
+    expect(clip.style.getPropertyValue("--clip-bg")).toBe("var(--test-clip-bg)");
+    expect(clip.style.getPropertyValue("--clip-border-active")).toBe(
+      "var(--test-clip-border-active)",
+    );
+    expect(clip.style.getPropertyValue("--clip-handle")).toBe("var(--test-handle)");
+    expect(clip.querySelector<HTMLElement>(".timeline-clip__handle-bar")?.style.background).toBe(
+      "var(--clip-handle)",
+    );
+    act(() => root.unmount());
+  });
+
+  it("keeps default token references off the properties they resolve", () => {
+    const { host, root } = renderClip({
+      element: {
+        id: "default-theme",
+        label: "Default",
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: 0,
+      },
+      isSelected: true,
+    });
+    const clip = host.querySelector<HTMLElement>(".timeline-clip")!;
+    expect(clip.style.getPropertyValue("--clip-bg")).toBe("var(--timeline-clip-bg)");
+    expect(clip.style.getPropertyValue("--clip-bg")).not.toBe("var(--clip-bg)");
+    expect(clip.style.getPropertyValue("--clip-handle")).toBe("var(--timeline-handle)");
+    act(() => root.unmount());
+  });
+
   it("is a roving native button with explicit selection semantics", () => {
     const { host, onClick, root } = renderClip({
       element: { id: "hero", label: "Hero", tag: "div", start: 1, duration: 2, track: 0 },

package/src/player/components/TimelineClip.tsx

@@ -64,6 +64,16 @@ export const TimelineClip = memo(function TimelineClip({
   const showDefaultText = !hasCustomContent && (widthPx >= 40 || isSelected);
   const startLabel = el.start.toFixed(1);
   const endLabel = (el.start + el.duration).toFixed(1);
+  const themeVariables = {
+    "--clip-bg": theme.clipBackground,
+    "--clip-bg-active": theme.clipBackgroundActive,
+    "--clip-bg-hover": theme.clipBackgroundHover,
+    "--clip-bg-dragging": theme.clipBackgroundDragging,
+    "--clip-border": theme.clipBorder,
+    "--clip-border-hover": theme.clipBorderHover,
+    "--clip-border-active": theme.clipBorderActive,
+    "--clip-handle": theme.handleColor,
+  } as CSSProperties;
   const clipClassName = [
     "timeline-clip",
     "absolute",
@@ -81,6 +91,7 @@ export const TimelineClip = memo(function TimelineClip({
     top: clipY,
     ...(clipHeight === undefined ? { bottom: clipY } : { height: clipHeight }),
     borderRadius: theme.clipRadius,
+    ...themeVariables,
     zIndex: isDragging ? 20 : isSelected ? 10 : isHovered ? 5 : 1,
     // Regular cursor over clips (CapCut-style, user preference) — no grab hand.
     cursor: "default",
@@ -144,7 +155,7 @@ export const TimelineClip = memo(function TimelineClip({
               bottom: 6,
               width: 2,
               borderRadius: 1,
-              background: "rgba(255, 255, 255, 0.55)",
+              background: "var(--clip-handle)",
               opacity: handleOpacity * 0.6,
             }}
           />
@@ -174,7 +185,7 @@ export const TimelineClip = memo(function TimelineClip({
               bottom: 6,
               width: 2,
               borderRadius: 1,
-              background: "rgba(255, 255, 255, 0.55)",
+              background: "var(--clip-handle)",
               opacity: handleOpacity * 0.6,
             }}
           />

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

@@ -5,7 +5,7 @@ import { createRoot, type Root } from "react-dom/client";
 import type { GsapAnimation, PropertyGroupName } from "@hyperframes/core/gsap-parser";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { TimelinePropertyLanes } from "./TimelinePropertyLanes";
-import { TimelineTrackHeader } from "./TimelineTrackHeader";
+import { TimelineTrackHeader, gutterFill } from "./TimelineTrackHeader";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { type TimelineElement } from "../store/playerStore";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -794,10 +794,6 @@ describe("TimelineTrackHeader", () => {
       });
       expect(header()?.style.paddingLeft).toBe("14px");
       expect(header()?.style.borderLeft).toContain("2px");
-      // And a lighter gutter, so the row reads as sitting INSIDE its group
-      // rather than beside it. Overlaid on the theme's own fill rather than a
-      // hard-coded colour, so it follows whatever the gutter is.
-      expect(header()?.style.background).toContain("linear-gradient");
       act(() => view.root.unmount());
     });
 
@@ -912,3 +908,28 @@ describe("TimelineTrackHeader", () => {
     });
   });
 });
+
+// A host themes the timeline by overriding --timeline-* on theme.css, so the
+// rendered gutter must carry the CSS variable, not a baked-in colour.
+describe("theming", () => {
+  it("reads the gutter background and border from timeline theme tokens", () => {
+    const view = renderHeader({});
+    const header = view.host.querySelector<HTMLElement>('[role="rowheader"]');
+    expect(header?.style.background).toBe(defaultTimelineTheme.gutterBackground);
+    expect(header?.style.background).toContain("var(--timeline-gutter-bg)");
+    expect(header?.style.borderRight).toContain(defaultTimelineTheme.gutterBorder);
+    act(() => view.root.unmount());
+  });
+
+  // happy-dom's `background` shorthand garbles a `var()` layer next to
+  // `linear-gradient(...)` (verified), so this checks the same value through
+  // the pure function instead of the broken CSSOM roundtrip.
+  it("overlays the group-member tint on the themed gutter, not a hard-coded colour", () => {
+    const filled = gutterFill(defaultTimelineTheme.gutterBackground, true);
+    expect(filled).toContain("linear-gradient");
+    expect(filled.endsWith(defaultTimelineTheme.gutterBackground)).toBe(true);
+    expect(gutterFill(defaultTimelineTheme.gutterBackground, false)).toBe(
+      defaultTimelineTheme.gutterBackground,
+    );
+  });
+});

package/src/player/components/TimelineTrackHeader.tsx

@@ -34,7 +34,7 @@ const GROUP_MEMBER_INDENT = 14;
 const GROUP_MEMBER_TINT = "rgba(255,255,255,0.035)";
 
 /** The gutter fill for a row, tinted when it belongs to a group. */
-function gutterFill(base: string, isGroupMember: boolean): string {
+export function gutterFill(base: string, isGroupMember: boolean): string {
   return isGroupMember
     ? `linear-gradient(${GROUP_MEMBER_TINT}, ${GROUP_MEMBER_TINT}), ${base}`
     : base;

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

@@ -75,11 +75,11 @@ describe("timeline motion styles", () => {
     const bloomOverlayRule = expectRule(studioCss, ".timeline-clip::before");
     const activeBloomOverlayRule = expectRule(studioCss, ".timeline-clip[data-active]::before");
 
-    expect(baseTimelineClipRule).toContain("background-color: rgba(255, 255, 255, 0.055)");
+    expect(baseTimelineClipRule).toContain("background-color: var(--clip-bg)");
     expect(activeTimelineClipRule).not.toContain("background: linear-gradient");
-    expect(activeTimelineClipRule).toContain("border-color: rgba(60, 230, 172, 0.55)");
+    expect(activeTimelineClipRule).toContain("border-color: var(--clip-border-active)");
     expect(activeTimelineClipRule).not.toContain("box-shadow");
-    expect(bloomOverlayRule).toContain("background: rgba(60, 230, 172, 0.2)");
+    expect(bloomOverlayRule).toContain("background: var(--clip-bg-active)");
     expect(bloomOverlayRule).not.toContain("linear-gradient");
     expect(bloomOverlayRule).toContain("opacity: 0");
     expect(activeBloomOverlayRule).toContain("opacity: 1");

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

@@ -9,10 +9,10 @@ import { getTrackStyle } from "./timelineIcons";
 describe("getTimelineTrackStyle", () => {
   it("uses one neutral clip style for every timeline tag", () => {
     const expectedStyle = {
-      clip: "rgba(255,255,255,0.055)",
-      clipActive: "rgba(60,230,172,0.16)",
-      accent: "#3CE6AC",
-      label: "rgba(255,255,255,0.5)",
+      clip: "var(--timeline-track-clip-fill)",
+      clipActive: "var(--timeline-track-clip-active)",
+      accent: "var(--color-accent)",
+      label: "var(--timeline-track-label)",
     };
 
     expect(getTimelineTrackStyle("video")).toEqual(expectedStyle);

package/src/player/components/timelineTheme.ts

@@ -22,6 +22,8 @@ export interface TimelineTheme {
   tickMinor: string;
   clipBackground: string;
   clipBackgroundActive: string;
+  clipBackgroundHover: string;
+  clipBackgroundDragging: string;
   clipBorder: string;
   clipBorderHover: string;
   clipBorderActive: string;
@@ -36,43 +38,45 @@ export interface TimelineTheme {
 }
 
 const TRACK_STYLE: TimelineTrackStyle = {
-  clip: "rgba(255,255,255,0.055)",
-  clipActive: "rgba(60,230,172,0.16)",
-  accent: "#3CE6AC",
-  label: "rgba(255,255,255,0.5)",
+  clip: "var(--timeline-track-clip-fill)",
+  clipActive: "var(--timeline-track-clip-active)",
+  accent: "var(--color-accent)",
+  label: "var(--timeline-track-label)",
 };
 
+// Every field reads a CSS custom property (declared in styles/theme.css)
+// rather than a literal, so a host themes the timeline the same way it
+// themes the rest of Studio: by overriding the token, not this object.
 export const defaultTimelineTheme: TimelineTheme = {
-  // Near-black card surfaces: the panels sit dark while the shell canvas
-  // between them is a step LIGHTER (#18181B), so the gaps read as visible
-  // seams around dark cards (CapCut-style).
-  shellBackground: "#0A0A0B",
-  shellBorder: "rgba(255,255,255,0.05)",
-  rulerBorder: "rgba(255,255,255,0.16)",
-  // All track lanes use a single uniform color — one step lighter than the panel
-  // surface (#0A0A0B) so lanes are visibly distinct from the ruler/shell.
-  rowBackground: "#101014",
-  rowBorder: "rgba(255,255,255,0.06)",
-  gutterBackground: "#0E0F12",
-  gutterBorder: "rgba(255,255,255,0.10)",
-  textPrimary: "rgba(255,255,255,0.92)",
-  textSecondary: "rgba(255,255,255,0.62)",
-  tickText: "rgba(255,255,255,0.34)",
-  tickMajor: "rgba(255,255,255,0.10)",
-  tickMinor: "rgba(255,255,255,0.06)",
-  clipBackground: "#141922",
-  clipBackgroundActive: "#181e28",
-  clipBorder: "rgba(255,255,255,0.10)",
-  clipBorderHover: "rgba(255,255,255,0.18)",
-  clipBorderActive: "rgba(255,255,255,0.24)",
+  shellBackground: "var(--timeline-shell-bg)",
+  shellBorder: "var(--timeline-shell-border)",
+  rulerBorder: "var(--timeline-ruler-border)",
+  rowBackground: "var(--timeline-row-bg)",
+  rowBorder: "var(--timeline-row-border)",
+  gutterBackground: "var(--timeline-gutter-bg)",
+  gutterBorder: "var(--timeline-gutter-border)",
+  textPrimary: "var(--timeline-text-primary)",
+  textSecondary: "var(--timeline-text-secondary)",
+  tickText: "var(--timeline-tick-text)",
+  tickMajor: "var(--timeline-tick-major)",
+  tickMinor: "var(--timeline-tick-minor)",
+  clipBackground: "var(--timeline-clip-bg)",
+  clipBackgroundActive: "var(--timeline-clip-bg-active)",
+  clipBackgroundHover: "var(--timeline-clip-bg-hover)",
+  clipBackgroundDragging: "var(--timeline-clip-bg-dragging)",
+  clipBorder: "var(--timeline-clip-border)",
+  clipBorderHover: "var(--timeline-clip-border-hover)",
+  clipBorderActive: "var(--timeline-clip-border-active)",
+  // Shadows stay literal: a light host still wants a dark contact shadow, so
+  // these are not part of the surface/hairline/text/clip-colour theming ask.
   clipShadow: "none",
   clipShadowHover: "0 2px 8px rgba(0,0,0,0.2)",
   clipShadowActive: "0 2px 8px rgba(0,0,0,0.2), 0 0 0 1px rgba(255,255,255,0.04)",
   clipShadowDragging: "0 8px 24px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.06)",
-  handleColor: "rgba(255,255,255,0.2)",
-  panelResizeSeam: "rgba(255,255,255,0.12)",
-  panelResizeActive: "rgba(255,255,255,0.24)",
-  clipRadius: "8px",
+  handleColor: "var(--timeline-handle)",
+  panelResizeSeam: "var(--timeline-resize-seam)",
+  panelResizeActive: "var(--timeline-resize-active)",
+  clipRadius: "var(--radius-lg)",
 };
 
 export function getTimelineTrackStyle(_tag: string): TimelineTrackStyle {

package/src/player/components/timelineTrackDisplay.ts

@@ -1,10 +1,7 @@
 /**
  * The one owner of "what track number does the user see".
  *
- * `TimelineElement.track` is a z-order SORT key, not a row number: an expanded
- * sub-composition child gets a synthesized fractional key (`host.track + n /
- * (siblings + 2)`, see `useTimelineRowElements`), so putting it in a string
- * announces "Hide track 0.16666666666666666". Every user-visible track number,
+ * `TimelineElement.track` is a z-order SORT key, not a row number. Every
  * whether it is rendered by a component or baked into an undo-history label,
  * routes through here; the raw key stays in callbacks and lookups only.
  */

package/src/player/components/useTimelineTrackDerivations.ts

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

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

@@ -3,7 +3,6 @@
 import { describe, expect, it } from "vitest";
 import {
   collectSubCompositionDomChildren,
-  collectTopLevelElementIds,
   collectSubCompositionHostState,
 } from "./timelineSyncHydration";
 import type { ClipManifestClip } from "../lib/playbackTypes";
@@ -95,20 +94,3 @@ 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,7 +14,6 @@ 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";
@@ -137,28 +136,6 @@ 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 = {};

package/src/player/hooks/useTimelineSyncCallbacks.ts

@@ -19,7 +19,6 @@ import {
   buildTimelineElementsFromClips,
   syncManifestTimeline,
   clipTreeParentMap,
-  collectTopLevelElementIds,
   collectSubCompositionDomChildren,
   collectSubCompositionHostState,
   hydrateTimelineFromPreview,
@@ -130,13 +129,11 @@ export function useTimelineSyncCallbacks({
         const parentMap = clipTreeParentMap(iframeRef.current?.contentWindow ?? null);
         const domClipChildren = collectSubCompositionDomChildren(iframeDoc, data.clips, parentMap);
         usePlayerStore.getState().setClipParentMap(parentMap);
-        usePlayerStore.getState().setTopLevelIds(collectTopLevelElementIds(iframeDoc));
         usePlayerStore.getState().setDomClipChildren(domClipChildren);
         usePlayerStore
           .getState()
           .setSubCompositionHostState(collectSubCompositionHostState(iframeDoc, data.clips));
       } catch {
-        usePlayerStore.getState().setTopLevelIds(null);
         // cross-origin or __clipTree not available — maps stay empty
       }
 

package/src/player/store/playerStore.ts

@@ -202,8 +202,6 @@ interface PlayerState extends PlayerStoreSlices {
   clipManifest: ClipManifestClip[] | null;
   setClipManifest: (clips: ClipManifestClip[] | null) => void;
   clipParentMap: Map<string, string>;
-  topLevelIds: ReadonlySet<string> | null;
-  setTopLevelIds: (ids: ReadonlySet<string> | null) => void;
   setClipParentMap: (map: Map<string, string>) => void;
   /**
    * Sub-composition DOM descendants (groups + their children) that have no
@@ -394,8 +392,6 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
   setClipManifest: (clips) => set({ clipManifest: clips }),
   clipParentMap: new Map(),
   setClipParentMap: (map) => set({ clipParentMap: map }),
-  topLevelIds: null,
-  setTopLevelIds: (ids) => set({ topLevelIds: ids }),
   domClipChildren: [],
   setDomClipChildren: (children) => set({ domClipChildren: children }),
   subCompositionHostState: new Map(),

package/src/player/store/timelineElement.ts

@@ -77,10 +77,8 @@ export interface TimelineElement {
   audioGroupFxChain?: string;
   audioGroupAutomation?: string;
   /**
-   * Set by useTimelineRowElements on an inline-expanded sub-composition
-   * child: the absolute master-timeline start of the sub-comp host the child
-   * lives in. Presence marks the element as expanded; edits subtract it to get
-   * the child's local (sourceFile-relative) time. Works at any nesting depth.
+   * Legacy source-coordinate marker for an inline sub-composition child. The
+   * current timeline keeps sub-compositions as single rows.
    */
   expandedParentStart?: number;
   expandedHostKey?: string;

package/src/player/store/timelineResetState.ts

@@ -44,7 +44,6 @@ export function createTimelineResetState() {
     beatPersist: null,
     clipManifest: null,
     clipParentMap: new Map<string, string>(),
-    topLevelIds: null,
     domClipChildren: [],
     subCompositionHostState: new Map<string, SubCompositionHostState>(),
   };