@hyperframes/studio 0.9.64 → 0.9.66

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 (99) hide show
  1. package/dist/assets/hyperframes-player-VGx6ow_e.js +573 -0
  2. package/dist/assets/{index-CVmmHGol.js → index-B8Xt_Oyw.js} +190 -186
  3. package/dist/assets/{index-DN167Uqf.js → index-BH18TdX9.js} +1 -1
  4. package/dist/assets/{pausedVideoDecoder-C8rhpGPx.js → pausedVideoDecoder-Bx3fGNkU.js} +1 -1
  5. package/dist/{chunk-VDDEXNVX.js → chunk-ESTBKVCB.js} +8 -0
  6. package/dist/index.d.ts +2 -0
  7. package/dist/index.html +1 -1
  8. package/dist/index.js +1580 -882
  9. package/dist/player.js +1 -1
  10. package/package.json +8 -8
  11. package/src/captions/components/CaptionOverlay.sealed.test.ts +2 -25
  12. package/src/captions/hooks/useCaptionSync.ts +4 -1
  13. package/src/components/editor/LayersPanel.opaque.test.ts +4 -29
  14. package/src/components/editor/MotionPathOverlay.sealed.test.tsx +85 -0
  15. package/src/components/editor/MotionPathOverlay.tsx +26 -12
  16. package/src/components/editor/domEditOverlayCrop.ts +78 -15
  17. package/src/components/editor/domEditOverlayCropFrameLift.test.ts +64 -0
  18. package/src/components/editor/domEditOverlayStartGesture.ts +0 -14
  19. package/src/components/editor/gestureUndoRevert.ts +3 -6
  20. package/src/components/editor/gsapMoveSealedPreview.test.ts +247 -0
  21. package/src/components/editor/manualEditsSnapshot.ts +2 -0
  22. package/src/components/editor/manualOffsetDrag.ts +13 -18
  23. package/src/components/editor/plainTranslate.test.ts +22 -1
  24. package/src/components/editor/plainTranslate.ts +8 -6
  25. package/src/components/editor/previewDrafts.test.ts +13 -39
  26. package/src/components/editor/previewDrafts.ts +4 -0
  27. package/src/components/editor/previewGestureStartRead.test.ts +59 -32
  28. package/src/components/editor/previewGestureStartRead.ts +9 -0
  29. package/src/components/editor/previewLayers.test.ts +3 -20
  30. package/src/components/editor/previewOverlayRects.test.ts +3 -20
  31. package/src/components/editor/previewPointerTargets.test.ts +3 -20
  32. package/src/components/editor/previewSelection.test.ts +51 -35
  33. package/src/components/editor/previewSelection.ts +18 -0
  34. package/src/components/editor/useColorGradingController.sealed.test.ts +5 -30
  35. package/src/components/editor/useMotionPathData.reply.test.ts +40 -0
  36. package/src/components/editor/useMotionPathData.sealed.test.ts +57 -0
  37. package/src/components/editor/useMotionPathData.test.tsx +1 -1
  38. package/src/components/editor/useMotionPathData.ts +83 -33
  39. package/src/components/nle/CompositionBreadcrumb.tsx +2 -5
  40. package/src/components/nle/NLEContext.drillDown.test.ts +85 -0
  41. package/src/components/nle/NLEContext.tsx +21 -23
  42. package/src/components/nle/NLEPreview.test.ts +18 -3
  43. package/src/components/nle/NLEPreview.tsx +10 -1
  44. package/src/components/nle/audioSealedPreview.test.ts +5 -32
  45. package/src/components/panels/motionBlurPanelModel.sealed.test.ts +30 -0
  46. package/src/components/panels/motionBlurPanelModel.ts +37 -7
  47. package/src/hooks/appHotkeysDispatch.ts +38 -1
  48. package/src/hooks/domEditCommits.sealed.test.ts +191 -0
  49. package/src/hooks/domStyleCommit.ts +18 -7
  50. package/src/hooks/draggedGsapPosition.ts +20 -0
  51. package/src/hooks/gsapEditOutcome.ts +3 -0
  52. package/src/hooks/gsapFrameSnapshot.test.ts +113 -0
  53. package/src/hooks/gsapFrameSnapshot.ts +246 -0
  54. package/src/hooks/gsapParsedTween.ts +16 -9
  55. package/src/hooks/gsapResizeIntercept.ts +7 -2
  56. package/src/hooks/gsapRuntimeBridge.ts +4 -0
  57. package/src/hooks/gsapRuntimeKeyframes.ts +23 -15
  58. package/src/hooks/gsapShared.ts +4 -0
  59. package/src/hooks/gsapSnapshotReply.ts +105 -0
  60. package/src/hooks/useAppHotkeys.previewForwarding.test.tsx +134 -0
  61. package/src/hooks/useAppHotkeys.ts +36 -1
  62. package/src/hooks/useDomEditAttributeCommits.ts +43 -19
  63. package/src/hooks/useDomEditCommits.test.tsx +1 -1
  64. package/src/hooks/useDomEditPreviewSync.test.ts +36 -1
  65. package/src/hooks/useDomEditPreviewSync.ts +3 -3
  66. package/src/hooks/useEditorSave.ts +2 -1
  67. package/src/hooks/useEnableKeyframes.sealed.test.ts +70 -0
  68. package/src/hooks/useEnableKeyframes.ts +9 -2
  69. package/src/hooks/useGsapTweenCache.ts +9 -3
  70. package/src/hooks/usePreviewPersistence.ts +18 -11
  71. package/src/hooks/useSdkSession.lifecycle.test.tsx +1 -0
  72. package/src/hooks/useSdkSession.ts +2 -0
  73. package/src/hooks/useSlideshowTabState.test.ts +47 -3
  74. package/src/hooks/useSlideshowTabState.ts +32 -16
  75. package/src/player/hooks/timelinePlayerTestHarness.ts +2 -1
  76. package/src/player/hooks/usePlaybackKeyboard.ts +1 -1
  77. package/src/player/hooks/useTimelineSyncCallbacks.sealed.test.ts +2 -29
  78. package/src/player/lib/previewChannel.test.ts +10 -0
  79. package/src/player/lib/previewChannel.ts +9 -0
  80. package/src/player/lib/previewElements.test.ts +34 -1
  81. package/src/player/lib/previewElements.ts +101 -18
  82. package/src/player/lib/sealedPreviewFrame.test-helpers.ts +38 -0
  83. package/src/player/lib/timelineIframeHelpers.ts +1 -1
  84. package/src/telemetry/client.ts +4 -2
  85. package/src/telemetry/eventShape.test.ts +189 -0
  86. package/src/telemetry/eventShape.ts +192 -0
  87. package/src/utils/blockInstaller.test.ts +82 -48
  88. package/src/utils/blockInstaller.ts +6 -14
  89. package/src/utils/domEditSaveQueue.test.ts +12 -2
  90. package/src/utils/domEditSaveQueue.ts +4 -4
  91. package/src/utils/previewCompositionSize.test.ts +61 -0
  92. package/src/utils/previewCompositionSize.ts +21 -1
  93. package/src/utils/sdkEditTransaction.ts +6 -2
  94. package/src/utils/sdkResolverShadow.ts +16 -15
  95. package/src/utils/studioSaveDiagnostics.test.ts +21 -3
  96. package/src/utils/studioSaveDiagnostics.ts +71 -6
  97. package/src/utils/studioTelemetry.ts +6 -1
  98. package/dist/assets/hyperframes-player-mSF_GvRs.js +0 -573
  99. package/src/components/editor/motionPathHome.ts +0 -75
