@hyperframes/studio 0.8.51 → 0.8.53-desktop.0

package/src/hostMount.test.tsx

@@ -0,0 +1,222 @@
+// @vitest-environment happy-dom
+
+// Proves the package's public exports, not internal hook paths, are enough
+// for a host to mount hand editing outside EditorShell: an edit writes
+// through the history path, Undo restores it, and a 409 shows the banner.
+import { act, createElement, useRef } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+// Backend/storage mocking only, standing in for a host's own server and
+// persistence — not part of the host's integration code under test.
+import { studioFileContentVersion } from "./utils/studioFileVersion";
+import { createMemoryEditHistoryStorage } from "./utils/editHistoryStorage";
+import {
+  flushStudioPendingEdits,
+  useTimelineEditing,
+  useProjectFileWriter,
+  usePersistentEditHistory,
+  useEditHistoryActions,
+  ExternalFileConflictBanner,
+  StudioFileConflictError,
+  type ExternalFileChangeCoordinatorHandle,
+  type TimelineElement,
+} from "./index";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const ORIGINAL_HTML = '<div id="clip" data-start="0" data-track-index="0"></div>';
+
+let root: Root | null = null;
+afterEach(() => {
+  act(() => root?.unmount());
+  document.body.innerHTML = "";
+  vi.unstubAllGlobals();
+});
+
+/** A minimal disk with etag-guarded PUT, faithful enough to exercise a real
+ *  conflict: a stale If-Match gets a 409 with the current version + content. */
+function stubHostProjectDisk(
+  initial: Record<string, string>,
+  options?: { editElsewhereAfterFirstRead?: boolean },
+) {
+  const content = { ...initial };
+  const readsSeen = new Set<string>();
+  // The real backend's etag is a content hash (useProjectFileWriter derives
+  // If-Match the same way) — an arbitrary counter here would make every
+  // write from a host that hasn't just read the file look stale.
+  const versionOf = (path: string) => studioFileContentVersion(content[path]);
+
+  async function handlePut(path: string, init: RequestInit | undefined) {
+    const ifMatch = new Headers(init?.headers).get("If-Match");
+    const currentVersion = await versionOf(path);
+    if (ifMatch && ifMatch !== currentVersion) {
+      return new Response(JSON.stringify({ currentVersion, currentContent: content[path] }), {
+        status: 409,
+      });
+    }
+    content[path] = String(init?.body ?? "");
+    return new Response(JSON.stringify({ version: await versionOf(path) }), { status: 200 });
+  }
+
+  async function handleGet(path: string) {
+    const served = content[path];
+    // Simulates another writer landing between this read and the caller's
+    // own write: content moves on right after being served once, so the
+    // caller's hash of what it just read no longer matches disk.
+    if (options?.editElsewhereAfterFirstRead && !readsSeen.has(path)) {
+      readsSeen.add(path);
+      content[path] = `${served} <!--edited elsewhere-->`;
+    }
+    return new Response(
+      JSON.stringify({ content: served, version: await studioFileContentVersion(served) }),
+      { status: 200 },
+    );
+  }
+
+  const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+    const match = String(input).match(/\/files\/([^?]+)/);
+    const path = match ? decodeURIComponent(match[1]) : "";
+    return (init?.method ?? "GET") === "PUT" ? handlePut(path, init) : handleGet(path);
+  });
+  vi.stubGlobal("fetch", fetchMock);
+  return { content, fetchMock };
+}
+
+type TimelineEditingHandle = {
+  handleTimelineElementMove: (
+    element: TimelineElement,
+    updates: { start: number; track: number },
+  ) => Promise<void>;
+};
+
+function mountHost(
+  clip: TimelineElement,
+  iframe: HTMLIFrameElement,
+): {
+  timelineEditing: TimelineEditingHandle;
+  undo: () => Promise<void>;
+  bannerHost: HTMLDivElement;
+} {
+  let timelineEditing: TimelineEditingHandle | null = null;
+  let undo: (() => Promise<void>) | null = null;
+  let conflict: ExternalFileChangeCoordinatorHandle = {
+    blocked: null,
+    retry: async () => {},
+    useExternalFile: async () => {},
+    keepStudioFile: async () => {},
+  };
+  const bannerHost = document.createElement("div");
+  document.body.append(bannerHost);
+  const bannerRoot = createRoot(bannerHost);
+  // Created once: a fresh storage object on every render would change
+  // usePersistentEditHistory's effect deps each time and loop forever.
+  const storage = createMemoryEditHistoryStorage();
+
+  function Harness() {
+    const writer = useProjectFileWriter({ projectId: "p1" });
+    const editHistory = usePersistentEditHistory({ projectId: "p1", storage });
+    const historyActions = useEditHistoryActions({
+      editHistory,
+      readOptionalProjectFile: writer.readOptionalProjectFile,
+      readProjectFile: writer.readProjectFile,
+      writeProjectFile: writer.writeProjectFile,
+      showToast: () => {},
+      syncHistoryPreviewAfterApply: async () => {},
+      // The pattern a host's own dom-edit queue would also drain through —
+      // this is the one gate that closes the undo/delete race (#4194).
+      waitForPendingDomEditSaves: async () => {
+        const result = await flushStudioPendingEdits();
+        if (result.status !== "clean") throw result.error;
+      },
+    });
+    undo = historyActions.undo;
+    const commitRef = useRef(null);
+    timelineEditing = useTimelineEditing({
+      projectId: "p1",
+      activeCompPath: "index.html",
+      timelineElements: [clip],
+      showToast: () => {},
+      writeProjectFile: async (path, content, expectedContent) => {
+        try {
+          await writer.writeProjectFile(path, content, expectedContent);
+        } catch (error) {
+          if (error instanceof StudioFileConflictError) {
+            conflict = {
+              ...conflict,
+              blocked: { status: "conflict", generation: 0, error, payload: null },
+            };
+            bannerRoot.render(createElement(ExternalFileConflictBanner, { coordinator: conflict }));
+          }
+          throw error;
+        }
+      },
+      observeProjectFileVersion: writer.observeProjectFileVersion,
+      recordEdit: editHistory.recordEdit,
+      reloadPreview: () => {},
+      previewIframeRef: { current: iframe },
+      pendingTimelineEditPathRef: { current: new Set<string>() },
+      uploadProjectFiles: async () => [],
+      handleDomZIndexReorderCommitRef: commitRef,
+    });
+    return null;
+  }
+
+  root = createRoot(document.createElement("div"));
+  act(() => root!.render(createElement(Harness)));
+  if (!timelineEditing) throw new Error("Expected hook to mount");
+  if (!undo) throw new Error("Expected undo to be exposed");
+  return { timelineEditing, undo, bannerHost };
+}
+
+describe("public export surface: a host mounting hand editing outside EditorShell", () => {
+  it("writes a move through the history path and undo restores it", async () => {
+    const disk = stubHostProjectDisk({ "index.html": ORIGINAL_HTML });
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;
+    const clip: TimelineElement = {
+      id: "clip",
+      domId: "clip",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+
+    const { timelineEditing, undo } = mountHost(clip, iframe);
+    await act(async () => {
+      await timelineEditing.handleTimelineElementMove(clip, { start: 5, track: 0 });
+    });
+    expect(disk.content["index.html"]).toContain('data-start="5"');
+
+    await act(async () => {
+      await undo();
+    });
+    expect(disk.content["index.html"]).toContain('data-start="0"');
+  });
+
+  it("surfaces the conflict banner on a 409", async () => {
+    stubHostProjectDisk({ "index.html": ORIGINAL_HTML }, { editElsewhereAfterFirstRead: true });
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    iframe.contentDocument!.body.innerHTML = ORIGINAL_HTML;
+    const clip: TimelineElement = {
+      id: "clip",
+      domId: "clip",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+
+    const { timelineEditing, bannerHost } = mountHost(clip, iframe);
+
+    await act(async () => {
+      await expect(
+        timelineEditing.handleTimelineElementMove(clip, { start: 5, track: 0 }),
+      ).rejects.toBeInstanceOf(StudioFileConflictError);
+    });
+
+    expect(bannerHost.textContent).toContain("changed outside Studio");
+  });
+});

package/src/index.ts

@@ -1,5 +1,36 @@
+// UI primitives
+export { Button, buttonBase, buttonVariants } from "./components/ui/Button";
+export type { ButtonSize, ButtonVariant, PreviewState } from "./components/ui/Button";
+export { IconButton } from "./components/ui/IconButton";
+export { Tab, TabPanel, Tabs, TabsList } from "./components/ui/Tabs";
+export { Tooltip } from "./components/ui/Tooltip";
+export { cn } from "./components/ui/cn";
+export {
+  ContextMenu,
+  Menu,
+  MenuItem,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuSeparator,
+  MenuShortcut,
+  popupSurface,
+} from "./components/ui/Menu";
+export type { MenuItemTone, PopupPreviewState } from "./components/ui/Menu";
+export { Popover } from "./components/ui/Popover";
+export { Input, fieldBase, fieldText } from "./components/ui/Input";
+export type { InputProps } from "./components/ui/Input";
+export { NumberField } from "./components/ui/NumberField";
+export type { NumberFieldProps } from "./components/ui/NumberField";
+export { Select } from "./components/ui/Select";
+export type { SelectOption, SelectProps } from "./components/ui/Select";
+export { Slider } from "./components/ui/Slider";
+export type { SliderProps } from "./components/ui/Slider";
+export { Toggle } from "./components/ui/Toggle";
+export type { ToggleProps } from "./components/ui/Toggle";
+
 // NLE Layout
 export { EditorShell } from "./components/EditorShell";
+export type { EditorShellProps } from "./components/EditorShell";
 export { NLEPreview } from "./components/nle/NLEPreview";
 export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
 export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
@@ -19,6 +50,10 @@ export {
 } from "./player";
 export type { TimelineElement } from "./player";
 
+// Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
+export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
+export type { PreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
+
 // Editor
 export { SourceEditor } from "./components/editor/SourceEditor";
 export { PropertyPanel } from "./components/editor/PropertyPanel";
@@ -37,6 +72,22 @@ export {
 } from "./components/editor/domEditingAgentPrompt";
 export type { AgentPromptElementInfo } from "./components/editor/domEditingAgentPrompt";
 
+// Render queue
+export { RenderQueue } from "./components/renders/RenderQueue";
+export type { RenderQueueProps, CompositionDimensions } from "./components/renders/RenderQueue";
+export { useRenderQueue } from "./components/renders/useRenderQueue";
+export type { FfmpegStatus } from "./components/renders/useFfmpegStatus";
+export type {
+  RenderJob,
+  ResolutionPreset,
+  StartRenderOptions,
+} from "./components/renders/useRenderQueue";
+export {
+  getPersistedRenderSettings,
+  persistRenderSettings,
+} from "./components/renders/renderSettings";
+export type { PersistedRenderSettings } from "./components/renders/renderSettings";
+
 // Hooks
 export { useElementPicker } from "./hooks/useElementPicker";
 export type { PickedElement } from "./hooks/useElementPicker";
@@ -45,3 +96,39 @@ export type { PickedElement } from "./hooks/useElementPicker";
 export { resolveSourceFile, applyPatch } from "./utils/sourcePatcher";
 export type { PatchOperation } from "./utils/sourcePatcher";
 export { parseStyleString, mergeStyleIntoTag, findElementBlock } from "./utils/htmlEditor";
+
+// Timeline editing: Studio's own hand-edit path, undo/redo, the
+// etag-guarded writer and the conflict banner, for a host mounting the
+// timeline outside EditorShell.
+export { usePersistentEditHistory } from "./hooks/usePersistentEditHistory";
+export type { UsePersistentEditHistoryOptions } from "./hooks/usePersistentEditHistory";
+export { useTimelineEditing } from "./hooks/useTimelineEditing";
+export type { UseTimelineEditingOptions } from "./hooks/useTimelineEditingTypes";
+// A host's own waitForPendingDomEditSaves must also call this, or undo/redo
+// can race a write still in flight (see useTrackPendingTimelineEdit.ts).
+export { flushStudioPendingEdits } from "./utils/studioPendingEdits";
+export type { StudioPendingEditsDrainResult } from "./utils/studioPendingEdits";
+export type {
+  CanEditTimelineElement,
+  TimelineEditPermission,
+} from "./hooks/timelineEditPermission";
+export { useEditHistoryActions } from "./hooks/useEditHistoryActions";
+export type {
+  EditHistoryHandle,
+  UseEditHistoryActionsOptions,
+} from "./hooks/useEditHistoryActions";
+export { useProjectFileWriter } from "./hooks/useProjectFileWriter";
+export type { UseProjectFileWriterOptions } from "./hooks/useProjectFileWriter";
+// A host's writeProjectFile throws this on a 409; catch it to know when
+// to show ExternalFileConflictBanner.
+export { StudioFileConflictError } from "./utils/studioSaveDiagnostics";
+export { ExternalFileConflictBanner } from "./components/ExternalFileConflictBanner";
+export type {
+  ExternalFileChangeCoordinatorHandle,
+  ExternalFileChangeBlockedState,
+} from "./hooks/useExternalFileChangeCoordinator";
+export { TimelinePane } from "./components/nle/TimelinePane";
+export type { TimelinePaneProps } from "./components/nle/TimelinePane";
+export { TimelineEditProvider } from "./contexts/TimelineEditContext";
+export type { TimelineEditCallbacks } from "./player/components/timelineCallbacks";
+export type { BlockedTimelineEditIntent } from "./player/components/timelineEditing";

package/src/player/components/AutomationSelectionMenu.tsx

@@ -29,7 +29,7 @@ export const AutomationSelectionMenu = memo(function AutomationSelectionMenu({
 }: AutomationSelectionMenuProps) {
   const menuRef = useContextMenuDismiss(onClose);
   const row =
-    "block w-full px-2 py-1 text-left text-[11px] text-panel-text-1 hover:bg-panel-bg-3 disabled:opacity-40";
+    "block w-full px-2 py-1 text-left text-[11px] text-panel-text-1 hover:bg-panel-hover disabled:opacity-40";
   // Same edge-clamping precedent as TrackGapContextMenu: without it a
   // right-click near the bottom/right of the timeline renders this menu
   // partially off-screen.

package/src/player/components/Timeline.tsx

@@ -448,7 +448,7 @@ export const Timeline = memo(function Timeline({
   return (
     <div
       ref={setContainerRef}
-      aria-label="Timeline"
+      aria-label="Timeline track view"
       data-timeline-element-count={expandedElements.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}

package/src/player/components/TimelineCanvas.tsx

@@ -179,8 +179,8 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
             left: props.contentOrigin + draggedClip.previewStart * props.pps,
             width: Math.max(draggedClip.element.duration * props.pps, 4),
             height: draggedClipHeight,
-            border: "1px solid rgba(60,230,172,0.55)",
-            background: "rgba(60,230,172,0.12)",
+            border: "1px solid color-mix(in srgb, var(--color-accent) 55%, transparent)",
+            background: "color-mix(in srgb, var(--color-accent) 12%, transparent)",
             borderRadius: 4,
             zIndex: 30,
           }}
@@ -199,8 +199,8 @@ export const TimelineCanvas = memo(function TimelineCanvas(props: TimelineCanvas
             left: props.contentOrigin + props.dropPreview.start * props.pps,
             width: DROP_PREVIEW_SECONDS * props.pps,
             height: TRACK_H - CLIP_Y * 2,
-            border: "1px solid rgba(60,230,172,0.55)",
-            background: "rgba(60,230,172,0.12)",
+            border: "1px solid color-mix(in srgb, var(--color-accent) 55%, transparent)",
+            background: "color-mix(in srgb, var(--color-accent) 12%, transparent)",
             borderRadius: 4,
             zIndex: 30,
           }}

package/src/player/components/TimelineClip.tsx

@@ -71,7 +71,6 @@ export const TimelineClip = memo(function TimelineClip({
     isSelected ? "is-selected" : "",
     isHovered ? "is-hovered" : "",
     isDragging ? "is-dragging" : "",
-    showDefaultText ? "" : "is-micro",
     isAudioTimelineElement(el) ? "is-audio" : "",
   ]
     .filter((className) => className.length > 0)

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", () => {
     });
   });
 });
+
+// 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,
+    );
+  });
+});

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/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

