feat(studio): timeline revamp with active-clip highlighting and hide controls (#2017)

Timeline UI
- Highlight clips visible at the playhead in the primary color; others share one neutral color
- Minimalist rounded clips, single-color track rows, no gutter icons or superscript labels
- Per-track eye toggle and a per-element hide button in the design panel
- Ruler zoom fixes: sub-second tick intervals and correct label formatting at high zoom
- Sticky gutter so track controls stay visible while scrolling

WYSIWYG visibility (data-hidden)
- Runtime honors data-hidden (display:none), so hiding affects the render, not just the preview
- HTML stays the source of truth; hide state persists and round-trips on reload

Split several studio files to stay under the 600-line cap; pure relocations, no behavior change.

Author: miguel-heygen

.fallowrc.jsonc

@@ -214,6 +214,12 @@
       "file": "packages/studio/src/player/components/timelineCallbacks.ts",
       "exports": ["*"],
     },
+    // Shared timeline DOM barrel for downstream consumers; fallow does not
+    // trace all re-export-only modules.
+    {
+      "file": "packages/studio/src/player/lib/timelineDOM.ts",
+      "exports": ["*"],
+    },
     // gsapTargetCache: cached O(1) GSAP target lookup, consumed by
     // useDomEditCommits and intended to replace the local copy in
     // useDomGeometryCommits once callers migrate.

packages/core/src/runtime/init.test.ts

@@ -776,6 +776,52 @@ describe("initSandboxRuntimeModular", () => {
     expect(bottomBand.style.visibility).toBe("hidden");
   });
 