@@ -1,5 +1,6 @@
1
1
  // @vitest-environment happy-dom
2
2
 
3
+ import { readFileSync } from "node:fs";
3
4
  import React, { act, useRef } from "react";
4
5
  import type { Root } from "react-dom/client";
5
6
  import { afterEach, describe, expect, it, vi } from "vitest";
@@ -8,6 +9,14 @@ import { usePlayerStore } from "../player/store/playerStore";
8
9
  import { useAppHotkeys } from "./useAppHotkeys";
9
10
  import { mountReactHarness } from "./domSelectionTestHarness";
10
11
  import { trackStudioEvent } from "../utils/studioTelemetry";
12
+ import { APP_HOTKEY_ACTIONS } from "./appHotkeysDispatch";
13
+ import { PLAYBACK_ACTIONS } from "../player/hooks/usePlaybackKeyboard";
14
+ import { DEFAULT_STUDIO_KEYS } from "../player/components/studioShortcuts";
15
+ import {
16
+ detachedFakeIframe,
17
+ serveEditingRequests,
18
+ } from "../player/hooks/timelinePlayerTestHarness";
19
+ import { previewRequest } from "../player/lib/previewChannel";
11
20
 
12
21
  vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
13
22
 
@@ -167,4 +176,129 @@ describe("preview iframe hotkey forwarding", () => {
167
176
  expect(add).toHaveBeenCalled();
168
177
  expect(remove.mock.calls).toEqual(add.mock.calls);
169
178
  });
