@hyperframes/studio 0.9.40 → 0.9.42

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 (93) hide show
  1. package/dist/assets/{codec-BPK_2CLL.js → codec-CKqLGYc6.js} +1 -1
  2. package/dist/assets/{hyperframes-player-D7qTTDIp.js → hyperframes-player-DoEYqOIa.js} +1 -1
  3. package/dist/assets/{index-CdA00Ybn.js → index-DLyQ91Ek.js} +166 -166
  4. package/dist/assets/{index-QS-DuxAU.js → index-s9iqoWnr.js} +1 -1
  5. package/dist/assets/{pausedVideoDecoder-Byzz98Gb.js → pausedVideoDecoder-B-ReRg6i.js} +1 -1
  6. package/dist/{chunk-KF6YVXJP.js → chunk-4QQMX4BX.js} +6 -3
  7. package/dist/{chunk-VZ5MD32A.js → chunk-GVW7AU57.js} +190 -254
  8. package/dist/{chunk-AV2PV7NE.js → chunk-VHV2ZDKY.js} +4 -40
  9. package/dist/{domEditingLayers-4KRREI5C.js → domEditingLayers-SA5KLSSS.js} +4 -2
  10. package/dist/index.d.ts +12 -0
  11. package/dist/index.html +1 -1
  12. package/dist/index.js +1501 -818
  13. package/dist/player.js +2 -2
  14. package/package.json +10 -10
  15. package/src/components/editor/DomEditOverlay.tsx +3 -15
  16. package/src/components/editor/LayersPanel.opaque.test.ts +176 -0
  17. package/src/components/editor/LayersPanel.tsx +41 -10
  18. package/src/components/editor/clickAfterPreventedPress.test.tsx +17 -1
  19. package/src/components/editor/domEditInlineText.ts +1 -16
  20. package/src/components/editor/domEditOverlayBasis.ts +7 -2
  21. package/src/components/editor/domEditOverlayCrop.test.ts +1 -1
  22. package/src/components/editor/domEditOverlayCrop.ts +17 -3
  23. package/src/components/editor/domEditOverlayGeometry.ts +64 -139
  24. package/src/components/editor/domEditSelectionRules.ts +138 -0
  25. package/src/components/editor/domEditing.test.ts +6 -28
  26. package/src/components/editor/domEditingDom.preview.test.ts +3 -3
  27. package/src/components/editor/domEditingDom.ts +3 -76
  28. package/src/components/editor/domEditingElement.ts +19 -240
  29. package/src/components/editor/domEditingGroups.ts +0 -31
  30. package/src/components/editor/domEditingLayers.ts +95 -100
  31. package/src/components/editor/domEditingRootLayer.ts +35 -30
  32. package/src/components/editor/domEditingTypes.ts +10 -0
  33. package/src/components/editor/gestureUndoRevert.ts +18 -1
  34. package/src/components/editor/inlineTextStyleRange.fill.test.ts +129 -0
  35. package/src/components/editor/inlineTextStyleRange.test.ts +0 -82
  36. package/src/components/editor/layerKind.ts +2 -19
  37. package/src/components/editor/layersPanelSort.ts +2 -2
  38. package/src/components/editor/manualEdits.ts +1 -0
  39. package/src/components/editor/manualEditsSnapshot.ts +10 -0
  40. package/src/components/editor/manualOffsetDrag.test.ts +1 -1
  41. package/src/components/editor/manualOffsetDrag.ts +7 -1
  42. package/src/components/editor/marqueeCommit.ts +47 -4
  43. package/src/components/editor/plainTranslate.ts +35 -16
  44. package/src/components/editor/previewDrafts.test.ts +263 -0
  45. package/src/components/editor/previewDrafts.ts +73 -0
  46. package/src/components/editor/previewGestureStarts.ts +73 -10
  47. package/src/components/editor/previewLayers.test.ts +308 -0
  48. package/src/components/editor/previewLayers.ts +164 -0
  49. package/src/components/editor/previewOverlayRects.test.ts +316 -0
  50. package/src/components/editor/previewOverlayRects.ts +150 -0
  51. package/src/components/editor/previewPointerTargets.test.ts +327 -0
  52. package/src/components/editor/previewSelection.test.ts +481 -0
  53. package/src/components/editor/previewSelection.ts +516 -0
  54. package/src/components/editor/probeSourceElement.ts +19 -1
  55. package/src/components/editor/propertyPanelFill.tsx +5 -1
  56. package/src/components/editor/resizeDraft.ts +38 -0
  57. package/src/components/editor/useDomEditOverlayGestures.ts +2 -2
  58. package/src/components/editor/useDomEditOverlayRects.ts +80 -1
  59. package/src/components/editor/useInlineTextEditing.tsx +1 -6
  60. package/src/components/editor/useLayerDrag.ts +1 -1
  61. package/src/components/nle/NLEPreview.slowBoot.test.ts +0 -1
  62. package/src/hooks/domEditDeleteMembers.test.ts +7 -0
  63. package/src/hooks/domSelectionTestHarness.ts +1 -1
  64. package/src/hooks/domSelectionTimelineMirror.ts +3 -1
  65. package/src/hooks/timelineTimingSync.ts +4 -1
  66. package/src/hooks/useDomEditSession.test.tsx +23 -1
  67. package/src/hooks/useDomEditSession.ts +2 -1
  68. package/src/hooks/useDomSelection.ts +63 -47
  69. package/src/hooks/useEditorSave.test.tsx +22 -1
  70. package/src/hooks/useEditorSave.ts +3 -1
  71. package/src/hooks/useGsapSelectionHandlers.test.tsx +17 -0
  72. package/src/hooks/useGsapSelectionHandlers.ts +2 -1
  73. package/src/hooks/usePreviewInteraction.test.ts +10 -2
  74. package/src/hooks/usePreviewInteraction.ts +9 -5
  75. package/src/hooks/useProjectFileWriter.ts +7 -3
  76. package/src/hooks/useStudioSelectionPublisher.test.tsx +50 -0
  77. package/src/hooks/useStudioSelectionPublisher.ts +9 -7
  78. package/src/hooks/useTimelineSelectionPreviewSync.test.tsx +30 -0
  79. package/src/hooks/useTimelineSelectionPreviewSync.ts +7 -2
  80. package/src/player/lib/layerOrdering.ts +2 -11
  81. package/src/player/lib/previewChannel.ts +4 -3
  82. package/src/player/lib/previewElements.ts +143 -3
  83. package/src/styles/hex-baseline.json +1 -2
  84. package/src/test-setup.ts +2 -0
  85. package/src/utils/gsapSoftReload.ts +1 -1
  86. package/src/utils/studioFileHistory.ts +1 -1
  87. package/src/utils/studioHelpers.ts +27 -17
  88. package/src/utils/studioPreviewHelpers.test.ts +8 -8
  89. package/src/utils/studioPreviewHelpers.ts +26 -242
  90. package/src/utils/studioSaveDiagnostics.test.ts +34 -0
  91. package/src/utils/studioSaveDiagnostics.ts +35 -6
  92. package/src/utils/timelineCompositionInsert.ts +3 -1
  93. package/src/components/editor/domEditOverlayTransform.ts +0 -126
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * RAF-driven hook that tracks overlay, hover, and group rects from the iframe DOM.
3
3
  * Runs a requestAnimationFrame loop and writes React state only when rects change.
