@hyperframes/studio 0.8.80 → 0.8.82

package/src/player/hooks/useTimelinePlayer.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { Window } from "happy-dom";
 import {
   buildStandaloneRootTimelineElement,
@@ -597,3 +597,95 @@ describe("shouldIgnorePlaybackShortcutEvent", () => {
     ).toBe(false);
   });
 });
+
+describe("shouldIgnorePlaybackShortcutEvent while a modal dialog is open", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  // happy-dom has no layout, so the `hidden` attribute stands in for checkVisibility.
+  function stubStudioDocument(markup: string): Document {
+    const document = createDocument(markup);
+    const elementProto = document.defaultView!.Element.prototype as {
+      checkVisibility?: (this: Element) => boolean;
+    };
+    elementProto.checkVisibility = function () {
+      return this.closest("[hidden]") === null;
+    };
+    vi.stubGlobal("document", document);
+    return document;
+  }
+
+  it("ignores playback keys with focus still on the page behind the dialog", () => {
+    const document = stubStudioDocument(
+      `<div role="dialog" aria-modal="true"><p>Lint results</p></div>`,
+    );
+    for (const code of ["Space", "ArrowRight", "KeyL"]) {
+      expect(
+        shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent(code, { target: document.body })),
+      ).toBe(true);
+    }
+  });
+
+  it("ignores playback keys with focus inside the dialog", () => {
+    const document = stubStudioDocument(
+      `<div role="dialog" aria-modal="true" tabindex="-1"><p>Lint results</p></div>`,
+    );
+    const dialog = document.querySelector("[role='dialog']");
+    const text = document.querySelector("p");
+    expect(shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: dialog }))).toBe(
+      true,
+    );
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("ArrowLeft", { target: text })),
+    ).toBe(true);
+  });
+
+  it("keeps playback keys for dialogs that are hidden, inert or not modal", () => {
+    for (const markup of [
+      `<div role="dialog" aria-modal="true" hidden></div>`,
+      `<div inert><div role="dialog" aria-modal="true"></div></div>`,
+      `<div role="dialog"></div>`,
+    ]) {
+      const document = stubStudioDocument(markup);
+      expect(
+        shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+      ).toBe(false);
+    }
+  });
+
+  it("counts a dialog under fullscreen only when the fullscreen element holds it", () => {
+    const document = stubStudioDocument(
+      `<div id="stage"><div id="inner" role="dialog" aria-modal="true"></div></div>` +
+        `<div id="outer" role="dialog" aria-modal="true"></div>`,
+    );
+    const space = () =>
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body }));
+    const fullscreenOn = (id: string) =>
+      Object.defineProperty(document, "fullscreenElement", {
+        configurable: true,
+        value: document.getElementById(id),
+      });
+    fullscreenOn("stage");
+    expect(space()).toBe(true);
+    document.getElementById("inner")!.remove();
+    expect(space()).toBe(false);
+  });
+
+  it("counts an aria-modal dialog where the browser has no checkVisibility", () => {
+    const document = createDocument(`<div role="dialog" aria-modal="true"></div>`);
+    delete (document.defaultView!.Element.prototype as { checkVisibility?: unknown })
+      .checkVisibility;
+    vi.stubGlobal("document", document);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+    ).toBe(true);
+  });
+
+  it("keeps playback keys when no dialog is open", () => {
+    const document = stubStudioDocument(`<main><p>Preview</p></main>`);
+    expect(
+      shouldIgnorePlaybackShortcutEvent(mockKeyboardEvent("Space", { target: document.body })),
+    ).toBe(false);
+  });
+});

package/src/player/lib/playbackShortcuts.ts

@@ -41,6 +41,23 @@ export function shouldIgnorePlaybackShortcutTarget(target: EventTarget | null):
   );
 }
 
