@hyperframes/studio 0.8.57 → 0.8.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.57",
+  "version": "0.8.58",
   "description": "",
   "repository": {
     "type": "git",
@@ -51,11 +51,11 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.57",
-    "@hyperframes/player": "0.8.57",
-    "@hyperframes/parsers": "0.8.57",
-    "@hyperframes/sdk": "0.8.57",
-    "@hyperframes/studio-server": "0.8.57"
+    "@hyperframes/core": "0.8.58",
+    "@hyperframes/parsers": "0.8.58",
+    "@hyperframes/studio-server": "0.8.58",
+    "@hyperframes/sdk": "0.8.58",
+    "@hyperframes/player": "0.8.58"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -71,7 +71,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.57"
+    "@hyperframes/producer": "0.8.58"
   },
   "peerDependencies": {
     "react": "19",

package/src/components/editor/MotionPathOverlay.test.tsx

@@ -52,7 +52,6 @@ it("re-evaluates set-destination availability when a reload swaps the live ifram
     expect(usePlayerStore.getState().motionPathCreateAvailable).toBe(false);
 
     act(() => {
-      ref.current = after;
       usePreviewIframeStore.getState().setIframe(after);
     });
     expect(usePlayerStore.getState().motionPathCreateAvailable).toBe(true);

package/src/components/nle/NLEContext.tsx

@@ -1,7 +1,7 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 import { useContext, useState, useCallback, useRef, useEffect, type ReactNode } from "react";
-import { useTimelinePlayer, usePlayerStore } from "../../player";
-import type { TimelineElement } from "../../player";
+import { useTimelinePlayer } from "../../player/hooks/useTimelinePlayer";
+import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
 import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { useCompositionStack } from "./useCompositionStack";
@@ -18,6 +18,8 @@ export interface NLEContextValue {
   projectId: string;
   // player (from useTimelinePlayer — single instance for the whole shell)
   iframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  play: () => void;
+  pause: () => void;
   togglePlay: () => void;
   seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
   refreshPlayer: () => void;
@@ -84,6 +86,8 @@ export function NLEProvider({
   const containerRef = useRef<HTMLDivElement>(null);
   const {
     iframeRef,
+    play,
+    pause,
     togglePlay,
     seek,
     onIframeLoad: baseOnIframeLoad,
@@ -298,6 +302,8 @@ export function NLEProvider({
   const value: NLEContextValue = {
     projectId,
     iframeRef,
+    play,
+    pause,
     containerRef,
     togglePlay,
     seek,

package/src/components/nle/NLEPreview.test.ts

@@ -261,6 +261,7 @@ describe("NLEPreview", () => {
     expect(players[0].style.clipPath).toBe("");
     expect(players[1].style.clipPath).toBe("inset(100%)");
     expect(players[1].style.visibility).toBe("hidden");
+    expect(players[1].style.pointerEvents).toBe("none");
     view.cleanup();
   });
 

package/src/components/nle/useCompositionStack.ts

@@ -1,7 +1,7 @@
 import { buildProjectApiPath } from "../../utils/projectRouting";
 // Composition drill-down stack management for NLEContext/EditorShell
 import { useState, useCallback, useRef, useEffect } from "react";
-import { usePlayerStore } from "../../player";
+import { usePlayerStore } from "../../player/store/playerStore";
 import type { CompositionLevel } from "./CompositionBreadcrumb";
 import { encodePreviewPath } from "../../player/components/thumbnailUtils";
 

package/src/hooks/useCompositionDimensions.test.tsx

@@ -71,7 +71,6 @@ it("re-reads the size from the promoted iframe's document", () => {
     act(() => root.render(<Harness />));
     expect(host.textContent).toBe('{"width":1920,"height":1080}');
     act(() => {
-      ref.current = b;
       usePreviewIframeStore.getState().setIframe(b);
     });
     expect(host.textContent).toBe('{"width":1080,"height":1920}');

package/src/hooks/useSdkSession.lifecycle.test.tsx

@@ -267,6 +267,34 @@ describe("useSdkSession unavailable telemetry", () => {
     await act(async () => root.unmount());
   });
 
+  // A fetch that REJECTS produces no response at all. It used to escape this
+  // function and be caught by the effect's outer `.catch`, which reported it as
+  // `stage: "open"` — a label that means openComposition threw. Every `stage:
+  // open` event on 0.8.56/0.8.57 carries a fetch-rejection message, so the
+  // largest failure class was a network problem reported as a parser one and
+  // was unaddressable in that bucket.
+  it("reports a rejected request as a read failure, not an open failure", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new TypeError("Failed to fetch");
+      }),
+    );
+    const root = createRoot(document.createElement("div"));
+    await act(async () => root.render(<Probe projectId="project-a" />));
+    await flushAsyncEffects();
+
+    expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "read",
+      reason: "network",
+    });
+    expect(trackMock).not.toHaveBeenCalledWith("sdk_session_unavailable", {
+      stage: "open",
+      error: expect.anything(),
+    });
+    await act(async () => root.unmount());
+  });
+
   it("separates an unexpected response shape from a failed request", async () => {
     vi.stubGlobal(
       "fetch",

package/src/hooks/useSdkSession.ts

@@ -16,12 +16,23 @@ import { addExternalFileReloadListener } from "./externalFileReloadBus";
  *
  * Every reason lives in this union so the full surface is readable from one
  * place — `absent_or_empty` included, even though it is a 2xx.
+ *
+ * `network` is a fetch that REJECTED — the request never produced a response.
+ * It was not in this union until 2026-09-21, so it escaped `readProjectFileOptional`
+ * and was caught by the effect's outer `.catch`, landing in `stage: "open"`.
+ * That label means `openComposition` threw (unparseable composition, OOM), and
+ * it is what the largest failure class was reported as. Every `stage: open`
+ * event measured on 0.8.56 and 0.8.57 carries a fetch-rejection message —
+ * "Failed to fetch", "Load failed", "NetworkError when attempting to fetch
+ * resource." — so the class was a network problem filed under a parser one, and
+ * unaddressable in that bucket.
  */
 type ProjectFileReadFailure =
   | { ok: false; reason: "unsafe_path" }
   | { ok: false; reason: "http_error"; status: number }
   | { ok: false; reason: "missing_content" }
-  | { ok: false; reason: "absent_or_empty" };
+  | { ok: false; reason: "absent_or_empty" }
+  | { ok: false; reason: "network" };
 
 type ProjectFileReadResult = { ok: true; content: string } | ProjectFileReadFailure;
 
@@ -68,9 +79,20 @@ async function readProjectFileOptional(
   // and closes the CodeQL client-side-request-forgery flag). encodeURIComponent
   // already confines both values to single segments of this same-origin URL.
   if (path.includes("\0") || path.includes("..")) return { ok: false, reason: "unsafe_path" };
-  const res = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
-  );
+  let res: Response;
+  try {
+    res = await fetch(
+      `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}?optional=1`,
+    );
+  } catch {
+    // The request never produced a response: offline, the dev server gone, a
+    // CSP/Private-Network-Access block, or an extension rewriting fetch. Caught
+    // here so it is reported as a READ failure — left to propagate, the effect's
+    // outer catch reported it as `stage: "open"`, which claims the composition
+    // failed to parse. Every `stage: open` event before this change was this
+    // branch, so the label made the largest class unaddressable.
+    return { ok: false, reason: "network" };
+  }
   if (!res.ok) return { ok: false, reason: "http_error", status: res.status };
   const data = (await res.json()) as { content?: string };
   // `optional=1` answers a missing file with 200 + `content: ""`, so a
@@ -299,6 +321,11 @@ export function useSdkSession(
           // openComposition threw (unparseable composition, OOM) — same total
           // bypass as the read failure above, but this one is a real defect
           // rather than a missing file. Carry the message; it is the only clue.
+          //
+          // A rejected read no longer reaches here: `readProjectFileOptional`
+          // catches its own fetch rejection and answers `reason: "network"`, so
+          // this stage now means what it says. Before that, every event in this
+          // bucket was a network error wearing a parser's label.
           trackStudioEvent("sdk_session_unavailable", {
             stage: "open",
             error: error instanceof Error ? error.message : String(error),

package/src/index.ts

@@ -46,12 +46,20 @@ export {
   VideoThumbnail,
   CompositionThumbnail,
   useTimelinePlayer,
+  usePlayerHandle,
   resolveIframe,
   usePlayerStore,
   liveTime,
   formatTime,
 } from "./player";
-export type { TimelineElement, TimelineTimeRange } from "./player";
+export type {
+  PlayerHandle,
+  PlayerHandleElement,
+  PlayerHandleListener,
+  PlayerHandleTimeListener,
+  TimelineElement,
+  TimelineTimeRange,
+} from "./player";
 
 // Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
 export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";

package/src/player/components/LayerDisclosureRow.tsx

@@ -95,9 +95,9 @@ export function LayerDisclosureRow({
       <span aria-hidden="true" className="shrink-0 text-[13px] leading-none text-white/40">
         ◇
       </span>
-      {/* Wraps rather than truncating: a truncated name needs a hover to be
-          read, which a scanned column cannot rely on. */}
-      <span className="min-w-0 flex-1 wrap-break-word font-medium leading-tight">{name}</span>
+      <span title={name} className="min-w-0 flex-1 truncate font-medium leading-tight">
+        {name}
+      </span>
       <TrackClipCount clipCount={clipCount} />
       {children}
       {/* Anchored right, on every header that has one: the lane toggle is the

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

@@ -85,6 +85,8 @@ async function mountPlayer(props: Partial<PlayerProps> = {}) {
 
 const twoFrames = () => act(async () => void (await new Promise((r) => setTimeout(r, 80))));
 
+const flushEffects = () => act(async () => await Promise.resolve());
+
 function createAudioIframe() {
   const iframe = document.createElement("iframe");
   document.body.appendChild(iframe);
@@ -216,6 +218,38 @@ describe("ready to show", () => {
   const painted = (player: TestHyperframesPlayer) =>
     act(() => void player.dispatchEvent(new Event("painted")));
 
+  it("waits two animation frames before notifying that the preview can show", async () => {
+    const callbacks: FrameRequestCallback[] = [];
+    const requestAnimationFrame = vi
+      .spyOn(window, "requestAnimationFrame")
+      .mockImplementation((callback) => {
+        callbacks.push(callback);
+        return callbacks.length;
+      });
+    try {
+      const onReadyToShowChange = vi.fn();
+      const { player } = await mountPlayer({ onReadyToShowChange });
+      const el = player as TestHyperframesPlayer;
+
+      loadAndReady(el);
+      painted(el);
+      await flushEffects();
+      expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+      expect(callbacks).toHaveLength(1);
+
+      act(() => callbacks.shift()?.(0));
+      await flushEffects();
+      expect(onReadyToShowChange).not.toHaveBeenCalledWith(true);
+      expect(callbacks).toHaveLength(1);
+
+      act(() => callbacks.shift()?.(16));
+      await flushEffects();
+      expect(onReadyToShowChange).toHaveBeenLastCalledWith(true);
+    } finally {
+      requestAnimationFrame.mockRestore();
+    }
+  });
+
   it("promotes only once the player reports painted, not at ready or assetsready", async () => {
     const onReadyToShowChange = vi.fn();
     const { player } = await mountPlayer({ onReadyToShowChange });

package/src/player/components/TimelineGroupHeader.tsx

@@ -65,9 +65,9 @@ function GroupNameButton({
       <span aria-hidden="true" className="shrink-0 text-[12px] leading-none text-white/50">
         ▤
       </span>
-      {/* Wraps rather than truncating — a name that needs a hover to be read
-          is no use in a column you scan. */}
-      <span className="min-w-0 wrap-break-word text-left font-medium leading-tight">{label}</span>
+      <span title={label} className="min-w-0 truncate text-left font-medium leading-tight">
+        {label}
+      </span>
       <span
         className="shrink-0 rounded-full bg-white/10 px-1 text-[9px] leading-[14px] tabular-nums text-white/55"
         aria-hidden="true"
@@ -109,9 +109,7 @@ export function TimelineGroupHeader({
       }}
     >
       {/* One line, like a track header's: caret and name, then every control
-          anchored to the right edge. The name wraps and the controls are
-          `shrink-0`, so they hold the edge and the name gives way — no second
-          line needed to keep five controls off the label. */}
+          anchored to the right edge. */}
       <button
         type="button"
         tabIndex={-1}

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

@@ -136,4 +136,14 @@ describe("PlainTrackHeader", () => {
     expect(labelOf(view.host)).toBe("Hide track 1");
     view.unmount();
   });
+
+  it("truncates long names and keeps the full name in the tooltip", () => {
+    const name = "A-very-long-unbroken-clip-name-for-the-timeline";
+    const view = renderHeader({ trackLabel: name });
+    const label = view.host.querySelector("span[title]");
+    expect(label?.className).toContain("truncate");
+    expect(label?.className).not.toContain("wrap-break-word");
+    expect(label?.getAttribute("title")).toBe(name);
+    view.unmount();
+  });
 });

package/src/player/components/TimelineTrackPlainHeader.tsx

@@ -93,14 +93,11 @@ export function PlainTrackHeader({
         )}
         {/* No `flex-1`: the name takes only the width it needs, so the clip
             count sits against it rather than being pushed out to meet the
-            controls. The slack goes to the `ml-auto` group below instead.
-
-            Wraps rather than truncating: a truncated name needs a hover to be
-            read at all, and a tooltip is no use to a name you are scanning a
-            column of. `wrap-break-word` so a long single token breaks instead of
-            forcing the column wider. */}
+            controls. The slack goes to the `ml-auto` group below instead. */}
         {showTrackLabel && (
-          <span className="min-w-0 wrap-break-word text-[11px] leading-tight">{trackLabel}</span>
+          <span title={trackLabel} className="min-w-0 truncate text-[11px] leading-tight">
+            {trackLabel}
+          </span>
         )}
         {showTrackLabel && <TrackClipCount clipCount={clipCount} />}
         {/* `ml-auto` is what anchors the group right: it absorbs the slack the

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

@@ -0,0 +1,41 @@
+// @vitest-environment happy-dom
+
+import { describe, expect, it, vi } from "vitest";
+import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
+
+function timeline(duration: number) {
+  return {
+    duration: vi.fn(() => duration),
+    time: vi.fn(() => 0),
+    seek: vi.fn(),
+    play: vi.fn(),
+    pause: vi.fn(),
+    isActive: vi.fn(() => false),
+  };
+}
+
+describe("resolvePlaybackAdapter", () => {
+  it("uses the __timelines key matching the document root, not the first key", () => {
+    const first = timeline(12);
+    const second = timeline(12);
+    const third = timeline(12);
+    const iframe = document.createElement("iframe");
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML = '<div data-composition-id="second" data-duration="10"></div>';
+    Object.defineProperty(iframe, "contentDocument", { configurable: true, value: doc });
+    const win = {
+      __timelines: { first, second, third },
+    } as never;
+
+    const adapter = resolvePlaybackAdapter(iframe, win, {
+      cache: { current: null },
+      warned: { current: false },
+    });
+
+    expect(adapter).not.toBeNull();
+    adapter?.seek(7);
+    expect(second.seek).toHaveBeenCalledWith(7);
+    expect(first.seek).not.toHaveBeenCalled();
+    expect(third.seek).not.toHaveBeenCalled();
+  });
+});

package/src/player/hooks/usePlayerHandle.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment happy-dom
+
+import React, { useEffect } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
+import { liveTime, usePlayerStore } from "../store/playerStore";
+import { makeAdapterWindow, makeFakeIframe } from "./timelinePlayerTestHarness";
+import { usePlayerHandle, type PlayerHandle } from "./usePlayerHandle";
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
+
+function renderHandle() {
+  let latest: PlayerHandle | null = null;
+  let context: NLEContextValue | null = null;
+  let renders = 0;
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  act(() => {
+    root.render(
+      <NLEProvider projectId="player-handle-test">
+        <HandleHarness
+          onContext={(value) => (context = value)}
+          onValue={(value) => (latest = value)}
+          onRender={() => renders++}
+        />
+      </NLEProvider>,
+    );
+  });
+  if (!latest || !context) throw new Error("usePlayerHandle did not mount");
+  return {
+    root,
+    getHandle: () => latest as PlayerHandle,
+    getContext: () => context as NLEContextValue,
+    getRenderCount: () => renders,
+  };
+}
+
+function HandleHarness({
+  onContext,
+  onValue,
+  onRender,
+}: {
+  onContext: (value: NLEContextValue) => void;
+  onValue: (value: PlayerHandle) => void;
+  onRender: () => void;
+}) {
+  onRender();
+  const context = useNLEContext();
+  const handle = usePlayerHandle();
+  useEffect(() => {
+    onContext(context);
+    onValue(handle);
+  }, [context, handle, onContext, onValue]);
+  return null;
+}
+
+afterEach(() => {
+  usePlayerStore.getState().reset();
+  document.body.innerHTML = "";
+});
+
+describe("usePlayerHandle", () => {
+  it("refuses seek before readiness and notifies structural changes independently", () => {
+    const { root, getHandle } = renderHandle();
+    const handle = getHandle();
+
+    expect(handle.ready).toBe(false);
+    expect(handle.seek(4)).toBe(false);
+
+    const structuralListener = vi.fn();
+    const unsubscribe = handle.subscribe(structuralListener);
+    act(() => usePlayerStore.setState({ timelineReady: true }));
+    expect(structuralListener).toHaveBeenCalledTimes(1);
+    act(() => usePlayerStore.setState({ duration: 8 }));
+    expect(structuralListener).toHaveBeenCalledTimes(2);
+    act(() =>
+      usePlayerStore.setState({
+        elements: [
+          {
+            id: "clip",
+            tag: "div",
+            start: 2,
+            duration: 3,
+            track: 0,
+            selector: "#clip",
+            sourceFile: "index.html",
+            compositionSrc: "compositions/intro.html",
+          },
+        ],
+      }),
+    );
+    expect(structuralListener).toHaveBeenCalledTimes(3);
+    expect(getHandle().elements).toEqual([
+      {
+        id: "clip",
+        start: 2,
+        end: 5,
+        selector: "#clip",
+        sourceFile: "index.html",
+        compositionSrc: "compositions/intro.html",
+      },
+    ]);
+
+    unsubscribe();
+    act(() => root.unmount());
+  });
+
+  it("uses the shell player to seek a real preview adapter after readiness", async () => {
+    const { root, getContext, getHandle } = renderHandle();
+    const { adapter, win } = makeAdapterWindow();
+    await act(async () => {
+      getContext().iframeRef.current = makeFakeIframe(win);
+      getContext().onIframeLoad();
+      await Promise.resolve();
+    });
+
+    expect(usePlayerStore.getState().timelineReady).toBe(true);
+    expect(getHandle().seek(4)).toBe(true);
+    expect(adapter.getTime()).toBe(4);
+    expect(usePlayerStore.getState().currentTime).toBe(4);
+    act(() => getHandle().play());
+    expect(getHandle().playing).toBe(true);
+
+    act(() => root.unmount());
+  });
+
+  it("keeps playback time out of React renders and forwards live time notifications", () => {
+    const { root, getHandle, getRenderCount } = renderHandle();
+    const initialRenderCount = getRenderCount();
+    const timeListener = vi.fn();
+    const structuralListener = vi.fn();
+    const unsubscribeTime = getHandle().subscribeTime(timeListener);
+    const unsubscribe = getHandle().subscribe(structuralListener);
+
+    act(() => {
+      usePlayerStore.setState({ currentTime: 2.5 });
+      liveTime.notify(7.25);
+    });
+
+    expect(getRenderCount()).toBe(initialRenderCount);
+    expect(getHandle().currentTime).toBe(2.5);
+    expect(timeListener).toHaveBeenCalledWith(7.25);
+    expect(structuralListener).not.toHaveBeenCalled();
+
+    unsubscribeTime();
+    unsubscribe();
+    act(() => root.unmount());
+  });
+});

package/src/player/hooks/usePlayerHandle.ts

@@ -0,0 +1,94 @@
+import { useCallback, useMemo } from "react";
+import { liveTime, usePlayerStore, type TimelineElement } from "../store/playerStore";
+import { useNLEContext } from "../../components/nle/NLEContext";
+
+export interface PlayerHandleElement {
+  id: string;
+  start: number;
+  end: number;
+  selector?: string;
+  sourceFile?: string;
+  compositionSrc?: string;
+}
+
+export type PlayerHandleListener = () => void;
+export type PlayerHandleTimeListener = (time: number) => void;
+
+export interface PlayerHandle {
+  ready: boolean;
+  playing: boolean;
+  seek: (seconds: number) => boolean;
+  play: () => void;
+  pause: () => void;
+  togglePlay: () => void;
+  readonly currentTime: number;
+  duration: number;
+  elements: PlayerHandleElement[];
+  subscribe: (listener: PlayerHandleListener) => () => void;
+  subscribeTime: (listener: PlayerHandleTimeListener) => () => void;
+}
+
+function toHandleElement(element: TimelineElement): PlayerHandleElement {
+  return {
+    id: element.id,
+    start: element.start,
+    end: element.start + element.duration,
+    selector: element.selector,
+    sourceFile: element.sourceFile,
+    compositionSrc: element.compositionSrc,
+  };
+}
+
+/**
+ * Reads and controls the shell player. Call this under EditorShell/NLEProvider;
+ * the provider owns the mounted preview iframe and the single player instance.
+ */
+export function usePlayerHandle(): PlayerHandle {
+  const { play, pause, togglePlay, seek: seekPlayer } = useNLEContext();
+  const ready = usePlayerStore((state) => state.timelineReady);
+  const playing = usePlayerStore((state) => state.isPlaying);
+  const duration = usePlayerStore((state) => state.duration);
+  const elements = usePlayerStore((state) => state.elements);
+
+  const seek = useCallback(
+    (seconds: number) => {
+      if (!ready) return false;
+      return seekPlayer(seconds);
+    },
+    [ready, seekPlayer],
+  );
+
+  const subscribe = useCallback((listener: PlayerHandleListener) => {
+    let previous = usePlayerStore.getState();
+    return usePlayerStore.subscribe((state) => {
+      const structuralChange =
+        state.timelineReady !== previous.timelineReady ||
+        state.isPlaying !== previous.isPlaying ||
+        state.duration !== previous.duration ||
+        state.elements !== previous.elements;
+      previous = state;
+      if (structuralChange) listener();
+    });
+  }, []);
+
+  const subscribeTime = useCallback((listener: PlayerHandleTimeListener) => {
+    return liveTime.subscribe(listener);
+  }, []);
+  const handleElements = useMemo(() => elements.map(toHandleElement), [elements]);
+
+  return {
+    ready,
+    playing,
+    seek,
+    play,
+    pause,
+    togglePlay,
+    get currentTime() {
+      return usePlayerStore.getState().currentTime;
+    },
+    duration,
+    elements: handleElements,
+    subscribe,
+    subscribeTime,
+  };
+}

package/src/player/index.ts

@@ -7,6 +7,13 @@ export { CompositionThumbnail } from "./components/CompositionThumbnail";
 
 // Hooks
 export { useTimelinePlayer } from "./hooks/useTimelinePlayer";
+export { usePlayerHandle } from "./hooks/usePlayerHandle";
+export type {
+  PlayerHandle,
+  PlayerHandleElement,
+  PlayerHandleListener,
+  PlayerHandleTimeListener,
+} from "./hooks/usePlayerHandle";
 export { resolveIframe } from "./lib/timelineDOM";
 
 // Store