179
+
180
+ describe("a sealed preview", () => {
181
+ const closers: Array<() => void> = [];
182
+ afterEach(() => closers.splice(0).forEach((close) => close()));
183
+
184
+ // A frame whose document refuses Studio, reached only over the editing port it hands out per connect.
185
+ function sealedFrame(focus = { inPreview: true }) {
186
+ const frame: Record<string, unknown> = {};
187
+ const iframe = detachedFakeIframe(frame);
188
+ const hasFocus = vi.spyOn(document, "hasFocus").mockImplementation(() => focus.inPreview);
189
+ Object.defineProperty(document, "activeElement", {
190
+ configurable: true,
191
+ get: () => (focus.inPreview ? iframe : document.body),
192
+ });
193
+ closers.push(() => {
194
+ hasFocus.mockRestore();
195
+ delete (document as { activeElement?: unknown }).activeElement;
196
+ });
197
+ Object.defineProperty(iframe, "contentDocument", { value: null });
198
+ Object.defineProperty(frame, "document", {
199
+ get: () => {
200
+ throw new DOMException("blocked", "SecurityError");
201
+ },
202
+ });
203
+ const watched: string[][] = [];
204
+ const ports: MessagePort[] = [];
205
+ closers.push(
206
+ serveEditingRequests(
207
+ frame,
208
+ (kind, params) => {
209
+ if (kind === "max-z-index") return { zIndex: 7 };
210
+ if (kind !== "watch-keys") return null;
211
+ watched.push((params as { combos: string[] }).combos);
212
+ return { watching: watched.at(-1)!.length };
213
+ },
214
+ (port) => ports.push(port),
215
+ ),
216
+ );
217
+ const keyDown = (key: string, code: string) =>
218
+ ports.at(-1)!.postMessage({
219
+ v: 1,
220
+ event: "key",
221
+ key: {
222
+ type: "keydown",
223
+ key,
224
+ code,
225
+ altKey: false,
226
+ ctrlKey: false,
227
+ metaKey: false,
228
+ shiftKey: false,
229
+ repeat: false,
230
+ },
231
+ });
232
+ return { iframe, watched, ports, keyDown, hasFocus };
233
+ }
234
+
235
+ it("leaves Studio's own reads of the preview answered while it forwards keys", async () => {
236
+ root = mountReactHarness(<Harness />);
237
+ const { iframe, watched } = sealedFrame();
238
+ let read: Promise<unknown> | undefined;
239
+ act(() => {
240
+ sync?.(iframe);
241
+ read = previewRequest(iframe, "max-z-index", {}, 1_000);
242
+ });
243
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
244
+ await expect(read).resolves.toEqual({ zIndex: 7 });
245
+ });
246
+
247
+ it("deletes the selection on a Delete pressed inside the preview", async () => {
248
+ root = mountReactHarness(<Harness />);
249
+ const { iframe, watched, keyDown } = sealedFrame();
250
+ act(() => sync?.(iframe));
251
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
252
+ expect(new Set(watched[0])).toEqual(
253
+ new Set(APP_HOTKEY_ACTIONS.map((action) => DEFAULT_STUDIO_KEYS[action])),
254
+ );
255
+ keyDown("Delete", "Delete");
256
+ await vi.waitFor(() => expect(domDelete).toHaveBeenCalledTimes(1));
257
+ });
258
+
259
+ it("ignores a key the preview reports while the person is not in the preview", async () => {
260
+ root = mountReactHarness(<Harness />);
261
+ const focus = { inPreview: false };
262
+ const { iframe, watched, keyDown, hasFocus } = sealedFrame(focus);
263
+ act(() => sync?.(iframe));
264
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
265
+ keyDown("Delete", "Delete");
266
+ await vi.waitFor(() => expect(hasFocus).toHaveBeenCalledTimes(1));
267
+ focus.inPreview = true;
268
+ keyDown("Delete", "Delete");
269
+ await vi.waitFor(() => expect(domDelete).toHaveBeenCalledTimes(1));
270
+ expect(hasFocus).toHaveBeenCalledTimes(2);
271
+ });
272
+
273
+ it("stops watching on the preview's next load, from a new port", async () => {
274
+ root = mountReactHarness(<Harness />);
275
+ const { iframe, watched, ports } = sealedFrame();
276
+ act(() => sync?.(iframe));
277
+ await vi.waitFor(() => expect(watched).toHaveLength(1));
278
+ act(() => sync?.(iframe));
279
+ await vi.waitFor(() => expect(watched).toHaveLength(3));
280
+ expect(watched.slice(1)).toContainEqual([]);
281
+ expect(ports).toHaveLength(2);
282
+ });
283
+
284
+ it("watches every action the app's key dispatchers answer, so none is dead in a sealed preview", () => {
285
+ const read = (file: string) => readFileSync(new URL(file, import.meta.url), "utf8");
286
+ const answered = new Set([
287
+ ...[...read("./appHotkeysDispatch.ts").matchAll(/matchesKey\(\w+, "(\w+)"\)/g)].map(
288
+ (m) => m[1],
289
+ ),
290
+ ...[...read("./linkShortcuts.ts").matchAll(/\["(\w+)", "\w+"\]/g)].map((m) => m[1]),
291
+ ]);
292
+ expect(answered.size).toBeGreaterThan(20);
293
+ expect(new Set(APP_HOTKEY_ACTIONS)).toEqual(answered);
294
+ });
295
+
296
+ it("watches no key the playback keys also watch, so the frame forwards each press once", () => {
297
+ const app = new Set(APP_HOTKEY_ACTIONS.map((action) => DEFAULT_STUDIO_KEYS[action]));
298
+ const shared = PLAYBACK_ACTIONS.map((action) => DEFAULT_STUDIO_KEYS[action]).filter((combo) =>
299
+ app.has(combo),
300
+ );
301
+ expect(shared).toEqual([]);
302
+ });
303
+ });
170
304
  });
@@ -8,13 +8,21 @@ import {
8
8
  applyCaptionModelToIframe,
9
9
  isCaptionPreviewVisible,
10
10
  } from "../captions/components/CaptionOverlayUtils";
