@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
@@ -0,0 +1,55 @@
1
+ import { computeOverlayRootScale, type OverlayRootScale } from "./domEditOverlayBasis";
2
+ import type { OverlayRect } from "./domEditOverlayGeometry";
3
+
4
+ export interface GestureReadoutState {
5
+ basis: OverlayRootScale;
6
+ viewportWidth: number;
7
+ viewportHeight: number;
8
+ text: string;
9
+ rect: OverlayRect;
10
+ }
11
+
12
+ export function createGestureReadout(
13
+ overlay: HTMLDivElement | null,
14
+ iframe: HTMLIFrameElement | null,
15
+ rect: OverlayRect,
16
+ ): GestureReadoutState | undefined {
17
+ const basis =
18
+ overlay && iframe && computeOverlayRootScale(overlay, iframe, iframe.contentDocument);
19
+ if (!basis || basis.rootScaleX <= 0 || basis.rootScaleY <= 0) return undefined;
20
+ return {
21
+ basis,
22
+ viewportWidth: window.innerWidth,
23
+ viewportHeight: window.innerHeight,
24
+ text: "",
25
+ rect,
26
+ };
27
+ }
28
+
29
+ export function updateGestureReadout(
30
+ readout: GestureReadoutState | undefined,
31
+ rect: OverlayRect,
32
+ text?: string,
33
+ ): void {
34
+ if (!readout) return;
35
+ const { basis } = readout;
36
+ const x = (rect.left - (basis.iframeRect.left - basis.overlayRect.left)) / basis.rootScaleX;
37
+ const y = (rect.top - (basis.iframeRect.top - basis.overlayRect.top)) / basis.rootScaleY;
38
+ readout.text = text ?? `Canvas X ${Math.round(x)} · Y ${Math.round(y)}`;
39
+ readout.rect = rect;
40
+ }
41
+
42
+ export function updateGestureReadoutAngle(
43
+ readout: GestureReadoutState | undefined,
44
+ angle: number,
45
+ ): void {
46
+ if (readout) updateGestureReadout(readout, readout.rect, `${Math.round(angle)}°`);
47
+ }
48
+
49
+ export function updateGestureReadoutSize(
50
+ readout: GestureReadoutState | undefined,
51
+ rect: OverlayRect,
52
+ size: { width: number; height: number },
53
+ ): void {
54
+ updateGestureReadout(readout, rect, `${Math.round(size.width)} × ${Math.round(size.height)}`);
55
+ }
@@ -1,3 +1,4 @@
1
+ import type { GestureReadoutState } from "./domEditGestureReadoutState";
1
2
  import type { RefObject } from "react";
2
3
  import type { DomEditSelection } from "./domEditing";
