@hyperframes/studio 0.8.55 → 0.8.56

package/src/hooks/useInlineTextEdit.test.tsx

@@ -3,6 +3,7 @@
 import React, { act } from "react";
 import { createRoot } from "react-dom/client";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { PreviewReadOnlyProvider } from "../components/editor/previewReadOnlyContext";
 import { useInlineTextEdit, type InlineTextEditControls } from "./useInlineTextEdit";
 
 (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -20,7 +21,7 @@ function heading(text = "Motion Playground"): HTMLElement {
   return element;
 }
 
-function mount(onCommit = vi.fn(), onPause = vi.fn()) {
+function mount(onCommit = vi.fn(), onPause = vi.fn(), readOnly = false) {
   const controls: { current: InlineTextEditControls | null } = { current: null };
   function Probe() {
     controls.current = useInlineTextEdit({ onCommit, onPause });
@@ -29,7 +30,13 @@ function mount(onCommit = vi.fn(), onPause = vi.fn()) {
   const host = document.createElement("div");
   document.body.append(host);
   const root = createRoot(host);
-  act(() => root.render(<Probe />));
+  act(() =>
+    root.render(
+      <PreviewReadOnlyProvider readOnly={readOnly}>
+        <Probe />
+      </PreviewReadOnlyProvider>,
+    ),
+  );
   return { controls: () => controls.current!, root, onCommit, onPause };
 }
 
@@ -552,4 +559,18 @@ describe("useInlineTextEdit with styled runs", () => {
     expect(insertText).toHaveBeenCalledWith("insertText", false, "plain words");
     act(() => root.unmount());
   });
+
+  it("refuses to open an edit while the preview is read-only", () => {
+    const element = heading();
+    const { controls, root, onCommit, onPause } = mount(vi.fn(), vi.fn(), true);
+    let opened = true;
+    act(() => {
+      opened = controls().start(element);
+    });
+    expect(opened).toBe(false);
+    expect(element.hasAttribute("contenteditable")).toBe(false);
+    expect(onPause).not.toHaveBeenCalled();
+    expect(onCommit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+  });
 });

package/src/hooks/useInlineTextEdit.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { sanitizeRichTextChildren } from "@hyperframes/core/rich-text-sanitize";
+import { usePreviewReadOnly } from "../components/editor/previewReadOnlyContext";
 
 /**
  * Editing an element's text where it sits, in the composition itself.
@@ -89,6 +90,7 @@ export function useInlineTextEdit({
   /** Stop playback, so the element is not animating under the caret. */
   onPause?: () => void;
 }): InlineTextEditControls {
+  const readOnly = usePreviewReadOnly();
   const [session, setSession] = useState<InlineTextEditSession | null>(null);
   // The teardown reads this rather than the state, so an exit path that runs
   // before React re-renders still sees the element it has to clean up.
@@ -123,7 +125,7 @@ export function useInlineTextEdit({
 
   const start = useCallback(
     (element: HTMLElement, caretAt?: { x: number; y: number }): boolean => {
-      if (openRef.current) return false;
+      if (openRef.current || readOnly) return false;
 
       const open = {
         element,
@@ -156,7 +158,7 @@ export function useInlineTextEdit({
       framesRef.current = raf ?? null;
       return true;
     },
-    [onPause],
+    [onPause, readOnly],
   );
 
   const commit = useCallback(() => {
@@ -179,6 +181,13 @@ export function useInlineTextEdit({
     teardown();
   }, [teardown]);
 
+  // Read-only can be enabled while an edit is already open. Close that
+  // session as a cancellation so the preview cannot keep committing through
+  // the now-disabled editing surface.
+  useEffect(() => {
+    if (readOnly && openRef.current) cancel();
+  }, [cancel, readOnly]);
+
   // The keys belong to the element, not to the document: the element lives in
   // the preview's own document, so a listener on Studio's would never see them.
   useEffect(() => {

package/src/hooks/useTimelineAssetDropOps.test.tsx

@@ -103,7 +103,7 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     expect(usePlayerStore.getState().selectedElementId).toBe("index.html#clip");
   });
 
-  it("measures the insert row against the visible rows, not clips the timeline hides", async () => {
+  it("measures the insert row against every manifest timeline row", async () => {
     const clip = (id: string, track: number): TimelineElement => ({
       id,
       key: id,
@@ -123,7 +123,6 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
       }),
       "</main>",
     ].join("\n");
-    usePlayerStore.getState().setTopLevelIds(new Set(["a", "b"]));
     const writeProjectFile = vi.fn().mockResolvedValue(undefined);
     const getDrop = renderDropHook(source, writeProjectFile, [
       clip("a", 0),
@@ -136,8 +135,8 @@ describe("useTimelineAssetDropOps handleTimelineAssetDrop", () => {
     });
 
     const [, written] = writeProjectFile.mock.calls[0] as [string, string];
-    expect(written).toContain('id="b" data-start="0" data-track-index="2"');
-    expect(written).toContain('id="hidden" data-start="0" data-track-index="1"');
+    expect(written).toContain('id="b" data-start="0" data-track-index="3"');
+    expect(written).toContain('id="hidden" data-start="0" data-track-index="2"');
     expect(written).toMatch(/<video id="clip"[^>]*data-track-index="1"/);
   });
 

package/src/hooks/useTimelineAssetDropOps.ts

@@ -25,8 +25,6 @@ import { commitTimelineCompositionInsertion } from "../utils/timelineComposition
 import { extendRootDurationInSource } from "../utils/rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 import { selectAndRevealTimelineElement } from "../player/components/timelineDropReveal";
-import { selectTimelineRowElements } from "../player/hooks/useTimelineRowElements";
-import { usePlayerStore } from "../player/store/playerStore";
 
 /** The first uploaded file opens the new track (if asked); the rest land on the lane it landed on. */
 function fileDropPlacement(
@@ -127,10 +125,7 @@ export function useTimelineAssetDropOps({
         const { source: sourceWithRoom, track } = resolveDropTrack({
           source: originalContent,
           // insertRow counts the rows the timeline shows, so plan against those.
-          elements: selectTimelineRowElements(
-            relevantElements,
-            usePlayerStore.getState().topLevelIds,
-          ),
+          elements: relevantElements,
           placement,
           dropped: {
             id: newId,

package/src/hooks/useTimelineEditing.test.tsx

@@ -1561,21 +1561,24 @@ describe("useTimelineEditing: canEdit gate", () => {
     unmount();
   });
 
-  it("resolves toggle-track-hidden against the expanded rows, not the raw timelineElements prop", async () => {
-    // Regression: canEdit must resolve against the expanded rows
-    // (timelineTrackVisibility.ts's own invariant), not the raw
-    // timelineElements prop — proven by making the two disagree below.
+  it("resolves toggle-track-hidden against the store-owned timeline rows", async () => {
+    // The visibility hook reads the single store-owned row source. The editing
+    // guard must receive that same source so a blocked row cannot fall through
+    // to the write path.
     const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
     const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
     usePlayerStore.getState().setElements([clip]);
     const showToast = vi.fn();
     const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const canEdit = vi.fn((element: TimelineElement) =>
+      element.id === "clip" ? { blocked: true as const, reason: "Reserved by an agent" } : true,
+    );
     let hook: ReturnType<typeof useTimelineEditing> | null = null;
     function Harness() {
       hook = useTimelineEditing({
         projectId: "p1",
         activeCompPath: "index.html",
-        timelineElements: [], // deliberately does not contain `clip`
+        timelineElements: [clip],
         showToast,
         writeProjectFile,
         recordEdit: vi.fn(),
@@ -1583,8 +1586,7 @@ describe("useTimelineEditing: canEdit gate", () => {
         previewIframeRef: { current: iframe },
         pendingTimelineEditPathRef: { current: new Set<string>() },
         uploadProjectFiles: vi.fn(),
-        canEdit: (element) =>
-          element.id === "clip" ? { blocked: true, reason: "Reserved by an agent" } : true,
+        canEdit,
       });
       return null;
     }
@@ -1596,6 +1598,7 @@ describe("useTimelineEditing: canEdit gate", () => {
       await flushAsyncWork();
     });
 
+    expect(canEdit).toHaveBeenCalledWith(clip);
     expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
     expect(writeProjectFile).not.toHaveBeenCalled();
     unmount();

package/src/hooks/useTimelineEditing.ts

@@ -25,7 +25,6 @@ import type { PersistTimelineEditInput } from "./timelineEditingHelpers";
 import { useSetAudioGroupAttribute } from "./timelineAudioGroupVolume";
 import { useSetElementAttribute } from "./timelineElementFxAttribute";
 import { useTimelineDeleteOps } from "./useTimelineDeleteOps";
-import { useTimelineRowElements } from "../player/hooks/useTimelineRowElements";
 import { useTrackPendingTimelineEdit } from "./useTrackPendingTimelineEdit";
 import { useAudioGroupCarveAssignment } from "./timelineAudioGroupCreate";
 import {
@@ -77,10 +76,6 @@ export function useTimelineEditing({
   const checkEditable = useTimelineEditGate(canEdit, showToast);
   const checkEditableRef = useRef(checkEditable);
   checkEditableRef.current = checkEditable;
-  // Same expanded-row source the hide handlers themselves resolve against
-  // (timelineTrackVisibility.ts) — a virtual sub-comp child's track/key
-  // only exists here, not in the raw store list canEdit would otherwise miss.
-  const timelineRowElements = useTimelineRowElements();
   const guardedRef = useRef(new WeakMap<GuardedTimelineHandler, GuardedTimelineEntry>());
   // Refuses (no call, no write, no history entry) when any target is
   // blocked; otherwise runs fn as before. Cached by fn identity — like
@@ -514,14 +509,14 @@ export function useTimelineEditing({
     handleTimelineElementResize: track(guard((element) => [element], handleTimelineElementResize)),
     handleToggleTrackHidden: track(
       guard(
-        (trackIndex) => timelineRowElements.filter((el) => el.track === trackIndex),
+        (trackIndex) => timelineElements.filter((el) => el.track === trackIndex),
         handleToggleTrackHidden,
       ),
     ),
     handleToggleElementHidden: track(
       guard((elementKey) => {
         const keys = new Set(Array.isArray(elementKey) ? elementKey : [elementKey]);
-        return timelineRowElements.filter((el) => keys.has(el.key ?? el.id));
+        return timelineElements.filter((el) => keys.has(el.key ?? el.id));
       }, handleToggleElementHidden),
     ),
     handleAutoGroupCarveSources: track(handleAutoGroupCarveSources),

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);