+const MODAL_DIALOG_SELECTOR = "[role=dialog][aria-modal=true]";
+
+// An open modal owns the keyboard wherever focus sits, preview iframe included. It counts only
+// when shown: visible, not inert, and not behind a fullscreen element that leaves it out.
+function isModalDialogOpen(): boolean {
+  const doc = globalThis.document;
+  if (!doc) return false;
+  const fullscreen = doc.fullscreenElement;
+  return Array.from(doc.querySelectorAll(MODAL_DIALOG_SELECTOR)).some(
+    (dialog) =>
+      (!fullscreen || fullscreen.contains(dialog)) &&
+      !dialog.closest("[inert]") &&
+      (typeof dialog.checkVisibility !== "function" ||
+        dialog.checkVisibility({ visibilityProperty: true })),
+  );
+}
+
 interface PlaybackShortcutCaptionState {
   isCaptionEditMode: boolean;
   selectedCaptionSegmentCount: number;
@@ -60,6 +77,7 @@ export function shouldIgnorePlaybackShortcutEvent(
 ): boolean {
   if (event.metaKey || event.ctrlKey || event.altKey) return true;
   if (shouldIgnorePlaybackShortcutTarget(event.target)) return true;
+  if (isModalDialogOpen()) return true;
   return (
     PLAYBACK_FRAME_STEP_CODES.has(event.code) &&
     captionState.isCaptionEditMode &&

package/src/player/lib/playbackTypes.ts

@@ -62,6 +62,7 @@ export type IframeWindow = Window & {
   __timeline?: TimelineLike;
   __timelines?: Record<string, TimelineLike>;
   __clipManifest?: ClipManifest;
+  __hfWaitForSeekCompletion?: () => Promise<void>;
   /** Declared runtime-side in core's window.d.ts, which this package cannot see.
    *  Every member stays optional and is optional-called, so a runtime that
    *  predates the hook degrades to a no-op instead of throwing. */

package/src/player/lib/timelineDOM.test.ts

@@ -9,6 +9,7 @@ import {
 import { isTimelineIgnoredElement } from "./timelineElementHelpers";
 import { computeResizePreview } from "../components/timelineClipDragPreview";
 import type { TimelineElement } from "../store/playerStore";
+import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
 
 function el(id: string, extra: Partial<TimelineElement> = {}): TimelineElement {
   return { id, tag: "img", start: 0, duration: 5, track: 0, ...extra };
@@ -46,6 +47,26 @@ describe("parseTimelineFromDOM — media in-point", () => {
   });
 });
 
+describe("parseTimelineFromDOM — in-point read as playback reads it", () => {
+  it.each([
+    ['data-playback-start="-1" data-media-start="2"', 2, "playback-start"],
+    ['data-playback-start="abc" data-media-start="2"', 2, "playback-start"],
+    ['data-media-start="junk"', 0, "media-start"],
+    ['data-media-start="1.5s"', 0, "media-start"],
+  ])("%s", (inPoint, playbackStart, playbackStartAttr) => {
+    const doc = makeDoc(
+      `<div data-composition-id="root"><video id="v" class="clip" data-start="0" data-duration="4" ${inPoint}></video></div>`,
+    );
+    const element = parseTimelineFromDOM(doc, 10).find((e) => e.domId === "v")!;
+    const video = doc.getElementById("v")!;
+    expect(element.playbackStart).toBe(readMediaOffsetSeconds((n) => video.getAttribute(n)));
+    expect([element.playbackStart, element.playbackStartAttr]).toEqual([
+      playbackStart,
+      playbackStartAttr,
+    ]);
+  });
+});
+
 describe("parseTimelineFromDOM — hfId from data-hf-id", () => {
   it("bridges a real GSAP transition marker onto both named clips", () => {
     document.body.innerHTML = `
@@ -526,3 +547,74 @@ describe("a composition clip's source length", () => {
     expect(card?.sourceDuration).toBeUndefined();
   });
 });
+
+describe("what the live clip list says a clip plays", () => {
+  function manifestVideo(attrs: string): TimelineElement {
+    const doc = makeDoc(
+      `<div data-composition-id="root"><video id="v" src="a.mp4" data-start="0" data-duration="4" ${attrs}></video></div>`,
+    );
+    return createTimelineElementFromManifestClip({
+      clip: {
+        id: "v",
+        label: "v",
+        kind: "video",
+        tagName: "video",
+        start: 0,
+        duration: 4,
+        track: 0,
+        assetUrl: null,
+      },
+      fallbackIndex: 0,
+      doc,
+      hostEl: doc.getElementById("v"),
+    });
+  }
+
+  it("carries data-volume and muted from the element", () => {
+    expect(manifestVideo('data-volume="0" muted')).toMatchObject({ volume: 0, muted: true });
+    const plain = manifestVideo("");
+    expect(plain.volume).toBeUndefined();
+    expect(plain.muted).toBeUndefined();
+  });
+
+  it("carries the clip-edge fades, and drops a zero one", () => {
+    const faded = manifestVideo('data-fade-in="1.5" data-fade-out="0"');
+    expect(faded.fadeIn).toBe(1.5);
+    expect(faded.fadeOut).toBeUndefined();
+  });
+
+  it("gives a video with neither muted nor data-has-audio sound, as the compiler does", () => {
+    expect(manifestVideo("").hasAudio).toBe(true);
+    expect(manifestVideo("muted").hasAudio).toBeUndefined();
+    expect(manifestVideo('data-has-audio="false"').hasAudio).toBeUndefined();
+    expect(manifestVideo('muted data-has-audio="true"')).toMatchObject({
+      hasAudio: true,
+      muted: true,
+    });
+  });
+
+  it.each(["", ' data-has-audio="true"'])(
+    "does not give a timed wrapper the sound of an untimed video%s inside it",
+    (videoAttrs) => {
+      const doc = makeDoc(
+        `<div data-composition-id="root"><div id="w" data-start="0" data-duration="4"><video src="a.mp4"${videoAttrs}></video></div></div>`,
+      );
+      const wrapper = createTimelineElementFromManifestClip({
+        clip: {
+          id: "w",
+          label: "w",
+          kind: "element",
+          tagName: "div",
+          start: 0,
+          duration: 4,
+          track: 0,
+          assetUrl: null,
+        },
+        fallbackIndex: 0,
+        doc,
+        hostEl: doc.getElementById("w"),
+      });
+      expect(wrapper.hasAudio).toBeUndefined();
+    },
+  );
+});

package/src/player/lib/timelineDOM.ts

@@ -304,8 +304,6 @@ export function parseTimelineFromDOM(
       if (mediaEl.tagName === "IMG") {
         entry.tag = "img";
       }
-      const vol = el.getAttribute("data-volume") ?? mediaEl.getAttribute("data-volume");
-      if (vol) entry.volume = parseFloat(vol);
       // Override AFTER the helper (which sets the raw relative attribute) so the
       // resolved absolute URL wins — the Studio can then fetch the asset
       // regardless of whether the attribute value was relative or absolute.

package/src/player/lib/timelineElementHelpers.ts

@@ -13,7 +13,7 @@ import { isFinitePositive } from "./playbackAdapter";
 import { getSourceScopedSelectorIndex } from "../../utils/sourceScopedSelectorIndex";
 import { HF_AUDIO_GROUP_TAG } from "@hyperframes/core/audio-groups";
 import { readElementFades } from "@hyperframes/core/audio-fade";
-import { readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
+import { type AttrReader, readMediaOffsetSeconds } from "@hyperframes/parsers/media-duration";
 
 // ---------------------------------------------------------------------------
 // Layer-reveal lift transparency
@@ -168,14 +168,34 @@ export function resolveMediaElement(el: Element): HTMLMediaElement | HTMLImageEl
     : null;
 }
 
+/** The in-point as playback reads it, and the attribute holding it; empty when neither is authored. */
+export function readPlaybackStartAttributes(
+  getAttr: AttrReader,
+): Pick<TimelineElement, "playbackStart" | "playbackStartAttr"> {
+  const playbackStartAttr =
+    getAttr("data-playback-start") != null
+      ? "playback-start"
+      : getAttr("data-media-start") != null
+        ? "media-start"
+        : undefined;
+  return playbackStartAttr
+    ? { playbackStart: readMediaOffsetSeconds(getAttr), playbackStartAttr }
+    : {};
+}
+
+export function playbackStartAttributeForElement(
+  element: Pick<TimelineElement, "kind" | "playbackStartAttr">,
+): "data-media-start" | "data-playback-start" {
+  return element.playbackStartAttr === "playback-start" || element.kind === "composition"
+    ? "data-playback-start"
+    : "data-media-start";
+}
+
 function applyPlaybackMetadataFromElement(entry: TimelineElement, el: Element): void {
-  const playbackStartValue = el.getAttribute("data-playback-start");
-  const legacyMediaStartValue = el.getAttribute("data-media-start");
-  const mediaStartValue = playbackStartValue ?? legacyMediaStartValue;
-  if (mediaStartValue != null)
-    entry.playbackStart = readMediaOffsetSeconds((n) => el.getAttribute(n));
-  if (playbackStartValue != null) entry.playbackStartAttr = "playback-start";
-  else if (legacyMediaStartValue != null) entry.playbackStartAttr = "media-start";
+  Object.assign(
+    entry,
+    readPlaybackStartAttributes((n) => el.getAttribute(n)),
+  );
 
   const authoredPlaybackRate = Number.parseFloat(el.getAttribute("data-playback-rate") ?? "");
   if (Number.isFinite(authoredPlaybackRate) && authoredPlaybackRate > 0) {
@@ -193,9 +213,25 @@ function setOptional<K extends keyof TimelineElement>(
   else entry[key] = value;
 }
 
-/** `data-has-audio` and the clip-edge fades: what the mixer hears and how it enters and leaves. */
+function readVolume(el: Element, media: Element): number | undefined {
+  const volume = Number.parseFloat(
+    el.getAttribute("data-volume") ?? media.getAttribute("data-volume") ?? "",
+  );
+  return Number.isFinite(volume) ? volume : undefined;
+}
+
+/** What the mixer gets: the compiler's `data-has-audio` rule, muted and volume. */
 function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): void {
-  setOptional(entry, "hasAudio", el.getAttribute("data-has-audio") === "true" ? true : undefined);
+  const media = resolveMediaElement(el) ?? el;
+  const muted = el.hasAttribute("muted") || media.hasAttribute("muted");
+  const hasAudio = el.getAttribute("data-has-audio");
+  const sound = hasAudio === null ? el.tagName === "VIDEO" && !muted : hasAudio === "true";
+  setOptional(entry, "hasAudio", sound ? true : undefined);
+  setOptional(entry, "muted", muted ? true : undefined);
+  setOptional(entry, "volume", readVolume(el, media));
+}
+
+function applyFadeMetadataFromElement(entry: TimelineElement, el: Element): void {
   const fades = readElementFades(el);
   setOptional(entry, "fadeIn", fades.fadeIn > 0 ? fades.fadeIn : undefined);
   setOptional(entry, "fadeOut", fades.fadeOut > 0 ? fades.fadeOut : undefined);
@@ -204,6 +240,7 @@ function applyAudioMetadataFromElement(entry: TimelineElement, el: Element): voi
 export function applyMediaMetadataFromElement(entry: TimelineElement, el: Element): void {
   applyPlaybackMetadataFromElement(entry, el);
   applyAudioMetadataFromElement(entry, el);
+  applyFadeMetadataFromElement(entry, el);
 
   const mediaEl = resolveMediaElement(el);
   if (!mediaEl) return;

package/src/player/lib/timelineViewportBudgets.ts

@@ -49,7 +49,7 @@ export interface TimelineViewportBudgets {
 
 const MEBIBYTE = 1024 * 1024;
 const DAY_MS = 24 * 60 * 60 * 1000;
-export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); // 4K timeline width / tallest 16:9 tile.
+export const MAX_VISIBLE_THUMBNAIL_FRAMES = Math.ceil(3840 / (66 * (16 / 9))); // Decode-memory cap, 4K width / a 66 px 16:9 tile; 40 px clips reuse frames past it.
 
 /**
  * The sole default budget owner for timeline viewport and media virtualization.

package/src/player/store/timelineElement.ts

@@ -55,8 +55,9 @@ export interface TimelineElement {
   playbackRate?: number;
   sourceDuration?: number;
   volume?: number;
-  /** `data-has-audio="true"` on a video: its sound is mixed, so it takes audio affordances (fades). */
+  /** A video with sound to mix (`data-has-audio`, or unmuted without it); `muted` silences it. */
   hasAudio?: boolean;
+  muted?: boolean;
   /** Clip-edge fades from `data-fade-in` / `data-fade-out`, seconds; absent means none. */
   fadeIn?: number;
   fadeOut?: number;

package/src/timelineChromeExports.test.tsx

@@ -0,0 +1,79 @@
+// @vitest-environment happy-dom
+// Mounts the timeline chrome by package name with no StudioShellProvider, as a host app does.
+import { act } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  AudioMeterStrip,
+  TimelineHistoryButtons,
+  TimelineToolbar,
+  useClipboard,
+  usePlayerStore,
+  type UseClipboardOptions,
+} from "@hyperframes/studio";
+import { installReactActEnvironment, mountReactHarness } from "./hooks/domSelectionTestHarness";
+import { useAudioMetersVisible } from "./utils/audioMeterVisibility";
+
+installReactActEnvironment();
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  usePlayerStore.setState({ elements: [], selectedElementId: null });
+  useAudioMetersVisible.setState(useAudioMetersVisible.getInitialState());
+});
+
+describe("timeline chrome package exports, outside Studio's shell", () => {
+  it("mounts the toolbar with the host's history and no Add beat", async () => {
+    const onUndo = vi.fn();
+    const root = mountReactHarness(
+      <TimelineToolbar history={{ canUndo: true, onUndo }} showAddBeat={false} />,
+    );
+    const undo = document.querySelector<HTMLButtonElement>('button[aria-label="Undo"]');
+    act(() => undo?.click());
+    expect(onUndo).toHaveBeenCalledTimes(1);
+    expect(document.querySelector('button[aria-label="Add beat at playhead"]')).toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("mounts the history buttons disabled when given nothing", async () => {
+    const root = mountReactHarness(<TimelineHistoryButtons />);
+    const buttons = Array.from(document.querySelectorAll("button"));
+    expect(buttons.map((b) => b.disabled)).toEqual([true, true]);
+    await act(async () => root.unmount());
+  });
+
+  it("mounts the meter strip on the host's preview iframe", async () => {
+    usePlayerStore.setState({
+      elements: [{ id: "music", tag: "audio", start: 0, duration: 4, track: 0 }],
+    });
+    useAudioMetersVisible.setState({ visible: true });
+    const root = mountReactHarness(<AudioMeterStrip previewIframeRef={{ current: null }} />);
+    expect(document.querySelector('[data-testid="audio-meter-strip"]')).not.toBeNull();
+    await act(async () => root.unmount());
+  });
+
+  it("runs the clipboard with no DOM edit session", async () => {
+    const toasts: string[] = [];
+    const options: UseClipboardOptions = {
+      projectId: "p",
+      activeCompPath: "index.html",
+      domEditSelectionRef: { current: null },
+      showToast: (message) => toasts.push(message),
+      writeProjectFile: async () => {},
+      recordEdit: async () => {},
+      reloadPreview: () => {},
+      handleTimelineElementsDelete: async () => {},
+      handleDomEditElementDelete: async () => {},
+      previewIframeRef: { current: null },
+      waitForPendingDomEditSaves: async () => {},
+    };
+    const api: { current: ReturnType<typeof useClipboard> | null } = { current: null };
+    function Harness() {
+      api.current = useClipboard(options);
+      return null;
+    }
+    const root = mountReactHarness(<Harness />);
+    expect(api.current?.handleCopy()).toBe(false);
+    expect(toasts).toEqual(["Nothing selected to copy."]);
+    await act(async () => root.unmount());
+  });
+});

package/src/utils/authoredSource.ts

@@ -1,4 +1,8 @@
 import { ensureHfIds, isCompositionTemplate } from "@hyperframes/parsers/hf-ids";
+import {
+  STUDIO_PREVIEW_LAZY_ATTR,
+  STUDIO_PREVIEW_UPCOMING_ATTR,
+} from "@hyperframes/core/studio-preview-mark";
 
 // Stamped as the preview stamps the files it serves, so a live element's hf-id finds its source.
 export function parseSavedSource(html: string): Document {
@@ -90,3 +94,14 @@ export function authoredMarkup(authored: Element, live: Element, sourceFile: str
   }
   return copy.outerHTML;
 }
+
+export function liveMarkupWithoutPreviewMarks(live: Element): string {
+  const copy = live.cloneNode(true) as Element;
+  for (const el of [copy, ...Array.from(copy.querySelectorAll("*"))]) {
+    el.removeAttribute(STUDIO_PREVIEW_UPCOMING_ATTR);
+    if (!el.hasAttribute(STUDIO_PREVIEW_LAZY_ATTR)) continue;
+    el.removeAttribute("loading");
+    el.removeAttribute(STUDIO_PREVIEW_LAZY_ATTR);
+  }
+  return copy.outerHTML;
+}

package/src/utils/blockInstaller.ts

@@ -9,6 +9,7 @@ import { collectHtmlIds } from "./studioHelpers";
 import { generateId } from "./generateId";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
+import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
 import { extendRootDurationInSource } from "./rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
@@ -93,12 +94,14 @@ async function makeComponentBackgroundTransparent(
   writeProjectFile: AddBlockOptions["writeProjectFile"],
 ): Promise<void> {
   if (block.type !== "hyperframes:component") return;
-  const content = await readProjectFile(compositionFile);
-  const transparentContent = content.replace(
-    /background:\s*(?:#(?:0a0a0a|000000|000|0a0805)|rgba?\([^)]*\))\s*;/g,
-    "background: transparent;",
-  );
-  if (transparentContent !== content) await writeProjectFile(compositionFile, transparentContent);
+  await serializeStudioFileMutation(writeProjectFile, compositionFile, async () => {
+    const content = await readProjectFile(compositionFile);
+    const transparentContent = content.replace(
+      /background:\s*(?:#(?:0a0a0a|000000|000|0a0805)|rgba?\([^)]*\))\s*;/g,
+      "background: transparent;",
+    );
+    if (transparentContent !== content) await writeProjectFile(compositionFile, transparentContent);
+  });
 }
 
 function resolveBlockPlacement({
@@ -201,7 +204,6 @@ export async function addBlockToProject(
     );
 
     const targetPath = activeCompPath || "index.html";
-    const originalContent = await readProjectFile(targetPath);
     const relevantElements = timelineElements.filter(
       (element) => (element.sourceFile || targetPath) === targetPath,
     );
@@ -211,29 +213,32 @@ export async function addBlockToProject(
       timelineElements: relevantElements,
       currentTime: opts.currentTime ?? 0,
     });
-    const { width, height } = resolveTimelineAssetCompositionSize(originalContent);
-    const hostId = buildUniqueCompositionId(block.name, collectHtmlIds(originalContent));
-    const subComposition = buildSubCompositionHtml({
-      id: hostId,
-      compositionFile,
-      start,
-      duration,
-      track,
-      width,
-      height,
-      left: visualPosition ? Math.round(visualPosition.left) : 0,
-      top: visualPosition ? Math.round(visualPosition.top) : 0,
-      zIndex: getMaxZIndexFromIframe(opts.previewIframe ?? null) + 1,
-    });
-    const patchedContent = extendRootDurationInSource(
-      insertTimelineAssetIntoSource(originalContent, subComposition),
-      start + duration,
-    );
+    let hostId = "";
+    const insertHost = (originalContent: string) => {
+      const { width, height } = resolveTimelineAssetCompositionSize(originalContent);
+      hostId = buildUniqueCompositionId(block.name, collectHtmlIds(originalContent));
+      const subComposition = buildSubCompositionHtml({
+        id: hostId,
+        compositionFile,
+        start,
+        duration,
+        track,
+        width,
+        height,
+        left: visualPosition ? Math.round(visualPosition.left) : 0,
+        top: visualPosition ? Math.round(visualPosition.top) : 0,
+        zIndex: getMaxZIndexFromIframe(opts.previewIframe ?? null) + 1,
+      });
+      return extendRootDurationInSource(
+        insertTimelineAssetIntoSource(originalContent, subComposition),
+        start + duration,
+      );
+    };
     await saveProjectFilesWithHistory({
       projectId,
       label: `Add ${isBlock ? "block" : "component"}: ${block.title}`,
-      files: { [targetPath]: patchedContent },
-      readFile: async () => originalContent,
+      files: { [targetPath]: insertHost },
+      readFile: readProjectFile,
       writeFile: writeProjectFile,
       recordEdit,
     });

package/src/utils/studioFileHistory.test.ts

@@ -11,7 +11,7 @@ describe("saveProjectFilesWithHistory", () => {
     await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Move layer",
-      files: { "index.html": "after" },
+      files: { "index.html": () => "after" },
       readFile: async (path) => reads[path],
       writeFile: async (path, content) => {
         writes[path] = content;
@@ -40,7 +40,7 @@ describe("saveProjectFilesWithHistory", () => {
     await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Delete timeline clip",
-      files: { "index.html": "removed+shrunk" },
+      files: { "index.html": () => "removed+shrunk" },
       readFile: async () => "original",
       diskContent: { "index.html": "removed" },
       writeFile: async (path, _content, expectedContent) => {
@@ -64,7 +64,7 @@ describe("saveProjectFilesWithHistory", () => {
     await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Move layer",
-      files: { "index.html": "after" },
+      files: { "index.html": () => "after" },
       readFile: async () => "before",
       writeFile: async (path, _content, expectedContent) => {
         expectations[path] = expectedContent;
@@ -81,7 +81,7 @@ describe("saveProjectFilesWithHistory", () => {
     const changedPaths = await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Edit layer",
-      files: { "index.html": "same" },
+      files: { "index.html": () => "same" },
       readFile: async () => "same",
       writeFile,
       recordEdit,
@@ -105,8 +105,8 @@ describe("saveProjectFilesWithHistory", () => {
         projectId: "project-1",
         label: "Move layer",
         files: {
-          "index.html": "index-after",
-          "scene.html": "scene-after",
+          "index.html": () => "index-after",
+          "scene.html": () => "scene-after",
         },
         readFile: async (path) => reads[path],
         writeFile: async (path, content) => {
@@ -139,8 +139,8 @@ describe("saveProjectFilesWithHistory", () => {
         projectId: "project-1",
         label: "Move layer",
         files: {
-          "index.html": "index-after",
-          "scene.html": "scene-after",
+          "index.html": () => "index-after",
+          "scene.html": () => "scene-after",
         },
         readFile: async (path) => reads[path],
         writeFile: async (path, content) => {
@@ -172,8 +172,8 @@ describe("saveProjectFilesWithHistory", () => {
         projectId: "project-1",
         label: "Move layer",
         files: {
-          "index.html": "index-after",
-          "scene.html": "scene-after",
+          "index.html": () => "index-after",
+          "scene.html": () => "scene-after",
         },
         readFile: async (path) => reads[path],
         writeFile: async (path, content) => {
@@ -196,7 +196,7 @@ describe("saveProjectFilesWithHistory", () => {
     ]);
   });
 
-  it("reads and writes after an earlier same-file mutation completes", async () => {
+  it("builds from what the file holds after an earlier same-file mutation completes", async () => {
     let disk = "before";
     let release!: () => void;
     const blocked = new Promise<void>((resolve) => {
@@ -215,7 +215,7 @@ describe("saveProjectFilesWithHistory", () => {
     const save = saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Edit source",
-      files: { "index.html": "editor-after" },
+      files: { "index.html": (current) => `${current}+editor` },
       readFile,
       writeFile,
       recordEdit,
@@ -227,10 +227,10 @@ describe("saveProjectFilesWithHistory", () => {
     await priorMutation;
     await save;
 
-    expect(disk).toBe("editor-after");
+    expect(disk).toBe("sdk-after+editor");
     expect(recordEdit).toHaveBeenCalledWith(
       expect.objectContaining({
-        files: { "index.html": { before: "sdk-after", after: "editor-after" } },
+        files: { "index.html": { before: "sdk-after", after: "sdk-after+editor" } },
       }),
     );
   });