+  it("forces data-hidden timed elements out of layout until the attribute is removed", () => {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "main");
+    root.setAttribute("data-root", "true");
+    root.setAttribute("data-start", "0");
+    root.setAttribute("data-duration", "10");
+    root.setAttribute("data-width", "1920");
+    root.setAttribute("data-height", "1080");
+    document.body.appendChild(root);
+
+    const hiddenClip = document.createElement("div");
+    hiddenClip.style.position = "absolute";
+    hiddenClip.setAttribute("data-start", "2");
+    hiddenClip.setAttribute("data-duration", "4");
+    hiddenClip.setAttribute("data-hidden", "");
+    root.appendChild(hiddenClip);
+
+    window.__timelines = {
+      main: createMockTimeline(10),
+    };
+
+    initSandboxRuntimeModular();
+
+    const player = window.__player;
+    expect(player).toBeDefined();
+
+    player?.seek(0);
+    expect(hiddenClip.style.display).toBe("none");
+
+    player?.seek(3);
+    expect(hiddenClip.style.display).toBe("none");
+
+    player?.seek(7);
+    expect(hiddenClip.style.display).toBe("none");
+
+    hiddenClip.removeAttribute("data-hidden");
+
+    player?.seek(3);
+    expect(hiddenClip.style.visibility).toBe("visible");
+    expect(hiddenClip.style.display).toBe("");
+
+    player?.seek(7);
+    expect(hiddenClip.style.visibility).toBe("hidden");
+    expect(hiddenClip.style.display).toBe("");
+  });
+
   it("does not stamp Studio timing on GSAP targets inside authored timed clips", () => {
     withStudioIframe(() => {
       const root = document.createElement("div");

packages/core/src/runtime/init.ts

@@ -1666,6 +1666,8 @@ export function initSandboxRuntimeModular(): void {
     timedClipInFlow = new WeakMap<Element, boolean>();
     timedClipIsLeaf = new WeakMap<Element, boolean>();
   };
+  const dataHiddenDisplayRestores = new WeakMap<HTMLElement, string>();
+  const dataHiddenDisplayNodes = new WeakSet<HTMLElement>();
 
   const syncMediaForCurrentState = () => {
     const resolveMediaCompositionContext = (element: HTMLVideoElement | HTMLAudioElement) => {
@@ -1754,6 +1756,29 @@ export function initSandboxRuntimeModular(): void {
     for (const rawNode of visibilityNodes) {
       if (!(rawNode instanceof HTMLElement)) continue;
 
+      if (rawNode.hasAttribute("data-hidden")) {
+        if (!dataHiddenDisplayNodes.has(rawNode)) {
+          dataHiddenDisplayRestores.set(rawNode, rawNode.style.getPropertyValue("display"));
+          dataHiddenDisplayNodes.add(rawNode);
+        }
+        rawNode.style.display = "none";
+        if (rawNode instanceof HTMLVideoElement || rawNode instanceof HTMLImageElement) {
+          colorGradingRuntime?.setSourceVisibility(rawNode, false);
+        }
+        continue;
+      }
+
+      if (dataHiddenDisplayNodes.has(rawNode)) {
+        const previousDisplay = dataHiddenDisplayRestores.get(rawNode);
+        if (previousDisplay) {
+          rawNode.style.display = previousDisplay;
+        } else {
+          rawNode.style.removeProperty("display");
+        }
+        dataHiddenDisplayRestores.delete(rawNode);
+        dataHiddenDisplayNodes.delete(rawNode);
+      }
+
       let isVisibleNow = isTimedElementVisibleAt(rawNode, state.currentTime);
       // Descendants must not override a hidden ancestor clip. CSS visibility can
       // otherwise leak child pixels through inactive scenes because a descendant

packages/studio-server/src/helpers/waveform.ts

@@ -18,6 +18,7 @@ function computePeaks(floats: Float32Array, count: number): number[] {
     const end = Math.min(Math.floor((i + 1) * step), floats.length);
     let max = 0;
     for (let j = start; j < end; j++) {
+      // fallow-ignore-next-line code-duplication
       const abs = Math.abs(floats[j] ?? 0);
       if (abs > max) max = abs;
     }

packages/studio/src/App.tsx

@@ -360,7 +360,6 @@ export function StudioApp() {
     resetErrors: resetConsoleErrors,
   } = useConsoleErrorCapture(previewIframe);
   const dragOverlay = useDragOverlay(fileManager.handleImportFiles);
-  // Gesture recording
   const handleToggleRecordingRef = useRef<() => void>(() => {});
   const domEditSessionRef = useRef(domEditSession);
   domEditSessionRef.current = domEditSession;
@@ -531,6 +530,7 @@ export function StudioApp() {
                       handleTimelineFileDrop={timelineEditing.handleTimelineFileDrop}
                       handleTimelineElementMove={timelineEditing.handleTimelineElementMove}
                       handleTimelineElementResize={timelineEditing.handleTimelineElementResize}
+                      handleToggleTrackHidden={timelineEditing.handleToggleTrackHidden}
                       handleBlockedTimelineEdit={timelineEditing.handleBlockedTimelineEdit}
                       handleTimelineElementSplit={timelineEditing.handleTimelineElementSplit}
                       handleRazorSplit={timelineEditing.handleRazorSplit}
@@ -572,6 +572,7 @@ export function StudioApp() {
                         domEditSaveTimestampRef={domEditSaveTimestampRef}
                         recordEdit={editHistory.recordEdit}
                         {...cropModeProps}
+                        onToggleElementHidden={timelineEditing.handleToggleElementHidden}
                       />
                     )}
                   </div>

packages/studio/src/components/StudioPreviewArea.tsx

@@ -58,6 +58,7 @@ export interface StudioPreviewAreaProps {
     element: TimelineElement,
     updates: Pick<TimelineElement, "start" | "duration" | "playbackStart">,
   ) => Promise<void> | void;
+  handleToggleTrackHidden: (track: number, hidden: boolean) => Promise<void> | void;
   handleBlockedTimelineEdit: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
   handleRazorSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -85,6 +86,7 @@ export function StudioPreviewArea({
   handleTimelineFileDrop,
   handleTimelineElementMove,
   handleTimelineElementResize,
+  handleToggleTrackHidden,
   handleBlockedTimelineEdit,
   handleTimelineElementSplit,
   handleRazorSplit,
@@ -165,6 +167,7 @@ export function StudioPreviewArea({
   // diamond reports a clip-% but the script ops key on the tween-%. Prefers the
   // anim in the keyframe's property group, falling back to the first keyframed one.
   const resolveKeyframeTarget = useCallback(
+    // fallow-ignore-next-line complexity
     (pct: number): { animId: string; tweenPct: number } | null => {
       const cached = usePlayerStore.getState().keyframeCache.get(domEditSelection?.id ?? "");
       const kf = cached?.keyframes.find((k) => Math.abs(k.percentage - pct) < 0.2);
@@ -182,6 +185,7 @@ export function StudioPreviewArea({
     () => ({
       onMoveElement: handleTimelineElementMove,
       onResizeElement: handleTimelineElementResize,
+      onToggleTrackHidden: handleToggleTrackHidden,
       onBlockedEditAttempt: handleBlockedTimelineEdit,
       onSplitElement: handleTimelineElementSplit,
       onRazorSplit: handleRazorSplit,
@@ -210,6 +214,7 @@ export function StudioPreviewArea({
       // drop past the boundary (last keyframe past the end, first before the start)
       // resizes the tween — position/duration grow so the dragged keyframe lands at
       // the drop while every other keyframe keeps its absolute time (value+ease too).
+      // fallow-ignore-next-line complexity
       onMoveKeyframe: (_elId: string, fromClipPct: number, toClipPct: number) => {
         const target = resolveKeyframeTarget(fromClipPct);
         const sel = domEditSelection;
@@ -280,6 +285,7 @@ export function StudioPreviewArea({
     [
       handleTimelineElementMove,
       handleTimelineElementResize,
+      handleToggleTrackHidden,
       handleBlockedTimelineEdit,
       handleTimelineElementSplit,
       handleRazorSplit,

packages/studio/src/components/StudioRightPanel.tsx

@@ -62,6 +62,7 @@ export interface StudioRightPanelProps {
     kind: EditHistoryKind;
     files: Record<string, { before: string; after: string }>;
   }) => Promise<void>;
+  onToggleElementHidden?: (elementKey: string, hidden: boolean) => Promise<void> | void;
 }
 
 // fallow-ignore-next-line complexity
@@ -78,6 +79,7 @@ export function StudioRightPanel({
   reloadPreview,
   domEditSaveTimestampRef,
   recordEdit,
+  onToggleElementHidden,
 }: StudioRightPanelProps) {
   const {
     rightWidth,
@@ -350,6 +352,7 @@ export function StudioRightPanel({
       multiSelectCount={domEditGroupSelections.length}
       copiedAgentPrompt={copiedAgentPrompt}
       onClearSelection={clearDomSelection}
+      onToggleElementHidden={onToggleElementHidden}
       onUngroup={handleUngroupSelection}
       onSetStyle={handleDomStyleCommit}
       onSetAttribute={handleDomAttributeCommit}

packages/studio/src/components/editor/PropertyPanel.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import type { TimelineElement } from "../../player";
 import {
   buildInsetClipPathSides,
   buildStrokeStyleUpdates,
@@ -11,6 +12,7 @@ import {
   parseInsetClipPathSides,
   setCssFilterFunctionPx,
 } from "./PropertyPanel";
+import { isSelectedElementHidden } from "./propertyPanelHelpers";
 
 describe("PropertyPanel style helpers", () => {
   it("normalizes bounded pixel values without accepting incompatible units", () => {
@@ -113,3 +115,26 @@ describe("PropertyPanel style helpers", () => {
     expect(buildStrokeStyleUpdates("solid", "4px")).toEqual([["border-style", "solid"]]);
   });
 });
+
+describe("isSelectedElementHidden", () => {
+  it("reads hidden state by selected timeline id or key", () => {
+    const elements: TimelineElement[] = [
+      { id: "visible", tag: "div", start: 0, duration: 1, track: 0 },
+      { id: "hidden", tag: "div", start: 0, duration: 1, track: 0, hidden: true },
+      {
+        id: "keyed-hidden",
+        key: "scene.html:#keyed-hidden",
+        tag: "div",
+        start: 0,
+        duration: 1,
+        track: 0,
+        hidden: true,
+      },
+    ];
+
+    expect(isSelectedElementHidden(elements, null)).toBe(false);
+    expect(isSelectedElementHidden(elements, "visible")).toBe(false);
+    expect(isSelectedElementHidden(elements, "hidden")).toBe(true);
+    expect(isSelectedElementHidden(elements, "scene.html:#keyed-hidden")).toBe(true);
+  });
+});

packages/studio/src/components/editor/PropertyPanel.tsx

@@ -1,5 +1,6 @@
 import { memo, useEffect, useMemo, useRef, useState } from "react";
 import { Move } from "../../icons/SystemIcons";
+import { Eye, EyeSlash } from "@phosphor-icons/react";
 import { InspectorHeaderActions } from "./InspectorHeaderActions";
 import { useStudioShellContext } from "../../contexts/StudioContext";
 import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
@@ -10,6 +11,7 @@ import {
   RESPONSIVE_GRID,
   readGsapRuntimeValuesForPanel,
   readGsapBorderRadiusForPanel,
+  isSelectedElementHidden,
 } from "./propertyPanelHelpers";
 import { MetricField, Section } from "./propertyPanelPrimitives";
 import { createTransformCommitHandlers } from "./propertyPanelTransformCommit";
@@ -67,6 +69,7 @@ export const PropertyPanel = memo(function PropertyPanel({
   onAddTextField,
   onRemoveTextField,
   onAskAgent: _onAskAgent,
+  onToggleElementHidden,
   onImportAssets,
   fontAssets = [],
   onImportFonts,
@@ -106,6 +109,10 @@ export const PropertyPanel = memo(function PropertyPanel({
   const clipboardTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);
   const storeTime = usePlayerStore((s) => s.currentTime);
   const isPlaying = usePlayerStore((s) => s.isPlaying);
+  const timelineElements = usePlayerStore((s) => s.elements);
+  const selectedElementId = usePlayerStore((s) => s.selectedElementId);
+  const selectedElementHidden = isSelectedElementHidden(timelineElements, selectedElementId);
+  const visibilityToggleLabel = selectedElementHidden ? "Show element" : "Hide element";
   const liveTimeRef = useRef(storeTime);
   const [, forceRender] = useState(0);
   useEffect(() => {
@@ -288,13 +295,32 @@ export const PropertyPanel = memo(function PropertyPanel({
             </div>
             <div className="mt-0.5 truncate text-[11px] text-neutral-500">{sourceLabel}</div>
           </div>
-          <InspectorHeaderActions
-            element={element}
-            copied={clipboardCopied}
-            onCopy={handleCopyElementInfo}
-            onClear={onClearSelection}
-            onUngroup={onUngroup}
-          />
+          <div className="flex items-center gap-1">
+            {selectedElementId && onToggleElementHidden && (
+              <button
+                type="button"
+                aria-label={visibilityToggleLabel}
+                title={visibilityToggleLabel}
+                onClick={() => {
+                  void onToggleElementHidden(selectedElementId, !selectedElementHidden);
+                }}
+                className="flex h-6 w-6 items-center justify-center rounded text-neutral-500 transition-colors hover:bg-neutral-800 hover:text-neutral-300"
+              >
+                {selectedElementHidden ? (
+                  <EyeSlash size={13} weight="bold" aria-hidden="true" />
+                ) : (
+                  <Eye size={13} weight="bold" aria-hidden="true" />
+                )}
+              </button>
+            )}
+            <InspectorHeaderActions
+              element={element}
+              copied={clipboardCopied}
+              onCopy={handleCopyElementInfo}
+              onClear={onClearSelection}
+              onUngroup={onUngroup}
+            />
+          </div>
         </div>
       </div>
       <div className="flex-1 overflow-y-auto">

packages/studio/src/components/editor/domEditingElement.ts

@@ -28,6 +28,7 @@ export function isElementComputedVisible(el: HTMLElement): boolean {
 
 const VISUAL_LEAF_TAGS = new Set(["img", "video", "canvas", "svg", "audio"]);
 
+// fallow-ignore-next-line complexity
 function hasVisualPresence(el: HTMLElement): boolean {
   const win = el.ownerDocument.defaultView;
   if (!win) return false;
@@ -236,9 +237,13 @@ export function isLargeRasterDomEditSelection(
 
 // ─── Element finders ──────────────────────────────────────────────────────────
 
+type FindElementSelection = Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex"> & {
+  sourceFile?: string;
+};
+
 export function findElementForSelection(
   doc: Document,
-  selection: Pick<DomEditSelection, "id" | "hfId" | "selector" | "selectorIndex" | "sourceFile">,
+  selection: FindElementSelection,
   activeCompositionPath: string | null = null,
 ): HTMLElement | null {
   if (selection.hfId) {
@@ -259,6 +264,7 @@ export function findElementForSelection(
 
   if (!selection.selector) return null;
 
+  // fallow-ignore-next-line code-duplication
   if (selection.selector.startsWith(".") && selection.selectorIndex != null) {
     const matches = querySelectorAllSafely(doc, selection.selector).filter(
       (candidate): candidate is HTMLElement =>
@@ -270,6 +276,7 @@ export function findElementForSelection(
     return matches[selection.selectorIndex] ?? null;
   }
 
+  // fallow-ignore-next-line code-duplication
   const matches = querySelectorAllSafely(doc, selection.selector).filter(
     (candidate): candidate is HTMLElement =>
       isHtmlElement(candidate) &&