@hyperframes/studio 0.9.37 → 0.9.39

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/dist/assets/{codec-BP7F-7Jx.js → codec-CY6KnWXa.js} +1 -1
  2. package/dist/assets/{hyperframes-player-_QnPoHup.js → hyperframes-player-B9-CuG_h.js} +1 -1
  3. package/dist/assets/{index-BJTCbv8z.css → index-4VGEAZyf.css} +1 -1
  4. package/dist/assets/{index-D6ePWUpc.js → index-Bjz2UaYv.js} +1 -1
  5. package/dist/assets/{index-tjhfci4N.js → index-_pkzoYYF.js} +166 -166
  6. package/dist/assets/{pausedVideoDecoder-B7U86zDa.js → pausedVideoDecoder-Dr7nKUUu.js} +1 -1
  7. package/dist/{chunk-63DH4LRB.js → chunk-44VRMER6.js} +2 -11
  8. package/dist/{chunk-45KKBU63.js → chunk-ATDO3YLX.js} +1 -1
  9. package/dist/chunk-FQ3VRKMC.js +148 -0
  10. package/dist/{chunk-YKBN653R.js → chunk-NBULUIWH.js} +252 -1
  11. package/dist/{domEditingLayers-7Q56QAU5.js → domEditingLayers-FRVHP6IB.js} +2 -2
  12. package/dist/index.d.ts +3 -85
  13. package/dist/index.html +2 -2
  14. package/dist/index.js +379 -400
  15. package/dist/keys-CaWcxUST.d.ts +86 -0
  16. package/dist/keys.d.ts +1 -0
  17. package/dist/keys.js +11 -0
  18. package/dist/player.js +2 -2
  19. package/dist/styles.css +1 -1
  20. package/package.json +12 -8
  21. package/src/components/editor/DomEditGestureReadout.test.tsx +204 -20
  22. package/src/components/editor/DomEditGestureReadout.tsx +36 -18
  23. package/src/components/editor/InlineTextToolbar.tsx +2 -2
  24. package/src/components/editor/domEditGestureReadoutPlacement.ts +144 -0
  25. package/src/components/editor/domEditGestureReadoutState.ts +18 -8
  26. package/src/components/editor/domEditingDom.ts +2 -15
  27. package/src/components/editor/propertyPanelFlatMediaSection.test.tsx +7 -36
  28. package/src/components/editor/propertyPanelFlatMediaSection.tsx +9 -32
  29. package/src/components/editor/useDomEditCompositionRect.ts +13 -4
  30. package/src/components/editor/useDomEditOverlayGestures.ts +1 -1
  31. package/src/components/editor/usePreviewCompositionRect.test.tsx +39 -0
  32. package/src/components/editor/useVolumeAutomation.test.tsx +0 -69
  33. package/src/components/editor/useVolumeAutomation.ts +0 -4
  34. package/src/hooks/elementPickerStyles.ts +53 -0
  35. package/src/hooks/gsapScriptCommitTypes.ts +2 -6
  36. package/src/hooks/timelineEditingHelpers.test.ts +39 -0
  37. package/src/hooks/timelineEditingHelpers.ts +13 -0
  38. package/src/hooks/useDomEditCommits.ts +4 -9
  39. package/src/hooks/useDomEditPersist.ts +2 -12
  40. package/src/hooks/useElementPicker.test.ts +83 -3
  41. package/src/hooks/useElementPicker.ts +27 -66
  42. package/src/hooks/useGsapScriptCommits.test.tsx +21 -0
  43. package/src/hooks/useGsapScriptCommits.ts +7 -3
  44. package/src/keys.test.ts +53 -0
  45. package/src/keys.ts +11 -0
  46. package/src/player/components/Player.test.ts +15 -0
  47. package/src/player/components/Player.tsx +6 -4
  48. package/src/player/components/audioGainApply.test.ts +13 -0
  49. package/src/player/components/audioGainApply.ts +0 -3
  50. package/src/player/components/studioKeyDefaults.ts +68 -0
  51. package/src/player/components/studioShortcuts.ts +2 -67
  52. package/src/player/hooks/playbackAdapterResolution.ts +15 -0
  53. package/src/player/hooks/previewMessageRouter.manifest.test.ts +67 -0
  54. package/src/player/hooks/previewMessageRouter.ts +38 -8
  55. package/src/player/hooks/timelinePlayerTestHarness.ts +27 -1
  56. package/src/player/hooks/useShadowPreviewReload.ts +24 -6
  57. package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +46 -0
  58. package/src/player/hooks/useTimelinePlayer.ts +5 -9
  59. package/src/player/lib/bridgePlayback.ts +156 -0
  60. package/src/player/lib/previewChannel.test.ts +260 -0
  61. package/src/player/lib/previewChannel.ts +100 -0
  62. package/src/player/sceneSwap.test.ts +12 -0
  63. package/src/player/sceneSwap.ts +2 -0
  64. package/src/utils/studioFileHistory.test.ts +29 -1
  65. package/src/utils/studioFileHistory.ts +24 -1
