@hyperframes/studio 0.8.105 → 0.8.106

package/src/components/editor/propertyPanelFont.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import {
   googleFontStylesheetUrl,
   POPULAR_GOOGLE_FONT_FAMILIES,
@@ -19,6 +19,7 @@ import {
   type LocalFontData,
 } from "./propertyPanelHelpers";
 import { useTrackDesignInput } from "../../contexts/DesignPanelInputContext";
+import { runWhenInputIdle } from "./overlayFrameLoop";
 
 /* ------------------------------------------------------------------ */
 /*  Font helper functions                                              */
@@ -117,6 +118,62 @@ function loadImportedFontStylesheet(asset: ImportedFontAsset): void {
   document.head.appendChild(style);
 }
 
+type FontLists = {
+  loaded: boolean;
+  google: readonly string[];
+  googleKeys: ReadonlySet<string>;
+  installed: string[];
+};
+
+let fontLists: FontLists = {
+  loaded: false,
+  google: POPULAR_GOOGLE_FONT_FAMILIES,
+  googleKeys: new Set(POPULAR_GOOGLE_FONT_FAMILIES.map((f) => f.toLowerCase())),
+  installed: [],
+};
+let fontListsRequest: Promise<void> | null = null;
+const fontListListeners = new Set<() => void>();
+
+async function fetchFontList(url: string): Promise<string[]> {
+  const data = (await (await fetch(url)).json()) as { fonts?: unknown };
+  if (!Array.isArray(data.fonts)) throw new Error(`${url} returned no font list`);
+  return data.fonts as string[];
+}
+
+function loadFontLists(): void {
+  if (fontLists.loaded) return;
+  fontListsRequest ??= Promise.all([
+    fetchFontList("/api/fonts"),
+    fetchFontList("/api/fonts/google"),
+  ])
+    .then(([installed, google]) => {
+      const names = google.concat(POPULAR_GOOGLE_FONT_FAMILIES);
+      const families: string[] = [];
+      const googleKeys = new Set<string>();
+      let next = 0;
+      runWhenInputIdle((timeLeft) => {
+        while (next < names.length && timeLeft() > 0) {
+          const batch = names.slice(next, next + 200);
+          next += batch.length;
+          families.push(...uniqueFontFamilies(batch, googleKeys));
+        }
+        if (next < names.length) return false;
+        fontLists = { loaded: true, google: families, googleKeys, installed };
+        for (const listener of fontListListeners) listener();
+        return true;
+      });
+    })
+    .catch(() => {
+      fontListsRequest = null;
+    });
+}
+
+function subscribeFontLists(listener: () => void): () => void {
+  fontListListeners.add(listener);
+  loadFontLists();
+  return () => fontListListeners.delete(listener);
+}
+
 /* ------------------------------------------------------------------ */
 /*  FontFamilyField                                                    */
 /* ------------------------------------------------------------------ */
@@ -146,9 +203,8 @@ export function FontFamilyField({
   const [activeIndex, setActiveIndex] = useState(-1);
   const [localFonts, setLocalFonts] = useState<string[]>([]);
   const [localFontData, setLocalFontData] = useState<LocalFontData[]>([]);
-  const [googleFonts, setGoogleFonts] = useState<string[]>(() => [...POPULAR_GOOGLE_FONT_FAMILIES]);
+  const lists = useSyncExternalStore(subscribeFontLists, () => fontLists);
   const [loadingLocalFonts, setLoadingLocalFonts] = useState(false);
-  const [loadingGoogleFonts, setLoadingGoogleFonts] = useState(false);
   const [importingFonts, setImportingFonts] = useState(false);
   const [fontNotice, setFontNotice] = useState<string | null>(null);
   const canQueryLocalFonts =
@@ -175,46 +231,18 @@ export function FontFamilyField({
   }, [open]);
 
   useEffect(() => {
-    let cancelled = false;
-    void fetch("/api/fonts")
-      .then((r) => (r.ok ? r.json() : null))
-      .then((data: { fonts?: string[] } | null) => {
-        if (cancelled || !Array.isArray(data?.fonts)) return;
-        setLocalFonts((cur) => uniqueFontFamilies([...cur, ...data.fonts!]));
-      })
-      .catch(() => undefined);
-    return () => {
-      cancelled = true;
-    };
-  }, []);
-
-  useEffect(() => {
-    let cancelled = false;
-    setLoadingGoogleFonts(true);
-    void fetch("/api/fonts/google")
-      .then((r) => (r.ok ? r.json() : null))
-      .then((data: { fonts?: string[] } | null) => {
-        if (cancelled || !Array.isArray(data?.fonts)) return;
-        setGoogleFonts(uniqueFontFamilies([...data.fonts!, ...POPULAR_GOOGLE_FONT_FAMILIES]));
-      })
-      .catch(() => undefined)
-      .finally(() => {
-        if (!cancelled) setLoadingGoogleFonts(false);
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, []);
+    if (open) loadFontLists();
+  }, [open]);
 
   useEffect(() => {
-    if (googleFonts.some((f) => f.toLowerCase() === currentFamily.toLowerCase())) {
+    if (lists.googleKeys.has(currentFamily.toLowerCase())) {
       loadGoogleFontStylesheet(currentFamily);
     }
     const imported = importedFonts.find(
       (f) => f.family.toLowerCase() === currentFamily.toLowerCase(),
     );
     if (imported) loadImportedFontStylesheet(imported);
-  }, [currentFamily, googleFonts, importedFonts]);
+  }, [currentFamily, lists, importedFonts]);
 
   const loadBrowserLocalFonts = async () => {
     if (!canQueryLocalFonts || !window.queryLocalFonts) {
@@ -278,24 +306,19 @@ export function FontFamilyField({
   const options = useMemo(() => {
     if (!open) return [];
     const documentFonts = collectDocumentFontFamilies();
-    const googleSet = new Set(googleFonts.map((f) => f.toLowerCase()));
-    const taggedLocal = localFonts.map(
-      (family): FontOption => ({
-        family,
-        source: googleSet.has(family.toLowerCase()) ? "Google" : "Local",
-      }),
-    );
     return sortFontOptions(
       uniqueFontOptions([
         { family: currentFamily, source: "Current" },
         ...documentFonts.map((f): FontOption => ({ family: f, source: "Document" })),
         ...projectFontAssets,
-        ...googleFonts.map((f): FontOption => ({ family: f, source: "Google" })),
-        ...taggedLocal,
+        ...lists.google.map((f): FontOption => ({ family: f, source: "Google" })),
+        ...[...lists.installed, ...localFonts].map(
+          (f): FontOption => ({ family: f, source: "Local" }),
+        ),
         ...DEFAULT_FONT_FAMILIES.map((f): FontOption => ({ family: f, source: "System" })),
       ]),
     );
-  }, [open, currentFamily, googleFonts, localFonts, projectFontAssets]);
+  }, [open, currentFamily, lists, localFonts, projectFontAssets]);
 
   const filteredOptions = useMemo(() => {
     const matches = options.filter((o) => fontMatchesQuery(o.family, query));
@@ -392,7 +415,7 @@ export function FontFamilyField({
           type="text"
           value={query}
           disabled={disabled}
-          placeholder={loadingGoogleFonts ? "Loading Google Fonts..." : "Search fonts"}
+          placeholder={lists.loaded ? "Search fonts" : "Loading Google Fonts..."}
           onChange={(e) => {
             setQuery(e.target.value);
             setActiveIndex(-1);

package/src/components/editor/propertyPanelHelpers.ts

@@ -125,8 +125,7 @@ export function localFontSortScore(font: LocalFontData): number {
   return 3;
 }
 
-export function uniqueFontFamilies(values: string[]): string[] {
-  const seen = new Set<string>();
+export function uniqueFontFamilies(values: string[], seen = new Set<string>()): string[] {
   return values.reduce<string[]>((result, value) => {
     const family = value.trim();
     if (!family) return result;

package/src/components/editor/studioCodeTheme.test.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+const read = (file: string) => readFileSync(new URL(file, import.meta.url), "utf8");
+const source = read("./studioCodeTheme.ts");
+const themeCss = read("../../styles/theme.css");
+
+describe("the code editor theme", () => {
+  it("takes every colour from a token theme.css declares", () => {
+    const used = [...source.matchAll(/var\((--color-[\w-]+)\)/g)].map((match) => match[1]!);
+    expect(used.length).toBeGreaterThan(20);
+    for (const token of new Set(used)) expect(themeCss, token).toContain(`${token}:`);
+  });
+
+  it("paints no literal colour of its own", () => {
+    expect(source).not.toMatch(
+      /#[\da-f]{3,8}\b|\b(rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix)\(|"(white|black|red|orange|yellow|green|blue|purple|pink|gray|grey|silver|lime|cyan|magenta)"/i,
+    );
+  });
+});

package/src/components/editor/studioCodeTheme.ts

@@ -0,0 +1,99 @@
+import { HighlightStyle, syntaxHighlighting } from "@codemirror/language";
+import { EditorView } from "@codemirror/view";
+import { tags as t } from "@lezer/highlight";
+
+// One Dark's layout on Studio's tokens: every colour is a theme.css variable, so the editor
+// follows the light or dark theme the page paints with no editor reconfiguration.
+const editorTheme = EditorView.theme({
+  "&": { height: "100%", color: "var(--color-text-0)", backgroundColor: "var(--color-surface)" },
+  ".cm-scroller": { overflow: "auto" },
+  ".cm-content": { caretColor: "var(--color-text-0)" },
+  ".cm-cursor, .cm-dropCursor": { borderLeftColor: "var(--color-text-0)" },
+  "&.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground, .cm-selectionBackground, .cm-content ::selection":
+    { backgroundColor: "var(--color-on)" },
+  ".cm-activeLine": { backgroundColor: "var(--color-hover)" },
+  ".cm-selectionMatch": {
+    backgroundColor: "transparent",
+    outline: "1px solid var(--color-text-muted)",
+  },
+  ".cm-searchMatch": {
+    backgroundColor: "transparent",
+    outline: "1px solid var(--color-text-muted)",
+  },
+  ".cm-searchMatch.cm-searchMatch-selected": {
+    backgroundColor: "transparent",
+    outline: "2px solid var(--color-accent-ink)",
+  },
+  "&.cm-focused .cm-matchingBracket, &.cm-focused .cm-nonmatchingBracket": {
+    backgroundColor: "var(--color-on)",
+  },
+  ".cm-gutters": {
+    backgroundColor: "var(--color-surface)",
+    color: "var(--color-text-muted)",
+    border: "none",
+  },
+  ".cm-activeLineGutter": { backgroundColor: "var(--color-hover)", color: "var(--color-text-2)" },
+  ".cm-foldPlaceholder": {
+    backgroundColor: "transparent",
+    border: "none",
+    color: "var(--color-text-2)",
+  },
+  ".cm-panels": { backgroundColor: "var(--color-raised)", color: "var(--color-text-0)" },
+  ".cm-panels.cm-panels-top": { borderBottom: "1px solid var(--color-border)" },
+  ".cm-panels.cm-panels-bottom": { borderTop: "1px solid var(--color-border)" },
+  ".cm-textfield": {
+    backgroundColor: "var(--color-input)",
+    color: "var(--color-text-0)",
+    border: "1px solid var(--color-border-input)",
+  },
+  ".cm-button": {
+    backgroundImage: "none",
+    backgroundColor: "var(--color-hover)",
+    color: "var(--color-text-0)",
+    border: "1px solid var(--color-border)",
+  },
+  "&.cm-editor .cm-button:active": {
+    backgroundImage: "none",
+    backgroundColor: "var(--color-press)",
+  },
+  ".cm-specialChar": { color: "var(--color-danger-ink)" },
+});
+
+const highlightStyle = HighlightStyle.define([
+  { tag: t.keyword, color: "var(--color-code-keyword)" },
+  {
+    tag: [t.name, t.deleted, t.character, t.propertyName, t.macroName],
+    color: "var(--color-code-name)",
+  },
+  { tag: [t.function(t.variableName), t.labelName], color: "var(--color-code-function)" },
+  { tag: [t.color, t.constant(t.name), t.standard(t.name)], color: "var(--color-code-constant)" },
+  { tag: [t.definition(t.name), t.separator], color: "var(--color-text-0)" },
+  {
+    tag: [
+      t.typeName,
+      t.className,
+      t.number,
+      t.changed,
+      t.annotation,
+      t.modifier,
+      t.self,
+      t.namespace,
+    ],
+    color: "var(--color-code-type)",
+  },
+  {
+    tag: [t.operator, t.operatorKeyword, t.url, t.escape, t.regexp, t.special(t.string)],
+    color: "var(--color-code-operator)",
+  },
+  { tag: [t.meta, t.comment], color: "var(--color-code-comment)" },
+  { tag: t.strong, fontWeight: "bold" },
+  { tag: t.emphasis, fontStyle: "italic" },
+  { tag: t.strikethrough, textDecoration: "line-through" },
+  { tag: t.link, color: "var(--color-code-comment)", textDecoration: "underline" },
+  { tag: t.heading, fontWeight: "bold", color: "var(--color-code-name)" },
+  { tag: [t.atom, t.bool, t.special(t.variableName)], color: "var(--color-code-constant)" },
+  { tag: [t.processingInstruction, t.string, t.inserted], color: "var(--color-code-string)" },
+  { tag: t.invalid, color: "var(--color-danger-ink)" },
+]);
+
+export const studioCodeTheme = [editorTheme, syntaxHighlighting(highlightStyle)];

package/src/components/editor/useDomEditNudge.test.tsx

@@ -124,6 +124,37 @@ describe("useDomEditNudge — selection cleanup keyed on stable identity", () =>
     element.remove();
   });
 
+  it("leaves arrows on a focused slider alone", () => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const root = createRoot(host);
+    const element = document.createElement("div");
+    element.id = "dot-a";
+    const slider = document.createElement("div");
+    slider.setAttribute("role", "slider");
+    document.body.append(element, slider);
+    const commit = vi.fn();
+    act(() => {
+      root.render(
+        React.createElement(Harness, {
+          selection: makeSelection("Dot", element),
+          onPathOffsetCommit: commit,
+        }),
+      );
+    });
+    act(() => {
+      slider.dispatchEvent(
+        new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true, cancelable: true }),
+      );
+      vi.advanceTimersByTime(CANVAS_NUDGE_COMMIT_DEBOUNCE_MS + 10);
+    });
+    expect(commit).not.toHaveBeenCalled();
+    act(() => root.unmount());
+    host.remove();
+    element.remove();
+    slider.remove();
+  });
+
   it("still flushes the burst when the selection actually changes to a different element", () => {
     const host = document.createElement("div");
     document.body.append(host);

package/src/components/editor/useDomEditNudge.ts

@@ -7,7 +7,7 @@
  */
 import { useCallback, useEffect, useRef, type RefObject } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
-import { isTypingTarget } from "../../utils/typingTarget";
+import { ownsPlainKeys } from "../../utils/typingTarget";
 import { acquireCanvasNudgeKeys } from "../../utils/canvasNudgeGate";
 import type { DomEditSelection } from "./domEditing";
 import {
@@ -132,7 +132,7 @@ function resolveSingleNudgeTarget(
 function shouldIgnoreNudgeKey(p: UseDomEditNudgeParams, event: KeyboardEvent): boolean {
   if (!p.allowCanvasMovement || event.defaultPrevented) return true;
   if (p.gestureRef.current || p.groupGestureRef.current || p.blockedMoveRef.current) return true;
-  return isTypingTarget(event.target);
+  return ownsPlainKeys(event.target);
 }
 
 export function useDomEditNudge(params: UseDomEditNudgeParams): { flushNudge: () => void } {

package/src/components/editor/useInlineTextEditing.tsx

@@ -44,7 +44,7 @@ export function useInlineTextEditing(
 } {
   const actions = useDomEditActionsContextOptional();
   const inlineText = useInlineTextEdit({
-    onCommit: (commit) => void actions?.handleDomRichTextCommit(commit),
+    onCommit: (commit) => actions?.handleDomRichTextCommit(commit),
     onPause: () => usePlayerStore.getState().setIsPlaying(false),
   });
   const lastPressRef = useRef<PressMark | null>(null);

package/src/components/editor/useMotionPathData.test.tsx

@@ -0,0 +1,64 @@
+// @vitest-environment happy-dom
+import { act, useRef } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { useMotionPathData } from "./useMotionPathData";
+import { resetOverlayFrameLoopForTests } from "./overlayFrameLoop";
+import { usePlayerStore } from "../../player/store/playerStore";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+
+const originalRaf = window.requestAnimationFrame;
+let frames: Array<() => void> = [];
+const runFrames = (count: number) => {
+  for (let i = 0; i < count; i++) {
+    const batch = frames;
+    frames = [];
+    act(() => {
+      for (const frame of batch) frame();
+      vi.advanceTimersByTime(16);
+    });
+  }
+};
+
+beforeEach(() => {
+  vi.useFakeTimers({
+    toFake: ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "performance"],
+  });
+  window.requestAnimationFrame = ((callback: FrameRequestCallback) =>
+    frames.push(() => callback(performance.now()))) as typeof window.requestAnimationFrame;
+  usePlayerStore.setState({ previewBooted: true, motionPathArmed: false });
+});
+
+afterEach(() => {
+  resetOverlayFrameLoopForTests();
+  window.requestAnimationFrame = originalRaf;
+  vi.useRealTimers();
+  usePlayerStore.setState({ previewBooted: false, motionPathArmed: false });
+  document.body.innerHTML = "";
+});
+
+it("reads no layout per frame until there is a path or a create ring to draw", () => {
+  const iframe = document.createElement("iframe");
+  document.body.append(iframe);
+  const reads = vi.spyOn(iframe, "getBoundingClientRect");
+  function Probe() {
+    const ref = useRef(iframe);
+    useMotionPathData(ref, "#box");
+    return null;
+  }
+  const host = document.createElement("div");
+  document.body.append(host);
+  const root = createRoot(host);
+  try {
+    act(() => root.render(<Probe />));
+    runFrames(10);
+    expect(reads).not.toHaveBeenCalled();
+
+    act(() => usePlayerStore.setState({ motionPathArmed: true }));
+    runFrames(10);
+    expect(reads).toHaveBeenCalled();
+  } finally {
+    act(() => root.unmount());
+  }
+});

package/src/components/editor/useMotionPathData.ts

@@ -3,6 +3,7 @@ import { readRuntimeKeyframes } from "../../hooks/gsapRuntimeKeyframes";
 import { isElementVisibleForOverlay } from "./domEditOverlayGeometry";
 import { buildMotionPathGeometry, type MotionPathGeometry } from "./motionPathGeometry";
 import { subscribeOverlayFrame } from "./overlayFrameLoop";
+import { usePlayerStore } from "../../player/store/playerStore";
 
 type Rect = { left: number; top: number; width: number; height: number };
 
@@ -114,6 +115,8 @@ export function useMotionPathData(
   // Perspective magnification (1/m44) of the selected element — applied to the
   // path's offset points so depth (translateZ) elements' paths track on screen.
   const [pScale, setPScale] = useState(1);
+  const armed = usePlayerStore((s) => s.motionPathArmed);
+  const drawn = geometry !== null || armed;
 
   useEffect(() => {
     if (!selector) {
@@ -122,6 +125,7 @@ export function useMotionPathData(
       return;
     }
     setHome(null);
+    if (!drawn) return;
     const tick = () => {
       const el = iframeRef.current;
       if (el) {
@@ -155,7 +159,7 @@ export function useMotionPathData(
       }
     };
     return subscribeOverlayFrame(tick);
-  }, [selector, iframeRef]);
+  }, [selector, iframeRef, drawn]);
 
   useEffect(() => {
     if (!selector) {

package/src/hooks/appHotkeysDispatch.ts

@@ -3,7 +3,7 @@ import { usePlayerStore } from "../player";
 import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
 import { useDockLayoutStore } from "../components/dock/dockLayoutStore";
-import { isTypingTarget } from "../utils/typingTarget";
+import { isTypingTarget, ownsPlainKeys } from "../utils/typingTarget";
 import { isEditableTarget } from "../utils/timelineDiscovery";
 import { shouldIgnoreHistoryShortcut } from "../utils/studioHelpers";
 import { canSplitElement } from "../utils/timelineElementSplit";
@@ -153,6 +153,7 @@ export function dispatchModifierKey(
  *  Delete arbitration between keyframes, an automation range and the clip can
  *  be asserted without standing up the whole hook. */
 export function dispatchPlainKey(event: KeyboardEvent, key: string, cb: HotkeyCallbacks): void {
+  if (ownsPlainKeys(event.target)) return;
   if (key === STUDIO_PLAIN_KEYS.fullscreen && !event.shiftKey && !event.altKey) {
     event.preventDefault();
     if (document.fullscreenElement) void document.exitFullscreen();

package/src/hooks/previewPromotionSelection.test.tsx

@@ -0,0 +1,180 @@
+// @vitest-environment happy-dom
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { resolveElementForOverlay } from "../components/editor/domEditOverlayGeometry";
+import {
+  makePreview,
+  mountPlayerWithPreview,
+  paintShadow,
+  resetPlayerStore,
+  type TimelinePlayerApi,
+} from "../player/hooks/timelinePlayerTestHarness";
+import { announcePreviewPromoted } from "../player/sceneSwap";
+import { stageElementOffset } from "./elementOffsetStager";
+import { savePlainRotation } from "./plainRotation";
+import { useDomEditPreviewSync } from "./useDomEditPreviewSync";
+import { useLivePreviewIframe } from "./useLivePreviewIframe";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+vi.mock("../utils/gsapSoftReload", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/gsapSoftReload")>()),
+  ensureMotionPathPluginLoaded: vi.fn(),
+}));
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+const previewWithTitle = (query = "") => makePreview('<h1 id="title">Title</h1>', query);
+
+const titleOf = (iframe: HTMLIFrameElement | null) =>
+  iframe!.contentDocument!.getElementById("title") as HTMLElement;
+
+const selectionOf = (element: HTMLElement) =>
+  ({ element, id: "title", selector: "#title", label: "title" }) as unknown as DomEditSelection;
+
+/** A host shaped like Desktop's: it reads its iframe once and never re-renders for a reload. */
+function mountHost(followPromotions: boolean) {
+  const selectionRef = { current: null as DomEditSelection | null };
+  function Session({ host }: { host: HTMLIFrameElement }) {
+    const live = useLivePreviewIframe(host);
+    useDomEditPreviewSync({
+      previewIframe: followPromotions ? live : host,
+      activeCompPath: null,
+      captionEditMode: false,
+      domEditSelectionRef: selectionRef,
+      domEditGroupSelectionsRef: { current: [] },
+      domEditSelection: selectionRef.current,
+      refreshDomEditGroupSelectionsFromPreview: async () => {},
+      applyDomSelection: (selection) => void (selectionRef.current = selection),
+      buildDomSelectionFromTarget: async (element) => selectionOf(element),
+      refreshPreviewDocumentVersion: () => {},
+      syncPreviewHotkeys: () => {},
+      applyStudioManualEditsToPreviewRef: { current: async () => {} },
+    });
+    return null;
+  }
+  const live = previewWithTitle();
+  const player = mountPlayerWithPreview(live);
+  selectionRef.current = selectionOf(titleOf(live));
+  const sessionRoot = createRoot(document.body.appendChild(document.createElement("div")));
+  act(() => sessionRoot.render(React.createElement(Session, { host: live })));
+  const unmount = () => {
+    act(() => sessionRoot.unmount());
+    act(() => player.root.unmount());
+  };
+  return { player: player.getApi, selectionRef, live, unmount };
+}
+
+/** The real shadow reload: load a shadow, report it painted, and let the player promote it. */
+async function promoteShadow(player: () => TimelinePlayerApi): Promise<HTMLIFrameElement> {
+  act(() => player().refreshPlayer());
+  const shadow = previewWithTitle("?_t=1");
+  await paintShadow(player, shadow);
+  expect(player().iframeRef.current).toBe(shadow);
+  return shadow;
+}
+
+describe("a shadow reload promoted without a host re-render", () => {
+  // A host stage holds both players, each with the same #title, in either order.
+  it.each([
+    ["second", true],
+    ["first", false],
+  ])(
+    "with the live preview %s on the stage, the selection, overlay, rotate and move land on it",
+    async (_, liveSecond) => {
+      const host = mountHost(true);
+      const shadow = await promoteShadow(host.player);
+      // The stage only orders the two players; nothing here needs their pages to load.
+      for (const frame of [host.live, shadow]) frame.removeAttribute("src");
+      const stage = document.body.appendChild(document.createElement("div"));
+      stage.append(...(liveSecond ? [host.live, shadow] : [shadow, host.live]));
+
+      const selection = host.selectionRef.current!;
+      expect(selection.element).toBe(titleOf(shadow));
+      const overlayNode = resolveElementForOverlay(shadow.contentDocument!, selection, null, {
+        current: null,
+      });
+      expect(overlayNode).toBe(selection.element);
+
+      const commitPositionPatchToHtml = vi.fn(async () => {});
+      await savePlainRotation({ commitPositionPatchToHtml }, selection, { angle: 30 });
+      await stageElementOffset(
+        { commitPositionPatchToHtml, showToast: vi.fn() },
+        selection,
+        { x: 10, y: 5 },
+        true,
+      ).save();
+      expect(titleOf(shadow).style.getPropertyValue("rotate")).toBe("30deg");
+      expect(titleOf(shadow).style.getPropertyValue("translate")).toBe("10px 5px");
+      expect(titleOf(host.live).getAttribute("style")).toBeNull();
+      host.unmount();
+    },
+  );
+
+  it("left the selection on the retired node when the session kept the host's first iframe", async () => {
+    const host = mountHost(false);
+    await promoteShadow(host.player);
+    expect(host.selectionRef.current!.element).toBe(titleOf(host.live));
+    host.unmount();
+  });
+});
+
+describe("useLivePreviewIframe", () => {
+  function track(host: HTMLIFrameElement) {
+    const seen: Array<HTMLIFrameElement | null> = [];
+    function Probe({ iframe }: { iframe: HTMLIFrameElement }) {
+      seen.push(useLivePreviewIframe(iframe));
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe, { iframe: host })));
+    const rerender = (iframe: HTMLIFrameElement) =>
+      act(() => root.render(React.createElement(Probe, { iframe })));
+    return { live: () => seen.at(-1), rerender, root };
+  }
+
+  it("follows each promotion of its own preview and ignores another preview's", () => {
+    const [a, b, c, other] = [0, 1, 2, 3].map(() => document.createElement("iframe"));
+    const probe = track(a!);
+    act(() => announcePreviewPromoted({ retired: other!, live: c! }));
+    expect(probe.live()).toBe(a);
+    act(() => announcePreviewPromoted({ retired: a!, live: b! }));
+    expect(probe.live()).toBe(b);
+    act(() => announcePreviewPromoted({ retired: b!, live: c! }));
+    expect(probe.live()).toBe(c);
+    act(() => probe.root.unmount());
+  });
+
+  it("lands on the same iframe wrapped twice, as when a host wraps what it hands the session", () => {
+    const [a, b, c] = [0, 1, 2].map(() => document.createElement("iframe"));
+    let seen: { outer: HTMLIFrameElement | null; inner: HTMLIFrameElement | null } | null = null;
+    function Probe({ host }: { host: HTMLIFrameElement }) {
+      const outer = useLivePreviewIframe(host);
+      seen = { outer, inner: useLivePreviewIframe(outer) };
+      return null;
+    }
+    const root = createRoot(document.createElement("div"));
+    act(() => root.render(React.createElement(Probe, { host: a! })));
+    act(() => announcePreviewPromoted({ retired: a!, live: b! }));
+    expect(seen).toEqual({ outer: b, inner: b });
+    act(() => announcePreviewPromoted({ retired: b!, live: c! }));
+    expect(seen).toEqual({ outer: c, inner: c });
+    act(() => root.unmount());
+  });
+
+  it("takes a new host iframe as given, and stops listening on unmount", () => {
+    const [a, b, d] = [0, 1, 2].map(() => document.createElement("iframe"));
+    const probe = track(a!);
+    act(() => announcePreviewPromoted({ retired: a!, live: b! }));
+    probe.rerender(d!);
+    expect(probe.live()).toBe(d);
+    const remove = vi.spyOn(document, "removeEventListener");
+    act(() => probe.root.unmount());
+    expect(remove).toHaveBeenCalledWith("hf-preview-promoted", expect.any(Function));
+  });
+});