Skip to content

Write HTML. Render video. Built for agents.

feat(studio): a host app can reuse Studio's snapping and marquee selection in its own preview (#4635)

Miguel Ángel4aa6b168fea8
diff --git a/packages/core/src/inline-scripts/pickerApi.ts b/packages/core/src/inline-scripts/pickerApi.ts
index f58f203269..fbe0dc72bf 100644
--- a/packages/core/src/inline-scripts/pickerApi.ts
+++ b/packages/core/src/inline-scripts/pickerApi.ts
@@ -37,6 +37,7 @@ export type HyperframePickerApi = {
clientY: number,
indexes?: number[],
) => HyperframePickerElementInfo[];
+ describe?: (element: Element) => HyperframePickerElementInfo | null;
};
declare global {
diff --git a/packages/core/src/runtime/picker.test.ts b/packages/core/src/runtime/picker.test.ts
index 7f9e1c11cd..20fb8b1c97 100644
--- a/packages/core/src/runtime/picker.test.ts
+++ b/packages/core/src/runtime/picker.test.ts
@@ -125,6 +125,7 @@ describe("createPickerModule", () => {
expect(typeof api.getCandidatesAtPoint).toBe("function");
expect(typeof api.pickAtPoint).toBe("function");
expect(typeof api.pickManyAtPoint).toBe("function");
+ expect(typeof api.describe).toBe("function");
});
it("isActive returns pick mode state", () => {
@@ -305,6 +306,22 @@ describe("createPickerModule", () => {
]);
});
+ it("describe returns what a click on the same element returns", () => {
+ const picker = createPickerModule({ postMessage: createMockPostMessage() });
+ picker.installPickerApi();
+ document.body.innerHTML = `<div id="root" data-composition-id="main"><p>a</p>
+ <p class="card" data-start="1">b</p></div>`;
+ const card = document.querySelector(".card")!;
+ const api = (window as any).__HF_PICKER_API;
+ const restore = emulateHitTest(() => [card, document.getElementById("root")!]);
+ try {
+ expect(api.describe(card)).toEqual(api.getCandidatesAtPoint(10, 10)[0]);
+ } finally {
+ restore();
+ }
+ expect(api.describe(document.createTextNode("x"))).toBeNull();
+ });
+
it("a section background click picks the host, and an inner root never gets a bare tag selector", () => {
const picker = createPickerModule({ postMessage: createMockPostMessage() });
picker.installPickerApi();
diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts
index 7e6b409736..b598b7e397 100644
--- a/packages/core/src/runtime/picker.ts
+++ b/packages/core/src/runtime/picker.ts
@@ -372,6 +372,7 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
disablePickMode();
return selected;
},
+ describe: (element) => (isElementNode(element) ? extractElementInfo(element) : null),
pickManyAtPoint: (clientX, clientY, indexes) => {
if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return [];
const infos = getPickInfosFromPoint(clientX, clientY, 8);
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index d5e62a0c7b..8586fc8442 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -378,9 +378,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
)
: null;
if (freshTarget) return;
- const overlayEl = overlayRef.current;
- if (overlayEl) {
- const oRect = overlayEl.getBoundingClientRect();
+ if (overlayRef.current) {
// Anywhere empty on the overlay starts one, not just inside the frame.
// An element dragged past the edge sits OUT there in the grey, and a
// rubber band that refuses to start there cannot reach it — which left
@@ -390,17 +388,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
event.preventDefault();
event.stopPropagation();
suppressNextOverlayMouseDownRef.current = true;
- (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
- const cx = event.clientX - oRect.left;
- const cy = event.clientY - oRect.top;
- marquee.marqueeRef.current = {
- startX: cx,
- startY: cy,
- currentX: cx,
- currentY: cy,
- pointerId: event.pointerId,
- pastThreshold: false,
- };
+ marquee.begin(event);
return;
}
}
diff --git a/packages/studio/src/components/editor/MarqueeOverlay.tsx b/packages/studio/src/components/editor/MarqueeOverlay.tsx
index 9187c130de..df7da60111 100644
--- a/packages/studio/src/components/editor/MarqueeOverlay.tsx
+++ b/packages/studio/src/components/editor/MarqueeOverlay.tsx
@@ -1,6 +1,6 @@
import type { Rect } from "../../utils/marqueeGeometry";
-interface MarqueeOverlayProps {
+export interface MarqueeOverlayProps {
/** Elements the marquee currently intersects — outlined live before mouse-up. */
candidateRects: Rect[];
/** The marquee drag rectangle itself, or null when not marquee-selecting. */
diff --git a/packages/studio/src/components/editor/SnapGuideOverlay.tsx b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
index ad6f98e2c9..dc04d16797 100644
--- a/packages/studio/src/components/editor/SnapGuideOverlay.tsx
+++ b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
@@ -15,7 +15,7 @@ const GUIDE_COLOR = "rgba(255, 68, 204, 0.85)";
const SPACING_COLOR = "rgba(255, 68, 204, 0.6)";
const SPACING_BG = "rgba(255, 68, 204, 0.15)";
-interface SnapGuideOverlayProps {
+export interface SnapGuideOverlayProps {
snapGuidesRef: RefObject<SnapGuidesState | null>;
/** Composition rect in overlay space — guide lines span exactly this rect. */
compositionLeft: number;
diff --git a/packages/studio/src/components/editor/marqueeCommit.ts b/packages/studio/src/components/editor/marqueeCommit.ts
index fa731613c0..24c94052ed 100644
--- a/packages/studio/src/components/editor/marqueeCommit.ts
+++ b/packages/studio/src/components/editor/marqueeCommit.ts
@@ -14,6 +14,7 @@ interface MarqueeState {
currentY: number;
pointerId: number;
pastThreshold: boolean;
+ target: Element;
}
const MARQUEE_THRESHOLD_PX = 4;
@@ -80,14 +81,13 @@ function hitsWithin(rect: Rect, candidates: MarqueeHit[]): MarqueeHit[] {
return candidates.filter((candidate) => rectsOverlap(rect, candidate.rect));
}
-async function runMarqueeIntersection(
- rect: Rect,
- candidates: MarqueeHit[],
+async function resolveDomEditSelections(
+ elements: HTMLElement[],
activeCompositionPath: string,
): Promise<DomEditSelection[]> {
const isMasterView = !activeCompositionPath || activeCompositionPath === "index.html";
const hits: DomEditSelection[] = [];
- for (const { element } of hitsWithin(rect, candidates)) {
+ for (const element of elements) {
const sel = await resolveDomEditSelection(element, {
activeCompositionPath,
isMasterView,
@@ -98,23 +98,48 @@ async function runMarqueeIntersection(
return hits;
}
-interface MarqueeGesturesDeps {
+export interface MarqueeGesturesDeps<T = DomEditSelection> {
iframeRef: React.RefObject<HTMLIFrameElement | null>;
overlayRef: React.RefObject<HTMLDivElement | null>;
activeCompositionPathRef: React.RefObject<string | null>;
- onMarqueeSelectRef: React.RefObject<
- ((selections: DomEditSelection[], additive: boolean) => void) | undefined
- >;
- selectionRef: React.RefObject<DomEditSelection | null>;
- gestures: {
+ onMarqueeSelectRef: React.RefObject<((selections: T[], additive: boolean) => void) | undefined>;
+ /** Turns the elements a drag touched into picks; without it, Studio's edit selections. */
+ resolveHits?: (elements: HTMLElement[]) => T[] | Promise<T[]>;
+ selectionRef?: React.RefObject<DomEditSelection | null>;
+ /** Studio's pointer handling, for the events that are not part of a marquee. */
+ gestures?: {
onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
clearPointerState: (ref: React.RefObject<DomEditSelection | null>) => void;
};
}
+export interface MarqueeGestures {
+ marqueeRect: Rect | null;
+ candidateRects: Rect[];
+ /** Starts a marquee at this press; the host has decided it landed on empty canvas. */
+ begin: (event: React.PointerEvent<HTMLElement>) => void;
+ /** Drops an active marquee without selecting anything. */
+ cancel: () => void;
+ onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
+ onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
+ onPointerCancel: () => void;
+}
+
+function releaseCapture(m: MarqueeState): void {
+ try {
+ m.target.releasePointerCapture(m.pointerId);
+ } catch {
+ /* already released */
+ }
+}
+
+export function useMarqueeGestures(deps: MarqueeGesturesDeps): MarqueeGestures;
+export function useMarqueeGestures<T>(
+ deps: MarqueeGesturesDeps<T> & Required<Pick<MarqueeGesturesDeps<T>, "resolveHits">>,
+): MarqueeGestures;
// fallow-ignore-next-line complexity
-export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
+export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGestures {
const marqueeRef = useRef<MarqueeState | null>(null);
const [marqueeRect, setMarqueeRect] = useState<Rect | null>(null);
// Live "candidate" highlight: the elements the marquee currently touches,
@@ -135,12 +160,55 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
if (!iframe || !overlay || !deps.onMarqueeSelectRef.current) return;
const acp = deps.activeCompositionPathRef.current ?? "index.html";
const candidates = candidatesRef.current ?? collectMarqueeCandidates(iframe, overlay, acp);
- const hits = await runMarqueeIntersection(rect, candidates, acp);
- deps.onMarqueeSelectRef.current(hits, additive);
+ const elements = hitsWithin(rect, candidates).map((hit) => hit.element);
+ const resolveHits = deps.resolveHits;
+ const picks = resolveHits
+ ? await resolveHits(elements)
+ : ((await resolveDomEditSelections(elements, acp)) as T[]);
+ deps.onMarqueeSelectRef.current?.(picks, additive);
},
- [deps.iframeRef, deps.overlayRef, deps.onMarqueeSelectRef, deps.activeCompositionPathRef],
+ [
+ deps.iframeRef,
+ deps.overlayRef,
+ deps.onMarqueeSelectRef,
+ deps.activeCompositionPathRef,
+ deps.resolveHits,
+ ],
);
+ const reset = useCallback(() => {
+ marqueeRef.current = null;
+ setMarqueeRect(null);
+ setCandidateRects([]);
+ candidatesRef.current = null;
+ }, []);
+
+ const begin = useCallback(
+ (event: React.PointerEvent<HTMLElement>) => {
+ const oRect = deps.overlayRef.current?.getBoundingClientRect();
+ if (!oRect) return;
+ event.currentTarget.setPointerCapture(event.pointerId);
+ const x = event.clientX - oRect.left;
+ const y = event.clientY - oRect.top;
+ marqueeRef.current = {
+ startX: x,
+ startY: y,
+ currentX: x,
+ currentY: y,
+ pointerId: event.pointerId,
+ pastThreshold: false,
+ target: event.currentTarget,
+ };
+ },
+ [deps.overlayRef],
+ );
+
+ const cancel = useCallback(() => {
+ if (!marqueeRef.current) return;
+ releaseCapture(marqueeRef.current);
+ reset();
+ }, [reset]);
+
const onPointerMove = useCallback(
(event: React.PointerEvent<HTMLDivElement>) => {
const m = marqueeRef.current;
@@ -172,7 +240,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
}
return;
}
- deps.gestures.onPointerMove(event);
+ deps.gestures?.onPointerMove(event);
},
[deps.gestures, deps.overlayRef, deps.iframeRef, deps.activeCompositionPathRef],
);
@@ -181,12 +249,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
(event: React.PointerEvent<HTMLDivElement>) => {
const m = marqueeRef.current;
if (m) {
- marqueeRef.current = null;
- try {
- (event.currentTarget as HTMLElement).releasePointerCapture(m.pointerId);
- } catch {
- /* already released */
- }
+ releaseCapture(m);
if (m.pastThreshold) {
commitMarquee(
{
@@ -200,26 +263,26 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
} else {
deps.onMarqueeSelectRef.current?.([], false);
}
- setMarqueeRect(null);
- setCandidateRects([]);
- candidatesRef.current = null;
+ reset();
return;
}
- deps.gestures.onPointerUp(event);
+ deps.gestures?.onPointerUp(event);
},
- [deps.gestures, commitMarquee, deps.onMarqueeSelectRef],
+ [deps.gestures, commitMarquee, deps.onMarqueeSelectRef, reset],
);
const onPointerCancel = useCallback(() => {
- if (marqueeRef.current) {
- marqueeRef.current = null;
- setMarqueeRect(null);
- setCandidateRects([]);
- candidatesRef.current = null;
- return;
- }
- deps.gestures.clearPointerState(deps.selectionRef);
- }, [deps.gestures, deps.selectionRef]);
-
- return { marqueeRef, marqueeRect, candidateRects, onPointerMove, onPointerUp, onPointerCancel };
+ if (marqueeRef.current) return cancel();
+ if (deps.selectionRef) deps.gestures?.clearPointerState(deps.selectionRef);
+ }, [deps.gestures, deps.selectionRef, cancel]);
+
+ return {
+ marqueeRect,
+ candidateRects,
+ begin,
+ cancel,
+ onPointerMove,
+ onPointerUp,
+ onPointerCancel,
+ };
}
diff --git a/packages/studio/src/editorGesturesExports.test.tsx b/packages/studio/src/editorGesturesExports.test.tsx
new file mode 100644
index 0000000000..58425a83fb
--- /dev/null
+++ b/packages/studio/src/editorGesturesExports.test.tsx
@@ -0,0 +1,236 @@
+// @vitest-environment happy-dom
+// Drives Studio's snapping and marquee by package name with a host's own iframe and overlay.
+import { act, type PointerEvent } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+ collectSnapContext,
+ resolveSnapAdjustment,
+ SNAP_THRESHOLD_PX,
+ SnapGuideOverlay,
+ useMarqueeGestures,
+ usePlayerStore,
+ type MarqueeGestures,
+ type MarqueeGesturesDeps,
+ type MarqueeRect,
+} from "@hyperframes/studio";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+import {
+ collectDomEditLayerItems,
+ resolveDomEditSelection,
+} from "./components/editor/domEditingLayers";
+
+const rects = new Map<string, MarqueeRect>([
+ ["a", { left: 0, top: 0, width: 10, height: 10 }],
+ ["b", { left: 100, top: 100, width: 10, height: 10 }],
+]);
+
+vi.mock("./components/editor/domEditOverlayGeometry", async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ isElementVisibleForOverlay: () => true,
+ toVisibleOverlayRect: (_overlay: unknown, _iframe: unknown, el: HTMLElement) => {
+ const rect = rects.get(el.id);
+ return rect ? { ...rect, editScaleX: 1, editScaleY: 1 } : null;
+ },
+}));
+vi.mock("./components/editor/domEditingElement", async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ isElementComputedVisible: () => true,
+}));
+vi.mock("./components/editor/domEditingLayers", async (importOriginal) => ({
+ ...(await importOriginal<object>()),
+ collectDomEditLayerItems: vi.fn((root: HTMLElement) =>
+ Array.from(root.children).map((element) => ({ element })),
+ ),
+ resolveDomEditSelection: vi.fn(async (element: HTMLElement) => ({ id: element.id })),
+}));
+
+installReactActEnvironment();
+
+afterEach(() => {
+ document.body.innerHTML = "";
+ vi.clearAllMocks();
+ usePlayerStore.setState({ previewBooted: false });
+});
+
+function MarqueeHost<T>(props: {
+ deps: MarqueeGesturesDeps<T>;
+ onState: (state: MarqueeGestures) => void;
+}) {
+ props.onState(useMarqueeGestures(props.deps as unknown as MarqueeGesturesDeps));
+ return null;
+}
+
+function mountMarquee<T>(extra: Partial<MarqueeGesturesDeps<T>> = {}) {
+ document.body.innerHTML = `<div data-composition-id="main" data-width="1920" data-height="1080">
+ <div id="a"></div><div id="b"></div></div>`;
+ const overlay = document.createElement("div");
+ overlay.setPointerCapture = vi.fn();
+ overlay.releasePointerCapture = vi.fn();
+ document.body.append(overlay);
+ const onSelect = vi.fn();
+ const deps: MarqueeGesturesDeps<T> = {
+ iframeRef: { current: { contentDocument: document } as unknown as HTMLIFrameElement },
+ overlayRef: { current: overlay },
+ activeCompositionPathRef: { current: "index.html" },
+ onMarqueeSelectRef: { current: onSelect },
+ ...extra,
+ };
+ let state: MarqueeGestures | undefined;
+ const root = mountReactHarness(<MarqueeHost deps={deps} onState={(next) => (state = next)} />);
+ const at = (x: number, y: number, shiftKey = false) =>
+ ({
+ clientX: x,
+ clientY: y,
+ pointerId: 7,
+ shiftKey,
+ currentTarget: overlay,
+ }) as unknown as PointerEvent<HTMLDivElement>;
+ const marquee = () => state as MarqueeGestures;
+ return { overlay, onSelect, root, at, marquee };
+}
+
+describe("marquee package export, driven by a host", () => {
+ const byId = { resolveHits: (elements: HTMLElement[]) => elements.map((el) => el.id) };
+
+ it("hands the elements a drag touched to the host's resolveHits and selects what it returns", async () => {
+ const { overlay, onSelect, at, marquee } = mountMarquee<string>(byId);
+ act(() => marquee().begin(at(1, 1)));
+ expect(overlay.setPointerCapture).toHaveBeenCalledWith(7);
+ act(() => marquee().onPointerMove(at(20, 20)));
+ expect(marquee().marqueeRect).toEqual({ left: 1, top: 1, width: 19, height: 19 });
+ expect(marquee().candidateRects).toEqual([rects.get("a")]);
+ await act(async () => marquee().onPointerUp(at(20, 20, true)));
+ expect(onSelect).toHaveBeenCalledWith(["a"], true);
+ expect(overlay.releasePointerCapture).toHaveBeenCalledWith(7);
+ expect(marquee().marqueeRect).toBeNull();
+ });
+
+ it("measures the candidates once per drag", async () => {
+ const { at, marquee } = mountMarquee<string>(byId);
+ act(() => marquee().begin(at(1, 1)));
+ act(() => marquee().onPointerMove(at(20, 20)));
+ act(() => marquee().onPointerMove(at(120, 120)));
+ await act(async () => marquee().onPointerUp(at(120, 120)));
+ expect(collectDomEditLayerItems).toHaveBeenCalledTimes(1);
+ });
+
+ it("selects nothing on a release under the threshold, as a click", async () => {
+ const resolveHits = vi.fn(byId.resolveHits);
+ const { onSelect, at, marquee } = mountMarquee<string>({ resolveHits });
+ act(() => marquee().begin(at(1, 1)));
+ await act(async () => marquee().onPointerUp(at(2, 2)));
+ expect(onSelect).toHaveBeenCalledWith([], false);
+ expect(resolveHits).not.toHaveBeenCalled();
+ });
+
+ it("cancel() drops an active marquee and the release that follows selects nothing", async () => {
+ const { overlay, onSelect, at, marquee } = mountMarquee<string>(byId);
+ act(() => marquee().begin(at(1, 1)));
+ act(() => marquee().onPointerMove(at(20, 20)));
+ act(() => marquee().cancel());
+ expect(marquee().marqueeRect).toBeNull();
+ expect(marquee().candidateRects).toEqual([]);
+ expect(overlay.releasePointerCapture).toHaveBeenCalledWith(7);
+ await act(async () => marquee().onPointerUp(at(20, 20)));
+ expect(onSelect).not.toHaveBeenCalled();
+ });
+
+ it("a pointercancel mid-drag drops the marquee without selecting", async () => {
+ const { onSelect, at, marquee } = mountMarquee<string>(byId);
+ act(() => marquee().begin(at(1, 1)));
+ act(() => marquee().onPointerMove(at(20, 20)));
+ act(() => marquee().onPointerCancel());
+ expect(marquee().marqueeRect).toBeNull();
+ await act(async () => marquee().onPointerUp(at(20, 20)));
+ expect(onSelect).not.toHaveBeenCalled();
+ });
+
+ it("will not hand a host Studio's selections under the host's own pick type", () => {
+ const hostDeps: MarqueeGesturesDeps<string> = {
+ iframeRef: { current: null },
+ overlayRef: { current: null },
+ activeCompositionPathRef: { current: null },
+ onMarqueeSelectRef: { current: undefined },
+ };
+ // @ts-expect-error a host pick type needs its own resolveHits
+ const typed = () => useMarqueeGestures<string>(hostDeps);
+ expect(typed).toBeTypeOf("function");
+ });
+
+ it("resolves Studio edit selections when the host passes no resolveHits", async () => {
+ const { onSelect, at, marquee } = mountMarquee();
+ act(() => marquee().begin(at(1, 1)));
+ act(() => marquee().onPointerMove(at(20, 20)));
+ await act(async () => marquee().onPointerUp(at(20, 20)));
+ expect(resolveDomEditSelection).toHaveBeenCalledWith(
+ document.getElementById("a"),
+ expect.objectContaining({ skipSourceProbe: true }),
+ );
+ expect(onSelect).toHaveBeenCalledWith([{ id: "a" }], false);
+ });
+
+ it("passes pointer events that are not a marquee to Studio's gestures, and needs none", () => {
+ const gestures = { onPointerMove: vi.fn(), onPointerUp: vi.fn(), clearPointerState: vi.fn() };
+ const selectionRef = { current: null };
+ const withGestures = mountMarquee<string>({ ...byId, gestures, selectionRef });
+ act(() => withGestures.marquee().onPointerMove(withGestures.at(5, 5)));
+ act(() => withGestures.marquee().onPointerUp(withGestures.at(5, 5)));
+ act(() => withGestures.marquee().onPointerCancel());
+ expect(gestures.onPointerMove).toHaveBeenCalledTimes(1);
+ expect(gestures.onPointerUp).toHaveBeenCalledTimes(1);
+ expect(gestures.clearPointerState).toHaveBeenCalledWith(selectionRef);
+
+ const bare = mountMarquee<string>(byId);
+ expect(() => {
+ bare.marquee().onPointerMove(bare.at(5, 5));
+ bare.marquee().onPointerUp(bare.at(5, 5));
+ bare.marquee().onPointerCancel();
+ }).not.toThrow();
+ });
+});
+
+describe("snapping package export, driven by a host", () => {
+ it("snaps a host's drag to another element and draws the guide", async () => {
+ document.body.innerHTML = `<div data-composition-id="main" data-width="1920" data-height="1080">
+ <div id="a"></div><div id="b"></div></div>`;
+ const overlay = document.createElement("div");
+ const iframe = {
+ contentDocument: document,
+ getBoundingClientRect: () => ({ left: 0, top: 0, width: 1920, height: 1080 }),
+ } as unknown as HTMLIFrameElement;
+ const moving = document.getElementById("a") as HTMLElement;
+ const context = collectSnapContext({
+ overlayEl: overlay,
+ iframe,
+ excludeElements: new Set([moving]),
+ });
+ const snap = resolveSnapAdjustment({
+ movingRect: rects.get("a")!,
+ proposedDx: 98,
+ proposedDy: 0,
+ targets: context.targets,
+ threshold: SNAP_THRESHOLD_PX,
+ disabled: !context.snapEnabled,
+ });
+ expect(snap.dx).toBe(100);
+ expect(snap.guides.length).toBeGreaterThan(0);
+
+ // The guides draw once the host's preview has booted, as NLEPreview's player marks it.
+ usePlayerStore.setState({ previewBooted: true });
+ const snapGuidesRef = { current: { guides: snap.guides, spacingGuides: snap.spacingGuides } };
+ const root = mountReactHarness(
+ <SnapGuideOverlay
+ snapGuidesRef={snapGuidesRef}
+ compositionLeft={0}
+ compositionTop={0}
+ compositionWidth={1920}
+ compositionHeight={1080}
+ />,
+ );
+ await vi.waitFor(() => {
+ const guide = document.querySelector<HTMLElement>('[aria-hidden="true"] > div');
+ expect(guide?.style.display).toBe("");
+ });
+ await act(async () => root.unmount());
+ });
+});
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index baed6432e4..2e7e1639e7 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -199,3 +199,32 @@ export {
type SeamTransitionLoopHandle,
type SeamTransitionLoopOptions,
} from "@hyperframes/shader-transitions";
+
+// Editor gestures for a host's own preview overlay: snapping and the marquee
+export {
+ SNAP_THRESHOLD_PX,
+ snapEngagedForTravel,
+ extractSnapTargets,
+ buildCompositionSnapTarget,
+ buildGridSnapEdges,
+ resolveSnapAdjustment,
+ resolveGuideLineRect,
+ resolveEquidistanceGuides,
+} from "./components/editor/snapEngine";
+export type {
+ SnapEdge,
+ SnapTarget,
+ SnapGuide,
+ SpacingGuide,
+ SnapResult,
+ Rect as SnapRect,
+} from "./components/editor/snapEngine";
+export { collectSnapContext } from "./components/editor/snapTargetCollection";
+export type { SnapContext } from "./components/editor/snapTargetCollection";
+export { SnapGuideOverlay } from "./components/editor/SnapGuideOverlay";
+export type { SnapGuideOverlayProps, SnapGuidesState } from "./components/editor/SnapGuideOverlay";
+export { useMarqueeGestures } from "./components/editor/marqueeCommit";
+export type { MarqueeGestures, MarqueeGesturesDeps } from "./components/editor/marqueeCommit";
+export { MarqueeOverlay } from "./components/editor/MarqueeOverlay";
+export type { MarqueeOverlayProps } from "./components/editor/MarqueeOverlay";
+export type { Rect as MarqueeRect } from "./utils/marqueeGeometry";