11
- import { type HotkeyCallbacks, dispatchModifierKey, dispatchPlainKey } from "./appHotkeysDispatch";
11
+ import {
12
+ APP_HOTKEY_ACTIONS,
13
+ type HotkeyCallbacks,
14
+ dispatchModifierKey,
15
+ dispatchPlainKey,
16
+ } from "./appHotkeysDispatch";
12
17
  import {
13
18
  useEditHistoryActions,
14
19
  type EditHistoryHandle,
15
20
  type UseEditHistoryActionsOptions,
16
21
  } from "./useEditHistoryActions";
17
22
  import { useStableHandlers } from "./useStableHandlers";
23
+ import { createEditingPortClient } from "@hyperframes/core/runtime/editing-port";
24
+ import { previewFrameOpaque } from "../player/lib/previewChannel";
25
+ import { getStudioKey, subscribeStudioKeys } from "../player/components/studioShortcuts";
18
26
 
19
27
  function iframeContentWindow(iframe: HTMLIFrameElement | null): Window | null {
20
28
  try {
@@ -24,6 +32,29 @@ function iframeContentWindow(iframe: HTMLIFrameElement | null): Window | null {
24
32
  }
25
33
  }
26
34
 
35
+ // A port of its own: watch-keys replaces a port's whole list, and playback watches its keys on the shared one.
36
+ function forwardSealedFrameKeys(iframe: HTMLIFrameElement, onKeyDown: (e: KeyboardEvent) => void) {
37
+ const client = createEditingPortClient({ iframe });
38
+ const watch = (combos: string[]) => void client.request("watch-keys", { combos }).catch(() => {});
39
+ const watchApp = () => watch(APP_HOTKEY_ACTIONS.map(getStudioKey));
40
+ watchApp();
41
+ const stopRebinds = subscribeStudioKeys(watchApp);
42
+ // The frame can report keys nobody pressed: act only while the person is in the preview.
43
+ const focused = () =>
44
+ iframe.ownerDocument.hasFocus() && iframe.ownerDocument.activeElement === iframe;
45
+ const stopKeys = client.onKey((key) => {
46
+ if (key.type === "keydown" && focused()) onKeyDown(new KeyboardEvent(key.type, key));
47
+ });
48
+ return () => {
49
+ stopRebinds();
50
+ stopKeys();
51
+ void client
52
+ .request("watch-keys", { combos: [] })
53
+ .catch(() => {})
54
+ .finally(() => client.dispose());
55
+ };
56
+ }
57
+
27
58
  function safeAddListener(t: EventTarget | null, type: string, h: EventListener, capture = false) {
28
59
  try {
29
60
  t?.addEventListener(type, h, capture);
@@ -247,6 +278,10 @@ export function useAppHotkeys({
247
278
  (iframe: HTMLIFrameElement | null) => {
248
279
  previewHistoryCleanupRef.current?.();
249
280
  previewHistoryCleanupRef.current = null;
281
+ if (iframe && previewFrameOpaque(iframe)) {
282
+ previewHistoryCleanupRef.current = forwardSealedFrameKeys(iframe, handleAppKeyDown);
283
+ return;
284
+ }
250
285
  const win = iframeContentWindow(iframe);
251
286
  if (!win) return;
252
287
  const appHandler = handleAppKeyDown as EventListener;
@@ -14,6 +14,8 @@ import { bumpDomEditCommitMapVersion, runDomEditCommit } from "./domEditCommitRu
14
14
  import { syncStoredAutomationFromPreview } from "../player/lib/automationStoreSync";
15
15
  import { HF_AUDIO_GROUP_ATTR, HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
16
16
  import { invalidateGroupInfoCache } from "../player/lib/timelineGroupInfo";
17
+ import { editSealedSelection } from "../components/editor/previewSelection";
18
+ import { afterSealedDraw, type PreviewElementEdit } from "../player/lib/previewElements";
17
19
 
18
20
  // ── Types ──
19
21
 
@@ -161,6 +163,7 @@ export function useDomEditAttributeCommits({
161
163
  const op: PatchOperation = { type: "attribute", property: attr, value };
162
164
  let editedElement: HTMLElement | null = null;
163
165
  let previousValue: string | null = null;
166
+ let sealedEdit: PreviewElementEdit | null = null;
164
167
 
165
168
  await runDomEditCommit({
166
169
  capture: () => {
@@ -175,20 +178,27 @@ export function useDomEditAttributeCommits({
175
178
  previousValue = captured.previousValue;
176
179
  },
177
180
  apply: () => {
178
- if (!editedElement) return;
179
181
  const nextValue = value === null || value === "" ? null : value;
182
+ if (!editedElement) {
183
+ const attributes: Array<[string, string | null]> = [[fullAttr, nextValue]];
184
+ sealedEdit = editSealedSelection(iframe, domEditSelection, { attributes });
185
+ return;
186
+ }
180
187
  setOrRemovePreviewAttribute(editedElement, fullAttr, nextValue);
181
188
  },
182
189
  persist: options.previewOnly
183
190
  ? async () => {}
184
191
  : () =>
185
- persistDomEditOperations(domEditSelection, [op], {
186
- label: options.label,
187
- coalesceKey: commitKey,
188
- skipRefresh: options.skipRefresh,
189
- }),
192
+ afterSealedDraw(sealedEdit, (drawn) =>
193
+ persistDomEditOperations(domEditSelection, [op], {
194
+ label: options.label,
195
+ coalesceKey: commitKey,
196
+ skipRefresh: options.skipRefresh && drawn,
197
+ }),
198
+ ),
190
199
  shouldRevert: () => isLatestCommit(),
191
200
  revert: () => {
201
+ sealedEdit?.restore();
192
202
  if (!editedElement) return;
193
203
  setOrRemovePreviewAttribute(editedElement, fullAttr, previousValue);
194
204
  },
@@ -256,6 +266,7 @@ export function useDomEditAttributeCommits({
256
266
  commitKey,
257
267
  );
258
268
  let captured: CapturedMultiAttributeElement | null = null;
269
+ let sealedEdit: PreviewElementEdit | null = null;
259
270
  let landed = false;
260
271
 
261
272
  await runDomEditCommit({
@@ -268,21 +279,31 @@ export function useDomEditAttributeCommits({
268
279
  );
269
280
  },
270
281
  apply: () => {
271
- if (!captured) return;
282
+ if (!captured) {
283
+ const attributes = entries.map(({ fullAttr, value }): [string, string | null] => [
284
+ fullAttr,
285
+ value,
286
+ ]);
287
+ sealedEdit = editSealedSelection(iframe, selection, { attributes });
288
+ return;
289
+ }
272
290
  for (const entry of entries) {
273
291
  setOrRemovePreviewAttribute(captured.element, entry.fullAttr, entry.value);
274
292
  }
275
293
  },
276
294
  persist: () =>
277
- persistDomEditOperations(selection, ops, {
278
- label: options.label,
279
- coalesceKey: commitKey,
280
- skipRefresh: options.skipRefresh,
281
- prepareContent: options.prepareContent,
282
- }),
295
+ afterSealedDraw(sealedEdit, (drawn) =>
296
+ persistDomEditOperations(selection, ops, {
297
+ label: options.label,
298
+ coalesceKey: commitKey,
299
+ skipRefresh: options.skipRefresh && drawn,
300
+ prepareContent: options.prepareContent,
301
+ }),
302
+ ),
283
303
  shouldRevert: (error) =>
284
304
  isLatestCommit() && !(error instanceof DomEditPersistPreparedWriteError),
285
305
  revert: () => {
306
+ sealedEdit?.restore();
286
307
  if (!captured) return;
287
308
  for (const entry of entries) {
288
309
  setOrRemovePreviewAttribute(
@@ -413,6 +434,7 @@ export function useDomEditAttributeCommits({
413
434
  const op: PatchOperation = { type: "html-attribute", property: attr, value };
414
435
  let editedElement: HTMLElement | null = null;
415
436
  let previousValue: string | null = null;
437
+ let sealedEdit: PreviewElementEdit | null = null;
416
438
 
417
439
  await runDomEditCommit({
418
440
  capture: () => {
@@ -427,12 +449,13 @@ export function useDomEditAttributeCommits({
427
449
  previousValue = captured.previousValue;
428
450
  },
429
451
  apply: () => {
430
- if (!editedElement) return;
431
- setOrRemovePreviewAttribute(
432
- editedElement,
433
- attr,
434
- resolveOptimisticAttributeValue(attr, value),
435
- );
452
+ const optimistic = resolveOptimisticAttributeValue(attr, value);
453
+ if (!editedElement) {
454
+ const attributes: Array<[string, string | null]> = [[attr, optimistic]];
455
+ sealedEdit = editSealedSelection(iframe, domEditSelection, { attributes });
456
+ return;
457
+ }
458
+ setOrRemovePreviewAttribute(editedElement, attr, optimistic);
436
459
  },
437
460
  persist: () =>
438
461
  persistDomEditOperations(domEditSelection, [op], {
@@ -442,6 +465,7 @@ export function useDomEditAttributeCommits({
442
465
  }),
443
466
  shouldRevert: () => isLatestCommit(),
444
467
  revert: () => {
468
+ sealedEdit?.restore();
445
469
  if (!editedElement) return;
446
470
  setOrRemovePreviewAttribute(editedElement, attr, previousValue);
447
471
  },
@@ -455,7 +455,7 @@ describe("useDomEditCommits z-index reorder persistence", () => {
455
455
  expect.objectContaining({
456
456
  mutation_type: "z-reorder-unmatched",
457
457
  file_path: "index.html",
458
- error_message: expect.stringContaining("b"),
458
+ error_key: "unknown",
459
459
  }),
460
460
  );
461
461
  } finally {
@@ -4,7 +4,8 @@ import { createElement, act } from "react";
4
4
  import { createRoot } from "react-dom/client";
5
5
  import { describe, expect, it, vi } from "vitest";
6
6
  import { useDomEditPreviewSync } from "./useDomEditPreviewSync";
7
- import { sceneSwapFor } from "../player/sceneSwap";
7
+ import { announcePreviewDocumentLoaded, sceneSwapFor } from "../player/sceneSwap";
8
+ import type { DomEditSelection } from "../components/editor/domEditing";
8
9
 
9
10
  (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
10
11
 
@@ -51,4 +52,38 @@ describe("useDomEditPreviewSync", () => {
51
52
  act(() => root.unmount());
52
53
  fetchSpy.mockRestore();
53
54
  });
55
+
56
+ it("re-resolves the selection when a sealed preview loads a new page", () => {
57
+ const iframe = document.createElement("iframe");
58
+ Object.defineProperty(iframe, "contentDocument", { value: null });
59
+ Object.defineProperty(iframe, "contentWindow", {
60
+ value: {
61
+ get document() {
62
+ throw new DOMException("blocked", "SecurityError");
63
+ },
64
+ },
65
+ });
66
+ const selection = { selector: "#target", handle: "old-page:1" } as DomEditSelection;
67
+ const refresh = vi.fn(async () => {});
68
+ function Harness() {
69
+ useDomEditPreviewSync({
70
+ previewIframe: iframe,
71
+ captionEditMode: false,
72
+ domEditSelectionRef: { current: selection },
73
+ domEditSelection: selection,
74
+ refreshDomEditSelectionFromPreview: refresh,
75
+ refreshPreviewDocumentVersion: () => {},
76
+ syncPreviewHotkeys: () => {},
77
+ applyStudioManualEditsToPreviewRef: { current: async () => {} },
78
+ });
79
+ return null;
80
+ }
81
+ const root = createRoot(document.createElement("div"));
82
+ act(() => root.render(createElement(Harness)));
83
+ refresh.mockClear();
84
+
85
+ act(() => announcePreviewDocumentLoaded(iframe));
86
+ expect(refresh).toHaveBeenCalledWith(selection, iframe);
87
+ act(() => root.unmount());
88
+ });
54
89
  });
@@ -9,6 +9,7 @@ import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits"
9
9
  import { useDockLayoutStore } from "../components/dock/dockLayoutStore";
10
10
  import type { PatchTarget } from "../utils/sourcePatcher";
11
11
  import { onPreviewContentReplaced } from "../player/sceneSwap";
12
+ import { previewFrameOpaque } from "../player/lib/previewChannel";
12
13
 
13
14
  interface UseDomEditPreviewSyncParams {
14
15
  previewIframe: HTMLIFrameElement | null;
@@ -57,9 +58,8 @@ export function useDomEditPreviewSync({
57
58
  } catch {
58
59
  return;
59
60
  }
60
- if (!doc) return;
61
-
62
- reapplyPositionEditsAfterSeek(doc);
61
+ if (doc) reapplyPositionEditsAfterSeek(doc);
62
+ else if (!previewFrameOpaque(previewIframe)) return;
63
63
  await refreshDomEditSelectionFromPreview(currentSelection, previewIframe);
64
64
  };
65
65
 
@@ -3,6 +3,7 @@ import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
3
3
  import {
4
4
  StudioFileConflictError,
5
5
  buildStudioSaveFailureProperties,
6
+ getStudioSaveErrorMessage,
6
7
  heldFileWords,
7
8
  trackStudioSaveFailure,
8
9
  type StudioSaveDrainResult,
@@ -76,7 +77,7 @@ export function useEditorSave({
76
77
  const fingerprint = JSON.stringify([
77
78
  path,
78
79
  errorName,
79
- properties.error_message,
80
+ getStudioSaveErrorMessage(error),
80
81
  properties.status_code,
81
82
  ]);
82
83
  const previous = lastFailureReportRef.current;
@@ -0,0 +1,70 @@
1
+ // @vitest-environment happy-dom
2
+
3
+ import { afterEach, expect, it, vi } from "vitest";
4
+ import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
5
+ import { describePreviewElements, queryPreviewElements } from "../player/lib/previewElements";
6
+ import { usePlayerStore } from "../player/store/playerStore";
7
+ import { standInFor } from "../components/editor/previewSelection";
8
+ import type { DomEditSelection } from "../components/editor/domEditingTypes";
9
+ import { applyKeyframeAtPlayhead, type EnableKeyframesSession } from "./useEnableKeyframes";
10
+ import { sealedPreviewFrame } from "../player/lib/sealedPreviewFrame.test-helpers";
11
+
12
+ afterEach(() => {
13
+ usePlayerStore.setState({ currentTime: 0, isPlaying: false });
14
+ document.body.innerHTML = "";
15
+ for (const name of ["gsap", "__timelines", "__player"]) Reflect.deleteProperty(window, name);
16
+ });
17
+
18
+ /** The frame's GSAP: one keyframed tween moving #box, paused half way where GSAP has it at 120, 40. */
19
+ function frameGsapAt(seconds: number) {
20
+ const box = document.getElementById("box")!;
21
+ const live = { x: 120, y: 40 } as Record<string, number>;
22
+ const tween = {
23
+ targets: () => [box],
24
+ vars: { keyframes: { "0%": { x: 0, y: 0 }, "100%": { x: 200, y: 80 } }, duration: 1 },
25
+ startTime: () => 0,
26
+ duration: () => 1,
27
+ _initted: true,
28
+ };
29
+ Object.assign(window, {
30
+ gsap: { getProperty: (el: Element, prop: string) => (el === box ? live[prop] : 0) },
31
+ __timelines: { main: { getChildren: () => [tween], time: () => seconds } },
32
+ __player: { getTime: () => seconds },
33
+ });
34
+ }
35
+
36
+ const keyframed: GsapAnimation = {
37
+ id: "#box-to-0-position",
38
+ targetSelector: "#box",
39
+ method: "to",
40
+ position: 0,
41
+ duration: 1,
42
+ properties: {},
43
+ keyframes: {
44
+ format: "percentage",
45
+ keyframes: [
46
+ { percentage: 0, properties: { x: 0, y: 0 } },
47
+ { percentage: 100, properties: { x: 200, y: 80 } },
48
+ ],
49
+ },
50
+ };
51
+
52
+ // fails without the fix: a sealed preview's GSAP values were out of reach, so the add did nothing.
53
+ it("adds a keyframe at the playhead with the sealed preview's GSAP values there", async () => {
54
+ document.body.innerHTML = `<main data-composition-id="main"><div id="box"></div></main>`;
55
+ frameGsapAt(0.5);
56
+ usePlayerStore.setState({ currentTime: 0.5, isPlaying: false });
57
+ const iframe = sealedPreviewFrame().iframe;
58
+ const [match] = (await queryPreviewElements(iframe, "#box"))!.matches;
59
+ const [described] = (await describePreviewElements(iframe, [match!.handle]))!;
60
+ const sel = { id: "box", selector: "#box", element: standInFor(iframe, described!) };
61
+ const addKeyframes = vi.fn(async () => undefined);
62
+ const session = {
63
+ handleGsapAddKeyframeBatch: addKeyframes,
64
+ handleGsapRemoveKeyframe: vi.fn(),
65
+ } as unknown as EnableKeyframesSession;
66
+
67
+ await applyKeyframeAtPlayhead(session, sel as DomEditSelection, keyframed, 0.5, iframe);
68
+
69
+ expect(addKeyframes).toHaveBeenCalledWith(keyframed.id, 50, { x: 120, y: 40 }, undefined);
70
+ });
@@ -33,6 +33,8 @@ import { findParsedTween, withLiveTiming } from "./gsapParsedTween";
33
33
  import { roundTo3 } from "../utils/rounding";
34
34
  import { readTranslatePxLeavingPercent } from "../components/editor/plainTranslate";
35
35
  import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
36
+ import { previewFrameOpaque } from "../player/lib/previewChannel";
37
+ import { frameGsap, settleGsapSnapshot } from "./gsapFrameSnapshot";
36
38
  import {
37
39
  buildExtendedKeyframes,
38
40
  buildTemporalArcKeyframes,
@@ -133,15 +135,19 @@ function readElementPosition(
133
135
  const result: Record<string, number> = {};
134
136
  if (!iframe?.contentWindow) return result;
135
137
 
138
+ const sealed = previewFrameOpaque(iframe);
136
139
  let gsap: { getProperty?: (el: Element, prop: string) => number } | undefined;
137
140
  try {
138
- gsap = (iframe.contentWindow as Window & { gsap?: typeof gsap }).gsap;
141
+ gsap = sealed
142
+ ? (frameGsap(iframe) ?? undefined)
143
+ : (iframe.contentWindow as Window & { gsap?: typeof gsap }).gsap;
139
144
  } catch {
140
145
  return result;
141
146
  }
142
147
 
148
+ // A sealed selection is Studio's stand-in, which the snapshot matches by handle.
143
149
  const element = sel.element;
144
- if (!element?.isConnected || !gsap?.getProperty) return result;
150
+ if (!element || (!sealed && !element.isConnected) || !gsap?.getProperty) return result;
145
151
 
146
152
  // ponytail: a brand-new tween captures position only — bundling opacity made it
147
153
  // a mixed group that the position-only drag intercept couldn't resolve.
@@ -280,6 +286,7 @@ export async function applyKeyframeAtPlayhead(
280
286
  commitOverrides?: Partial<CommitMutationOptions>,
281
287
  liveTween?: ReturnType<typeof findParsedTween>,
282
288
  ): Promise<void> {
289
+ await settleGsapSnapshot(iframe);
283
290
  const keepAuthoredDuration = kfAnim.durationUnresolved === true;
284
291
  if (keepAuthoredDuration) {
285
292
  kfAnim = withLiveTiming(kfAnim, liveTween ?? findParsedTween(iframe, sel.element, kfAnim));
@@ -20,12 +20,17 @@ import {
20
20
  } from "./gsapTweenSynth";
21
21
  import { fetchParsedAnimations, populateKeyframeCacheFromAst } from "./keyframeCacheAstLoad";
22
22
  import { getAnimationsForElement } from "./gsapElementMatch";
23
+ import { frameDocument, useGsapSnapshotVersion } from "./gsapFrameSnapshot";
23
24
 
24
25
  // Re-exported so callers keep importing the GSAP cache surface from one module.
25
26
  export { resolveClipTimingBasis } from "./gsapShared";
26
27
  export { fetchParsedAnimations, resolveSelectorElementIds } from "./keyframeCacheAstLoad";
27
28
  export { getAnimationsForElement } from "./gsapElementMatch";
28
29
 
30
+ /** The frame's document, or a sealed frame's tween targets as one a selector can query. */
31
+ const previewDocument = (iframe: HTMLIFrameElement | null | undefined) =>
32
+ iframe?.contentDocument ?? frameDocument(iframe ?? null);
33
+
29
34
  export function useGsapAnimationsForElement(
30
35
  projectId: string | null,
31
36
  sourceFile: string,
@@ -83,20 +88,21 @@ export function useGsapAnimationsForElement(
83
88
 
84
89
  const targetId = target?.id ?? null;
85
90
  const targetSelector = target?.selector ?? null;
91
+ const snapshotVersion = useGsapSnapshotVersion();
86
92
  const rawAnimations = useMemo(() => {
87
93
  if (!targetId && !targetSelector) return [];
88
94
  // Resolve the live element so class / descendant tweens (e.g.
89
95
  // gsap.from(".dot", {stagger})) attribute to every matching element, not
90
96
  // just the one whose exact selector equals the tween's. `version` re-runs
91
97
  // this after composition reloads.
92
- const element = target ? findPreviewNode(iframeRef?.current?.contentDocument, target) : null;
98
+ const element = target ? findPreviewNode(previewDocument(iframeRef?.current), target) : null;
93
99
  return getAnimationsForElement(
94
100
  allAnimations,
95
101
  { id: targetId, selector: targetSelector },
96
102
  element,
97
103
  );
98
104
  // eslint-disable-next-line react-hooks/exhaustive-deps
99
- }, [allAnimations, target, version, iframeRef]);
105
+ }, [allAnimations, target, version, iframeRef, snapshotVersion]);
100
106
 
101
107
  // fallow-ignore-next-line complexity
102
108
  const animations = useMemo(() => {
@@ -301,7 +307,7 @@ export function usePopulateKeyframeCacheForFile(
301
307
  if (!sameData) pruneKeyframeCacheToFiles(files);
302
308
  if (stale.length === 0) return;
303
309
  runtimeScanDoneRef.current = "";
304
- const doc = iframeRef?.current?.contentDocument;
310
+ const doc = previewDocument(iframeRef?.current);
305
311
  for (const sf of stale) {
306
312
  void populateKeyframeCacheFromAst(projectId, sf, doc).then((loaded) => {
307
313
  if (!loaded && loadedRef.current.dataKey === dataKey) loadedRef.current.files.delete(sf);
@@ -10,7 +10,11 @@ import {
10
10
  } from "../components/editor/manualEditsDom";
11
11
  import { STUDIO_MOTION_PATH } from "../components/editor/studioMotion";
12
12
  import { markScenesStale } from "../player/sceneSwap";
13
- import { createDomEditSaveQueue, type DomEditSaveDrainResult } from "../utils/domEditSaveQueue";
13
+ import {
14
+ createDomEditSaveQueue,
15
+ type DomEditSaveDrainResult,
16
+ type DomEditSaveQueueOpenEvent,
17
+ } from "../utils/domEditSaveQueue";
14
18
  import {
15
19
  flushStudioPendingEdits,
16
20
  hasStudioPendingEdits,
@@ -53,6 +57,18 @@ export interface UsePreviewPersistenceParams {
53
57
  reloadPreview: () => void;
54
58
  }
55
59
 
60
+ function saveQueuePaused(event: DomEditSaveQueueOpenEvent): string {
61
+ trackStudioEvent("save_queue_paused", {
62
+ source: "dom_edit",
63
+ ...event.errorCodes,
64
+ status_code: event.statusCode,
65
+ consecutive_failures: event.consecutiveFailures,
66
+ });
67
+ return event.statusCode === 409
68
+ ? "Save paused: this file changed elsewhere. Reload and review the latest version before reapplying your edit."
69
+ : "Auto-save is paused. Check your connection.";
70
+ }
71
+
56
72
  function readIframeDocument(iframe: HTMLIFrameElement): Document | null {
57
73
  try {
58
74
  return iframe.contentDocument;
@@ -131,18 +147,9 @@ export function usePreviewPersistence({
131
147
  if (!domEditSaveQueueRef.current) {
132
148
  domEditSaveQueueRef.current = createDomEditSaveQueue({
133
149
  onOpen: (event) => {
134
- const message =
135
- event.statusCode === 409
136
- ? "Save paused: this file changed elsewhere. Reload and review the latest version before reapplying your edit."
137
- : "Auto-save is paused. Check your connection.";
150
+ const message = saveQueuePaused(event);
138
151
  setDomEditSaveQueuePaused(message);
139
152
  showToastRef.current(message, "error");
140
- trackStudioEvent("save_queue_paused", {
141
- source: "dom_edit",
142
- error_message: event.errorMessage,
143
- status_code: event.statusCode,
144
- consecutive_failures: event.consecutiveFailures,
145
- });
146
153
  },
147
154
  onReset: () => {
148
155
  setDomEditSaveQueuePaused(null);
@@ -797,6 +797,7 @@ describe("useSdkSession unavailable telemetry", () => {
797
797
  expect(trackMock).toHaveBeenCalledWith("sdk_session_unavailable", {
798
798
  stage: "open",
799
799
  error: "unparseable composition",
800
+ error_name: "Error",
800
801
  });
801
802
  await act(async () => root.unmount());
802
803
  });