@hyperframes/studio 0.9.56 → 0.9.58

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 (30) hide show
  1. package/dist/assets/{hyperframes-player-SRLbmEDB.js → hyperframes-player-B78JDyI_.js} +1 -1
  2. package/dist/assets/{index-CgyBYe2L.js → index-D7ICtobF.js} +178 -178
  3. package/dist/assets/{index-yuN1pZrv.js → index-ww7-RmuM.js} +1 -1
  4. package/dist/assets/{pausedVideoDecoder-DtvSF8bV.js → pausedVideoDecoder-Dbe8Cmab.js} +1 -1
  5. package/dist/index.d.ts +87 -3
  6. package/dist/index.html +1 -1
  7. package/dist/index.js +867 -774
  8. package/package.json +8 -8
  9. package/src/components/nle/NLEPreview.test.ts +35 -3
  10. package/src/components/nle/NLEPreview.tsx +5 -4
  11. package/src/hooks/gsapRuntimePatch.ts +2 -3
  12. package/src/hooks/gsapRuntimeReaders.test.ts +5 -40
  13. package/src/hooks/gsapRuntimeReaders.ts +3 -27
  14. package/src/hooks/useExternalFileChangeCoordinator.test.tsx +20 -0
  15. package/src/hooks/useExternalFileChangeCoordinator.ts +1 -1
  16. package/src/index.ts +17 -0
  17. package/src/player/components/studioShortcuts.ts +3 -2
  18. package/src/player/hooks/timelinePlayerTestHarness.ts +2 -0
  19. package/src/player/hooks/timelineSyncHydration.test.ts +28 -2
  20. package/src/player/hooks/timelineSyncHydration.ts +3 -7
  21. package/src/player/hooks/usePlaybackKeyboard.test.ts +107 -2
  22. package/src/player/hooks/usePlaybackKeyboard.ts +38 -1
  23. package/src/player/hooks/useShadowPreviewReload.ts +131 -14
  24. package/src/player/hooks/useTimelinePlayer.reloadStill.test.ts +241 -0
  25. package/src/player/hooks/useTimelinePlayer.ts +13 -1
  26. package/src/player/hooks/useTimelineSyncCallbacks.ts +4 -0
  27. package/src/sealedPreviewExports.test.ts +20 -0
  28. package/src/utils/externalConflictStorage.test.ts +66 -14
  29. package/src/utils/externalConflictStorage.ts +36 -82
  30. package/src/utils/gsapSoftReload.ts +2 -14
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyperframes/studio",
3
- "version": "0.9.56",
3
+ "version": "0.9.58",
4
4
  "description": "",
5
5
  "repository": {
6
6
  "type": "git",
@@ -64,12 +64,12 @@
64
64
  "dockview-react": "8.3.1",
65
65
  "gsap": "^3.13.0",
66
66
  "mediabunny": "^1.66.0",
67
- "@hyperframes/core": "0.9.56",
68
- "@hyperframes/parsers": "0.9.56",
69
- "@hyperframes/sdk": "0.9.56",
70
- "@hyperframes/shader-transitions": "0.9.56",
71
- "@hyperframes/studio-server": "0.9.56",
72
- "@hyperframes/player": "0.9.56"
67
+ "@hyperframes/parsers": "0.9.58",
68
+ "@hyperframes/player": "0.9.58",
69
+ "@hyperframes/sdk": "0.9.58",
70
+ "@hyperframes/shader-transitions": "0.9.58",
71
+ "@hyperframes/studio-server": "0.9.58",
72
+ "@hyperframes/core": "0.9.58"
73
73
  },
74
74
  "devDependencies": {
75
75
  "@tailwindcss/vite": "^4.3.3",
@@ -86,7 +86,7 @@
86
86
  "vite": "^6.4.5",
87
87
  "vitest": "^4.1.12",
88
88
  "zustand": "^5.0.0",
89
- "@hyperframes/producer": "0.9.56"
89
+ "@hyperframes/producer": "0.9.58"
90
90
  },
