@hyperframes/studio 0.9.18 → 0.9.20

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 (52) hide show
  1. package/dist/assets/{hyperframes-player-pLs7eSzg.js → hyperframes-player-ZQZslutT.js} +3 -3
  2. package/dist/assets/index-Bgfyny02.css +1 -0
  3. package/dist/assets/{index-DZ7OLB7p.js → index-Bn5atbhb.js} +1 -1
  4. package/dist/assets/{index-D_iVCwL3.js → index-Bz2pYyGM.js} +196 -196
  5. package/dist/index.d.ts +1 -4
  6. package/dist/index.html +2 -2
  7. package/dist/index.js +6571 -5519
  8. package/dist/styles.css +1 -1
  9. package/package.json +8 -8
  10. package/src/components/DesktopGuideCard.tsx +21 -4
  11. package/src/components/EditorShell.tsx +10 -7
  12. package/src/components/OpenInDesktopButton.dom.test.tsx +64 -8
  13. package/src/components/OpenInDesktopButton.tsx +31 -14
  14. package/src/components/editor/DomEditGestureReadout.test.tsx +177 -0
  15. package/src/components/editor/DomEditGestureReadout.tsx +58 -0
  16. package/src/components/editor/DomEditOverlay.tsx +6 -0
  17. package/src/components/editor/domEditGestureReadoutState.ts +55 -0
  18. package/src/components/editor/domEditOverlayGestures.ts +12 -0
  19. package/src/components/editor/domEditOverlayStartGesture.ts +2 -0
  20. package/src/components/editor/useDomEditOverlayGestures.ts +12 -13
  21. package/src/components/nle/NLEPreview.test.ts +72 -0
  22. package/src/components/nle/NLEPreview.tsx +8 -9
  23. package/src/components/nle/PreviewZoomOverlay.tsx +155 -9
  24. package/src/components/nle/previewZoom.test.ts +98 -0
  25. package/src/components/nle/previewZoom.ts +65 -1
  26. package/src/components/panels/MotionBlurPanel.test.tsx +4 -0
  27. package/src/components/panels/MotionBlurPanel.tsx +1 -1
  28. package/src/components/storyboard/ApproveBoardButton.dom.test.tsx +48 -0
  29. package/src/components/storyboard/ApproveBoardButton.tsx +33 -0
  30. package/src/components/storyboard/PreviewStage.dom.test.tsx +114 -0
  31. package/src/components/storyboard/PreviewStage.player.dom.test.tsx +72 -0
  32. package/src/components/storyboard/PreviewStage.tsx +93 -0
  33. package/src/components/storyboard/StoryboardBoardView.tsx +322 -0
  34. package/src/components/storyboard/storyboardBoard.test.ts +183 -0
  35. package/src/components/storyboard/storyboardBoard.ts +148 -0
  36. package/src/components/storyboard/useStoryboardBoard.ts +99 -0
  37. package/src/hooks/elementPickerHoverLabel.browser.test.ts +85 -0
  38. package/src/hooks/elementPickerHoverLabel.test.ts +106 -0
  39. package/src/hooks/elementPickerHoverLabel.ts +173 -0
  40. package/src/hooks/fileChangeFanout.test.ts +20 -0
  41. package/src/hooks/fileChangeFanout.ts +13 -0
  42. package/src/hooks/useElementPicker.test.ts +254 -3
  43. package/src/hooks/useElementPicker.ts +237 -48
  44. package/src/hooks/useExternalFileChangeCoordinator.ts +6 -1
  45. package/src/player/components/timelineProviderStateBuilders.test.ts +3 -6
  46. package/src/player/components/timelineProviderStateBuilders.ts +1 -2
  47. package/src/player/components/timelineShellMeta.tsx +0 -2
  48. package/src/player/components/useTimelineProviderState.tsx +1 -2
  49. package/src/player/components/useTimelineShiftModifier.test.tsx +40 -0
  50. package/src/player/components/useTimelineShiftModifier.ts +7 -7
  51. package/src/styles/theme.css +2 -0
  52. package/dist/assets/index-CNZk2EFC.css +0 -1
@@ -3,7 +3,7 @@ import React, { act, useState } from "react";
3
3
  import { createRoot, type Root } from "react-dom/client";
