@hyperframes/studio 0.8.53-desktop.0 → 0.8.54

package/src/hooks/useTimelineAssetDropOps.ts

@@ -38,6 +38,20 @@ function fileDropPlacement(
   return index === 0 ? { ...dropped, ...next } : { ...next, track: landedTrack ?? next.track };
 }
 
+function timelineDropTarget(
+  sourceFile: string,
+  placement: Pick<TimelineElement, "start" | "track">,
+): TimelineElement {
+  return {
+    id: "timeline-drop",
+    tag: "div",
+    start: placement.start,
+    duration: 0,
+    track: placement.track,
+    sourceFile,
+  };
+}
+
 interface UseTimelineAssetDropOpsOptions {
   projectIdRef: MutableRefObject<string | null>;
   activeCompPath: string | null;
@@ -50,6 +64,7 @@ interface UseTimelineAssetDropOpsOptions {
   isRecordingRef?: RefObject<boolean>;
   forceReloadSdkSession?: () => void;
   observeProjectFileVersion?: (path: string, version: string | null) => void;
+  checkEditable?: (targets: readonly TimelineElement[]) => boolean;
 }
 
 export function useTimelineAssetDropOps({
@@ -64,6 +79,7 @@ export function useTimelineAssetDropOps({
   isRecordingRef,
   forceReloadSdkSession,
   observeProjectFileVersion,
+  checkEditable,
 }: UseTimelineAssetDropOpsOptions) {
   // fallow-ignore-next-line complexity
   const dropAssetAt = useCallback(
@@ -77,6 +93,10 @@ export function useTimelineAssetDropOps({
         showToast("Cannot edit timeline while recording", "error");
         return undefined;
       }
+      const targetPath = activeCompPath || "index.html";
+      if (checkEditable && !checkEditable([timelineDropTarget(targetPath, placement)])) {
+        return undefined;
+      }
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
 
@@ -86,7 +106,6 @@ export function useTimelineAssetDropOps({
         return undefined;
       }
 
-      const targetPath = activeCompPath || "index.html";
       try {
         const originalContent = await readFileContent(pid, targetPath);
 
@@ -172,6 +191,7 @@ export function useTimelineAssetDropOps({
       reloadPreview,
       isRecordingRef,
       forceReloadSdkSession,
+      checkEditable,
     ],
   );
 
@@ -190,6 +210,11 @@ export function useTimelineAssetDropOps({
         showToast("Cannot edit timeline while recording", "error");
         return;
       }
+      const targetPath = activeCompPath || "index.html";
+      const initialPlacement = placement ?? { start: 0, track: 0 };
+      if (checkEditable && !checkEditable([timelineDropTarget(targetPath, initialPlacement)])) {
+        return;
+      }
       const pid = projectIdRef.current;
       if (!pid) return;
       const uploaded = await uploadProjectFiles(files);
@@ -215,7 +240,15 @@ export function useTimelineAssetDropOps({
         if (index === 0) landedTrack = track;
       }
     },
-    [dropAssetAt, projectIdRef, uploadProjectFiles, isRecordingRef, showToast],
+    [
+      activeCompPath,
+      checkEditable,
+      dropAssetAt,
+      projectIdRef,
+      uploadProjectFiles,
+      isRecordingRef,
+      showToast,
+    ],
   );
 
   const handleTimelineCompositionDrop = useCallback(
@@ -224,9 +257,12 @@ export function useTimelineAssetDropOps({
         showToast("Cannot edit timeline while recording", "error");
         return;
       }
+      const targetPath = activeCompPath || "index.html";
+      if (checkEditable && !checkEditable([timelineDropTarget(targetPath, placement)])) {
+        return;
+      }
       const pid = projectIdRef.current;
       if (!pid) throw new Error("No active project");
-      const targetPath = activeCompPath || "index.html";
       try {
         await commitTimelineCompositionInsertion({
           projectId: pid,
@@ -251,6 +287,7 @@ export function useTimelineAssetDropOps({
     },
     [
       activeCompPath,
+      checkEditable,
       forceReloadSdkSession,
       isRecordingRef,
       observeProjectFileVersion,

package/src/hooks/useTimelineEditing.test.tsx

@@ -1,7 +1,7 @@
 // fallow-ignore-file code-duplication
 // @vitest-environment happy-dom
 
-import React, { act, useRef } from "react";
+import React, { act, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { openComposition } from "@hyperframes/sdk";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -130,6 +130,8 @@ function renderTimelineEditingHook(input: {
   groupResize: ReturnType<typeof useTimelineEditing>["handleTimelineGroupResize"];
   del: ReturnType<typeof useTimelineEditing>["handleTimelineElementDelete"];
   elementsDelete: ReturnType<typeof useTimelineEditing>["handleTimelineElementsDelete"];
+  handleAutoGroupCarveSources: ReturnType<typeof useTimelineEditing>["handleAutoGroupCarveSources"];
+  setAudioGroupAttribute: ReturnType<typeof useTimelineEditing>["setAudioGroupAttribute"];
   unmount: () => void;
 } {
   let move: ReturnType<typeof useTimelineEditing>["handleTimelineElementMove"] | null = null;
@@ -139,6 +141,12 @@ function renderTimelineEditingHook(input: {
   let del: ReturnType<typeof useTimelineEditing>["handleTimelineElementDelete"] | null = null;
   let elementsDelete: ReturnType<typeof useTimelineEditing>["handleTimelineElementsDelete"] | null =
     null;
+  let handleAutoGroupCarveSources:
+    | ReturnType<typeof useTimelineEditing>["handleAutoGroupCarveSources"]
+    | null = null;
+  let setAudioGroupAttribute:
+    | ReturnType<typeof useTimelineEditing>["setAudioGroupAttribute"]
+    | null = null;
 
   function Harness() {
     const commitRef = useRef(input.onZIndexCommit);
@@ -167,6 +175,8 @@ function renderTimelineEditingHook(input: {
     groupResize = hook.handleTimelineGroupResize;
     del = hook.handleTimelineElementDelete;
     elementsDelete = hook.handleTimelineElementsDelete;
+    handleAutoGroupCarveSources = hook.handleAutoGroupCarveSources;
+    setAudioGroupAttribute = hook.setAudioGroupAttribute;
     return null;
   }
 
@@ -177,7 +187,19 @@ function renderTimelineEditingHook(input: {
   if (!groupResize) throw new Error("Expected hook to expose group resize handler");
   if (!del) throw new Error("Expected hook to expose delete handler");
   if (!elementsDelete) throw new Error("Expected hook to expose elements-delete handler");
-  return { move, resize, groupMove, groupResize, del, elementsDelete, unmount };
+  if (!handleAutoGroupCarveSources) throw new Error("Expected hook to expose group handler");
+  if (!setAudioGroupAttribute) throw new Error("Expected hook to expose audio group handler");
+  return {
+    move,
+    resize,
+    groupMove,
+    groupResize,
+    del,
+    elementsDelete,
+    handleAutoGroupCarveSources,
+    setAudioGroupAttribute,
+    unmount,
+  };
 }
 
 type TimelineRecordEdit = NonNullable<
@@ -1457,6 +1479,53 @@ describe("useTimelineEditing duration rollback on failed persist", () => {
 // Blocked means no fetch write, no recordEdit, and the host's reason
 // toasted. Absent canEdit behaves exactly as before (asserted above).
 describe("useTimelineEditing: canEdit gate", () => {
+  it("re-reads canEdit after the host changes its verdict", async () => {
+    const iframe = createPreviewIframe([{ id: "clip", track: 0 }]);
+    const clip = timelineElement({ id: "clip", track: 0, zIndex: 0 });
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const showToast = vi.fn();
+    const recordEdit = vi.fn(async () => {});
+    const pendingTimelineEditPathRef = { current: new Set<string>() };
+    const previewIframeRef = { current: iframe };
+    const uploadProjectFiles = vi.fn();
+    const reloadPreview = vi.fn();
+    let setBlocked = () => {};
+    let hook: ReturnType<typeof useTimelineEditing> | null = null;
+
+    function Harness() {
+      const [blocked, updateBlocked] = useState(false);
+      setBlocked = () => updateBlocked(true);
+      hook = useTimelineEditing({
+        projectId: "p1",
+        activeCompPath: "index.html",
+        timelineElements: [clip],
+        showToast,
+        writeProjectFile,
+        recordEdit,
+        reloadPreview,
+        previewIframeRef,
+        pendingTimelineEditPathRef,
+        uploadProjectFiles,
+        canEdit: () => (blocked ? { blocked: true, reason: "Reserved by an agent" } : true),
+      });
+      return null;
+    }
+
+    const { unmount } = mountHarness(<Harness />);
+    if (!hook) throw new Error("Expected hook to mount");
+    act(() => setBlocked());
+
+    await act(async () => {
+      await hook!.handleTimelineElementMove(clip, { start: 3, track: clip.track });
+      await flushAsyncWork();
+    });
+
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    unmount();
+  });
+
   it("refuses a move with the host's reason, writing nothing", async () => {
     const { clip, move, writeProjectFile, recordEdit, showToast, unmount } = setupSingleClipHarness(
       {
@@ -1700,6 +1769,95 @@ describe("useTimelineEditing: canEdit gate", () => {
     expect(fetchMock).not.toHaveBeenCalled();
     unmount();
   });
+
+  it("refuses auto-grouping before it patches existing clips", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument;
+    if (!doc) throw new Error("Expected iframe document");
+    doc.body.innerHTML =
+      '<audio id="voice-1" data-start="0" data-duration="5"></audio>' +
+      '<audio id="voice-2" data-start="5" data-duration="5"></audio>';
+    const voice1 = timelineElement({ id: "voice-1", tag: "audio", track: 0, zIndex: 0 });
+    const voice2 = timelineElement({ id: "voice-2", tag: "audio", track: 1, zIndex: 0 });
+    usePlayerStore.getState().setElements([voice1, voice2]);
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const recordEdit = vi.fn(async () => {});
+    const showToast = vi.fn();
+    const fetchMock = stubProjectFetch(
+      '<audio id="voice-1" data-start="0" data-duration="5"></audio>' +
+        '<audio id="voice-2" data-start="5" data-duration="5"></audio>',
+    );
+    const hook = renderTimelineEditingHook({
+      timelineElements: [voice1, voice2],
+      iframe,
+      onZIndexCommit: vi.fn().mockResolvedValue(undefined),
+      projectId: "p1",
+      writeProjectFile,
+      recordEdit,
+      showToast,
+      canEdit: (element) =>
+        element.id === "voice-2" ? { blocked: true, reason: "Reserved by an agent" } : true,
+    });
+
+    await expect(
+      hook.handleAutoGroupCarveSources(["voice-1", "voice-2"], "voiceover"),
+    ).rejects.toThrow("Timeline edit blocked");
+
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    expect(doc.getElementById("voice-1")?.getAttribute("data-audio-group")).toBeNull();
+    expect(doc.getElementById("voiceover")).toBeNull();
+    hook.unmount();
+  });
+
+  it("reverts an optimistic group live value when the commit is refused", async () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const doc = iframe.contentDocument;
+    if (!doc) throw new Error("Expected iframe document");
+    doc.body.innerHTML =
+      '<hf-audio-group id="voiceover" data-volume="1"></hf-audio-group>' +
+      '<audio id="voice-1" data-start="0" data-duration="5"></audio>';
+    const member = {
+      ...timelineElement({ id: "voice-1", tag: "audio", track: 0, zIndex: 0 }),
+      audioGroup: "voiceover",
+      audioGroupVolume: 1,
+    };
+    usePlayerStore.getState().setElements([member]);
+    const writeProjectFile = vi.fn<(...args: unknown[]) => Promise<void>>(async () => {});
+    const recordEdit = vi.fn(async () => {});
+    const showToast = vi.fn();
+    const hook = renderTimelineEditingHook({
+      timelineElements: [member],
+      iframe,
+      onZIndexCommit: vi.fn().mockResolvedValue(undefined),
+      projectId: "p1",
+      writeProjectFile,
+      recordEdit,
+      showToast,
+      canEdit: () => ({ blocked: true, reason: "Reserved by an agent" }),
+    });
+
+    await act(async () => {
+      hook.setAudioGroupAttribute.setLive("voiceover", "data-volume", "0.4");
+    });
+    expect(doc.getElementById("voiceover")?.getAttribute("data-volume")).toBe("0.4");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(0.4);
+
+    await act(async () => {
+      await hook.setAudioGroupAttribute.setQuiet("voiceover", "data-volume", "0.4", "Set volume");
+    });
+
+    expect(doc.getElementById("voiceover")?.getAttribute("data-volume")).toBe("1");
+    expect(usePlayerStore.getState().elements[0]?.audioGroupVolume).toBe(1);
+    expect(writeProjectFile).not.toHaveBeenCalled();
+    expect(recordEdit).not.toHaveBeenCalled();
+    expect(showToast).toHaveBeenCalledWith("Reserved by an agent", "error");
+    hook.unmount();
+  });
 });
 
 // Regression: track()/guard() must return the same wrapped handler across

package/src/hooks/useTimelineEditing.ts

@@ -40,6 +40,16 @@ import { cutoverCommittedOrThrow, sdkTimingPersist } from "../utils/sdkCutover";
 import type { TimelineMoveUpdates, UseTimelineEditingOptions } from "./useTimelineEditingTypes";
 import { getStudioSaveErrorMessage } from "../utils/studioSaveDiagnostics";
 
+type GuardedTimelineHandler = (...args: never[]) => Promise<void>;
+type GuardedTimelineResolver = (...args: never[]) => readonly TimelineElement[];
+type GuardedTimelineRefusal = (...args: never[]) => void;
+
+interface GuardedTimelineEntry {
+  resolveTargets: GuardedTimelineResolver;
+  onRefused?: GuardedTimelineRefusal;
+  wrapped: GuardedTimelineHandler;
+}
+
 export function useTimelineEditing({
   projectId,
   activeCompPath,
@@ -65,13 +75,13 @@ export function useTimelineEditing({
   const editQueueRef = useRef(Promise.resolve());
   const track = useTrackPendingTimelineEdit();
   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<(...args: never[]) => Promise<void>, (...args: never[]) => Promise<void>>(),
-  );
+  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
   // track() — so a fresh closure here doesn't defeat track's own cache.
@@ -79,16 +89,29 @@ export function useTimelineEditing({
     <H extends (...args: never[]) => Promise<void>>(
       resolveTargets: (...args: Parameters<H>) => readonly TimelineElement[],
       fn: H,
+      onRefused?: (...args: Parameters<H>) => void,
     ): H => {
-      const key = fn as unknown as (...args: never[]) => Promise<void>;
+      const key = fn as unknown as GuardedTimelineHandler;
       const cached = guardedRef.current.get(key);
-      if (cached) return cached as H;
-      const wrapped = ((...args: Parameters<H>) =>
-        checkEditable(resolveTargets(...args)) ? fn(...args) : Promise.resolve()) as H;
-      guardedRef.current.set(key, wrapped as unknown as (...args: never[]) => Promise<void>);
-      return wrapped;
+      if (cached) {
+        cached.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+        cached.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+        return cached.wrapped as H;
+      }
+      const entry = {} as GuardedTimelineEntry;
+      entry.resolveTargets = resolveTargets as unknown as GuardedTimelineResolver;
+      entry.onRefused = onRefused as unknown as GuardedTimelineRefusal | undefined;
+      entry.wrapped = ((...args: Parameters<H>) => {
+        if (!checkEditableRef.current(entry.resolveTargets(...(args as never[])))) {
+          entry.onRefused?.(...(args as never[]));
+          return Promise.resolve();
+        }
+        return fn(...args);
+      }) as H as unknown as GuardedTimelineHandler;
+      guardedRef.current.set(key, entry);
+      return entry.wrapped as H;
     },
-    [checkEditable],
+    [],
   );
 
   const enqueueEdit = useCallback(
@@ -411,9 +434,10 @@ export function useTimelineEditing({
     previewIframeRef,
     pendingTimelineEditPathRef,
     isRecordingRef,
+    checkEditable,
   });
 
-  const setElementFxAttribute = useSetElementAttribute({
+  const { revertLive: revertElementFxLive, ...setElementFxAttribute } = useSetElementAttribute({
     projectIdRef,
     activeCompPath,
     showToast,
@@ -424,16 +448,18 @@ export function useTimelineEditing({
     isRecordingRef,
   });
 
-  const setAudioGroupAttribute = useSetAudioGroupAttribute({
-    projectIdRef,
-    activeCompPath,
-    showToast,
-    writeProjectFile,
-    recordEdit,
-    previewIframeRef,
-    pendingTimelineEditPathRef,
-    isRecordingRef,
-  });
+  const { revertLive: revertAudioGroupLive, ...setAudioGroupAttribute } = useSetAudioGroupAttribute(
+    {
+      projectIdRef,
+      activeCompPath,
+      showToast,
+      writeProjectFile,
+      recordEdit,
+      previewIframeRef,
+      pendingTimelineEditPathRef,
+      isRecordingRef,
+    },
+  );
 
   const { handleTimelineElementsDelete, handleTimelineElementDelete } = useTimelineDeleteOps({
     projectIdRef,
@@ -462,6 +488,7 @@ export function useTimelineEditing({
       isRecordingRef,
       forceReloadSdkSession,
       observeProjectFileVersion,
+      checkEditable,
     });
 
   const handleBlockedTimelineEdit = useBlockedTimelineEditToast(showToast);
@@ -504,28 +531,38 @@ export function useTimelineEditing({
       // (timelineAudioGroupVolume.ts): a sub-composition's group members have
       // no flat twin, only a domClipChildren entry, so both are checked.
       setQuiet: track(
-        guard((groupId) => {
-          const state = usePlayerStore.getState();
-          const flatMembers = state.elements.filter((el) => el.audioGroup === groupId);
-          const domMembers = state.domClipChildren
-            .filter((child) => child.audioGroup === groupId)
-            .map(
-              (child): TimelineElement => ({
-                id: child.id,
-                domId: child.id,
-                tag: "div",
-                start: 0,
-                duration: 0,
-                track: -1,
-              }),
-            );
-          return [...flatMembers, ...domMembers];
-        }, setAudioGroupAttribute.setQuiet),
+        guard(
+          (groupId) => {
+            const state = usePlayerStore.getState();
+            const flatMembers = state.elements.filter((el) => el.audioGroup === groupId);
+            const domMembers = state.domClipChildren
+              .filter((child) => child.audioGroup === groupId)
+              .map(
+                (child): TimelineElement => ({
+                  id: child.id,
+                  domId: child.id,
+                  tag: "div",
+                  start: 0,
+                  duration: 0,
+                  track: -1,
+                }),
+              );
+            return [...flatMembers, ...domMembers];
+          },
+          setAudioGroupAttribute.setQuiet,
+          (groupId, attr) => revertAudioGroupLive(groupId, attr),
+        ),
       ),
     },
     setElementFxAttribute: {
       ...setElementFxAttribute,
-      setQuiet: track(guard((element) => [element], setElementFxAttribute.setQuiet)),
+      setQuiet: track(
+        guard(
+          (element) => [element],
+          setElementFxAttribute.setQuiet,
+          (element, attr) => revertElementFxLive(element, attr),
+        ),
+      ),
     },
     handleTimelineElementDelete: track(guard((element) => [element], handleTimelineElementDelete)),
     handleTimelineElementsDelete: track(

package/src/index.ts

@@ -1,8 +1,11 @@
 // UI primitives
-export { Button, buttonBase, buttonVariants } from "./components/ui/Button";
+export { Button, buttonBase, buttonSizes, buttonVariants } from "./components/ui/Button";
 export type { ButtonSize, ButtonVariant, PreviewState } from "./components/ui/Button";
+export { HyperframesLogo } from "./components/StudioHeader";
 export { IconButton } from "./components/ui/IconButton";
 export { Tab, TabPanel, Tabs, TabsList } from "./components/ui/Tabs";
+export { HyperframesLoader } from "./components/ui/HyperframesLoader";
+export type { HyperframesLoaderProps } from "./components/ui/HyperframesLoader";
 export { Tooltip } from "./components/ui/Tooltip";
 export { cn } from "./components/ui/cn";
 export {
@@ -48,7 +51,7 @@ export {
   liveTime,
   formatTime,
 } from "./player";
-export type { TimelineElement } from "./player";
+export type { TimelineElement, TimelineTimeRange } from "./player";
 
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";

package/src/main.tsx

@@ -65,6 +65,10 @@ window.addEventListener("error", (event) => {
 });
 
 let filteredAssetErrorCount = 0;
+let filteredAbortCount = 0;
+// Bounded so a hostile extension cannot grow it; a novel abort message still surfaces once.
+const seenAbortMessages = new Set<string>();
+const MAX_SEEN_ABORT_MESSAGES = 20;
 
 // fallow-ignore-next-line complexity
 window.addEventListener("unhandledrejection", (event) => {
@@ -80,6 +84,28 @@ window.addEventListener("unhandledrejection", (event) => {
     }
     return;
   }
+  // An AbortError rejection is a cancellation we asked for, not a failure. Our own
+  // fetch chains handle it; the unhandled copies come from browser extensions that
+  // wrap window.fetch and derive a promise from each request without a rejection
+  // handler, so they reject with our abort reason whenever a thumbnail lease is
+  // released mid-fetch. Filtered before the cap so a scroll burst cannot exhaust
+  // ERROR_CAP and silence the session's real rejections. Sampled per distinct
+  // message, so an abort we have not seen before (e.g. our own "Aborted") is
+  // recorded once instead of drowning in the extension flood.
+  if (props.error_name === "AbortError") {
+    filteredAbortCount++;
+    const message = props.error_message.slice(0, 200);
+    const novel =
+      !seenAbortMessages.has(message) && seenAbortMessages.size < MAX_SEEN_ABORT_MESSAGES;
+    if (novel) seenAbortMessages.add(message);
+    if (novel || filteredAbortCount % 100 === 0) {
+      trackStudioEvent("abort_rejection_filtered", {
+        error_message: message,
+        total_filtered: filteredAbortCount,
+      });
+    }
+    return;
+  }
 
   rejectionCount++;
   if (rejectionCount > ERROR_CAP) {

package/src/player/components/Timeline.tsx

@@ -4,6 +4,7 @@ import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { useTimelineRowElements } from "../hooks/useTimelineRowElements";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { useTimelineRangeSelection } from "./useTimelineRangeSelection";
+import { usePublishRangeSelection } from "./usePublishRangeSelection";
 import { useTimelinePlayhead } from "./useTimelinePlayhead";
 import { useTimelineZoom } from "./useTimelineZoom";
 import { useTimelineAssetDrop } from "./timelineDragDrop";
@@ -80,6 +81,7 @@ export const Timeline = memo(function Timeline({
   onBlockedEditAttempt: onBlockedEditAttemptOverride,
   onSplitElement: onSplitElementOverride,
   onSelectElement,
+  onRangeSelect,
   onCopyClip,
   onPasteClip,
   onDuplicateClip,
@@ -167,10 +169,10 @@ export const Timeline = memo(function Timeline({
     selectedElementIds,
   );
   const expandedElementsRef = useRef(expandedElements);
-  expandedElementsRef.current = expandedElements;
+  expandedElementsRef.current = expandedElements; // oxlint-disable-line react/refs -- event handlers read the latest elements
   const ppsRef = useRef(100);
   const durationRef = useRef(effectiveDuration);
-  durationRef.current = effectiveDuration;
+  durationRef.current = effectiveDuration; // oxlint-disable-line react/refs -- event handlers read the latest duration
   const fitPpsRef = useRef(100);
   const {
     pinZoomBeforeEdit,
@@ -214,7 +216,6 @@ export const Timeline = memo(function Timeline({
     onMoveElements: pinnedOnMoveElements,
   });
   const onContextMenuClip = useClipContextMenu(onSelectElement, dismissGapMenu, setClipContextMenu);
-
   const {
     draggedClip,
     setDraggedClip,
@@ -241,7 +242,6 @@ export const Timeline = memo(function Timeline({
     refreshAfterLaneMove,
     sessionEpoch,
   });
-
   const assetDrop = useTimelineAssetDrop({
     scrollRef,
     ppsRef,
@@ -320,7 +320,6 @@ export const Timeline = memo(function Timeline({
       setKfContextMenu,
       toggleSelectedKeyframe,
     });
-
   const { clipIndex, renderTimeRange, visibleTimeRange, pinnedClipIdentities } =
     useTimelineClipRenderWindow({
       tracks,
@@ -415,7 +414,8 @@ export const Timeline = memo(function Timeline({
     contentOrigin,
     sessionEpoch,
   });
-  setRangeSelectionRef.current = setRangeSelection; // stable ref consumed by useTimelineClipDrag
+  usePublishRangeSelection(rangeSelection, onRangeSelect);
+  setRangeSelectionRef.current = setRangeSelection; // oxlint-disable-line react/refs -- stable ref consumed by useTimelineClipDrag
 
   useTimelineSelectionLifecycle(expandedElements, selectedElementId, setShowPopover, () =>
     setRangeSelection(null),

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, gutterFill } from "./TimelineTrackHeader";
+import { TimelineTrackHeader } from "./TimelineTrackHeader";
 import { defaultTimelineTheme } from "./timelineTheme";
 import { type TimelineElement } from "../store/playerStore";
 import type { TimelineEditCallbacks } from "./timelineCallbacks";
@@ -794,6 +794,10 @@ 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());
     });
 
@@ -908,28 +912,3 @@ describe("TimelineTrackHeader", () => {
     });
   });
 });
-
-// AD147: 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,
-    );
-  });
-});