@hyperframes/studio 0.9.59 → 0.9.63

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 (61) hide show
  1. package/dist/assets/{hyperframes-player-bya4hgms.js → hyperframes-player-CUQxAJaE.js} +1 -1
  2. package/dist/assets/{index--dcfSUzI.js → index-D3rdYBVx.js} +1 -1
  3. package/dist/assets/{index-Bxh5lW0C.js → index-DSrTQv-k.js} +204 -204
  4. package/dist/assets/{pausedVideoDecoder-BKym1jA6.js → pausedVideoDecoder-BWllfjF-.js} +1 -1
  5. package/dist/{chunk-G6FJSL7X.js → chunk-JTUKMELR.js} +34 -6
  6. package/dist/{chunk-5EEM5WO4.js → chunk-ZUDVUI7K.js} +11 -1
  7. package/dist/index.d.ts +28 -1
  8. package/dist/index.html +1 -1
  9. package/dist/index.js +1815 -1104
  10. package/dist/player.js +2 -2
  11. package/dist/ui.js +1 -1
  12. package/package.json +8 -8
  13. package/src/captions/components/CaptionOverlay.sealed.test.ts +273 -0
  14. package/src/captions/components/CaptionOverlay.tsx +112 -57
  15. package/src/captions/components/CaptionOverlayUtils.ts +319 -33
  16. package/src/captions/components/CaptionPropertyPanel.tsx +17 -0
  17. package/src/components/editor/LayersPanel.opaque.test.ts +2 -2
  18. package/src/components/editor/previewDrafts.test.ts +2 -2
  19. package/src/components/editor/previewGestureStartRead.test.ts +2 -2
  20. package/src/components/editor/previewLayers.test.ts +2 -2
  21. package/src/components/editor/previewOverlayRects.test.ts +2 -2
  22. package/src/components/editor/previewPointerTargets.test.ts +2 -2
  23. package/src/components/editor/previewSelection.test.ts +2 -2
  24. package/src/components/editor/useColorGradingController.sealed.test.ts +165 -0
  25. package/src/components/editor/useColorGradingController.ts +20 -1
  26. package/src/components/editor/useColorGradingPreviews.ts +127 -43
  27. package/src/components/nle/AudioMeterStrip.tsx +63 -2
  28. package/src/components/nle/NLEPreview.test.ts +24 -0
  29. package/src/components/nle/NLEPreview.tsx +2 -6
  30. package/src/components/nle/audioSealedPreview.test.ts +254 -0
  31. package/src/components/nle/previewStage.ts +11 -1
  32. package/src/components/nle/zLaneGesture.test.ts +67 -0
  33. package/src/components/nle/zLaneGesture.ts +4 -0
  34. package/src/components/panels/VariablesPanel.test.tsx +90 -1
  35. package/src/components/panels/VariablesPanel.tsx +41 -17
  36. package/src/components/panels/renderHandoff.test.ts +86 -0
  37. package/src/components/panels/renderHandoff.ts +28 -0
  38. package/src/components/ui/Menu.test.tsx +77 -0
  39. package/src/components/ui/Menu.tsx +47 -4
  40. package/src/components/ui/Popover.tsx +5 -2
  41. package/src/elementAnimations.test.ts +13 -0
  42. package/src/hooks/timelineAudioGroupCreate.ts +57 -7
  43. package/src/hooks/timelineAudioGroupVolume.ts +110 -34
  44. package/src/hooks/useCaptionDetection.ts +175 -54
  45. package/src/hooks/usePersistentEditHistory.test.ts +84 -0
  46. package/src/hooks/usePersistentEditHistory.ts +36 -3
  47. package/src/index.ts +1 -0
  48. package/src/main.tsx +14 -11
  49. package/src/player/components/Timeline.newTrack.test.tsx +106 -0
  50. package/src/player/components/TimelineLanes.tsx +4 -2
  51. package/src/player/components/TimelineTrackHeader.tsx +12 -4
  52. package/src/player/components/clipMenuAudioItems.tsx +46 -3
  53. package/src/player/components/timelineRowKeys.test.ts +28 -0
  54. package/src/player/components/timelineRowKeys.ts +27 -0
  55. package/src/player/hooks/useShadowPreviewReload.ts +7 -0
  56. package/src/player/hooks/useTimelinePlayer.shadowReload.test.ts +20 -0
  57. package/src/player/lib/previewChannel.ts +10 -0
  58. package/src/utils/gsapUndoRestore.sealed.test.ts +73 -0
  59. package/src/utils/gsapUndoRestore.ts +66 -0
  60. package/src/utils/studioPendingEdits.test.ts +20 -0
  61. package/src/utils/studioPendingEdits.ts +11 -4