4
4
  import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
5
5
  import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
6
- import { afterEach, describe, expect, it } from "vitest";
6
+ import { afterEach, describe, expect, it, vi } from "vitest";
7
7
  import { useElementPicker } from "./useElementPicker";
8
8
 
9
9
  // As the host leaves it on disk: hf-ids pinned, no element ids.
@@ -17,6 +17,7 @@ afterEach(() => {
17
17
  act(() => root?.unmount());
18
18
  root = null;
19
19
  document.body.innerHTML = "";
20
+ vi.restoreAllMocks();
20
21
  });
21
22
 
22
23
  // The runtime's element-picked message, posted by `from`.
@@ -35,6 +36,33 @@ const picked = (from: Window | null, selector: string) =>
35
36
  );
36
37
  });
37
38
 
39
+ const pickerMessage = (from: Window | null, data: Record<string, unknown>) =>
40
+ act(() => {
41
+ window.dispatchEvent(
42
+ new MessageEvent("message", {
43
+ source: from,
44
+ data: {
45
+ source: "hf-preview",
46
+ ...data,
47
+ ...runtimeProtocolMetadata(30),
48
+ },
49
+ }),
50
+ );
51
+ });
52
+
53
+ const hoverInfo = (overrides: Record<string, unknown> = {}) => ({
54
+ id: null,
55
+ className: "title",
56
+ tagName: "div",
57
+ selector: "div.title",
58
+ label: "Title",
59
+ boundingBox: { x: 20, y: 30, width: 100, height: 40 },
60
+ textContent: "Title",
61
+ src: null,
62
+ dataAttributes: {},
63
+ ...overrides,
64
+ });
65
+
38
66
  // The preview page: the saved markup plus what the runtime adds to it.
