@hyperframes/studio 0.9.19 → 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-Dszy0WKm.js → hyperframes-player-ZQZslutT.js} +3 -3
  2. package/dist/assets/index-Bgfyny02.css +1 -0
  3. package/dist/assets/{index-CWYuXWlI.js → index-Bn5atbhb.js} +1 -1
  4. package/dist/assets/{index-BeR5xCi5.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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hyperframes/studio",
3
- "version": "0.9.19",
3
+ "version": "0.9.20",
4
4
  "description": "",
5
5
  "repository": {
6
6
  "type": "git",
@@ -60,12 +60,12 @@
60
60
  "dockview-react": "8.3.1",
61
61
  "gsap": "^3.13.0",
62
62
  "mediabunny": "^1.45.3",
63
- "@hyperframes/core": "0.9.19",
64
- "@hyperframes/player": "0.9.19",
65
- "@hyperframes/parsers": "0.9.19",
66
- "@hyperframes/sdk": "0.9.19",
67
- "@hyperframes/shader-transitions": "0.9.19",
68
- "@hyperframes/studio-server": "0.9.19"
63
+ "@hyperframes/core": "0.9.20",
64
+ "@hyperframes/player": "0.9.20",
65
+ "@hyperframes/parsers": "0.9.20",
66
+ "@hyperframes/shader-transitions": "0.9.20",
67
+ "@hyperframes/sdk": "0.9.20",
68
+ "@hyperframes/studio-server": "0.9.20"
69
69
  },
70
70
  "devDependencies": {
71
71
  "@tailwindcss/vite": "^4.3.3",
@@ -82,7 +82,7 @@
82
82
  "vite": "^6.4.2",
83
83
  "vitest": "^4.1.11",
84
84
  "zustand": "^5.0.0",
85
- "@hyperframes/producer": "0.9.19"
85
+ "@hyperframes/producer": "0.9.20"
86
86
  },
87
87
  "peerDependencies": {
88
88
  "react": "19",
@@ -7,10 +7,17 @@ import { Button, cn } from "./ui";
7
7
  // The desktop-app guide card under OpenInDesktopButton: Framey and three steps (download, install, open), all drawn
8
8
  // from one `Progress`.
9
9
 
10
+ export type DesktopCtaPlacement = "header" | "storyboard";
11
+
10
12
  export type DesktopRoute = {
11
13
  handoff: boolean;
12
14
  downloadUrl: string | null;
13
- context: { os: string; app_installed: boolean; download_available: boolean };
15
+ context: {
16
+ os: string;
17
+ app_installed: boolean;
18
+ download_available: boolean;
19
+ placement: DesktopCtaPlacement;
20
+ };
14
21
  };
15
22
 
16
23
  /** The OS for the download, and what "this …" calls the machine. */
@@ -145,10 +152,14 @@ export function labelOf(p: Progress): string {
145
152
  return isWaiting(p) ? "Finish installing" : "Install the desktop app";
146
153
  }
147
154
 
155
+ const boardFirst = (p: Progress) => p.route.context.placement === "storyboard";
156
+
148
157
  function subtitleOf(p: Progress): string {
149
158
  if (p.failed) return "Almost there: the last step needs another try.";
150
159
  if (!isInstalled(p))
151
- return "Watch it, click a frame, tell Framey what to change. Three steps, about two minutes.";
160
+ return boardFirst(p)
161
+ ? "Comment on a frame, draw on it, then press Build. Three steps, about two minutes."
162
+ : "Watch it, click a frame, tell Framey what to change. Three steps, about two minutes.";
152
163
  return p.route.handoff
153
164
  ? "Everything is ready. One press and you're in."
154
165
  : "Almost there: one last step.";
@@ -252,7 +263,11 @@ function OpenStep({ progress, projectDir, onOpen }: CardProps) {
252
263
  );
253
264
  return (
254
265
  <Step n={3} state={installed ? NOW : TODO} title={title}>
255
- <p className={NOTE}>Same project, same files, in the desktop app.</p>
266
+ <p className={NOTE}>
267
+ {boardFirst(progress)
268
+ ? "Same project, same files. It opens on this storyboard."
269
+ : "Same project, same files, in the desktop app."}
270
+ </p>
256
271
  <Button
257
272
  variant="primary"
258
273
  className="mt-2"
@@ -275,7 +290,9 @@ export function GuideCard(props: CardProps) {
275
290
  <FrameyGlyph size={46} mood={moodOf(progress)} />
276
291
  <div className="min-w-0">
277
292
  <p className="text-step-14 font-semibold text-balance text-text-0">
278
- Edit this video in the desktop app
293
+ {boardFirst(progress)
294
+ ? "Comment on this storyboard in the desktop app"
295
+ : "Edit this video in the desktop app"}
279
296
  </p>
280
297
  <p className={NOTE}>
281
298
  <Swap value={subtitle}>{subtitle}</Swap>
@@ -1,6 +1,7 @@
1
1
  import { memo, useCallback, type ReactNode } from "react";
2
2
  import { matchesKey } from "../player/components/studioShortcuts";
3
3
  import { PreviewPane } from "./nle/PreviewPane";
4
+ import { PreviewStage } from "./storyboard/PreviewStage";
4
5
  import { TimelinePane } from "./nle/TimelinePane";
5
6
  import { PreviewOverlays } from "./nle/PreviewOverlays";
6
7
  import { PreviewReadOnlyProvider } from "./editor/previewReadOnlyContext";
@@ -313,13 +314,15 @@ function EditorShellBody({
313
314
  <StudioAgentTools />
314
315
  <Dock.Root projectId={projectId}>
315
316
  <Dock.Panel id="preview">
316
- <div className="relative flex h-full w-full min-w-0 flex-col">
317
- <PreviewPane
318
- previewOverlay={previewOverlay}
319
- onSelectTimelineElement={onSelectTimelineElement}
320
- onPreviewBlockDrop={onPreviewBlockDrop}
321
- />
322
- </div>
317
+ <PreviewStage projectId={projectId}>
318
+ <div className="relative flex h-full w-full min-w-0 flex-col">
319
+ <PreviewPane
320
+ previewOverlay={previewOverlay}
321
+ onSelectTimelineElement={onSelectTimelineElement}
322
+ onPreviewBlockDrop={onPreviewBlockDrop}
323
+ />
324
+ </div>
325
+ </PreviewStage>
323
326
  </Dock.Panel>
324
327
  <Dock.Panel id="timeline">
325
328
  <TimelinePane
@@ -52,12 +52,12 @@ function serve(get: Response | null, post?: unknown) {
52
52
  );
53
53
  }
54
54
 
55
- async function mount(): Promise<HTMLElement> {
55
+ async function mount(placement?: "storyboard"): Promise<HTMLElement> {
56
56
  const host = document.createElement("div");
57
57
  document.body.append(host);
58
58
  const root = createRoot(host);
59
59
  mounted = { root, host };
60
- await act(async () => root.render(<OpenInDesktopButton />));
60
+ await act(async () => root.render(<OpenInDesktopButton placement={placement} />));
61
61
  return host;
62
62
  }
63
63
 
@@ -86,7 +86,7 @@ beforeEach(() => {
86
86
 
87
87
  const events = (name: string) =>
88
88
  track.mock.calls.filter(([event]) => event === name).map(([, props]) => props);
89
- const MAC = { os: "darwin", app_installed: true, download_available: true };
89
+ const MAC = { os: "darwin", app_installed: true, download_available: true, placement: "header" };
90
90
 
91
91
  afterEach(() => {
92
92
  vi.unstubAllGlobals();
@@ -140,7 +140,7 @@ const stepState = (n: number) =>
140
140
  guide()?.querySelector<HTMLElement>(`[data-step="${n}"]`)?.dataset.state ?? null;
141
141
  const cardButton = (text: string) =>
142
142
  [...(guide()?.querySelectorAll("button") ?? [])].find((b) => b.textContent === text) ?? null;
143
- const noApp = { os: "darwin", app_installed: false, download_available: true };
143
+ const noApp = { os: "darwin", app_installed: false, download_available: true, placement: "header" };
144
144
  const routeBody = (over: Record<string, unknown> = {}) => ({
145
145
  ...noApp,
146
146
  available: true,
@@ -244,7 +244,13 @@ it("finds the install only from the preview server, asking only while the card i
244
244
  (e) => (e as { step: string }).step === "install_detected",
245
245
  );
246
246
  expect(detected).toEqual([
247
- { step: "install_detected", os: "darwin", app_installed: true, download_available: true },
247
+ {
248
+ step: "install_detected",
249
+ os: "darwin",
250
+ app_installed: true,
251
+ download_available: true,
252
+ placement: "header",
253
+ },
248
254
  ]);
249
255
  const settled = gets;
250
256
  await act(async () => vi.advanceTimersByTime(10_000));
@@ -360,7 +366,7 @@ it("a hand-off that finds the app gone goes back to the download step", async ()
360
366
  });
361
367
 
362
368
  it("where the app is installed but cannot take a project (Linux), step 3 shows the folder to drop in", async () => {
363
- const linux = { os: "linux", app_installed: true, download_available: true };
369
+ const linux = { os: "linux", app_installed: true, download_available: true, placement: "header" };
364
370
  serve(
365
371
  Response.json({
366
372
  ...linux,
@@ -399,7 +405,13 @@ it("on Windows, step 1 names the Windows download and opens it tagged", async ()
399
405
  await act(async () => cardButton("Download for Windows")!.click());
400
406
  expect(opened).toEqual([tagged(`${DOWNLOAD}?os=windows`)]);
401
407
  expect(events("desktop_cta_eligibility")).toEqual([
402
- { eligibility: "download", os: "win32", app_installed: false, download_available: true },
408
+ {
409
+ eligibility: "download",
410
+ os: "win32",
411
+ app_installed: false,
412
+ download_available: true,
413
+ placement: "header",
414
+ },
403
415
  ]);
404
416
  });
405
417
 
@@ -436,11 +448,50 @@ it("counts where the button can show, the app here, and platforms with no app",
436
448
  os: "freebsd",
437
449
  app_installed: false,
438
450
  download_available: false,
451
+ placement: "header",
439
452
  },
440
453
  ]);
441
454
  expect(events("desktop_cta_impression")).toEqual([]);
442
455
  });
443
456
 
457
+ it("tells the storyboard's button from the header's in every funnel event", async () => {
458
+ serve(
459
+ Response.json({
460
+ ...MAC,
461
+ available: true,
462
+ handoff: true,
463
+ downloadUrl: DOWNLOAD,
464
+ installed: true,
465
+ }),
466
+ { opened: true },
467
+ );
468
+ await mount("storyboard");
469
+ const storyboardButton = document.querySelector<HTMLButtonElement>(
470
+ '[data-testid="storyboard-open-in-desktop"]',
471
+ );
472
+ expect(storyboardButton).not.toBeNull();
473
+ await act(async () => storyboardButton!.click());
474
+ const placements = track.mock.calls
475
+ .filter(([event]) => String(event).startsWith("desktop_cta"))
476
+ .map(([, props]) => (props as { placement?: string }).placement);
477
+ expect(placements.length).toBeGreaterThan(0);
478
+ expect(new Set(placements)).toEqual(new Set(["storyboard"]));
479
+ expect(postBodies).toEqual([{ cta: resolveTabId(), doc: "storyboard" }]);
480
+ });
481
+
482
+ it("asks the storyboard's visitor to comment on the board in the app, not to edit the video", async () => {
483
+ serve(Response.json({ ...MAC, available: true, handoff: false, downloadUrl: DOWNLOAD }));
484
+ await mount("storyboard");
485
+ await act(async () =>
486
+ document
487
+ .querySelector<HTMLButtonElement>('[data-testid="storyboard-open-in-desktop"]')!
488
+ .click(),
489
+ );
490
+ expect(guide()!.textContent).toContain("Comment on this storyboard in the desktop app");
491
+ expect(guide()!.textContent).toContain("then press Build");
492
+ expect(guide()!.textContent).not.toContain("Edit this video");
493
+ });
494
+
444
495
  it("records one impression, only once the button is on screen", async () => {
445
496
  serve(
446
497
  Response.json({
@@ -512,7 +563,12 @@ it("records a press the preview server never answered as failed", async () => {
512
563
  });
513
564
 
514
565
  it("records the download press as sent to the download, never as an install", async () => {
515
- const linux = { os: "linux", app_installed: false, download_available: true };
566
+ const linux = {
567
+ os: "linux",
568
+ app_installed: false,
569
+ download_available: true,
570
+ placement: "header",
571
+ };
516
572
  vi.stubGlobal("open", () => ({ opener: null }));
517
573
  serve(
518
574
  Response.json({
@@ -10,6 +10,7 @@ import {
10
10
  isWaiting,
11
11
  labelOf,
12
12
  moodOf,
13
+ type DesktopCtaPlacement,
13
14
  type DesktopRoute,
14
15
  type Progress,
15
16
  } from "./DesktopGuideCard";
@@ -47,7 +48,7 @@ const eligibilityOf = (route: DesktopRoute): Eligibility =>
47
48
  route.handoff ? "open_in_app" : route.downloadUrl ? "download" : "no_app_for_platform";
48
49
 
49
50
  /** The preview server's answer, or null when there is none (the desktop's own Studio, or no server). */
50
- async function readRoute(): Promise<DesktopRoute | null> {
51
+ async function readRoute(placement: DesktopCtaPlacement): Promise<DesktopRoute | null> {
51
52
  const res = await studioApiFetch(ROUTE);
52
53
  if (!res.ok) return null;
53
54
  const body = (await res.json()) as {
@@ -66,16 +67,17 @@ async function readRoute(): Promise<DesktopRoute | null> {
66
67
  os: typeof body.os === "string" ? body.os : "unknown",
67
68
  app_installed: body.installed === true,
68
69
  download_available: downloadUrl !== null,
70
+ placement,
69
71
  },
70
72
  };
71
73
  }
72
74
 
73
75
  /** Null hides the button: no route, or nothing here to open or download. `setRoute` takes a fresher answer. */
74
- function useDesktopRoute() {
76
+ function useDesktopRoute(placement: DesktopCtaPlacement) {
75
77
  const [route, setRoute] = useState<DesktopRoute | null>(null);
76
78
  useEffect(() => {
77
79
  let live = true;
78
- readRoute()
80
+ readRoute(placement)
79
81
  .then((answered) => {
80
82
  if (!live || !answered) return;
81
83
  trackStudioEvent("desktop_cta_eligibility", {
@@ -88,7 +90,7 @@ function useDesktopRoute() {
88
90
  return () => {
89
91
  live = false;
90
92
  };
91
- }, []);
93
+ }, [placement]);
92
94
  return [route, setRoute] as const;
93
95
  }
94
96
 
@@ -145,12 +147,16 @@ function useGaze(
145
147
  }
146
148
 
147
149
  /** While the card is open and the app is not here, ask the preview server again; stops on close or once found. */
148
- function useInstallWatch(watching: boolean, onAnswer: (route: DesktopRoute) => void): void {
150
+ function useInstallWatch(
151
+ watching: boolean,
152
+ placement: DesktopCtaPlacement,
153
+ onAnswer: (route: DesktopRoute) => void,
154
+ ): void {
149
155
  useEffect(() => {
150
156
  if (!watching) return;
151
157
  let live = true;
152
158
  const ask = () =>
153
- readRoute()
159
+ readRoute(placement)
154
160
  .then((answered) => live && answered && onAnswer(answered))
155
161
  .catch(() => {});
156
162
  void ask();
@@ -159,7 +165,7 @@ function useInstallWatch(watching: boolean, onAnswer: (route: DesktopRoute) => v
159
165
  live = false;
160
166
  clearInterval(timer);
161
167
  };
162
- }, [watching, onAnswer]);
168
+ }, [watching, placement, onAnswer]);
163
169
  }
164
170
 
165
171
  const LOOK =
@@ -167,7 +173,11 @@ const LOOK =
167
173
  const LOOK_FAILED = "border-danger/45 bg-danger/8 text-danger-ink enabled:hover:bg-danger/14";
168
174
 
169
175
  /** The guide's state and the two actions that move it: the download and the hand-off. */
170
- function useGuide(route: DesktopRoute | null, setRoute: (route: DesktopRoute) => void) {
176
+ function useGuide(
177
+ route: DesktopRoute | null,
178
+ setRoute: (route: DesktopRoute) => void,
179
+ placement: DesktopCtaPlacement,
180
+ ) {
171
181
  const { showToast } = useStudioShellContext();
172
182
  const [cardOpen, setCardOpen] = useState(false);
173
183
  const [opening, setOpening] = useState(false);
@@ -190,7 +200,7 @@ function useGuide(route: DesktopRoute | null, setRoute: (route: DesktopRoute) =>
190
200
  },
191
201
  [setRoute],
192
202
  );
193
- useInstallWatch(cardOpen && route !== null && !installed, onAnswer);
203
+ useInstallWatch(cardOpen && route !== null && !installed, placement, onAnswer);
194
204
 
195
205
  useEffect(() => {
196
206
  if (!downloaded || installed) return;
@@ -256,7 +266,10 @@ function useGuide(route: DesktopRoute | null, setRoute: (route: DesktopRoute) =>
256
266
  const res = await studioApiFetch(ROUTE, {
257
267
  method: "POST",
258
268
  headers: { "content-type": "application/json" },
259
- body: JSON.stringify({ cta: resolveTabId() }),
269
+ body: JSON.stringify({
270
+ cta: resolveTabId(),
271
+ ...(placement === "storyboard" ? { doc: "storyboard" } : {}),
272
+ }),
260
273
  });
261
274
  await landed((await res.json()) as OpenResult);
262
275
  } catch {
@@ -271,14 +284,18 @@ function useGuide(route: DesktopRoute | null, setRoute: (route: DesktopRoute) =>
271
284
  return { progress, cardOpen, showCard, download, open };
272
285
  }
273
286
 
274
- export function OpenInDesktopButton() {
287
+ export function OpenInDesktopButton({
288
+ placement = "header",
289
+ }: {
290
+ placement?: DesktopCtaPlacement;
291
+ } = {}) {
275
292
  const projectDir = useFileManagerContextOptional()?.projectDir ?? null;
276
- const [route, setRoute] = useDesktopRoute();
293
+ const [route, setRoute] = useDesktopRoute(placement);
277
294
  const trigger = useRef<HTMLButtonElement>(null);
278
295
  const eye = useRef<SVGGElement>(null);
279
296
  useGaze(trigger, eye);
280
297
  useImpression(trigger, route);
281
- const guide = useGuide(route, setRoute);
298
+ const guide = useGuide(route, setRoute, placement);
282
299
  if (!guide) return null;
283
300
  const { progress, cardOpen, showCard, download, open } = guide;
284
301
  const label = labelOf(progress);
@@ -300,7 +317,7 @@ export function OpenInDesktopButton() {
300
317
  <Button
301
318
  ref={trigger}
302
319
  variant="ghost"
303
- data-testid="header-open-in-desktop"
320
+ data-testid={`${placement}-open-in-desktop`}
304
321
  data-opening={progress.opening || undefined}
305
322
  aria-busy={progress.opening || waiting || undefined}
306
323
  title={
@@ -0,0 +1,177 @@
1
+ // @vitest-environment happy-dom
2
+ import React, { act, type ComponentProps } from "react";
3
+ import { createRoot, type Root } from "react-dom/client";
4
+ import { afterEach, describe, expect, it, vi } from "vitest";
5
+ import { DomEditGestureReadout } from "./DomEditGestureReadout";
6
+ import { createGestureReadout, updateGestureReadout } from "./domEditGestureReadoutState";
7
+
8
+ const frames = vi.hoisted(() => ({ update: () => {} }));
9
+ vi.mock("./overlayFrameLoop", () => ({
10
+ subscribeOverlayFrame: (update: () => void) => {
11
+ frames.update = update;
12
+ return () => {
13
+ frames.update = () => {};
14
+ };
15
+ },
16
+ }));
17
+ // React needs its runtime test flag, which the global typings do not declare.
18
+ (globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
19
+ let root: Root | undefined;
20
+ afterEach(() => {
21
+ act(() => root?.unmount());
22
+ document.body.replaceChildren();
23
+ vi.clearAllMocks();
24
+ });
25
+
26
+ function mount(kind: "drag" | "resize" | "rotate") {
27
+ const host = document.createElement("div");
28
+ const overlay = document.createElement("div");
29
+ const iframe = document.createElement("iframe");
30
+ document.body.append(host, overlay, iframe);
31
+ const doc = iframe.contentDocument;
32
+ if (!doc) throw new Error("Missing preview document");
33
+ const composition = doc.createElement("div");
34
+ composition.setAttribute("data-composition-id", "scene");
35
+ composition.setAttribute("data-width", "1000");
36
+ composition.setAttribute("data-height", "800");
37
+ const element = doc.createElement("div");
38
+ composition.append(element);
39
+ doc.body.append(composition);
40
+ let x = 70.25;
41
+ let y = 40.75;
42
+ const width = 100;
43
+ const height = 60;
44
+ overlay.getBoundingClientRect = () => new DOMRect(20, 30, 500, 400);
45
+ iframe.getBoundingClientRect = () => new DOMRect(20, 30, 500, 400);
46
+ composition.getBoundingClientRect = () => new DOMRect(0, 0, 1000, 800);
47
+ element.getBoundingClientRect = () => new DOMRect(x, y, width, height);
48
+ Object.defineProperties(element, {
49
+ offsetWidth: { value: width },
50
+ offsetHeight: { value: height },
51
+ });
52
+ const gestureRef: ComponentProps<typeof DomEditGestureReadout>["gestureRef"] = {
53
+ current: {
54
+ travelled: true,
55
+ readout: createGestureReadout(overlay, iframe, {
56
+ left: x / 2,
57
+ top: y / 2,
58
+ width: width / 2,
59
+ height: height / 2,
60
+ editScaleX: 0.5,
61
+ editScaleY: 0.5,
62
+ }),
63
+ },
64
+ };
65
+ const update = (text?: string) =>
66
+ updateGestureReadout(
67
+ gestureRef.current?.readout,
68
+ {
69
+ left: x / 2,
70
+ top: y / 2,
71
+ width: width / 2,
72
+ height: height / 2,
73
+ editScaleX: 0.5,
74
+ editScaleY: 0.5,
75
+ },
76
+ text,
77
+ );
78
+ update(kind === "resize" ? "100 × 60" : kind === "rotate" ? "0°" : undefined);
79
+ root = createRoot(host);
80
+ act(() =>
81
+ root?.render(
82
+ <DomEditGestureReadout
83
+ gestureRef={gestureRef}
84
+ overlayRef={{ current: overlay }}
85
+ iframeRef={{ current: iframe }}
86
+ />,
87
+ ),
88
+ );
89
+ const label = host.querySelector<HTMLDivElement>("[data-dom-edit-gesture-readout]");
90
+ if (!label) throw new Error("Missing readout");
91
+ Object.defineProperties(label, { offsetWidth: { value: 120 }, offsetHeight: { value: 24 } });
92
+ const draw = () => frames.update();
93
+ const end = () => {
94
+ gestureRef.current = null;
95
+ draw();
96
+ };
97
+ return {
98
+ measurements: [overlay, iframe, composition, element].map((node) =>
99
+ vi.spyOn(node, "getBoundingClientRect"),
100
+ ),
101
+ element,
102
+ gestureRef,
103
+ update,
104
+ doc,
105
+ label,
106
+ draw,
107
+ end,
108
+ move: (nextX: number, nextY: number) => {
109
+ x = nextX;
110
+ y = nextY;
111
+ update();
112
+ },
113
+ };
114
+ }
115
+
116
+ describe("gesture readout", () => {
117
+ it("adds no layout reads while drawing and stays hidden on a plain press", () => {
118
+ const view = mount("drag");
119
+ const measure = vi.spyOn(Element.prototype, "getBoundingClientRect");
120
+ if (!view.gestureRef.current) throw new Error("Missing gesture");
121
+ view.gestureRef.current.travelled = false;
122
+ view.draw();
123
+ expect(view.label.style.display).toBe("none");
124
+ view.gestureRef.current.travelled = true;
125
+ view.move(120, 70);
126
+ view.draw();
127
+ view.draw();
128
+ expect(view.label.textContent).toBe("Canvas X 120 · Y 70");
129
+ expect(measure).not.toHaveBeenCalled();
130
+ for (const measurement of view.measurements) expect(measurement).not.toHaveBeenCalled();
131
+ measure.mockRestore();
132
+ for (const measurement of view.measurements) measurement.mockRestore();
133
+ });
134
+ it("shows rounded composition coordinates during a move, accounting for preview zoom", () => {
135
+ const view = mount("drag");
136
+ view.draw();
137
+ expect(view.label.textContent).toBe("Canvas X 70 · Y 41");
138
+ view.move(120.25, 70.75);
139
+ view.draw();
140
+ expect(view.label.textContent).toBe("Canvas X 120 · Y 71");
141
+ expect(view.doc.querySelector("[data-dom-edit-gesture-readout]")).toBeNull();
142
+ view.end();
143
+ expect(view.label.style.display).toBe("none");
144
+ });
145
+ it("shows the actual size draft during resize and hides on release", () => {
146
+ const view = mount("resize");
147
+ view.draw();
148
+ expect(view.label.textContent).toBe("100 × 60");
149
+ view.update("144 × 87");
150
+ view.draw();
151
+ expect(view.label.textContent).toBe("144 × 87");
152
+ view.end();
153
+ expect(view.label.style.display).toBe("none");
154
+ });
155
+ it("reads the live angle during rotation and hides on cancellation", () => {
156
+ const view = mount("rotate");
157
+ view.update("32°");
158
+ view.draw();
159
+ expect(view.label.textContent).toBe("32°");
160
+ view.update("-46°");
161
+ view.draw();
162
+ expect(view.label.textContent).toBe("-46°");
163
+ view.end();
164
+ expect(view.label.style.display).toBe("none");
165
+ });
166
+ it("clamps the label inside the visible overlay at either edge", () => {
167
+ const view = mount("drag");
168
+ view.move(900, -100);
169
+ view.draw();
170
+ expect(view.label.style.left).toBe("496px");
171
+ expect(view.label.style.top).toBe("4px");
172
+ view.move(-900, 900);
173
+ view.draw();
174
+ expect(view.label.style.left).toBe("4px");
175
+ expect(view.label.style.top).toBe("396px");
176
+ });
177
+ });
@@ -0,0 +1,58 @@
1
+ import { useRef, type RefObject } from "react";
2
+ import { useMountEffect } from "../../hooks/useMountEffect";
3
+ import type { GestureState } from "./domEditOverlayGestures";
4
+ import { subscribeOverlayFrame } from "./overlayFrameLoop";
5
+
6
+ type ReadoutGesture = Pick<GestureState, "readout" | "travelled">;
7
+
8
+ interface DomEditGestureReadoutProps {
9
+ gestureRef: RefObject<ReadoutGesture | null>;
10
+ overlayRef: RefObject<HTMLDivElement | null>;
11
+ iframeRef: RefObject<HTMLIFrameElement | null>;
12
+ }
13
+
14
+ function positionGestureReadout(label: HTMLDivElement, gesture: ReadoutGesture): void {
15
+ const readout = gesture.readout;
16
+ if (!readout) return;
17
+ const bounds = readout.basis.overlayRect;
18
+ const rect = readout.rect;
19
+ const minX = Math.max(0, -bounds.left) + 4;
20
+ const minY = Math.max(0, -bounds.top) + 4;
21
+ const maxX = Math.min(bounds.width, readout.viewportWidth - bounds.left) - 4;
22
+ const maxY = Math.min(bounds.height, readout.viewportHeight - bounds.top) - 4;
23
+ const x = Math.max(minX, Math.min(maxX, rect.left + rect.width + 8));
24
+ const y = Math.max(minY, Math.min(maxY, rect.top - 8));
25
+ label.style.left = `${x}px`;
26
+ label.style.top = `${y}px`;
27
+ label.style.maxWidth = `${Math.max(0, maxX - minX)}px`;
28
+ // CSS resolves the label's own size without a synchronous layout read after its text changes.
29
+ label.style.transform = `translate(max(-100%, ${minX - x}px), max(-100%, ${minY - y}px))`;
30
+ }
31
+
32
+ export function DomEditGestureReadout({ gestureRef }: DomEditGestureReadoutProps) {
33
+ const labelRef = useRef<HTMLDivElement | null>(null);
34
+ useMountEffect(() =>
35
+ subscribeOverlayFrame(() => {
36
+ const label = labelRef.current;
37
+ if (!label) return;
38
+ const gesture = gestureRef.current;
39
+ const text = gesture?.travelled && gesture.readout?.text;
40
+ if (!gesture || !text) {
41
+ label.style.display = "none";
42
+ return;
43
+ }
44
+ if (label.textContent !== text) label.textContent = text;
45
+ label.style.display = "block";
46
+ positionGestureReadout(label, gesture);
47
+ }),
48
+ );
49
+ return (
50
+ <div
51
+ ref={labelRef}
52
+ aria-hidden="true"
53
+ data-dom-edit-gesture-readout="true"
54
+ className="pointer-events-none absolute z-50 overflow-hidden rounded bg-studio-surface px-2 py-1 font-mono text-xs whitespace-nowrap text-studio-text shadow-md"
55
+ style={{ display: "none" }}
56
+ />
57
+ );
58
+ }
@@ -40,6 +40,7 @@ import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
40
40
  import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
41
41
  import { logSelect } from "../../utils/selectDebug";
42
42
  import { useOffCanvasIndicators } from "./useOffCanvasIndicators";
43
+ import { DomEditGestureReadout } from "./DomEditGestureReadout";
43
44
 
44
45
  // Re-exports for external consumers — preserving existing import paths.
45
46
  export {
@@ -542,6 +543,11 @@ export const DomEditOverlay = memo(function DomEditOverlay({
542
543
  onBoxClick={handleBoxClick}
543
544
  />
544
545
  )}
546
+ <DomEditGestureReadout
547
+ gestureRef={gestureRef}
548
+ overlayRef={overlayRef}
549
+ iframeRef={iframeRef}
550
+ />
545
551
  <ChildRectOutlines rects={compRect.width > 0 ? childRects : []} />
546
552
  {/* Mounted here rather than with the selection chrome: the chrome does
547
553
  not render for every selection, and the toolbar belongs to the