@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
@@ -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
 
@@ -73,6 +74,7 @@ export function usePreviewInteraction({
73
74
  }: UsePreviewInteractionParams) {
74
75
  const cycleRef = useRef<ClickCycleState | null>(null);
75
76
  const lastDownRef = useRef<{ t: number; x: number; y: number } | null>(null);
77
+ const hoverSeqRef = useRef(0);
76
78
 
77
79
  const pausePreviewPlayback = useCallback(() => {
78
80
  const pausedTime = pauseStudioPreviewPlayback(previewIframeRef.current);
@@ -119,7 +121,7 @@ export function usePreviewInteraction({
119
121
  cycle.candidates.length > 1 &&
120
122
  Math.hypot(e.clientX - cycle.x, e.clientY - cycle.y) < CYCLE_RADIUS_PX &&
121
123
  downTs - cycle.at < CYCLE_WINDOW_MS;
122
- if (hit?.element.hasAttribute("data-hf-group")) {
124
+ if (hit && selectionDataAttribute(hit, "data-hf-group") !== null) {
123
125
  e.preventDefault();
124
126
  e.stopPropagation();
125
127
  cycleRef.current = null;
@@ -134,8 +136,8 @@ export function usePreviewInteraction({
134
136
  if (
135
137
  hit &&
136
138
  !hasStackCycleAtSpot &&
137
- !hit.element.hasAttribute("data-composition-src") &&
138
- !hit.element.hasAttribute("data-composition-file")
139
+ selectionDataAttribute(hit, "data-composition-src") === null &&
140
+ selectionDataAttribute(hit, "data-composition-file") === null
139
141
  ) {
140
142
  e.preventDefault();
141
143
  e.stopPropagation();
@@ -190,7 +192,7 @@ export function usePreviewInteraction({
190
192
  preferClipAncestor: options?.preferClipAncestor ?? false,
191
193
  });
192
194
  // 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
195
+ // group (selectionTargetIndex: out of scope). Drill-in isn't sticky: exit it and
194
196
  // re-resolve at the top level so this click selects whatever's there (or the
195
197
  // group as a unit). Without this, a stale drill-in keeps selecting children and
196
198
  // the "first click selects the group" expectation breaks.
@@ -237,6 +239,7 @@ export function usePreviewInteraction({
237
239
  const handlePreviewCanvasPointerMove = useCallback(
238
240
  // fallow-ignore-next-line complexity
239
241
  async (e: React.PointerEvent<HTMLDivElement>, options?: { preferClipAncestor?: boolean }) => {
242
+ const seq = ++hoverSeqRef.current;
240
243
  if (captionEditMode || compositionLoading) {
241
244
  updateDomEditHoverSelection(null);
242
245
  return null;
@@ -246,7 +249,7 @@ export function usePreviewInteraction({
246
249
  preferClipAncestor: options?.preferClipAncestor ?? false,
247
250
  skipSourceProbe: true,
248
251
  });
249
- updateDomEditHoverSelection(nextSelection);
252
+ if (seq === hoverSeqRef.current) updateDomEditHoverSelection(nextSelection);
250
253
  return nextSelection;
251
254
  },
252
255
  [
@@ -258,6 +261,7 @@ export function usePreviewInteraction({
258
261
  );
259
262
 
260
263
  const handlePreviewCanvasPointerLeave = useCallback(() => {
264
+ hoverSeqRef.current += 1;
261
265
  updateDomEditHoverSelection(null);
262
266
  }, [updateDomEditHoverSelection]);
263
267
 
@@ -17,7 +17,8 @@ async function fetchProjectFile(projectId: string | null, path: string, query: s
17
17
  const response = await studioApiFetch(
18
18
  `/api/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(path)}${query}`,
19
19
  );
20
- if (!response.ok) throw new Error(`Failed to read ${path}`);
20
+ if (!response.ok)
21
+ throw await createStudioSaveHttpError(response, `Failed to read ${path}`, { path });
21
22
  const data = (await response.json()) as { content?: string; version?: string };
22
23
  return { content: data.content, version: data.version ?? response.headers.get("etag") };
23
24
  }
@@ -78,7 +79,9 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
78
79
  } else if (preflight.status === 404) {
79
80
  expectedVersion = null;
80
81
  } else {
81
- throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`);
82
+ throw await createStudioSaveHttpError(preflight, `Failed to read ${path} before save`, {
83
+ path,
84
+ });
82
85
  }
83
86
  }
84
87
  // fallow-ignore-next-line complexity
@@ -121,7 +124,8 @@ export function useProjectFileWriter({ projectId }: UseProjectFileWriterOptions)
121
124
  attemptedContent: content,
122
125
  });
123
126
  }
124
- if (!response.ok) throw await createStudioSaveHttpError(response, `Failed to save ${path}`);
127
+ if (!response.ok)
128
+ throw await createStudioSaveHttpError(response, `Failed to save ${path}`, { path });
125
129
  const result = (await response.json()) as { version?: string };
126
130
  const version = result.version ?? response.headers.get("etag");
127
131
  if (!version)
@@ -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();
@@ -80,6 +80,36 @@ function makeSyncFixture() {
80
80
  }
81
81
 
82
82
  describe("useTimelineSelectionPreviewSync", () => {
83
+ it("keeps an opaque frame's selection that matches a clip known only by its id", async () => {
84
+ // An opaque frame's rows carry only the clip id; its selections carry the frame's handle.
85
+ const timelineElements = [
86
+ { id: "clip-1", tag: "div", start: 0, duration: 1, track: 0 },
87
+ ] as TimelineElement[];
88
+ const element = document.createElement("div");
89
+ element.id = "clip-1";
90
+ const selection = { ...makeSelection("First", element), handle: "0123456789abcdef:1" };
91
+ const applyDomSelection = vi.fn();
92
+ const applyMarqueeSelection = vi.fn();
93
+ const buildDomSelectionForTimelineElement = vi.fn(async () => null);
94
+ const harness = renderHarness();
95
+
96
+ await harness.rerender({
97
+ selectedElementId: "clip-1",
98
+ selectedElementIds: new Set(["clip-1"]),
99
+ timelineElements,
100
+ domEditSelection: selection,
101
+ domEditGroupSelections: [selection],
102
+ buildDomSelectionForTimelineElement,
103
+ applyDomSelection,
104
+ applyMarqueeSelection,
105
+ onSelectionNotFound: vi.fn(),
106
+ });
107
+
108
+ expect(buildDomSelectionForTimelineElement).not.toHaveBeenCalled();
109
+ expect(applyDomSelection).not.toHaveBeenCalled();
110
+ harness.cleanup();
111
+ });
112
+
83
113
  it("syncs a multi-id timeline selection into preview group selections", async () => {
84
114
  const { firstSelection, secondSelection, timelineElements, selectionById } = makeSyncFixture();
85
115
  const applyDomSelection = vi.fn();
@@ -139,11 +139,16 @@ export function useTimelineSelectionPreviewSync({
139
139
  : [];
140
140
  const currentIds = currentSelections
141
141
  .map((selection) =>
142
- resolveTimelineIdForSelection(selection, timelineElements, activeCompPath),
142
+ resolveTimelineIdForSelection(selection, timelineElements, activeCompPath, true),
143
143
  )
144
144
  .filter((id): id is string => Boolean(id));
145
145
  const currentAnchor = currentDomEditSelection
146
- ? resolveTimelineIdForSelection(currentDomEditSelection, timelineElements, activeCompPath)
146
+ ? resolveTimelineIdForSelection(
147
+ currentDomEditSelection,
148
+ timelineElements,
149
+ activeCompPath,
150
+ true,
151
+ )
147
152
  : null;
148
153
 
149
154
  if (selectedIds.length === 0) {
@@ -1,3 +1,4 @@
1
+ import { elementZIndex } from "@hyperframes/core/runtime/editing-port";
1
2
  import { readLayerRevealPriorZ } from "./timelineElementHelpers";
2
3
 
3
4
  export interface StackingContextDescriptor {
@@ -16,17 +17,7 @@ export function getElementZIndex(element: HTMLElement): number {
16
17
  // An active Layers-panel reveal lift reports the element's TRUE z.
17
18
  const prior = readLayerRevealPriorZ(element);
18
19
  if (prior != null) return prior;
19
- const inline = element.style?.zIndex;
20
- if (inline && inline !== "auto") {
21
- const parsed = parseInt(inline, 10);
22
- if (Number.isFinite(parsed)) return parsed;
23
- }
24
- const win = element.ownerDocument?.defaultView;
25
- if (!win) return 0;
26
- const value = win.getComputedStyle(element).zIndex;
27
- if (value === "auto" || value === "") return 0;
28
- const parsed = parseInt(value, 10);
29
- return Number.isFinite(parsed) ? parsed : 0;
20
+ return elementZIndex(element);
30
21
  } catch {
31
22
  return 0;
32
23
  }
@@ -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,9 +5,16 @@
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,
17
+ type EditingLayer,
11
18
  } from "@hyperframes/core/runtime/editing-port";
12
19
  import { resolveElementSourceFile } from "../../components/editor/domEditingDom";
13
20
  import { previewRequest } from "./previewChannel";
@@ -49,11 +56,12 @@ function hasPlainFields(value: Fields): boolean {
49
56
  return groupsOk && attributesOk && childrenOk && typeof value.truncated === "boolean";
50
57
  }
51
58
 
59
+ const isRect = (value: unknown) =>
60
+ isFields(value) && [value.x, value.y, value.width, value.height].every(Number.isFinite);
61
+
52
62
  function readHit(value: unknown): PreviewElementHit | null {
53
63
  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;
64
+ return isRect(value.rect) ? (value as unknown as PreviewElementHit) : null;
57
65
  }
58
66
 
59
67
  /** Frame data checked against `EditingElementDescription`; null when any field is off. */
@@ -78,6 +86,18 @@ export async function previewElementsAtPoint(
78
86
  return elements.map(readHit).filter((element) => element !== null);
79
87
  }
80
88
 
89
+ export async function previewPointerTargets(
90
+ iframe: HTMLIFrameElement,
91
+ rootFractionX: number,
92
+ rootFractionY: number,
93
+ ): Promise<{ target: PreviewElementHit | null; stack: PreviewElementHit[] } | null> {
94
+ const params = { x: rootFractionX, y: rootFractionY };
95
+ const reply = await previewRequest(iframe, "pointer-targets", params);
96
+ const stack: unknown = reply?.stack;
97
+ if (!reply || !Array.isArray(stack)) return null;
98
+ return { target: readHit(reply.target), stack: stack.map(readHit).filter((hit) => hit !== null) };
99
+ }
100
+
81
101
  /**
82
102
  * One entry per handle, in order: null for an element the frame no longer has. The whole answer is
83
103
  * null when the runtime cannot answer, or when there are no handles or more than the runtime takes.
@@ -96,6 +116,32 @@ export async function describePreviewElements(
96
116
  });
97
117
  }
98
118
 
119
+ /** Each handle's ancestors, parent first; null for an element the frame no longer has. */
120
+ export async function previewAncestors(
121
+ iframe: HTMLIFrameElement,
122
+ handles: readonly string[],
123
+ ): Promise<Array<string[] | null> | null> {
124
+ if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
125
+ const reply = await previewRequest(iframe, "ancestors", { handles: [...handles] });
126
+ const chains: unknown = reply?.ancestors;
127
+ if (!Array.isArray(chains) || chains.length !== handles.length) return null;
128
+ return chains.map((chain) =>
129
+ Array.isArray(chain) && chain.every(isHandle) ? (chain as string[]) : null,
130
+ );
131
+ }
132
+
133
+ /** The frame's matches for `selector` in document order; null when the runtime cannot answer. */
134
+ export async function queryPreviewElements(
135
+ iframe: HTMLIFrameElement,
136
+ selector: string,
137
+ ): Promise<{ matches: EditingElementMatch[]; truncated: boolean } | null> {
138
+ const reply = await previewRequest(iframe, "query", { selector });
139
+ const matches: unknown = reply?.matches;
140
+ if (!Array.isArray(matches) || typeof reply?.truncated !== "boolean") return null;
141
+ const ok = matches.every((m) => isFields(m) && isHandle(m.handle) && isSource(m.source));
142
+ return ok ? { matches: matches as EditingElementMatch[], truncated: reply.truncated } : null;
143
+ }
144
+
99
145
  /** `getSourceFileForElement` for the frame's own element. */
100
146
  export function previewElementSourceFile(
101
147
  element: PreviewElement,
@@ -115,3 +161,97 @@ export function previewElementSelectorIndex(
115
161
  .filter((group) => resolveElementSourceFile(group.source, activeCompositionPath) === file)
116
162
  .reduce((sum, group) => sum + group.count, 0);
117
163
  }
164
+
165
+ const isPoint = (value: unknown) =>
166
+ isFields(value) && Number.isFinite(value.x) && Number.isFinite(value.y);
167
+ const isSizeOrNull = (value: unknown) =>
168
+ value === null || (Number.isFinite(value) && (value as number) > 0);
169
+
170
+ const CORNERS = ["nw", "ne", "se", "sw"] as const;
171
+ const isCorners = (value: unknown) =>
172
+ value === null || (isFields(value) && CORNERS.every((corner) => isPoint(value[corner])));
173
+
174
+ const isSourceBox = (value: unknown) =>
175
+ value === null ||
176
+ (isFields(value) &&
177
+ Number.isFinite(value.width) &&
178
+ Number.isFinite(value.height) &&
179
+ isSizeOrNull(value.declaredWidth) &&
180
+ isSizeOrNull(value.declaredHeight));
181
+
182
+ const isClipPath = (value: unknown) =>
183
+ value === null || (isText(value) && (value as string).length <= MAX_ELEMENT_VALUE);
184
+
185
+ const isBox = (value: unknown): value is EditingElementBox =>
186
+ isFields(value) &&
187
+ isRect(value.rect) &&
188
+ Number.isFinite(value.angle) &&
189
+ isCorners(value.corners) &&
190
+ isSourceBox(value.source) &&
191
+ isClipPath(value.clipPath);
192
+
193
+ const readGeometry = (value: unknown): EditingElementGeometry | null => {
194
+ if (!isBox(value) || !isFields(value) || typeof value.visible !== "boolean") return null;
195
+ const { members } = value;
196
+ const membersOk =
197
+ members === null ||
198
+ (Array.isArray(members) && members.length <= MAX_ELEMENT_ENTRIES && members.every(isRect));
199
+ return membersOk ? (value as unknown as EditingElementGeometry) : null;
200
+ };
201
+
202
+ export interface PreviewGeometry {
203
+ /** One entry per handle, in order: null for an element the frame no longer has. */
204
+ elements: Array<EditingElementGeometry | null>;
205
+ /** The `children` element's descendants, when it has 1 to MAX_GEOMETRY_CHILDREN; else empty. */
206
+ children: EditingElementBox[] | null;
207
+ }
208
+
209
+ /** Overlay geometry for `handles`, and `children`'s descendant boxes; null when the runtime cannot answer. */
210
+ export async function previewGeometry(
211
+ iframe: HTMLIFrameElement,
212
+ handles: readonly string[],
213
+ children?: string,
214
+ ): Promise<PreviewGeometry | null> {
215
+ if (!handles.length || handles.length > MAX_DESCRIBE_HANDLES) return null;
216
+ const params = { handles: [...handles], ...(children ? { children } : {}) };
217
+ const reply = await previewRequest(iframe, "geometry", params);
218
+ const elements: unknown = reply?.elements;
219
+ if (!Array.isArray(elements) || elements.length !== handles.length) return null;
220
+ const boxes: unknown = reply?.children;
221
+ const childrenOk =
222
+ Array.isArray(boxes) && boxes.length <= MAX_GEOMETRY_CHILDREN && boxes.every(isBox);
223
+ return {
224
+ elements: elements.map(readGeometry),
225
+ children: children && childrenOk ? (boxes as EditingElementBox[]) : null,
226
+ };
227
+ }
228
+
229
+ const LAYER_KINDS = new Set(["image", "video", "audio", "vector", "group", "text", "shape"]);
230
+ const isLayer = (value: unknown): value is EditingLayer =>
231
+ isFields(value) &&
232
+ isHandle(value.handle) &&
233
+ isCount(value.depth) &&
234
+ isCount(value.childCount) &&
235
+ Number.isFinite(value.zIndex) &&
236
+ LAYER_KINDS.has(value.kind as string);
237
+
238
+ export interface PreviewLayers {
239
+ layers: EditingLayer[];
240
+ truncated: boolean;
241
+ missingGroup: boolean;
242
+ }
243
+
244
+ /** One page of the frame's layers in document order from `offset`, scoped to `group` when given; null when the runtime cannot answer. */
245
+ export async function previewLayers(
246
+ iframe: HTMLIFrameElement,
247
+ group?: string,
248
+ offset = 0,
249
+ ): Promise<PreviewLayers | null> {
250
+ const params = { ...(group ? { group } : {}), ...(offset ? { offset } : {}) };
251
+ const reply = await previewRequest(iframe, "layers", params);
252
+ const layers: unknown = reply?.layers;
253
+ const { truncated, missingGroup } = reply ?? {};
254
+ if (!Array.isArray(layers) || typeof truncated !== "boolean") return null;
255
+ if (typeof missingGroup !== "boolean") return null;
256
+ return layers.every(isLayer) ? { layers, truncated, missingGroup } : null;
257
+ }
@@ -1,5 +1,5 @@
1
1
  {
2
- "total": 226,
2
+ "total": 223,
3
3
  "files": {
4
4
  "packages/studio/src/captions/components/CaptionOverlay.tsx": 5,
5
5
  "packages/studio/src/captions/components/CaptionTimeline.tsx": 11,
@@ -18,7 +18,6 @@
18
18
  "packages/studio/src/components/editor/SnapGuideOverlay.tsx": 3,
19
19
  "packages/studio/src/components/editor/Transform3DCube.tsx": 5,
20
20
  "packages/studio/src/components/editor/colorValue.ts": 3,
21
- "packages/studio/src/components/editor/domEditingElement.ts": 1,
22
21
  "packages/studio/src/components/editor/gradientValue.ts": 6,
23
22
  "packages/studio/src/components/editor/panelTokens.ts": 4,
24
23
  "packages/studio/src/components/editor/propertyPanelColor.tsx": 7,
package/src/test-setup.ts CHANGED
@@ -12,3 +12,5 @@ if (typeof CSS.escape !== "function") {
12
12
  if (typeof globalThis.confirm !== "function") {
13
13
  (globalThis as Record<string, unknown>).confirm = () => false;
14
14
  }
15
+
16
+ (globalThis as Record<string, unknown>).BASE_UI_ANIMATIONS_DISABLED = true;
@@ -286,8 +286,8 @@ export function applySoftReloadFinalization(
286
286
  currentTime: number,
287
287
  ): boolean {
288
288
  const win = iframe?.contentWindow as IframeWindow | null;
289
- if (!win?.__hfForceTimelineRebind) return false;
290
289
  try {
290
+ if (!win?.__hfForceTimelineRebind) return false;
291
291
  if (win.__hfSuppressSceneMutations) {
292
292
  win.__hfSuppressSceneMutations(() => finalizeSoftReload(win, currentTime));
293
293
  } else {
@@ -75,7 +75,7 @@ export async function readProjectFileContent(pid: string, path: string): Promise
75
75
  buildProjectApiPath(pid, `/files/${encodeURIComponent(path)}`),
76
76
  );
77
77
  if (!response.ok) {
78
- throw await createStudioSaveHttpError(response, `Failed to read ${path}`);
78
+ throw await createStudioSaveHttpError(response, `Failed to read ${path}`, { path });
79
79
  }
80
80
  const data = (await response.json()) as { content?: string };
81
81
  if (typeof data.content !== "string") {
@@ -103,19 +103,6 @@ export function isManualGeometryStyleProperty(property: string): boolean {
103
103
  return property === "left" || property === "top" || property === "width" || property === "height";
104
104
  }
105
105
 
106
- export function getEventTargetElement(target: EventTarget | null): HTMLElement | null {
107
- if (!target || typeof target !== "object") return null;
108
- const maybeNode = target as {
109
- nodeType?: number;
110
- parentElement?: Element | null;
111
- };
112
- if (maybeNode.nodeType === 1) return target as HTMLElement;
113
- if (maybeNode.nodeType === 3 && maybeNode.parentElement) {
114
- return maybeNode.parentElement as HTMLElement;
115
- }
116
- return null;
117
- }
118
-
119
106
  export function shouldIgnoreHistoryShortcut(target: EventTarget | null): boolean {
120
107
  return isTypingTarget(target);
121
108
  }
@@ -146,14 +133,30 @@ export type ElementMatchSelection = Pick<
146
133
  | "sourceFile"
147
134
  | "compositionSrc"
148
135
  | "isCompositionHost"
149
- >;
136
+ > &
137
+ Partial<Pick<DomEditSelection, "handle">>;
138
+
139
+ function matchesByClipId(
140
+ selection: ElementMatchSelection,
141
+ element: TimelineElement,
142
+ file: string,
143
+ value: string | undefined,
144
+ clipIdScope: string | undefined,
145
+ ) {
146
+ if (!clipIdScope || !selection.handle) return false;
147
+ if (element.domId || element.hfId || element.selector) return false;
148
+ return element.id === value && (element.sourceFile || clipIdScope) === file;
149
+ }
150
150
 
151
151
  function matchesByDomId(
152
152
  selection: ElementMatchSelection,
153
153
  element: TimelineElement,
154
154
  selectionSourceFile: string,
155
+ clipIdScope?: string,
155
156
  ): boolean {
156
157
  if (!selection.id) return false;
158
+ if (matchesByClipId(selection, element, selectionSourceFile, selection.id, clipIdScope))
159
+ return true;
157
160
  return (
158
161
  element.domId === selection.id && (element.sourceFile || "index.html") === selectionSourceFile
159
162
  );
@@ -163,8 +166,11 @@ function matchesByHfId(
163
166
  selection: ElementMatchSelection,
164
167
  element: TimelineElement,
165
168
  selectionSourceFile: string,
169
+ clipIdScope?: string,
166
170
  ): boolean {
167
171
  if (!selection.hfId) return false;
172
+ if (matchesByClipId(selection, element, selectionSourceFile, selection.hfId, clipIdScope))
173
+ return true;
168
174
  return (
169
175
  element.hfId === selection.hfId && (element.sourceFile || "index.html") === selectionSourceFile
170
176
  );
@@ -187,9 +193,11 @@ function matchesBySelector(selection: ElementMatchSelection, element: TimelineEl
187
193
  );
188
194
  }
189
195
 
196
+ /** `clipIdScope` matches opaque picks to clip-id-only rows, which have no patch target: select/seek only. */
190
197
  export function findMatchingTimelineElementId(
191
198
  selection: ElementMatchSelection,
192
199
  elements: TimelineElement[],
200
+ clipIdScope?: string,
193
201
  ): string | null {
194
202
  const selectionSourceFile = selection.sourceFile || "index.html";
195
203
  // Priority matters, not just "any of the three": a composition-host
@@ -204,7 +212,7 @@ export function findMatchingTimelineElementId(
204
212
  // first; only fall back to the coarser compositionSrc-only match when
205
213
  // none of them identifies a specific element.
206
214
  const byId = selection.id
207
- ? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile))
215
+ ? elements.find((el) => matchesByDomId(selection, el, selectionSourceFile, clipIdScope))
208
216
  : undefined;
209
217
  if (byId) return byId.key ?? byId.id;
210
218
 
@@ -212,7 +220,7 @@ export function findMatchingTimelineElementId(
212
220
  // whether it has a real DOM id — the only correlator for an element like
213
221
  // an ungroup child that has neither an authored id nor a selector.
214
222
  const byHfId = selection.hfId
215
- ? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile))
223
+ ? elements.find((el) => matchesByHfId(selection, el, selectionSourceFile, clipIdScope))
216
224
  : undefined;
217
225
  if (byHfId) return byHfId.key ?? byHfId.id;
218
226
 
@@ -280,9 +288,11 @@ export function resolveTimelineIdForSelection(
280
288
  selection: DomEditSelection,
281
289
  elements: TimelineElement[],
282
290
  activeCompPath: string | null,
291
+ byClipId = false,
283
292
  ): string | null {
293
+ const clipIdScope = byClipId ? activeCompPath || "index.html" : undefined;
284
294
  return (
285
- findMatchingTimelineElementId(selection, elements) ??
295
+ findMatchingTimelineElementId(selection, elements, clipIdScope) ??
286
296
  findTimelineIdByAncestor(
287
297
  selection.element,
288
298
  elements,