@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
@@ -0,0 +1,246 @@
1
+ // A sealed preview's GSAP tweens, read over the editing port and shaped like the live objects the
2
+ // readers walk. Tween data answers at any time; values and timeline times only at the playhead read.
3
+ import { useSyncExternalStore } from "react";
4
+ import type { EditingPortClient, EditingResult } from "@hyperframes/core/runtime/editing-port";
5
+ import {
6
+ previewEditingClient,
7
+ previewFrameOpaque,
8
+ previewRequest,
9
+ } from "../player/lib/previewChannel";
10
+ import { onPreviewContentReplaced } from "../player/sceneSwap";
11
+ import { usePlayerStore } from "../player/store/playerStore";
12
+ import { usePreviewIframeStore } from "../player/store/previewIframeStore";
13
+ import { previewStandInHandle } from "../components/editor/previewDrafts";
14
+ import type { RuntimeTimeline } from "./gsapRuntimeKeyframes";
15
+ import { readGsapSnapshot } from "./gsapSnapshotReply";
16
+
17
+ type Snapshot = EditingResult<"gsap-snapshot">;
18
+ type SnapshotTween = Snapshot["timelines"][number]["tweens"][number];
19
+
20
+ interface HeldSnapshot {
21
+ /** The paused playhead the frame was read at. */
22
+ readAt: number | null;
23
+ json: string;
24
+ timelines: Record<string, RuntimeTimeline>;
25
+ document: Document;
26
+ byHandle: Map<string, Element>;
27
+ values: WeakMap<Element, Record<string, number>>;
28
+ defaultEase: string | null;
29
+ }
30
+
31
+ const held = new WeakMap<EditingPortClient, HeldSnapshot>();
32
+ const asking = new WeakMap<EditingPortClient, Promise<void>>();
33
+ const watched = new WeakSet<EditingPortClient>();
34
+ const listeners = new Set<() => void>();
35
+ let version = 0;
36
+
37
+ const pausedPlayhead = (): number | null => {
38
+ const { isPlaying, currentTime } = usePlayerStore.getState();
39
+ return isPlaying ? null : currentTime;
40
+ };
41
+
42
+ function fresh(snapshot: HeldSnapshot): boolean {
43
+ const playhead = pausedPlayhead();
44
+ return playhead !== null && snapshot.readAt === playhead;
45
+ }
46
+
47
+ /** Half a frame at 60 fps: the frame may hold a seek to its own frame grid. */
48
+ const SEEK_TOLERANCE_S = 1 / 120;
49
+ const seekLanded = (frameTime: number | null, readAt: number | null) =>
50
+ frameTime !== null && readAt !== null && Math.abs(frameTime - readAt) <= SEEK_TOLERANCE_S;
51
+
52
+ let watchingPlayhead = false;
53
+
54
+ /** After a seek, the previewed frame is read again where the playhead stopped. */
55
+ function watchPlayhead() {
56
+ if (watchingPlayhead) return;
57
+ watchingPlayhead = true;
58
+ usePlayerStore.subscribe((state, before) => {
59
+ if (state.isPlaying || state.currentTime === before.currentTime) return;
60
+ const { iframe } = usePreviewIframeStore.getState();
61
+ if (iframe && held.has(previewEditingClient(iframe))) void refreshGsapSnapshot(iframe);
62
+ });
63
+ }
64
+
65
+ function announce() {
66
+ version += 1;
67
+ for (const listener of listeners) listener();
68
+ }
69
+
70
+ /** Re-reads the frame's tweens; readers answer from the last read meanwhile. */
71
+ function refreshGsapSnapshot(iframe: HTMLIFrameElement): Promise<void> {
72
+ const client = previewEditingClient(iframe);
73
+ const pending = asking.get(client) ?? read(iframe, client);
74
+ asking.set(client, pending);
75
+ return pending;
76
+ }
77
+
78
+ /** Reads the frame again unless the held read is at the paused playhead; false if an opaque frame holds none. */
79
+ export async function settleGsapSnapshot(iframe: HTMLIFrameElement | null): Promise<boolean> {
80
+ if (!iframe || !previewFrameOpaque(iframe)) return true;
81
+ const client = previewEditingClient(iframe);
82
+ for (let reads = 0; reads < 2; reads++) {
83
+ const snapshot = held.get(client);
84
+ if (snapshot && fresh(snapshot)) return true;
85
+ await refreshGsapSnapshot(iframe);
86
+ }
87
+ return held.has(client);
88
+ }
89
+
90
+ async function read(iframe: HTMLIFrameElement, client: EditingPortClient): Promise<void> {
91
+ watchPlayhead();
92
+ if (!watched.has(client)) {
93
+ watched.add(client);
94
+ const stop = onPreviewContentReplaced(iframe, () => {
95
+ stop();
96
+ held.delete(client);
97
+ watched.delete(client);
98
+ void refreshGsapSnapshot(iframe);
99
+ });
100
+ }
101
+ const readAt = pausedPlayhead();
102
+ try {
103
+ const snapshot = readGsapSnapshot(await previewRequest(iframe, "gsap-snapshot", {}));
104
+ const before = held.get(client);
105
+ if (!snapshot) {
106
+ if (before) held.delete(client);
107
+ return;
108
+ }
109
+ const json = JSON.stringify(snapshot);
110
+ const stamp = pausedPlayhead() === readAt && seekLanded(snapshot.time, readAt) ? readAt : null;
111
+ if (before?.json === json && before.readAt === stamp) return;
112
+ held.set(client, hold(snapshot, json, stamp));
113
+ announce();
114
+ } finally {
115
+ asking.delete(client);
116
+ }
117
+ }
118
+
119
+ /** The last read of an opaque frame, asking again when there is none or the playhead moved. */
120
+ function heldSnapshot(iframe: HTMLIFrameElement | null): HeldSnapshot | null {
121
+ if (!iframe || !previewFrameOpaque(iframe)) return null;
122
+ const snapshot = held.get(previewEditingClient(iframe)) ?? null;
123
+ if (!snapshot || (!fresh(snapshot) && pausedPlayhead() !== null))
124
+ void refreshGsapSnapshot(iframe);
125
+ return snapshot;
126
+ }
127
+
128
+ /** An opaque frame's timelines; null for a same-origin frame or before the first read lands. */
129
+ export function frameTimelines(iframe: HTMLIFrameElement | null) {
130
+ return heldSnapshot(iframe)?.timelines ?? null;
131
+ }
132
+
133
+ /** An opaque frame's tween targets, as elements of a detached document a selector can query. */
134
+ export function frameDocument(iframe: HTMLIFrameElement | null): Document | null {
135
+ return heldSnapshot(iframe)?.document ?? null;
136
+ }
137
+
138
+ export function frameQuery(iframe: HTMLIFrameElement | null, selector: string): Element | null {
139
+ try {
140
+ return frameDocument(iframe)?.querySelector(selector) ?? null;
141
+ } catch {
142
+ return null;
143
+ }
144
+ }
145
+
146
+ /** The snapshot's element for Studio's stand-in of a frame element, matched by handle, else id. */
147
+ export function frameTarget(iframe: HTMLIFrameElement | null, element: Element): Element | null {
148
+ const snapshot = heldSnapshot(iframe);
149
+ if (!snapshot) return null;
150
+ const handle = previewStandInHandle(element);
151
+ const byHandle = handle ? snapshot.byHandle.get(handle) : undefined;
152
+ if (byHandle) return byHandle;
153
+ return element.id ? snapshot.document.getElementById(element.id) : null;
154
+ }
155
+
156
+ /** The ease GSAP falls back to; time-independent. */
157
+ export function frameDefaultEase(iframe: HTMLIFrameElement | null): string | null {
158
+ return heldSnapshot(iframe)?.defaultEase ?? null;
159
+ }
160
+
161
+ /** GSAP's values as read at the paused playhead; null once it moved, until the next read lands. */
162
+ export function frameGsap(iframe: HTMLIFrameElement | null) {
163
+ const snapshot = heldSnapshot(iframe);
164
+ if (!iframe || !snapshot || !fresh(snapshot)) return null;
165
+ return {
166
+ getProperty(element: Element, prop: string): number {
167
+ const target = snapshot.values.has(element) ? element : frameTarget(iframe, element);
168
+ return (target && snapshot.values.get(target)?.[prop]) ?? Number.NaN;
169
+ },
170
+ };
171
+ }
172
+
173
+ function subscribe(listener: () => void) {
174
+ listeners.add(listener);
175
+ return () => listeners.delete(listener);
176
+ }
177
+
178
+ /** Changes when a sealed frame's read lands, so memos over the readers recompute. */
179
+ export function useGsapSnapshotVersion(): number {
180
+ return useSyncExternalStore(
181
+ subscribe,
182
+ () => version,
183
+ () => version,
184
+ );
185
+ }
186
+
187
+ function hold(snapshot: Snapshot, json: string, readAt: number | null): HeldSnapshot {
188
+ const document = window.document.implementation.createHTMLDocument("");
189
+ const byHandle = new Map<string, Element>();
190
+ const values = new WeakMap<Element, Record<string, number>>();
191
+ for (const target of snapshot.targets) {
192
+ const element = document.createElement("div");
193
+ if (target.id) element.id = target.id;
194
+ if (target.className) element.setAttribute("class", target.className);
195
+ document.body.append(element);
196
+ byHandle.set(target.handle, element);
197
+ values.set(element, target.values);
198
+ }
199
+ const held: HeldSnapshot = {
200
+ readAt,
201
+ json,
202
+ // Ids are the frame's: a timeline named __proto__ must stay a timeline.
203
+ timelines: Object.create(null) as Record<string, RuntimeTimeline>,
204
+ document,
205
+ byHandle,
206
+ values,
207
+ defaultEase: snapshot.defaultEase,
208
+ };
209
+ for (const line of snapshot.timelines) {
210
+ const timeline = {
211
+ vars: { defaults: { ease: line.defaultEase ?? undefined } },
212
+ time: () => (fresh(held) ? line.time : null),
213
+ getChildren: () => tweens,
214
+ } as unknown as RuntimeTimeline;
215
+ const tweens = line.tweens.map((tween) => liveShaped(tween, byHandle, timeline));
216
+ held.timelines[line.id] = timeline;
217
+ }
218
+ return held;
219
+ }
220
+
221
+ /** The fields of a GSAP tween the readers use, from the snapshot's copy. */
222
+ function liveShaped(
223
+ tween: SnapshotTween,
224
+ byHandle: Map<string, Element>,
225
+ parent?: unknown,
226
+ ): Record<string, unknown> {
227
+ const targets = tween.targets.flatMap((handle) => byHandle.get(handle) ?? []);
228
+ const _pt = tween.parsed.reduceRight<object | undefined>(
229
+ (next, { p, s, c }) => ({ p, s, c, _next: next }),
230
+ undefined,
231
+ );
232
+ const parts: Array<Record<string, unknown>> = tween.parts.map((part) =>
233
+ liveShaped(part, byHandle),
234
+ );
235
+ return {
236
+ vars: tween.vars,
237
+ _from: tween.from,
238
+ _initted: tween.initted,
239
+ _pt,
240
+ parent,
241
+ targets: () => targets,
242
+ startTime: () => tween.start,
243
+ duration: () => tween.duration,
244
+ ...(parts.length > 0 && { timeline: { getChildren: () => parts } }),
245
+ };
246
+ }
@@ -3,6 +3,7 @@ import { elementTargets } from "../utils/elementGsap";
3
3
  import { resolveTweenStart } from "../utils/globalTimeCompiler";
