@hyperframes/studio 0.8.82 → 0.8.84

package/src/player/components/timelineClipDragGestureLifecycle.test.ts

@@ -11,86 +11,108 @@ afterEach(() => {
   usePlayerStore.getState().reset();
 });
 
+const element: TimelineElement = {
+  id: "clip-1",
+  tag: "div",
+  start: 0,
+  duration: 2,
+  track: 0,
+};
+
+function mountGesture(kind: "drag" | "resize") {
+  const drag: DraggedClipState = {
+    pointerId: 0,
+    element,
+    originClientX: 0,
+    originClientY: 0,
+    originScrollLeft: 0,
+    originScrollTop: 0,
+    pointerClientX: 0,
+    pointerClientY: 0,
+    pointerOffsetX: 0,
+    pointerOffsetY: 0,
+    previewStart: 1,
+    previewTrack: 0,
+    desiredTrack: 0,
+    insertRow: null,
+    snapTime: null,
+    snapType: null,
+    started: true,
+  };
+  const resize: ResizingClipState = {
+    pointerId: 0,
+    element,
+    edge: "end",
+    originClientX: 0,
+    previewStart: 0,
+    previewDuration: 3,
+    started: true,
+  };
+  const draggedClipRef = { current: kind === "drag" ? drag : null };
+  const resizingClipRef = { current: kind === "resize" ? resize : null };
+  const setDraggedClip = (next: SetStateAction<DraggedClipState | null>) => {
+    draggedClipRef.current = typeof next === "function" ? next(draggedClipRef.current) : next;
+  };
+  const updateDraggedClipPreview = vi.fn((previous: DraggedClipState) => ({
+    ...previous,
+    previewStart: 3,
+  }));
+  const onMoveElement = vi.fn();
+  const onResizeElement = vi.fn();
+  const updateElement = vi.fn();
+  const stopAutoScroll = vi.fn();
+  const cancelGestureRef = { current: () => false };
+  const dispose = mountTimelineClipDragGestureLifecycle({
+    lifecycleRef: { current: { kind, phase: "active", pointerId: null, sessionEpoch: 0 } },
+    sessionEpochRef: { current: 0 },
+    cancelGestureRef,
+    scrollRef: { current: null },
+    draggedClipRef,
+    resizingClipRef,
+    blockedClipRef: { current: null },
+    groupResizeRef: { current: null },
+    suppressClickRef: { current: false },
+    gestureSelectedKeysRef: { current: new Set() },
+    elementsRef: { current: [element] },
+    trackOrderRef: { current: [0] },
+    setDraggedClipState: setDraggedClip,
+    setResizingClipState: () => {},
+    setShowPopover: () => {},
+    setRangeSelectionRef: { current: null },
+    applyResizePointerRef: { current: () => {} },
+    syncClipDragAutoScrollRef: { current: () => {} },
+    stopClipDragAutoScrollRef: { current: stopAutoScroll },
+    updateDraggedClipPreviewRef: { current: updateDraggedClipPreview },
+    publishDraggedClip: setDraggedClip,
+    updateElement,
+    onMoveElementRef: { current: onMoveElement },
+    onMoveElementsRef: { current: undefined },
+    onResizeElementRef: { current: onResizeElement },
+    onResizeElementsRef: { current: undefined },
+    onBlockedEditAttemptRef: { current: undefined },
+    readZIndexRef: { current: undefined },
+    onStackingPatchesRef: { current: undefined },
+    refreshAfterLaneMoveRef: { current: undefined },
+  });
+  return {
+    draggedClipRef,
+    resizingClipRef,
+    updateDraggedClipPreview,
+    onMoveElement,
+    onResizeElement,
+    updateElement,
+    stopAutoScroll,
+    cancelGestureRef,
+    dispose,
+  };
+}
+
+const release = (clientX: number, clientY: number) =>
+  window.dispatchEvent(new MouseEvent("pointerup", { clientX, clientY }));
+
 describe("timeline clip drag gesture lifecycle", () => {
   it("finishes a drag after virtualization unmounts its source row", () => {
-    const element: TimelineElement = {
-      id: "clip-1",
-      tag: "div",
-      start: 0,
-      duration: 2,
-      track: 0,
-    };
-    const drag: DraggedClipState = {
-      pointerId: 0,
-      element,
-      originClientX: 0,
-      originClientY: 0,
-      originScrollLeft: 0,
-      originScrollTop: 0,
-      pointerClientX: 0,
-      pointerClientY: 0,
-      pointerOffsetX: 0,
-      pointerOffsetY: 0,
-      previewStart: 1,
-      previewTrack: 0,
-      desiredTrack: 0,
-      insertRow: null,
-      snapTime: null,
-      snapType: null,
-      started: true,
-    };
-    const draggedClipRef = { current: drag as DraggedClipState | null };
-    const resizingClipRef = { current: null as ResizingClipState | null };
-    const setDraggedClip = (next: SetStateAction<DraggedClipState | null>) => {
-      draggedClipRef.current = typeof next === "function" ? next(draggedClipRef.current) : next;
-    };
-    const updateDraggedClipPreview = vi.fn((previous: DraggedClipState) => ({
-      ...previous,
-      previewStart: 3,
-    }));
-    const onMoveElement = vi.fn();
-    const stopAutoScroll = vi.fn();
-    const cancelGestureRef = { current: () => false };
-    const dispose = mountTimelineClipDragGestureLifecycle({
-      lifecycleRef: {
-        current: {
-          kind: "drag",
-          phase: "active",
-          pointerId: null,
-          sessionEpoch: 0,
-        },
-      },
-      sessionEpochRef: { current: 0 },
-      cancelGestureRef,
-      scrollRef: { current: null },
-      draggedClipRef,
-      resizingClipRef,
-      blockedClipRef: { current: null },
-      groupResizeRef: { current: null },
-      suppressClickRef: { current: false },
-      gestureSelectedKeysRef: { current: new Set() },
-      elementsRef: { current: [element] },
-      trackOrderRef: { current: [0] },
-      setDraggedClipState: setDraggedClip,
-      setResizingClipState: () => {},
-      setShowPopover: () => {},
-      setRangeSelectionRef: { current: null },
-      applyResizePointerRef: { current: () => {} },
-      syncClipDragAutoScrollRef: { current: () => {} },
-      stopClipDragAutoScrollRef: { current: stopAutoScroll },
-      updateDraggedClipPreviewRef: { current: updateDraggedClipPreview },
-      publishDraggedClip: setDraggedClip,
-      updateElement: vi.fn(),
-      onMoveElementRef: { current: onMoveElement },
-      onMoveElementsRef: { current: undefined },
-      onResizeElementRef: { current: undefined },
-      onResizeElementsRef: { current: undefined },
-      onBlockedEditAttemptRef: { current: undefined },
-      readZIndexRef: { current: undefined },
-      onStackingPatchesRef: { current: undefined },
-      refreshAfterLaneMoveRef: { current: undefined },
-    });
-
+    const g = mountGesture("drag");
     const sourceRow = document.createElement("div");
     sourceRow.dataset.timelineRow = "";
     sourceRow.append(document.createElement("div"));
@@ -98,15 +120,49 @@ describe("timeline clip drag gesture lifecycle", () => {
     sourceRow.remove();
 
     window.dispatchEvent(new MouseEvent("pointermove", { clientX: 20, clientY: 10 }));
-    expect(updateDraggedClipPreview).toHaveBeenCalledTimes(1);
-    expect(draggedClipRef.current?.previewStart).toBe(3);
+    expect(g.updateDraggedClipPreview).toHaveBeenCalledTimes(1);
+    expect(g.draggedClipRef.current?.previewStart).toBe(3);
 
     window.dispatchEvent(new MouseEvent("pointerup"));
-    expect(onMoveElement).toHaveBeenCalledWith(element, { start: 3, track: 0 });
-    expect(draggedClipRef.current).toBeNull();
-    expect(stopAutoScroll).toHaveBeenCalledTimes(1);
+    expect(g.onMoveElement).toHaveBeenCalledWith(element, { start: 3, track: 0 });
+    expect(g.draggedClipRef.current).toBeNull();
+    expect(g.stopAutoScroll).toHaveBeenCalledTimes(1);
+
+    g.dispose();
+    expect(g.cancelGestureRef.current()).toBe(false);
+  });
+
+  it.each([
+    ["above the window", 20, -40],
+    ["past the window's right edge", window.innerWidth + 40, 10],
+    ["on the window's right edge", window.innerWidth, 10],
+    ["on the window's bottom edge", 20, window.innerHeight],
+  ])("cancels a drag released %s and leaves the clip where it was", (_, clientX, clientY) => {
+    const g = mountGesture("drag");
+    window.dispatchEvent(new MouseEvent("pointermove", { clientX: 20, clientY: 10 }));
+    release(clientX, clientY);
+    expect(g.onMoveElement).not.toHaveBeenCalled();
+    expect(g.updateElement).not.toHaveBeenCalled();
+    expect(g.draggedClipRef.current).toBeNull();
+    // The cancel ended the gesture, so a later release has nothing to commit.
+    release(20, 10);
+    expect(g.onMoveElement).not.toHaveBeenCalled();
+    g.dispose();
+  });
+
+  it("cancels a trim released outside the window", () => {
+    const g = mountGesture("resize");
+    release(20, -40);
+    expect(g.onResizeElement).not.toHaveBeenCalled();
+    expect(g.updateElement).not.toHaveBeenCalled();
+    expect(g.resizingClipRef.current).toBeNull();
+    g.dispose();
+  });
 
-    dispose();
-    expect(cancelGestureRef.current()).toBe(false);
+  it("still commits a drag released on the window's last pixel", () => {
+    const g = mountGesture("drag");
+    release(window.innerWidth - 1, window.innerHeight - 1);
+    expect(g.onMoveElement).toHaveBeenCalledWith(element, { start: 1, track: 0 });
+    g.dispose();
   });
 });

package/src/player/components/timelineClipDragGestureLifecycle.ts

@@ -8,6 +8,7 @@ import type {
 } from "./timelineClipDragTypes";
 import type { TimelineGroupResizeSession } from "./timelineGroupEditing";
 import { commitTimelineGroupResize } from "./timelineGroupResizeCommit";
+import { releasedOutsideWindow } from "./timelinePointerRelease";
 import {
   beginTimelineOptimisticGesture,
   rollbackLatestTimelineOptimisticGesture,
@@ -349,6 +350,7 @@ export function mountTimelineClipDragGestureLifecycle({
   };
 
   const handleWindowPointerUp = (event: PointerEvent) => {
+    if (releasedOutsideWindow(event)) return handleWindowPointerCancel(event);
     const claimed = claimActiveGesture(event);
     if (claimed === "ignored") return;
     if (claimed) {

package/src/player/components/timelinePointerRelease.ts

@@ -0,0 +1,4 @@
+export function releasedOutsideWindow(point: Pick<MouseEvent, "clientX" | "clientY">): boolean {
+  const { clientX: x, clientY: y } = point;
+  return x < 0 || y < 0 || x >= window.innerWidth || y >= window.innerHeight;
+}

package/src/player/components/useTimelineProviderState.tsx

@@ -71,6 +71,8 @@ export function useTimelineProviderState({
   canPasteClip,
   theme: themeOverrides,
   sessionEpoch = 0,
+  previewIframeRef,
+  onZIndexReorder,
 }: TimelineProps = {}): TimelineContextValue {
   const {
     onMoveElement,
@@ -184,6 +186,8 @@ export function useTimelineProviderState({
   });
   const { readClipZIndex, applyStackingPatches, zSyncEnabled } = useTimelineStackingSync({
     expandedElementsRef: timelineElementsRef,
+    previewIframeRef,
+    onZIndexReorder,
   });
   const {
     draggedClip,

package/src/player/components/useTimelineStackingSync.test.tsx

@@ -73,4 +73,50 @@ describe("useTimelineStackingSync", () => {
     mocks.actions = null;
     iframe.remove();
   });
+
+  it("uses a host's iframe and commit over Studio's own", async () => {
+    const studioCommit = vi.fn().mockResolvedValue(undefined);
+    mocks.actions = {
+      previewIframeRef: { current: null },
+      handleDomZIndexReorderCommit: studioCommit,
+    };
+    const iframe = document.createElement("iframe");
+    document.body.appendChild(iframe);
+    const node = iframe.contentDocument!.createElement("div");
+    node.id = "a";
+    iframe.contentDocument!.body.appendChild(node);
+    const hostCommit = vi.fn().mockResolvedValue(undefined);
+    const element: TimelineElement = {
+      id: "a",
+      key: "a",
+      tag: "div",
+      start: 0,
+      duration: 2,
+      track: 0,
+    };
+    let sync: ReturnType<typeof useTimelineStackingSync> | null = null;
+    function Harness() {
+      sync = useTimelineStackingSync({
+        expandedElementsRef: { current: [element] },
+        previewIframeRef: { current: iframe },
+        onZIndexReorder: hostCommit,
+      });
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+
+    await act(async () => {
+      await sync!.applyStackingPatches([{ key: "a", zIndex: 3 }]);
+    });
+
+    expect(sync!.zSyncEnabled).toBe(true);
+    expect(hostCommit).toHaveBeenCalledWith(
+      [expect.objectContaining({ element: node, zIndex: 3 })],
+      undefined,
+    );
+    expect(studioCommit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+    mocks.actions = null;
+    iframe.remove();
+  });
 });

package/src/player/components/useTimelineStackingSync.ts

@@ -5,23 +5,30 @@ import { useStudioShellContextOptional } from "../../contexts/StudioContext";
 import { findElementForSelection } from "../../components/editor/domEditingElement";
 import { readEffectiveZIndex } from "../../components/editor/canvasContextMenuZOrder";
 import type { StackingPatch } from "./timelineStackingSync";
+import type { TimelineZIndexReorderCommit } from "../../hooks/useTimelineEditingTypes";
 
-interface UseTimelineStackingSyncInput {
+/** With both set, a lane move restacks the preview's z-index to match the rows; each overrides Studio's own. */
+export interface TimelineStackingSyncProps {
+  previewIframeRef?: RefObject<HTMLIFrameElement | null>;
+  onZIndexReorder?: TimelineZIndexReorderCommit;
+}
+
+interface UseTimelineStackingSyncInput extends TimelineStackingSyncProps {
   expandedElementsRef: RefObject<TimelineElement[]>;
 }
 
-// Lane ↔ stacking unification (research/STAGE3-NEEDED-WIRING.md). Provision the
-// two deps commitDraggedClipMove accepts so a lane-change drag also patches the
-// edited clip's z-index. Both read the SAME preview iframe + z-order persist path
-// the canvas right-click menu / LayersPanel use, so a timeline lane move and a
-// menu z-edit produce one shared inline-style commit shape. Optional contexts:
-// outside the NLE (standalone <Timeline>) these are null ⇒ deps undefined ⇒ the
-// commit's z-sync is a no-op (backward compatible).
-export function useTimelineStackingSync({ expandedElementsRef }: UseTimelineStackingSyncInput) {
+// Lane ↔ stacking sync: the two deps commitDraggedClipMove takes so a lane-change drag also patches
+// z-index, through the same iframe + z persist path the canvas menu and LayersPanel use. Either missing ⇒ no-op.
+export function useTimelineStackingSync({
+  expandedElementsRef,
+  previewIframeRef,
+  onZIndexReorder,
+}: UseTimelineStackingSyncInput) {
   const domEditActions = useDomEditActionsContextOptional();
   const shell = useStudioShellContextOptional();
-  const zSyncPreviewIframeRef = domEditActions?.previewIframeRef ?? null;
-  const handleDomZIndexReorderCommit = domEditActions?.handleDomZIndexReorderCommit;
+  const zSyncPreviewIframeRef = previewIframeRef ?? domEditActions?.previewIframeRef ?? null;
+  const handleDomZIndexReorderCommit =
+    onZIndexReorder ?? domEditActions?.handleDomZIndexReorderCommit;
   const zSyncActiveCompPath = shell?.activeCompPath ?? null;
 
   // Resolve a TimelineElement to its live iframe HTMLElement via the same

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

@@ -13,6 +13,7 @@ describe("timelineElementsChanged", () => {
     ["audio group hidden", { audioGroupHidden: true }],
     ["fade in", { fadeIn: 1 }],
     ["fade out", { fadeOut: 1 }],
+    ["source (re-pointed at its preview copy)", { src: "clip1.mp4?hf-proxy=h264" }],
   ])("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

@@ -15,6 +15,7 @@ const RENDERED_FIELDS: readonly (keyof TimelineElement)[] = [
   "audioGroupHidden",
   "fadeIn",
   "fadeOut",
+  "src",
 ];
 
 /** Whether a derived timeline changes any field that affects rendering. */

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

@@ -9,7 +9,11 @@ import {
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
 import { computeResizePreview } from "../components/timelineClipDragPreview";
 import type { TimelineElement } from "../store/playerStore";
-import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+import {
+  MAX_PLAYBACK_RATE,
+  MIN_PLAYBACK_RATE,
+  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 };
@@ -269,19 +273,49 @@ describe("group info cache", () => {
 
 describe("parseTimelineFromDOM — canonical playback rate", () => {
   it.each([
-    ["10", 5],
-    ["0.01", 0.1],
-  ])("clamps authored rate %s to %s for trim and split math", (authored, expected) => {
-    const doc = makeDoc(`
+    ["8", 8],
+    ["10", MAX_PLAYBACK_RATE],
+    ["50", MAX_PLAYBACK_RATE],
+    ["0.01", MIN_PLAYBACK_RATE],
+  ])(
+    "clamps authored rate %s to %s, as playback does, for trim and split math",
+    (authored, expected) => {
+      const doc = makeDoc(`
       <div data-composition-id="root">
         <div id="nested" class="clip" data-composition-src="scene.html"
           data-start="0" data-duration="5" data-playback-rate="${authored}"></div>
       </div>
     `);
 
-    const nested = parseTimelineFromDOM(doc, 10).find((entry) => entry.domId === "nested");
+      const nested = parseTimelineFromDOM(doc, 10).find((entry) => entry.domId === "nested");
+
+      expect(nested?.playbackRate).toBe(expected);
+    },
+  );
+});
 
-    expect(nested?.playbackRate).toBe(expected);
+describe("parseTimelineFromDOM — head trim at an authored speed above 5x", () => {
+  it("moves the in-point by the speed playback uses", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root">
+        <video id="v" class="clip" data-start="2" data-duration="4" data-media-start="1"
+          data-playback-rate="8"></video>
+      </div>
+    `);
+    const element = parseTimelineFromDOM(doc, 10).find((e) => e.domId === "v")!;
+    const preview = computeResizePreview(
+      {
+        element,
+        edge: "start",
+        originClientX: 0,
+        previewStart: 2,
+        previewDuration: 4,
+        started: true,
+      },
+      100,
+      { scroll: null, pps: 100, buildSnapTargets: () => [] },
+    );
+    expect([preview.previewStart, preview.previewPlaybackStart]).toEqual([3, 9]);
   });
 });
 

package/src/player/lib/timelineElementHelpers.ts

@@ -13,7 +13,11 @@ 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 { type AttrReader, readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+import {
+  type AttrReader,
+  clampPlaybackRate,
+  readMediaOffsetSeconds,
+} from "@hyperframes/parsers/media-duration";
 
 // ---------------------------------------------------------------------------
 // Layer-reveal lift transparency
@@ -79,10 +83,6 @@ function readDurationAttribute(el: Element | null | undefined): number {
   return isFinitePositive(duration) ? duration : 0;
 }
 
-function normalizePlaybackRate(raw: number): number {
-  return Number.isFinite(raw) && raw > 0 ? Math.max(0.1, Math.min(5, raw)) : 1;
-}
-
 export function isTimelineIgnoredElement(el: Element): boolean {
   // An `<hf-audio-group>` is a mixer bus with no timing of its own, drawn as a group row, never a clip.
   if (el.tagName.toLowerCase() === HF_AUDIO_GROUP_TAG) return true;
@@ -199,7 +199,7 @@ function applyPlaybackMetadataFromElement(entry: TimelineElement, el: Element):
 
   const authoredPlaybackRate = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
   if (Number.isFinite(authoredPlaybackRate) && authoredPlaybackRate > 0) {
-    entry.playbackRate = normalizePlaybackRate(authoredPlaybackRate);
+    entry.playbackRate = clampPlaybackRate(authoredPlaybackRate);
   }
 }
 
@@ -262,7 +262,7 @@ export function applyMediaMetadataFromElement(entry: TimelineElement, el: Elemen
 
   const playbackRate = mediaEl.defaultPlaybackRate;
   if (entry.playbackRate == null && Number.isFinite(playbackRate) && playbackRate > 0) {
-    entry.playbackRate = normalizePlaybackRate(playbackRate);
+    entry.playbackRate = clampPlaybackRate(playbackRate);
   }
 }
 

package/src/playerEntry.ts

@@ -0,0 +1 @@
+export { Player } from "./player/components/Player";

package/src/timelineStackingSyncExport.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+// Mounts the timeline by package name with no Studio shell, as a host app does.
+import { act } from "react";
+import { expect, it, vi } from "vitest";
+import { Timeline, usePlayerStore, type TimelineZIndexReorderCommit } from "@hyperframes/studio";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+
+installReactActEnvironment();
+// happy-dom has no layout; the timeline only renders clips inside a sized viewport.
+for (const [prop, px] of [
+  ["clientWidth", 1000],
+  ["clientHeight", 400],
+  ["offsetWidth", 1000],
+  ["offsetHeight", 400],
+] as const) {
+  vi.spyOn(HTMLElement.prototype, prop, "get").mockReturnValue(px);
+}
+
+const settle = () => act(async () => new Promise((r) => setTimeout(r, 50)));
+const pointer = (type: string, clientY: number) =>
+  new PointerEvent(type, { bubbles: true, button: 0, pointerId: 1, clientX: 150, clientY });
+
+it("restacks the host's preview when a lane move puts a clip below another", async () => {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const doc = iframe.contentDocument!;
+  // No authored z: DOM order paints tag over title, which matches the rows until the move.
+  doc.body.innerHTML = '<div id="title"></div><div id="tag"></div><div id="note"></div>';
+  const clip = (id: string, start: number, duration: number, track: number) =>
+    ({ id, key: id, domId: id, tag: "div", start, duration, track }) as const;
+  usePlayerStore.setState({
+    duration: 10,
+    timelineReady: true,
+    elements: [clip("title", 0, 4, 1), clip("tag", 0, 4, 0), clip("note", 6, 2, 2)],
+  });
+  const commit = vi.fn<TimelineZIndexReorderCommit>(async (entries) => {
+    for (const e of entries) e.element.style.zIndex = String(e.zIndex);
+  });
+  const root = mountReactHarness(
+    <Timeline
+      previewIframeRef={{ current: iframe }}
+      onZIndexReorder={commit}
+      onMoveElement={async () => {}}
+      onMoveElements={async () => {}}
+    />,
+  );
+  await settle();
+  const tagClip = document.querySelector<HTMLElement>('.timeline-clip[aria-label^="tag,"]')!;
+  vi.spyOn(tagClip, "getBoundingClientRect").mockReturnValue(new DOMRect(80, 77, 360, 42));
+
+  // Drag tag from the top row to the bottom row, clear of note in time.
+  act(() => void tagClip.dispatchEvent(pointer("pointerdown", 98)));
+  act(() => {
+    window.dispatchEvent(pointer("pointermove", 140));
+    window.dispatchEvent(pointer("pointermove", 194));
+  });
+  await act(async () => void window.dispatchEvent(pointer("pointerup", 194)));
+  await settle();
+
+  expect(usePlayerStore.getState().elements.find((e) => e.id === "tag")?.track).toBe(2);
+  expect(commit).toHaveBeenCalledTimes(1);
+  expect(commit.mock.calls[0]![0].every((e) => e.element.ownerDocument === doc)).toBe(true);
+  const z = (id: string) => Number(doc.getElementById(id)!.style.zIndex || 0);
+  expect(z("title")).toBeGreaterThan(z("tag"));
+  await act(async () => root.unmount());
+  usePlayerStore.setState({ elements: [], timelineReady: false });
+});

package/src/ui.ts

@@ -0,0 +1,31 @@
+export { Button, buttonBase, buttonSizes, buttonVariants } from "./components/ui/Button";
+export type { ButtonSize, ButtonVariant, PreviewState } from "./components/ui/Button";
+export { HyperframesLogo } from "./components/ui/HyperframesLogo";
+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 {
+  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";

package/src/utils/mediaTypes.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { AUDIO_EXT, IMAGE_EXT, isMediaFile, MEDIA_EXT, VIDEO_EXT } from "./mediaTypes";
+import { getTimelineAssetKind } from "./timelineAssetDrop";
+
+describe("media types", () => {
+  it.each([
+    ["clip.m4v", "video"],
+    ["assets/Take 2.M4V", "video"],
+    ["song.flac", "audio"],
+    ["voice.FLAC", "audio"],
+    ["clip.mp4", "video"],
+    ["music.mp3", "audio"],
+    ["still.png", "image"],
+  ] as const)("the timeline takes %s as %s", (path, kind) => {
+    expect(getTimelineAssetKind(path)).toBe(kind);
+    expect(isMediaFile(path)).toBe(true);
+  });
+
+  it("still refuses files that are not media", () => {
+    for (const path of ["notes.pdf", "font.woff2", "grade.cube", "clip.m4v.txt", "flac"]) {
+      expect(getTimelineAssetKind(path)).toBeNull();
+      expect(isMediaFile(path)).toBe(false);
+    }
+  });
+
+  it("counts a file as media exactly when it is an image, video or audio file", () => {
+    const paths = ["a.mp4", "a.m4v", "a.flac", "a.png", "a.ico", "a.woff", "a.pdf", "a.cube"];
+    for (const path of paths) {
+      const kinds = [IMAGE_EXT, VIDEO_EXT, AUDIO_EXT].filter((re) => re.test(path)).length;
+      expect(MEDIA_EXT.test(path)).toBe(kinds > 0);
+    }
+  });
+});

package/src/utils/mediaTypes.ts

@@ -1,10 +1,17 @@
-export const IMAGE_EXT = /\.(jpg|jpeg|png|gif|webp|avif|svg|ico)$/i;
-export const VIDEO_EXT = /\.(mp4|webm|mov)$/i;
-export const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i;
+const IMAGE_EXTS = ["jpg", "jpeg", "png", "gif", "webp", "avif", "svg", "ico"];
+const VIDEO_EXTS = ["mp4", "webm", "mov", "m4v"];
+const AUDIO_EXTS = ["mp3", "wav", "ogg", "m4a", "aac", "flac"];
+
+function extensionPattern(extensions: readonly string[]): RegExp {
+  return new RegExp(`\\.(${extensions.join("|")})$`, "i");
+}
+
+export const IMAGE_EXT = extensionPattern(IMAGE_EXTS);
+export const VIDEO_EXT = extensionPattern(VIDEO_EXTS);
+export const AUDIO_EXT = extensionPattern(AUDIO_EXTS);
 export const FONT_EXT = /\.(woff|woff2|ttf|ttc|otf|eot)$/i;
 export const LUT_EXT = /\.cube$/i;
-export const MEDIA_EXT =
-  /\.(mp4|webm|mov|mp3|wav|ogg|m4a|aac|jpg|jpeg|png|gif|webp|avif|svg|ico)$/i;
+export const MEDIA_EXT = extensionPattern([...VIDEO_EXTS, ...AUDIO_EXTS, ...IMAGE_EXTS]);
 
 export function isMediaFile(path: string): boolean {
   return MEDIA_EXT.test(path);