@hyperframes/studio 0.9.63 → 0.9.64

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.
@@ -211,145 +211,26 @@ describe("setPreviewMediaVolume", () => {
211
211
  });
212
212
 
213
213
  describe("scrubPreviewAudio", () => {
214
- it("scales scrub feedback by the Studio preview volume", () => {
215
- const iframe = document.createElement("iframe");
216
- document.body.append(iframe);
217
- const audio = iframe.contentDocument?.createElement("audio");
218
- if (!audio || !iframe.contentDocument?.body) throw new Error("expected iframe audio document");
219
- audio.id = "music";
220
- audio.play = vi.fn(async () => {});
221
- audio.pause = vi.fn();
222
- iframe.contentDocument.body.append(audio);
223
-
224
- scrubPreviewAudio(iframe, 0.5, { id: "music" }, 0.4);
225
-
226
- expect(audio.volume).toBeCloseTo(0.1);
227
- stopScrubPreviewAudio();
228
- });
229
-
230
- /**
231
- * The preview document is a different realm, so `instanceof HTMLAudioElement`
232
- * is false for every node in it. That threw the `music` hint away and left
233
- * the first `<audio>` in the document as the only route — and the first
234
- * `<audio>` is often the voiceover, so scrubbing previewed the wrong track.
235
- * Two elements, music second, is what tells the two paths apart: with one
236
- * element the fallback reaches the right node by accident.
237
- */
238
- it("previews the track named by the music row, not the first audio in the document", () => {
239
- const iframe = document.createElement("iframe");
240
- document.body.append(iframe);
241
- const previewDoc = iframe.contentDocument;
242
- if (!previewDoc?.body) throw new Error("expected an iframe document");
243
-
244
- const voiceover = previewDoc.createElement("audio");
245
- voiceover.id = "voiceover";
246
- voiceover.play = vi.fn(async () => {});
247
- voiceover.pause = vi.fn();
248
-
249
- const music = previewDoc.createElement("audio");
250
- music.id = "music-bed";
251
- music.play = vi.fn(async () => {});
252
- music.pause = vi.fn();
253
-
254
- previewDoc.body.append(voiceover, music);
255
-
256
- // The node really is cross-realm; this is the condition, not a contrivance.
257
- expect(music instanceof HTMLAudioElement).toBe(false);
258
-
259
- scrubPreviewAudio(iframe, 0.5, { id: "music-bed" }, 1);
260
-
261
- expect(music.play).toHaveBeenCalled();
262
- expect(voiceover.play).not.toHaveBeenCalled();
263
- stopScrubPreviewAudio();
264
- });
265
-
266
- it("previews the music row's own track when a sub-composition repeats its id", () => {
267
- const iframe = document.createElement("iframe");
268
- document.body.append(iframe);
269
- const previewDoc = iframe.contentDocument;
270
- if (!previewDoc?.body) throw new Error("expected an iframe document");
271
- previewDoc.body.innerHTML =
272
- '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><audio id="music"></audio></div>' +
273
- '<audio id="music" class="root"></audio>';
274
- const [inner, root] = Array.from(previewDoc.querySelectorAll("audio"));
275
- for (const audio of [inner, root])
276
- Object.assign(audio!, { play: vi.fn(async () => {}), pause: vi.fn() });
277
-
278
- scrubPreviewAudio(iframe, 0.5, { id: "music" }, 1);
279
-
280
- expect(root!.play).toHaveBeenCalled();
281
- expect(inner!.play).not.toHaveBeenCalled();
282
- stopScrubPreviewAudio();
283
- });
284
-
285
- /** An edit to a sub-composition rebuilds the media inside it, so the music row can
286
- * name a track that is not in the preview for a moment. Auditioning whatever audio
287
- * came first then previews the voiceover, which is not the track being scrubbed. */
288
- it("previews nothing when the music row's own track is not in the preview", () => {
289
- const iframe = document.createElement("iframe");
290
- document.body.append(iframe);
291
- const previewDoc = iframe.contentDocument;
292
- if (!previewDoc?.body) throw new Error("expected an iframe document");
293
-
294
- const voiceover = previewDoc.createElement("audio");
295
- voiceover.id = "voiceover";
296
- voiceover.play = vi.fn(async () => {});
297
- voiceover.pause = vi.fn();
298
- previewDoc.body.append(voiceover);
299
-
300
- scrubPreviewAudio(iframe, 0.5, { id: "music-bed" }, 1);
301
-
302
- expect(voiceover.play).not.toHaveBeenCalled();
303
- expect(voiceover.volume).toBe(1);
304
- stopScrubPreviewAudio();
305
- });
306
-
307
- it("still previews the track marked as the music when the row's own id is gone", () => {
308
- const iframe = document.createElement("iframe");
309
- document.body.append(iframe);
310
- const previewDoc = iframe.contentDocument;
311
- if (!previewDoc?.body) throw new Error("expected an iframe document");
312
- previewDoc.body.innerHTML =
313
- '<audio id="voiceover"></audio><audio id="bed" data-timeline-role="music"></audio>';
314
- const [voiceover, bed] = Array.from(previewDoc.querySelectorAll("audio"));
315
- for (const audio of [voiceover, bed])
316
- Object.assign(audio!, { play: vi.fn(async () => {}), pause: vi.fn() });
317
-
318
- scrubPreviewAudio(iframe, 0.5, { id: "music-bed" }, 1);
319
-
320
- expect(bed!.play).toHaveBeenCalled();
321
- expect(voiceover!.play).not.toHaveBeenCalled();
322
- stopScrubPreviewAudio();
323
- });
324
-
325
- /** A scrub audition is media running under a paused clock, which the runtime now
326
- * stops on sight. So it borrows the element. That a leased element survives the
327
- * tick is asserted runtime-side in core's `transportPark.test.ts`; here the
328
- * contract is that the hook is called with the right element and given back. */
329
- it("borrows the element from the runtime for the audition and returns it on stop", () => {
330
- const iframe = document.createElement("iframe");
331
- document.body.append(iframe);
332
- const previewDoc = iframe.contentDocument;
333
- if (!previewDoc?.body) throw new Error("expected an iframe document");
334
-
335
- const music = previewDoc.createElement("audio");
336
- music.id = "music";
337
- music.play = vi.fn(async () => {});
338
- music.pause = vi.fn();
339
- previewDoc.body.append(music);
340
-
341
- const leasePausedMedia = vi.fn();
342
- const releasePausedMedia = vi.fn();
343
- (previewDoc.defaultView as IframeWindow).__hf = { leasePausedMedia, releasePausedMedia };
344
-
345
- scrubPreviewAudio(iframe, 0.5, { id: "music" }, 1);
346
-
347
- expect(leasePausedMedia).toHaveBeenCalledWith(music);
348
- expect(releasePausedMedia).not.toHaveBeenCalled();
349
-
214
+ // fails without the fix: Studio played the track through the frame's document, which a sealed frame does not give it.
215
+ it("asks a sealed preview's runtime to play the music row's track, and to stop", () => {
216
+ const postMessage = vi.fn();
217
+ const iframe = {
218
+ contentDocument: null,
219
+ contentWindow: { postMessage },
220
+ } as unknown as HTMLIFrameElement;
221
+
222
+ scrubPreviewAudio(iframe, 0.5, { id: "music", hfId: "a1", sourceFile: "index.html" }, 0.4);
350
223
  stopScrubPreviewAudio();
351
224
 
352
- expect(releasePausedMedia).toHaveBeenCalledWith(music);
225
+ expect(postMessage.mock.calls.map(([message]) => message)).toEqual([
226
+ expect.objectContaining({
227
+ action: "scrub-audio",
228
+ time: 0.5,
229
+ volume: 0.4,
230
+ target: { id: "music", hfId: "a1", sourceFile: "index.html" },
231
+ }),
232
+ expect.objectContaining({ action: "scrub-audio", time: null }),
233
+ ]);
353
234
  });
354
235
  });
355
236
 
@@ -208,73 +208,9 @@ export function resolveIframe(el: Element | null): HTMLIFrameElement | null {
208
208
  // ---------------------------------------------------------------------------
209
209
  // Audio scrubbing
210
210
  // ---------------------------------------------------------------------------
211
- // Plays a brief slice of the music track while the user drags the playhead,
212
- // like an NLE scrub. Repeated calls keep playback alive; it auto-pauses shortly
213
- // after scrubbing stops and restores the element's prior muted state.
211
+ // The preview's runtime plays the slice, so a sealed frame scrubs as an open one does.
214
212
 
215
- const SCRUB_VOLUME = 0.25;
216
-
217
- let scrubAudioEl: HTMLAudioElement | null = null;
218
- let scrubStopTimer: ReturnType<typeof setTimeout> | null = null;
219
- let scrubPrevMuted: boolean | null = null;
220
- let scrubPrevVolume: number | null = null;
221
-
222
- // Resolve the SAME element the store identified as music: prefer that row's own
223
- // element, then the role attribute, and only fall back to the first <audio>
224
- // (which could be a voiceover, so the row hint matters).
225
- /**
226
- * `doc` is the preview iframe's document, so its `<audio>` nodes are instances of
227
- * the IFRAME's `HTMLAudioElement`, never this module's. `instanceof
228
- * HTMLAudioElement` here is false for every one of them, which silently threw the
229
- * `music` hint away and fell through to "first `<audio>` in the document" — the
230
- * very thing the comment above warns can be a voiceover. Ask what the node IS.
231
- * Same rule and same reasoning as packages/core/src/runtime/domRealm.ts.
232
- */
233
- function isAudioNode(node: Element | null): node is HTMLAudioElement {
234
- return (
235
- node !== null &&
236
- node.namespaceURI === "http://www.w3.org/1999/xhtml" &&
237
- node.localName === "audio"
238
- );
239
- }
240
-
241
- function resolveScrubAudioEl(doc: Document, music?: PreviewTarget | null): HTMLAudioElement | null {
242
- if (music) {
243
- const byId = previewElementFinder(doc, "audio")(music);
244
- if (isAudioNode(byId)) return byId;
245
- }
246
- return doc.querySelector<HTMLAudioElement>("audio[data-timeline-role='music']");
247
- }
248
-
249
- /** The runtime stops any media running under a paused clock, and a scrub audition
250
- * IS media running under a paused clock, so it has to borrow the element. Every
251
- * hop is optional: a runtime predating the hook must no-op, not throw. Wrapped in
252
- * named calls so `applyScrub` does not carry the optional chains' branches. */
253
- function leaseScrubElement(el: HTMLAudioElement): void {
254
- (el.ownerDocument.defaultView as IframeWindow | null)?.__hf?.leasePausedMedia?.(el);
255
- }
256
-
257
- function releaseScrubElement(el: HTMLAudioElement): void {
258
- (el.ownerDocument.defaultView as IframeWindow | null)?.__hf?.releasePausedMedia?.(el);
259
- }
260
-
261
- function applyScrub(el: HTMLAudioElement, audioFileTime: number, previewVolume: number): void {
262
- if (scrubAudioEl && scrubAudioEl !== el) stopScrubPreviewAudio();
263
- if (scrubPrevMuted === null) scrubPrevMuted = el.muted;
264
- if (scrubPrevVolume === null) scrubPrevVolume = el.volume;
265
- scrubAudioEl = el;
266
- leaseScrubElement(el);
267
- try {
268
- el.muted = false;
269
- el.volume = SCRUB_VOLUME * normalizePreviewVolume(previewVolume);
270
- if (Math.abs(el.currentTime - audioFileTime) > 0.04) el.currentTime = audioFileTime;
271
- if (el.paused) void el.play().catch(() => {});
272
- } catch {
273
- /* element not ready */
274
- }
275
- if (scrubStopTimer) clearTimeout(scrubStopTimer);
276
- scrubStopTimer = setTimeout(stopScrubPreviewAudio, 140);
277
- }
213
+ let scrubFrame: Window | null = null;
278
214
 
279
215
  /**
280
216
  * Scrub the preview music audio to `audioFileTime` (seconds into the source
@@ -291,37 +227,22 @@ export function scrubPreviewAudio(
291
227
  stopScrubPreviewAudio();
292
228
  return;
293
229
  }
294
- let doc: Document | null = null;
295
- try {
296
- doc = iframe.contentDocument;
297
- } catch {
298
- return;
299
- }
300
- if (!doc) return;
301
- const el = resolveScrubAudioEl(doc, music);
302
- if (el) applyScrub(el, audioFileTime, previewVolume);
230
+ const frame = iframe.contentWindow;
231
+ if (scrubFrame && scrubFrame !== frame) stopScrubPreviewAudio();
232
+ scrubFrame = frame;
233
+ const target = music
234
+ ? { id: music.id, hfId: music.hfId, domId: music.domId, sourceFile: music.sourceFile }
235
+ : null;
236
+ postRuntimeControlMessage(frame, "scrub-audio", {
237
+ target,
238
+ time: audioFileTime,
239
+ volume: normalizePreviewVolume(previewVolume),
240
+ });
303
241
  }
304
242
 
305
243
  export function stopScrubPreviewAudio(): void {
306
- if (scrubStopTimer) {
307
- clearTimeout(scrubStopTimer);
308
- scrubStopTimer = null;
309
- }
310
- const el = scrubAudioEl;
311
- scrubAudioEl = null;
312
- if (!el) return;
313
- // `scrubStopTimer` guarantees this runs within ~140 ms of the last scrub, so
314
- // the borrow cannot outlive the audition.
315
- releaseScrubElement(el);
316
- try {
317
- el.pause();
318
- if (scrubPrevMuted !== null) el.muted = scrubPrevMuted;
319
- if (scrubPrevVolume !== null) el.volume = scrubPrevVolume;
320
- } catch {
321
- /* ignore */
322
- }
323
- scrubPrevMuted = null;
324
- scrubPrevVolume = null;
244
+ postRuntimeControlMessage(scrubFrame, "scrub-audio", { time: null });
245
+ scrubFrame = null;
325
246
  }
326
247
 
327
248
  // ---------------------------------------------------------------------------