Skip to content

Commit 4ff4435

Browse files
feat(studio): export player handle for hosts (#4227)
1 parent 2fb6f69 commit 4ff4435

6 files changed

Lines changed: 271 additions & 4 deletions

File tree

‎packages/studio/src/components/nle/NLEContext.tsx‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { buildProjectApiPath } from "../../utils/projectRouting";
22
import { useContext, useState, useCallback, useRef, useEffect, type ReactNode } from "react";
3-
import { useTimelinePlayer, usePlayerStore } from "../../player";
4-
import type { TimelineElement } from "../../player";
3+
import { useTimelinePlayer } from "../../player/hooks/useTimelinePlayer";
4+
import { usePlayerStore, type TimelineElement } from "../../player/store/playerStore";
55
import type { PreviewIframeSlot } from "../../player/hooks/useTimelineSyncCallbacks";
66
import type { CompositionLevel } from "./CompositionBreadcrumb";
77
import { useCompositionStack } from "./useCompositionStack";
@@ -18,6 +18,8 @@ export interface NLEContextValue {
1818
projectId: string;
1919
// player (from useTimelinePlayer — single instance for the whole shell)
2020
iframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
21+
play: () => void;
22+
pause: () => void;
2123
togglePlay: () => void;
2224
seek: (time: number, options?: { keepPlaying?: boolean }) => boolean;
2325
refreshPlayer: () => void;
@@ -84,6 +86,8 @@ export function NLEProvider({
8486
const containerRef = useRef<HTMLDivElement>(null);
8587
const {
8688
iframeRef,
89+
play,
90+
pause,
8791
togglePlay,
8892
seek,
8993
onIframeLoad: baseOnIframeLoad,
@@ -298,6 +302,8 @@ export function NLEProvider({
298302
const value: NLEContextValue = {
299303
projectId,
300304
iframeRef,
305+
play,
306+
pause,
301307
containerRef,
302308
togglePlay,
303309
seek,

‎packages/studio/src/components/nle/useCompositionStack.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { buildProjectApiPath } from "../../utils/projectRouting";
22
// Composition drill-down stack management for NLEContext/EditorShell
33
import { useState, useCallback, useRef, useEffect } from "react";
4-
import { usePlayerStore } from "../../player";
4+
import { usePlayerStore } from "../../player/store/playerStore";
55
import type { CompositionLevel } from "./CompositionBreadcrumb";
66
import { encodePreviewPath } from "../../player/components/thumbnailUtils";
77

‎packages/studio/src/index.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,12 +46,20 @@ export {
4646
VideoThumbnail,
4747
CompositionThumbnail,
4848
useTimelinePlayer,
49+
usePlayerHandle,
4950
resolveIframe,
5051
usePlayerStore,
5152
liveTime,
5253
formatTime,
5354
} from "./player";
54-
export type { TimelineElement, TimelineTimeRange } from "./player";
55+
export type {
56+
PlayerHandle,
57+
PlayerHandleElement,
58+
PlayerHandleListener,
59+
PlayerHandleTimeListener,
60+
TimelineElement,
61+
TimelineTimeRange,
62+
} from "./player";
5563

5664
// Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
5765
export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
// @vitest-environment happy-dom
2+
3+
import React, { useEffect } from "react";
4+
import { act } from "react";
5+
import { createRoot } from "react-dom/client";
6+
import { afterEach, describe, expect, it, vi } from "vitest";
7+
import { NLEProvider, useNLEContext, type NLEContextValue } from "../../components/nle/NLEContext";
8+
import { liveTime, usePlayerStore } from "../store/playerStore";
9+
import { makeAdapterWindow, makeFakeIframe } from "./timelinePlayerTestHarness";
10+
import { usePlayerHandle, type PlayerHandle } from "./usePlayerHandle";
11+
12+
Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true });
13+
14+
function renderHandle() {
15+
let latest: PlayerHandle | null = null;
16+
let context: NLEContextValue | null = null;
17+
let renders = 0;
18+
const host = document.createElement("div");
19+
document.body.append(host);
20+
const root = createRoot(host);
21+
act(() => {
22+
root.render(
23+
<NLEProvider projectId="player-handle-test">
24+
<HandleHarness
25+
onContext={(value) => (context = value)}
26+
onValue={(value) => (latest = value)}
27+
onRender={() => renders++}
28+
/>
29+
</NLEProvider>,
30+
);
31+
});
32+
if (!latest || !context) throw new Error("usePlayerHandle did not mount");
33+
return {
34+
root,
35+
getHandle: () => latest as PlayerHandle,
36+
getContext: () => context as NLEContextValue,
37+
getRenderCount: () => renders,
38+
};
39+
}
40+
41+
function HandleHarness({
42+
onContext,
43+
onValue,
44+
onRender,
45+
}: {
46+
onContext: (value: NLEContextValue) => void;
47+
onValue: (value: PlayerHandle) => void;
48+
onRender: () => void;
49+
}) {
50+
onRender();
51+
const context = useNLEContext();
52+
const handle = usePlayerHandle();
53+
useEffect(() => {
54+
onContext(context);
55+
onValue(handle);
56+
}, [context, handle, onContext, onValue]);
57+
return null;
58+
}
59+
60+
afterEach(() => {
61+
usePlayerStore.getState().reset();
62+
document.body.innerHTML = "";
63+
});
64+
65+
describe("usePlayerHandle", () => {
66+
it("refuses seek before readiness and notifies structural changes independently", () => {
67+
const { root, getHandle } = renderHandle();
68+
const handle = getHandle();
69+
70+
expect(handle.ready).toBe(false);
71+
expect(handle.seek(4)).toBe(false);
72+
73+
const structuralListener = vi.fn();
74+
const unsubscribe = handle.subscribe(structuralListener);
75+
act(() => usePlayerStore.setState({ timelineReady: true }));
76+
expect(structuralListener).toHaveBeenCalledTimes(1);
77+
act(() => usePlayerStore.setState({ duration: 8 }));
78+
expect(structuralListener).toHaveBeenCalledTimes(2);
79+
act(() =>
80+
usePlayerStore.setState({
81+
elements: [
82+
{
83+
id: "clip",
84+
tag: "div",
85+
start: 2,
86+
duration: 3,
87+
track: 0,
88+
selector: "#clip",
89+
sourceFile: "index.html",
90+
compositionSrc: "compositions/intro.html",
91+
},
92+
],
93+
}),
94+
);
95+
expect(structuralListener).toHaveBeenCalledTimes(3);
96+
expect(getHandle().elements).toEqual([
97+
{
98+
id: "clip",
99+
start: 2,
100+
end: 5,
101+
selector: "#clip",
102+
sourceFile: "index.html",
103+
compositionSrc: "compositions/intro.html",
104+
},
105+
]);
106+
107+
unsubscribe();
108+
act(() => root.unmount());
109+
});
110+
111+
it("uses the shell player to seek a real preview adapter after readiness", async () => {
112+
const { root, getContext, getHandle } = renderHandle();
113+
const { adapter, win } = makeAdapterWindow();
114+
await act(async () => {
115+
getContext().iframeRef.current = makeFakeIframe(win);
116+
getContext().onIframeLoad();
117+
await Promise.resolve();
118+
});
119+
120+
expect(usePlayerStore.getState().timelineReady).toBe(true);
121+
expect(getHandle().seek(4)).toBe(true);
122+
expect(adapter.getTime()).toBe(4);
123+
expect(usePlayerStore.getState().currentTime).toBe(4);
124+
act(() => getHandle().play());
125+
expect(getHandle().playing).toBe(true);
126+
127+
act(() => root.unmount());
128+
});
129+
130+
it("keeps playback time out of React renders and forwards live time notifications", () => {
131+
const { root, getHandle, getRenderCount } = renderHandle();
132+
const initialRenderCount = getRenderCount();
133+
const timeListener = vi.fn();
134+
const structuralListener = vi.fn();
135+
const unsubscribeTime = getHandle().subscribeTime(timeListener);
136+
const unsubscribe = getHandle().subscribe(structuralListener);
137+
138+
act(() => {
139+
usePlayerStore.setState({ currentTime: 2.5 });
140+
liveTime.notify(7.25);
141+
});
142+
143+
expect(getRenderCount()).toBe(initialRenderCount);
144+
expect(getHandle().currentTime).toBe(2.5);
145+
expect(timeListener).toHaveBeenCalledWith(7.25);
146+
expect(structuralListener).not.toHaveBeenCalled();
147+
148+
unsubscribeTime();
149+
unsubscribe();
150+
act(() => root.unmount());
151+
});
152+
});
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
import { useCallback, useMemo } from "react";
2+
import { liveTime, usePlayerStore, type TimelineElement } from "../store/playerStore";
3+
import { useNLEContext } from "../../components/nle/NLEContext";
4+
5+
export interface PlayerHandleElement {
6+
id: string;
7+
start: number;
8+
end: number;
9+
selector?: string;
10+
sourceFile?: string;
11+
compositionSrc?: string;
12+
}
13+
14+
export type PlayerHandleListener = () => void;
15+
export type PlayerHandleTimeListener = (time: number) => void;
16+
17+
export interface PlayerHandle {
18+
ready: boolean;
19+
playing: boolean;
20+
seek: (seconds: number) => boolean;
21+
play: () => void;
22+
pause: () => void;
23+
togglePlay: () => void;
24+
readonly currentTime: number;
25+
duration: number;
26+
elements: PlayerHandleElement[];
27+
subscribe: (listener: PlayerHandleListener) => () => void;
28+
subscribeTime: (listener: PlayerHandleTimeListener) => () => void;
29+
}
30+
31+
function toHandleElement(element: TimelineElement): PlayerHandleElement {
32+
return {
33+
id: element.id,
34+
start: element.start,
35+
end: element.start + element.duration,
36+
selector: element.selector,
37+
sourceFile: element.sourceFile,
38+
compositionSrc: element.compositionSrc,
39+
};
40+
}
41+
42+
/**
43+
* Reads and controls the shell player. Call this under EditorShell/NLEProvider;
44+
* the provider owns the mounted preview iframe and the single player instance.
45+
*/
46+
export function usePlayerHandle(): PlayerHandle {
47+
const { play, pause, togglePlay, seek: seekPlayer } = useNLEContext();
48+
const ready = usePlayerStore((state) => state.timelineReady);
49+
const playing = usePlayerStore((state) => state.isPlaying);
50+
const duration = usePlayerStore((state) => state.duration);
51+
const elements = usePlayerStore((state) => state.elements);
52+
53+
const seek = useCallback(
54+
(seconds: number) => {
55+
if (!ready) return false;
56+
return seekPlayer(seconds);
57+
},
58+
[ready, seekPlayer],
59+
);
60+
61+
const subscribe = useCallback((listener: PlayerHandleListener) => {
62+
let previous = usePlayerStore.getState();
63+
return usePlayerStore.subscribe((state) => {
64+
const structuralChange =
65+
state.timelineReady !== previous.timelineReady ||
66+
state.isPlaying !== previous.isPlaying ||
67+
state.duration !== previous.duration ||
68+
state.elements !== previous.elements;
69+
previous = state;
70+
if (structuralChange) listener();
71+
});
72+
}, []);
73+
74+
const subscribeTime = useCallback((listener: PlayerHandleTimeListener) => {
75+
return liveTime.subscribe(listener);
76+
}, []);
77+
const handleElements = useMemo(() => elements.map(toHandleElement), [elements]);
78+
79+
return {
80+
ready,
81+
playing,
82+
seek,
83+
play,
84+
pause,
85+
togglePlay,
86+
get currentTime() {
87+
return usePlayerStore.getState().currentTime;
88+
},
89+
duration,
90+
elements: handleElements,
91+
subscribe,
92+
subscribeTime,
93+
};
94+
}

‎packages/studio/src/player/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,13 @@ export { CompositionThumbnail } from "./components/CompositionThumbnail";
77

88
// Hooks
99
export { useTimelinePlayer } from "./hooks/useTimelinePlayer";
10+
export { usePlayerHandle } from "./hooks/usePlayerHandle";
11+
export type {
12+
PlayerHandle,
13+
PlayerHandleElement,
14+
PlayerHandleListener,
15+
PlayerHandleTimeListener,
16+
} from "./hooks/usePlayerHandle";
1017
export { resolveIframe } from "./lib/timelineDOM";
1118

1219
// Store

0 commit comments

Comments
 (0)