@@ -0,0 +1,86 @@
1
+ import { afterEach, describe, expect, it, vi } from "vitest";
2
+ import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders";
3
+ import { renderHandoffCommand, saveRenderVariables } from "./renderHandoff";
4
+
5
+ afterEach(() => {
6
+ vi.unstubAllGlobals();
7
+ });
8
+
9
+ describe("renderHandoffCommand", () => {
10
+ it.each(["index.html", "compositions/intro.html", "scenes/v2_final-cut.html", "2026/q4.html"])(
11
+ "renders %s with the values file",
12
+ (compPath) => {
13
+ expect(renderHandoffCommand(compPath)).toBe(
14
+ `npx hyperframes render -c ${compPath} --variables-file .hyperframes/render-variables.json`,
15
+ );
16
+ },
17
+ );
18
+
19
+ it.each([
20
+ "x';calc;'.html",
21
+ 'x";calc;".html',
22
+ "a&calc.html",
23
+ "a|calc.html",
24
+ "a;calc.html",
25
+ "a\\b.html",
26
+ "a b.html",
27
+ "$(id).html",
28
+ "`id`.html",
29
+ "%PATH%.html",
30
+ "a^b.html",
31
+ "a(b).html",
32
+ "a!b.html",
33
+ "a,b.html",
34
+ "a{b}.html",
35
+ "a*b.html",
36
+ "a\nb.html",
37
+ "~/a.html",
38
+ "@a.html",
39
+ "#a.html",
40
+ "-o.html",
41
+ "--output=x.html",
42
+ ".x.html",
43
+ "intró.html",
44
+ "",
45
+ ])("never puts a composition name a shell reads as syntax in the command: %j", (compPath) => {
46
+ expect(renderHandoffCommand(compPath)).toBeNull();
47
+ });
48
+
49
+ it("names a values file that is one plain word in every shell", () => {
50
+ expect(RENDER_VARIABLES_FILE).toMatch(/^[A-Za-z0-9_./-]+$/);
51
+ });
52
+ });
53
+
54
+ describe("saveRenderVariables", () => {
55
+ it("puts the values as JSON to the project's render-variables route", async () => {
56
+ const fetch = vi.fn(async () => new Response("{}", { status: 200 }));
57
+ vi.stubGlobal("fetch", fetch);
58
+ const values = { title: "It's Q4'; calc; '", count: 3 };
59
+
60
+ expect(await saveRenderVariables("my project", values)).toBe(true);
61
+
62
+ expect(fetch).toHaveBeenCalledTimes(1);
63
+ const [url, init] = fetch.mock.calls[0] as unknown as [string, RequestInit];
64
+ expect(url).toBe("/api/projects/my%20project/render-variables");
65
+ expect(init.method).toBe("PUT");
66
+ expect(JSON.parse(String(init.body))).toEqual(values);
67
+ });
68
+
69
+ it("is false when the server refuses the write", async () => {
70
+ vi.stubGlobal(
71
+ "fetch",
72
+ vi.fn(async () => new Response("{}", { status: 403 })),
73
+ );
74
+ expect(await saveRenderVariables("p", {})).toBe(false);
75
+ });
76
+
77
+ it("is false when the server cannot be reached", async () => {
78
+ vi.stubGlobal(
79
+ "fetch",
80
+ vi.fn(async () => {
81
+ throw new TypeError("Failed to fetch");
82
+ }),
83
+ );
84
+ expect(await saveRenderVariables("p", {})).toBe(false);
85
+ });
86
+ });
@@ -0,0 +1,28 @@
1
+ import { RENDER_VARIABLES_FILE } from "@hyperframes/core/project-folders";
2
+ import { buildProjectApiPath } from "../../utils/projectRouting";
3
+ import { studioApiFetch } from "../../utils/studioApiFetch";
4
+
5
+ // One literal word to sh, bash, zsh, fish, PowerShell and cmd.exe, also on cmd's second pass over npx.cmd's arguments.
6
+ // No one quoting is safe in all of them, so values go in a file and a path that is not such a word gets no command.
7
+ const SHELL_WORD = /^[A-Za-z0-9_][A-Za-z0-9_./-]*$/;
8
+
9
+ export function renderHandoffCommand(compPath: string): string | null {
10
+ if (!SHELL_WORD.test(compPath)) return null;
11
+ return `npx hyperframes render -c ${compPath} --variables-file ${RENDER_VARIABLES_FILE}`;
12
+ }
13
+
14
+ export async function saveRenderVariables(
15
+ projectId: string,
16
+ values: Record<string, unknown>,
17
+ ): Promise<boolean> {
18
+ try {
19
+ const response = await studioApiFetch(buildProjectApiPath(projectId, "/render-variables"), {
20
+ method: "PUT",
21
+ headers: { "Content-Type": "application/json" },
22
+ body: JSON.stringify(values),
23
+ });
24
+ return response.ok;
25
+ } catch {
26
+ return false;
27
+ }
28
+ }
@@ -372,6 +372,83 @@ describe("Popover", () => {
372
372
  });