4
+ * A frame Studio cannot script is measured over its channel instead, one read at a time.
4
5
  */
5
6
  import { useRef, useState, type RefObject } from "react";
6
7
  import { useMountEffect } from "../../hooks/useMountEffect";
@@ -21,6 +22,8 @@ import {
21
22
  } from "./domEditOverlayGeometry";
22
23
  import { computeOverlayRootScale } from "./domEditOverlayBasis";
23
24
  import { subscribeOverlayFrame } from "./overlayFrameLoop";
25
+ import { previewFrameOpaque } from "../../player/lib/previewChannel";
26
+ import { measurePreviewOverlay } from "./previewOverlayRects";
24
27
 
25
28
  function childRectsEqual(a: OverlayRect[], b: OverlayRect[]): boolean {
26
29
  if (a.length !== b.length) return false;
@@ -74,6 +77,7 @@ export function useDomEditOverlayRects({
74
77
  const resolvedHoverElementRef = useRef<{ key: string; element: HTMLElement } | null>(null);
75
78
  const resolvedGroupElementRef = useRef<Map<string, HTMLElement>>(new Map());
76
79
  const childRectsRef = useRef<OverlayRect[]>([]);
80
+ const channelReadRef = useRef(false);
77
81
 
78
82
  const setOverlayRect = (next: OverlayRect | null) => {
79
83
  if (rectsEqual(overlayRectRef.current, next)) return;
@@ -107,6 +111,74 @@ export function useDomEditOverlayRects({
107
111
  return next;
108
112
  };
109
113
 
114
+ const setChildRects = (next: OverlayRect[]) => {
115
+ if (childRectsEqual(childRectsRef.current, next)) return;
116
+ childRectsRef.current = next;
117
+ setChildRectsState(next);
118
+ };
119
+
120
+ /** Members of the same group collapse to one selection under select-as-unit, so one key each. */
121
+ const distinctGroup = (group: DomEditSelection[]) => {
122
+ const keys = new Set<string>();
123
+ return group.flatMap((selection) => {
124
+ const key = selectionCacheKey(selection);
125
+ if (keys.has(key)) return [];
126
+ keys.add(key);
127
+ return [{ key, selection }];
128
+ });
129
+ };
130
+
131
+ const hoverShown = (sel: DomEditSelection | null, group: DomEditSelection[]) => {
132
+ const hoverSel = hoverSelectionRef.current;
133
+ const key = hoverSel && selectionCacheKey(hoverSel);
134
+ const covered =
135
+ (sel && selectionCacheKey(sel) === key) ||
136
+ group.some((entry) => selectionCacheKey(entry) === key);
137
+ return covered ? null : hoverSel;
138
+ };
139
+
140
+ /** The opaque frame's rects, one geometry read in flight at a time; a stale answer is dropped. */
141
+ const updateOverChannel = (iframe: HTMLIFrameElement, overlayEl: HTMLDivElement) => {
142
+ if (channelReadRef.current) return;
143
+ const sel = selectionRef.current;
144
+ const group = groupSelectionsRef.current;
145
+ const members = distinctGroup(group);
146
+ const hover = hoverShown(sel, group);
147
+ const targets = {
148
+ selection: sel?.handle ?? null,
149
+ group: members.map(({ selection }) => selection.handle ?? null),
150
+ hover: hover?.handle ?? null,
151
+ };
152
+ if (!sel && !members.length && !hover) {
153
+ setOverlayRect(null);
154
+ setChildRects([]);
155
+ setGroupOverlayItems([]);
156
+ setHoverRect(null);
157
+ return;
158
+ }
159
+ channelReadRef.current = true;
160
+ void measurePreviewOverlay(iframe, overlayEl, targets)
161
+ .then((rects) => {
162
+ const current =
163
+ selectionRef.current === sel &&
164
+ groupSelectionsRef.current === group &&
165
+ hoverShown(sel, group) === hover;
166
+ if (!rects || !current || rafPausedRef.current || iframeRef.current !== iframe) return;
167
+ setOverlayRect(rects.selection);
168
+ setChildRects(rects.children);
169
+ setGroupOverlayItems(
170
+ members.flatMap(({ key, selection }, index) => {
171
+ const rect = rects.group[index];
172
+ return rect ? [{ key, selection, element: selection.element, rect }] : [];
173
+ }),
174
+ );
175
+ setHoverRect(rects.hover);
176
+ })
177
+ .finally(() => {
178
+ channelReadRef.current = false;
179
+ });
180
+ };
181
+
110
182
  useMountEffect(() => {
111
183
  const clearAll = () => {
112
184
  setOverlayRect(null);
@@ -261,7 +333,14 @@ export function useDomEditOverlayRects({
261
333
  setHoverRect(orientedGroupAwareOverlayRect(overlayEl, iframe, hoverEl, scale));
262
334
  };
263
335
 
264
- return subscribeOverlayFrame(update);
336
+ const frame = () => {
337
+ const iframe = iframeRef.current;
338
+ const overlayEl = overlayRef.current;
339
+ const channel = !rafPausedRef.current && iframe && overlayEl && !iframe.contentDocument;
340
+ if (channel && previewFrameOpaque(iframe)) updateOverChannel(iframe, overlayEl);
341
+ else update();
342
+ };
343
+ return subscribeOverlayFrame(frame);
265
344
  });
266
345
 
267
346
  return {
@@ -64,12 +64,7 @@ export function useInlineTextEditing(
64
64
  if (!iframe) return null;
65
65
  // The same hit test the canvas uses to decide what was clicked; a plain
66
66
  // elementFromPoint only finds wrappers, since Studio suppresses pointer events.
67
- return getPreviewTargetFromPointer(
68
- iframe,
69
- event.clientX,
70
- event.clientY,
71
- selectionRef.current?.compositionPath ?? null,
72
- );
67
+ return getPreviewTargetFromPointer(iframe, event.clientX, event.clientY);
73
68
  };
74
69
 
75
70
  /** A point on Studio's canvas, in the scaled composition's coordinates. */
@@ -36,7 +36,7 @@ export interface UseLayerDragReturn {
36
36
  }
37
37
 
38
38
  export function isLayerDraggable(layer: DomEditLayerItem): boolean {
39
- if (!(layer.selector || layer.id)) return false;
39
+ if (!(layer.selector || layer.id) || layer.preview) return false;
40
40
  let el: HTMLElement | null = layer.element;
41
41
  while (el) {
42
42
  if (el.hasAttribute("data-timeline-locked")) return false;
@@ -1,5 +1,4 @@
1
1
  // @vitest-environment happy-dom
2
- // @vitest-environment-options {"happyDOM":{"settings":{"disableIframePageLoading":true}}}
3
2
 
4
3
  import React, { act, createRef } from "react";
5
4
  import { createRoot } from "react-dom/client";
@@ -27,4 +27,11 @@ describe("timelineElementsForDelete", () => {
27
27
  const elements = [clip("a", "clip-a")];
28
28
  expect(timelineElementsForDelete([sel("nested-text")], elements)).toBeNull();
29
29
  });
30
+
31
+ it("leaves an opaque frame's selection on the DOM path, as its clip-id row has no patch target", () => {
32
+ // An opaque frame's rows carry only the clip id; the selection carries the frame's handle.
33
+ const row = { id: "title", sourceFile: "index.html", start: 0, duration: 1, track: 0 };
34
+ const opaque = { ...sel("title"), handle: "0123456789abcdef:1" } as DomEditSelection;
35
+ expect(timelineElementsForDelete([opaque], [row as TimelineElement])).toBeNull();
36
+ });
30
37
  });
@@ -63,7 +63,7 @@ export function makeSelection(label: string, element: HTMLElement): DomEditSelec
63
63
  };
64
64
  }
65
65
 
66
- /** Built as getDomLayerPatchTarget builds it: a bare class for an element with no id or hf-id. */
66
+ /** Built as resolveDomLayerIdentity builds it: a bare class for an element with no id or hf-id. */
67
67
  export function stableSelectionFor(el: HTMLElement): DomEditSelection {
68
68
  const selector = buildStableSelector(el);
69
69
  return {
@@ -6,6 +6,7 @@ import { logSelect } from "../utils/selectDebug";
6
6
 
7
7
  interface TimelineMirrorDeps {
8
8
  timelineElements: TimelineElement[];
9
+ activeCompPath: string | null;
9
10
  getTimelineSelectionSet: () => ReadonlySet<string>;
10
11
  setSelectedTimelineElementId: (id: string | null, options?: SelectElementOptions) => void;
11
12
  setTimelineSelectionSet: (ids: Set<string>) => void;
@@ -32,6 +33,7 @@ export function announceTimelineSelection(
32
33
  ): void {
33
34
  const {
34
35
  timelineElements,
36
+ activeCompPath,
35
37
  getTimelineSelectionSet,
36
38
  setSelectedTimelineElementId,
37
39
  setTimelineSelectionSet,
@@ -42,7 +44,7 @@ export function announceTimelineSelection(
42
44
  return;
43
45
  }
44
46
  const timelineIdFor = (selection: DomEditSelection) =>
45
- findMatchingTimelineElementId(selection, timelineElements) ??
47
+ findMatchingTimelineElementId(selection, timelineElements, activeCompPath || "index.html") ??
46
48
  findTimelineIdByAncestor(
47
49
  selection.element,
48
50
  timelineElements,
@@ -30,6 +30,7 @@ import {
30
30
  type StudioProjectFileWriter,
31
31
  } from "../utils/studioFileMutationCoordinator";
32
32
  import { studioApiFetch } from "../utils/studioApiFetch";
33
+ import { createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
33
34
  import { moveLiveTweens } from "../utils/gsapLiveRetime";
34
35
 
35
36
  export async function readFileContent(projectId: string, targetPath: string): Promise<string> {
@@ -40,7 +41,9 @@ export async function readFileContent(projectId: string, targetPath: string): Pr
40
41
  `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(targetPath)}`,
41
42
  );
42
43
  if (!response.ok) {
43
- throw new Error(`Failed to read ${targetPath}`);
44
+ throw await createStudioSaveHttpError(response, `Failed to read ${targetPath}`, {
45
+ path: targetPath,
46
+ });
44
47
  }
45
48
  const data = (await response.json()) as { content?: string };
46
49
  if (typeof data.content !== "string") {
@@ -64,6 +64,7 @@ const capturedOnReorderShadow: { fn: ((targets: string[]) => void) | undefined }
64
64
  const domEditSelectionRef: { current: DomEditSelection | null } = { current: null };
65
65
  const domEditGroupSelectionsRef: { current: DomEditSelection[] } = { current: [] };
66
66
  const groupSelectionSpy = vi.fn();
67
+ const ungroupSelectionSpy = vi.fn();
67
68
  const gsapCommitMutation = Object.assign(vi.fn(), { batch: vi.fn() });
68
69
  const neverParsed = new Promise<{ animations: GsapAnimation[] }>(() => undefined);
69
70
  const parsedFile = { current: neverParsed };
@@ -211,7 +212,7 @@ vi.mock("./useGsapScriptCommits", () => ({
211
212
  vi.mock("./useGroupCommits", () => ({
212
213
  useGroupCommits: () => ({
213
214
  groupSelection: (...args: unknown[]) => groupSelectionSpy(...args),
214
- ungroupSelection: vi.fn(),
215
+ ungroupSelection: (...args: unknown[]) => ungroupSelectionSpy(...args),
215
216
  }),
216
217
  }));
217
218
  vi.mock("./useDomEditWiring", () => ({
@@ -501,6 +502,27 @@ describe("handleGroupSelection with audio in the selection", () => {
501
502
  await group([sel("div"), sel("span")]);
502
503
  expect(groupSelectionSpy).toHaveBeenCalledTimes(1);
503
504
  });
505
+
506
+ it("ungroups an opaque frame's group, read off its description, not the tag-only stand-in", async () => {
507
+ const { useDomEditSession } = await import("./useDomEditSession");
508
+ const wrapper = {
509
+ ...sel("div"),
510
+ handle: "0123456789abcdef:1",
511
+ dataAttributes: { "hf-group": "g" },
512
+ };
513
+ domEditSelectionRef.current = wrapper as DomEditSelection;
514
+ const captured: { fn?: () => void } = {};
515
+ function Probe() {
516
+ captured.fn = useDomEditSession(createSessionParams()).handleUngroupSelection;
517
+ return null;
518
+ }
519
+ const root = createRoot(document.createElement("div"));
520
+ act(() => root.render(<Probe />));
521
+ act(() => captured.fn?.());
522
+ act(() => root.unmount());
523
+ domEditSelectionRef.current = null;
524
+ expect(ungroupSelectionSpy).toHaveBeenCalledWith(wrapper);
525
+ });
504
526
  });
505
527
 
506
528
  // ── Delete routing: a timeline row goes through the timeline's own delete op ──
@@ -21,6 +21,7 @@ import { useStudioSelectionPublisher } from "./useStudioSelectionPublisher";
21
21
  import { useKeyframeEaseCommits } from "./useKeyframeEaseCommits";
22
22
  import { useCommitPreflightCapabilities } from "./useCommitPreflightCapabilities";
23
23
  import type { DomEditSelection } from "../components/editor/domEditingTypes";
24
+ import { selectionDataAttribute } from "../components/editor/previewSelection";
24
25
  import { membersForDelete, timelineElementsForDelete } from "./domEditDeleteMembers";
25
26
  import type { RecordEditInput } from "./domEditDeleteMembers";
26
27
  import type { DomEditTimelineParams } from "./useDomSelectionTypes";
@@ -351,7 +352,7 @@ export function useDomEditSession({
351
352
 
352
353
  const handleUngroupSelection = useCallback(() => {
353
354
  const sel = domEditSelectionRef.current;
354
- if (!sel?.element.hasAttribute("data-hf-group")) {
355
+ if (!sel || selectionDataAttribute(sel, "data-hf-group") === null) {
355
356
  showToast("Select a group to ungroup", "info");
356
357
  return;
357
358
  }
@@ -1,9 +1,5 @@
1
1
  import { useState, useCallback, useRef, useEffect } from "react";
2
2
  import type { TimelineElement } from "../player";
3
- import {
4
- getAllPreviewTargetsFromPointer,
5
- getPreviewTargetFromPointer,
6
- } from "../utils/studioPreviewHelpers";
7
3
  import {
8
4
  domEditSelectionsEqual,
9
5
  domEditSelectionsTargetSame,
@@ -13,11 +9,19 @@ import {
13
9
  seedDomEditGroupWithSelection,
14
10
  } from "../utils/domEditHelpers";
15
11
  import {
16
- findElementForSelection,
17
12
  findElementForTimelineElement,
18
- resolveDomEditSelection,
19
13
  type DomEditSelection,
20
14
  } from "../components/editor/domEditing";
15
+ import {
16
+ elementWithin,
17
+ findOpaqueTimelineElement,
18
+ findPointerTarget,
19
+ findPointerTargets,
20
+ findSelectionElement,
21
+ resolveFoundSelection,
22
+ selectionElementLive,
23
+ } from "../components/editor/previewSelection";
24
+ import type { PreviewElement } from "../player/lib/previewElements";
21
25
  import { reapplyPositionEditsAfterSeek } from "../components/editor/manualEdits";
22
26
  import { holdScenesOf } from "../utils/sceneHold";
23
27
  import { useStudioTestHooks } from "./useStudioTestHooks";
@@ -38,6 +42,15 @@ export type {
38
42
  UseDomSelectionReturn,
39
43
  } from "./useDomSelectionTypes";
40
44
 
45
+ /** A refreshed group lands only when it found someone and the user has not picked another meanwhile. */
46
+ function groupStillLive(
47
+ live: { current: DomEditSelection[] },
48
+ refreshed: DomEditSelection[],
49
+ next: DomEditSelection[],
50
+ ): boolean {
51
+ return next.length > 0 && live.current === refreshed;
52
+ }
53
+
41
54
  // ── Hook ──
42
55
 
43
56
  export function useDomSelection({
@@ -91,6 +104,7 @@ export function useDomSelection({
91
104
  announceSelectionToTimeline(
92
105
  {
93
106
  timelineElements,
107
+ activeCompPath,
94
108
  getTimelineSelectionSet,
95
109
  setSelectedTimelineElementId,
96
110
  setTimelineSelectionSet,
@@ -100,6 +114,7 @@ export function useDomSelection({
100
114
  replaceSet,
101
115
  ),
102
116
  [
117
+ activeCompPath,
103
118
  getTimelineSelectionSet,
104
119
  setSelectedTimelineElementId,
105
120
  setTimelineSelectionSet,
@@ -176,7 +191,7 @@ export function useDomSelection({
176
191
  // Selecting something outside the drilled-into group exits the drill-in, so
177
192
  // a later click on the group selects it as a unit again (non-sticky drill-in).
178
193
  const activeGroup = activeGroupElementRef.current;
179
- if (activeGroup && nextSelection && !activeGroup.contains(nextSelection.element)) {
194
+ if (activeGroup && nextSelection && !elementWithin(activeGroup, nextSelection.element)) {
180
195
  activeGroupElementRef.current = null;
181
196
  setActiveGroupElementState(null);
182
197
  }
@@ -216,8 +231,12 @@ export function useDomSelection({
216
231
  );
217
232
 
218
233
  const buildDomSelectionFromTarget = useCallback(
219
- (target: HTMLElement, options?: ResolveDomSelectionOptions) => {
220
- return resolveDomEditSelection(target, {
234
+ (
235
+ target: HTMLElement | PreviewElement,
236
+ options?: ResolveDomSelectionOptions,
237
+ iframe = previewIframeRef.current,
238
+ ) => {
239
+ return resolveFoundSelection(iframe, target, {
221
240
  activeCompositionPath: activeCompPath,
222
241
  isMasterView,
223
242
  preferClipAncestor: options?.preferClipAncestor,
@@ -231,7 +250,7 @@ export function useDomSelection({
231
250
  projectId,
232
251
  });
233
252
  },
234
- [activeCompPath, isMasterView, projectId],
253
+ [activeCompPath, isMasterView, previewIframeRef, projectId],
235
254
  );
236
255
 
237
256
  const resolveDomSelectionFromPreviewPoint = useCallback(
@@ -252,7 +271,7 @@ export function useDomSelection({
252
271
  } catch {
253
272
  /* cross-origin guard */
254
273
  }
255
- const target = getPreviewTargetFromPointer(iframe, clientX, clientY, activeCompPath);
274
+ const target = await findPointerTarget(iframe, clientX, clientY);
256
275
  if (!target) return null;
257
276
  return buildDomSelectionFromTarget(
258
277
  target,
@@ -268,7 +287,7 @@ export function useDomSelection({
268
287
  },
269
288
  );
270
289
  },
271
- [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
290
+ [buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
272
291
  );
273
292
 
274
293
  const resolveAllDomSelectionsFromPreviewPoint = useCallback(
@@ -281,7 +300,7 @@ export function useDomSelection({
281
300
  } catch {
282
301
  /* cross-origin guard */
283
302
  }
284
- const targets = getAllPreviewTargetsFromPointer(iframe, clientX, clientY, activeCompPath);
303
+ const targets = await findPointerTargets(iframe, clientX, clientY);
285
304
  const results: DomEditSelection[] = [];
286
305
  for (const target of targets) {
287
306
  const sel = await buildDomSelectionFromTarget(target, { skipSourceProbe: true });
@@ -289,11 +308,13 @@ export function useDomSelection({
289
308
  }
290
309
  return results;
291
310
  },
292
- [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
311
+ [buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
293
312
  );
294
313
 
295
314
  const updateDomEditHoverSelection = useCallback((selection: DomEditSelection | null) => {
296
- if (domEditSelectionsTargetSame(domEditHoverSelectionRef.current, selection)) return;
315
+ const current = domEditHoverSelectionRef.current;
316
+ const sameHandle = current?.handle === selection?.handle;
317
+ if (domEditSelectionsTargetSame(current, selection) && sameHandle) return;
297
318
  domEditHoverSelectionRef.current = selection;
298
319
  setDomEditHoverSelection(selection);
299
320
  }, []);
@@ -302,23 +323,25 @@ export function useDomSelection({
302
323
  // fallow-ignore-next-line complexity
303
324
  async (element: TimelineElement): Promise<DomEditSelection | null> => {
304
325
  const iframe = previewIframeRef.current;
326
+ const lookup = { activeCompositionPath: activeCompPath, compIdToSrc, isMasterView };
305
327
  let doc: Document | null = null;
306
328
  try {
307
329
  doc = iframe?.contentDocument ?? null;
308
330
  } catch {
309
331
  return null;
310
332
  }
311
- if (!doc) return null;
333
+ if (!doc) {
334
+ const found = await findOpaqueTimelineElement(iframe, element, lookup);
335
+ return found
336
+ ? buildDomSelectionFromTarget(found, { preferClipAncestor: false }, iframe)
337
+ : null;
338
+ }
312
339
 
313
340
  const held = holdScenesOf(iframe, element);
314
341
  if (held) await held;
315
342
  reapplyPositionEditsAfterSeek(doc);
316
343
 
317
- const targetElement = findElementForTimelineElement(doc, element, {
318
- activeCompositionPath: activeCompPath,
319
- compIdToSrc,
320
- isMasterView,
321
- });
344
+ const targetElement = findElementForTimelineElement(doc, element, lookup);
322
345
  return targetElement
323
346
  ? buildDomSelectionFromTarget(targetElement, {
324
347
  preferClipAncestor: false,
@@ -356,7 +379,7 @@ export function useDomSelection({
356
379
  // refresher falls back to it when the primary is gone, and a ref keeps that from
357
380
  // forcing either callback to be declared in the other's dependency list.
358
381
  const refreshDomEditGroupSelectionsFromPreviewRef = useRef<
359
- (selections: DomEditSelection[]) => Promise<void>
382
+ (selections: DomEditSelection[], iframe: HTMLIFrameElement | null) => Promise<void>
360
383
  >(async () => {});
361
384
 
362
385
  const refreshDomEditSelectionFromPreview = useCallback(
@@ -365,15 +388,8 @@ export function useDomSelection({
365
388
  const stillSelected = () =>
366
389
  domEditSelectionsTargetSame(domEditSelectionRef.current, selection);
367
390
  if (!stillSelected()) return;
368
- let doc: Document | null = null;
369
- try {
370
- doc = iframe?.contentDocument ?? null;
371
- } catch {
372
- return;
373
- }
374
- if (!doc) return;
375
-
376
- const element = findElementForSelection(doc, selection, activeCompPath);
391
+ const element = await findSelectionElement(iframe, selection, activeCompPath);
392
+ if (element === undefined || !stillSelected()) return;
377
393
  if (!element) {
378
394
  // Losing the primary is not losing the selection. When a group is live,
379
395
  // re-resolve it and keep whoever still exists rather than wiping the lot.
@@ -383,14 +399,18 @@ export function useDomSelection({
383
399
  group: group.length,
384
400
  });
385
401
  if (group.length > 1) {
386
- await refreshDomEditGroupSelectionsFromPreviewRef.current(group);
402
+ await refreshDomEditGroupSelectionsFromPreviewRef.current(group, iframe);
387
403
  return;
388
404
  }
389
405
  applyDomSelection(null, { revealPanel: false });
390
406
  return;
391
407
  }
392
408
 
393
- const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection });
409
+ const nextSelection = await buildDomSelectionFromTarget(
410
+ element,
411
+ { previous: selection },
412
+ iframe,
413
+ );
394
414
  if (nextSelection && stillSelected()) {
395
415
  applyDomSelection(nextSelection, {
396
416
  revealPanel: false,
@@ -403,24 +423,20 @@ export function useDomSelection({
403
423
 
404
424
  const refreshDomEditGroupSelectionsFromPreview = useCallback(
405
425
  // fallow-ignore-next-line complexity
406
- async (selections: DomEditSelection[]) => {
407
- const iframe = previewIframeRef.current;
408
- let doc: Document | null = null;
409
- try {
410
- doc = iframe?.contentDocument ?? null;
411
- } catch {
412
- return;
413
- }
414
- if (!doc) return;
415
-
426
+ async (selections: DomEditSelection[], iframe = previewIframeRef.current) => {
416
427
  const nextGroup: DomEditSelection[] = [];
417
428
  for (const selection of selections) {
418
- const element = findElementForSelection(doc, selection, activeCompPath);
429
+ const element = await findSelectionElement(iframe, selection, activeCompPath);
430
+ if (element === undefined) return;
419
431
  if (!element) continue;
420
- const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection });
432
+ const nextSelection = await buildDomSelectionFromTarget(
433
+ element,
434
+ { previous: selection },
435
+ iframe,
436
+ );
421
437
  if (nextSelection) nextGroup.push(nextSelection);
422
438
  }
423
- if (nextGroup.length === 0) return;
439
+ if (!groupStillLive(domEditGroupSelectionsRef, selections, nextGroup)) return;
424
440
 
425
441
  const currentSelection = domEditSelectionRef.current;
426
442
  const nextSelection =
@@ -469,7 +485,7 @@ export function useDomSelection({
469
485
  captionEditMode ||
470
486
  domEditSelectionsTargetSame(domEditHoverSelection, domEditSelection) ||
471
487
  domEditSelectionInGroup(domEditGroupSelections, domEditHoverSelection) ||
472
- !domEditHoverSelection.element.isConnected;
488
+ !selectionElementLive(domEditHoverSelection);
473
489
  if (shouldClear) updateDomEditHoverSelection(null);
474
490
  }, [
475
491
  captionEditMode,
@@ -9,7 +9,7 @@ vi.mock("../utils/studioSaveDiagnostics", async (importOriginal) => ({
9
9
  trackStudioSaveFailure,
10
10
  }));
11
11
 
12
- import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
12
+ import { StudioFileConflictError, createStudioSaveHttpError } from "../utils/studioSaveDiagnostics";
13
13
  import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
14
14
 
15
15
  (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
@@ -150,6 +150,27 @@ describe("useEditorSave pending work", () => {
150
150
  await mounted.unmount();
151
151
  });
152
152
 
153
+ // fails without the fix: the toast told the person to check the preview server for a file another program holds open.
154
+ it("toasts a held file in its own words, not the generic preview-server advice", async () => {
155
+ const held = await createStudioSaveHttpError(
156
+ new Response(JSON.stringify({ why: "busy" }), { status: 423 }),
157
+ "Failed to save index.html",
158
+ { path: "index.html" },
159
+ );
160
+ const mounted = await mountEditorSave(async () => {
161
+ throw held;
162
+ });
163
+
164
+ act(() => mounted.handle.handleContentChange("edit"));
165
+ await mounted.handle.flushPendingSave();
166
+
167
+ expect(mounted.showToast).toHaveBeenCalledWith(
168
+ "index.html is open in another program. Close it there, then try again.",
169
+ "error",
170
+ );
171
+ await mounted.unmount();
172
+ });
173
+
153
174
  it("emits a changed failure immediately and repeats after the burst window", async () => {
154
175
  const now = vi.spyOn(Date, "now").mockReturnValue(1_000);
155
176
  const writeProjectFile = vi
@@ -3,6 +3,7 @@ import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
3
3
  import {
4
4
  StudioFileConflictError,
5
5
  buildStudioSaveFailureProperties,
6
+ heldFileWords,
6
7
  trackStudioSaveFailure,
7
8
  type StudioSaveDrainResult,
8
9
  } from "../utils/studioSaveDiagnostics";
@@ -93,7 +94,8 @@ export function useEditorSave({
93
94
  ) {
94
95
  lastFailureToastAtRef.current = now;
95
96
  showToast(
96
- `Couldn't save ${path}. Your latest edits are NOT persisted. Check the preview server; editing again retries the save.`,
97
+ heldFileWords(error) ??
98
+ `Couldn't save ${path}. Your latest edits are NOT persisted. Check the preview server; editing again retries the save.`,
97
99
  "error",
98
100
  );
99
101
  }
@@ -182,3 +182,20 @@ describe("useGsapSelectionHandlers retime settlement", () => {
182
182
  withSelection.unmount();
183
183
  });
184
184
  });
185
+
186
+ describe("useGsapSelectionHandlers on an opaque frame's selection", () => {
187
+ it("reads a moved element's offset mark off the description, not the tag-only stand-in", async () => {
188
+ const selection = {
189
+ ...makeSelection(),
190
+ handle: "0123456789abcdef:1",
191
+ dataAttributes: { "hf-studio-path-offset": "" },
192
+ } as DomEditSelection;
193
+ const handleDomManualEditsReset = vi.fn().mockResolvedValue(undefined);
194
+ const rendered = renderHandlers(
195
+ makeParams({ domEditSelection: selection, handleDomManualEditsReset }),
196
+ );
197
+ await act(() => rendered.handlers().handleGsapAddAnimation("to"));
198
+ expect(handleDomManualEditsReset).toHaveBeenCalledWith(selection);
199
+ rendered.unmount();
200
+ });
201
+ });
@@ -9,6 +9,7 @@ import {
9
9
  trackStudioSaveFailure,
10
10
  } from "../utils/studioSaveDiagnostics";
11
11
  import { trackStudioEvent } from "../utils/studioTelemetry";
12
+ import { selectionDataAttribute } from "../components/editor/previewSelection";
12
13
  import type { CommitMutationOptions } from "./gsapScriptCommitTypes";
13
14
 
14
15
  /**
@@ -243,7 +244,7 @@ export function useGsapSelectionHandlers({
243
244
  "add",
244
245
  `Add GSAP ${method} animation`,
245
246
  );
246
- if (selection.element.hasAttribute("data-hf-studio-path-offset")) {
247
+ if (selectionDataAttribute(selection, "data-hf-studio-path-offset") !== null) {
247
248
  // The reset owns rollback and the position commit already owns user and
248
249
  // telemetry reporting. This is only the fire-and-forget UI boundary.
249
250
  void landed.then((didLand) => {
@@ -165,13 +165,21 @@ describe("usePreviewInteraction", () => {
165
165
  cleanup();
166
166
  });
167
167
 
168
- it("preserves group drill-in on double-click", async () => {
168
+ it.each([
169
+ ["a wrapper Studio can script", false],
170
+ ["an opaque frame's tag-only stand-in", true],
171
+ ])("preserves group drill-in on double-click on %s", async (_, opaque) => {
169
172
  const group = document.createElement("div");
170
- group.setAttribute("data-hf-group", "hero");
173
+ if (!opaque) group.setAttribute("data-hf-group", "hero");
171
174
  const child = document.createElement("span");
172
175
  child.id = "headline";
173
176
  group.append(child);
174
177
  const groupSelection = makeSelection("Hero Group", group);
178
+ if (opaque)
179
+ Object.assign(groupSelection, {
180
+ handle: "0123456789abcdef:1",
181
+ dataAttributes: { "hf-group": "hero" },
182
+ });
175
183
  const childSelection = makeSelection("Headline", child);
176
184
  const applyDomSelection = vi.fn();
177
185
  const setActiveGroupElement = vi.fn();