@@ -0,0 +1,67 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import { afterEach, describe, expect, it, vi } from "vitest";
4
+ import { usePlayerStore } from "../store/playerStore";
5
+ import { createPreviewMessageHandler } from "./previewMessageRouter";
6
+ import { detachedFakeIframe, serveEditingRequests } from "./timelinePlayerTestHarness";
7
+
8
+ const closers: Array<() => void> = [];
9
+ afterEach(() => {
10
+ closers.splice(0).forEach((close) => close());
11
+ usePlayerStore.getState().reset();
12
+ });
13
+
14
+ const PORT_MANIFEST = { clips: [{ id: "a" }], durationInFrames: 60, scenes: [] };
15
+ const GLOBAL_MANIFEST = { clips: [{ id: "x" }], durationInFrames: 30, scenes: [] };
16
+
17
+ /** A frame whose globals and editing port carry different manifests, so a test sees which was read. */
18
+ function routeStateTicks(opaque: boolean) {
19
+ const frame: Record<string, unknown> = { __clipManifest: GLOBAL_MANIFEST };
20
+ const iframe = detachedFakeIframe(frame);
21
+ if (opaque) {
22
+ Object.defineProperty(iframe, "contentDocument", { value: null });
23
+ Object.defineProperty(frame, "document", {
24
+ get: () => {
25
+ throw new DOMException("blocked", "SecurityError");
26
+ },
27
+ });
28
+ }
29
+ const asked = vi.fn(() => ({ clipManifest: PORT_MANIFEST }));
30
+ closers.push(serveEditingRequests(frame, asked));
31
+ const processed = vi.fn();
32
+ const handle = createPreviewMessageHandler({
33
+ iframeRef: { current: iframe },
34
+ processTimelineMessageRef: { current: processed },
35
+ enrichMissingCompositionsRef: { current: vi.fn() },
36
+ lastTimelineMessageRef: { current: Date.now() },
37
+ getAdapter: () => null,
38
+ syncTimelineElements: vi.fn(),
39
+ });
40
+ const tick = () =>
41
+ handle(
42
+ new MessageEvent("message", {
43
+ source: frame as unknown as Window,
44
+ data: { source: "hf-preview", type: "state", isPlaying: false },
45
+ }),
46
+ );
47
+ return { tick, asked, processed };
48
+ }
49
+
50
+ describe("a state tick while the timeline is empty", () => {
51
+ it("reads a scriptable frame's manifest straight off it, at once, with no port", async () => {
52
+ const { tick, asked, processed } = routeStateTicks(false);
53
+ tick();
54
+ expect(processed).toHaveBeenCalledWith(GLOBAL_MANIFEST);
55
+ await new Promise((resolve) => setTimeout(resolve, 20));
56
+ expect(asked).not.toHaveBeenCalled();
57
+ });
58
+
59
+ it("asks an opaque frame's runtime over the editing port, one request at a time", async () => {
60
+ const { tick, asked, processed } = routeStateTicks(true);
61
+ tick();
62
+ tick();
63
+ await vi.waitFor(() => expect(processed).toHaveBeenCalledWith(PORT_MANIFEST));
64
+ expect(asked).toHaveBeenCalledOnce();
65
+ expect(processed).toHaveBeenCalledOnce();
66
+ });
67
+ });
@@ -23,6 +23,7 @@ import {
23
23
  parsePreviewFacts,
24
24
  } from "../store/previewQualitySlice";