@@ -36,43 +36,43 @@ 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)",
+  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/lib/playbackShortcuts.ts

@@ -17,6 +17,8 @@ const PLAYBACK_SHORTCUT_IGNORED_SELECTOR = [
   "[role='checkbox']",
   "[role='combobox']",
   "[role='menuitem']",
+  // Base UI's menu radio item is a `<div>`, so `button` above no longer catches it.
+  "[role='menuitemradio']",
   "[role='radio']",
   "[role='slider']",
   "[role='spinbutton']",

package/src/player/lib/timelinePerformanceDiagnostics.test.ts

@@ -14,7 +14,7 @@ describe("timeline performance diagnostics", () => {
 
   it("reads mounted resources without mutating the timeline", () => {
     document.body.innerHTML = `
-      <div aria-label="Timeline" data-timeline-scheduler-queued="3"
+      <div aria-label="Timeline track view" data-timeline-scheduler-queued="3"
            data-timeline-scheduler-active="2" data-timeline-cache-bytes="4096">
         <div data-timeline-row><div data-clip="true"></div><div data-clip="true"></div></div>
         <div data-timeline-row><div data-clip="true"></div></div>
@@ -41,7 +41,8 @@ describe("timeline performance diagnostics", () => {
   });
 
   it("returns the zero baseline after unmount or reset removes the DOM", () => {
-    document.body.innerHTML = '<div aria-label="Timeline"><div data-clip="true"></div></div>';
+    document.body.innerHTML =
+      '<div aria-label="Timeline track view"><div data-clip="true"></div></div>';
     expect(readTimelinePerformanceDiagnostics().mountedClipRoots).toBe(1);
 
     document.body.replaceChildren();

package/src/player/lib/timelinePerformanceDiagnostics.ts

@@ -69,7 +69,7 @@ function sumDataAttribute(root: ParentNode, selector: string, dataKey: string):
 export function readTimelinePerformanceDiagnostics(
   root: ParentNode = document,
 ): Readonly<TimelinePerformanceDiagnostics> {
-  const timelineRoots = root.querySelectorAll<HTMLElement>('[aria-label="Timeline"]');
+  const timelineRoots = root.querySelectorAll<HTMLElement>('[aria-label="Timeline track view"]');
   let mountedTimelineDescendants = 0;
   for (const timelineRoot of timelineRoots) {
     mountedTimelineDescendants += timelineRoot.querySelectorAll("*").length;

package/src/player/store/previewIframeStore.notify.test.tsx

@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { act, StrictMode, useCallback, useEffect, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { expect, it } from "vitest";
+import { useOwnPreviewIframe, usePreviewIframeStore } from "./previewIframeStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+// Mirrors NLEContext.tsx: a ref callback pushes the element on attach
+// (~L126, onIframeLoad) and a separate mount/dep effect re-pushes the SAME
+// ref value (~L304-306, deps include an unrelated counter like refreshKey).
+function Child({ tick }: { tick: number }) {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const setIframe = usePreviewIframeStore((s) => s.setIframe);
+
+  const handleRef = useCallback(
+    (el: HTMLIFrameElement | null) => {
+      iframeRef.current = el;
+      setIframe(el);
+    },
+    [setIframe],
+  );
+
+  useEffect(() => {
+    setIframe(iframeRef.current);
+  }, [tick, setIframe]);
+
+  return <iframe ref={handleRef} />;
+}
+
+function Owner({ tick }: { tick: number }) {
+  useOwnPreviewIframe();
+  return <Child tick={tick} />;
+}
+
+it("does not notify raw subscribers for a repeated setIframe(sameValue)", () => {
+  let notifyCount = 0;
+  const unsubscribe = usePreviewIframeStore.subscribe(() => {
+    notifyCount += 1;
+  });
+
+  const container = document.createElement("div");
+  const root = createRoot(container);
+  act(() => {
+    root.render(
+      <StrictMode>
+        <Owner tick={0} />
+      </StrictMode>,
+    );
+  });
+  // A dep bump on the mount effect with the iframe DOM node unchanged -
+  // the shape NLEContext hits every time refreshKey moves without a new
+  // <iframe>.
+  act(() => {
+    root.render(
+      <StrictMode>
+        <Owner tick={1} />
+      </StrictMode>,
+    );
+  });
+
+  const iframe = usePreviewIframeStore.getState().iframe;
+  expect(iframe).not.toBeNull();
+
+  // 3 real Object.is-distinct transitions happen here: the ref-callback's
+  // null -> element attach, then StrictMode's mount-effect replay drives
+  // useOwnPreviewIframe's unmount cleanup (element -> null) and the
+  // re-run mount effect (null -> element) once each. Measured on the
+  // unfixed store: 7 (four of those are the SAME value re-pushed by the
+  // ref callback's own redundant effect run and the tick-bump update).
+  expect(notifyCount).toBe(3);
+
+  act(() => root.unmount());
+  unsubscribe();
+});