@hyperframes/studio 0.8.77 → 0.8.79

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.8.77",
+  "version": "0.8.79",
   "description": "",
   "repository": {
     "type": "git",
@@ -52,11 +52,12 @@
     "dockview-react": "8.3.1",
     "gsap": "^3.13.0",
     "mediabunny": "^1.45.3",
-    "@hyperframes/core": "0.8.77",
-    "@hyperframes/parsers": "0.8.77",
-    "@hyperframes/studio-server": "0.8.77",
-    "@hyperframes/player": "0.8.77",
-    "@hyperframes/sdk": "0.8.77"
+    "@hyperframes/core": "0.8.79",
+    "@hyperframes/parsers": "0.8.79",
+    "@hyperframes/sdk": "0.8.79",
+    "@hyperframes/player": "0.8.79",
+    "@hyperframes/shader-transitions": "0.8.79",
+    "@hyperframes/studio-server": "0.8.79"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -72,7 +73,7 @@
     "vite": "^6.4.2",
     "vitest": "^4.1.11",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.8.77"
+    "@hyperframes/producer": "0.8.79"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -239,6 +239,7 @@ export function StudioApp({ readOnlyPreview = false, readOnlyPreviewReason }: St
     handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,
     handleDomEditElementDelete: domEditDeleteBridge,
     previewIframeRef,
+    waitForPendingDomEditSaves: previewPersistence.waitForPendingDomEditSaves,
   });
   const appHotkeys = useAppHotkeys({
     handleTimelineElementsDelete: timelineEditing.handleTimelineElementsDelete,

package/src/components/nle/useTimelineEditCallbacks.ts

@@ -1,3 +1,4 @@
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
 import { useCallback, useMemo } from "react";
 import type { GsapAnimation } from "@hyperframes/core/gsap-parser";
 import type { TimelineElement } from "../../player";
@@ -40,7 +41,12 @@ export interface TimelineEditCallbackDeps {
   handleToggleTrackHidden: (track: number, hidden: boolean) => Promise<void> | void;
   setAudioGroupAttribute: {
     setLive: (groupId: string, attr: string, value: string | null) => void;
-    setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+    setQuiet: (
+      groupId: string,
+      attr: string,
+      value: string | null,
+      label: string,
+    ) => Promise<TimelineEditOutcome | void>;
   };
   handleBlockedTimelineEdit: (element: TimelineElement, intent: BlockedTimelineEditIntent) => void;
   handleTimelineElementSplit: (element: TimelineElement, splitTime: number) => Promise<void> | void;
@@ -60,7 +66,7 @@ export interface TimelineEditCallbackDeps {
       attr: string,
       value: string | null,
       label: string,
-    ) => Promise<void>;
+    ) => Promise<TimelineEditOutcome | void>;
   };
 }
 

package/src/hooks/timelineAudioGroupVolume.ts

@@ -1,4 +1,5 @@
 import { useCallback, useRef } from "react";
