@hyperframes/studio 0.8.81 → 0.8.82

package/src/player/components/useTimelinePlayhead.ts

@@ -4,12 +4,12 @@ import { useMountEffect } from "../../hooks/useMountEffect";
 import { getPinchTimelineZoomPercent } from "./timelineZoom";
 import {
   getTimelinePlaybackFollowScrollLeft,
-  getTimelinePlayheadLeft,
   getTimelineScrubTime,
   getTimelineScrollLeftForZoomTransition,
   getTimelineScrollLeftForZoomAnchor,
   shouldAutoScrollTimeline,
 } from "./timelineLayout";
+import { getTimelinePlayheadTransform } from "./timelinePlayheadTransform";
 import { applyTimelineHorizontalAutoScrollStep } from "./timelineEditing";
 
 interface UseTimelinePlayheadInput {
@@ -92,7 +92,12 @@ export function useTimelinePlayhead({
   const syncPlayheadPosition = useCallback(
     (time: number) => {
       if (!playheadRef.current || durationRef.current <= 0) return;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(time, ppsRef.current, contentOrigin)}px`;
+      playheadRef.current.style.transform = getTimelinePlayheadTransform(
+        time,
+        ppsRef.current,
+        contentOrigin,
+        !usePlayerStore.getState().isPlaying,
+      );
     },
     [playheadRef, durationRef, ppsRef, contentOrigin],
   );
@@ -122,14 +127,24 @@ export function useTimelinePlayhead({
   }, [zoomMode, scrollRef]);
 
   useMountEffect(() => {
-    const unsub = liveTime.subscribe((t) => {
-      if (!playheadRef.current || durationRef.current <= 0) return;
-      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
-      playheadRef.current.style.left = `${getTimelinePlayheadLeft(
+    let lastLiveTime = usePlayerStore.getState().currentTime;
+    const place = (t: number, atRest: boolean) => {
+      if (!playheadRef.current || durationRef.current <= 0) return false;
+      playheadRef.current.style.transform = getTimelinePlayheadTransform(
         t,
         ppsRef.current,
         contentOriginRef.current,
-      )}px`;
+        atRest,
+      );
+      return true;
+    };
+    const unsubPlaying = usePlayerStore.subscribe((state, prev) => {
+      if (prev.isPlaying && !state.isPlaying) place(lastLiveTime, true);
+    });
+    const unsub = liveTime.subscribe((t) => {
+      lastLiveTime = t;
+      if (!place(t, !usePlayerStore.getState().isPlaying)) return;
+      const playheadX = contentOriginRef.current + Math.max(0, t) * ppsRef.current;
       const scroll = scrollRef.current;
       if (
         !scroll ||
@@ -150,7 +165,10 @@ export function useTimelinePlayhead({
         scroll.scrollLeft = nextScrollLeft;
       }
     });
-    return unsub;
+    return () => {
+      unsub();
+      unsubPlaying();
+    };
   });
 
   const seekFromX = useCallback(

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { timelineElementsChanged } from "./timelinePlayerSync";
+
+describe("timelineElementsChanged", () => {
+  const clip = { id: "v", tag: "video", start: 0, duration: 4, track: 1 };
+  it.each([
+    ["muted", { muted: true }],
+    ["sound", { hasAudio: true }],
+    ["volume", { volume: 0 }],
+    ["speed", { playbackRate: 2 }],
+    ["hidden", { hidden: true }],
+    ["audio group volume", { audioGroupVolume: 0 }],
+    ["audio group hidden", { audioGroupHidden: true }],
+    ["fade in", { fadeIn: 1 }],
+    ["fade out", { fadeOut: 1 }],
+  ])("sees a clip whose %s changed with no timing change", (_name, change) => {
+    expect(timelineElementsChanged([clip], [{ ...clip, ...change }])).toBe(true);
+    expect(timelineElementsChanged([{ ...clip, ...change }], [{ ...clip, ...change }])).toBe(false);
+  });
+});

package/src/player/hooks/timelinePlayerSync.ts

@@ -1,5 +1,22 @@
 import type { TimelineElement } from "../store/playerStore";
 
+const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
+  "id",
+  "start",
+  "duration",
+  "track",
+  "sourceDuration",
+  "muted",
+  "hasAudio",
+  "volume",
+  "playbackRate",
+  "hidden",
+  "audioGroupVolume",
+  "audioGroupHidden",
+  "fadeIn",
+  "fadeOut",
+];
+
 /** Whether a derived timeline changes any field that affects rendering. */
 export function timelineElementsChanged(
   previous: TimelineElement[],
@@ -8,13 +25,6 @@ export function timelineElementsChanged(
   if (next.length !== previous.length) return true;
   return next.some((element, index) => {
     const prior = previous[index];
-    return (
-      !prior ||
-      element.id !== prior.id ||
-      element.start !== prior.start ||
-      element.duration !== prior.duration ||
-      element.track !== prior.track ||
-      element.sourceDuration !== prior.sourceDuration
-    );
+    return !prior || RENDERED_FIELDS.some((key) => element[key] !== prior[key]);
   });
 }

package/src/player/hooks/useShadowPreviewReload.ts

@@ -12,7 +12,7 @@ import {
   type PreviewIframeSlot,
   type UseTimelineSyncCallbacksParams,
 } from "./useTimelineSyncCallbacks";
-import type { PlaybackAdapter } from "../lib/playbackTypes";
+import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
 import { thumbnailScheduler } from "../lib/thumbnailScheduler";
 import { usePlayerStore } from "../store/playerStore";
 
@@ -23,6 +23,11 @@ export const SHADOW_READY_TIMEOUT_MS = 15_000;
 // A busy machine can need more than one budget; the shadow keeps loading for this many before it is dropped.
 export const SHADOW_READY_BUDGETS = 3;
 
+function restoreSeekPainted(iframe: HTMLIFrameElement | null): Promise<void> | undefined {
+  const win = iframe?.contentWindow as IframeWindow | null | undefined;
+  return win?.__hfWaitForSeekCompletion?.().catch(() => {});
+}
+
 function isDocumentHidden(): boolean {
   return typeof document !== "undefined" && document.visibilityState === "hidden";
 }
@@ -136,10 +141,16 @@ export function useShadowPreviewReload({
   const getShadowAdapter = useCallback(() => getAdapter(shadowIframeRef.current), [getAdapter]);
   const isCurrentShadow = useCallback((gen?: number) => gen === shadowGenRef.current, []);
   const markAdapterReady = useCallback(
-    (_iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
+    (iframe: HTMLIFrameElement | null, gen: number | undefined, commit: () => void) => {
       if (gen == null || gen !== shadowGenRef.current) return;
-      pendingCommitRef.current = { gen, commit };
-      promoteWhenReady(gen);
+      const register = () => {
+        if (gen !== shadowGenRef.current) return;
+        pendingCommitRef.current = { gen, commit };
+        promoteWhenReady(gen);
+      };
+      const painted = restoreSeekPainted(iframe);
+      if (painted) void painted.then(register);
+      else register();
     },
     [promoteWhenReady],
   );

package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts

@@ -325,6 +325,25 @@ describe("shadow reload readiness and failure", () => {
     unmount(root);
   });
 
+  it("promotes only once the shadow's restore seek has painted its frame", async () => {
+    const { getApi, live, gen, root } = beginReload();
+    const shadow = makeShadowWithSpies();
+    let seekPainted = () => {};
+    Object.assign(shadow.iframe.contentWindow!, {
+      __hfWaitForSeekCompletion: () => new Promise<void>((resolve) => (seekPainted = resolve)),
+    });
+    act(() => {
+      getApi().setShadowIframeNode(shadow.iframe);
+      getApi().onShadowIframeLoad(gen);
+      getApi().onShadowReadyChange(gen, true);
+    });
+    expect(getApi().iframeRef.current).toBe(live);
+
+    await act(async () => seekPainted());
+    expect(getApi().iframeRef.current).toBe(shadow.iframe);
+    unmount(root);
+  });
+
   it("promotes when the loader clears before the adapter is ready", () => {
     const { getApi, gen, root } = beginReload();
     const shadow = makeShadowWithSpies();

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

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
@@ -597,3 +597,95 @@ describe("shouldIgnorePlaybackShortcutEvent", () => {
     ).toBe(false);
   });
 });
+
+describe("shouldIgnorePlaybackShortcutEvent while a modal dialog is open", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // happy-dom has no layout, so the `hidden` attribute stands in for checkVisibility.
+  function stubStudioDocument(markup: string): Document {
+    const document = createDocument(markup);
+    const elementProto = document.defaultView!.Element.prototype as {
+      checkVisibility?: (this: Element) => boolean;
+    };
+    elementProto.checkVisibility = function () {
+      return this.closest("[hidden]") === null;
+    };
+    vi.stubGlobal("document", document);
+    return document;
+  }
+
+  it("ignores playback keys with focus still on the page behind the dialog", () => {
+    const document = stubStudioDocument(
+      `<div role="dialog" aria-modal="true"><p>Lint results</p></div>`,
+    );
+    for (const code of ["Space", "ArrowRight", "KeyL"]) {
+      expect(
+        shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent(code, { target: document.body })),
+      ).toBe(true);
+    }
+  });
+
+  it("ignores playback keys with focus inside the dialog", () => {
+    const document = stubStudioDocument(
+      `<div role="dialog" aria-modal="true" tabindex="-1"><p>Lint results</p></div>`,
+    );
+    const dialog = document.querySelector("[role='dialog']");
+    const text = document.querySelector("p");
+    expect(shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: dialog }))).toBe(
+      true,
+    );
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowLeft", { target: text })),
+    ).toBe(true);
+  });
+
+  it("keeps playback keys for dialogs that are hidden, inert or not modal", () => {
+    for (const markup of [
+      `<div role="dialog" aria-modal="true" hidden></div>`,
+      `<div inert><div role="dialog" aria-modal="true"></div></div>`,
+      `<div role="dialog"></div>`,
+    ]) {
+      const document = stubStudioDocument(markup);
+      expect(
+        shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+      ).toBe(false);
+    }
+  });
+
+  it("counts a dialog under fullscreen only when the fullscreen element holds it", () => {
+    const document = stubStudioDocument(
+      `<div id="stage"><div id="inner" role="dialog" aria-modal="true"></div></div>` +
+        `<div id="outer" role="dialog" aria-modal="true"></div>`,
+    );
+    const space = () =>
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body }));
+    const fullscreenOn = (id: string) =>
+      Object.defineProperty(document, "fullscreenElement", {
+        configurable: true,
+        value: document.getElementById(id),
+      });
+    fullscreenOn("stage");
+    expect(space()).toBe(true);
+    document.getElementById("inner")!.remove();
+    expect(space()).toBe(false);
+  });
+
+  it("counts an aria-modal dialog where the browser has no checkVisibility", () => {
+    const document = createDocument(`<div role="dialog" aria-modal="true"></div>`);
+    delete (document.defaultView!.Element.prototype as { checkVisibility?: unknown })
+      .checkVisibility;
+    vi.stubGlobal("document", document);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+    ).toBe(true);
+  });
+
+  it("keeps playback keys when no dialog is open", () => {
+    const document = stubStudioDocument(`<main><p>Preview</p></main>`);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+    ).toBe(false);
+  });
+});

package/src/player/lib/playbackShortcuts.ts

@@ -41,6 +41,23 @@ export function shouldIgnorePlaybackShortcutTarget(target: EventTarget | null):
   );
 }
 
+const MODAL_DIALOG_SELECTOR = "[role=dialog][aria-modal=true]";
+
+// An open modal owns the keyboard wherever focus sits, preview iframe included. It counts only
+// when shown: visible, not inert, and not behind a fullscreen element that leaves it out.
+function isModalDialogOpen(): boolean {
+  const doc = globalThis.document;
+  if (!doc) return false;
+  const fullscreen = doc.fullscreenElement;
+  return Array.from(doc.querySelectorAll(MODAL_DIALOG_SELECTOR)).some(
+    (dialog) =>
+      (!fullscreen || fullscreen.contains(dialog)) &&
+      !dialog.closest("[inert]") &&
+      (typeof dialog.checkVisibility !== "function" ||
+        dialog.checkVisibility({ visibilityProperty: true })),
+  );
+}
+
 interface PlaybackShortcutCaptionState {
   isCaptionEditMode: boolean;
   selectedCaptionSegmentCount: number;
@@ -60,6 +77,7 @@ export function shouldIgnorePlaybackShortcutEvent(
 ): boolean {
   if (event.metaKey || event.ctrlKey || event.altKey) return true;
   if (shouldIgnorePlaybackShortcutTarget(event.target)) return true;
+  if (isModalDialogOpen()) return true;
   return (
     PLAYBACK_FRAME_STEP_CODES.has(event.code) &&
     captionState.isCaptionEditMode &&

package/src/player/lib/playbackTypes.ts

@@ -62,6 +62,7 @@ export type IframeWindow = Window & {
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;
+  __hfWaitForSeekCompletion?: () => Promise<void>;
   /** Declared runtime-side in core's window.d.ts, which this package cannot see.
    *  Every member stays optional and is optional-called, so a runtime that
    *  predates the hook degrades to a no-op instead of throwing. */

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

@@ -9,6 +9,7 @@ import {
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
 import { computeResizePreview } from "../components/timelineClipDragPreview";
 import type { TimelineElement } from "../store/playerStore";
+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
 
 function el(id: string, extra: Partial<TimelineElement> = {}): TimelineElement {
   return { id, tag: "img", start: 0, duration: 5, track: 0, ...extra };
@@ -46,6 +47,26 @@ describe("parseTimelineFromDOM — media in-point", () => {
   });
 });
 
+describe("parseTimelineFromDOM — in-point read as playback reads it", () => {
+  it.each([
+    ['data-playback-start="-1" data-media-start="2"', 2, "playback-start"],
+    ['data-playback-start="abc" data-media-start="2"', 2, "playback-start"],
+    ['data-media-start="junk"', 0, "media-start"],
+    ['data-media-start="1.5s"', 0, "media-start"],
+  ])("%s", (inPoint, playbackStart, playbackStartAttr) => {
+    const doc = makeDoc(
+      `<div data-composition-id="root"><video id="v" class="clip" data-start="0" data-duration="4" ${inPoint}></video></div>`,
+    );
+    const element = parseTimelineFromDOM(doc, 10).find((e) => e.domId === "v")!;
+    const video = doc.getElementById("v")!;
+    expect(element.playbackStart).toBe(readMediaOffsetSeconds((n) => video.getAttribute(n)));
+    expect([element.playbackStart, element.playbackStartAttr]).toEqual([
+      playbackStart,
+      playbackStartAttr,
+    ]);
+  });
+});
+
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   it("bridges a real GSAP transition marker onto both named clips", () => {
     document.body.innerHTML = `
@@ -526,3 +547,74 @@ describe("a composition clip's source length", () => {
     expect(card?.sourceDuration).toBeUndefined();
   });
 });
+
+describe("what the live clip list says a clip plays", () => {
+  function manifestVideo(attrs: string): TimelineElement {
+    const doc = makeDoc(
+      `<div data-composition-id="root"><video id="v" src="a.mp4" data-start="0" data-duration="4" ${attrs}></video></div>`,
+    );
+    return createTimelineElementFromManifestClip({
+      clip: {
+        id: "v",
+        label: "v",
+        kind: "video",
+        tagName: "video",
+        start: 0,
+        duration: 4,
+        track: 0,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: doc.getElementById("v"),
+    });
+  }
+
+  it("carries data-volume and muted from the element", () => {
+    expect(manifestVideo('data-volume="0" muted')).toMatchObject({ volume: 0, muted: true });
+    const plain = manifestVideo("");
+    expect(plain.volume).toBeUndefined();
+    expect(plain.muted).toBeUndefined();
+  });
+
+  it("carries the clip-edge fades, and drops a zero one", () => {
+    const faded = manifestVideo('data-fade-in="1.5" data-fade-out="0"');
+    expect(faded.fadeIn).toBe(1.5);
+    expect(faded.fadeOut).toBeUndefined();
+  });
+
+  it("gives a video with neither muted nor data-has-audio sound, as the compiler does", () => {
+    expect(manifestVideo("").hasAudio).toBe(true);
+    expect(manifestVideo("muted").hasAudio).toBeUndefined();
+    expect(manifestVideo('data-has-audio="false"').hasAudio).toBeUndefined();
+    expect(manifestVideo('muted data-has-audio="true"')).toMatchObject({
+      hasAudio: true,
+      muted: true,
+    });
+  });
+
+  it.each(["", ' data-has-audio="true"'])(
+    "does not give a timed wrapper the sound of an untimed video%s inside it",
+    (videoAttrs) => {
+      const doc = makeDoc(
+        `<div data-composition-id="root"><div id="w" data-start="0" data-duration="4"><video src="a.mp4"${videoAttrs}></video></div></div>`,
+      );
+      const wrapper = createTimelineElementFromManifestClip({
+        clip: {
+          id: "w",
+          label: "w",
+          kind: "element",
+          tagName: "div",
+          start: 0,
+          duration: 4,
+          track: 0,
+          assetUrl: null,
+        },
+        fallbackIndex: 0,
+        doc,
+        hostEl: doc.getElementById("w"),
+      });
+      expect(wrapper.hasAudio).toBeUndefined();
+    },
+  );
+});

package/src/player/lib/timelineDOM.ts

@@ -304,8 +304,6 @@ export function parseTimelineFromDOM(
       if (mediaEl.tagName === "IMG") {
         entry.tag = "img";
       }
-      const vol = el.getAttribute("data-volume") ?? mediaEl.getAttribute("data-volume");
-      if (vol) entry.volume = parseFloat(vol);
       // Override AFTER the helper (which sets the raw relative attribute) so the
       // resolved absolute URL wins — the Studio can then fetch the asset
       // regardless of whether the attribute value was relative or absolute.

package/src/player/lib/timelineElementHelpers.ts

@@ -13,7 +13,7 @@ import { isFinitePositive } from "./playbackAdapter";
 import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
 import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 import { readElementFades } from "@hyperframes/core/audio-fade";
-import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+import { type AttrReader, readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
 
 // ---------------------------------------------------------------------------
 // Layer-reveal lift transparency
@@ -168,14 +168,34 @@ export function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageEl
     : null;
 }
 
+/** The in-point as playback reads it, and the attribute holding it; empty when neither is authored. */
+export function readPlaybackStartAttributes(
+  getAttr: AttrReader,
+): Pick<TimelineElement, "playbackStart" | "playbackStartAttr"> {
+  const playbackStartAttr =
+    getAttr("data-playback-start") != null
+      ? "playback-start"
+      : getAttr("data-media-start") != null
+        ? "media-start"
+        : undefined;
+  return playbackStartAttr
+    ? { playbackStart: readMediaOffsetSeconds(getAttr), playbackStartAttr }
+    : {};
+}
+
+export function playbackStartAttributeForElement(
+  element: Pick<TimelineElement, "kind" | "playbackStartAttr">,
+): "data-media-start" | "data-playback-start" {
+  return element.playbackStartAttr === "playback-start" || element.kind === "composition"
+    ? "data-playback-start"
+    : "data-media-start";
+}
+
 function applyPlaybackMetadataFromElement(entry: TimelineElement, el: Element): void {
-  const playbackStartValue = el.getAttribute("data-playback-start");
-  const legacyMediaStartValue = el.getAttribute("data-media-start");
-  const mediaStartValue = playbackStartValue ?? legacyMediaStartValue;
-  if (mediaStartValue != null)
-    entry.playbackStart = readMediaOffsetSeconds((n) => el.getAttribute(n));
-  if (playbackStartValue != null) entry.playbackStartAttr = "playback-start";
-  else if (legacyMediaStartValue != null) entry.playbackStartAttr = "media-start";
+  Object.assign(
+    entry,
+    readPlaybackStartAttributes((n) => el.getAttribute(n)),
+  );
 
   const authoredPlaybackRate = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
   if (Number.isFinite(authoredPlaybackRate) && authoredPlaybackRate > 0) {
@@ -193,9 +213,25 @@ function setOptional<K extends keyof TimelineElement>(
   else entry[key] = value;
 }
 
-/** `data-has-audio` and the clip-edge fades: what the mixer hears and how it enters and leaves. */
+function readVolume(el: Element, media: Element): number | undefined {
+  const volume = Number.parseFloat(
+    el.getAttribute("data-volume") ?? media.getAttribute("data-volume") ?? "",
+  );
+  return Number.isFinite(volume) ? volume : undefined;
+}
+
+/** What the mixer gets: the compiler's `data-has-audio` rule, muted and volume. */
 function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): void {
-  setOptional(entry, "hasAudio", el.getAttribute("data-has-audio") === "true" ? true : undefined);
+  const media = resolveMediaElement(el) ?? el;
+  const muted = el.hasAttribute("muted") || media.hasAttribute("muted");
+  const hasAudio = el.getAttribute("data-has-audio");
+  const sound = hasAudio === null ? el.tagName === "VIDEO" && !muted : hasAudio === "true";
+  setOptional(entry, "hasAudio", sound ? true : undefined);
+  setOptional(entry, "muted", muted ? true : undefined);
+  setOptional(entry, "volume", readVolume(el, media));
+}
+
+function applyFadeMetadataFromElement(entry: TimelineElement, el: Element): void {
   const fades = readElementFades(el);
   setOptional(entry, "fadeIn", fades.fadeIn > 0 ? fades.fadeIn : undefined);
   setOptional(entry, "fadeOut", fades.fadeOut > 0 ? fades.fadeOut : undefined);
@@ -204,6 +240,7 @@ function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): voi
 export function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
   applyPlaybackMetadataFromElement(entry, el);
   applyAudioMetadataFromElement(entry, el);
+  applyFadeMetadataFromElement(entry, el);
 
   const mediaEl = resolveMediaElement(el);
   if (!mediaEl) return;

package/src/player/lib/timelineViewportBudgets.ts

@@ -49,7 +49,7 @@ export interface TimelineViewportBudgets {
 
 const MEBIBYTE = 1024 * 1024;
 const DAY_MS = 24 * 60 * 60 * 1000;
-export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); // 4K timeline width / tallest 16:9 tile.
+export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); // Decode-memory cap, 4K width / a 66 px 16:9 tile; 40 px clips reuse frames past it.
 
 /**
  * The sole default budget owner for timeline viewport and media virtualization.

package/src/player/store/timelineElement.ts

@@ -55,8 +55,9 @@ export interface TimelineElement {
   playbackRate?: number;
   sourceDuration?: number;
   volume?: number;
-  /** `data-has-audio="true"` on a video: its sound is mixed, so it takes audio affordances (fades). */
+  /** A video with sound to mix (`data-has-audio`, or unmuted without it); `muted` silences it. */
   hasAudio?: boolean;
+  muted?: boolean;
   /** Clip-edge fades from `data-fade-in` / `data-fade-out`, seconds; absent means none. */
   fadeIn?: number;
   fadeOut?: number;

package/src/timelineChromeExports.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+// Mounts the timeline chrome by package name with no StudioShellProvider, as a host app does.
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  AudioMeterStrip,
+  TimelineHistoryButtons,
+  TimelineToolbar,
+  useClipboard,
+  usePlayerStore,
+  type UseClipboardOptions,
+} from "@hyperframes/studio";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+import { useAudioMetersVisible } from "./utils/audioMeterVisibility";
+
+installReactActEnvironment();
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.setState({ elements: [], selectedElementId: null });
+  useAudioMetersVisible.setState(useAudioMetersVisible.getInitialState());
+});
+
+describe("timeline chrome package exports, outside Studio's shell", () => {
+  it("mounts the toolbar with the host's history and no Add beat", async () => {
+    const onUndo = vi.fn();
+    const root = mountReactHarness(
+      <TimelineToolbar history={{ canUndo: true, onUndo }} showAddBeat={false} />,
+    );
+    const undo = document.querySelector<HTMLButtonElement>('button[aria-label="Undo"]');
+    act(() => undo?.click());
+    expect(onUndo).toHaveBeenCalledTimes(1);
+    expect(document.querySelector('button[aria-label="Add beat at playhead"]')).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("mounts the history buttons disabled when given nothing", async () => {
+    const root = mountReactHarness(<TimelineHistoryButtons />);
+    const buttons = Array.from(document.querySelectorAll("button"));
+    expect(buttons.map((b) => b.disabled)).toEqual([true, true]);
+    await act(async () => root.unmount());
+  });
+
+  it("mounts the meter strip on the host's preview iframe", async () => {
+    usePlayerStore.setState({
+      elements: [{ id: "music", tag: "audio", start: 0, duration: 4, track: 0 }],
+    });
+    useAudioMetersVisible.setState({ visible: true });
+    const root = mountReactHarness(<AudioMeterStrip previewIframeRef={{ current: null }} />);
+    expect(document.querySelector('[data-testid="audio-meter-strip"]')).not.toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("runs the clipboard with no DOM edit session", async () => {
+    const toasts: string[] = [];
+    const options: UseClipboardOptions = {
+      projectId: "p",
+      activeCompPath: "index.html",
+      domEditSelectionRef: { current: null },
+      showToast: (message) => toasts.push(message),
+      writeProjectFile: async () => {},
+      recordEdit: async () => {},
+      reloadPreview: () => {},
+      handleTimelineElementsDelete: async () => {},
+      handleDomEditElementDelete: async () => {},
+      previewIframeRef: { current: null },
+      waitForPendingDomEditSaves: async () => {},
+    };
+    const api: { current: ReturnType<typeof useClipboard> | null } = { current: null };
+    function Harness() {
+      api.current = useClipboard(options);
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+    expect(api.current?.handleCopy()).toBe(false);
+    expect(toasts).toEqual(["Nothing selected to copy."]);
+    await act(async () => root.unmount());
+  });
+});