4
4
  import { KEYFRAME_PCT_MATCH } from "./gsapShared";
5
5
  import { previewFrameOpaque } from "../player/lib/previewChannel";
6
+ import { frameDefaultEase, frameTarget, frameTimelines } from "./gsapFrameSnapshot";
6
7
  import type { ImplicitEndValue } from "./gsapValueAtPlayhead";
7
8
  import type { ReadTween } from "./gsapRuntimeKeyframes";
8
9
 
@@ -82,23 +83,28 @@ export function findParsedTween(
82
83
  element: Element,
83
84
  anim: GsapAnimation,
84
85
  ): ParsedTween | null {
85
- if (!iframe || previewFrameOpaque(iframe)) return null;
86
- const win = iframe.contentWindow as GsapWindow | null;
86
+ if (!iframe) return null;
87
+ const sealed = previewFrameOpaque(iframe);
88
+ const win = sealed ? null : (iframe.contentWindow as GsapWindow | null);
89
+ const timelines = sealed
90
+ ? (frameTimelines(iframe) as GsapWindow["__timelines"])
91
+ : win?.__timelines;
92
+ const target = sealed ? frameTarget(iframe, element) : element;
87
93
  const start = resolveTweenStart(anim);
88
- if (!win?.__timelines || start == null) return null;
94
+ if (!timelines || !target || start == null) return null;
89
95
  const steps = anim.keyframes?.keyframes.map((kf) => kf.properties) ?? [anim.properties];
90
96
  const props = [...new Set(steps.flatMap((step) => Object.keys(step)))];
91
97
  const keyframed = Boolean(anim.keyframes);
92
- for (const timeline of Object.values(win.__timelines)) {
98
+ for (const timeline of Object.values(timelines)) {
93
99
  for (const tween of timeline?.getChildren?.(true) ?? []) {
94
100
  const targets = (tween.targets?.() ?? []) as Array<{ id?: unknown }>;
95
- if (!targets.includes(element) && !targets.some((t) => element.id && t.id === element.id))
101
+ if (!targets.includes(target) && !targets.some((t) => target.id && t.id === target.id))
96
102
  continue;
97
103
  if (!startsAt(tween, start)) continue;
98
104
  const vars = tween.vars ?? {};
99
105
  const carries = keyframed ? "keyframes" in vars : props.some((p) => p in vars);
100
106
  if (!carries || !((tween.duration?.() ?? 0) > 0)) continue;
101
- parseUnplayed(win, element, tween, props);
107
+ if (win) parseUnplayed(win, element, tween, props);
102
108
  return tween;
103
109
  }
104
110
  }
@@ -220,9 +226,10 @@ function partsFrom(tween: ParsedTween, end: "start" | "end"): ParsedTween[] {
220
226
  /** The ease GSAP resolved for a flat tween that authors none: its timeline's default, else GSAP's. */
221
227
  export function parsedTweenEase(iframe: HTMLIFrameElement | null, tween: ParsedTween | null) {
222
228
  if (!tween) return null;
223
- const win = iframe?.contentWindow as GsapWindow | null;
224
- const ease =
225
- tween.vars?.ease ?? tween.parent?.vars?.defaults?.ease ?? win?.gsap?.defaults?.().ease;
229
+ const sealed = iframe ? previewFrameOpaque(iframe) : false;
230
+ const win = sealed ? null : (iframe?.contentWindow as GsapWindow | null);
231
+ const fallback = sealed ? frameDefaultEase(iframe) : win?.gsap?.defaults?.().ease;
232
+ const ease = tween.vars?.ease ?? tween.parent?.vars?.defaults?.ease ?? fallback;
226
233
  if (typeof ease === "string") return ease;
227
234
  const named = (name: string) => win?.gsap?.parseEase?.(name) === ease;
228
235
  return typeof ease === "function" ? (BUILT_IN_EASES.find(named) ?? null) : null;
@@ -19,6 +19,7 @@ import {
19
19
  } from "../utils/elementGsap";
20
20
  import { usePlayerStore } from "../player/store/playerStore";
21
21
  import { readGsapProperty } from "./gsapRuntimeReaders";
22
+ import { gestureStartLayout } from "../components/editor/previewGestureStartRead";
22
23
  import {
23
24
  commitStaticGsapPosition,
24
25
  commitStaticGsapSize,
@@ -321,8 +322,12 @@ export async function tryGsapResizeIntercept(
321
322
  // sent almost every element to the fallback below: a 630px chip scaled by
322
323
  // 630/200, landing over three times the size it was dropped at, and worse
323
324
  // on the next drag because the wrong scale then counted as its live one.
324
- const cssW = originalBoxSize(el, STUDIO_ORIGINAL_BOX_WIDTH_ATTR, "width") ?? 200;
325
- const cssH = originalBoxSize(el, STUDIO_ORIGINAL_BOX_HEIGHT_ATTR, "height") ?? cssW;
325
+ // A sealed preview has no element here: its gesture started from the box the frame measured.
326
+ const started = selection.handle ? gestureStartLayout(selection.handle) : null;
327
+ const cssW =
328
+ originalBoxSize(el, STUDIO_ORIGINAL_BOX_WIDTH_ATTR, "width") ?? (started?.width || 200);
329
+ const cssH =
330
+ originalBoxSize(el, STUDIO_ORIGINAL_BOX_HEIGHT_ATTR, "height") ?? (started?.height || cssW);
326
331
  // `size` is the draft's CSS box; on screen it is multiplied by the element's
327
332
  // LIVE scale (the draft divides the cursor delta by it — see
328
333
  // resolveDomEditResizeGesture). The committed keyframe REPLACES that live
@@ -33,6 +33,7 @@ import { roundTo3 } from "../utils/rounding";
33
33
  import type { GsapDragCommitCallbacks } from "./gsapDragCommit";
34
34
  import { readDragStamp, type DragStamp } from "./draggedGsapPosition";
35
35
  import { editMoment } from "./editMoment";
36
+ import { settleGsapSnapshot } from "./gsapFrameSnapshot";
36
37
  import type { EditMoment } from "../components/editor/manualEditsTypes";
37
38
  import { isInstantHold, selectorFromSelection, writeTargetSelector } from "./gsapShared";
38
39
  import {
@@ -261,6 +262,9 @@ export async function tryGsapDragIntercept(
261
262
  const stamp = options?.stamp ?? readDragStamp(selection.element);
262
263
  const moment = editMoment(stamp);
263
264
  const time = moment.time;
265
+ if (!(await settleGsapSnapshot(iframe)) && stamp.moving) {
266
+ return { status: "blocked", reason: "source-uneditable", detail: "frame-tweens-unreadable" };
267
+ }
264
268
  if (!options?.preflightPassed) {
265
269
  const preflight = await preflightGsapDragIntercept(
266
270
  selection,
@@ -17,6 +17,8 @@ import { matchesElement, tweensTargeting } from "./gsapRuntimeTweenIndex";
17
17
  import { withParsedStart } from "./gsapParsedTween";
18
18
  import { BOX_SIZE_STYLE_PROPS } from "../components/editor/manualEditsDomPatches";
19
19
  import { gsapRendersTransform } from "../components/editor/gsapAnimatesProperty";
20
+ import { previewFrameOpaque } from "../player/lib/previewChannel";
21
+ import { frameQuery, frameTimelines } from "./gsapFrameSnapshot";
20
22
 
21
23
  /**
22
24
  * A GSAP tween's `vars` object — intentionally open: it mixes channel values
@@ -96,6 +98,20 @@ function timelinesOf(iframe: HTMLIFrameElement | null): Record<string, RuntimeTi
96
98
  }
97
99
  }
98
100
 
101
+ /** A sealed frame reads from its snapshot; resolveRuntimeTween patches, so it takes live tweens only. */
102
+ function readableTimelines(iframe: HTMLIFrameElement | null) {
103
+ return iframe && previewFrameOpaque(iframe) ? frameTimelines(iframe) : timelinesOf(iframe);
104
+ }
105
+
106
+ function readableTarget(iframe: HTMLIFrameElement | null, selector: string): Element | null {
107
+ if (iframe && previewFrameOpaque(iframe)) return frameQuery(iframe, selector);
108
+ try {
109
+ return iframe?.contentDocument?.querySelector(selector) ?? null;
110
+ } catch {
111
+ return null;
112
+ }
113
+ }
114
+
99
115
  /**
100
116
  * A tween we must skip when reading keyframes: a zero-duration `set`/hold (incl.
101
117
  * the studio pre-keyframe position hold, tagged `data: STUDIO_HOLD_MARKER`).
@@ -292,15 +308,10 @@ export function readRuntimeKeyframes(
292
308
  requireChannels?: string[],
293
309
  // fallow-ignore-next-line code-duplication
294
310
  ): ReadTween | null {
295
- const timelines = timelinesOf(iframe);
311
+ const timelines = readableTimelines(iframe);
296
312
  if (!timelines) return null;
297
313
 
298
- let targetEl: Element | null = null;
299
- try {
300
- targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
301
- } catch {
302
- return null;
303
- }
314
+ const targetEl = readableTarget(iframe, selector);
304
315
  if (!targetEl) return null;
305
316
 
306
317
  // Search the element's OWN composition timeline. With inlined subcompositions the
@@ -366,13 +377,10 @@ export function hasNonHoldTweenForElement(
366
377
  compositionId?: string,
367
378
  channels?: string[],
368
379
  ): boolean {
369
- let targetEl: Element | null = null;
370
- try {
371
- targetEl = iframe?.contentDocument?.querySelector(selector) ?? null;
372
- } catch {
373
- return false;
374
- }
375
- return !!targetEl && hasNonHoldTween(timelinesOf(iframe), targetEl, channels, compositionId);
380
+ const targetEl = readableTarget(iframe, selector);
381
+ return (
382
+ !!targetEl && hasNonHoldTween(readableTimelines(iframe), targetEl, channels, compositionId)
383
+ );
376
384
  }
377
385
 
378
386
  // A sibling rotation/scale tween must never push a static position hold into the keyframe branch.
@@ -545,7 +553,7 @@ export function scanAllRuntimeKeyframes(
545
553
  clipById?: ClipDims,
546
554
  ): Map<string, RuntimeKeyframeEntry> {
547
555
  const result = new Map<string, RuntimeKeyframeEntry>();
548
- const timelines = timelinesOf(iframe);
556
+ const timelines = readableTimelines(iframe);
549
557
  if (!timelines) return result;
550
558
  for (const timeline of Object.values(timelines)) {
551
559
  if (!timeline?.getChildren) continue;
@@ -14,6 +14,8 @@ import {
14
14
  resolveTweenDuration,
15
15
  } from "../utils/globalTimeCompiler";
16
16
  import { toCompositionTime } from "../player/store/timelineElement";
17
+ import { previewFrameOpaque } from "../player/lib/previewChannel";
18
+ import { frameGsap, frameQuery } from "./gsapFrameSnapshot";
17
19
 
18
20
  // ── Types ─────────────────────────────────────────────────────────────────────
19
21
 
@@ -361,6 +363,7 @@ export function computeElementPercentage(
361
363
 
362
364
  /** Safely retrieve the GSAP runtime from the preview iframe. */
363
365
  export function getIframeGsap(iframe: HTMLIFrameElement | null): IframeGsap | null {
366
+ if (iframe && previewFrameOpaque(iframe)) return frameGsap(iframe);
364
367
  if (!iframe?.contentWindow) return null;
365
368
  try {
366
369
  const gsap = (iframe.contentWindow as unknown as { gsap?: IframeGsap }).gsap;
@@ -375,6 +378,7 @@ export function queryIframeElement(
375
378
  iframe: HTMLIFrameElement | null,
376
379
  selector: string,
377
380
  ): Element | null {
381
+ if (iframe && previewFrameOpaque(iframe)) return frameQuery(iframe, selector);
378
382
  try {
379
383
  return iframe?.contentDocument?.querySelector(selector) ?? null;
380
384
  } catch {
@@ -0,0 +1,105 @@
1
+ // A gsap-snapshot reply is frame data: Studio holds one only in the shape and within the
2
+ // bounds the frame keeps to.
3
+ import {
4
+ MAX_SNAPSHOT_CHANNELS,
5
+ MAX_SNAPSHOT_FIELDS,
6
+ MAX_SNAPSHOT_TARGETS,
7
+ MAX_SNAPSHOT_TEXT,
8
+ MAX_SNAPSHOT_TWEENS,
9
+ MAX_VARS_DEPTH,
10
+ type EditingResult,
11
+ } from "@hyperframes/core/runtime/editing-port";
12
+ import { isFields, isHandle } from "../player/lib/previewElements";
13
+
14
+ type Snapshot = EditingResult<"gsap-snapshot">;
15
+ /** What the whole reply may still spend, shared by every tween and vars field in it. */
16
+ type Budget = { tweens: number; fields: number };
17
+
18
+ const isText = (value: unknown): value is string =>
19
+ typeof value === "string" && value.length <= MAX_SNAPSHOT_TEXT;
20
+ const isTextOrNull = (value: unknown) => value === null || isText(value);
21
+ const isNumber = (value: unknown): value is number =>
22
+ typeof value === "number" && Number.isFinite(value);
23
+ const isNumberOrNull = (value: unknown) => value === null || isNumber(value);
24
+ const isList = (value: unknown, max: number): value is unknown[] =>
25
+ Array.isArray(value) && value.length <= max;
26
+
27
+ /** The reply as a snapshot, or null when any part of it is off its shape or past a bound. */
28
+ export function readGsapSnapshot(value: unknown): Snapshot | null {
29
+ if (!isFields(value) || !isNumberOrNull(value.time) || !isTextOrNull(value.defaultEase))
30
+ return null;
31
+ const budget: Budget = { tweens: MAX_SNAPSHOT_TWEENS, fields: MAX_SNAPSHOT_FIELDS };
32
+ const { timelines, targets } = value;
33
+ const ok =
34
+ isList(timelines, MAX_SNAPSHOT_TWEENS) &&
35
+ timelines.every((line) => isTimeline(line, budget)) &&
36
+ isList(targets, MAX_SNAPSHOT_TARGETS) &&
37
+ targets.every(isTarget);
38
+ return ok ? (value as unknown as Snapshot) : null;
39
+ }
40
+
41
+ function isTimeline(value: unknown, budget: Budget): boolean {
42
+ return (
43
+ isFields(value) &&
44
+ isText(value.id) &&
45
+ isNumberOrNull(value.time) &&
46
+ isTextOrNull(value.defaultEase) &&
47
+ isList(value.tweens, MAX_SNAPSHOT_TWEENS) &&
48
+ value.tweens.every((tween) => isTween(tween, budget))
49
+ );
50
+ }
51
+
52
+ function isTween(value: unknown, budget: Budget): boolean {
53
+ if ((budget.tweens -= 1) < 0 || !isFields(value)) return false;
54
+ return (
55
+ isTargetHandles(value.targets) &&
56
+ isFields(value.vars) &&
57
+ isVars(value.vars, budget, 0) &&
58
+ isTiming(value) &&
59
+ isParsed(value.parsed) &&
60
+ areParts(value.parts, budget)
61
+ );
62
+ }
63
+
64
+ const isTargetHandles = (value: unknown) =>
65
+ isList(value, MAX_SNAPSHOT_TARGETS) && value.every(isHandle);
66
+
67
+ const isTiming = (tween: Record<string, unknown>) =>
68
+ isNumber(tween.start) &&
69
+ isNumber(tween.duration) &&
70
+ typeof tween.from === "boolean" &&
71
+ typeof tween.initted === "boolean";
72
+
73
+ const isChannel = (value: unknown) =>
74
+ isFields(value) && isText(value.p) && isNumber(value.s) && isNumber(value.c);
75
+
76
+ const isParsed = (value: unknown) => isList(value, MAX_SNAPSHOT_CHANNELS) && value.every(isChannel);
77
+
78
+ function areParts(value: unknown, budget: Budget): boolean {
79
+ return isList(value, MAX_SNAPSHOT_TWEENS) && value.every((part) => isTween(part, budget));
80
+ }
81
+
82
+ /** A plain vars value: finite numbers, bounded text, booleans, null, and lists and records
83
+ * no deeper than the frame's. */
84
+ function isVars(value: unknown, budget: Budget, depth: number): boolean {
85
+ if ((budget.fields -= 1) < 0) return false;
86
+ if (value === null || typeof value === "boolean" || isNumber(value) || isText(value)) return true;
87
+ if (depth >= MAX_VARS_DEPTH) return false;
88
+ if (Array.isArray(value)) return value.every((item) => isVars(item, budget, depth + 1));
89
+ return (
90
+ isFields(value) &&
91
+ Object.entries(value).every(([key, item]) => isText(key) && isVars(item, budget, depth + 1))
92
+ );
93
+ }
94
+
95
+ function isTarget(value: unknown): boolean {
96
+ if (!isFields(value) || !isFields(value.values)) return false;
97
+ const values = Object.entries(value.values);
98
+ return (
99
+ isHandle(value.handle) &&
100
+ isText(value.id) &&
101
+ isText(value.className) &&
102
+ values.length <= MAX_SNAPSHOT_CHANNELS &&
103
+ values.every(([key, number]) => isText(key) && isNumber(number))
104
+ );
105
+ }