@hyperframes/studio 0.8.105 → 0.8.107

package/src/hooks/inspectorSaveReload.test.tsx

@@ -0,0 +1,107 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import {
+  makePreview,
+  mountPlayerWithPreview,
+  paintShadow,
+  resetPlayerStore,
+} from "../player/hooks/timelinePlayerTestHarness";
+import { useDomEditCommits } from "./useDomEditCommits";
+
+Reflect.set(globalThis, "IS_REACT_ACT_ENVIRONMENT", true);
+vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
+vi.mock("../utils/gsapSoftReload", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../utils/gsapSoftReload")>()),
+  ensureMotionPathPluginLoaded: vi.fn(),
+}));
+
+/** The project file; the patch route applies a colour to it, and each preview load serves it. */
+let color = "red";
+const card = () => `<div data-hf-id="hf-card" style="color: ${color}">Card</div>`;
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+  resetPlayerStore();
+});
+
+it("an inspector save made while a reload loads is not undone when that reload goes on screen", async () => {
+  color = "red";
+  let land = () => {};
+  const landed = new Promise<void>((resolve) => (land = resolve));
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: string, init?: RequestInit) => {
+      if (!input.includes("/file-mutations/patch-element/"))
+        return Response.json({ content: card() });
+      await landed;
+      const { operations } = JSON.parse(String(init?.body)) as { operations: { value: string }[] };
+      color = operations[0]!.value;
+      return Response.json({ ok: true, changed: true, matched: true, content: card() });
+    }),
+  );
+  const live = makePreview(card());
+  const player = mountPlayerWithPreview(live);
+  const element = live.contentDocument!.querySelector<HTMLElement>("[data-hf-id]")!;
+  const selection = {
+    element,
+    label: "Card",
+    tagName: "div",
+    sourceFile: "index.html",
+    compositionPath: "index.html",
+    textFields: [],
+    inlineStyles: { color: "red" },
+    computedStyles: {},
+    dataAttributes: {},
+    capabilities: { canSelect: true, canEditStyles: true },
+    hfId: "hf-card",
+    selector: '[data-hf-id="hf-card"]',
+    selectorIndex: 0,
+  } as unknown as DomEditSelection;
+  let commits: ReturnType<typeof useDomEditCommits> | null = null;
+  function Inspector() {
+    commits = useDomEditCommits({
+      activeCompPath: "index.html",
+      previewIframeRef: player.getApi().iframeRef,
+      showToast: () => {},
+      queueDomEditSave: (save) => save(),
+      writeProjectFile: async () => {},
+      editHistory: { recordEdit: async () => {} },
+      fileTree: [],
+      importedFontAssetsRef: { current: [] },
+      projectId: "p1",
+      projectIdRef: { current: "p1" },
+      reloadPreview: () => {},
+      domEditSelection: selection,
+      applyDomSelection: () => {},
+      clearDomSelection: () => {},
+      refreshDomEditSelectionFromPreview: () => {},
+      buildDomSelectionFromTarget: async () => null,
+      readOnlyPreview: false,
+    });
+    return null;
+  }
+  const root = createRoot(document.createElement("div"));
+  act(() => root.render(createElement(Inspector)));
+
+  act(() => player.getApi().refreshPlayer());
+  const beforeSave = makePreview(card(), "?_t=1");
+  let saved: Promise<unknown> = Promise.resolve();
+  act(() => void (saved = commits!.handleDomStyleCommit("color", "green")));
+  await act(async () => {
+    land();
+    await saved;
+  });
+  expect(color).toBe("green");
+
+  const requested = await paintShadow(player.getApi, beforeSave);
+  expect(player.getApi().iframeRef.current, "the file before the save").toBe(live);
+  const fresh = makePreview(card(), "?_t=2");
+  expect(await paintShadow(player.getApi, fresh)).toBeGreaterThan(requested);
+  expect(player.getApi().iframeRef.current).toBe(fresh);
+  act(() => root.unmount());
+  act(() => player.root.unmount());
+});

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));
+  });
+});

package/src/hooks/useAppHotkeys.previewForwarding.test.tsx