373
373
  });
374
374
 
375
+ // fails without the fix: Escape in a modal opened from a popover's row closed the popover and cancelled the key, so the
376
+ // modal stayed open over a page with no popover (a paywall opened from a picker row).
377
+ describe("Escape goes to the topmost open layer", () => {
378
+ /** A modal opened above the popup, as a paywall from a picker row is: outside the popup, focus inside it. */
379
+ function modalAbove(): HTMLButtonElement {
380
+ const dialog = document.createElement("div");
381
+ dialog.setAttribute("role", "dialog");
382
+ dialog.setAttribute("aria-modal", "true");
383
+ const close = document.createElement("button");
384
+ dialog.append(close);
385
+ document.body.append(dialog);
386
+ act(() => close.focus());
387
+ return close;
388
+ }
389
+ /** Escape at `target`, and whether anything cancelled it. */
390
+ function escapeAt(target: Element): boolean {
391
+ const event = new KeyboardEvent("keydown", {
392
+ key: "Escape",
393
+ bubbles: true,
394
+ cancelable: true,
395
+ composed: true,
396
+ });
397
+ act(() => void target.dispatchEvent(event));
398
+ return event.defaultPrevented;
399
+ }
400
+
401
+ it("leaves a Popover open and the key uncancelled when the modal above it has focus; its own Escape still closes it", async () => {
402
+ render(
403
+ <Popover trigger={<button data-testid="trigger">Pickers</button>} aria-label="Pickers">
404
+ <button>Ultra</button>
405
+ </Popover>,
406
+ );
407
+ act(() => trigger().click());
408
+ await settle();
409
+ const close = modalAbove();
410
+ expect(escapeAt(close), "the modal's Escape is left to the modal").toBe(false);
411
+ await settle();
412
+ expect(document.querySelector('[aria-label="Pickers"]')).not.toBeNull();
413
+ close.parentElement!.remove();
414
+
415
+ escapeAt(one('[aria-label="Pickers"] button', "popover row"));
416
+ await settle();
417
+ expect(document.querySelector('[aria-label="Pickers"]')).toBeNull();
418
+ });
419
+
420
+ it("leaves a Menu open under a modal above it", async () => {
421
+ render(
422
+ <Menu trigger={<button data-testid="trigger">Model</button>} aria-label="Model">
423
+ <MenuItem>Ultra</MenuItem>
424
+ </Menu>,
425
+ );
426
+ act(() => trigger().click());
427
+ await settle();
428
+ expect(escapeAt(modalAbove())).toBe(false);
429
+ await settle();
430
+ expect(document.querySelector('[role="menu"]')).not.toBeNull();
431
+ });
432
+
433
+ it("closes a Popover opened from inside a dialog on Escape there: that dialog is under it, not above", async () => {
434
+ const dialog = document.createElement("dialog");
435
+ dialog.setAttribute("open", "");
436
+ document.body.append(dialog);
437
+ const host = render(
438
+ <Popover trigger={<button data-testid="trigger">Speed</button>} aria-label="Speed">
439
+ <span>1x</span>
440
+ </Popover>,
441
+ );
442
+ dialog.append(host);
443
+ act(() => trigger().click());
444
+ await settle();
445
+ escapeAt(trigger());
446
+ await settle();
447
+ expect(document.querySelector('[aria-label="Speed"]')).toBeNull();
448
+ dialog.remove();
449
+ });
450
+ });
451
+
375
452
  describe("hotkey classification", () => {
376
453
  it("classifies menu rows and popover contents the way the menus they replace were", async () => {
377
454
  // `typingTarget` and `playbackShortcuts` match exact role strings; Base UI renders
@@ -98,6 +98,45 @@ interface PositionedProps {
98
98
  "data-preview-state"?: PopupPreviewState;
99
99
  }
100
100
 
101
+ /** What Base UI hands `onOpenChange`: why it would close, the event, and a way to keep it open. */
102
+ type OpenChangeDetails = { reason: string; event: Event; cancel: () => void };
103
+
104
+ /**
105
+ * The topmost open layer owns Escape. Escape pressed inside a dialog that holds neither this popup nor its trigger (one
106
+ * opened from the popup's own row) keeps the popup open and leaves the key alone, so that dialog closes first; the
107
+ * popup hears the next Escape, once it is on top again.
108
+ */
109
+ export function useTopLayerEscape<D extends OpenChangeDetails>(
110
+ onOpenChange: ((open: boolean, details: D) => void) | undefined,
111
+ ) {
112
+ const own = useRef<{ popup: Element | null; trigger: Element | null }>({
113
+ popup: null,
114
+ trigger: null,
115
+ });
116
+ const change = (open: boolean, details: D) => {
117
+ const { popup, trigger } = own.current;
118
+ if (
119
+ !open &&
120
+ details.reason === "escape-key" &&
121
+ insideLayerAbove([popup, trigger], details.event)
122
+ )
123
+ return details.cancel();
124
+ onOpenChange?.(open, details);
125
+ };
126
+ return {
127
+ popup: (el: Element | null) => void (own.current.popup = el),
128
+ trigger: (el: Element | null) => void (own.current.trigger = el),
129
+ onOpenChange: change,
130
+ };
131
+ }
132
+
133
+ /** Whether `event` started inside an open dialog or modal that holds none of `own`. */
134
+ function insideLayerAbove(own: (Element | null)[], event: Event): boolean {
135
+ const from = event.composedPath()[0];
136
+ const layer = from instanceof Element ? from.closest('dialog[open], [aria-modal="true"]') : null;
137
+ return layer !== null && !own.some((el) => el !== null && layer.contains(el));
138
+ }
139
+
101
140
  interface MenuProps
102
141
  extends PositionedProps, Omit<ComponentPropsWithoutRef<typeof BaseMenu.Root>, "children"> {
103
142
  /** A single element. It becomes the trigger; no wrapper is added around it. */
@@ -123,9 +162,10 @@ export function Menu({
123
162
  ...root
124
163
  }: MenuProps) {
125
164
  const inline = useInlinePortal(container);
165
+ const escape = useTopLayerEscape(root.onOpenChange);
126
166
  return (
127
- <BaseMenu.Root {...root}>
128
- <BaseMenu.Trigger render={trigger} />
167
+ <BaseMenu.Root {...root} onOpenChange={escape.onOpenChange}>
168
+ <BaseMenu.Trigger ref={escape.trigger} render={trigger} />
129
169
  {inline.host}
130
170
  <BaseMenu.Portal {...inline.portal}>
131
171
  <BaseMenu.Positioner
@@ -136,6 +176,7 @@ export function Menu({
136
176
  className={POPUP_LAYER}
137
177
  >
138
178
  <BaseMenu.Popup
179
+ ref={escape.popup}
139
180
  aria-label={ariaLabel}
140
181
  data-preview-state={previewState}
141
182
  className={cn(menuPopup, className)}
@@ -169,13 +210,15 @@ export function ContextMenu({
169
210
  ...root
170
211
  }: Omit<ContextMenuProps, "side" | "align" | "sideOffset">) {
171
212
  const inline = useInlinePortal(container);
213
+ const escape = useTopLayerEscape(root.onOpenChange);
172
214
  return (
173
- <BaseContextMenu.Root {...root}>
174
- <BaseContextMenu.Trigger render={trigger} />
215
+ <BaseContextMenu.Root {...root} onOpenChange={escape.onOpenChange}>
216
+ <BaseContextMenu.Trigger ref={escape.trigger} render={trigger} />
175
217
  {inline.host}
176
218
  <BaseContextMenu.Portal {...inline.portal}>
177
219
  <BaseContextMenu.Positioner collisionPadding={VIEWPORT_MARGIN} className={POPUP_LAYER}>
178
220
  <BaseContextMenu.Popup
221
+ ref={escape.popup}
179
222
  aria-label={ariaLabel}
180
223
  data-preview-state={previewState}
181
224
  className={cn(menuPopup, className)}
@@ -12,6 +12,7 @@ import {
12
12
  useInlinePortal,
13
13
  type PopupPreviewState,
14
14
  type PortalContainer,
15
+ useTopLayerEscape,
15
16
  } from "./Menu";
16
17
 
17
18
  /** Matches Menu's gap from its trigger, and its viewport margin. */
@@ -71,9 +72,10 @@ export function Popover({
71
72
  ...root
72
73
  }: PopoverProps) {
73
74
  const inline = useInlinePortal(container);
75
+ const escape = useTopLayerEscape(root.onOpenChange);
74
76
  return (
75
- <BasePopover.Root {...root}>
76
- <BasePopover.Trigger render={trigger} aria-describedby={describedBy} />
77
+ <BasePopover.Root {...root} onOpenChange={escape.onOpenChange}>
78
+ <BasePopover.Trigger ref={escape.trigger} render={trigger} aria-describedby={describedBy} />
77
79
  {inline.host}
78
80
  <BasePopover.Portal {...inline.portal}>
79
81
  <BasePopover.Positioner
@@ -86,6 +88,7 @@ export function Popover({
86
88
  className={POPUP_LAYER}
87
89
  >
88
90
  <BasePopover.Popup
91
+ ref={escape.popup}
89
92
  aria-label={ariaLabel}
90
93
  initialFocus={initialFocus}
91
94
  data-preview-state={previewState}
@@ -0,0 +1,13 @@
1
+ import { describe, expect, it } from "vitest";
2
+ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
3
+ import { getAnimationsForElement } from "./index";
4
+
5
+ const tween = (targetSelector: string) => ({ targetSelector }) as GsapAnimation;
6
+
7
+ describe("an element's animations from Studio's public API", () => {
8
+ it("are the parsed tweens that address it by id or selector, read where a sealed preview's host can", () => {
9
+ const parsed = [tween("#title"), tween(".card, .hero"), tween("#other")];
10
+ expect(getAnimationsForElement(parsed, { id: "title", selector: null })).toEqual([parsed[0]]);
11
+ expect(getAnimationsForElement(parsed, { id: null, selector: ".hero" })).toEqual([parsed[1]]);
12
+ });
13
+ });
@@ -12,6 +12,8 @@ import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
12
12
  import { HF_AUDIO_GROUP_ATTR, HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
13
13
  import { runtimeAudioId } from "../player/lib/timelineElementHelpers";
14
14
  import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
15
+ import { previewFrameOpaque, previewRequest } from "../player/lib/previewChannel";
16
+ import { findOpaqueTimelineElement } from "../components/editor/previewSelection";
15
17
  import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
16
18
  import {
17
19
  findTimelineElementInIframe,
@@ -146,6 +148,55 @@ function patchLiveGroupElement(
146
148
  return true;
147
149
  }
148
150
 
151
+ /** The members' and the group element's live writes, as `patchLiveAudioGroupState` and
152
+ * `patchLiveGroupElement` make them; returns their unwind. */
153
+ function patchLiveGroup(
154
+ iframe: HTMLIFrameElement | null,
155
+ elements: readonly TimelineElement[],
156
+ groupId: string,
157
+ groupLabel: string | undefined,
158
+ activeCompPath: string | null,
159
+ ): () => void {
160
+ const priorGroups = captureAudioGroupState(iframe, elements, activeCompPath);
161
+ patchLiveAudioGroupState(iframe, elements, groupId, activeCompPath);
162
+ const createdLiveGroupElement = patchLiveGroupElement(iframe, groupId, groupLabel);
163
+ return () => {
164
+ patchLiveAudioGroupState(iframe, elements, null, activeCompPath, priorGroups);
165
+ if (createdLiveGroupElement) {
166
+ iframe?.contentDocument?.getElementById(groupId)?.remove();
167
+ }
168
+ };
169
+ }
170
+
171
+ /** The same writes in a sealed preview, run by its runtime on the members it resolves. */
172
+ async function patchSealedGroup(
173
+ iframe: HTMLIFrameElement,
174
+ elements: readonly TimelineElement[],
175
+ groupId: string,
176
+ groupLabel: string | undefined,
177
+ activeCompPath: string | null,
178
+ ): Promise<() => Promise<void>> {
179
+ const lookup = { activeCompositionPath: activeCompPath, isMasterView: true };
180
+ const found = await Promise.all(
181
+ elements.map((element) => findOpaqueTimelineElement(iframe, element, lookup)),
182
+ );
183
+ const handles = found.flatMap((element) => (element ? [element.handle] : []));
184
+ const assigned = await previewRequest(iframe, "assign-audio-group", {
185
+ members: handles.map((handle) => ({ handle, group: groupId })),
186
+ element: { id: groupId, label: groupLabel ?? null, present: true },
187
+ });
188
+ return async () => {
189
+ if (!assigned) return;
190
+ await previewRequest(iframe, "assign-audio-group", {
191
+ members: handles.map((handle, i) => {
192
+ const prior = assigned.previous[i];
193
+ return { handle, group: typeof prior === "string" && prior ? prior : null };
194
+ }),
195
+ element: assigned.changed ? { id: groupId, label: null, present: false } : null,
196
+ });
197
+ };
198
+ }
199
+
149
200
  interface CreateAudioGroupAndAssignMembersInput {
150
201
  projectId: string;
151
202
  activeCompPath: string | null;
@@ -188,9 +239,10 @@ export async function createAudioGroupAndAssignMembers({
188
239
  throw new Error(`Invalid audio group id ${JSON.stringify(groupId)}`);
189
240
  }
190
241
 
191
- const priorGroups = captureAudioGroupState(previewIframe, elements, activeCompPath);
192
- patchLiveAudioGroupState(previewIframe, elements, groupId, activeCompPath);
193
- const createdLiveGroupElement = patchLiveGroupElement(previewIframe, groupId, groupLabel);
242
+ const unwindLive =
243
+ previewIframe && previewFrameOpaque(previewIframe)
244
+ ? await patchSealedGroup(previewIframe, elements, groupId, groupLabel, activeCompPath)
245
+ : patchLiveGroup(previewIframe, elements, groupId, groupLabel, activeCompPath);
194
246
  reseekPreviewRuntime(previewIframe);
195
247
 
196
248
  const groupOperation: PatchOperation = {
@@ -220,6 +272,7 @@ export async function createAudioGroupAndAssignMembers({
220
272
  label: groupLabel
221
273
  ? `Group ${elements.length} clips as ${groupLabel}`
222
274
  : `Group ${elements.length} voice clips`,
275
+ // fallow-ignore-next-line code-duplication
223
276
  files,
224
277
  readFile: (path) => readFileContent(projectId, path),
225
278
  writeFile: writeProjectFile,
@@ -233,10 +286,7 @@ export async function createAudioGroupAndAssignMembers({
233
286
  // Mirrors setElementsHidden's failure path: the optimistic live patch
234
287
  // already ran, so a save failure has to be unwound or the preview shows a
235
288
  // grouping that never made it to disk.
236
- patchLiveAudioGroupState(previewIframe, elements, null, activeCompPath, priorGroups);
237
- if (createdLiveGroupElement) {
238
- previewIframe?.contentDocument?.getElementById(groupId)?.remove();
239
- }
289
+ await unwindLive();
240
290
  reseekPreviewRuntime(previewIframe);
241
291
  throw error;
242
292
  }
@@ -1,4 +1,4 @@
1
- import { useCallback } from "react";
1
+ import { useCallback, useState } from "react";
2
2
  import {
3
3
  failedTimelineSave,
4
4
  projectForTimelineSave,
@@ -9,6 +9,11 @@ import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
9
9
  import { usePlayerStore } from "../player";
10
10
  import type { TimelineElementPatch } from "../player/store/timelineElement";
11
11
  import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
12
+ import {
13
+ previewDocumentCopy,
14
+ previewFrameOpaque,
15
+ previewRequest,
16
+ } from "../player/lib/previewChannel";
12
17
  import {
13
18
  buildPatchTarget,
14
19
  persistElementAttribute,
@@ -21,6 +26,35 @@ import type {
21
26
  UseTimelineElementVisibilityEditingInput,
22
27
  } from "./timelineTrackVisibility";
23
28
 
29
+ type SealedLane = { busy: boolean; next: { value: string | null } | null };
30
+ const sealedLanes = new WeakMap<HTMLIFrameElement, Map<string, SealedLane>>();
31
+
32
+ /** A drag writes per frame: one write in flight per group attribute, and only the newest waits. */
33
+ function writeSealedGroupAttribute(
34
+ iframe: HTMLIFrameElement,
35
+ groupId: string,
36
+ attr: string,
37
+ value: string | null,
38
+ ): void {
39
+ const lanes = sealedLanes.get(iframe) ?? new Map<string, SealedLane>();
40
+ sealedLanes.set(iframe, lanes);
41
+ const key = audioGroupAttributeLiveKey(groupId, attr);
42
+ const lane = lanes.get(key) ?? { busy: false, next: null };
43
+ lanes.set(key, lane);
44
+ lane.next = { value };
45
+ const pump = () => {
46
+ if (lane.busy || !lane.next) return;
47
+ const params = { id: groupId, attr, value: lane.next.value };
48
+ lane.next = null;
49
+ lane.busy = true;
50
+ void previewRequest(iframe, "set-audio-group-attribute", params).finally(() => {
51
+ lane.busy = false;
52
+ pump();
53
+ });
54
+ };
55
+ pump();
56
+ }
57
+
24
58
  /** Direct DOM write on the group element for the gesture in progress — no
25
59
  * file write, no history entry (mirrors FxParamRow's live/commit split). */
26
60
  function patchLiveGroupAttribute(
@@ -29,6 +63,10 @@ function patchLiveGroupAttribute(
29
63
  attr: string,
30
64
  value: string | null,
31
65
  ): void {
66
+ if (iframe && previewFrameOpaque(iframe)) {
67
+ writeSealedGroupAttribute(iframe, groupId, attr, value);
68
+ return;
69
+ }
32
70
  const target = iframe?.contentDocument?.getElementById(groupId);
33
71
  if (!target) return;
34
72
  if (value === null) target.removeAttribute(attr);
@@ -146,12 +184,9 @@ export function resolveGroupSourceFile(groupEl: Element | null): string | undefi
146
184
 
147
185
  interface SetAudioGroupAttributeInput {
148
186
  projectId: string;
149
- activeCompPath: string | null;
150
- groupId: string;
151
- attr: string;
187
+ source: LiveLaneSource;
152
188
  value: string | null;
153
189
  label: string;
154
- previewIframe: HTMLIFrameElement | null;
155
190
  patchLive: (value: string | null) => void;
156
191
  onFileRead: (value: string | null) => void;
157
192
  writeProjectFile: (path: string, content: string) => Promise<void>;
@@ -165,36 +200,31 @@ interface SetAudioGroupAttributeInput {
165
200
  * `createAudioGroupAndAssignMembers`'s save shape but for a single element
166
201
  * and attribute rather than a member-assignment sweep.
167
202
  */
168
- function groupSaveTarget(
169
- previewIframe: HTMLIFrameElement | null,
170
- groupId: string,
171
- activeCompPath: string | null,
172
- ) {
173
- const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
203
+ function groupSaveTarget(groupEl: Element | null, groupId: string, activeCompPath: string | null) {
174
204
  return {
175
205
  targetPath: resolveGroupSourceFile(groupEl) || activeCompPath || "index.html",
176
206
  patchTarget: buildPatchTarget({ domId: groupId }),
177
207
  };
178
208
  }
179
209
 
210
+ const liveGroupElement = (previewIframe: HTMLIFrameElement | null, groupId: string) =>
211
+ previewIframe?.contentDocument?.getElementById(groupId) ?? null;
212
+
180
213
  function groupLiveSource(
181
- previewIframe: HTMLIFrameElement | null,
214
+ groupEl: Element | null,
182
215
  groupId: string,
183
216
  activeCompPath: string | null,
184
217
  attr: string,
185
218
  ): LiveLaneSource {
186
- const { targetPath, patchTarget } = groupSaveTarget(previewIframe, groupId, activeCompPath);
219
+ const { targetPath, patchTarget } = groupSaveTarget(groupEl, groupId, activeCompPath);
187
220
  return { path: targetPath, target: patchTarget, attr };
188
221
  }
189
222
 
190
223
  async function setAudioGroupAttribute({
191
224
  projectId,
192
- activeCompPath,
193
- groupId,
194
- attr,
225
+ source,
195
226
  value,
196
227
  label,
197
- previewIframe,
198
228
  patchLive,
199
229
  onFileRead,
200
230
  writeProjectFile,
@@ -209,7 +239,7 @@ async function setAudioGroupAttribute({
209
239
  // means `readTagSnippetByTarget` finds nothing and every mute, fader move and
210
240
  // FX preset throws "Unable to patch element in index.html". Every sibling
211
241
  // timeline writer already routes `element.sourceFile || activeCompPath`.
212
- const { targetPath, patchTarget } = groupSaveTarget(previewIframe, groupId, activeCompPath);
242
+ const { path: targetPath, target: patchTarget, attr } = source;
213
243
  if (!patchTarget) return null;
214
244
 
215
245
  return persistElementAttribute({
@@ -255,22 +285,62 @@ export function useSetAudioGroupAttribute({
255
285
  restoreLive: (restore: LiveLaneRestore) => void;
256
286
  } {
257
287
  const liveLanes = useLiveLanes(projectIdRef, activeCompPath);
288
+ // A sealed preview's gesture reads the group once, off a copy of the frame, before its first write.
289
+ const [sealedReads] = useState(() => new Map<string, Promise<Document | null>>());
290
+ const openSealedLane = useCallback(
291
+ (iframe: HTMLIFrameElement, groupId: string, attr: string) => {
292
+ const key = audioGroupAttributeLiveKey(groupId, attr);
293
+ const open = sealedReads.get(key);
294
+ if (open) return open;
295
+ const read = previewDocumentCopy(iframe);
296
+ sealedReads.set(key, read);
297
+ void read.then((doc) => {
298
+ if (sealedReads.get(key) !== read) return;
299
+ const groupEl = doc?.getElementById(groupId) ?? null;
300
+ liveLanes.preview(
301
+ key,
302
+ () => groupEl?.getAttribute(attr) ?? null,
303
+ groupLiveSource(groupEl, groupId, activeCompPath, attr),
304
+ );
305
+ });
306
+ return read;
307
+ },
308
+ [sealedReads, liveLanes, activeCompPath],
309
+ );
310
+ const sealedGroupElement = useCallback(
311
+ async (iframe: HTMLIFrameElement, groupId: string, attr: string) => {
312
+ const key = audioGroupAttributeLiveKey(groupId, attr);
313
+ const read = sealedReads.get(key) ?? previewDocumentCopy(iframe);
314
+ const doc = await read;
315
+ if (sealedReads.get(key) === read) sealedReads.delete(key);
316
+ return doc?.getElementById(groupId) ?? null;
317
+ },
318
+ [sealedReads],
319
+ );
258
320
  const setLive = useCallback(
259
321
  (groupId: string, attr: string, value: string | null) => {
260
322
  const key = audioGroupAttributeLiveKey(groupId, attr);
261
- const target = previewIframeRef.current?.contentDocument?.getElementById(groupId);
262
- liveLanes.preview(
263
- key,
264
- () => target?.getAttribute(attr) ?? null,
265
- groupLiveSource(previewIframeRef.current, groupId, activeCompPath, attr),
266
- );
267
- patchLiveGroupAttribute(previewIframeRef.current, groupId, attr, value);
323
+ const iframe = previewIframeRef.current;
324
+ if (iframe && previewFrameOpaque(iframe)) {
325
+ const read = openSealedLane(iframe, groupId, attr);
326
+ void read.then(() => {
327
+ if (sealedReads.get(key) === read) patchLiveGroupAttribute(iframe, groupId, attr, value);
328
+ });
329
+ } else {
330
+ const target = liveGroupElement(iframe, groupId);
331
+ liveLanes.preview(
332
+ key,
333
+ () => target?.getAttribute(attr) ?? null,
334
+ groupLiveSource(target, groupId, activeCompPath, attr),
335
+ );
336
+ patchLiveGroupAttribute(iframe, groupId, attr, value);
337
+ }
268
338
  // Live too, not just on commit: a fader drag is `setLive` per frame and
269
339
  // `setQuiet` once on release, so without this the strip's own readout
270
340
  // fights the drag.
271
341
  syncStoredGroupAttribute(groupId, attr, value);
272
342
  },
273
- [liveLanes, previewIframeRef, activeCompPath],
343
+ [liveLanes, previewIframeRef, activeCompPath, openSealedLane, sealedReads],
274
344
  );
275
345
  const laneApply = useCallback(
276
346
  (groupId: string, attr: string) => ({
@@ -286,9 +356,12 @@ export function useSetAudioGroupAttribute({
286
356
  [liveLanes, laneApply],
287
357
  );
288
358
  const revertLive = useCallback(
289
- (groupId: string, attr: string) =>
290
- liveLanes.revert(audioGroupAttributeLiveKey(groupId, attr), laneApply(groupId, attr)),
291
- [liveLanes, laneApply],
359
+ (groupId: string, attr: string) => {
360
+ const key = audioGroupAttributeLiveKey(groupId, attr);
361
+ sealedReads.delete(key);
362
+ liveLanes.revert(key, laneApply(groupId, attr));
363
+ },
364
+ [liveLanes, laneApply, sealedReads],
292
365
  );
293
366
  const setQuiet = useCallback(
294
367
  async (
@@ -301,7 +374,12 @@ export function useSetAudioGroupAttribute({
301
374
  const pid = projectForTimelineSave(isRecordingRef?.current, project, showToast);
302
375
  // Settles on what the file holds, so overlapping saves that fail cannot leave
303
376
  // the preview or the store on a value that never landed.
304
- const source = groupLiveSource(previewIframeRef.current, groupId, activeCompPath, attr);
377
+ const iframe = previewIframeRef.current;
378
+ const groupEl =
379
+ iframe && previewFrameOpaque(iframe)
380
+ ? await sealedGroupElement(iframe, groupId, attr)
381
+ : liveGroupElement(iframe, groupId);
382
+ const source = groupLiveSource(groupEl, groupId, activeCompPath, attr);
305
383
  const live = claimLive(groupId, attr, source);
306
384
  const unsaved = async (outcome: TimelineEditOutcome): Promise<TimelineEditOutcome> => {
307
385
  live.settle(
@@ -313,12 +391,9 @@ export function useSetAudioGroupAttribute({
313
391
  try {
314
392
  const written = await setAudioGroupAttribute({
315
393
  projectId: pid,
316
- activeCompPath,
317
- groupId,
318
- attr,
394
+ source,
319
395
  value,
320
396
  label,
321
- previewIframe: previewIframeRef.current,
322
397
  patchLive: live.preview,
323
398
  onFileRead: live.read,
324
399
  writeProjectFile,
@@ -337,6 +412,7 @@ export function useSetAudioGroupAttribute({
337
412
  },
338
413
  [
339
414
  claimLive,
415
+ sealedGroupElement,
340
416
  activeCompPath,
341
417
  previewIframeRef,
342
418
  writeProjectFile,