39
67
  function mountPreview(mounted = ""): HTMLIFrameElement {
40
68
  const iframe = document.createElement("iframe");
@@ -80,12 +108,150 @@ function mountPicker(
80
108
  picked(iframe.contentWindow, selector);
81
109
  const picker = () => api as ReturnType<typeof useElementPicker>;
82
110
  return {
111
+ iframe,
83
112
  picker,
84
113
  synced,
85
114
  setHostFiles: (next: Record<string, string>) => act(() => setHostFiles(next)),
86
115
  };
87
116
  }
88
117
 
118
+ describe("pick mode cancellation and hover feedback", () => {
119
+ it("cancels pick mode when Escape is pressed with Studio focus", () => {
120
+ const { picker } = mountPicker({ "index.html": SAVED });
121
+ act(() => picker().enablePick());
122
+
123
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
124
+
125
+ expect(picker().isPickMode).toBe(false);
126
+ });
127
+
128
+ it("shows the hovered element identifier beside the preview", () => {
129
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
130
+ act(() => picker().enablePick());
131
+
132
+ pickerMessage(iframe.contentWindow, {
133
+ type: "element-hovered",
134
+ elementInfo: hoverInfo(),
135
+ });
136
+
137
+ expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe("div.title");
138
+ });
139
+
140
+ it("restores the element selected before pick mode began when cancelled", () => {
141
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
142
+ expect(picker().pickedElement?.selector).toBe("h1");
143
+ act(() => picker().enablePick());
144
+ pickerMessage(iframe.contentWindow, {
145
+ type: "element-pick-candidates",
146
+ candidates: [{ selector: "div.candidate", tagName: "div" }],
147
+ selectedIndex: 0,
148
+ point: { x: 1, y: 1 },
149
+ });
150
+ expect(picker().pickedElement?.selector).toBe("div.candidate");
151
+
152
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
153
+
154
+ expect(picker().pickedElement?.selector).toBe("h1");
155
+ });
156
+
157
+ it("restores the previous selection when Escape comes from the preview runtime", () => {
158
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
159
+ act(() => picker().enablePick());
160
+ pickerMessage(iframe.contentWindow, {
161
+ type: "element-pick-candidates",
162
+ candidates: [{ selector: "div.candidate", tagName: "div" }],
163
+ selectedIndex: 0,
164
+ point: { x: 1, y: 1 },
165
+ });
166
+
167
+ pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
168
+
169
+ expect(picker().isPickMode).toBe(false);
170
+ expect(picker().pickedElement?.selector).toBe("h1");
171
+ });
172
+
173
+ it("ignores Escape while inactive and where an editor owns it", () => {
174
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
175
+ const frameWindow = iframe.contentWindow;
176
+ if (!frameWindow) throw new Error("preview iframe has no content window");
177
+ const postMessage = vi.spyOn(frameWindow, "postMessage");
178
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
179
+ expect(postMessage).not.toHaveBeenCalled();
180
+
181
+ const editor = document.body.appendChild(document.createElement("textarea"));
182
+ act(() => picker().enablePick());
183
+ act(() => editor.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true })));
184
+
185
+ expect(picker().isPickMode).toBe(true);
186
+ });
187
+
188
+ it("survives repeated enable and cancellation cycles", () => {
189
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
190
+ for (let cycle = 0; cycle < 3; cycle += 1) {
191
+ act(() => picker().enablePick());
192
+ expect(picker().isPickMode).toBe(true);
193
+ pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
194
+ expect(picker().isPickMode).toBe(false);
195
+ expect(picker().pickedElement?.selector).toBe("h1");
196
+ }
197
+ });
198
+
199
+ it("removes its Studio key listener and disables the runtime on unmount", () => {
200
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
201
+ const frameWindow = iframe.contentWindow;
202
+ if (!frameWindow) throw new Error("preview iframe has no content window");
203
+ const removeEventListener = vi.spyOn(window, "removeEventListener");
204
+ const postMessage = vi.spyOn(frameWindow, "postMessage");
205
+ act(() => picker().enablePick());
206
+
207
+ act(() => root?.unmount());
208
+ root = null;
209
+
210
+ expect(removeEventListener.mock.calls.some(([type]) => type === "keydown")).toBe(true);
211
+ expect(
212
+ postMessage.mock.calls.some(
213
+ ([message]) =>
214
+ typeof message === "object" &&
215
+ message !== null &&
216
+ "action" in message &&
217
+ message.action === "disable-pick-mode",
218
+ ),
219
+ ).toBe(true);
220
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
221
+ });
222
+
223
+ it("commits a normal pick and clears hover state", () => {
224
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
225
+ act(() => picker().enablePick());
226
+ pickerMessage(iframe.contentWindow, {
227
+ type: "element-hovered",
228
+ elementInfo: hoverInfo(),
229
+ });
230
+
231
+ picked(iframe.contentWindow, "div.final");
232
+
233
+ expect(picker().isPickMode).toBe(false);
234
+ expect(picker().pickedElement?.selector).toBe("div.final");
235
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
236
+ });
237
+
238
+ it("clears the label after cancellation", () => {
239
+ const { iframe, picker } = mountPicker({ "index.html": SAVED });
240
+ act(() => picker().enablePick());
241
+ pickerMessage(iframe.contentWindow, {
242
+ type: "element-hovered",
243
+ elementInfo: hoverInfo({ id: "hero-title", tagName: "h1" }),
244
+ });
245
+ expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe(
246
+ "h1#hero-title",
247
+ );
248
+
249
+ pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
250
+
251
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
252
+ });
253
+ });
254
+
89
255
  describe("an edit to a picked element without an id", () => {
90
256
  it("writes only that edit into the saved file", () => {
91
257
  const { picker, synced } = mountPicker({ "index.html": SAVED });
@@ -185,8 +351,9 @@ describe("a pick across a reload that swaps the preview frame", () => {
185
351
  return null;
186
352
  }
187
353
  root = createRoot(document.createElement("div"));
188
- act(() => root?.render(React.createElement(Harness)));
189
- return { live, ref, picker: () => api as ReturnType<typeof useElementPicker> };
354
+ const rerender = () => act(() => root?.render(React.createElement(Harness)));
355
+ rerender();
356
+ return { live, ref, rerender, picker: () => api as ReturnType<typeof useElementPicker> };
190
357
  }
191
358
 
192
359
  it("keeps a pick posted by the frame it was made in after a new frame took its place", () => {
@@ -212,6 +379,90 @@ describe("a pick across a reload that swaps the preview frame", () => {
212
379
  expect(picker().pickedElement?.selector).toBe("h1");
213
380
  });
214
381
 
382
+ it("drops hover messages from a primary iframe after it is replaced", () => {
383
+ const { live, ref, rerender, picker } = mountSwapping();
384
+ const liveWindow = live.contentWindow;
385
+ if (!liveWindow) throw new Error("preview iframe has no content window");
386
+ const oldPostMessage = vi.spyOn(liveWindow, "postMessage");
387
+ act(() => picker().enablePick());
388
+ pickerMessage(liveWindow, {
389
+ type: "element-hovered",
390
+ elementInfo: hoverInfo(),
391
+ });
392
+ expect(document.querySelector("[data-hf-picker-hover-label]")).not.toBeNull();
393
+
394
+ const replacement = mountPreview();
395
+ const replacementWindow = replacement.contentWindow;
396
+ if (!replacementWindow) throw new Error("replacement iframe has no content window");
397
+ const replacementPostMessage = vi.spyOn(replacementWindow, "postMessage");
398
+ ref.current = replacement;
399
+ rerender();
400
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
401
+ expect(
402
+ oldPostMessage.mock.calls.some(
403
+ ([message]) =>
404
+ typeof message === "object" &&
405
+ message !== null &&
406
+ "action" in message &&
407
+ message.action === "disable-pick-mode",
408
+ ),
409
+ ).toBe(true);
410
+ expect(
411
+ replacementPostMessage.mock.calls.some(
412
+ ([message]) =>
413
+ typeof message === "object" &&
414
+ message !== null &&
415
+ "action" in message &&
416
+ message.action === "enable-pick-mode",
417
+ ),
418
+ ).toBe(true);
419
+ pickerMessage(liveWindow, {
420
+ type: "element-hovered",
421
+ elementInfo: hoverInfo({ id: "stale" }),
422
+ });
423
+
424
+ expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
425
+ });
426
+
427
+ it("moves active pick mode to a zoomed iframe without losing the original selection", () => {
428
+ const { live, picker } = mountSwapping();
429
+ picked(live.contentWindow, "h1");
430
+ const zoom = mountPreview();
431
+ const zoomWindow = zoom.contentWindow;
432
+ if (!zoomWindow) throw new Error("zoom iframe has no content window");
433
+ const zoomPostMessage = vi.spyOn(zoomWindow, "postMessage");
434
+ act(() => picker().enablePick());
435
+
436
+ act(() => picker().setActiveIframe(zoom));
437
+ pickerMessage(zoomWindow, {
438
+ type: "element-hovered",
439
+ elementInfo: hoverInfo({ id: "zoomed" }),
440
+ });
441
+ pickerMessage(zoomWindow, {
442
+ type: "element-pick-candidates",
443
+ candidates: [{ selector: "div.zoomed", tagName: "div" }],
444
+ selectedIndex: 0,
445
+ point: { x: 1, y: 1 },
446
+ });
447
+
448
+ expect(picker().activeIframeRef.current).toBe(zoom);
449
+ expect(
450
+ zoomPostMessage.mock.calls.some(
451
+ ([message]) =>
452
+ typeof message === "object" &&
453
+ message !== null &&
454
+ "action" in message &&
455
+ message.action === "enable-pick-mode",
456
+ ),
457
+ ).toBe(true);
458
+ expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe("div#zoomed");
459
+
460
+ act(() => picker().setActiveIframe(null));
461
+ act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
462
+ expect(picker().pickedElement?.selector).toBe("h1");
463
+ expect(picker().activeIframeRef.current).toBe(live);
464
+ });
465
+
215
466
  it("still ignores a frame it never showed", () => {
216
467
  const { picker } = mountSwapping();
217
468
  const stranger = mountPreview();
@@ -1,4 +1,4 @@
1
- import { useState, useCallback, useRef } from "react";
1
+ import { useState, useCallback, useEffect, useRef } from "react";
2
2
  import { useMountEffect } from "./useMountEffect";
3
3
  import {
4
4
  resolveSourceFile,
@@ -13,6 +13,11 @@ import {
13
13
  } from "../player/lib/runtimeProtocol";
14
14
  import { compositionPathOfPreviewUrl } from "../player/components/CompositionThumbnail";
15
15
  import { getSourceFileForElement } from "../components/editor/domEditingDom";
16
+ import {
17
+ createElementPickerHoverLabel,
18
+ type ElementPickerHoverInfo,
19
+ type ElementPickerHoverLabel,
20
+ } from "./elementPickerHoverLabel";
16
21
 
17
22
  export interface PickedElement {
18
23
  id: string | null;
@@ -51,54 +56,142 @@ interface PickerOptions {
51
56
  onSyncFiles?: (files: Record<string, string>) => void;
52
57
  }
53
58
 
54
- /**
55
- * Hook for element picking via the HyperFrame runtime's picker API.
56
- * Communicates with the iframe via postMessage.
57
- */
58
- export function useElementPicker(
59
- iframeRef: React.RefObject<HTMLIFrameElement | null>,
60
- options?: PickerOptions,
61
- ): UseElementPickerReturn {
62
- const [isPickMode, setIsPickMode] = useState(false);
63
- const [pickedElement, setPickedElement] = useState<PickedElement | null>(null);
59
+ interface UseElementPickerSessionReturn extends Omit<
60
+ UseElementPickerReturn,
61
+ "setStyle" | "setDataAttr" | "setTextContent"
62
+ > {
63
+ setPickedElement: React.Dispatch<React.SetStateAction<PickedElement | null>>;
64
+ getActiveIframe: () => HTMLIFrameElement | null;
65
+ }
64
66
 
65
- // Secondary/override iframe ref — set when a zoomed frame is active.
66
- // When set, all postMessage sends and DOM reads go to this ref instead.
67
- const activeOverrideRef = useRef<HTMLIFrameElement | null>(null);
67
+ function usePickerHoverLabel(): {
68
+ clearHover: () => void;
69
+ disposeHover: () => void;
70
+ showHover: (info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => void;
71
+ } {
72
+ const hoverLabelRef = useRef<ElementPickerHoverLabel | null>(null);
73
+ const clearHover = useCallback(() => hoverLabelRef.current?.clear(), []);
74
+ const disposeHover = useCallback(() => hoverLabelRef.current?.dispose(), []);
75
+ const showHover = useCallback((info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => {
76
+ hoverLabelRef.current ??= createElementPickerHoverLabel();
77
+ hoverLabelRef.current.show(info, iframe);
78
+ }, []);
79
+ return { clearHover, disposeHover, showHover };
80
+ }
68
81
 
69
- const getActiveIframe = useCallback((): HTMLIFrameElement | null => {
70
- return activeOverrideRef.current ?? iframeRef.current;
71
- }, [iframeRef]);
82
+ function useActivePickerIframe(
83
+ iframeRef: React.RefObject<HTMLIFrameElement | null>,
84
+ isPickModeRef: React.RefObject<boolean>,
85
+ clearHover: () => void,
86
+ ): {
87
+ activeIframeRef: React.RefObject<HTMLIFrameElement | null>;
88
+ getActiveIframe: () => HTMLIFrameElement | null;
89
+ setActiveIframe: (el: HTMLIFrameElement | null) => void;
90
+ } {
91
+ const activeOverrideRef = useRef<HTMLIFrameElement | null>(null);
92
+ const activeIframeRef = useRef<HTMLIFrameElement | null>(null);
93
+ const lastRenderedActiveIframeRef = useRef<HTMLIFrameElement | null>(null);
94
+ const getActiveIframe = useCallback(
95
+ () => activeOverrideRef.current ?? iframeRef.current,
96
+ [iframeRef],
97
+ );
98
+ const setActiveIframe = useCallback(
99
+ (el: HTMLIFrameElement | null) => {
100
+ const previous = activeOverrideRef.current ?? iframeRef.current;
101
+ const next = el ?? iframeRef.current;
102
+ if (previous === next) return;
103
+ clearHover();
104
+ if (isPickModeRef.current) postPickerControl(previous, "disable-pick-mode");
105
+ activeOverrideRef.current = el;
106
+ activeIframeRef.current = next;
107
+ lastRenderedActiveIframeRef.current = next;
108
+ if (isPickModeRef.current) postPickerControl(next, "enable-pick-mode");
109
+ },
110
+ [clearHover, iframeRef, isPickModeRef],
111
+ );
112
+ const renderedActiveIframe = getActiveIframe();
113
+ useEffect(() => {
114
+ const previous = lastRenderedActiveIframeRef.current;
115
+ if (previous !== renderedActiveIframe) {
116
+ clearHover();
117
+ if (isPickModeRef.current) {
118
+ postPickerControl(previous, "disable-pick-mode");
119
+ postPickerControl(renderedActiveIframe, "enable-pick-mode");
120
+ }
121
+ }
122
+ lastRenderedActiveIframeRef.current = renderedActiveIframe;
123
+ }, [clearHover, isPickModeRef, renderedActiveIframe]);
124
+ activeIframeRef.current = getActiveIframe();
125
+ return { activeIframeRef, getActiveIframe, setActiveIframe };
126
+ }
72
127
 
73
- // Exposed so the host page can wire the focused view's iframe into the picker
74
- const setActiveIframe = useCallback((el: HTMLIFrameElement | null) => {
75
- activeOverrideRef.current = el;
76
- }, []);
128
+ function useElementPickerSession(
129
+ iframeRef: React.RefObject<HTMLIFrameElement | null>,
130
+ ): UseElementPickerSessionReturn {
131
+ const [isPickMode, setIsPickMode] = useState(false);
132
+ const [pickedElement, setPickedElement] = useState<PickedElement | null>(null);
133
+ const isPickModeRef = useRef(false);
134
+ const pickedElementRef = useRef<PickedElement | null>(null);
135
+ pickedElementRef.current = pickedElement;
136
+ const pickStartSelectionRef = useRef<PickedElement | null | undefined>(undefined);
137
+ const { clearHover, disposeHover, showHover } = usePickerHoverLabel();
138
+ const { activeIframeRef, getActiveIframe, setActiveIframe } = useActivePickerIframe(
139
+ iframeRef,
140
+ isPickModeRef,
141
+ clearHover,
142
+ );
77
143
 
78
144
  const enablePick = useCallback(() => {
79
- try {
80
- postRuntimeControlMessage(getActiveIframe()?.contentWindow, "enable-pick-mode");
81
- setIsPickMode(true);
82
- } catch {
83
- /* cross-origin */
84
- }
145
+ if (isPickModeRef.current || !postPickerControl(getActiveIframe(), "enable-pick-mode")) return;
146
+ pickStartSelectionRef.current = pickedElementRef.current;
147
+ isPickModeRef.current = true;
148
+ setIsPickMode(true);
85
149
  }, [getActiveIframe]);
86
150
 
87
- const disablePick = useCallback(() => {
88
- try {
89
- postRuntimeControlMessage(getActiveIframe()?.contentWindow, "disable-pick-mode");
90
- } catch {
91
- /* cross-origin */
92
- }
93
- setIsPickMode(false);
94
- }, [getActiveIframe]);
151
+ const cancelPick = useCallback(
152
+ (notifyRuntime: boolean) => {
153
+ if (notifyRuntime) {
154
+ postPickerControl(getActiveIframe(), "disable-pick-mode");
155
+ }
156
+ const selection = pickStartSelectionRef.current;
157
+ pickStartSelectionRef.current = undefined;
158
+ if (selection !== undefined) {
159
+ pickedElementRef.current = selection;
160
+ setPickedElement(selection);
161
+ }
162
+ isPickModeRef.current = false;
163
+ clearHover();
164
+ setIsPickMode(false);
165
+ },
166
+ [clearHover, getActiveIframe],
167
+ );
168
+
169
+ const disablePick = useCallback(() => cancelPick(true), [cancelPick]);
95
170
 
96
171
  const clearPick = useCallback(() => {
172
+ pickedElementRef.current = null;
97
173
  setPickedElement(null);
98
174
  }, []);
99
175
 
100
176
  const windowsThatWerePrimary = useRef(new WeakSet<MessageEventSource>());
101
177
 
178
+ useEffect(() => {
179
+ if (!isPickMode) return;
180
+ const handleKeyDown = (event: KeyboardEvent) => {
181
+ if (
182
+ event.key !== "Escape" ||
183
+ event.defaultPrevented ||
184
+ event.isComposing ||
185
+ elementOwnsEscape(event.target)
186
+ )
187
+ return;
188
+ event.preventDefault();
189
+ disablePick();
190
+ };
191
+ window.addEventListener("keydown", handleKeyDown);
192
+ return () => window.removeEventListener("keydown", handleKeyDown);
193
+ }, [disablePick, isPickMode]);
194
+
102
195
  // Listen for picker messages from the iframe
103
196
  useMountEffect(() => {
104
197
  // One guard per message field, then one branch per message type.
@@ -119,31 +212,81 @@ export function useElementPicker(
119
212
  )
120
213
  return;
121
214
 
215
+ if (data.type === "element-hovered") {
216
+ if (e.source !== activeIframe.contentWindow || !isPickModeRef.current) return;
217
+ const info = toHoverInfo(data.elementInfo);
218
+ if (info) showHover(info, activeIframe);
219
+ return;
220
+ }
221
+
122
222
  if (data.type === "element-picked" && data.elementInfo) {
123
- setPickedElement(toPickedElement(data.elementInfo, activeIframe));
223
+ const next = toPickedElement(data.elementInfo, activeIframe);
224
+ pickedElementRef.current = next;
225
+ setPickedElement(next);
226
+ pickStartSelectionRef.current = undefined;
227
+ isPickModeRef.current = false;
228
+ clearHover();
124
229
  setIsPickMode(false);
125
230
  } else if (data.type === "element-pick-candidates") {
126
231
  // Multiple candidates at click point — pick the first one
127
232
  const el = data.candidates?.[data.selectedIndex ?? 0];
128
- if (el) setPickedElement(toPickedElement(el, activeIframe));
233
+ if (el) {
234
+ const next = toPickedElement(el, activeIframe);
235
+ pickedElementRef.current = next;
236
+ setPickedElement(next);
237
+ }
129
238
  }
130
239
 
131
240
  if (data.type === "pick-mode-cancelled") {
132
- setIsPickMode(false);
241
+ cancelPick(false);
133
242
  }
134
243
  };
135
244
 
136
245
  window.addEventListener("message", handleMessage);
137
- return () => window.removeEventListener("message", handleMessage);
246
+ return () => {
247
+ window.removeEventListener("message", handleMessage);
248
+ if (isPickModeRef.current) {
249
+ postPickerControl(getActiveIframe(), "disable-pick-mode");
250
+ }
251
+ disposeHover();
252
+ };
138
253
  });
139
254
 
140
- // Ref for options to avoid stale closures in debounced callback
255
+ return {
256
+ isPickMode,
257
+ pickedElement,
258
+ setPickedElement,
259
+ getActiveIframe,
260
+ enablePick,
261
+ disablePick,
262
+ clearPick,
263
+ setActiveIframe,
264
+ activeIframeRef,
265
+ };
266
+ }
267
+
268
+ /** Element picking through the HyperFrame runtime's postMessage API. */
269
+ export function useElementPicker(
270
+ iframeRef: React.RefObject<HTMLIFrameElement | null>,
271
+ options?: PickerOptions,
272
+ ): UseElementPickerReturn {
273
+ const {
274
+ isPickMode,
275
+ pickedElement,
276
+ setPickedElement,
277
+ getActiveIframe,
278
+ enablePick,
279
+ disablePick,
280
+ clearPick,
281
+ setActiveIframe,
282
+ activeIframeRef,
283
+ } = useElementPickerSession(iframeRef);
284
+
141
285
  const optionsRef = useRef(options);
142
286
  optionsRef.current = options;
143
287
  const pendingWritesRef = useRef(new Map<string, PendingWrite>());
144
288
  settlePendingWrites(pendingWritesRef.current, options?.workspaceFiles);
145
289
 
146
- // Sync immediately (not debounced) — save on every change for reliability
147
290
  const syncToSource = useCallback(
148
291
  (picked: PickedElement, live: HTMLElement, iframe: HTMLIFrameElement, op: PatchOperation) => {
149
292
  const opts = optionsRef.current;
@@ -191,7 +334,7 @@ export function useElementPicker(
191
334
  /* cross-origin */
192
335
  }
193
336
  },
194
- [pickedElement, getActiveIframe, syncToSource],
337
+ [pickedElement, getActiveIframe, setPickedElement, syncToSource],
195
338
  );
196
339
 
197
340
  const setDataAttr = useCallback(
@@ -221,7 +364,7 @@ export function useElementPicker(
221
364
  /* cross-origin */
222
365
  }
223
366
  },
224
- [pickedElement, getActiveIframe, syncToSource],
367
+ [pickedElement, getActiveIframe, setPickedElement, syncToSource],
225
368
  );
226
369
 
227
370
  const setTextContent = useCallback(
@@ -244,13 +387,9 @@ export function useElementPicker(
244
387
  /* cross-origin */
245
388
  }
246
389
  },
247
- [pickedElement, getActiveIframe, syncToSource],
390
+ [pickedElement, getActiveIframe, setPickedElement, syncToSource],
248
391
  );
249
392
 
250
- // Ref-like object that always points to the active iframe (override or primary)
251
- const activeIframeRef = useRef<HTMLIFrameElement | null>(null);
252
- activeIframeRef.current = getActiveIframe();
253
-
254
393
  return {
255
394
  isPickMode,
256
395
  pickedElement,
@@ -266,6 +405,56 @@ export function useElementPicker(
266
405
  };
267
406
  }
268
407
 
408
+ function elementOwnsEscape(target: EventTarget | null): boolean {
409
+ if (!(target instanceof Element)) return false;
410
+ return Boolean(
411
+ target.closest(
412
+ 'dialog,[role="dialog"],[aria-modal="true"],input,textarea,select,[contenteditable="true"],[contenteditable=""],[data-studio-escape-owner]',
413
+ ),
414
+ );
415
+ }
416
+
417
+ function postPickerControl(
418
+ iframe: HTMLIFrameElement | null | undefined,
419
+ action: "enable-pick-mode" | "disable-pick-mode",
420
+ ): boolean {
421
+ try {
422
+ postRuntimeControlMessage(iframe?.contentWindow, action);
423
+ return true;
424
+ } catch {
425
+ return false;
426
+ }
427
+ }
428
+
429
+ function isUnknownRecord(value: unknown): value is Record<string, unknown> {
430
+ return typeof value === "object" && value !== null;
431
+ }
432
+
433
+ function isFiniteNumber(value: unknown): value is number {
434
+ return typeof value === "number" && Number.isFinite(value);
435
+ }
436
+
437
+ function isOptionalString(value: unknown): value is string | null | undefined {
438
+ return value === null || value === undefined || typeof value === "string";
439
+ }
440
+
441
+ function toHoverInfo(value: unknown): ElementPickerHoverInfo | null {
442
+ if (!isUnknownRecord(value)) return null;
443
+ const info = value;
444
+ const box = info.boundingBox;
445
+ if (typeof info.tagName !== "string" || !isUnknownRecord(box)) return null;
446
+ const coordinates = [box.x, box.y, box.width, box.height];
447
+ if (!coordinates.every(isFiniteNumber)) return null;
448
+ const [x, y, width, height] = coordinates as [number, number, number, number];
449
+ if (!isOptionalString(info.id) || !isOptionalString(info.className)) return null;
450
+ return {
451
+ id: typeof info.id === "string" ? info.id : null,
452
+ className: typeof info.className === "string" ? info.className : null,
453
+ tagName: info.tagName,
454
+ boundingBox: { x, y, width, height },
455
+ };
456
+ }
457
+
269
458
  type PickedElementInfo = Partial<Omit<PickedElement, "computedStyles">>;
270
459
 
271
460
  // workspaceFiles lags this hook's own writes until the host rerenders.
@@ -1,3 +1,4 @@
1
+ import { announceExternalFileChange } from "./fileChangeFanout";
1
2
  import { useCallback, useEffect, useRef, useState, type MutableRefObject } from "react";
2
3
  import {
3
4
  mergeFileChangePayloads,
@@ -477,7 +478,11 @@ export function useExternalFileChangeCoordinator({
477
478
  processChangeRef.current = processChange;
478
479
  useEffect(() => {
479
480
  // One decoder for all three transports; the rungs only choose the channel.
480
- const handler = (delivery?: unknown) => processChangeRef.current(decodeFileChange(delivery));
481
+ const handler = (delivery?: unknown) => {
482
+ const payload = decodeFileChange(delivery);
483
+ announceExternalFileChange(payload);
484
+ processChangeRef.current(payload);
485
+ };
481
486
  const adapter = testHotAdapter();
482
487
  if (adapter) {
483
488
  adapter.on("hf:file-change", handler);