@hyperframes/studio 0.9.40 → 0.9.41

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 (56) hide show
  1. package/dist/assets/{codec-BPK_2CLL.js → codec-B_mpbc4w.js} +1 -1
  2. package/dist/assets/{hyperframes-player-D7qTTDIp.js → hyperframes-player-Dvi3I_mv.js} +1 -1
  3. package/dist/assets/{index-CdA00Ybn.js → index-B5ExwsOp.js} +146 -146
  4. package/dist/assets/{index-QS-DuxAU.js → index-BrFm9Y5k.js} +1 -1
  5. package/dist/assets/{pausedVideoDecoder-Byzz98Gb.js → pausedVideoDecoder-MHQ57yZ6.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 +4 -0
  11. package/dist/index.html +1 -1
  12. package/dist/index.js +898 -551
  13. package/dist/player.js +2 -2
  14. package/package.json +8 -8
  15. package/src/components/editor/DomEditOverlay.tsx +3 -15
  16. package/src/components/editor/clickAfterPreventedPress.test.tsx +17 -1
  17. package/src/components/editor/domEditOverlayBasis.ts +7 -2
  18. package/src/components/editor/domEditOverlayCrop.test.ts +1 -1
  19. package/src/components/editor/domEditOverlayCrop.ts +17 -3
  20. package/src/components/editor/domEditOverlayGeometry.ts +64 -139
  21. package/src/components/editor/domEditSelectionRules.ts +138 -0
  22. package/src/components/editor/domEditing.test.ts +6 -28
  23. package/src/components/editor/domEditingDom.preview.test.ts +3 -3
  24. package/src/components/editor/domEditingDom.ts +3 -76
  25. package/src/components/editor/domEditingElement.ts +19 -240
  26. package/src/components/editor/domEditingGroups.ts +0 -31
  27. package/src/components/editor/domEditingLayers.ts +95 -100
  28. package/src/components/editor/domEditingRootLayer.ts +35 -30
  29. package/src/components/editor/domEditingTypes.ts +4 -0
  30. package/src/components/editor/previewGestureStarts.ts +73 -10
  31. package/src/components/editor/previewOverlayRects.test.ts +316 -0
  32. package/src/components/editor/previewOverlayRects.ts +123 -0
  33. package/src/components/editor/previewPointerTargets.test.ts +260 -0
  34. package/src/components/editor/previewSelection.test.ts +481 -0
  35. package/src/components/editor/previewSelection.ts +472 -0
  36. package/src/components/editor/probeSourceElement.ts +19 -1
  37. package/src/components/editor/propertyPanelFill.tsx +5 -1
  38. package/src/components/editor/useDomEditOverlayRects.ts +80 -1
  39. package/src/components/editor/useInlineTextEditing.tsx +1 -6
  40. package/src/hooks/domSelectionTestHarness.ts +1 -1
  41. package/src/hooks/useDomEditSession.test.tsx +23 -1
  42. package/src/hooks/useDomEditSession.ts +2 -1
  43. package/src/hooks/useDomSelection.ts +61 -47
  44. package/src/hooks/useGsapSelectionHandlers.test.tsx +17 -0
  45. package/src/hooks/useGsapSelectionHandlers.ts +2 -1
  46. package/src/hooks/usePreviewInteraction.test.ts +10 -2
  47. package/src/hooks/usePreviewInteraction.ts +5 -4
  48. package/src/hooks/useStudioSelectionPublisher.test.tsx +50 -0
  49. package/src/hooks/useStudioSelectionPublisher.ts +9 -7
  50. package/src/player/lib/previewChannel.ts +4 -3
  51. package/src/player/lib/previewElements.ts +112 -3
  52. package/src/styles/hex-baseline.json +1 -2
  53. package/src/utils/studioHelpers.ts +0 -13
  54. package/src/utils/studioPreviewHelpers.test.ts +8 -8
  55. package/src/utils/studioPreviewHelpers.ts +26 -242
  56. package/src/components/editor/domEditOverlayTransform.ts +0 -126
@@ -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({
@@ -176,7 +189,7 @@ export function useDomSelection({
176
189
  // Selecting something outside the drilled-into group exits the drill-in, so
177
190
  // a later click on the group selects it as a unit again (non-sticky drill-in).
178
191
  const activeGroup = activeGroupElementRef.current;
179
- if (activeGroup && nextSelection && !activeGroup.contains(nextSelection.element)) {
192
+ if (activeGroup && nextSelection && !elementWithin(activeGroup, nextSelection.element)) {
180
193
  activeGroupElementRef.current = null;
181
194
  setActiveGroupElementState(null);
182
195
  }
@@ -216,8 +229,12 @@ export function useDomSelection({
216
229
  );
217
230
 
218
231
  const buildDomSelectionFromTarget = useCallback(
219
- (target: HTMLElement, options?: ResolveDomSelectionOptions) => {
220
- return resolveDomEditSelection(target, {
232
+ (
233
+ target: HTMLElement | PreviewElement,
234
+ options?: ResolveDomSelectionOptions,
235
+ iframe = previewIframeRef.current,
236
+ ) => {
237
+ return resolveFoundSelection(iframe, target, {
221
238
  activeCompositionPath: activeCompPath,
222
239
  isMasterView,
223
240
  preferClipAncestor: options?.preferClipAncestor,
@@ -231,7 +248,7 @@ export function useDomSelection({
231
248
  projectId,
232
249
  });
233
250
  },
234
- [activeCompPath, isMasterView, projectId],
251
+ [activeCompPath, isMasterView, previewIframeRef, projectId],
235
252
  );
236
253
 
237
254
  const resolveDomSelectionFromPreviewPoint = useCallback(
@@ -252,7 +269,7 @@ export function useDomSelection({
252
269
  } catch {
253
270
  /* cross-origin guard */
254
271
  }
255
- const target = getPreviewTargetFromPointer(iframe, clientX, clientY, activeCompPath);
272
+ const target = await findPointerTarget(iframe, clientX, clientY);
256
273
  if (!target) return null;
257
274
  return buildDomSelectionFromTarget(
258
275
  target,
@@ -268,7 +285,7 @@ export function useDomSelection({
268
285
  },
269
286
  );
270
287
  },
271
- [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
288
+ [buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
272
289
  );
273
290
 
274
291
  const resolveAllDomSelectionsFromPreviewPoint = useCallback(
@@ -281,7 +298,7 @@ export function useDomSelection({
281
298
  } catch {
282
299
  /* cross-origin guard */
283
300
  }
284
- const targets = getAllPreviewTargetsFromPointer(iframe, clientX, clientY, activeCompPath);
301
+ const targets = await findPointerTargets(iframe, clientX, clientY);
285
302
  const results: DomEditSelection[] = [];
286
303
  for (const target of targets) {
287
304
  const sel = await buildDomSelectionFromTarget(target, { skipSourceProbe: true });
@@ -289,11 +306,13 @@ export function useDomSelection({
289
306
  }
290
307
  return results;
291
308
  },
292
- [activeCompPath, buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
309
+ [buildDomSelectionFromTarget, captionEditMode, previewIframeRef],
293
310
  );
294
311
 
295
312
  const updateDomEditHoverSelection = useCallback((selection: DomEditSelection | null) => {
296
- if (domEditSelectionsTargetSame(domEditHoverSelectionRef.current, selection)) return;
313
+ const current = domEditHoverSelectionRef.current;
314
+ const sameHandle = current?.handle === selection?.handle;
315
+ if (domEditSelectionsTargetSame(current, selection) && sameHandle) return;
297
316
  domEditHoverSelectionRef.current = selection;
298
317
  setDomEditHoverSelection(selection);
299
318
  }, []);
@@ -302,23 +321,25 @@ export function useDomSelection({
302
321
  // fallow-ignore-next-line complexity
303
322
  async (element: TimelineElement): Promise<DomEditSelection | null> => {
304
323
  const iframe = previewIframeRef.current;
324
+ const lookup = { activeCompositionPath: activeCompPath, compIdToSrc, isMasterView };
305
325
  let doc: Document | null = null;
306
326
  try {
307
327
  doc = iframe?.contentDocument ?? null;
308
328
  } catch {
309
329
  return null;
310
330
  }
311
- if (!doc) return null;
331
+ if (!doc) {
332
+ const found = await findOpaqueTimelineElement(iframe, element, lookup);
333
+ return found
334
+ ? buildDomSelectionFromTarget(found, { preferClipAncestor: false }, iframe)
335
+ : null;
336
+ }
312
337
 
313
338
  const held = holdScenesOf(iframe, element);
314
339
  if (held) await held;
315
340
  reapplyPositionEditsAfterSeek(doc);
316
341
 
317
- const targetElement = findElementForTimelineElement(doc, element, {
318
- activeCompositionPath: activeCompPath,
319
- compIdToSrc,
320
- isMasterView,
321
- });
342
+ const targetElement = findElementForTimelineElement(doc, element, lookup);
322
343
  return targetElement
323
344
  ? buildDomSelectionFromTarget(targetElement, {
324
345
  preferClipAncestor: false,
@@ -356,7 +377,7 @@ export function useDomSelection({
356
377
  // refresher falls back to it when the primary is gone, and a ref keeps that from
357
378
  // forcing either callback to be declared in the other's dependency list.
358
379
  const refreshDomEditGroupSelectionsFromPreviewRef = useRef<
359
- (selections: DomEditSelection[]) => Promise<void>
380
+ (selections: DomEditSelection[], iframe: HTMLIFrameElement | null) => Promise<void>
360
381
  >(async () => {});
361
382
 
362
383
  const refreshDomEditSelectionFromPreview = useCallback(
@@ -365,15 +386,8 @@ export function useDomSelection({
365
386
  const stillSelected = () =>
366
387
  domEditSelectionsTargetSame(domEditSelectionRef.current, selection);
367
388
  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);
389
+ const element = await findSelectionElement(iframe, selection, activeCompPath);
390
+ if (element === undefined || !stillSelected()) return;
377
391
  if (!element) {
378
392
  // Losing the primary is not losing the selection. When a group is live,
379
393
  // re-resolve it and keep whoever still exists rather than wiping the lot.
@@ -383,14 +397,18 @@ export function useDomSelection({
383
397
  group: group.length,
384
398
  });
385
399
  if (group.length > 1) {
386
- await refreshDomEditGroupSelectionsFromPreviewRef.current(group);
400
+ await refreshDomEditGroupSelectionsFromPreviewRef.current(group, iframe);
387
401
  return;
388
402
  }
389
403
  applyDomSelection(null, { revealPanel: false });
390
404
  return;
391
405
  }
392
406
 
393
- const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection });
407
+ const nextSelection = await buildDomSelectionFromTarget(
408
+ element,
409
+ { previous: selection },
410
+ iframe,
411
+ );
394
412
  if (nextSelection && stillSelected()) {
395
413
  applyDomSelection(nextSelection, {
396
414
  revealPanel: false,
@@ -403,24 +421,20 @@ export function useDomSelection({
403
421
 
404
422
  const refreshDomEditGroupSelectionsFromPreview = useCallback(
405
423
  // 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
-
424
+ async (selections: DomEditSelection[], iframe = previewIframeRef.current) => {
416
425
  const nextGroup: DomEditSelection[] = [];
417
426
  for (const selection of selections) {
418
- const element = findElementForSelection(doc, selection, activeCompPath);
427
+ const element = await findSelectionElement(iframe, selection, activeCompPath);
428
+ if (element === undefined) return;
419
429
  if (!element) continue;
420
- const nextSelection = await buildDomSelectionFromTarget(element, { previous: selection });
430
+ const nextSelection = await buildDomSelectionFromTarget(
431
+ element,
432
+ { previous: selection },
433
+ iframe,
434
+ );
421
435
  if (nextSelection) nextGroup.push(nextSelection);
422
436
  }
423
- if (nextGroup.length === 0) return;
437
+ if (!groupStillLive(domEditGroupSelectionsRef, selections, nextGroup)) return;
424
438
 
425
439
  const currentSelection = domEditSelectionRef.current;
426
440
  const nextSelection =
@@ -469,7 +483,7 @@ export function useDomSelection({
469
483
  captionEditMode ||
470
484
  domEditSelectionsTargetSame(domEditHoverSelection, domEditSelection) ||
471
485
  domEditSelectionInGroup(domEditGroupSelections, domEditHoverSelection) ||
472
- !domEditHoverSelection.element.isConnected;
486
+ !selectionElementLive(domEditHoverSelection);
473
487
  if (shouldClear) updateDomEditHoverSelection(null);
474
488
  }, [
475
489
  captionEditMode,
@@ -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();
@@ -3,6 +3,7 @@ import { useCallback, useRef } from "react";
3
3
  import { liveTime, usePlayerStore } from "../player";
4
4
  import { pauseStudioPreviewPlayback } from "../utils/studioPreviewHelpers";
5
5
  import { type DomEditSelection } from "../components/editor/domEditing";
6
+ import { selectionDataAttribute } from "../components/editor/previewSelection";
6
7
  import type { ApplyDomSelectionOptions, ResolveDomSelectionOptions } from "./useDomSelection";
7
8
  import { trackStudioEvent } from "../utils/studioTelemetry";
8
9
 
@@ -119,7 +120,7 @@ export function usePreviewInteraction({
119
120
  cycle.candidates.length > 1 &&
120
121
  Math.hypot(e.clientX - cycle.x, e.clientY - cycle.y) < CYCLE_RADIUS_PX &&
121
122
  downTs - cycle.at < CYCLE_WINDOW_MS;
122
- if (hit?.element.hasAttribute("data-hf-group")) {
123
+ if (hit && selectionDataAttribute(hit, "data-hf-group") !== null) {
123
124
  e.preventDefault();
124
125
  e.stopPropagation();
125
126
  cycleRef.current = null;
@@ -134,8 +135,8 @@ export function usePreviewInteraction({
134
135
  if (
135
136
  hit &&
136
137
  !hasStackCycleAtSpot &&
137
- !hit.element.hasAttribute("data-composition-src") &&
138
- !hit.element.hasAttribute("data-composition-file")
138
+ selectionDataAttribute(hit, "data-composition-src") === null &&
139
+ selectionDataAttribute(hit, "data-composition-file") === null
139
140
  ) {
140
141
  e.preventDefault();
141
142
  e.stopPropagation();
@@ -190,7 +191,7 @@ export function usePreviewInteraction({
190
191
  preferClipAncestor: options?.preferClipAncestor ?? false,
191
192
  });
192
193
  // A null result while drilled into a group means the click landed OUTSIDE that
193
- // group (resolveGroupCapture → out-of-scope). Drill-in isn't sticky: exit it and
194
+ // group (selectionTargetIndex: out of scope). Drill-in isn't sticky: exit it and
194
195
  // re-resolve at the top level so this click selects whatever's there (or the
195
196
  // group as a unit). Without this, a stale drill-in keeps selecting children and
196
197
  // the "first click selects the group" expectation breaks.
@@ -0,0 +1,50 @@
1
+ // @vitest-environment happy-dom
2
+ import { act } from "react";
3
+ import { createRoot } from "react-dom/client";
4
+ import { afterEach, expect, it, vi } from "vitest";
5
+ import type { DomEditSelection } from "../components/editor/domEditingTypes";
6
+ import { makeSelection } from "./domSelectionTestHarness";
7
+ import { useStudioSelectionPublisher } from "./useStudioSelectionPublisher";
8
+
9
+ (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
10
+
11
+ const fetches = vi.hoisted(() => ({ bodies: [] as unknown[] }));
12
+ vi.mock("../utils/studioApiFetch", () => ({
13
+ studioApiFetch: (_url: string, init: { body: string }) => {
14
+ fetches.bodies.push(JSON.parse(init.body).selection);
15
+ return Promise.resolve(new Response(null));
16
+ },
17
+ }));
18
+
19
+ afterEach(() => {
20
+ fetches.bodies.length = 0;
21
+ });
22
+
23
+ function publish(selection: DomEditSelection) {
24
+ function Probe() {
25
+ useStudioSelectionPublisher({
26
+ projectId: "p",
27
+ domEditSelection: selection,
28
+ domEditSelectionRef: { current: selection },
29
+ refreshKey: 0,
30
+ previewDocumentVersion: 0,
31
+ refreshDomEditSelectionFromPreview: () => Promise.resolve(),
32
+ });
33
+ return null;
34
+ }
35
+ const root = createRoot(document.createElement("div"));
36
+ act(() => root.render(<Probe />));
37
+ act(() => root.unmount());
38
+ return fetches.bodies[0];
39
+ }
40
+
41
+ it("tells agents about an opaque frame's selection, whose stand-in is never connected", () => {
42
+ const selection = makeSelection("Title", document.createElement("h1"));
43
+ expect(publish({ ...selection, handle: "0123456789abcdef:1" })).toMatchObject({
44
+ schemaVersion: 1,
45
+ });
46
+ });
47
+
48
+ it("still withholds a scriptable frame's selection once its element is gone", () => {
49
+ expect(publish(makeSelection("Title", document.createElement("h1")))).toBeNull();
50
+ });
@@ -2,6 +2,7 @@ import { useEffect, useRef, type MutableRefObject } from "react";
2
2
  import type { DomEditSelection } from "../components/editor/domEditing";
3
3
  import { usePlayerStore } from "../player";
4
4
  import { buildStudioSelectionSnapshot } from "../utils/studioSelectionSnapshot";
5
+ import { selectionElementLive } from "../components/editor/previewSelection";
5
6
  import { trackStudioEvent } from "../utils/studioTelemetry";
6
7
  import { studioApiFetch } from "../utils/studioApiFetch";
7
8
 
@@ -49,13 +50,14 @@ export function useStudioSelectionPublisher({
49
50
  // eslint-disable-next-line no-restricted-syntax
50
51
  useEffect(() => {
51
52
  if (!projectId) return;
52
- const selection = domEditSelection?.element.isConnected
53
- ? buildStudioSelectionSnapshot({
54
- projectId,
55
- selection: domEditSelection,
56
- currentTime: usePlayerStore.getState().currentTime,
57
- })
58
- : null;
53
+ const selection =
54
+ domEditSelection && selectionElementLive(domEditSelection)
55
+ ? buildStudioSelectionSnapshot({
56
+ projectId,
57
+ selection: domEditSelection,
58
+ currentTime: usePlayerStore.getState().currentTime,
59
+ })
60
+ : null;
59
61
  const controller = new AbortController();
60
62
  void putSelection(projectId, selection, controller.signal).catch(reportSelectionPublishError);
61
63
  return () => controller.abort();
@@ -97,13 +97,14 @@ export async function previewClipManifest(iframe: HTMLIFrameElement): Promise<Cl
97
97
  return manifest as ClipManifest;
98
98
  }
99
99
 
100
- /** The runtime's computed `properties` for the element `selector` names; null when it has none. */
100
+ /** The runtime's computed `properties` for the element `target` names; null when it has none. */
101
101
  export async function previewComputedStyles(
102
102
  iframe: HTMLIFrameElement,
103
- selector: string,
103
+ target: string | { handle: string },
104
104
  properties: string[],
105
105
  ): Promise<Record<string, string> | null> {
106
- const reply = await previewRequest(iframe, "computed-styles", { selector, properties });
106
+ const element = typeof target === "string" ? { selector: target } : { handle: target.handle };
107
+ const reply = await previewRequest(iframe, "computed-styles", { ...element, properties });
107
108
  const styles: unknown = reply?.styles;
108
109
  if (typeof styles !== "object" || styles === null) return null;
109
110
  const read: Record<string, string> = {};
@@ -5,8 +5,14 @@
5
5
  import {
6
6
  EDITING_ELEMENT_HANDLE,
7
7
  MAX_DESCRIBE_HANDLES,
8
+ MAX_ELEMENT_ENTRIES,
9
+ MAX_ELEMENT_VALUE,
10
+ MAX_GEOMETRY_CHILDREN,
11
+ type EditingElementBox,
8
12
  type EditingElementDescription,
13
+ type EditingElementGeometry,
9
14
  type EditingElementHit,
15
+ type EditingElementMatch,
10
16
  type EditingElementSource,
11
17
  } from "@hyperframes/core/runtime/editing-port";
12
18
  import { resolveElementSourceFile } from "../../components/editor/domEditingDom";
@@ -49,11 +55,12 @@ function hasPlainFields(value: Fields): boolean {
49
55
  return groupsOk && attributesOk && childrenOk && typeof value.truncated === "boolean";
50
56
  }
51
57
 
58
+ const isRect = (value: unknown) =>
59
+ isFields(value) && [value.x, value.y, value.width, value.height].every(Number.isFinite);
60
+
52
61
  function readHit(value: unknown): PreviewElementHit | null {
53
62
  if (!isFields(value) || !isHandle(value.handle) || !isText(value.tag)) return null;
54
- const { rect } = value;
55
- const rectOk = isFields(rect) && [rect.x, rect.y, rect.width, rect.height].every(Number.isFinite);
56
- return rectOk ? (value as unknown as PreviewElementHit) : null;
63
+ return isRect(value.rect) ? (value as unknown as PreviewElementHit) : null;
57
64
  }
58
65
 
59
66
  /** Frame data checked against `EditingElementDescription`; null when any field is off. */
@@ -78,6 +85,18 @@ export async function previewElementsAtPoint(
78
85
  return elements.map(readHit).filter((element) => element !== null);
79
86
  }
80
87
 
88
+ export async function previewPointerTargets(
89
+ iframe: HTMLIFrameElement,
90
+ rootFractionX: number,
91
+ rootFractionY: number,
92
+ ): Promise<{ target: PreviewElementHit | null; stack: PreviewElementHit[] } | null> {
93
+ const params = { x: rootFractionX, y: rootFractionY };
94
+ const reply = await previewRequest(iframe, "pointer-targets", params);
95
+ const stack: unknown = reply?.stack;
96
+ if (!reply || !Array.isArray(stack)) return null;
97
+ return { target: readHit(reply.target), stack: stack.map(readHit).filter((hit) => hit !== null) };
98
+ }
99
+
81
100
  /**
82
101
  * One entry per handle, in order: null for an element the frame no longer has. The whole answer is
83
102
  * null when the runtime cannot answer, or when there are no handles or more than the runtime takes.
@@ -96,6 +115,32 @@ export async function describePreviewElements(
96
115
  });
97
116
  }
98
117
 
118
+ /** Each handle's ancestors, parent first; null for an element the frame no longer has. */
119
+ export async function previewAncestors(
120
+ iframe: HTMLIFrameElement,
121
+ handles: readonly string[],
122
+ ): Promise<Array<string[] | null> | null> {
123
+ if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
124
+ const reply = await previewRequest(iframe, "ancestors", { handles: [...handles] });
125
+ const chains: unknown = reply?.ancestors;
126
+ if (!Array.isArray(chains) || chains.length !== handles.length) return null;
127
+ return chains.map((chain) =>
128
+ Array.isArray(chain) && chain.every(isHandle) ? (chain as string[]) : null,
129
+ );
130
+ }
131
+
132
+ /** The frame's matches for `selector` in document order; null when the runtime cannot answer. */
133
+ export async function queryPreviewElements(
134
+ iframe: HTMLIFrameElement,
135
+ selector: string,
136
+ ): Promise<{ matches: EditingElementMatch[]; truncated: boolean } | null> {
137
+ const reply = await previewRequest(iframe, "query", { selector });
138
+ const matches: unknown = reply?.matches;
139
+ if (!Array.isArray(matches) || typeof reply?.truncated !== "boolean") return null;
140
+ const ok = matches.every((m) => isFields(m) && isHandle(m.handle) && isSource(m.source));
141
+ return ok ? { matches: matches as EditingElementMatch[], truncated: reply.truncated } : null;
142
+ }
143
+
99
144
  /** `getSourceFileForElement` for the frame's own element. */
100
145
  export function previewElementSourceFile(
101
146
  element: PreviewElement,
@@ -115,3 +160,67 @@ export function previewElementSelectorIndex(
115
160
  .filter((group) => resolveElementSourceFile(group.source, activeCompositionPath) === file)
116
161
  .reduce((sum, group) => sum + group.count, 0);
117
162
  }
163
+
164
+ const isPoint = (value: unknown) =>
165
+ isFields(value) && Number.isFinite(value.x) && Number.isFinite(value.y);
166
+ const isSizeOrNull = (value: unknown) =>
167
+ value === null || (Number.isFinite(value) && (value as number) > 0);
168
+
169
+ const CORNERS = ["nw", "ne", "se", "sw"] as const;
170
+ const isCorners = (value: unknown) =>
171
+ value === null || (isFields(value) && CORNERS.every((corner) => isPoint(value[corner])));
172
+
173
+ const isSourceBox = (value: unknown) =>
174
+ value === null ||
175
+ (isFields(value) &&
176
+ Number.isFinite(value.width) &&
177
+ Number.isFinite(value.height) &&
178
+ isSizeOrNull(value.declaredWidth) &&
179
+ isSizeOrNull(value.declaredHeight));
180
+
181
+ const isClipPath = (value: unknown) =>
182
+ value === null || (isText(value) && (value as string).length <= MAX_ELEMENT_VALUE);
183
+
184
+ const isBox = (value: unknown): value is EditingElementBox =>
185
+ isFields(value) &&
186
+ isRect(value.rect) &&
187
+ Number.isFinite(value.angle) &&
188
+ isCorners(value.corners) &&
189
+ isSourceBox(value.source) &&
190
+ isClipPath(value.clipPath);
191
+
192
+ const readGeometry = (value: unknown): EditingElementGeometry | null => {
193
+ if (!isBox(value) || !isFields(value) || typeof value.visible !== "boolean") return null;
194
+ const { members } = value;
195
+ const membersOk =
196
+ members === null ||
197
+ (Array.isArray(members) && members.length <= MAX_ELEMENT_ENTRIES && members.every(isRect));
198
+ return membersOk ? (value as unknown as EditingElementGeometry) : null;
199
+ };
200
+
201
+ export interface PreviewGeometry {
202
+ /** One entry per handle, in order: null for an element the frame no longer has. */
203
+ elements: Array<EditingElementGeometry | null>;
204
+ /** The `children` element's descendants, when it has 1 to MAX_GEOMETRY_CHILDREN; else empty. */
205
+ children: EditingElementBox[] | null;
206
+ }
207
+
208
+ /** Overlay geometry for `handles`, and `children`'s descendant boxes; null when the runtime cannot answer. */
209
+ export async function previewGeometry(
210
+ iframe: HTMLIFrameElement,
211
+ handles: readonly string[],
212
+ children?: string,
213
+ ): Promise<PreviewGeometry | null> {
214
+ if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
215
+ const params = { handles: [...handles], ...(children ? { children } : {}) };
216
+ const reply = await previewRequest(iframe, "geometry", params);
217
+ const elements: unknown = reply?.elements;
218
+ if (!Array.isArray(elements) || elements.length !== handles.length) return null;
219
+ const boxes: unknown = reply?.children;
220
+ const childrenOk =
221
+ Array.isArray(boxes) && boxes.length <= MAX_GEOMETRY_CHILDREN && boxes.every(isBox);
222
+ return {
223
+ elements: elements.map(readGeometry),
224
+ children: children && childrenOk ? (boxes as EditingElementBox[]) : null,
225
+ };
226
+ }