@@ -16,6 +16,7 @@ vi.mock("../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
 const domDelete = vi.fn(async () => undefined);
 const historyUndo = vi.fn(async () => ({ ok: false }));
 const historyRedo = vi.fn(async () => ({ ok: false }));
+const settle = vi.fn(async () => undefined);
 let root: Root | null = null;
 let sync: ((iframe: HTMLIFrameElement | null) => void) | null = null;
 
@@ -49,7 +50,7 @@ function Harness() {
     writeProjectFile: vi.fn(async () => undefined),
     showToast: vi.fn(),
     syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
-    waitForPendingDomEditSaves: vi.fn(async () => undefined),
+    settlePendingEdits: settle,
     handleCopy: vi.fn(() => false),
     handlePaste: vi.fn(() => false),
     handleCut: vi.fn(() => false),
@@ -69,6 +70,8 @@ afterEach(() => {
   domDelete.mockClear();
   historyUndo.mockClear();
   historyRedo.mockClear();
+  settle.mockReset();
+  settle.mockImplementation(async () => undefined);
   vi.mocked(trackStudioEvent).mockClear();
 });
 
@@ -122,6 +125,18 @@ describe("preview iframe hotkey forwarding", () => {
     expect(trackStudioEvent).toHaveBeenCalledWith("keyboard_shortcut", { action: "undo" });
   });
 
+  it("settles pending edits, failed ones included, before Cmd+Z steps the history", async () => {
+    let settled!: () => void;
+    settle.mockImplementation(
+      () => new Promise<undefined>((resolve) => (settled = () => resolve(undefined))),
+    );
+    await press(mountWithPreview(), { key: "z", ctrlKey: true });
+    expect(settle).toHaveBeenCalledTimes(1);
+    expect(historyUndo).not.toHaveBeenCalled();
+    await act(async () => settled());
+    expect(historyUndo).toHaveBeenCalledTimes(1);
+  });
+
   it.each([
     ["Shift+Cmd+Z", { key: "Z", metaKey: true, shiftKey: true }],
     ["Ctrl+Y", { key: "y", ctrlKey: true }],

package/src/hooks/useAppHotkeys.test.ts

@@ -60,6 +60,55 @@ afterEach(() => {
   });
 });
 
+describe("keys on a focused slider", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+  const slider = () => {
+    const el = document.createElement("div");
+    el.setAttribute("role", "slider");
+    document.body.append(el);
+    return el;
+  };
+  const from = (target: HTMLElement, init: KeyboardEventInit) => {
+    const event = new KeyboardEvent("keydown", { ...init, bubbles: true, cancelable: true });
+    Object.defineProperty(event, "target", { value: target });
+    return event;
+  };
+
+  it("leaves Delete to the slider instead of deleting the selected clip", () => {
+    usePlayerStore.setState({
+      elements: [bgmElement],
+      selectedElementId: "bgm",
+      selectedElementIds: new Set(["bgm"]),
+    });
+    const cb = callbacks();
+    dispatchPlainKey(from(slider(), { key: "Delete" }), "delete", cb);
+    expect(cb.handleTimelineElementsDelete).not.toHaveBeenCalled();
+    expect(cb.handleTimelineElementDelete).not.toHaveBeenCalled();
+  });
+
+  it.each(["video", "audio"])("leaves Delete to a focused <%s controls>", (tag) => {
+    usePlayerStore.setState({
+      elements: [bgmElement],
+      selectedElementId: "bgm",
+      selectedElementIds: new Set(["bgm"]),
+    });
+    const player = document.body.appendChild(document.createElement(tag));
+    player.setAttribute("controls", "");
+    const cb = callbacks();
+    dispatchPlainKey(from(player, { key: "Delete" }), "delete", cb);
+    expect(cb.handleTimelineElementsDelete).not.toHaveBeenCalled();
+    expect(cb.handleTimelineElementDelete).not.toHaveBeenCalled();
+  });
+
+  it("still undoes with Cmd+Z while a slider has focus", () => {
+    const cb = callbacks();
+    dispatchModifierKey(from(slider(), { key: "z", metaKey: true }), "z", cb);
+    expect(cb.handleUndo).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe("dispatchPlainKey — select leftward / rightward", () => {
   const clips = [
     { ...bgmElement, id: "early", key: "early", start: 0, track: 0 },

package/src/hooks/useAppHotkeys.textEditing.test.tsx

@@ -86,7 +86,7 @@ function Harness() {
     writeProjectFile: vi.fn(async () => undefined),
     showToast: vi.fn(),
     syncHistoryPreviewAfterApply: vi.fn(async () => undefined),
-    waitForPendingDomEditSaves: vi.fn(async () => undefined),
+    settlePendingEdits: vi.fn(async () => undefined),
     handleCopy: vi.fn(() => false),
     handlePaste: vi.fn(async () => undefined),
     handleCut: vi.fn(async () => false),

package/src/hooks/useAppHotkeys.ts

@@ -2,7 +2,6 @@ import { useCallback, useEffect, useRef } from "react";
 import { usePlayerStore } from "../player";
 import type { TimelineElement } from "../player";
 import type { DomEditSelection } from "../components/editor/domEditing";
-import { isTypingTarget } from "../utils/typingTarget";
 import { useCaptionStore } from "../captions/store";
 import {
   applyCaptionModelToIframe,
@@ -86,7 +85,7 @@ interface UseAppHotkeysParams {
   showToast: (message: string, tone?: "error" | "info") => void;
   syncHistoryPreviewAfterApply: UseEditHistoryActionsOptions["syncHistoryPreviewAfterApply"];
   showHistoryRestoreNow?: UseEditHistoryActionsOptions["showHistoryRestoreNow"];
-  waitForPendingDomEditSaves: () => Promise<void>;
+  settlePendingEdits: () => Promise<void>;
   handleCopy: () => boolean;
   handlePaste: () => Promise<void>;
   handleCut: () => Promise<boolean>;
@@ -125,7 +124,7 @@ export function useAppHotkeys({
   showToast,
   syncHistoryPreviewAfterApply,
   showHistoryRestoreNow,
-  waitForPendingDomEditSaves,
+  settlePendingEdits,
   handleCopy,
   handlePaste,
   handleCut,
@@ -152,7 +151,7 @@ export function useAppHotkeys({
     showToast,
     syncHistoryPreviewAfterApply,
     showHistoryRestoreNow,
-    waitForPendingDomEditSaves,
+    waitForPendingDomEditSaves: settlePendingEdits,
     onAfterUndoRedo,
     activeCompPath,
     forceReloadSdkSession,
@@ -220,7 +219,7 @@ export function useAppHotkeys({
       dispatchModifierKey(event, key, cb);
       return;
     }
-    if (!isTypingTarget(event.target)) dispatchPlainKey(event, key, cb);
+    dispatchPlainKey(event, key, cb);
   }, []);
 
   // eslint-disable-next-line no-restricted-syntax

package/src/hooks/useAutomationSelectionKeyboard.test.tsx

@@ -216,6 +216,23 @@ describe("useAutomationSelectionKeyboard", () => {
     input.remove();
   });
 
+  describe("with a focused picker", () => {
+    const picker = document.createElement("button");
+    picker.setAttribute("role", "combobox");
+    afterEach(() => picker.remove());
+
+    it("is inert while a picker that owns typing has focus", () => {
+      usePlayerStore
+        .getState()
+        .setAutomationSelection(wholeAxis({ elementKey: "bgm", target: "volume", t0: 1, t1: 3 }));
+      const { onCommit } = setup({});
+      document.body.append(picker);
+      picker.focus();
+      key("Delete");
+      expect(onCommit).not.toHaveBeenCalled();
+    });
+  });
+
   it("Cmd+C copies the active selection", () => {
     clearAutomationClipboard();
     usePlayerStore.setState({ elements: [bgmElement], selectedElementId: "bgm" });

package/src/hooks/useAutomationSelectionKeyboard.ts

@@ -31,6 +31,7 @@ import {
   type HfAutomationLane,
 } from "@hyperframes/core/audio-automation";
 import { clampNumber } from "../utils/studioHelpers";
+import { isTypingTarget } from "../utils/typingTarget";
 import type { AutomationSelection } from "../player/store/automationSelectionSlice";
 import type {
   AutomationLaneBinding,
@@ -39,13 +40,6 @@ import type {
 
 type PlayerState = ReturnType<typeof usePlayerStore.getState>;
 
-function isTextInput(el: Element | null): boolean {
-  if (!el) return false;
-  const tag = el.tagName;
-  if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") return true;
-  return el instanceof HTMLElement && el.isContentEditable;
-}
-
 /**
  * A Cmd/Ctrl+<letter> chord. `e.key` is normalised because CapsLock makes it
  * "V"/"C", and useAppHotkeys already lowercases — a raw `e.key === "v"` test
@@ -302,7 +296,7 @@ function handleCopy(
  * dead key beats today's double write.
  */
 export function automationOwnsKey(e: KeyboardEvent): boolean {
-  if (isTextInput(document.activeElement)) return false;
+  if (isTypingTarget(document.activeElement)) return false;
   const state = usePlayerStore.getState();
   if (isChord(e, "c")) return state.automationSelection !== null;
   if (!isChord(e, "v")) return false;
@@ -340,7 +334,7 @@ export function useAutomationSelectionKeyboard({
 }): void {
   useEffect(() => {
     const handler = (e: KeyboardEvent): void => {
-      if (isTextInput(document.activeElement)) return;
+      if (isTypingTarget(document.activeElement)) return;
       // Somebody upstream already claimed this key. useAppHotkeys is on
       // window/capture so it always runs first, and it deliberately lets a
       // keyframe selection outrank an automation range on Delete — without

package/src/hooks/useClipboard.source.test.ts

@@ -98,6 +98,7 @@ function mountClipboard(
   sub = SUB,
   bundle: (host: Element) => void = () => {},
   saved = SAVED,
+  view = { path: "index.html" },
 ) {
   const files: Record<string, string> = { "index.html": saved, "compositions/sub.html": sub };
   const fail = { on: false };
@@ -115,7 +116,7 @@ function mountClipboard(
   function Harness() {
     api = useClipboard({
       projectId: "p",
-      activeCompPath: "index.html",
+      activeCompPath: view.path,
       domEditSelectionRef: domSelectionRef,
       showToast: () => {},
       writeProjectFile,
@@ -134,7 +135,9 @@ function mountClipboard(
   root = createRoot(document.createElement("div"));
   act(() => root?.render(React.createElement(Harness)));
   const clipboard = () => api as ReturnType<typeof useClipboard>;
+  const rerender = () => act(() => root?.render(React.createElement(Harness)));
   return {
+    rerender,
     clipboard,
     writes,
     deleted,
@@ -253,6 +256,17 @@ const SUB_SELECTION = {
   sourceFile: "compositions/sub.html",
 } as DomEditSelection;
 
+const copySubNext = ({ clipboard, domSelectionRef }: ReturnType<typeof mountClipboard>) => {
+  clearSelection();
+  domSelectionRef.current = SUB_SELECTION;
+  clipboard().handleCopy();
+};
+
+const expectSubPastedAlone = (writes: string[]) => {
+  expect(writes[0]).toContain(">Sub</h2>");
+  expect(writes[0]?.match(/>Title<\/h1>/g)).toHaveLength(1);
+};
+
 describe("paste of an element styled by its id", () => {
   it("gives the copy the look its original has", async () => {
     clearSelection();
@@ -339,30 +353,24 @@ describe("copy order", () => {
 
   it("pastes the second of two copies", async () => {
     selectTitle();
-    const { clipboard, writes, domSelectionRef } = mountClipboard();
-    clipboard().handleCopy();
+    const view = mountClipboard();
+    view.clipboard().handleCopy();
     await new Promise((resolve) => setTimeout(resolve, 10));
-    clearSelection();
-    domSelectionRef.current = SUB_SELECTION;
-    clipboard().handleCopy();
-    await clipboard().handlePaste();
-    expect(writes[0]).toContain(">Sub</h2>");
-    expect(writes[0]?.match(/>Title<\/h1>/g)).toHaveLength(1);
+    copySubNext(view);
+    await view.clipboard().handlePaste();
+    expectSubPastedAlone(view.writes);
   });
 
   it("pastes the later copy even when the earlier copy's read lands last", async () => {
     selectTitle();
-    const { clipboard, writes, delayMs, domSelectionRef } = mountClipboard();
-    delayMs["index.html"] = 20;
-    clipboard().handleCopy();
-    clearSelection();
-    domSelectionRef.current = SUB_SELECTION;
-    clipboard().handleCopy();
+    const view = mountClipboard();
+    view.delayMs["index.html"] = 20;
+    view.clipboard().handleCopy();
+    copySubNext(view);
     await new Promise((resolve) => setTimeout(resolve, 40));
-    delayMs["index.html"] = 0;
-    await clipboard().handlePaste();
-    expect(writes[0]).toContain(">Sub</h2>");
-    expect(writes[0]?.match(/>Title<\/h1>/g)).toHaveLength(1);
+    view.delayMs["index.html"] = 0;
+    await view.clipboard().handlePaste();
+    expectSubPastedAlone(view.writes);
   });
 
   it("duplicates a hidden clip with its saved markup", async () => {
@@ -374,6 +382,78 @@ describe("copy order", () => {
   });
 });
 
+describe("a copy in place, as the canvas makes one", () => {
+  // The copy's start and track: the saved original has no data-hf-id, its copy is minted one.
+  const copyAt = (html: string | undefined) => {
+    const copy = html?.match(/<h1[^>]*data-hf-id[^>]*>Title<\/h1>/)?.[0] ?? "";
+    return [copy.match(/data-start="([^"]*)"/)?.[1], copy.match(/data-track-index="([^"]*)"/)?.[1]];
+  };
+
+  it("duplicates at the clip's own time, on the next free track", async () => {
+    selectTitle();
+    const { clipboard, writes } = mountClipboard();
+    await clipboard().handleDuplicate({ inPlace: true });
+    expect(copyAt(writes[0])).toEqual(["2", "1"]);
+  });
+
+  it("pastes at the copied clip's time, not the playhead's", async () => {
+    selectTitle();
+    const { clipboard, writes } = mountClipboard();
+    clipboard().handleCopy();
+    await clipboard().handlePaste({ inPlace: true });
+    expect(copyAt(writes[0])).toEqual(["2", "1"]);
+  });
+
+  // Host at 2 s: the clip's local 1-3 s shows as a 3-5 s master row, the clock the film's own timeline has.
+  const SUB_CLIP: TimelineElement = {
+    id: SUB_HF_ID,
+    hfId: SUB_HF_ID,
+    tag: "h2",
+    start: 3,
+    duration: 2,
+    track: 0,
+    authoredTrack: 0,
+    sourceFile: "compositions/sub.html",
+    parentCompositionStart: 2,
+  };
+  const pastedSubStarts = (html: string | undefined) =>
+    [...(html ?? "").matchAll(/<h2[^>]*data-hf-id[^>]*data-start="([^"]+)"/g)].map((m) => m[1]);
+  const mountSubClip = (currentTime = 0, view = { path: "index.html" }) => {
+    usePlayerStore.setState({
+      elements: [TITLE, SUB_CLIP],
+      selectedElementId: SUB_CLIP.id,
+      selectedElementIds: new Set([SUB_CLIP.id]),
+      currentTime,
+    });
+    return mountClipboard(null, SUB, (host) => host.setAttribute("data-start", "2"), SAVED, view);
+  };
+
+  it("pastes a sub-composition's clip into the film at the moment the film shows it", async () => {
+    const { clipboard, writes } = mountSubClip(7);
+    clipboard().handleCopy();
+    await clipboard().handlePaste({ inPlace: true });
+    expect(pastedSubStarts(writes[0])).toEqual(["3"]);
+  });
+
+  it("duplicates a sub-composition's clip at its own local time, on another track", async () => {
+    const { clipboard, writes } = mountSubClip();
+    await clipboard().handleDuplicate({ inPlace: true });
+    const copy = /<h2[^>]*data-hf-id[^>]*>/.exec(writes[0] ?? "")?.[0] ?? "";
+    expect(copy).toContain('data-start="1"');
+    expect(copy).toContain('data-track-index="1"');
+  });
+
+  it("pastes at the playhead once the edited composition is another, whose clock differs", async () => {
+    const view = { path: "index.html" };
+    const { clipboard, writes, rerender } = mountSubClip(0.5, view);
+    clipboard().handleCopy();
+    view.path = "compositions/sub.html";
+    rerender();
+    await clipboard().handlePaste({ inPlace: true });
+    expect(pastedSubStarts(writes[0])).toEqual(["0.5"]);
+  });
+});
+
 describe("duplicate of a clip inside a sub-composition", () => {
   it("writes the copy at local time right after the original", async () => {
     // Host at 2 s, so the clip's local 1-3 s shows as a 3-5 s master row.