+import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { usePlayerStore } from "../player";
@@ -167,7 +168,7 @@ async function setAudioGroupAttribute({
   writeProjectFile,
   recordEdit,
   pendingTimelineEditPathRef,
-}: SetAudioGroupAttributeInput): Promise<string[]> {
+}: SetAudioGroupAttributeInput): Promise<string[] | null> {
   // The file that actually CONTAINS the group element, not just the active
   // composition. A hand-authored sub-composition can declare both the members
   // and their `<hf-audio-group>`, and until sub-comp children inherited
@@ -179,7 +180,7 @@ async function setAudioGroupAttribute({
   const groupEl = previewIframe?.contentDocument?.getElementById(groupId) ?? null;
   const targetPath = resolveGroupSourceFile(groupEl) || activeCompPath || "index.html";
   const patchTarget = buildPatchTarget({ domId: groupId });
-  if (!patchTarget) return [];
+  if (!patchTarget) return null;
 
   return persistElementAttribute({
     projectId,
@@ -213,7 +214,12 @@ export function useSetAudioGroupAttribute({
   isRecordingRef,
 }: UseTimelineElementVisibilityEditingInput): {
   setLive: (groupId: string, attr: string, value: string | null) => void;
-  setQuiet: (groupId: string, attr: string, value: string | null, label: string) => Promise<void>;
+  setQuiet: (
+    groupId: string,
+    attr: string,
+    value: string | null,
+    label: string,
+  ) => Promise<TimelineEditOutcome>;
   revertLive: (groupId: string, attr: string) => void;
 } {
   const liveBeforeRef = useRef(new Map<string, string | null>());
@@ -253,15 +259,16 @@ export function useSetAudioGroupAttribute({
     [previewIframeRef],
   );
   const setQuiet = useCallback(
-    async (groupId: string, attr: string, value: string | null, label: string) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) return;
+    async (
+      groupId: string,
+      attr: string,
+      value: string | null,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
+      const pid = projectForTimelineSave(isRecordingRef?.current, projectIdRef.current, showToast);
+      if (typeof pid !== "string") return pid;
       try {
-        await setAudioGroupAttribute({
+        const written = await setAudioGroupAttribute({
           projectId: pid,
           activeCompPath,
           groupId,
@@ -274,7 +281,9 @@ export function useSetAudioGroupAttribute({
           pendingTimelineEditPathRef,
         });
         liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
+        if (!written) return { status: "failed", reason: "This group has no id to save it by" };
         syncStoredGroupAttribute(groupId, attr, value);
+        return { status: "saved" };
       } catch (error) {
         // `persistElementAttribute` leaves the live DOM at the previous value
         // however it failed — it unwinds a failed save, and an unresolvable
@@ -290,6 +299,7 @@ export function useSetAudioGroupAttribute({
         const message = error instanceof Error ? error.message : "Failed to update group";
         showToast(message);
         liveBeforeRef.current.delete(audioGroupAttributeLiveKey(groupId, attr));
+        return { status: "failed", reason: message };
       }
     },
     [

package/src/hooks/timelineEditPermission.ts

@@ -6,26 +6,60 @@ export type TimelineEditPermission = true | { blocked: true; reason: string };
 
 export type CanEditTimelineElement = (element: TimelineElement) => TimelineEditPermission;
 
+/** What an effect save did: landed, refused before writing, or failed while writing. */
+export type TimelineEditOutcome =
+  | { status: "saved" }
+  | { status: "refused" | "failed"; reason: string };
+
+/** The project to save into, or why the save stops before it writes. */
+export function projectForTimelineSave(
+  isRecording: boolean | undefined,
+  projectId: string | null,
+  showToast: (message: string, tone?: "error" | "info") => void,
+): string | TimelineEditOutcome {
+  if (isRecording) {
+    showToast("Cannot edit timeline while recording", "error");
+    return { status: "refused", reason: "Cannot edit timeline while recording" };
+  }
+  return projectId ?? { status: "failed", reason: "No project is open" };
+}
+
+function timelineEditRefusal(
+  canEdit: CanEditTimelineElement | undefined,
+  targets: readonly TimelineElement[],
+): string | null {
+  for (const element of targets) {
+    const verdict = canEdit?.(element) ?? true;
+    if (verdict !== true) return verdict.reason;
+  }
+  return null;
+}
+
 /**
- * Refuses a write when any target element is blocked, toasting the host's
- * reason. Absent `canEdit` never refuses, so Studio itself is unchanged.
+ * The host's reason to refuse a write when any target element is blocked, toasted,
+ * or null. Absent `canEdit` never refuses, so Studio itself is unchanged.
  */
-export function useTimelineEditGate(
+export function useTimelineEditRefusal(
   canEdit: CanEditTimelineElement | undefined,
   showToast: (message: string, tone?: "error" | "info") => void,
 ) {
   return useCallback(
-    (targets: readonly TimelineElement[]): boolean => {
-      if (!canEdit) return true;
-      for (const element of targets) {
-        const verdict = canEdit(element);
-        if (verdict !== true) {
-          showToast(verdict.reason, "error");
-          return false;
-        }
-      }
-      return true;
+    (targets: readonly TimelineElement[]): string | null => {
+      const reason = timelineEditRefusal(canEdit, targets);
+      if (reason !== null) showToast(reason, "error");
+      return reason;
     },
     [canEdit, showToast],
   );
 }
+
+export function useTimelineEditGate(
+  canEdit: CanEditTimelineElement | undefined,
+  showToast: (message: string, tone?: "error" | "info") => void,
+) {
+  const refuse = useTimelineEditRefusal(canEdit, showToast);
+  return useCallback(
+    (targets: readonly TimelineElement[]): boolean => refuse(targets) === null,
+    [refuse],
+  );
+}

package/src/hooks/timelineElementFxAttribute.ts

@@ -18,6 +18,7 @@ import type {
   MutableRef,
   UseTimelineElementVisibilityEditingInput,
 } from "./timelineTrackVisibility";
+import { projectForTimelineSave, type TimelineEditOutcome } from "./timelineEditPermission";
 
 function patchLiveElementAttribute(
   iframe: HTMLIFrameElement | null,
@@ -64,10 +65,10 @@ async function setElementAttribute({
   writeProjectFile,
   recordEdit,
   pendingTimelineEditPathRef,
-}: SetElementAttributeInput): Promise<string[]> {
+}: SetElementAttributeInput): Promise<string[] | null> {
   const targetPath = element.sourceFile || activeCompPath || "index.html";
   const patchTarget = buildPatchTarget(element);
-  if (!patchTarget) return [];
+  if (!patchTarget) return null;
 
   return persistElementAttribute({
     projectId,
@@ -99,7 +100,7 @@ export function useSetElementAttribute({
     attr: string,
     value: string | null,
     label: string,
-  ) => Promise<void>;
+  ) => Promise<TimelineEditOutcome>;
   revertLive: (element: TimelineElement, attr: string) => void;
 } {
   const liveBeforeRef = useRef(new Map<string, string | null>());
@@ -130,15 +131,17 @@ export function useSetElementAttribute({
     [previewIframeRef, activeCompPath],
   );
   const setQuiet = useCallback(
-    async (element: TimelineElement, attr: string, value: string | null, label: string) => {
-      if (isRecordingRef?.current) {
-        showToast("Cannot edit timeline while recording", "error");
-        return;
-      }
-      const pid = projectIdRef.current;
-      if (!pid) return;
+    async (
+      element: TimelineElement,
+      attr: string,
+      value: string | null,
+      label: string,
+    ): Promise<TimelineEditOutcome> => {
+      const pid = projectForTimelineSave(isRecordingRef?.current, projectIdRef.current, showToast);
+      if (typeof pid !== "string") return pid;
+      const liveKey = elementAttributeLiveKey(element, activeCompPath, attr);
       try {
-        await setElementAttribute({
+        const written = await setElementAttribute({
           projectId: pid,
           activeCompPath,
           element,
@@ -150,12 +153,15 @@ export function useSetElementAttribute({
           recordEdit,
           pendingTimelineEditPathRef,
         });
-        liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
+        liveBeforeRef.current.delete(liveKey);
+        if (written) return { status: "saved" };
+        return { status: "failed", reason: "This clip has no id to save it by" };
       } catch (error) {
         console.error("[Timeline] Failed to set element attribute", error);
         const message = error instanceof Error ? error.message : "Failed to update effect";
         showToast(message);
-        liveBeforeRef.current.delete(elementAttributeLiveKey(element, activeCompPath, attr));
+        liveBeforeRef.current.delete(liveKey);
+        return { status: "failed", reason: message };
       }
     },
     [

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

@@ -0,0 +1,340 @@
+// @vitest-environment jsdom
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useClipboard } from "./useClipboard";
+import { usePlayerStore, type TimelineElement } from "../player";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
+
+// Saved without hf-ids and with no element id: the preview stamps ids only in memory.
+const SAVED = `<!doctype html><html><body>
+<div data-composition-id="main" data-start="0" data-duration="10">
+<h1 class="clip" data-start="2" data-duration="3" data-track-index="0">Title</h1>
+</div></body></html>`;
+
+const SUB = `<template id="sub-template"><div data-composition-id="sub" data-start="0" data-duration="4">
+<h2 class="clip" data-start="1" data-duration="2" data-track-index="0">Sub</h2>
+</div></template>`;
+
+// What the runtime leaves on a clip while the playhead is before its start.
+const RUNTIME_HIDE = "visibility: hidden; display: none; position: absolute";
+
+function stampedHfId(source: string, selector: string): string {
+  const doc = new DOMParser().parseFromString(ensureHfIds(source), "text/html");
+  const roots = [doc, ...Array.from(doc.querySelectorAll("template"), (t) => t.content)];
+  const el = roots.map((root) => root.querySelector(selector)).find(Boolean);
+  return el?.getAttribute("data-hf-id") ?? "";
+}
+
+const TITLE_HF_ID = stampedHfId(SAVED, "h1");
+const SUB_HF_ID = stampedHfId(SUB, "h2");
+
+const TITLE: TimelineElement = {
+  id: TITLE_HF_ID,
+  hfId: TITLE_HF_ID,
+  tag: "h1",
+  start: 2,
+  duration: 3,
+  track: 0,
+  authoredTrack: 0,
+  sourceFile: "index.html",
+};
+
+let root: Root | null = null;
+afterEach(() => {
+  act(() => root?.unmount());
+  root = null;
+  vi.unstubAllGlobals();
+  document.body.innerHTML = "";
+});
+
+// The preview page: the saved markup with the preview's in-memory ids, a sub-composition
+// mounted inline, and the runtime's hide on both clips.
+function mountPreview(sub: string, bundle: (host: Element) => void): HTMLIFrameElement {
+  const iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  const doc = iframe.contentDocument as Document;
+  doc.open();
+  doc.write(ensureHfIds(SAVED));
+  doc.close();
+  const parsed = new DOMParser().parseFromString(ensureHfIds(sub), "text/html");
+  const subRoot = (parsed.querySelector("template") as HTMLTemplateElement).content
+    .firstElementChild;
+  const host = doc.createElement("div");
+  host.setAttribute("data-composition-src", "compositions/sub.html");
+  host.append(doc.importNode(subRoot as Element, true));
+  bundle(host);
+  doc.querySelector('[data-composition-id="main"]')?.append(host);
+  for (const clip of doc.querySelectorAll(".clip"))
+    (clip as HTMLElement).style.cssText = RUNTIME_HIDE;
+  return iframe;
+}
+
+function stubFiles(
+  files: Record<string, string>,
+  fail: { on: boolean },
+  delayMs: Record<string, number>,
+) {
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (url: string) => {
+      const path = decodeURIComponent(String(url).split("/files/")[1] ?? "");
+      // The server answers later, so a write that lands first is what the read sees.
+      await new Promise((resolve) => setTimeout(resolve, delayMs[path] ?? 0));
+      if (fail.on) return new Response("", { status: 500 });
+      return new Response(JSON.stringify({ content: files[path] }));
+    }),
+  );
+}
+
+function mountClipboard(
+  domSelection: DomEditSelection | null = null,
+  sub = SUB,
+  bundle: (host: Element) => void = () => {},
+) {
+  const files: Record<string, string> = { "index.html": SAVED, "compositions/sub.html": sub };
+  const fail = { on: false };
+  const delayMs: Record<string, number> = {};
+  const domEditSave = { pending: Promise.resolve() };
+  const domSelectionRef = { current: domSelection };
+  stubFiles(files, fail, delayMs);
+  const iframe = mountPreview(sub, bundle);
+  const writes: string[] = [];
+  const deleted: string[] = [];
+  const writeProjectFile = async (_path: string, content: string) => {
+    writes.push(content);
+  };
+  let api: ReturnType<typeof useClipboard> | null = null;
+  function Harness() {
+    api = useClipboard({
+      projectId: "p",
+      activeCompPath: "index.html",
+      domEditSelectionRef: domSelectionRef,
+      showToast: () => {},
+      writeProjectFile,
+      recordEdit: async () => {},
+      reloadPreview: () => {},
+      handleTimelineElementsDelete: async (elements) => {
+        deleted.push(...elements.map((el) => el.id));
+        files["index.html"] = SAVED.replace(/<h1[\s\S]*<\/h1>/, "");
+      },
+      handleDomEditElementDelete: async () => {},
+      previewIframeRef: { current: iframe },
+      waitForPendingDomEditSaves: () => domEditSave.pending,
+    });
+    return null;
+  }
+  root = createRoot(document.createElement("div"));
+  act(() => root?.render(React.createElement(Harness)));
+  const clipboard = () => api as ReturnType<typeof useClipboard>;
+  return {
+    clipboard,
+    writes,
+    deleted,
+    files,
+    fail,
+    writeProjectFile,
+    iframe,
+    delayMs,
+    domEditSave,
+    domSelectionRef,
+  };
+}
+
+function selectTitle() {
+  usePlayerStore.setState({
+    elements: [TITLE],
+    selectedElementId: TITLE.id,
+    selectedElementIds: new Set([TITLE.id]),
+    currentTime: 6,
+  });
+}
+
+function clearSelection() {
+  usePlayerStore.setState({ selectedElementId: null, selectedElementIds: new Set() });
+}
+
+describe("copy takes a clip's saved markup, not the runtime's live styling", () => {
+  it("pastes a timeline clip copied while hidden, matched through the preview's hf-id", async () => {
+    selectTitle();
+    const { clipboard, writes } = mountClipboard();
+    expect(clipboard().handleCopy()).toBe(true);
+    await clipboard().handlePaste();
+    expect(writes).toHaveLength(1);
+    expect(writes[0]).toContain(">Title</h1>");
+    expect(writes[0]).not.toContain("display: none");
+    expect(writes[0]).not.toContain("visibility: hidden");
+  });
+
+  it("pastes a sub-composition clip copied while hidden, found inside its template", async () => {
+    clearSelection();
+    const selection = {
+      hfId: SUB_HF_ID,
+      selector: "h2",
+      selectorIndex: 0,
+      sourceFile: "compositions/sub.html",
+    } as DomEditSelection;
+    const { clipboard, writes } = mountClipboard(selection);
+    expect(clipboard().handleCopy()).toBe(true);
+    await clipboard().handlePaste();
+    expect(writes).toHaveLength(1);
+    expect(writes[0]).toContain(">Sub</h2>");
+    expect(writes[0]).not.toContain("display: none");
+  });
+
+  it("cuts only once the saved markup is read, and pastes it", async () => {
+    selectTitle();
+    const { clipboard, writes, deleted } = mountClipboard();
+    await clipboard().handleCut();
+    expect(deleted).toEqual([TITLE.id]);
+    await clipboard().handlePaste();
+    expect(writes[0]).toContain(">Title</h1>");
+    expect(writes[0]).not.toContain("display: none");
+  });
+
+  it("reads a save still in flight when the copy starts", async () => {
+    selectTitle();
+    const { clipboard, writes, files, writeProjectFile } = mountClipboard();
+    void serializeStudioFileMutations(writeProjectFile, ["index.html"], async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      // The host pins hf-ids on disk, so a Studio save keeps the clip's id.
+      files["index.html"] = ensureHfIds(SAVED).replace(">Title<", ">Title v2<");
+    });
+    clipboard().handleCopy();
+    await clipboard().handlePaste();
+    expect(writes[0]?.match(/>Title v2<\/h1>/g)).toHaveLength(2);
+    expect(writes[0]).not.toContain(">Title</h1>");
+  });
+
+  it("finds a clip by its id once its saved markup no longer hashes to the preview's hf-id", async () => {
+    selectTitle();
+    const { clipboard, writes, files, iframe } = mountClipboard();
+    iframe.contentDocument?.querySelector("h1")?.setAttribute("id", "title");
+    files["index.html"] = SAVED.replace("<h1 ", '<h1 id="title" ').replace(">Title<", ">Title v2<");
+    clipboard().handleCopy();
+    await clipboard().handlePaste();
+    expect(writes[0]?.match(/>Title v2<\/h1>/g)).toHaveLength(2);
+    expect(writes[0]).not.toContain("display: none");
+  });
+});
+
+const SUB_SELECTION = {
+  hfId: SUB_HF_ID,
+  selector: "h2",
+  selectorIndex: 0,
+  sourceFile: "compositions/sub.html",
+} as DomEditSelection;
+
+describe("copy of a sub-composition clip", () => {
+  it("rebases its relative asset paths to the project root, as the preview does", async () => {
+    clearSelection();
+    const sub = SUB.replace(
+      ">Sub<",
+      '><img src="../assets/logo.png?v=2"><img src="logo.png"><img src="assets/shared.png">' +
+        '<img src="../assets/100%.png"><span style="background: url(\'../fonts/My Font.woff2\')"></span>Sub<',
+    );
+    const selection = { ...SUB_SELECTION, hfId: stampedHfId(sub, "h2") };
+    const { clipboard, writes } = mountClipboard(selection, sub, (host) => {
+      const [up, sibling] = Array.from(host.querySelectorAll("img"));
+      up?.setAttribute("src", "assets/logo.png?v=2");
+      sibling?.setAttribute("src", "compositions/logo.png");
+    });
+    clipboard().handleCopy();
+    await clipboard().handlePaste();
+    expect(writes[0]).toContain('src="assets/logo.png?v=2"');
+    expect(writes[0]).toContain('src="compositions/logo.png"');
+    expect(writes[0]).toContain('src="assets/shared.png"');
+    expect(writes[0]).toContain('src="assets/100%.png"');
+    expect(writes[0]).toContain("url('fonts/My Font.woff2')");
+    expect(writes[0]).not.toContain("../");
+    expect(writes[0]).not.toContain("display: none");
+  });
+});
+
+describe("copy order", () => {
+  it("waits for a DOM edit save still in flight", async () => {
+    selectTitle();
+    const { clipboard, writes, files, domEditSave } = mountClipboard();
+    domEditSave.pending = new Promise((resolve) =>
+      setTimeout(() => {
+        files["index.html"] = ensureHfIds(SAVED).replace(">Title<", ">Title v2<");
+        resolve();
+      }, 5),
+    );
+    clipboard().handleCopy();
+    await clipboard().handlePaste();
+    expect(writes[0]?.match(/>Title v2<\/h1>/g)).toHaveLength(2);
+  });
+
+  it("still copies after a DOM edit save failed", async () => {
+    selectTitle();
+    const { clipboard, writes, domEditSave } = mountClipboard();
+    domEditSave.pending = Promise.reject(new Error("save conflict"));
+    domEditSave.pending.catch(() => {});
+    clipboard().handleCopy();
+    await clipboard().handlePaste();
+    expect(writes[0]?.match(/>Title<\/h1>/g)).toHaveLength(2);
+  });
+
+  it("pastes the second of two copies", async () => {
+    selectTitle();
+    const { clipboard, writes, domSelectionRef } = mountClipboard();
+    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);
+  });
+
+  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();
+    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);
+  });
+
+  it("duplicates a hidden clip with its saved markup", async () => {
+    selectTitle();
+    const { clipboard, writes } = mountClipboard();
+    await clipboard().handleDuplicate();
+    expect(writes[0]?.match(/>Title<\/h1>/g)).toHaveLength(2);
+    expect(writes[0]).not.toContain("display: none");
+  });
+});
+
+describe("a copy that fails", () => {
+  it("leaves the previous copy on the clipboard", async () => {
+    selectTitle();
+    const { clipboard, writes, fail } = mountClipboard();
+    clipboard().handleCopy();
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    fail.on = true;
+    clipboard().handleCopy();
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    fail.on = false;
+    await clipboard().handlePaste();
+    expect(writes).toHaveLength(1);
+    expect(writes[0]).toContain(">Title</h1>");
+  });
+
+  it("deletes nothing on a cut", async () => {
+    selectTitle();
+    const { clipboard, deleted, fail } = mountClipboard();
+    fail.on = true;
+    expect(await clipboard().handleCut()).toBe(false);
+    expect(deleted).toEqual([]);
+  });
+});