25
25
  import { parseTimelineFromDOM } from "../lib/timelineDOM";
26
+ import { previewClipManifest, previewFrameOpaque } from "../lib/previewChannel";
26
27
 
27
28
  /** What `processTimelineMessage` accepts — the clip-manifest postMessage. */
28
29
  export interface ClipManifestMessage {
@@ -83,6 +84,39 @@ function enrichDue(lastTimelineMessage: number, enriched: { at: number }): boole
83
84
  return true;
84
85
  }
85
86
 
87
+ /** Asks the runtime for its clip manifest, one request at a time, while the store has no elements. */
88
+ function recoverClipManifest(
89
+ deps: PreviewMessageRouterDeps,
90
+ iframe: HTMLIFrameElement,
91
+ recovery: { asking: boolean },
92
+ ): void {
93
+ if (recovery.asking) return;
94
+ recovery.asking = true;
95
+ previewClipManifest(iframe)
96
+ .then((manifest) => {
97
+ const stillWanted =
98
+ usePlayerStore.getState().elements.length === 0 &&
99
+ deps.iframeRef.current === iframe &&
100
+ !hasTimelinePerformanceFixtureLease();
101
+ if (manifest && manifest.clips.length > 0 && stillWanted)
102
+ deps.processTimelineMessageRef.current(manifest);
103
+ })
104
+ .catch(() => {})
105
+ .finally(() => (recovery.asking = false));
106
+ }
107
+
108
+ function recoverEmptyTimeline(
109
+ deps: PreviewMessageRouterDeps,
110
+ iframe: HTMLIFrameElement | null,
111
+ recovery: { asking: boolean },
112
+ ): void {
113
+ if (iframe && previewFrameOpaque(iframe)) return recoverClipManifest(deps, iframe, recovery);
114
+ const manifest = (iframe?.contentWindow as IframeWindow | null)?.__clipManifest;
115
+ if (manifest && manifest.clips.length > 0) {
116
+ deps.processTimelineMessageRef.current(manifest);
117
+ }
118
+ }
119
+
86
120
  /**
87
121
  * A `state` tick doubles as a recovery hook: if the store still has no
88
122
  * elements, read the manifest straight off the iframe, and if no `timeline`
@@ -92,15 +126,11 @@ function handleStateMessage(
92
126
  deps: PreviewMessageRouterDeps,
93
127
  iframe: HTMLIFrameElement | null,
94
128
  playingHoldsClipListPosts: boolean,
95
- enriched: { at: number },
129
+ enriched: { at: number; asking: boolean },
96
130
  ): void {
97
131
  try {
98
- if (usePlayerStore.getState().elements.length === 0) {
99
- const manifest = (iframe?.contentWindow as IframeWindow | null)?.__clipManifest;
100
- if (manifest && manifest.clips.length > 0) {
101
- deps.processTimelineMessageRef.current(manifest);
102
- }
103
- }
132
+ if (usePlayerStore.getState().elements.length === 0)
133
+ recoverEmptyTimeline(deps, iframe, enriched);
104
134
  if (!playingHoldsClipListPosts && enrichDue(deps.lastTimelineMessageRef.current, enriched)) {
105
135
  deps.enrichMissingCompositionsRef.current();
106
136
  }
@@ -156,7 +186,7 @@ function applyStoreReport(data: PreviewMessage): boolean {
156
186
  export function createPreviewMessageHandler(
157
187
  deps: PreviewMessageRouterDeps,
158
188
  ): (e: MessageEvent) => void {
159
- const enriched = { at: 0 };
189
+ const enriched = { at: 0, asking: false };
160
190
  return (e: MessageEvent) => {
161
191
  const iframe = deps.iframeRef.current;
162
192
  const data = acceptedPreviewMessage(e, iframe);
@@ -60,7 +60,7 @@ export function renderTimelinePlayerHarness(options?: UseTimelinePlayerOptions)
60
60
  };
61
61
  }
62
62
 
63
- export function makeFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFrameElement {
63
+ export function detachedFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFrameElement {
64
64
  const iframe = document.createElement("iframe");
65
65
  Object.defineProperty(iframe, "contentWindow", { value: iframeWindow, configurable: true });
66
66
  Object.defineProperty(iframe, "contentDocument", {
@@ -70,6 +70,12 @@ export function makeFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFram
70
70
  return iframe;
71
71
  }
72
72
 
73
+ export function makeFakeIframe(iframeWindow: Record<string, unknown>): HTMLIFrameElement {
74
+ const iframe = detachedFakeIframe(iframeWindow);
75
+ document.body.appendChild(iframe);
76
+ return iframe;
77
+ }
78
+
73
79
  export function attachIframeWindow(api: TimelinePlayerApi, iframeWindow: Record<string, unknown>) {
74
80
  const iframe = makeFakeIframe(iframeWindow);
75
81
  act(() => {
@@ -147,3 +153,23 @@ export async function paintShadow(getApi: () => TimelinePlayerApi, shadow: HTMLI
147
153
  });
148
154
  return slot.gen;
149
155
  }
156
+
157
+ export function serveEditingRequests(
158
+ frame: Record<string, unknown>,
159
+ answer: (kind: string, params: unknown) => unknown,
160
+ ): () => void {
161
+ const ports: MessagePort[] = [];
162
+ frame.postMessage = (message: { type?: string } | null) => {
163
+ if (message?.type !== "editing-connect") return;
164
+ const { port1, port2 } = new MessageChannel();
165
+ ports.push(port1);
166
+ port1.onmessage = (event: MessageEvent<{ id: number; kind: string; params: unknown }>) => {
167
+ const { id, kind, params } = event.data;
168
+ port1.postMessage({ v: 1, id, ok: true, result: answer(kind, params) });
169
+ };
170
+ const handoff = { source: "hf-preview", type: "editing-port", v: 1 };
171
+ const source = frame as unknown as Window;
172
+ window.dispatchEvent(new MessageEvent("message", { source, data: handoff, ports: [port2] }));
173
+ };
174
+ return () => ports.forEach((port) => port.close());
175
+ }
@@ -20,6 +20,7 @@ import {
20
20
  } from "./useTimelineSyncCallbacks";
21
21
  import type { IframeWindow, PlaybackAdapter } from "../lib/playbackTypes";
22
22
  import { setPreviewReloading } from "../previewReloading";
23
+ import { previewFrameOpaque, previewSeekPainted } from "../lib/previewChannel";
23
24
  import { studioFileRevision } from "../../utils/studioFileVersion";
24
25
  import { announcePreviewPromoted } from "../sceneSwap";
25
26
  import { afterStudioPendingEdits, isStudioEditSaving } from "../../utils/studioPendingEdits";
@@ -34,7 +35,9 @@ export const SHADOW_READY_TIMEOUT_MS = 15_000;
34
35
  export const SHADOW_READY_BUDGETS = 3;
35
36
 
36
37
  function restoreSeekPainted(iframe: HTMLIFrameElement | null): Promise<void> | undefined {
37
- const win = iframe?.contentWindow as IframeWindow | null | undefined;
38
+ if (!iframe) return undefined;
39
+ if (previewFrameOpaque(iframe)) return previewSeekPainted(iframe, SHADOW_READY_TIMEOUT_MS);
40
+ const win = iframe.contentWindow as IframeWindow | null;
38
41
  return win?.__hfWaitForSeekCompletion?.().catch(() => {});
39
42
  }
40
43
 
@@ -114,6 +117,7 @@ export function useShadowPreviewReload({
114
117
  const budgetsSpentRef = useRef(0);
115
118
  // The shadow still owed a wait budget, so a hidden tab can resume it when it becomes visible.
116
119
  const budgetGenRef = useRef<number | null>(null);
120
+ const shadowFrameLeftPageRef = useRef(false);
117
121
  const cancelPendingLoadRef = useRef<() => void>(() => {});
118
122
  const stopHoldRef = useRef<() => void>(() => {});
119
123
  const shadowUrlRef = useRef("");
@@ -127,6 +131,7 @@ export function useShadowPreviewReload({
127
131
  const stopPendingShadow = useCallback(() => {
128
132
  clearTimeout(readyTimerRef.current);
129
133
  budgetGenRef.current = null;
134
+ shadowFrameLeftPageRef.current = false;
130
135
  cancelPendingLoadRef.current();
131
136
  stopHoldRef.current();
132
137
  pendingCommitRef.current = null;
@@ -296,14 +301,10 @@ export function useShadowPreviewReload({
296
301
  [promoteWhenReady],
297
302
  );
298
303
 
299
- const setShadowIframeNode = useCallback((node: HTMLIFrameElement | null) => {
300
- shadowIframeRef.current = node;
301
- }, []);
302
-
303
304
  const armReadyTimer = useCallback(
304
305
  (gen: number) => {
305
306
  clearTimeout(readyTimerRef.current);
306
- if (isDocumentHidden()) return;
307
+ if (isDocumentHidden() || shadowFrameLeftPageRef.current) return;
307
308
  let drew = false;
308
309
  let starved = false;
309
310
  requestAnimationFrame(() => {
@@ -317,6 +318,12 @@ export function useShadowPreviewReload({
317
318
  logReload("shadow-starved", { gen });
318
319
  return;
319
320
  }
321
+ const frame = shadowIframeRef.current;
322
+ if (frame && !frame.isConnected) {
323
+ shadowFrameLeftPageRef.current = true;
324
+ logReload("shadow-detached", { gen });
325
+ return;
326
+ }
320
327
  budgetsSpentRef.current += 1;
321
328
  if (budgetsSpentRef.current < SHADOW_READY_BUDGETS) {
322
329
  logReload("shadow-slow", { budgetsSpent: budgetsSpentRef.current });
@@ -331,6 +338,17 @@ export function useShadowPreviewReload({
331
338
  const armReadyTimerRef = useRef(armReadyTimer);
332
339
  armReadyTimerRef.current = armReadyTimer;
333
340
 
341
+ const setShadowIframeNode = useCallback((node: HTMLIFrameElement | null) => {
342
+ shadowIframeRef.current = node;
343
+ const gen = budgetGenRef.current;
344
+ if (!node || !shadowFrameLeftPageRef.current || gen == null || gen !== shadowGenRef.current)
345
+ return;
346
+ shadowFrameLeftPageRef.current = false;
347
+ budgetsSpentRef.current = 0;
348
+ logReload("shadow-reattached", { gen });
349
+ armReadyTimerRef.current(gen);
350
+ }, []);
351
+
334
352
  const beginShadowReload = useCallback(
335
353
  (url: string) => {
336
354
  retry.started();
@@ -533,6 +533,52 @@ describe("shadow reload readiness and failure", () => {
533
533
  unmount(root);
534
534
  });
535
535
 
536
+ it("keeps a reload whose frame left the page, and promotes it once a new frame mounts", () => {
537
+ vi.useFakeTimers();
538
+ const onPreviewReloadFailed = vi.fn();
539
+ const { getApi, gen, live, root } = beginReload({ onPreviewReloadFailed });
540
+ const first = makeShadowWithSpies();
541
+ act(() => getApi().setShadowIframeNode(first.iframe));
542
+
543
+ // The pane holding the preview unmounts mid-reload: its Players remove their frames.
544
+ act(() => first.iframe.remove());
545
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS * 2));
546
+ expect(onPreviewReloadFailed).not.toHaveBeenCalled();
547
+ expect(getApi().iframeRef.current).toBe(live);
548
+
549
+ // The pane comes back: a new Player for the same slot mounts a new frame, which loads.
550
+ const again = makeShadowWithSpies();
551
+ act(() => {
552
+ getApi().setShadowIframeNode(again.iframe);
553
+ getApi().onShadowIframeLoad(gen);
554
+ });
555
+ act(() => getApi().onShadowReadyChange(gen, true));
556
+ expect(getApi().iframeRef.current).toBe(again.iframe);
557
+ expect(onPreviewReloadFailed).not.toHaveBeenCalled();
558
+ unmount(root);
559
+ });
560
+
561
+ it("gives a frame that mounts again its full budgets, then drops it if it stays silent", () => {
562
+ vi.useFakeTimers();
563
+ vi.spyOn(console, "error").mockImplementation(() => {});
564
+ const onPreviewReloadFailed = vi.fn();
565
+ const { getApi, live, root } = beginReload({ onPreviewReloadFailed });
566
+ const first = makeShadowWithSpies();
567
+ act(() => getApi().setShadowIframeNode(first.iframe));
568
+ act(() => void vi.advanceTimersByTime(SHADOW_READY_TIMEOUT_MS + 1000));
569
+ act(() => first.iframe.remove());
570
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS));
571
+ expect(onPreviewReloadFailed).not.toHaveBeenCalled();
572
+
573
+ act(() => getApi().setShadowIframeNode(makeShadowWithSpies().iframe));
574
+ act(() => void vi.advanceTimersByTime(FULL_WAIT_MS - 1));
575
+ expect(onPreviewReloadFailed).not.toHaveBeenCalled();
576
+ act(() => void vi.advanceTimersByTime(1));
577
+ expect(onPreviewReloadFailed).toHaveBeenCalledWith(expect.stringContaining("too long"));
578
+ expect(getApi().iframeRef.current).toBe(live);
579
+ unmount(root);
580
+ });
581
+
536
582
  it("does not spend the budget while the tab is hidden, and promotes once it is visible", () => {
537
583
  vi.useFakeTimers();
538
584
  const onPreviewReloadFailed = vi.fn();
@@ -4,7 +4,7 @@ import { useMountEffect } from "../../hooks/useMountEffect";
4
4
  import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
5
5
  import { useTimelineSyncCallbacks } from "./useTimelineSyncCallbacks";
6
6
  import { useShadowPreviewReload } from "./useShadowPreviewReload";
7
- import { resolvePlaybackAdapter } from "./playbackAdapterResolution";
7
+ import { resolveFramePlaybackAdapter } from "./playbackAdapterResolution";
8
8
  import { subscribePreviewFrame, transportAdapter } from "../store/previewFrameStore";
9
9
  import { clampToDuration } from "../lib/time";
10
10
  import { useTimelinePlayerLoop } from "./useTimelinePlayerLoop";
@@ -28,7 +28,7 @@ export {
28
28
  } from "../lib/playbackShortcuts";
29
29
 
30
30
  import type { PlaybackAdapter, IframeWindow } from "../lib/playbackTypes";
31
- import { attachPausedVideoProvider } from "../lib/pausedVideoProvider";
31
+ import { setFrameLoopStart } from "../lib/previewChannel";
32
32
  import { releaseStaticSeekCache, type StaticSeekCacheEntry } from "../lib/playbackAdapter";
33
33
  import { mergeTimelineElementsPreservingDowngrades } from "../lib/timelineDOM";
34
34
  import { findTimelineElementInIframe } from "../../hooks/timelineEditingHelpers";
@@ -149,10 +149,8 @@ export function useTimelinePlayer({
149
149
  try {
150
150
  // undefined means "no override"; an explicit null override means "no adapter".
151
151
  const iframe = overrideIframe !== undefined ? overrideIframe : iframeRef.current;
152
- const win = iframe?.contentWindow as IframeWindow | null;
153
- if (!iframe || !win) return null;
154
- attachPausedVideoProvider(iframe, win);
155
- const adapter = resolvePlaybackAdapter(iframe, win, {
152
+ if (!iframe) return null;
153
+ const adapter = resolveFramePlaybackAdapter(iframe, {
156
154
  cache: staticSeekAdapterRef,
157
155
  warned: staticSeekWarnedRef,
158
156
  });
@@ -165,9 +163,7 @@ export function useTimelinePlayer({
165
163
  );
166
164
 
167
165
  const setLoopStart = useCallback((seconds: number | null) => {
168
- try {
169
- (iframeRef.current?.contentWindow as IframeWindow | null)?.__hf?.setLoopStart?.(seconds);
170
- } catch {}
166
+ if (iframeRef.current) setFrameLoopStart(iframeRef.current, seconds);
171
167
  }, []);
172
168
  const { startRAFLoop, stopRAFLoop, stopReverseLoop } = useTimelinePlayerLoop({
173
169
  rafRef,
@@ -0,0 +1,156 @@
1
+ // Playback of a frame Studio cannot script: control-bridge commands, with time and duration mirrored
2
+ // from the runtime's `state` and `timeline` posts. Player registers each frame before it loads,
3
+ // because a runtime posts its first `timeline` while it boots.
4
+ import type { PlaybackAdapter } from "./playbackTypes";
5
+ import { inspectStudioRuntimeMessage, postRuntimeControlMessage } from "./runtimeProtocol";
6
+
7
+ interface PlaybackMirror {
8
+ iframe: HTMLIFrameElement;
9
+ time: number;
10
+ duration: number;
11
+ playing: boolean;
12
+ /** A seek the runtime has not confirmed yet, and until when to wait for it. */
13
+ seekTo: number | null;
14
+ seekUntil: number;
15
+ /** The composition's declared size from the runtime's `stage-size` post. */
16
+ stageSize: { width: number; height: number } | null;
17
+ }
18
+
19
+ const SEEK_CONFIRM_MS = 500;
20
+ // A post without fps metadata is matched within half a frame of the lowest frame rate a film may use.
21
+ const LOWEST_FPS = 1;
22
+
23
+ /** Keyed by the frame's window, which a frame keeps across its loads. */
24
+ const mirrors = new WeakMap<object, PlaybackMirror>();
25
+
26
+ function mirrorOf(iframe: HTMLIFrameElement): PlaybackMirror | null {
27
+ const frame = iframe.contentWindow;
28
+ if (!frame) return null;
29
+ let mirror = mirrors.get(frame);
30
+ if (!mirror) {
31
+ mirror = {
32
+ iframe,
33
+ time: 0,
34
+ duration: 0,
35
+ playing: false,
36
+ seekTo: null,
37
+ seekUntil: 0,
38
+ stageSize: null,
39
+ };
40
+ mirrors.set(frame, mirror);
41
+ }
42
+ mirror.iframe = iframe;
43
+ return mirror;
44
+ }
45
+
46
+ /** Starts mirroring a preview frame Studio built; call it before the frame loads. */
47
+ export function watchPreviewFrame(iframe: HTMLIFrameElement): void {
48
+ mirrorOf(iframe);
49
+ }
50
+
51
+ /** The composition size a registered frame's runtime last posted. */
52
+ export function previewStageSize(
53
+ iframe: HTMLIFrameElement,
54
+ ): { width: number; height: number } | null {
55
+ const frame = iframe.contentWindow;
56
+ return (frame && mirrors.get(frame)?.stageSize) ?? null;
57
+ }
58
+
59
+ /** The origins a post from this frame can carry, given its sandbox and what it loads. */
60
+ export function frameOrigins(iframe: HTMLIFrameElement): string[] {
61
+ const sandbox = iframe.getAttribute("sandbox")?.toLowerCase().split(/\s+/);
62
+ if (sandbox && !sandbox.includes("allow-same-origin")) return ["null"];
63
+ const src = iframe.getAttribute("src");
64
+ if (iframe.hasAttribute("srcdoc") || !src) return [window.location.origin];
65
+ try {
66
+ const url = new URL(src, window.location.href);
67
+ if (url.protocol === "about:") return [window.location.origin];
68
+ return [url.protocol === "data:" ? "null" : url.origin];
69
+ } catch {
70
+ return [];
71
+ }
72
+ }
73
+
74
+ const finiteAtLeastZero = (value: unknown): value is number =>
75
+ typeof value === "number" && Number.isFinite(value) && value >= 0;
76
+ const finitePositive = (value: unknown): value is number => finiteAtLeastZero(value) && value > 0;
77
+
78
+ /** The runtime lands a seek on the frame at or before it, so only that frame confirms it. */
79
+ function confirmsSeek(currentTime: number, seekTo: number, fps: number | null): boolean {
80
+ if (fps === null) return Math.abs(currentTime - seekTo) <= 0.5 / LOWEST_FPS;
81
+ return Math.abs(currentTime - Math.floor(seekTo * fps + 1e-9) / fps) < 0.5 / fps;
82
+ }
83
+
84
+ /** The runtime's playback post and its frame rate, or null for anything else. */
85
+ function runtimePost(
86
+ data: unknown,
87
+ ): { message: Record<string, unknown>; fps: number | null } | null {
88
+ if (typeof data !== "object" || data === null) return null;
89
+ const message = data as Record<string, unknown>;
90
+ if (message.source !== "hf-preview") return null;
91
+ const inspection = inspectStudioRuntimeMessage(message);
92
+ if (inspection.status === "unsupported") return null;
93
+ return { message, fps: inspection.status === "supported" ? inspection.fps : null };
94
+ }
95
+
96
+ function mirrorState(
97
+ mirror: PlaybackMirror,
98
+ currentTime: number,
99
+ playing: boolean,
100
+ fps: number | null,
101
+ ) {
102
+ // A state posted before the runtime handled our seek would put the playhead back.
103
+ const { seekTo } = mirror;
104
+ const waiting = seekTo !== null && performance.now() < mirror.seekUntil;
105
+ if (waiting && !confirmsSeek(currentTime, seekTo, fps)) return;
106
+ mirror.seekTo = null;
107
+ mirror.time = currentTime;
108
+ mirror.playing = playing;
109
+ }
110
+
111
+ function mirrorPost(mirror: PlaybackMirror, message: Record<string, unknown>, fps: number | null) {
112
+ if (message.type === "timeline" && finiteAtLeastZero(message.durationSeconds)) {
113
+ mirror.duration = message.durationSeconds;
114
+ } else if (message.type === "state" && finiteAtLeastZero(message.currentTime)) {
115
+ mirrorState(mirror, message.currentTime, message.isPlaying === true, fps);
116
+ } else if (message.type === "stage-size") {
117
+ const { width, height } = message;
118
+ if (finitePositive(width) && finitePositive(height)) mirror.stageSize = { width, height };
119
+ }
120
+ }
121
+
122
+ function mirrorRuntimePlayback(event: MessageEvent): void {
123
+ // Only a frame Studio built, posting from an origin that frame can have.
124
+ const mirror = event.source ? mirrors.get(event.source) : undefined;
125
+ if (!mirror || !frameOrigins(mirror.iframe).includes(event.origin)) return;
126
+ const post = runtimePost(event.data);
127
+ if (post) mirrorPost(mirror, post.message, post.fps);
128
+ }
129
+
130
+ if (typeof window !== "undefined") window.addEventListener("message", mirrorRuntimePlayback);
131
+
132
+ export function bridgePlaybackAdapter(iframe: HTMLIFrameElement): PlaybackAdapter | null {
133
+ const frame = iframe.contentWindow;
134
+ const mirror = mirrorOf(iframe);
135
+ if (!frame || !mirror) return null;
136
+ const send = (action: string, payload?: Record<string, unknown>) =>
137
+ postRuntimeControlMessage(frame, action, payload);
138
+ return {
139
+ play: () => {
140
+ send("play");
141
+ mirror.playing = true;
142
+ },
143
+ pause: () => {
144
+ send("pause");
145
+ mirror.playing = false;
146
+ },
147
+ // The bridge's seek takes no keepPlaying or settled option yet.
148
+ seek: (time) => {
149
+ send("seek", { timeSeconds: time });
150
+ Object.assign(mirror, { time, seekTo: time, seekUntil: performance.now() + SEEK_CONFIRM_MS });
151
+ },
152
+ getTime: () => mirror.time,
153
+ getDuration: () => mirror.duration,
154
+ isPlaying: () => mirror.playing,
155
+ };
156
+ }