@hyperframes/studio 0.7.75 → 0.7.77

package/src/hooks/useGsapTweenCache.ts

@@ -1,54 +1,30 @@
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
-import type { GsapAnimation, GsapKeyframesData, ParsedGsap } from "@hyperframes/core/gsap-parser";
-import { isStudioHoldSet } from "@hyperframes/core/gsap-parser";
+import type { GsapAnimation, GsapKeyframesData } from "@hyperframes/core/gsap-parser";
 import { usePlayerStore } from "../player/store/playerStore";
 import { readRuntimeKeyframes, scanAllRuntimeKeyframes } from "./gsapRuntimeBridge";
 import {
   clearKeyframeCacheForElement,
-  clearKeyframeCacheForFile,
+  pruneKeyframeCacheToFiles,
+  writeGsapAnimationsForElement,
 } from "./gsapKeyframeCacheHelpers";
-import { toAbsoluteTime } from "./gsapShared";
-import { deduplicateKeyframes, synthesizeFlatTweenKeyframes } from "./gsapTweenSynth";
-
-function extractIdFromSelector(selector: string): string | null {
-  const match = selector.match(/^#([\w-]+)/);
-  return match ? match[1] : null;
-}
-
-/**
- * Resolve a tween's target selector to the ids of the element(s) it animates.
- * A bare `#id` resolves directly; anything else (a class like `.dot`, a group
- * `.a, .b`, or a descendant selector) is matched against the live preview DOM so
- * class/selector tweens (e.g. `gsap.from(".dot", {stagger})`) attribute to every
- * element they animate — not just one parsed from the string. Falls back to a
- * leading `#id` when there's no DOM (so the cache still populates pre-iframe).
- */
-// fallow-ignore-next-line complexity
-export function resolveSelectorElementIds(
-  selector: string,
-  doc: Document | null | undefined,
-): string[] {
-  const bareId = selector.match(/^#([\w-]+)$/);
-  if (bareId) return [bareId[1]];
-  if (!doc) {
-    const lead = extractIdFromSelector(selector);
-    return lead ? [lead] : [];
-  }
-  const ids = new Set<string>();
-  for (const part of selector.split(",")) {
-    const sel = part.trim();
-    if (!sel) continue;
-    try {
-      for (const el of Array.from(doc.querySelectorAll(sel))) {
-        if (el.id) ids.add(el.id);
-      }
-    } catch {
-      const lead = extractIdFromSelector(sel);
-      if (lead) ids.add(lead);
-    }
-  }
-  return Array.from(ids);
-}
+import { toAbsoluteTime, toClipPercentage } from "./gsapShared";
+import {
+  deduplicateKeyframes,
+  isStaticPositionHold,
+  synthesizeFlatTweenKeyframes,
+} from "./gsapTweenSynth";
+import {
+  fetchParsedAnimations,
+  populateKeyframeCacheFromAst,
+  resolveClipTimingBasis,
+} from "./keyframeCacheAstLoad";
+
+// Re-exported so callers keep importing the GSAP cache surface from one module.
+export {
+  fetchParsedAnimations,
+  resolveClipTimingBasis,
+  resolveSelectorElementIds,
+} from "./keyframeCacheAstLoad";
 
 /** The selected element's identity for matching tweens to it. */
 export interface GsapElementTarget {
@@ -98,59 +74,6 @@ export function getAnimationsForElement(
   );
 }
 
-export async function fetchParsedAnimations(
-  projectId: string,
-  sourceFile: string,
-): Promise<ParsedGsap | null> {
-  try {
-    const res = await fetch(
-      `/api/projects/${encodeURIComponent(projectId)}/gsap-animations/${encodeURIComponent(sourceFile)}`,
-      // Always re-read the freshly-parsed source; no per-call timestamp (which
-      // would defeat caching forever and is a deterministic-render no-no).
-      { cache: "no-store" },
-    );
-    if (!res.ok) return null;
-    const parsed = (await res.json()) as ParsedGsap;
-    // Studio-emitted pre-keyframe hold `set`s are an internal runtime detail (they
-    // hold an element's first keyframe before its tween). They must not surface as
-    // user animations — otherwise they pollute the keyframe cache / timeline diamonds.
-    return { ...parsed, animations: parsed.animations.filter((a) => !isStudioHoldSet(a)) };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Clip-relative timing basis for an element. Sub-composition internals (e.g. pills
- * inside a scene) aren't timeline clips themselves — they're derived at expand time
- * — so they're absent from `elements`. Without a basis, elDuration defaulted to 1
- * and clip-relative keyframe percentages blew past 100% (rendering off the clip).
- * Fall back to the sub-comp HOST's bounds, resolved via domClipChildren (the host's
- * data-composition-src is stripped in the rendered DOM, so we can't query it).
- */
-export function resolveClipTimingBasis(
-  elementId: string,
-  sourceFile: string,
-  elements: ReadonlyArray<{
-    domId?: string;
-    key?: string;
-    id: string;
-    start: number;
-    duration: number;
-  }>,
-  domClipChildren: ReadonlyArray<{ id: string; hostId: string }>,
-): { elStart: number; elDuration: number } {
-  const direct = elements.find(
-    (el) => el.domId === elementId || (el.key ?? el.id) === `${sourceFile}#${elementId}`,
-  );
-  if (direct) return { elStart: direct.start, elDuration: direct.duration };
-  const hostId = domClipChildren.find((c) => c.id === elementId)?.hostId;
-  const host = hostId
-    ? elements.find((el) => el.domId === hostId || (el.key ?? el.id) === `index.html#${hostId}`)
-    : undefined;
-  return { elStart: host?.start ?? 0, elDuration: host?.duration ?? 1 };
-}
-
 export function useGsapAnimationsForElement(
   projectId: string | null,
   sourceFile: string,
@@ -328,6 +251,17 @@ export function useGsapAnimationsForElement(
   // fallow-ignore-next-line complexity
   useEffect(() => {
     if (!elementId) return;
+    // Same admission rule as the keyframe cache below (hold skip included) and
+    // no property-group filter: the two stores must agree, or a hold draws an
+    // expanded property lane with no collapsed diamond behind it and an
+    // ungrouped tween draws diamonds with no lane source.
+    const sourceAnimations = animations.filter(
+      (animation) =>
+        !isStaticPositionHold(animation) &&
+        (animation.keyframes || synthesizeFlatTweenKeyframes(animation)),
+    );
+    if (sourceAnimations.length > 0)
+      writeGsapAnimationsForElement(sourceFile, elementId, sourceAnimations);
 
     // Resolve the element's time range from the player store so we can
     // convert tween-relative keyframe percentages to clip-relative ones.
@@ -340,24 +274,17 @@ export function useGsapAnimationsForElement(
     );
 
     const allKeyframes: Array<
-      GsapKeyframesData["keyframes"][0] & { tweenPercentage?: number; propertyGroup?: string }
+      GsapKeyframesData["keyframes"][0] & {
+        tweenPercentage?: number;
+        propertyGroup?: string;
+        animationId?: string;
+      }
     > = [];
     let format: GsapKeyframesData["format"] = "percentage";
     let ease: string | undefined;
     let easeEach: string | undefined;
     for (const anim of animations) {
-      // A static position hold (only x/y, no real motion) is a `set`, not a
-      // keyframe — don't synthesize a diamond for it. Covers both `tl.set(...)`
-      // and the `tl.to({ duration: 0, immediateRender: true })` hold that
-      // remove-all-keyframes collapses to (which is otherwise shown as a stray
-      // 0% keyframe).
-      if (
-        !anim.keyframes &&
-        Object.keys(anim.properties).length > 0 &&
-        Object.keys(anim.properties).every((k) => k === "x" || k === "y") &&
-        (anim.method === "set" || (anim.duration ?? 0) === 0)
-      )
-        continue;
+      if (isStaticPositionHold(anim)) continue;
       const kf = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
       if (!kf) continue;
       // Convert tween-relative percentages to clip-relative so diamonds
@@ -367,17 +294,13 @@ export function useGsapAnimationsForElement(
       const tweenDur = anim.duration ?? elDuration;
       for (const k of kf.keyframes) {
         const absTime = toAbsoluteTime(tweenPos, tweenDur, k.percentage);
-        // 0.001% precision (was 0.1%) so a beat-snapped keyframe centers exactly
-        // on the beat dot, which is rendered at the true beat time.
-        const clipPct =
-          elDuration > 0
-            ? Math.round(((absTime - elStart) / elDuration) * 100000) / 1000
-            : k.percentage;
+        const clipPct = toClipPercentage(absTime, elStart, elDuration, k.percentage);
         allKeyframes.push({
           ...k,
           percentage: clipPct,
           tweenPercentage: k.percentage,
           propertyGroup: anim.propertyGroup,
+          animationId: anim.id,
         });
       }
       format = kf.format;
@@ -424,6 +347,7 @@ export function useGsapCacheVersion() {
  * elements. Called from the Timeline component so diamonds show without
  * requiring a selection.
  */
+
 export function usePopulateKeyframeCacheForFile(
   projectId: string | null,
   sourceFile: string,
@@ -431,6 +355,16 @@ export function usePopulateKeyframeCacheForFile(
   iframeRef?: React.RefObject<HTMLIFrameElement | null>,
 ): void {
   const elementCount = usePlayerStore((s) => s.elements.length);
+  // Every sub-composition file the timeline shows rows for. The cache is loaded
+  // for all of them up front, so keyframe lanes are populated on open instead of
+  // only once a clip from that file is selected (which is what switches
+  // `sourceFile`). Only files reachable from the store's elements are covered;
+  // a composition nested inside another still loads on first selection.
+  const compositionSrcKey = usePlayerStore((s) =>
+    Array.from(new Set(s.elements.map((el) => el.compositionSrc).filter((src) => !!src)))
+      .sort()
+      .join("|"),
+  );
   // Re-run when sub-comp DOM children appear (they supply the host bounds the
   // clip-relative keyframe percentages are computed against; without this the
   // cache is computed once before they exist and the percentages stay wrong).
@@ -443,72 +377,24 @@ export function usePopulateKeyframeCacheForFile(
   const astFetchDoneRef = useRef("");
 
   useEffect(() => {
-    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}:${elementCount}:${domClipChildrenKey}`;
+    const fetchKey = `kf-cache:${projectId}:${sourceFile}:${version}:${elementCount}:${domClipChildrenKey}:${compositionSrcKey}`;
     if (fetchKey === lastFetchKeyRef.current) return;
     lastFetchKeyRef.current = fetchKey;
     runtimeScanDoneRef.current = "";
     astFetchDoneRef.current = "";
     if (!projectId) return;
 
-    const sf = sourceFile;
-    // fallow-ignore-next-line complexity
-    fetchParsedAnimations(projectId, sf).then((parsed) => {
-      if (!parsed) return;
-      const { setKeyframeCache } = usePlayerStore.getState();
-      clearKeyframeCacheForFile(sf);
-      const { elements, domClipChildren } = usePlayerStore.getState();
-      const doc = iframeRef?.current?.contentDocument;
-      const mergedByElement = new Map<string, GsapKeyframesData>();
-      for (const anim of parsed.animations) {
-        if (anim.hasUnresolvedKeyframes) continue;
-        // Position-only static holds are not keyframed animations — skip them so
-        // they don't draw a timeline diamond. Covers both a `tl.set(...)` and the
-        // `tl.to({ duration: 0, immediateRender: true })` that remove-all-keyframes
-        // collapses a keyframed tween to.
-        if (!anim.keyframes && (anim.method === "set" || (anim.duration ?? 0) === 0)) {
-          const propKeys = Object.keys(anim.properties).filter((k) => k !== "immediateRender");
-          if (propKeys.length > 0 && propKeys.every((k) => k === "x" || k === "y")) {
-            continue;
-          }
-        }
-        const kfData = anim.keyframes ?? synthesizeFlatTweenKeyframes(anim);
-        if (!kfData) continue;
-        const tweenPos =
-          anim.resolvedStart ?? (typeof anim.position === "number" ? anim.position : 0);
-        const tweenDur = anim.duration ?? 1;
-        // Attribute the tween to every element it animates (handles class /
-        // group / descendant selectors, not just `#id`).
-        for (const id of resolveSelectorElementIds(anim.targetSelector, doc)) {
-          const { elStart, elDuration } = resolveClipTimingBasis(id, sf, elements, domClipChildren);
-          const clipKeyframes = kfData.keyframes.map((kf) => {
-            const absTime = toAbsoluteTime(tweenPos, tweenDur, kf.percentage);
-            // 0.001% precision (matching useGsapAnimationsForElement above) so a
-            // beat-snapped keyframe centers exactly on the beat dot and the two
-            // caches agree on a keyframe's percentage.
-            const clipPct =
-              elDuration > 0
-                ? Math.round(((absTime - elStart) / elDuration) * 100000) / 1000
-                : kf.percentage;
-            return {
-              ...kf,
-              percentage: clipPct,
-              tweenPercentage: kf.percentage,
-              propertyGroup: anim.propertyGroup,
-            };
-          });
-          const existing = mergedByElement.get(id);
-          if (existing) {
-            existing.keyframes = deduplicateKeyframes([...existing.keyframes, ...clipKeyframes]);
-          } else {
-            mergedByElement.set(id, { ...kfData, keyframes: clipKeyframes });
-          }
-        }
-      }
-      for (const [id, kfData] of mergedByElement) {
-        setKeyframeCache(`${sf}#${id}`, kfData);
-        setKeyframeCache(id, kfData);
-        if (sf !== "index.html") setKeyframeCache(`index.html#${id}`, kfData);
-      }
+    // The active file first: it owns the selection, and each file clears only
+    // its own cache entries, so the order just decides who writes the bare
+    // `id` alias last.
+    const files = Array.from(
+      new Set([sourceFile, ...(compositionSrcKey ? compositionSrcKey.split("|") : [])]),
+    );
+    const doc = iframeRef?.current?.contentDocument;
+    // Everything the previous scan cached for a file this one no longer covers
+    // (the composition just switched away from) has no owner left to clear it.
+    pruneKeyframeCacheToFiles(files);
+    Promise.all(files.map((sf) => populateKeyframeCacheFromAst(projectId, sf, doc))).then(() => {
       astFetchDoneRef.current = fetchKey;
     });
     // elementCount is in the deps because new timeline elements (e.g. after a
@@ -517,7 +403,7 @@ export function usePopulateKeyframeCacheForFile(
     // iframeRef is read for DOM selector resolution but intentionally not a dep
     // (it's a stable ref; the separate runtime-scan effect owns iframe timing).
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [projectId, sourceFile, version, elementCount, domClipChildrenKey]);
+  }, [projectId, sourceFile, version, elementCount, domClipChildrenKey, compositionSrcKey]);
 
   // Separate effect for runtime keyframe discovery — polls until the iframe
   // has loaded GSAP timelines, independent of the AST fetch lifecycle.

package/src/hooks/usePopulateKeyframeCacheForFile.test.tsx

@@ -0,0 +1,68 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { usePopulateKeyframeCacheForFile } from "./useGsapTweenCache";
+import { usePlayerStore } from "../player/store/playerStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+function HookHost() {
+  usePopulateKeyframeCacheForFile("demo", "index.html", 1);
+  return null;
+}
+
+let root: Root | null = null;
+let container: HTMLElement | null = null;
+
+beforeEach(() => {
+  usePlayerStore.setState({
+    elements: [
+      {
+        id: "lab",
+        tag: "div",
+        start: 0,
+        duration: 12,
+        track: 1,
+        compositionSrc: "compositions/keyframe-lab.html",
+      },
+    ] as never,
+  });
+});
+
+afterEach(() => {
+  if (root) {
+    act(() => root?.unmount());
+    root = null;
+  }
+  container?.remove();
+  vi.unstubAllGlobals();
+});
+
+describe("usePopulateKeyframeCacheForFile", () => {
+  it("loads every sub-composition file the timeline shows, not just the active one", async () => {
+    // Keyframe lanes must be populated when the project opens. Fetching only the
+    // active file left them empty until a clip from the sub-composition was
+    // selected (which is the only thing that switched `sourceFile`).
+    const urls: string[] = [];
+    const fetchMock = vi.fn((input: RequestInfo | URL) => {
+      urls.push(String(input));
+      return Promise.resolve({ ok: true, json: () => Promise.resolve({ animations: [] }) });
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    act(() => {
+      container = document.createElement("div");
+      document.body.appendChild(container);
+      root = createRoot(container);
+      root.render(<HookHost />);
+    });
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    expect(urls.some((u) => u.endsWith("/index.html"))).toBe(true);
+    expect(urls.some((u) => u.includes("keyframe-lab.html"))).toBe(true);
+  });
+});

package/src/hooks/useStudioContextValue.test.ts

@@ -0,0 +1,93 @@
+// @vitest-environment happy-dom
+
+import React from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import type { RightInspectorPanes } from "../utils/studioHelpers";
+import { makeSelection } from "./domSelectionTestHarness";
+import { useInspectorState, type InspectorState } from "./useStudioContextValue";
+
+interface HarnessProps {
+  rightPanelTab: string;
+  rightInspectorPanes: RightInspectorPanes;
+  rightCollapsed: boolean;
+  isPlaying: boolean;
+  isGestureRecording: boolean;
+  domEditSelection: DomEditSelection | null;
+}
+
+function renderInspectorState(props: HarnessProps): InspectorState {
+  let state: InspectorState | null = null;
+
+  function Harness() {
+    state = useInspectorState(
+      props.rightPanelTab,
+      props.rightInspectorPanes,
+      props.rightCollapsed,
+      props.isPlaying,
+      props.domEditSelection,
+      props.isGestureRecording,
+    );
+    return null;
+  }
+
+  renderToStaticMarkup(React.createElement(Harness));
+  if (!state) throw new Error("Expected inspector state");
+  return state;
+}
+
+function selectedProps(
+  overrides: Partial<HarnessProps> = {},
+): HarnessProps & { domEditSelection: DomEditSelection } {
+  const element = document.createElement("div");
+  return {
+    rightPanelTab: "renders",
+    rightInspectorPanes: { layers: false, design: false },
+    rightCollapsed: true,
+    isPlaying: false,
+    isGestureRecording: false,
+    domEditSelection: makeSelection("Selected", element),
+    ...overrides,
+  };
+}
+
+describe("useInspectorState", () => {
+  it("shows the motion path for pure selection with the inspector collapsed", () => {
+    expect(renderInspectorState(selectedProps()).shouldShowMotionPath).toBe(true);
+  });
+
+  it("hides the motion path without a selection", () => {
+    expect(
+      renderInspectorState({ ...selectedProps(), domEditSelection: null }).shouldShowMotionPath,
+    ).toBe(false);
+  });
+
+  it("hides the motion path during playback", () => {
+    expect(renderInspectorState(selectedProps({ isPlaying: true })).shouldShowMotionPath).toBe(
+      false,
+    );
+  });
+
+  it("hides the motion path during gesture recording", () => {
+    expect(
+      renderInspectorState(selectedProps({ isGestureRecording: true })).shouldShowMotionPath,
+    ).toBe(false);
+  });
+
+  it("keeps selected DOM bounds coupled to the inspector or variables panel", () => {
+    expect(renderInspectorState(selectedProps()).shouldShowSelectedDomBounds).toBe(false);
+    expect(
+      renderInspectorState(
+        selectedProps({
+          rightPanelTab: "design",
+          rightInspectorPanes: { layers: false, design: true },
+        }),
+      ).shouldShowSelectedDomBounds,
+    ).toBe(true);
+    expect(
+      renderInspectorState(selectedProps({ rightPanelTab: "variables" }))
+        .shouldShowSelectedDomBounds,
+    ).toBe(true);
+  });
+});

package/src/hooks/useStudioContextValue.ts

@@ -1,5 +1,6 @@
 import { useCallback, useMemo, useRef, useState, type DragEvent } from "react";
 import { STUDIO_INSPECTOR_PANELS_ENABLED } from "../components/editor/manualEditingAvailability";
+import type { DomEditSelection } from "../components/editor/domEditing";
 import type { StudioContextValue } from "../contexts/StudioContext";
 import type { RightInspectorPanes } from "../utils/studioHelpers";
 import type { TimelineFileDropHandler } from "./useTimelineEditingTypes";
@@ -69,6 +70,7 @@ export interface InspectorState {
   designPanelActive: boolean;
   inspectorPanelActive: boolean;
   inspectorButtonActive: boolean;
+  shouldShowMotionPath: boolean;
   shouldShowSelectedDomBounds: boolean;
 }
 
@@ -77,6 +79,7 @@ export function useInspectorState(
   rightInspectorPanes: RightInspectorPanes,
   rightCollapsed: boolean,
   isPlaying: boolean,
+  domEditSelection: DomEditSelection | null,
   isGestureRecording?: boolean,
 ): InspectorState {
   // fallow-ignore-next-line complexity
@@ -93,8 +96,12 @@ export function useInspectorState(
       inspectorPanelActive,
       inspectorButtonActive:
         STUDIO_INSPECTOR_PANELS_ENABLED && !rightCollapsed && inspectorPanelActive,
-      // Keep the selection box + motion path drawn even when the Inspector is
-      // collapsed — closing the panel shouldn't visually deselect the element.
+      // Deliberately wider than shouldShowSelectedDomBounds: the on-canvas path
+      // handles ARE the arc-drag affordance, so gating them on an open Inspector
+      // would make keyframe path editing reachable only from a side panel.
+      shouldShowMotionPath: !!domEditSelection && !isPlaying && !isGestureRecording,
+      // Keep the selection box drawn even when the Inspector is collapsed —
+      // closing the panel shouldn't visually deselect the element.
       // The Variables tab also works against the canvas selection (bind card),
       // so the selection outline stays visible there too.
       shouldShowSelectedDomBounds:
@@ -102,7 +109,14 @@ export function useInspectorState(
         !isPlaying &&
         !isGestureRecording,
     };
-  }, [rightPanelTab, rightInspectorPanes, rightCollapsed, isPlaying, isGestureRecording]);
+  }, [
+    rightPanelTab,
+    rightInspectorPanes,
+    rightCollapsed,
+    isPlaying,
+    isGestureRecording,
+    domEditSelection,
+  ]);
 }
 
 // fallow-ignore-next-line complexity

package/src/hooks/useStudioTestHooks.ts

@@ -0,0 +1,63 @@
+import { useEffect } from "react";
+import type { DomEditSelection } from "../components/editor/domEditing";
+
+interface StudioTestHookDeps {
+  previewIframeRef: React.MutableRefObject<HTMLIFrameElement | null>;
+  buildDomSelectionFromTarget: (target: HTMLElement) => Promise<DomEditSelection | null>;
+  applyDomSelection: (
+    selection: DomEditSelection | null,
+    options?: { revealPanel?: boolean },
+  ) => void;
+}
+
+interface StudioTestApi {
+  selectByDomId: (id: string) => Promise<boolean>;
+}
+
+declare global {
+  interface Window {
+    __studioTest?: StudioTestApi;
+  }
+}
+
+/**
+ * Dev-only headless-QA shortcut. Selecting an element normally requires a
+ * pixel-precise click inside the preview iframe, which automated verification
+ * can't reliably land. `window.__studioTest.selectByDomId(id)` resolves the
+ * DomEditSelection for a preview element by id and reveals the inspector —
+ * exactly what a click does — so a driver can open the property/ease panels and
+ * then focus a segment via `__playerStore.getState().setFocusedEaseSegment`.
+ * No-op in production builds.
+ */
+export function useStudioTestHooks({
+  previewIframeRef,
+  buildDomSelectionFromTarget,
+  applyDomSelection,
+}: StudioTestHookDeps): void {
+  // eslint-disable-next-line no-restricted-syntax
+  useEffect(() => {
+    let isDev = false;
+    try {
+      isDev = import.meta.env.DEV === true;
+    } catch {
+      isDev = false;
+    }
+    if (!isDev || typeof window === "undefined") return;
+    const api: StudioTestApi = {
+      selectByDomId: async (id: string): Promise<boolean> => {
+        const element = previewIframeRef.current?.contentDocument?.getElementById(id) ?? null;
+        if (!element) return false;
+        const selection = await buildDomSelectionFromTarget(element);
+        if (!selection) return false;
+        applyDomSelection(selection, { revealPanel: true });
+        return true;
+      },
+    };
+    window.__studioTest = api;
+    return () => {
+      // delete, not `= undefined`: an own key holding undefined keeps
+      // `"__studioTest" in window` true, which defeats feature detection.
+      delete window.__studioTest;
+    };
+  }, [applyDomSelection, buildDomSelectionFromTarget, previewIframeRef]);
+}