@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
@@ -6,7 +6,14 @@ import {
6
6
  } from "./domEditOverlayBasis";
7
7
  import { isElementVisibleThroughAncestors } from "./domEditingDom";
8
8
  import { hugRectForElement } from "./domEditOverlayCrop";
9
- import { composeElementTransform, type PlanarTransformOps } from "./domEditOverlayTransform";
9
+ import {
10
+ elementCornerPoints,
11
+ readElementTransformSnapshot,
12
+ rotationDegreesFromMatrix,
13
+ ROTATION_GATE_EPSILON_DEG,
14
+ type EditingCorners,
15
+ type ElementTransformSnapshot,
16
+ } from "@hyperframes/core/runtime/editing-port";
10
17
  import { type OverlayMeasurePass, readThroughPass } from "./domEditOverlayMeasurePass";
11
18
 
12
19
  export const RESIZE_HANDLE_HIT_PX = 16;
@@ -134,95 +141,6 @@ export function toVisibleOverlayRects(
134
141
  });
135
142
  }
136
143
 
137
- /**
138
- * getComputedStyle(element).transform decomposed into a DOMMatrix, read ONCE.
139
- * Shared by orientedOverlayRect's rotation gate and elementCornerOverlayPoints
140
- * so a single measurement pass serves both — constructing this twice per frame
141
- * (one read per consumer) was redundant work; see orientedOverlayRect below.
142
- */
143
- interface ElementTransformSnapshot {
144
- matrix: DOMMatrix;
145
- cs: CSSStyleDeclaration;
146
- }
147
-
148
- /**
149
- * The transform from the element's own box to the composition's, ACCUMULATED
150
- * over its ancestors rather than read from the element alone.
151
- *
152
- * What the user sees is the product of every transform between the element and
153
- * the composition root, and an element is routinely a child of something
154
- * scaled or rotated. Reading only its own transform drew the selection box at
155
- * the element's untransformed size: a text layer inside a card carrying
156
- * `scale(1.2)` got a box at 1/1.2 of the text, with the top-left correct (the
157
- * caller anchors that to the real bounding rect) and the right and bottom
158
- * edges falling short. The same read decides whether to draw the box rotated,
159
- * so an element inside a rotated parent got an upright box too.
160
- *
161
- * Only the linear part matters here. Each transform's origin contributes
162
- * translation, and the caller discards translation by matching the corners'
163
- * bounding box to the element's real one, so composing the matrices alone is
164
- * enough and there is no per-ancestor origin to unpick.
165
- *
166
- * The walk stops at the composition document's root. The canvas zoom lives on
167
- * the iframe element in Studio's own document and is applied separately by
168
- * `computeOverlayRootScale`; including it here would count it twice.
169
- */
170
- function readElementTransformSnapshot(
171
- win: Window,
172
- element: HTMLElement,
173
- pass?: OverlayMeasurePass,
174
- ): ElementTransformSnapshot | null {
175
- const DOMMatrixCtor = (win as Window & typeof globalThis).DOMMatrix;
176
- if (!DOMMatrixCtor) return null;
177
- const cs = win.getComputedStyle(element);
178
- // The corner math transforms points, so this algebra keeps the full matrix,
179
- // translation included, where the crop frame's keeps only 2D components.
180
- const ops: PlanarTransformOps<DOMMatrix> = {
181
- identity: () => new DOMMatrixCtor(),
182
- fromTransform: (value) => new DOMMatrixCtor(value),
183
- fromRotate: (degrees) => new DOMMatrixCtor().rotateSelf(degrees),
184
- compose: (outer, inner) => outer.multiply(inner),
185
- };
186
- try {
187
- const matrix = composeElementTransform(
188
- element,
189
- ops,
190
- (node) => (node === element ? cs : win.getComputedStyle(node)),
191
- pass?.transform,
192
- );
193
- return matrix ? { matrix, cs } : null;
194
- } catch {
195
- return null;
196
- }
197
- }
198
-
199
- /**
200
- * The element's live transform rotation, in DEGREES (screen/CSS convention, CW
201
- * positive), decomposed from its transform matrix (rotation = atan2(b, a)).
202
- * GSAP folds rotation and scale into the same matrix; this reads rotation only.
203
- * Skew is ignored (does not affect atan2(b, a)).
204
- */
205
- function rotationDegreesFromMatrix(matrix: DOMMatrix): number {
206
- const a = Number.isFinite(matrix.a) ? matrix.a : 1;
207
- const b = Number.isFinite(matrix.b) ? matrix.b : 0;
208
- const c = Number.isFinite(matrix.c) ? matrix.c : 0;
209
- const d = Number.isFinite(matrix.d) ? matrix.d : 1;
210
- const fromX = (Math.atan2(b, a) * 180) / Math.PI;
211
- const determinant = a * d - b * c;
212
- // A reflection makes one basis direction read 180° away from the authored
213
- // rotation. For cursor/handle orientation those directions are equivalent;
214
- // choose the representative nearest zero instead of drawing a pure mirror's
215
- // rotate handle on the opposite side of the element.
216
- const fromY = (Math.atan2(-c, d) * 180) / Math.PI;
217
- const deg = determinant < 0 && Math.abs(fromY) < Math.abs(fromX) ? fromY : fromX;
218
- return Number.isFinite(deg) ? deg : 0;
219
- }
220
-
221
- /** Below this, orientedOverlayRect treats the element as unrotated and returns
222
- * the AABB directly (see its doc comment) — tight enough to only swallow
223
- * matrix-decomposition floating-point noise, never an actual rotation. */
224
- const ROTATION_GATE_EPSILON_DEG = 1e-4;
225
-
226
144
  function toOverlayRect(
227
145
  overlayEl: HTMLDivElement,
228
146
  iframe: HTMLIFrameElement,
@@ -233,7 +151,6 @@ function toOverlayRect(
233
151
  const scale =
234
152
  precomputedScale ?? computeOverlayRootScale(overlayEl, iframe, iframe.contentDocument);
235
153
  if (!scale) return null;
236
- const { iframeRect, overlayRect, rootScaleX, rootScaleY } = scale;
237
154
 
238
155
  const elementRect = element.getBoundingClientRect();
239
156
  const sourceBoundary = findSourceBoundary(element, pass);
@@ -245,13 +162,35 @@ function toOverlayRect(
245
162
  sourceBoundary.getBoundingClientRect(),
246
163
  )
247
164
  : sourceBoundary?.getBoundingClientRect();
165
+ return frameRectToOverlay(scale, elementRect, {
166
+ width: sourceBoundaryRect?.width,
167
+ height: sourceBoundaryRect?.height,
168
+ declaredWidth: readPositiveDimension(sourceBoundary?.getAttribute("data-width") ?? null),
169
+ declaredHeight: readPositiveDimension(sourceBoundary?.getAttribute("data-height") ?? null),
170
+ });
171
+ }
172
+
173
+ type FrameSource = {
174
+ width?: number;
175
+ height?: number;
176
+ declaredWidth: number | null;
177
+ declaredHeight: number | null;
178
+ } | null;
179
+
180
+ /** A client rect measured in the frame, and its source boundary's, in overlay coordinates. */
181
+ export function frameRectToOverlay(
182
+ scale: OverlayRootScale,
183
+ elementRect: { left: number; top: number; width: number; height: number },
184
+ source: FrameSource,
185
+ ): OverlayRect {
186
+ const { iframeRect, overlayRect, rootScaleX, rootScaleY } = scale;
248
187
  const editScale = resolveDomEditCoordinateScale({
249
188
  rootScaleX,
250
189
  rootScaleY,
251
- sourceRectWidth: sourceBoundaryRect?.width,
252
- sourceRectHeight: sourceBoundaryRect?.height,
253
- sourceWidth: readPositiveDimension(sourceBoundary?.getAttribute("data-width") ?? null),
254
- sourceHeight: readPositiveDimension(sourceBoundary?.getAttribute("data-height") ?? null),
190
+ sourceRectWidth: source?.width,
191
+ sourceRectHeight: source?.height,
192
+ sourceWidth: source?.declaredWidth,
193
+ sourceHeight: source?.declaredHeight,
255
194
  });
256
195
 
257
196
  return {
@@ -264,6 +203,23 @@ function toOverlayRect(
264
203
  };
265
204
  }
266
205
 
206
+ /** Corners measured in the frame's viewport px, in overlay coordinates. */
207
+ export function frameCornersToOverlay(
208
+ { iframeRect, overlayRect, rootScaleX, rootScaleY }: OverlayRootScale,
209
+ corners: EditingCorners,
210
+ ): Record<FixedCorner, { x: number; y: number }> {
211
+ const toOverlay = (pt: { x: number; y: number }): { x: number; y: number } => ({
212
+ x: iframeRect.left - overlayRect.left + pt.x * rootScaleX,
213
+ y: iframeRect.top - overlayRect.top + pt.y * rootScaleY,
214
+ });
215
+ return {
216
+ nw: toOverlay(corners.nw),
217
+ ne: toOverlay(corners.ne),
218
+ se: toOverlay(corners.se),
219
+ sw: toOverlay(corners.sw),
220
+ };
221
+ }
222
+
267
223
  /** Which physical corner of the (possibly rotated) element a resize handle keeps
268
224
  * fixed: NW grabs the top-left, so the bottom-right (se) is the anchor, etc. */
269
225
  export type FixedCorner = "nw" | "ne" | "sw" | "se";
@@ -309,55 +265,15 @@ export function elementCornerOverlayPoints(
309
265
  const win = iframe.contentWindow;
310
266
  const doc = iframe.contentDocument;
311
267
  if (!win || !doc) return null;
312
- const DOMPointCtor = (win as Window & typeof globalThis).DOMPoint;
313
- if (!DOMPointCtor) return null;
268
+ if (!(win as Window & typeof globalThis).DOMPoint) return null;
314
269
 
315
270
  const scale = precomputedScale ?? computeOverlayRootScale(overlayEl, iframe, doc);
316
271
  if (!scale) return null;
317
- const { iframeRect, overlayRect, rootScaleX, rootScaleY } = scale;
318
272
 
319
- // The element's local border box maps to viewport coords by the SAME transform
320
- // matrix the browser used for its BCR. We recover the transform's screen-space
321
- // action from the BCR: transformPoint(localCorner - origin) gives a corner
322
- // RELATIVE to the transformed origin. We anchor those relative corners to the
323
- // BCR by matching the AABB of the transformed corners to the real BCR — the
324
- // constant offset cancels in the before/after difference the caller takes, but
325
- // we resolve it fully here so callers can also read absolute overlay positions.
326
273
  const transform = precomputedTransform ?? readElementTransformSnapshot(win, element);
327
274
  if (!transform) return null;
328
- const { matrix, cs } = transform;
329
- const w = element.offsetWidth;
330
- const h = element.offsetHeight;
331
- const originParts = cs.transformOrigin.split(" ").map((p) => Number.parseFloat(p));
332
- const ox = Number.isFinite(originParts[0]!) ? originParts[0]! : w / 2;
333
- const oy = Number.isFinite(originParts[1]!) ? originParts[1]! : h / 2;
334
- const rel = (lx: number, ly: number): { x: number; y: number } => {
335
- const p = matrix.transformPoint(new DOMPointCtor(lx - ox, ly - oy));
336
- return { x: p.x, y: p.y };
337
- };
338
- const relCorners = {
339
- nw: rel(0, 0),
340
- ne: rel(w, 0),
341
- se: rel(w, h),
342
- sw: rel(0, h),
343
- };
344
- // Recover the absolute viewport position by matching to the element's BCR:
345
- // the relative corners' AABB min corresponds to the BCR's top-left.
346
- const xs = [relCorners.nw.x, relCorners.ne.x, relCorners.se.x, relCorners.sw.x];
347
- const ys = [relCorners.nw.y, relCorners.ne.y, relCorners.se.y, relCorners.sw.y];
348
- const bcr = element.getBoundingClientRect();
349
- const dx = bcr.left - Math.min(...xs);
350
- const dy = bcr.top - Math.min(...ys);
351
- const toOverlay = (pt: { x: number; y: number }): { x: number; y: number } => ({
352
- x: iframeRect.left - overlayRect.left + (pt.x + dx) * rootScaleX,
353
- y: iframeRect.top - overlayRect.top + (pt.y + dy) * rootScaleY,
354
- });
355
- return {
356
- nw: toOverlay(relCorners.nw),
357
- ne: toOverlay(relCorners.ne),
358
- se: toOverlay(relCorners.se),
359
- sw: toOverlay(relCorners.sw),
360
- };
275
+ const corners = elementCornerPoints(win, element, transform);
276
+ return corners && frameCornersToOverlay(scale, corners);
361
277
  }
362
278
 
363
279
  /**
@@ -397,11 +313,20 @@ export function orientedOverlayRect(
397
313
  if (!base) return null;
398
314
 
399
315
  const win = iframe.contentWindow;
400
- const transform = win ? readElementTransformSnapshot(win, element, pass) : null;
316
+ const transform = win ? readElementTransformSnapshot(win, element, pass?.transform) : null;
401
317
  const angle = transform ? rotationDegreesFromMatrix(transform.matrix) : 0;
402
318
  if (Math.abs(angle) < ROTATION_GATE_EPSILON_DEG) return base;
403
319
 
404
320
  const corners = elementCornerOverlayPoints(overlayEl, iframe, element, scale, transform);
321
+ return orientOverlayRect(base, angle, corners);
322
+ }
323
+
324
+ /** The oriented box whose corners are `corners`, at `angle`; `base` when they cannot describe one. */
325
+ export function orientOverlayRect(
326
+ base: OverlayRect,
327
+ angle: number,
328
+ corners: Record<FixedCorner, { x: number; y: number }> | null,
329
+ ): OverlayRect {
405
330
  if (!corners) return base;
406
331
  // Unrotated edge lengths (in overlay px): nw→ne is the width, nw→sw the height.
407
332
  const width = cornerEdgeLength(corners.nw, corners.ne);
@@ -0,0 +1,138 @@
1
+ /** Selection rules over an ancestor chain: one answer for live elements and for descriptions. */
2
+ import type { TimelineElementDomTarget, TimelineElementDomTargetOptions } from "./domEditingTypes";
3
+ import { escapeCssString, normalizeTimelineCompositionSource } from "./domEditingDom";
4
+
5
+ /** Reads one element of a chain: the target first, then each parent up to the document element. */
6
+ export interface SelectionChainReader<N> {
7
+ attr(node: N, name: string): string | null;
8
+ selector(node: N): string | undefined;
9
+ /** The document's `body` or root element, where the walk to an addressable element stops. */
10
+ isDocumentRoot(node: N): boolean;
11
+ }
12
+
13
+ const OUT_OF_SCOPE = -1;
14
+ const hasClass = (value: string | null, name: string) =>
15
+ (value ?? "").split(/[\t\n\f\r ]+/).includes(name);
16
+
17
+ /**
18
+ * A `data-hf-group` wrapper is one unit until the user drills into it; inside the drilled-into
19
+ * group, clicks reach its children, or the next group nested in it. Returns the unit's index, null
20
+ * to resolve the target itself, or OUT_OF_SCOPE when the target is outside the drilled-into group.
21
+ */
22
+ function groupUnitIndex<N>(
23
+ chain: readonly N[],
24
+ read: SelectionChainReader<N>,
25
+ activeGroupIndex: number | null,
26
+ ): number | null {
27
+ const groups = chain.flatMap((node, index) =>
28
+ read.attr(node, "data-hf-group") === null ? [] : [index],
29
+ );
30
+ if (activeGroupIndex === null) return groups.at(-1) ?? null;
31
+ const at = groups.indexOf(activeGroupIndex);
32
+ if (at === -1) return OUT_OF_SCOPE;
33
+ return at > 0 ? groups[at - 1]! : null;
34
+ }
35
+
36
+ /** The nearest `.clip`; a composition host counts only as the target itself. */
37
+ function clipAncestorIndex<N>(chain: readonly N[], read: SelectionChainReader<N>): number | null {
38
+ for (let index = 0; index < chain.length; index += 1) {
39
+ const node = chain[index]!;
40
+ if (!hasClass(read.attr(node, "class"), "clip")) continue;
41
+ const isHost =
42
+ read.attr(node, "data-composition-src") !== null ||
43
+ read.attr(node, "data-composition-file") !== null;
44
+ if (!isHost || index === 0) return index;
45
+ }
46
+ return null;
47
+ }
48
+
49
+ /** Where a selection of `chain[0]` lands; `activeGroupIndex` is -1 for a drilled group not in `chain`. */
50
+ export function selectionTargetIndex<N>(
51
+ chain: readonly N[],
52
+ read: SelectionChainReader<N>,
53
+ options: { exactTarget?: boolean; preferClipAncestor?: boolean; activeGroupIndex: number | null },
54
+ ): number | null {
55
+ let start = options.exactTarget ? 0 : groupUnitIndex(chain, read, options.activeGroupIndex);
56
+ if (start === OUT_OF_SCOPE) start = groupUnitIndex(chain, read, null);
57
+ start ??= options.preferClipAncestor ? (clipAncestorIndex(chain, read) ?? 0) : 0;
58
+ for (let index = start; index < chain.length; index += 1) {
59
+ const node = chain[index]!;
60
+ if (read.isDocumentRoot(node)) return null;
61
+ if (read.selector(node) || read.attr(node, "data-hf-id")?.trim()) return index;
62
+ }
63
+ return null;
64
+ }
65
+
66
+ export function chainLocked<N>(
67
+ chain: readonly N[],
68
+ read: SelectionChainReader<N>,
69
+ index: number,
70
+ ): boolean {
71
+ return chain.slice(index).some((node) => read.attr(node, "data-timeline-locked") !== null);
72
+ }
73
+
74
+ export interface SelectionLookupTarget {
75
+ id?: string | null;
76
+ hfId?: string;
77
+ selector?: string;
78
+ selectorIndex?: number;
79
+ sourceFile?: string;
80
+ }
81
+
82
+ /** The selectors tried in order, each with the index of its match among those from `sourceFile`. */
83
+ export function selectionLookups(
84
+ selection: SelectionLookupTarget,
85
+ ): Array<{ selector: string; index: number }> {
86
+ const lookups: Array<{ selector: string; index: number }> = [];
87
+ if (selection.hfId) {
88
+ lookups.push({ selector: `[data-hf-id="${escapeCssString(selection.hfId)}"]`, index: 0 });
89
+ }
90
+ // Flattened sub-compositions can repeat authored ids, so an id is matched by attribute, per source.
91
+ if (selection.id) lookups.push({ selector: `[id="${escapeCssString(selection.id)}"]`, index: 0 });
92
+ if (selection.selector) {
93
+ lookups.push({ selector: selection.selector, index: selection.selectorIndex ?? 0 });
94
+ }
95
+ return lookups;
96
+ }
97
+
98
+ /**
99
+ * Where a timeline element is in the preview: `target` to look up, else, when `rootFallback`, the
100
+ * first composition root if it comes from `sourceFile`.
101
+ */
102
+ export function timelineElementLookup(
103
+ element: TimelineElementDomTarget,
104
+ options: TimelineElementDomTargetOptions,
105
+ ): { target: SelectionLookupTarget | null; sourceFile: string; rootFallback: boolean } {
106
+ const elementId = typeof element.id === "string" ? element.id : "";
107
+ const compositionSource =
108
+ normalizeTimelineCompositionSource(element.compositionSrc) ??
109
+ options.compIdToSrc?.get(elementId);
110
+ const sourceFile =
111
+ compositionSource ??
112
+ normalizeTimelineCompositionSource(element.sourceFile) ??
113
+ options.activeCompositionPath ??
114
+ "index.html";
115
+ const escapedElementId = escapeCssString(elementId);
116
+ const escapedCompositionSource = compositionSource ? escapeCssString(compositionSource) : null;
117
+ const selector =
118
+ element.selector ??
119
+ (compositionSource
120
+ ? `[data-composition-src="${escapedCompositionSource}"],[data-composition-file="${escapedCompositionSource}"],[data-composition-id="${escapedElementId}"]`
121
+ : escapedElementId
122
+ ? `[data-composition-id="${escapedElementId}"]`
123
+ : undefined);
124
+
125
+ const target =
126
+ selector || element.domId
127
+ ? {
128
+ id: element.domId ?? undefined,
129
+ selector,
130
+ selectorIndex: element.selectorIndex,
131
+ sourceFile,
132
+ }
133
+ : null;
134
+ const hasExplicitDomTarget = Boolean(element.domId || element.selector || compositionSource);
135
+ const rootFallback =
136
+ !options.isMasterView && !hasExplicitDomTarget && Boolean(options.activeCompositionPath);
137
+ return { target, sourceFile, rootFallback };
138
+ }
@@ -240,11 +240,7 @@ describe("resolveVisualDomEditSelectionTarget", () => {
240
240
  setElementRect(container, { width: 900, height: 520 });
241
241
  setElementRect(headline, { left: 240, top: 160, width: 180, height: 36 });
242
242
 
243
- expect(
244
- resolveVisualDomEditSelectionTarget([container, headline], {
245
- activeCompositionPath: "index.html",
246
- }),
247
- ).toBe(headline);
243
+ expect(resolveVisualDomEditSelectionTarget([container, headline])).toBe(headline);
248
244
  });
249
245
 
250
246
  it("skips hidden and zero-size elements before picking a rendered candidate", () => {
@@ -260,11 +256,7 @@ describe("resolveVisualDomEditSelectionTarget", () => {
260
256
  setElementRect(empty, { width: 0, height: 0 });
261
257
  setElementRect(visible, { width: 120, height: 32 });
262
258
 
263
- expect(
264
- resolveVisualDomEditSelectionTarget([hidden, empty, visible], {
265
- activeCompositionPath: "index.html",
266
- }),
267
- ).toBe(visible);
259
+ expect(resolveVisualDomEditSelectionTarget([hidden, empty, visible])).toBe(visible);
268
260
  });
269
261
 
270
262
  it("skips transparent elements that still report a box", () => {
@@ -277,11 +269,7 @@ describe("resolveVisualDomEditSelectionTarget", () => {
277
269
  setElementRect(transparent, { width: 120, height: 32 });
278
270
  setElementRect(visible, { width: 120, height: 32 });
279
271
 
280
- expect(
281
- resolveVisualDomEditSelectionTarget([transparent, visible], {
282
- activeCompositionPath: "index.html",
283
- }),
284
- ).toBe(visible);
272
+ expect(resolveVisualDomEditSelectionTarget([transparent, visible])).toBe(visible);
285
273
  });
286
274
 
287
275
  it("falls back to the nearest stable editable ancestor when a visual child has no target", () => {
@@ -295,11 +283,7 @@ describe("resolveVisualDomEditSelectionTarget", () => {
295
283
  setElementRect(card, { width: 400, height: 200 });
296
284
  setElementRect(span, { left: 40, top: 40, width: 140, height: 28 });
297
285
 
298
- expect(
299
- resolveVisualDomEditSelectionTarget([span, card], {
300
- activeCompositionPath: "index.html",
301
- }),
302
- ).toBe(card);
286
+ expect(resolveVisualDomEditSelectionTarget([span, card])).toBe(card);
303
287
  });
304
288
 
305
289
  it("keeps explicit layer selection able to target containers", async () => {
@@ -313,9 +297,7 @@ describe("resolveVisualDomEditSelectionTarget", () => {
313
297
  setElementRect(container, { width: 900, height: 520 });
314
298
  setElementRect(headline, { left: 240, top: 160, width: 180, height: 36 });
315
299
 
316
- const visualTarget = resolveVisualDomEditSelectionTarget([container, headline], {
317
- activeCompositionPath: "index.html",
318
- });
300
+ const visualTarget = resolveVisualDomEditSelectionTarget([container, headline]);
319
301
  const explicitSelection = await resolveDomEditSelection(container, {
320
302
  activeCompositionPath: "index.html",
321
303
  isMasterView: false,
@@ -341,11 +323,7 @@ describe("resolveVisualDomEditSelectionTarget", () => {
341
323
  setElementRect(sfChrome, { left: 0, top: 0, width: 1920, height: 1080 });
342
324
  setElementRect(subComp, { left: 0, top: 0, width: 1920, height: 1080 });
343
325
 
344
- expect(
345
- resolveVisualDomEditSelectionTarget([pipStudio, subComp, sfChrome], {
346
- activeCompositionPath: "index.html",
347
- }),
348
- ).toBe(pipStudio);
326
+ expect(resolveVisualDomEditSelectionTarget([pipStudio, subComp, sfChrome])).toBe(pipStudio);
349
327
  });
350
328
  });
351
329
 
@@ -42,7 +42,7 @@ it("keeps a provider-backed video selectable and listed with its logical opacity
42
42
  const { video, canvas, root } = preview("0.65");
43
43
  expect(getComputedStyle(video).opacity).toBe("0");
44
44
  expect(isElementVisibleThroughAncestors(video)).toBe(true);
45
- expect(resolveVisualDomEditSelectionTarget([canvas, video], options)).toBe(video);
45
+ expect(resolveVisualDomEditSelectionTarget([canvas, video])).toBe(video);
46
46
  expect(collectDomEditLayerItems(root, options).map((item) => item.element)).toEqual([video]);
47
47
  const selected = await resolveDomEditSelection(video, options);
48
48
  expect(selected?.computedStyles.opacity).toBe("0.65");
@@ -53,7 +53,7 @@ it("keeps a provider-backed video selectable and listed with its logical opacity
53
53
  it("keeps authored zero opacity invisible and reports zero to the inspector", async () => {
54
54
  const { video, canvas } = preview("0");
55
55
  expect(isElementVisibleThroughAncestors(video)).toBe(false);
56
- expect(resolveVisualDomEditSelectionTarget([canvas, video], options)).toBeNull();
56
+ expect(resolveVisualDomEditSelectionTarget([canvas, video])).toBeNull();
57
57
  expect(getCuratedComputedStyles(video).opacity).toBe("0");
58
58
  const selected = await resolveDomEditSelection(video, options);
59
59
  expect(selected?.computedStyles.opacity).toBe("0");
@@ -64,7 +64,7 @@ it("still respects a hidden ancestor when the preview frame itself is visible",
64
64
  const { video, root } = preview("0.65");
65
65
  root.style.opacity = "0";
66
66
  expect(isElementVisibleThroughAncestors(video)).toBe(false);
67
- expect(resolveVisualDomEditSelectionTarget([video], options)).toBeNull();
67
+ expect(resolveVisualDomEditSelectionTarget([video])).toBeNull();
68
68
  });
69
69
 
70
70
  it("does not treat an unrelated preceding canvas as the video's visible frame", () => {
@@ -4,11 +4,11 @@
4
4
  * No imports from other domEditing* modules — safe to import from anywhere.
5
5
  */
6
6
  import { getLogicalOpacity } from "@hyperframes/core/studio-preview-mark";
7
- import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
8
7
  import {
9
8
  buildStableSelector,
10
9
  escapeCssString,
11
10
  getPreferredClassSelector,
11
+ isElementVisibleThroughAncestors,
12
12
  readElementSource,
13
13
  type EditingElementSource,
14
14
  } from "@hyperframes/core/runtime/editing-port";
@@ -45,65 +45,8 @@ export function isEditableTextLeaf(el: HTMLElement): boolean {
45
45
  export { getLogicalOpacity };
46
46
  // One addressing rule for Studio and the runtime that describes elements to it.
47
47
  export { buildStableSelector, escapeCssString };
48
-
49
- /** Does this node render AT ALL, ignoring what it inherits? Sole owner of the
50
- * rule; the walk below only decides which nodes to ask it about. */
51
- function elementRendersItself(win: Window, el: HTMLElement): boolean {
52
- const computed = win.getComputedStyle(el);
53
- if (computed.display === "none" || computed.visibility === "hidden") return false;
54
- const opacity = Number.parseFloat(getLogicalOpacity(el, computed));
55
- return !(
56
- Number.isFinite(opacity) &&
57
- opacity <= 0.01 &&
58
- !el.hasAttribute(COLOR_GRADING_SOURCE_HIDDEN_ATTR)
59
- );
60
- }
61
-
62
- /**
63
- * Does `el` render, given everything above it?
64
- *
65
- * `memo` is for a caller asking this about MANY elements in one synchronous
66
- * pass. Answers are a function of the node and its ancestors, and siblings
67
- * share almost all of their chain, so memoizing per node turns a walk per
68
- * element into one style read per node in the tree. It is only ever valid for
69
- * the length of one pass — the DOM cannot change under a pass, and every read
70
- * here is a read — so the caller creates it and drops it, and nothing survives
71
- * to be invalidated. Omitted, every call walks the chain itself.
72
- *
73
- * The ANSWER is what it always was. Which nodes get a style read is not: this
74
- * resolves top-down and stops at the first node that is out, where the previous
75
- * version resolved bottom-up and stopped at the first one that is out going the
76
- * other way. Same boolean for every input, a different (and, for a subtree
77
- * hidden near the root, smaller) set of reads.
78
- */
79
- export function isElementVisibleThroughAncestors(
80
- el: HTMLElement,
81
- memo?: Map<HTMLElement, boolean>,
82
- ): boolean {
83
- const win = el.ownerDocument.defaultView;
84
- if (!win) return true;
85
- // Up to the first node already answered for, then back down: a node's answer
86
- // needs its ancestors' first, and the topmost unanswered node is where the
87
- // chain of unknowns starts.
88
- const pending: HTMLElement[] = [];
89
- let inherited = true;
90
- for (let node: HTMLElement | null = el; node; node = node.parentElement) {
91
- const answered = memo?.get(node);
92
- if (answered !== undefined) {
93
- inherited = answered;
94
- break;
95
- }
96
- pending.push(node);
97
- }
98
- for (let i = pending.length - 1; i >= 0; i -= 1) {
99
- const node = pending[i]!;
100
- // Once an ancestor is out, its descendants are out with it, and asking the
101
- // platform about them would be a style read for an answer already known.
102
- inherited = inherited && elementRendersItself(win, node);
103
- memo?.set(node, inherited);
104
- }
105
- return inherited;
106
- }
48
+ // One visibility rule for Studio and the runtime that measures overlay geometry for it.
49
+ export { isElementVisibleThroughAncestors };
107
50
 
108
51
  // ─── Style accessors ──────────────────────────────────────────────────────────
109
52
 
@@ -140,22 +83,6 @@ export function getDataAttributes(el: HTMLElement): Record<string, string> {
140
83
  return attrs;
141
84
  }
142
85
 
143
- // ─── DOM traversal ────────────────────────────────────────────────────────────
144
-
145
- export function findClosestByAttribute(
146
- el: HTMLElement,
147
- attributeNames: string[],
148
- ): HTMLElement | null {
149
- let current: HTMLElement | null = el;
150
- while (current) {
151
- const candidate = current;
152
- if (attributeNames.some((attribute) => candidate.hasAttribute(attribute))) {
153
- return candidate;
154
- }
155
- current = current.parentElement;
156
- }
157
- return null;
158
- }
159
86
  // ─── Composition source resolution ───────────────────────────────────────────
160
87
 
161
88
  // The runtime INLINES subcompositions and strips the source-file linkage from the