91
91
  "peerDependencies": {
92
92
  "react": "19",
@@ -56,10 +56,9 @@ class MockResizeObserver {
56
56
  constructor(cb: ResizeObserverCallback) {
57
57
  this.cb = cb;
58
58
  }
59
+ // A browser calls back at its next frame, never inside observe(); renderPreview fires them.
59
60
  observe() {
60
- const fire = () => this.cb([], this as unknown as ResizeObserver);
61
- resizeCallbacks.push(fire);
62
- fire();
61
+ resizeCallbacks.push(() => this.cb([], this as unknown as ResizeObserver));
63
62
  }
64
63
  disconnect() {}
65
64
  }
@@ -67,6 +66,8 @@ class MockResizeObserver {
67
66
  const originalResizeObserver = globalThis.ResizeObserver;
68
67
 
69
68
  function setRect(node: Element, rect: { width: number; height: number }) {
69
+ Object.defineProperty(node, "clientWidth", { configurable: true, value: rect.width });
70
+ Object.defineProperty(node, "clientHeight", { configurable: true, value: rect.height });
70
71
  Object.defineProperty(node, "getBoundingClientRect", {
71
72
  configurable: true,
72
73
  value: () => ({
@@ -493,6 +494,37 @@ describe("NLEPreview", () => {
493
494
  filled.cleanup();
494
495
  });
495
496
 
497
+ it("sizes the stage within the resize callback, so the frame painted after a resize is never at the old size", () => {
498
+ const view = renderPreview(undefined, { box: { width: 640, height: 360 }, fillBox: true });
499
+ setRect(view.viewport, { width: 1920, height: 1080 });
500
+ // Outside act: the browser paints right after this callback returns.
501
+ for (const fire of resizeCallbacks) fire();
502
+ expect([view.stage.style.width, view.stage.style.height]).toEqual(["1920px", "1080px"]);
503
+ view.cleanup();
504
+ });
505
+
506
+ it("sizes the stage from the box's own size while a host scales the box on screen", () => {
507
+ const view = renderPreview(undefined, { box: { width: 640, height: 360 }, fillBox: true });
508
+ setRect(view.viewport, { width: 1920, height: 1080 });
509
+ // A host growing the preview from a quarter of its size: on screen the box is 480 x 270 for now.
510
+ Object.defineProperty(view.viewport, "getBoundingClientRect", {
511
+ configurable: true,
512
+ value: () => ({
513
+ x: 0,
514
+ y: 0,
515
+ left: 0,
516
+ top: 0,
517
+ right: 480,
518
+ bottom: 270,
519
+ width: 480,
520
+ height: 270,
521
+ }),
522
+ });
523
+ for (const fire of resizeCallbacks) fire();
524
+ expect([view.stage.style.width, view.stage.style.height]).toEqual(["1920px", "1080px"]);
525
+ view.cleanup();
526
+ });
527
+
496
528
  it("takes the host's composition size as the stage's shape until the preview measures its own", () => {
497
529
  const box = { width: 800, height: 600 };
498
530
  const plain = renderPreview(undefined, { box });
@@ -11,6 +11,7 @@ import {
11
11
  useState,
12
12
  type RefObject,
13
13
  } from "react";
14
+ import { flushSync } from "react-dom";
14
15
  import { Player } from "../../player";
15
16
  import { postFrameDisplayScale } from "../../player/lib/runtimeProtocol";
16
17
  import type { NLEContextValue } from "./NLEContext";
@@ -148,11 +149,10 @@ export const NLEPreview = memo(function NLEPreview({
148
149
  if (!viewport) return;
149
150
 
150
151
  const updateStageSize = () => {
151
- const rect = viewport.getBoundingClientRect();
152
152
  setStageSize(
153
153
  resolvePreviewStageSize(
154
- rect.width,
155
- rect.height,
154
+ viewport.clientWidth,
155
+ viewport.clientHeight,
156
156
  compositionSize ??
157
157
  (hintWidth && hintHeight ? { width: hintWidth, height: hintHeight } : null),
158
158
  portrait,
@@ -163,7 +163,8 @@ export const NLEPreview = memo(function NLEPreview({
163
163
  };
164
164
 
165
165
  updateStageSize();
166
- const observer = new ResizeObserver(updateStageSize);
166
+ const resizeBeforePaint = () => flushSync(updateStageSize);
167
+ const observer = new ResizeObserver(resizeBeforePaint);
167
168
  observer.observe(viewport);
168
169
  return () => observer.disconnect();
169
170
  }, [compositionSize, hintWidth, hintHeight, portrait, gutterPx, insetPx]);
@@ -250,9 +250,8 @@ function changeTouchesOpacity(change: RuntimeTweenChange): boolean {
250
250
 
251
251
  /**
252
252
  * A tween re-initialization (invalidate, or kill+recreate for keyframe-rebuild)
253
- * captures opacity from the element's CURRENT inline style — for a color-graded
254
- * source (hidden with `opacity: 0 !important`) or a mid-flight tween that's a
255
- * runtime transient, not the authored value, and the capture makes it permanent.
253
+ * captures opacity from the element's CURRENT inline style — for a mid-flight
254
+ * tween that's a runtime transient, not the authored value, and the capture makes it permanent.
256
255
  * Restore the runtime's parse-time authored capture (data-hf-authored-opacity)
257
256
  * first; the re-seek after the patch re-renders the animated value anyway.
258
257
  * Duck-typed (no instanceof): the targets live in the preview iframe's realm.
@@ -2,10 +2,7 @@
2
2
  import { afterEach, describe, expect, it } from "vitest";
3
3
  import { gsap } from "gsap";
4
4
  import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
5
- import {
6
- COLOR_GRADING_SOURCE_HIDDEN_ATTR,
7
- HF_COLOR_GRADING_CANVAS_ID_PREFIX,
8
- } from "@hyperframes/core/color-grading";
5
+ import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
9
6
  import { readAllAnimatedProperties, readGsapProperty } from "./gsapRuntimeReaders";
10
7
 
11
8
  /**
@@ -68,46 +65,14 @@ describe("readAllAnimatedProperties group filter", () => {
68
65
  });
69
66
 
70
67
  describe("color-grading opacity truth", () => {
71
- function gradedElement(): HTMLElement {
68
+ it("reads a graded source's opacity from GSAP, as for any element", () => {
72
69
  const el = document.createElement("img");
73
70
  el.id = "clip";
74
- el.setAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR, "");
75
- const canvas = document.createElement("canvas");
76
- canvas.id = `${HF_COLOR_GRADING_CANVAS_ID_PREFIX}clip`;
77
- canvas.style.opacity = "0.98";
78
- document.body.append(el, canvas);
79
- return el;
80
- }
81
-
82
- it("resolves opacity from the grading canvas, not the runtime hide", () => {
83
- const el = gradedElement();
84
- const iframe = fakeIframe(el, { gsapValues: { opacity: 0 } });
85
- const anim = {
86
- id: "#clip-from-200-visual",
87
- targetSelector: "#clip",
88
- method: "from",
89
- properties: { opacity: 0.5 },
90
- } as unknown as GsapAnimation;
91
-
92
- const result = readAllAnimatedProperties(iframe, "#clip", anim);
93
-
94
- expect(result.opacity).toBe(0.98);
95
- });
96
-
97
- it("readGsapProperty takes the same detour", () => {
98
- const el = gradedElement();
99
- const iframe = fakeIframe(el, { gsapValues: { opacity: 0 } });
100
-
101
- expect(readGsapProperty(iframe, "#clip", "opacity")).toBe(0.98);
102
- });
103
-
104
- it("reads GSAP directly when the source is not grading-hidden", () => {
105
- const el = document.createElement("div");
106
- el.id = "clip";
71
+ el.setAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR, "true");
107
72
  document.body.appendChild(el);
108
- const iframe = fakeIframe(el, { gsapValues: { opacity: 0.3 } });
73
+ const iframe = fakeIframe(el, { gsapValues: { opacity: 0.98 } });
109
74
 
110
- expect(readGsapProperty(iframe, "#clip", "opacity")).toBe(0.3);
75
+ expect(readGsapProperty(iframe, "#clip", "opacity")).toBe(0.98);
111
76
  });
112
77
  });
113
78
 
@@ -3,34 +3,10 @@
3
3
  */
4
4
  import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
5
5
  import { classifyPropertyGroup, type PropertyGroupName } from "@hyperframes/core/gsap-parser";
6
- import {
7
- COLOR_GRADING_SOURCE_HIDDEN_ATTR,
8
- HF_COLOR_GRADING_CANVAS_ID_PREFIX,
9
- } from "@hyperframes/core/color-grading";
10
- import { getIframeGsap, queryIframeElement, type IframeGsap } from "./gsapShared";
6
+ import { getIframeGsap, queryIframeElement } from "./gsapShared";
11
7
  import { gsapWritesChannels } from "./gsapRuntimeKeyframes";
12
8
  import { roundTo3 } from "../utils/rounding";
13
9
 
14
- /**
15
- * The element's live value for `prop` as GSAP drives it. Opacity on a
16
- * color-grading-hidden source needs a detour: the runtime hides the source
17
- * with inline `opacity: 0 !important`, so computed opacity is the hide, not
18
- * the animated value. The grading canvas mirrors the source's effective
19
- * opacity every frame, so it is the truth for that one property — reading the
20
- * raw 0 here is what bakes `opacity: 0` into committed keyframes.
21
- */
22
- function readLiveGsapValue(gsap: IframeGsap, el: Element, prop: string): number {
23
- if (prop === "opacity" && el.getAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR) != null && el.id) {
24
- const canvas = el.ownerDocument.getElementById(HF_COLOR_GRADING_CANVAS_ID_PREFIX + el.id);
25
- const win = el.ownerDocument.defaultView;
26
- if (canvas && win) {
27
- const val = Number(win.getComputedStyle(canvas).opacity);
28
- if (Number.isFinite(val)) return val;
29
- }
30
- }
31
- return Number(gsap.getProperty(el, prop));
32
- }
33
-
34
10
  export function readGsapProperty(
35
11
  iframe: HTMLIFrameElement | null,
36
12
  selector: string | null,
@@ -42,7 +18,7 @@ export function readGsapProperty(
42
18
  const el = queryIframeElement(iframe, selector);
43
19
  if (!el) return null;
44
20
  try {
45
- const val = readLiveGsapValue(gsap, el, prop);
21
+ const val = Number(gsap.getProperty(el, prop));
46
22
  if (!Number.isFinite(val)) return null;
47
23
  return POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
48
24
  } catch {
@@ -89,7 +65,7 @@ export function readAllAnimatedProperties(
89
65
  const groupedPropKeys = new Set([...propKeys].filter(inGroup));
90
66
 
91
67
  for (const prop of groupedPropKeys) {
92
- const val = readLiveGsapValue(gsap, el, prop);
68
+ const val = Number(gsap.getProperty(el, prop));
93
69
  if (Number.isFinite(val)) {
94
70
  result[prop] = POSITION_PROPS.has(prop) ? Math.round(val) : roundTo3(val);
95
71
  }
@@ -837,6 +837,26 @@ describe("external file change coordinator", () => {
837
837
  });
838
838
  });
839
839
 
840
+ // Studio settles which composition is open just after load, while the draft's file stays the same.
841
+ it("keeps a restored draft when the open composition changes but the draft's file does not", async () => {
842
+ const { captured, rerender } = await mountCoordinator({
843
+ recoveryFilePath: "index.html",
844
+ loadConflictSnapshot: vi.fn(async () => ({
845
+ kind: "conflict" as const,
846
+ projectId: "project-a",
847
+ filePath: "index.html",
848
+ externalVersion: "v2",
849
+ externalContent: "external",
850
+ studioContent: "studio",
851
+ createdAt: 100,
852
+ })),
853
+ });
854
+ await vi.waitFor(() => expect(captured.handle?.blocked?.status).toBe("conflict"));
855
+
856
+ await rerender({ activeCompPath: null });
857
+ await vi.waitFor(() => expect(captured.handle?.blocked?.status).toBe("conflict"));
858
+ });
859
+
840
860
  it("retains the final local candidate when a drain fails", async () => {
841
861
  const failure = new Error("network unavailable");
842
862
  const persistFailureSnapshot = vi.fn(async () => undefined);
@@ -248,7 +248,7 @@ export function useExternalFileChangeCoordinator({
248
248
  return () => {
249
249
  cancelled = true;
250
250
  };
251
- }, [loadConflictSnapshot, projectId, recoveryFilePath, setBlocked]);
251
+ }, [loadConflictSnapshot, projectId, activeCompPath, recoveryFilePath, setBlocked]);
252
252
 
253
253
  // What a settled change owes: thumbnails (unless its own write's echo brings them), then reloads.
254
254
  const deliverOwed = useCallback(
package/src/index.ts CHANGED
@@ -46,6 +46,23 @@ export {
46
46
  } from "./player";
47
47
  export { usePreviewIframeStore } from "./player/store/previewIframeStore";
48
48
  export { previewEditingClient, previewFrameOpaque } from "./player/lib/previewChannel";
49
+ export {
50
+ describePreviewElements,
51
+ previewAncestors,
52
+ previewElementsAtPoint,
53
+ previewGeometry,
54
+ previewLayers,
55
+ previewPointerTargets,
56
+ queryPreviewElements,
57
+ type PreviewElement,
58
+ type PreviewElementHit,
59
+ } from "./player/lib/previewElements";
60
+ export {
61
+ findPreviewElementForSelection,
62
+ findPreviewElementForTimelineElement,
63
+ readable,
64
+ standInFor,
65
+ } from "./components/editor/previewSelection";
49
66
  export { PREVIEW_QUALITY_LEVELS, type PreviewQuality } from "@hyperframes/core/preview-quality";
50
67
  export type {
51
68
  PlaybackHealth,
@@ -86,12 +86,13 @@ export function setStudioKeys(overrides: Partial<Record<StudioKeyAction, string>
86
86
  export const getStudioKeys = (): StudioKeys => current;
87
87
  export const getStudioKey = (action: StudioKeyAction): string => current[action];
88
88
 
89
- function subscribe(listener: () => void) {
89
+ export function subscribeStudioKeys(listener: () => void) {
90
90
  listeners.add(listener);
91
91
  return () => listeners.delete(listener);
92
92
  }
93
93
 
94
- export const useStudioKeys = (): StudioKeys => useSyncExternalStore(subscribe, getStudioKeys);
94
+ export const useStudioKeys = (): StudioKeys =>
95
+ useSyncExternalStore(subscribeStudioKeys, getStudioKeys);
95
96
 
96
97
  export function useShortcutSections(host?: readonly ShortcutSection[]): readonly ShortcutSection[] {
97
98
  const keys = useStudioKeys();
@@ -157,12 +157,14 @@ export async function paintShadow(getApi: () => TimelinePlayerApi, shadow: HTMLI
157
157
  export function serveEditingRequests(
158
158
  frame: Record<string, unknown>,
159
159
  answer: (kind: string, params: unknown) => unknown,
160
+ onPort?: (port: MessagePort) => void,
160
161
  ): () => void {
161
162
  const ports: MessagePort[] = [];
162
163
  frame.postMessage = (message: { type?: string } | null) => {
163
164
  if (message?.type !== "editing-connect") return;
164
165
  const { port1, port2 } = new MessageChannel();
165
166
  ports.push(port1);
167
+ onPort?.(port1);
166
168
  port1.onmessage = (event: MessageEvent<{ id: number; kind: string; params: unknown }>) => {
167
169
  const { id, kind, params } = event.data;
168
170
  port1.postMessage({ v: 1, id, ok: true, result: answer(kind, params) });
@@ -1,11 +1,12 @@
1
1
  // @vitest-environment happy-dom
2
2
 
3
- import { describe, expect, it } from "vitest";
3
+ import { describe, expect, it, vi } from "vitest";
4
4
  import {
5
5
  collectSubCompositionDomChildren,
6
6
  collectSubCompositionHostState,
7
+ hydrateTimelineFromPreview,
7
8
  } from "./timelineSyncHydration";
8
- import type { ClipManifestClip } from "../lib/playbackTypes";
9
+ import type { ClipManifestClip, PlaybackAdapter } from "../lib/playbackTypes";
9
10
 
10
11
  const clip = (over: Partial<ClipManifestClip>): ClipManifestClip => ({
11
12
  id: "x",
@@ -138,3 +139,28 @@ describe("collectSubCompositionHostState", () => {
138
139
  expect(state.size).toBe(0);
139
140
  });
140
141
  });
142
+
143
+ describe("hydrateTimelineFromPreview", () => {
144
+ it("attaches the shortcut listeners to a frame whose document it cannot read", () => {
145
+ const frame = {};
146
+ Object.defineProperty(frame, "document", {
147
+ get: () => {
148
+ throw new DOMException("blocked", "SecurityError");
149
+ },
150
+ });
151
+ const iframe = document.createElement("iframe");
152
+ Object.defineProperty(iframe, "contentWindow", { value: frame });
153
+ Object.defineProperty(iframe, "contentDocument", { value: null });
154
+ const attachIframeShortcutListeners = vi.fn();
155
+ hydrateTimelineFromPreview({
156
+ iframe,
157
+ adapter: { getDuration: () => 1 } as unknown as PlaybackAdapter,
158
+ processTimelineMessage: vi.fn(),
159
+ enrichMissingCompositions: vi.fn(),
160
+ applyPreviewAudioState: vi.fn(),
161
+ attachIframeShortcutListeners,
162
+ syncTimelineElements: vi.fn(),
163
+ });
164
+ expect(attachIframeShortcutListeners).toHaveBeenCalledOnce();
165
+ });
166
+ });
@@ -419,15 +419,10 @@ export interface HydrateTimelineFromPreviewInput {
419
419
  * cross-origin or mid-navigation frame, and none of them is worth failing the
420
420
  * adapter's initialisation over.
421
421
  */
422
- function normalizePreviewDom(
423
- doc: Document | null,
424
- iframeWin: IframeWindow | null,
425
- attachIframeShortcutListeners: () => void,
426
- ): void {
422
+ function normalizePreviewDom(doc: Document | null, iframeWin: IframeWindow | null): void {
427
423
  if (!doc || !iframeWin) return;
428
424
  normalizePreviewViewport(doc, iframeWin);
429
425
  autoHealMissingCompositionIds(doc);
430
- attachIframeShortcutListeners();
431
426
  }
432
427
 
433
428
  /** Hand the runtime's own clip manifest to the timeline, if it published one. */
@@ -444,7 +439,8 @@ export function hydrateTimelineFromPreview(input: HydrateTimelineFromPreviewInpu
444
439
  try {
445
440
  const doc = safeContentDocument(iframe);
446
441
  const iframeWin = (iframe?.contentWindow as IframeWindow | null) ?? null;
447
- normalizePreviewDom(doc, iframeWin, input.attachIframeShortcutListeners);
442
+ normalizePreviewDom(doc, iframeWin);
443
+ input.attachIframeShortcutListeners();
448
444
  applyRuntimeClipManifest(iframeWin, input.processTimelineMessage);
449
445
  input.enrichMissingCompositions();
450
446
  input.applyPreviewAudioState();
@@ -8,6 +8,7 @@ import { usePlaybackKeyboard } from "./usePlaybackKeyboard";
8
8
  import { usePlayerStore } from "../store/playerStore";
9
9
  import { setStudioKeys } from "../components/studioShortcuts";
10
10
  import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
11
+ import { detachedFakeIframe, serveEditingRequests } from "./timelinePlayerTestHarness";
11
12
 
12
13
  globalThis.IS_REACT_ACT_ENVIRONMENT = true;
13
14
 
@@ -28,10 +29,11 @@ interface Spies {
28
29
  interface HookHandle {
29
30
  dispatch: (event: KeyboardEvent) => void;
30
31
  release: (event: KeyboardEvent) => void;
32
+ attach: () => void;
31
33
  spies: Spies;
32
34
  }
33
35
 
34
- function setupHook(): HookHandle {
36
+ function setupHook(iframe: HTMLIFrameElement | null = null): HookHandle {
35
37
  const spies: Spies = {
36
38
  seek: vi.fn(),
37
39
  play: vi.fn(),
@@ -42,7 +44,7 @@ function setupHook(): HookHandle {
42
44
  let captured: ReturnType<typeof usePlaybackKeyboard> | null = null;
43
45
 
44
46
  function Harness() {
45
- const iframeRef = React.useRef<HTMLIFrameElement | null>(null);
47
+ const iframeRef = React.useRef<HTMLIFrameElement | null>(iframe);
46
48
  const shuttleDirectionRef = React.useRef<"forward" | "backward" | null>(null);
47
49
  const shuttleSpeedIndexRef = React.useRef(0);
48
50
  const iframeShortcutCleanupRef = React.useRef<(() => void) | null>(null);
@@ -72,6 +74,7 @@ function setupHook(): HookHandle {
72
74
  return {
73
75
  dispatch: (event) => captured!.playbackKeyDownRef.current(event),
74
76
  release: (event) => captured!.playbackKeyUpRef.current(event),
77
+ attach: () => captured!.attachIframeShortcutListeners(),
75
78
  spies,
76
79
  };
77
80
  }
@@ -483,3 +486,105 @@ describe("usePlaybackKeyboard: modifier combos and named keys", () => {
483
486
  expect(spies.playBackward).not.toHaveBeenCalled();
484
487
  });
485
488
  });
489
+
490
+ describe("usePlaybackKeyboard: a sealed preview frame", () => {
491
+ const closers: Array<() => void> = [];
492
+ afterEach(() => closers.splice(0).forEach((close) => close()));
493
+
494
+ function sealedFrame() {
495
+ const frame: Record<string, unknown> = {};
496
+ const iframe = detachedFakeIframe(frame);
497
+ Object.defineProperty(iframe, "contentDocument", { value: null });
498
+ Object.defineProperty(frame, "document", {
499
+ get: () => {
500
+ throw new DOMException("blocked", "SecurityError");
501
+ },
502
+ });
503
+ const watched: string[][] = [];
504
+ let port: MessagePort | null = null;
505
+ closers.push(
506
+ serveEditingRequests(
507
+ frame,
508
+ (kind, params) => {
509
+ if (kind !== "watch-keys") return null;
510
+ const { combos } = params as { combos: string[] };
511
+ watched.push(combos);
512
+ return { watching: combos.length };
513
+ },
514
+ (framePort) => (port = framePort),
515
+ ),
516
+ );
517
+ const forward = (type: "keydown" | "keyup", key: string, code: string) =>
518
+ port!.postMessage({
519
+ v: 1,
520
+ event: "key",
521
+ key: {
522
+ type,
523
+ key,
524
+ code,
525
+ altKey: false,
526
+ ctrlKey: false,
527
+ metaKey: false,
528
+ shiftKey: false,
529
+ repeat: false,
530
+ },
531
+ });
532
+ return { iframe, watched, forward };
533
+ }
534
+
535
+ it("asks the frame for exactly the playback keys, and again when they are remapped", async () => {
536
+ const { iframe, watched } = sealedFrame();
537
+ setupHook(iframe).attach();
538
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
539
+ expect(new Set(watched[0])).toEqual(
540
+ new Set([
541
+ "Space",
542
+ "ArrowLeft",
543
+ "ArrowRight",
544
+ "shift+ArrowLeft",
545
+ "shift+ArrowRight",
546
+ "m",
547
+ "shift+l",
548
+ "k",
549
+ "j",
550
+ "l",
551
+ "i",
552
+ "shift+i",
553
+ "o",
554
+ "shift+o",
555
+ "a",
556
+ "e",
557
+ ]),
558
+ );
559
+ act(() => setStudioKeys({ playPause: "p" }));
560
+ await vi.waitFor(() => expect(watched).toHaveLength(2));
561
+ expect(watched[1]).toContain("p");
562
+ expect(watched[1]).not.toContain("Space");
563
+ });
564
+
565
+ it("plays and steps from the keys the frame forwards, keyups included", async () => {
566
+ const { iframe, watched, forward } = sealedFrame();
567
+ const { attach, spies } = setupHook(iframe);
568
+ attach();
569
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
570
+ forward("keydown", " ", "Space");
571
+ await vi.waitFor(() => expect(spies.play).toHaveBeenCalledOnce());
572
+ forward("keydown", "k", "KeyK");
573
+ forward("keydown", "l", "KeyL");
574
+ await vi.waitFor(() => expect(spies.seek).toHaveBeenCalledOnce());
575
+ forward("keyup", "k", "KeyK");
576
+ forward("keydown", "l", "KeyL");
577
+ await vi.waitFor(() => expect(spies.play).toHaveBeenCalledTimes(2));
578
+ });
579
+
580
+ it("stops watching when its listeners are replaced", async () => {
581
+ const { iframe, watched } = sealedFrame();
582
+ const { attach } = setupHook(iframe);
583
+ attach();
584
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
585
+ attach();
586
+ await vi.waitFor(() => expect(watched).toHaveLength(3));
587
+ expect(watched[1]).toEqual([]);
588
+ expect(watched[2]).toEqual(watched[0]);
589
+ });
590
+ });
@@ -15,7 +15,13 @@ import {
15
15
  } from "../lib/playbackShortcuts";
16
16
  import { canvasNudgeKeysClaimed } from "../../utils/canvasNudgeGate";
17
17
  import { usePlayerStore } from "../store/playerStore";
18
- import { matchesKey, type StudioKeyAction } from "../components/studioShortcuts";
18
+ import {
19
+ getStudioKey,
20
+ matchesKey,
21
+ subscribeStudioKeys,
22
+ type StudioKeyAction,
23
+ } from "../components/studioShortcuts";
24
+ import { previewEditingClient, previewFrameOpaque } from "../lib/previewChannel";
19
25
  import { resolveCanvasNudgeDelta } from "../../components/editor/domEditNudge";
20
26
  import { stepFrameTime } from "../lib/time";
21
27
  import { useLinkedClipPreferences } from "../../utils/linkedClipPreferences";
@@ -67,6 +73,28 @@ function ignoresPlaybackKey(e: KeyboardEvent): boolean {
67
73
  });
68
74
  }
69
75
 
76
+ type KeyHandlerRef = React.RefObject<(e: KeyboardEvent) => void>;
77
+
78
+ function forwardSealedFrameKeys(
79
+ iframe: HTMLIFrameElement,
80
+ keyDown: KeyHandlerRef,
81
+ keyUp: KeyHandlerRef,
82
+ ): () => void {
83
+ const client = previewEditingClient(iframe);
84
+ const watch = (combos: string[]) => void client.request("watch-keys", { combos }).catch(() => {});
85
+ const watchPlayback = () => watch(PLAYBACK_ACTIONS.map(getStudioKey));
86
+ watchPlayback();
87
+ const stopRebinds = subscribeStudioKeys(watchPlayback);
88
+ const stopKeys = client.onKey((key) =>
89
+ (key.type === "keydown" ? keyDown : keyUp).current(new KeyboardEvent(key.type, key)),
90
+ );
91
+ return () => {
92
+ stopRebinds();
93
+ stopKeys();
94
+ watch([]);
95
+ };
96
+ }
97
+
70
98
  function handleWorkAreaKey(
71
99
  e: KeyboardEvent,
72
100
  action: PlaybackAction,
@@ -198,6 +226,15 @@ export function usePlaybackKeyboard({
198
226
  const attachIframeShortcutListeners = useCallback(() => {
199
227
  iframeShortcutCleanupRef.current?.();
200
228
  iframeShortcutCleanupRef.current = null;
229
+ const iframe = iframeRef.current;
230
+ if (iframe && previewFrameOpaque(iframe)) {
231
+ iframeShortcutCleanupRef.current = forwardSealedFrameKeys(
232
+ iframe,
233
+ playbackKeyDownRef,
234
+ playbackKeyUpRef,
235
+ );
236
+ return;
237
+ }
201
238
 
202
239
  let iframeWin: Window | null = null;
203
240
  let iframeDoc: Document | null = null;