3
4
  import type {
@@ -47,6 +48,7 @@ const ROTATION_SNAP_DEGREES = 15;
47
48
  export const ROTATED_SNAP_BYPASS_DEGREES = 0.5;
48
49
 
49
50
  export interface GestureState {
51
+ readout?: GestureReadoutState;
50
52
  kind: GestureKind;
51
53
  mode: "path-offset" | "box-size" | "rotation";
52
54
  selection: DomEditSelection;
@@ -311,3 +313,13 @@ export type UseDomEditOverlayGesturesOptions = {
311
313
  onCanvasMouseDown: (e: React.MouseEvent<HTMLDivElement>, o?: PreviewMouseDownOptions) => void;
312
314
  snapGuidesRef: RefObject<SnapGuidesState | null>;
313
315
  };
316
+
317
+ export function isDomEditGestureTap(
318
+ g: { startX: number; startY: number; travelled?: boolean },
319
+ e: React.PointerEvent,
320
+ ) {
321
+ return (
322
+ !g.travelled &&
323
+ Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < BLOCKED_MOVE_THRESHOLD_PX
324
+ );
325
+ }
@@ -1,3 +1,4 @@
1
+ import { createGestureReadout } from "./domEditGestureReadoutState";
1
2
  /**
2
3
  * Gesture-begin functions: startGroupDrag and startGesture.
3
4
  * These are pure "start a new gesture" operations — no draft rect updates.
@@ -278,6 +279,7 @@ export function startGesture(
278
279
  opts.rafPausedRef.current = true;
279
280
  opts.gestureRef.current = {
280
281
  kind,
282
+ readout: createGestureReadout(overlayEl, iframe, rect),
281
283
  mode,
282
284
  selection: sel,
283
285
  pointerId: e.pointerId,
@@ -1,3 +1,4 @@
1
+ import * as readout from "./domEditGestureReadoutState";
1
2
  import { createPreviewGestureStarts } from "./previewGestureStarts";
2
3
  import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
3
4
  // fallow-ignore-file code-duplication
@@ -40,6 +41,7 @@ import {
40
41
  hasDomEditRotationChanged,
41
42
  lockDragToDominantAxis,
42
43
  movesGesture,
44
+ isDomEditGestureTap,
43
45
  resolveDomEditRotationGesture,
44
46
  } from "./domEditOverlayGestures";
45
47
  import { resolveCenterResizeSize } from "./domEditResizeLocal";
@@ -58,13 +60,6 @@ import { createGroupDragMover } from "./groupDragMove";
58
60
  import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
59
61
  import { beginStudioPendingEdit } from "../../utils/studioPendingEdits";
60
62
 
61
- function isTap(g: { startX: number; startY: number; travelled?: boolean }, e: React.PointerEvent) {
62
- return (
63
- !g.travelled &&
64
- Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < BLOCKED_MOVE_THRESHOLD_PX
65
- );
66
- }
67
-
68
63
  function logGestureCommitFailure(message: string, error: unknown): void {
69
64
  if (error instanceof DomEditSaveQueueOpenError) return;
70
65
  console.error(message, error);
@@ -147,13 +142,13 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
147
142
  }
148
143
 
149
144
  if (groupG) {
150
- if (!isTap(groupG, e)) groupG.travelled = true;
145
+ if (!isDomEditGestureTap(groupG, e)) groupG.travelled = true;
151
146
  moveGroupDrag(groupG, e);
152
147
  return;
153
148
  }
154
149
 
155
150
  if (!g || !sel) return;
156
- if (!isTap(g, e)) g.travelled = true;
151
+ if (!isDomEditGestureTap(g, e)) g.travelled = true;
157
152
  let dx = e.clientX - g.startX;
158
153
  let dy = e.clientY - g.startY;
159
154
 
@@ -170,6 +165,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
170
165
  actualAngle: g.actualRotation,
171
166
  snap: e.shiftKey,
172
167
  });
168
+ readout.updateGestureReadoutAngle(g.readout, rotated.angle);
173
169
  applyRotationDraft(sel.element, rotated.angle, g.plainRotation);
174
170
  return;
175
171
  }
@@ -234,7 +230,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
234
230
 
235
231
  const nextBoxLeft = g.originLeft + dx;
236
232
  const nextBoxTop = g.originTop + dy;
237
- setDraftOverlayRect({
233
+ const draftRect = {
238
234
  left: nextBoxLeft,
239
235
  top: nextBoxTop,
240
236
  width: g.originWidth,
@@ -242,7 +238,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
242
238
  editScaleX: g.editScaleX,
243
239
  editScaleY: g.editScaleY,
244
240
  angle: g.actualRotation,
245
- });
241
+ };
242
+ readout.updateGestureReadout(g.readout, draftRect);
243
+ setDraftOverlayRect(draftRect);
246
244
  if (box) {
247
245
  box.style.left = `${nextBoxLeft}px`;
248
246
  box.style.top = `${nextBoxTop}px`;
@@ -286,6 +284,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
286
284
  box.style.width = `${draftRect.width}px`;
287
285
  box.style.height = `${draftRect.height}px`;
288
286
  }
287
+ readout.updateGestureReadoutSize(g.readout, draftRect, writtenSize);
289
288
  setDraftOverlayRect(draftRect);
290
289
  }
291
290
  };
@@ -316,7 +315,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
316
315
  const rawDy = e.clientY - groupG.startY;
317
316
  // Consume the release click so it cannot deselect the moved group.
318
317
  opts.suppressNextBoxClickRef.current = true;
319
- if (isTap(groupG, e)) {
318
+ if (isDomEditGestureTap(groupG, e)) {
320
319
  restoreGroupPathOffsets(groupG);
321
320
  if (e.shiftKey) {
322
321
  opts.onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
@@ -378,7 +377,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
378
377
  if (!g || !sel) return;
379
378
  const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
380
379
 
381
- if (g.kind === "drag" && isTap(g, e)) {
380
+ if (g.kind === "drag" && isDomEditGestureTap(g, e)) {
382
381
  if (g.pathOffsetMember) restoreManualOffsetDragMembers([g.pathOffsetMember]);
383
382
  if (box) {
384
383
  box.style.left = `${g.originLeft}px`;
@@ -390,6 +390,78 @@ describe("NLEPreview", () => {
390
390
  view.cleanup();
391
391
  });
392
392
 
393
+ /** Opens the zoom readout's input, types `text` into it and presses `key`. */
394
+ function typeZoom(view: ReturnType<typeof renderPreview>, text: string, key: string) {
395
+ act(() => {
396
+ view.host.querySelector<HTMLButtonElement>('[data-testid="preview-zoom-readout"]')!.click();
397
+ });
398
+ const input = view.host.querySelector<HTMLInputElement>(
399
+ '[data-testid="preview-zoom-input"]',
400
+ )!;
401
+ act(() => {
402
+ Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")!.set!.call(
403
+ input,
404
+ text,
405
+ );
406
+ input.dispatchEvent(new Event("input", { bubbles: true }));
407
+ });
408
+ act(() => {
409
+ input.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true }));
410
+ });
411
+ act(() => vi.advanceTimersByTime(300));
412
+ }
413
+ const pixelGrid = (view: ReturnType<typeof renderPreview>) =>
414
+ view.host.querySelector<HTMLElement>('[data-testid="preview-pixel-grid"]');
415
+
416
+ it("applies a typed zoom on Enter, clamped to the zoom limit, and closes the input", () => {
417
+ const view = renderPreview();
418
+ pinchIn(view, 10);
419
+ typeZoom(view, "350%", "Enter");
420
+ expect(view.stage.style.transform).toContain("scale(3.5)");
421
+ expect(chip(view)?.textContent).toBe("Zoomed 350%·Fit");
422
+
423
+ typeZoom(view, "99999", "Enter");
424
+ expect(view.stage.style.transform).toContain("scale(16)");
425
+ expect(view.host.querySelector('[data-testid="preview-zoom-input"]')).toBeNull();
426
+ view.cleanup();
427
+ });
428
+
429
+ it("keeps the zoom when the typed value is cancelled with Esc or is not a number", () => {
430
+ const view = renderPreview();
431
+ pinchIn(view, 10);
432
+ const before = view.stage.style.transform;
433
+
434
+ typeZoom(view, "500", "Escape");
435
+ expect(view.stage.style.transform).toBe(before);
436
+ expect(view.host.querySelector('[data-testid="preview-zoom-input"]')).toBeNull();
437
+
438
+ typeZoom(view, "abc", "Enter");
439
+ expect(view.stage.style.transform).toBe(before);
440
+ view.cleanup();
441
+ });
442
+
443
+ it("draws a one-pixel grid above 800% over the stage, one cell per composition pixel", () => {
444
+ const view = renderPreview(undefined, { compositionSizeHint: { width: 1920, height: 1080 } });
445
+ pinchIn(view, 10);
446
+ typeZoom(view, "800", "Enter");
447
+ expect(pixelGrid(view)?.hidden).toBe(true);
448
+
449
+ typeZoom(view, "1000", "Enter");
450
+ const grid = pixelGrid(view)!;
451
+ expect(grid.hidden).toBe(false);
452
+ expect(view.stage.contains(grid)).toBe(false);
453
+ const stageWidth = parseFloat(view.stage.style.width);
454
+ expect(parseFloat(grid.style.width)).toBeCloseTo(stageWidth * 10, 2);
455
+ expect(parseFloat(grid.style.backgroundSize)).toBeCloseTo((stageWidth * 10) / 1920, 3);
456
+
457
+ act(() => {
458
+ view.host.querySelector<HTMLButtonElement>('[data-testid="preview-zoom-fit"]')!.click();
459
+ });
460
+ act(() => vi.advanceTimersByTime(300));
461
+ expect(pixelGrid(view)).toBeNull();
462
+ view.cleanup();
463
+ });
464
+
393
465
  it("keeps a zoom only while the project is open: nothing is saved, and another project opens at Fit", () => {
394
466
  const view = renderPreview();
395
467
  pinchIn(view, 10);
@@ -27,7 +27,7 @@ import {
27
27
  type PreviewZoomState,
28
28
  } from "./previewZoom";
29
29
  import { RULER_GUTTER_PX, usePreviewGuidesStore } from "../editor/previewGuidesStore";
30
- import { PreviewZoomOverlay, usePreviewNavigator } from "./PreviewZoomOverlay";
30
+ import { PreviewZoomOverlay, usePreviewZoomOverlay } from "./PreviewZoomOverlay";
31
31
  import {
32
32
  PREVIEW_STAGE_INSET_PX,
33
33
  resolvePreviewStageSize,
@@ -192,11 +192,13 @@ export const NLEPreview = memo(function NLEPreview({
192
192
  const stageSizeRef = useRef(stageSize);
193
193
  stageSizeRef.current = stageSize;
194
194
 
195
- const { draw: drawNavigator, setRegion: setNavigatorRegion } = usePreviewNavigator(
195
+ const zoomOverlay = usePreviewZoomOverlay(
196
196
  viewportRef,
197
197
  stageSize,
198
198
  zoomRef,
199
+ compositionSize?.width ?? hintWidth,
199
200
  );
201
+ const { draw: drawZoomOverlay } = zoomOverlay;
200
202
  const writeTransform = useCallback(
201
203
  (state: PreviewZoomState) => {
202
204
  const stage = stageRef.current;
@@ -205,9 +207,9 @@ export const NLEPreview = memo(function NLEPreview({
205
207
  const px = toDomPrecision(state.panX);
206
208
  const py = toDomPrecision(state.panY);
207
209
  stage.style.transform = `translate3d(${px}px, ${py}px, 0) scale(${s})`;
208
- drawNavigator(state);
210
+ drawZoomOverlay(state);
209
211
  },
210
- [drawNavigator],
212
+ [drawZoomOverlay],
211
213
  );
212
214
 
213
215
  const zoomProjectRef = useRef(projectId);
@@ -551,11 +553,8 @@ export const NLEPreview = memo(function NLEPreview({
551
553
  <PreviewZoomOverlay
552
554
  zoom={settledZoom}
553
555
  stageSize={stageSize}
554
- onFit={() => {
555
- applyZoom(DEFAULT_PREVIEW_ZOOM);
556
- viewportRef.current?.focus();
557
- }}
558
- navigatorRegionRef={setNavigatorRegion}
556
+ onZoom={applyZoom}
557
+ controls={zoomOverlay}
559
558
  />
560
559
  </div>
561
560
  </div>
@@ -1,7 +1,11 @@
1
- import { useCallback, useEffect, useRef, type RefObject } from "react";
1
+ import { useCallback, useEffect, useRef, useState, type RefObject } from "react";
2
2
  import {
3
+ DEFAULT_PREVIEW_ZOOM,
3
4
  isFitZoom,
4
5
  isPreviewAtFit,
6
+ parsePreviewZoomInput,
7
+ resolvePreviewPixelGrid,
8
+ resolvePreviewTypedZoom,
5
9
  resolvePreviewVisibleRegion,
6
10
  toDomPrecision,
7
11
  type PreviewZoomState,
@@ -21,7 +25,7 @@ function navigatorFrameSize(stage: { width: number; height: number }) {
21
25
  }
22
26
 
23
27
  /** `draw` moves the navigator's highlight without a render, so it can follow every transform write. */
24
- export function usePreviewNavigator(
28
+ function usePreviewNavigator(
25
29
  viewportRef: RefObject<HTMLDivElement | null>,
26
30
  stageSize: { width: number; height: number },
27
31
  zoomRef: RefObject<PreviewZoomState>,
@@ -59,34 +63,176 @@ export function usePreviewNavigator(
59
63
  return { draw, setRegion };
60
64
  }
61
65
 
66
+ function ZoomPercentInput({
67
+ zoomPercent,
68
+ onSubmit,
69
+ onDone,
70
+ }: {
71
+ zoomPercent: number;
72
+ onSubmit: (zoomPercent: number) => void;
73
+ onDone: () => void;
74
+ }) {
75
+ const [text, setText] = useState(() => String(Math.round(zoomPercent)));
76
+ return (
77
+ <input
78
+ autoFocus
79
+ onFocus={(event) => event.currentTarget.select()}
80
+ value={text}
81
+ onChange={(event) => setText(event.currentTarget.value)}
82
+ onKeyDown={(event) => {
83
+ if (event.key === "Enter") {
84
+ const next = parsePreviewZoomInput(text);
85
+ if (next !== null) onSubmit(next);
86
+ onDone();
87
+ } else if (event.key === "Escape") {
88
+ onDone();
89
+ }
90
+ }}
91
+ onBlur={onDone}
92
+ inputMode="decimal"
93
+ aria-label="Zoom percentage"
94
+ className="w-12 rounded bg-white/10 px-1 py-0.5 text-xs tabular-nums text-white outline-hidden focus:ring-1 focus:ring-studio-accent"
95
+ data-testid="preview-zoom-input"
96
+ />
97
+ );
98
+ }
99
+
100
+ function usePreviewPixelGrid(
101
+ viewportRef: RefObject<HTMLDivElement | null>,
102
+ stageSize: { width: number; height: number },
103
+ compositionWidth: number | undefined,
104
+ zoomRef: RefObject<PreviewZoomState>,
105
+ ) {
106
+ const gridRef = useRef<HTMLDivElement | null>(null);
107
+ const layoutRef = useRef({ stageSize, compositionWidth });
108
+ layoutRef.current = { stageSize, compositionWidth };
109
+ const draw = useCallback(
110
+ (state: PreviewZoomState) => {
111
+ const grid = gridRef.current;
112
+ if (!grid) return;
113
+ const rect = viewportRef.current?.getBoundingClientRect();
114
+ const { stageSize: stage, compositionWidth: width } = layoutRef.current;
115
+ const box = rect && width ? resolvePreviewPixelGrid({ state, rect, stage, width }) : null;
116
+ grid.hidden = !box;
117
+ if (!box) return;
118
+ grid.style.left = `${box.left}px`;
119
+ grid.style.top = `${box.top}px`;
120
+ grid.style.width = `${box.width}px`;
121
+ grid.style.height = `${box.height}px`;
122
+ grid.style.backgroundSize = `${box.cellPx}px ${box.cellPx}px`;
123
+ },
124
+ [viewportRef],
125
+ );
126
+ const setGrid = useCallback(
127
+ (node: HTMLDivElement | null) => {
128
+ gridRef.current = node;
129
+ draw(zoomRef.current);
130
+ },
131
+ [draw, zoomRef],
132
+ );
133
+ useEffect(() => draw(zoomRef.current), [stageSize, compositionWidth, draw, zoomRef]);
134
+ return { draw, setGrid };
135
+ }
136
+
137
+ export type PreviewZoomOverlayControls = ReturnType<typeof usePreviewZoomOverlay>;
138
+
139
+ export function usePreviewZoomOverlay(
140
+ viewportRef: RefObject<HTMLDivElement | null>,
141
+ stageSize: { width: number; height: number },
142
+ zoomRef: RefObject<PreviewZoomState>,
143
+ compositionWidth: number | undefined,
144
+ ) {
145
+ const { draw: drawNavigator, setRegion } = usePreviewNavigator(viewportRef, stageSize, zoomRef);
146
+ const { draw: drawGrid, setGrid } = usePreviewPixelGrid(
147
+ viewportRef,
148
+ stageSize,
149
+ compositionWidth,
150
+ zoomRef,
151
+ );
152
+ const draw = useCallback(
153
+ (state: PreviewZoomState) => {
154
+ drawNavigator(state);
155
+ drawGrid(state);
156
+ },
157
+ [drawNavigator, drawGrid],
158
+ );
159
+ return { viewportRef, draw, setRegion, setGrid };
160
+ }
161
+
62
162
  export function PreviewZoomOverlay({
63
163
  zoom,
64
164
  stageSize,
65
- onFit,
66
- navigatorRegionRef,
165
+ onZoom,
166
+ controls,
67
167
  }: {
68
168
  zoom: PreviewZoomState;
69
169
  stageSize: { width: number; height: number };
70
- onFit: () => void;
71
- navigatorRegionRef: (node: HTMLDivElement | null) => void;
170
+ onZoom: (next: PreviewZoomState) => void;
171
+ controls: PreviewZoomOverlayControls;
72
172
  }) {
173
+ const [editing, setEditing] = useState(false);
73
174
  if (isPreviewAtFit(zoom)) return null;
175
+ const { viewportRef } = controls;
176
+ const zoomTo = (zoomPercent: number) => {
177
+ const rect = viewportRef.current?.getBoundingClientRect();
178
+ onZoom(
179
+ resolvePreviewTypedZoom({
180
+ state: zoom,
181
+ zoomPercent,
182
+ viewportWidth: rect?.width ?? stageSize.width,
183
+ viewportHeight: rect?.height ?? stageSize.height,
184
+ contentWidth: stageSize.width,
185
+ contentHeight: stageSize.height,
186
+ }),
187
+ );
188
+ viewportRef.current?.focus();
189
+ };
74
190
  return (
75
191
  <>
192
+ <div
193
+ ref={controls.setGrid}
194
+ hidden
195
+ aria-hidden="true"
196
+ className="pointer-events-none absolute z-10"
197
+ style={{
198
+ backgroundImage:
199
+ "linear-gradient(to right, var(--color-pixel-grid) 1px, transparent 1px), linear-gradient(to bottom, var(--color-pixel-grid) 1px, transparent 1px)",
200
+ }}
201
+ data-testid="preview-pixel-grid"
202
+ />
76
203
  <div
77
204
  className="absolute top-3 left-1/2 -translate-x-1/2 z-50 flex items-center gap-1.5 rounded-md py-1 pl-2.5 pr-1 text-xs text-white/80 bg-black/60 backdrop-blur-xs"
78
205
  data-testid="preview-zoom-chip"
79
206
  // The pane clears the timeline selection on a pointerdown outside the frame.
80
207
  onPointerDown={(event) => event.stopPropagation()}
81
208
  >
82
- <span className="tabular-nums">{zoomChipLabel(zoom.zoomPercent)}</span>
209
+ {editing ? (
210
+ <ZoomPercentInput
211
+ zoomPercent={zoom.zoomPercent}
212
+ onSubmit={zoomTo}
213
+ onDone={() => setEditing(false)}
214
+ />
215
+ ) : (
216
+ <button
217
+ type="button"
218
+ className="rounded px-1 py-0.5 tabular-nums hover:bg-white/10 transition-colors"
219
+ onClick={() => setEditing(true)}
220
+ aria-label="Type a zoom percentage"
221
+ data-testid="preview-zoom-readout"
222
+ >
223
+ {zoomChipLabel(zoom.zoomPercent)}
224
+ </button>
225
+ )}
83
226
  <span aria-hidden="true" className="text-white/30">
84
227
  ·
85
228
  </span>
86
229
  <button
87
230
  type="button"
88
231
  className="rounded px-1.5 py-0.5 font-medium text-accent-ink hover:bg-white/10 transition-colors"
89
- onClick={onFit}
232
+ onClick={() => {
233
+ onZoom(DEFAULT_PREVIEW_ZOOM);
234
+ viewportRef.current?.focus();
235
+ }}
90
236
  aria-label="Fit the whole frame in view"
91
237
  data-testid="preview-zoom-fit"
92
238
  >
@@ -100,7 +246,7 @@ export function PreviewZoomOverlay({
100
246
  >
101
247
  <div className="relative overflow-hidden bg-white/10" style={navigatorFrameSize(stageSize)}>
102
248
  <div
103
- ref={navigatorRegionRef}
249
+ ref={controls.setRegion}
104
250
  className="absolute rounded-[1px] border border-studio-accent bg-studio-accent/15"
105
251
  data-testid="preview-zoom-navigator-region"
106
252
  />
@@ -11,11 +11,16 @@ import {
11
11
  getNextPreviewZoomPercent,
12
12
  getPreviewWheelZoomPercent,
13
13
  ownsPreviewPanTarget,
14
+ parsePreviewZoomInput,
14
15
  PREVIEW_PAN_OVERSCROLL_PX,
15
16
  PREVIEW_PAN_SURFACE_SELECTOR,
17
+ PREVIEW_PIXEL_GRID_MIN_ZOOM_PERCENT,
18
+ resolvePreviewPixelGrid,
19
+ resolvePreviewTypedZoom,
16
20
  resolvePreviewVisibleRegion,
17
21
  resolvePreviewWheelPan,
18
22
  resolvePreviewWheelZoom,
23
+ showsPreviewPixelGrid,
19
24
  toDomPrecision,
20
25
  } from "./previewZoom";
21
26
 
@@ -44,6 +49,99 @@ describe("clampPreviewZoomPercent", () => {
44
49
  });
45
50
  });
46
51
 
52
+ describe("parsePreviewZoomInput", () => {
53
+ it("reads a plain number or a percentage, with surrounding spaces", () => {
54
+ expect(parsePreviewZoomInput("250")).toBe(250);
55
+ expect(parsePreviewZoomInput(" 250 % ")).toBe(250);
56
+ expect(parsePreviewZoomInput("137.5%")).toBe(137.5);
57
+ });
58
+
59
+ it("clamps to the preview zoom bounds", () => {
60
+ expect(parsePreviewZoomInput("5")).toBe(MIN_PREVIEW_ZOOM_PERCENT);
61
+ expect(parsePreviewZoomInput("0")).toBe(MIN_PREVIEW_ZOOM_PERCENT);
62
+ expect(parsePreviewZoomInput("99999")).toBe(MAX_PREVIEW_ZOOM_PERCENT);
63
+ });
64
+
65
+ it("rejects anything that is not a percentage", () => {
66
+ for (const text of ["", " ", "%", "abc", "-50", "1e3", "12px", "1,000", "50%%"]) {
67
+ expect(parsePreviewZoomInput(text)).toBeNull();
68
+ }
69
+ });
70
+ });
71
+
72
+ describe("showsPreviewPixelGrid", () => {
73
+ it("shows the grid only above 800%, which the zoom limit can reach", () => {
74
+ expect(PREVIEW_PIXEL_GRID_MIN_ZOOM_PERCENT).toBe(800);
75
+ expect(MAX_PREVIEW_ZOOM_PERCENT).toBeGreaterThan(PREVIEW_PIXEL_GRID_MIN_ZOOM_PERCENT);
76
+ expect(showsPreviewPixelGrid(100)).toBe(false);
77
+ expect(showsPreviewPixelGrid(800)).toBe(false);
78
+ expect(showsPreviewPixelGrid(801)).toBe(true);
79
+ expect(showsPreviewPixelGrid(MAX_PREVIEW_ZOOM_PERCENT)).toBe(true);
80
+ });
81
+ });
82
+
83
+ describe("resolvePreviewPixelGrid", () => {
84
+ const layout = {
85
+ rect: { width: 1000, height: 600 },
86
+ stage: { width: 960, height: 540 },
87
+ width: 1920,
88
+ };
89
+
90
+ it("covers the scaled, centred and panned stage with one cell per composition pixel", () => {
91
+ const box = resolvePreviewPixelGrid({
92
+ state: { zoomPercent: 1000, panX: 30, panY: -20 },
93
+ ...layout,
94
+ });
95
+ expect(box).toEqual({
96
+ left: (1000 - 9600) / 2 + 30,
97
+ top: (600 - 5400) / 2 - 20,
98
+ width: 9600,
99
+ height: 5400,
100
+ cellPx: 5,
101
+ });
102
+ });
103
+
104
+ it("draws nothing at or below the threshold or before the composition size is known", () => {
105
+ const state = { zoomPercent: 800, panX: 0, panY: 0 };
106
+ expect(resolvePreviewPixelGrid({ state, ...layout })).toBeNull();
107
+ expect(
108
+ resolvePreviewPixelGrid({ state: { ...state, zoomPercent: 1000 }, ...layout, width: 0 }),
109
+ ).toBeNull();
110
+ });
111
+ });
112
+
113
+ describe("resolvePreviewTypedZoom", () => {
114
+ const viewport = { viewportWidth: 1000, viewportHeight: 600 };
115
+
116
+ it("keeps the point at the centre of the view in place", () => {
117
+ const next = resolvePreviewTypedZoom({
118
+ state: { zoomPercent: 200, panX: 100, panY: -50 },
119
+ zoomPercent: 400,
120
+ ...viewport,
121
+ });
122
+ expect(next).toEqual({ zoomPercent: 400, panX: 200, panY: -100 });
123
+ });
124
+
125
+ it("clamps the zoom to its bounds", () => {
126
+ const state = { zoomPercent: 200, panX: 0, panY: 0 };
127
+ expect(resolvePreviewTypedZoom({ state, zoomPercent: 10, ...viewport }).zoomPercent).toBe(
128
+ MIN_PREVIEW_ZOOM_PERCENT,
129
+ );
130
+ expect(resolvePreviewTypedZoom({ state, zoomPercent: 99999, ...viewport }).zoomPercent).toBe(
131
+ MAX_PREVIEW_ZOOM_PERCENT,
132
+ );
133
+ });
134
+
135
+ it("clamps a pan that would leave the frame out of view", () => {
136
+ const next = resolvePreviewTypedZoom({
137
+ state: { zoomPercent: 400, panX: 1500, panY: 0 },
138
+ zoomPercent: 200,
139
+ ...viewport,
140
+ });
141
+ expect(next.panX).toBe((1000 * 2 - 1000) / 2 + PREVIEW_PAN_OVERSCROLL_PX);
142
+ });
143
+ });
144
+
47
145
  describe("getPreviewWheelZoomPercent", () => {
48
146
  it("zooms in on negative deltaY (scroll up / pinch out)", () => {
49
147
  expect(getPreviewWheelZoomPercent(-5, 100)).toBeGreaterThan(100);