@hyperframes/studio 0.8.75 → 0.8.77

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

@@ -33,6 +33,30 @@ beforeEach(() => {
 });
 
 describe("syncStoredAutomationFromPreview", () => {
+  it("reads the element the timeline bound, not an earlier same-id copy in a sub-composition", () => {
+    usePlayerStore.setState({ elements: [el({ hfId: "hf-root" })] });
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="strip"><audio id="bgm" data-hf-id="hf-inner"></audio></div>' +
+      '<audio id="bgm" data-hf-id="hf-root"></audio>';
+    doc.querySelector('[data-hf-id="hf-inner"]')?.setAttribute("data-automation", TWO_POINTS);
+    doc.querySelector('[data-hf-id="hf-root"]')?.setAttribute("data-automation", RESTORED);
+    syncStoredAutomationFromPreview(doc);
+    expect(usePlayerStore.getState().elements[0]?.automation).toBe(RESTORED);
+  });
+
+  it("reads the copy in the element's own file when a sub-composition repeats its hf-id", () => {
+    usePlayerStore.setState({ elements: [el({ hfId: "hf-bgm" })] });
+    const doc = document.implementation.createHTMLDocument("preview");
+    doc.body.innerHTML =
+      '<div data-composition-id="strip" data-composition-src="compositions/strip.html">' +
+      '<audio id="bgm" data-hf-id="hf-bgm"></audio></div><audio id="bgm" data-hf-id="hf-bgm"></audio>';
+    doc.querySelectorAll("audio")[0]?.setAttribute("data-automation", TWO_POINTS);
+    doc.querySelectorAll("audio")[1]?.setAttribute("data-automation", RESTORED);
+    syncStoredAutomationFromPreview(doc);
+    expect(usePlayerStore.getState().elements[0]?.automation).toBe(RESTORED);
+  });
+
   it("reads back an envelope an undo restored on the preview", () => {
     // The bug: a soft undo patches the preview document and re-runs the timeline, but
     // the store keeps its own copy of the attributes and that copy is what a lane

package/src/player/lib/automationStoreSync.ts

@@ -17,14 +17,7 @@ import { HF_AUDIO_AUTOMATION_ATTR } from "@hyperframes/core/audio-automation";
 import { HF_AUDIO_FX_ATTR } from "@hyperframes/core/audio-fx";
 import { usePlayerStore, type TimelineElement } from "../store/playerStore";
 import { groupInfoFor } from "./timelineGroupInfo";
-
-/** The preview node an element stands for, by dom id and then by `data-hf-id`. */
-function previewNodeFor(doc: Document, element: TimelineElement): Element | null {
-  const domId = element.domId ?? element.id;
-  const byId = domId ? doc.getElementById(domId) : null;
-  if (byId) return byId;
-  return element.hfId ? doc.querySelector(`[data-hf-id="${element.hfId}"]`) : null;
-}
+import { previewElementFinder } from "./timelineElementHelpers";
 
 /**
  * Re-read every element's automation and FX-chain attributes from the preview
@@ -62,10 +55,11 @@ function syncedFields(doc: Document, element: TimelineElement, node: Element) {
 
 export function syncStoredAutomationFromPreview(doc: Document | null | undefined): void {
   if (!doc) return;
+  const findNode = previewElementFinder(doc);
   usePlayerStore.setState((state) => {
     let changed = false;
     const elements = state.elements.map((element) => {
-      const node = previewNodeFor(doc, element);
+      const node = findNode(element);
       if (!node) return element;
       const fields = syncedFields(doc, element, node);
       // Same array back when nothing moved: `elements` keys memos all over the

package/src/player/lib/playbackScrub.ts

@@ -12,5 +12,5 @@ export function scrubMusicAtSeek(iframe: HTMLIFrameElement | null, nextTime: num
   if (!music || s.audioMuted) return;
   const rel = nextTime - music.start;
   const audioFileTime = rel >= 0 && rel <= music.duration ? (music.playbackStart ?? 0) + rel : null;
-  scrubPreviewAudio(iframe, audioFileTime, music.domId ?? music.id, s.audioVolume);
+  scrubPreviewAudio(iframe, audioFileTime, music, s.audioVolume);
 }

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

@@ -285,6 +285,34 @@ describe("createTimelineElementFromManifestClip — source-scoped selector ident
     });
   });
 
+  it("keeps the host it was given when a sub-composition is mounted twice", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="root" data-composition-file="index.html">
+        <div id="a" data-hf-id="hf-a" data-composition-id="card" data-composition-src="card.html"></div>
+        <div id="b" data-hf-id="hf-b" data-composition-id="card" data-composition-src="card.html"></div>
+      </div>
+    `);
+    const element = createTimelineElementFromManifestClip({
+      clip: {
+        id: "b",
+        label: "Card",
+        kind: "composition",
+        tagName: "div",
+        start: 4,
+        duration: 4,
+        track: 0,
+        compositionId: "card",
+        parentCompositionId: "root",
+        compositionSrc: null,
+        assetUrl: null,
+      },
+      fallbackIndex: 1,
+      doc,
+      hostEl: doc.getElementById("b"),
+    });
+    expect(element).toMatchObject({ domId: "b", hfId: "hf-b", compositionSrc: "card.html" });
+  });
+
   it("ignores an index.html duplicate when indexing a scene.html selector", () => {
     const doc = makeDoc(`
       <div data-composition-id="root" data-composition-file="index.html">

package/src/player/lib/timelineDOM.ts

@@ -171,8 +171,10 @@ export function createTimelineElementFromManifestClip(params: {
     entry.playbackRate ??= 1;
     let resolvedSrc = clip.compositionSrc;
     if (!resolvedSrc) {
-      hostEl =
-        doc?.querySelector(`[data-composition-id="${CSS.escape(clip.compositionId)}"]`) ?? hostEl;
+      if (hostEl?.getAttribute("data-composition-id") !== clip.compositionId) {
+        hostEl =
+          doc?.querySelector(`[data-composition-id="${CSS.escape(clip.compositionId)}"]`) ?? hostEl;
+      }
       resolvedSrc =
         hostEl?.getAttribute("data-composition-src") ??
         hostEl?.getAttribute("data-composition-file") ??

package/src/player/lib/timelineElementHelpers.ts

@@ -428,14 +428,83 @@ function nodeMatchesManifestClip(node: Element, clip: ClipManifestClip): boolean
   });
 }
 
-function findTimelineDomNode(doc: Document, id: string): Element | null {
-  return (
-    doc.getElementById(id) ??
-    doc.querySelector(`[data-hf-id="${CSS.escape(id)}"]`) ??
-    doc.querySelector(`[data-composition-id="${CSS.escape(id)}"]`) ??
-    doc.querySelector(`.${CSS.escape(id)}`) ??
-    null
-  );
+/** Whether `node` sits in the composition the clip was read from, the chain the runtime records outermost first
+ * (`resolveNearestCompositionContext` in core's runtime/timeline.ts). A clip without that scope accepts any node. */
+function nodeInClipScope(node: Element, clip: ClipManifestClip): boolean {
+  const scope = clip.compositionAncestors;
+  if (!scope) return true;
+  const ids: string[] = [];
+  for (let cursor = node.parentElement; cursor; cursor = cursor.parentElement) {
+    const id = cursor.getAttribute("data-composition-id");
+    if (id) ids.unshift(id);
+  }
+  return ids.length === scope.length && ids.every((id, index) => id === scope[index]);
+}
+
+/** The first match in the clip's composition across `selectors`; a lone match stands only when none is in scope, as a
+ * healed host can stale the clip's chain for a pass. An id can repeat in a sub-composition earlier in the document. */
+function findInClipScope(
+  doc: Document,
+  clip: ClipManifestClip,
+  selectors: string[],
+): Element | null {
+  let lone: Element | null = null;
+  for (const selector of selectors) {
+    const nodes = Array.from(doc.querySelectorAll(selector));
+    const scoped = nodes.find((node) => nodeInClipScope(node, clip));
+    if (scoped) return scoped;
+    if (nodes.length === 1) lone ??= nodes[0];
+  }
+  return lone;
+}
+
+export type PreviewTarget = Pick<TimelineElement, "hfId" | "domId" | "id" | "sourceFile">;
+
+/** Finds a row's preview element by `data-hf-id`, then id, preferring one in the row's own file: both repeat across
+ * files. Indexes the document once, so a pass over every row costs one scan. */
+export function previewElementFinder(
+  doc: Document,
+  selector = "[data-hf-id], [id]",
+): (target: PreviewTarget) => Element | null {
+  const byKey = new Map<string, Element[]>();
+  const add = (key: string, node: Element) => {
+    const nodes = byKey.get(key);
+    if (nodes) nodes.push(node);
+    else byKey.set(key, [node]);
+  };
+  for (const node of doc.querySelectorAll(selector)) {
+    const hfId = node.getAttribute("data-hf-id");
+    const id = node.getAttribute("id");
+    if (hfId) add(`hf:${hfId}`, node);
+    if (id) add(`id:${id}`, node);
+  }
+  return (target) => {
+    const matches = [
+      ...((target.hfId && byKey.get(`hf:${target.hfId}`)) || []),
+      ...(byKey.get(`id:${target.domId ?? target.id}`) ?? []),
+    ];
+    return (
+      matches.find((node) => getTimelineElementSourceFile(node) === target.sourceFile) ??
+      matches[0] ??
+      null
+    );
+  };
+}
+
+export function findClipElementById(doc: Document, clip: ClipManifestClip): Element | null {
+  if (!clip.id) return null;
+  const first = doc.getElementById(clip.id);
+  if (!first || nodeInClipScope(first, clip)) return first;
+  return findInClipScope(doc, clip, [`[id="${CSS.escape(clip.id)}"]`]);
+}
+
+function findTimelineDomNode(doc: Document, clip: ClipManifestClip): Element | null {
+  if (!clip.id) return null;
+  const first = doc.getElementById(clip.id);
+  if (first && nodeInClipScope(first, clip)) return first;
+  const id = CSS.escape(clip.id);
+  const byOtherKeys = [`[data-hf-id="${id}"]`, `[data-composition-id="${id}"]`, `.${id}`];
+  return findInClipScope(doc, clip, first ? [`[id="${id}"]`, ...byOtherKeys] : byOtherKeys);
 }
 
 export function findTimelineDomNodeForClip(
@@ -445,7 +514,7 @@ export function findTimelineDomNodeForClip(
   usedNodes = new Set<Element>(),
   getCandidates = () => getTimelineDomNodes(doc),
 ): Element | null {
-  const byIdentity = clip.id ? findTimelineDomNode(doc, clip.id) : null;
+  const byIdentity = findTimelineDomNode(doc, clip);
   if (byIdentity && !usedNodes.has(byIdentity) && nodeMatchesClipTag(byIdentity, clip))
     return byIdentity;
 

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

@@ -17,6 +17,31 @@ function makeDoc(html: string): Document {
 }
 
 describe("buildMissingCompositionElements — hfId (R7)", () => {
+  it("labels a row from its own host when a sub-composition repeats the host's id", () => {
+    const doc = makeDoc(`
+      <div data-composition-id="main">
+        <div data-composition-id="strip" data-composition-src="compositions/strip.html"><div id="scene"></div></div>
+        <div id="scene" data-hf-id="hf-scene" data-composition-id="scene" data-composition-file="compositions/scene.html"></div>
+      </div>
+    `);
+    const row = {
+      id: "scene",
+      key: "scene",
+      tag: "div",
+      start: 0,
+      duration: 4,
+      track: 0,
+      hfId: "hf-scene",
+    };
+    const { updatedEls, patched } = buildMissingCompositionElements(
+      doc,
+      window as IframeWindow,
+      [row],
+      10,
+    );
+    expect([patched, updatedEls[0]?.compositionSrc]).toEqual([true, "compositions/scene.html"]);
+  });
+
   it("harvests hfId from data-hf-id on composition host elements", () => {
     const doc = makeDoc(`
       <div data-composition-id="root">
@@ -104,7 +129,7 @@ describe("scrubPreviewAudio", () => {
     audio.pause = vi.fn();
     iframe.contentDocument.body.append(audio);
 
-    scrubPreviewAudio(iframe, 0.5, "music", 0.4);
+    scrubPreviewAudio(iframe, 0.5, { id: "music" }, 0.4);
 
     expect(audio.volume).toBeCloseTo(0.1);
     stopScrubPreviewAudio();
@@ -112,13 +137,13 @@ describe("scrubPreviewAudio", () => {
 
   /**
    * The preview document is a different realm, so `instanceof HTMLAudioElement`
-   * is false for every node in it. That threw the `musicId` hint away and left
+   * is false for every node in it. That threw the `music` hint away and left
    * the first `<audio>` in the document as the only route — and the first
    * `<audio>` is often the voiceover, so scrubbing previewed the wrong track.
    * Two elements, music second, is what tells the two paths apart: with one
    * element the fallback reaches the right node by accident.
    */
-  it("previews the track named by musicId, not the first audio in the document", () => {
+  it("previews the track named by the music row, not the first audio in the document", () => {
     const iframe = document.createElement("iframe");
     document.body.append(iframe);
     const previewDoc = iframe.contentDocument;
@@ -139,13 +164,32 @@ describe("scrubPreviewAudio", () => {
     // The node really is cross-realm; this is the condition, not a contrivance.
     expect(music instanceof HTMLAudioElement).toBe(false);
 
-    scrubPreviewAudio(iframe, 0.5, "music-bed", 1);
+    scrubPreviewAudio(iframe, 0.5, { id: "music-bed" }, 1);
 
     expect(music.play).toHaveBeenCalled();
     expect(voiceover.play).not.toHaveBeenCalled();
     stopScrubPreviewAudio();
   });
 
+  it("previews the music row's own track when a sub-composition repeats its id", () => {
+    const iframe = document.createElement("iframe");
+    document.body.append(iframe);
+    const previewDoc = iframe.contentDocument;
+    if (!previewDoc?.body) throw new Error("expected an iframe document");
+    previewDoc.body.innerHTML =
+      '<div data-composition-id="strip" data-composition-src="compositions/strip.html"><audio id="music"></audio></div>' +
+      '<audio id="music" class="root"></audio>';
+    const [inner, root] = Array.from(previewDoc.querySelectorAll("audio"));
+    for (const audio of [inner, root])
+      Object.assign(audio!, { play: vi.fn(async () => {}), pause: vi.fn() });
+
+    scrubPreviewAudio(iframe, 0.5, { id: "music" }, 1);
+
+    expect(root!.play).toHaveBeenCalled();
+    expect(inner!.play).not.toHaveBeenCalled();
+    stopScrubPreviewAudio();
+  });
+
   /** A scrub audition is media running under a paused clock, which the runtime now
    *  stops on sight. So it borrows the element. That a leased element survives the
    *  tick is asserted runtime-side in core's `transportPark.test.ts`; here the
@@ -166,7 +210,7 @@ describe("scrubPreviewAudio", () => {
     const releasePausedMedia = vi.fn();
     (previewDoc.defaultView as IframeWindow).__hf = { leasePausedMedia, releasePausedMedia };
 
-    scrubPreviewAudio(iframe, 0.5, "music", 1);
+    scrubPreviewAudio(iframe, 0.5, { id: "music" }, 1);
 
     expect(leasePausedMedia).toHaveBeenCalledWith(music);
     expect(releasePausedMedia).not.toHaveBeenCalled();

package/src/player/lib/timelineIframeHelpers.ts

@@ -20,6 +20,8 @@ import {
   getTimelineElementDisplayLabel,
   buildTimelineElementIdentity,
   readTimelineElementZIndex,
+  previewElementFinder,
+  type PreviewTarget,
 } from "./timelineElementHelpers";
 import { postRuntimeControlMessage } from "./runtimeProtocol";
 import { transitionLabelsForDocument } from "./timelineTransitionMetadata";
@@ -216,14 +218,14 @@ let scrubStopTimer: ReturnType<typeof setTimeout> | null = null;
 let scrubPrevMuted: boolean | null = null;
 let scrubPrevVolume: number | null = null;
 
-// Resolve the SAME element the store identified as music: prefer its id, then
-// the role attribute, and only fall back to the first <audio> (which could be a
-// voiceover, so the id hint matters).
+// Resolve the SAME element the store identified as music: prefer that row's own
+// element, then the role attribute, and only fall back to the first <audio>
+// (which could be a voiceover, so the row hint matters).
 /**
  * `doc` is the preview iframe's document, so its `<audio>` nodes are instances of
  * the IFRAME's `HTMLAudioElement`, never this module's. `instanceof
  * HTMLAudioElement` here is false for every one of them, which silently threw the
- * `musicId` hint away and fell through to "first `<audio>` in the document" — the
+ * `music` hint away and fell through to "first `<audio>` in the document" — the
  * very thing the comment above warns can be a voiceover. Ask what the node IS.
  * Same rule and same reasoning as packages/core/src/runtime/domRealm.ts.
  */
@@ -235,9 +237,9 @@ function isAudioNode(node: Element | null): node is HTMLAudioElement {
   );
 }
 
-function resolveScrubAudioEl(doc: Document, musicId?: string | null): HTMLAudioElement | null {
-  if (musicId) {
-    const byId = doc.getElementById(musicId);
+function resolveScrubAudioEl(doc: Document, music?: PreviewTarget | null): HTMLAudioElement | null {
+  if (music) {
+    const byId = previewElementFinder(doc, "audio")(music);
     if (isAudioNode(byId)) return byId;
   }
   return (
@@ -283,7 +285,7 @@ function applyScrub(el: HTMLAudioElement, audioFileTime: number, previewVolume:
 export function scrubPreviewAudio(
   iframe: HTMLIFrameElement | null,
   audioFileTime: number | null,
-  musicId?: string | null,
+  music?: PreviewTarget | null,
   previewVolume = 1,
 ): void {
   if (!iframe) return;
@@ -298,7 +300,7 @@ export function scrubPreviewAudio(
     return;
   }
   if (!doc) return;
-  const el = resolveScrubAudioEl(doc, musicId);
+  const el = resolveScrubAudioEl(doc, music);
   if (el) applyScrub(el, audioFileTime, previewVolume);
 }
 
@@ -512,12 +514,11 @@ export function buildMissingCompositionElements(
 
   // Patch existing elements that are missing compositionSrc
   let patched = false;
+  const findHost = previewElementFinder(doc);
   const updatedEls = (currentEls as TimelineElement[]).map((existing) => {
     if (existing.compositionSrc) return existing;
-    // Find the matching DOM host by element id or composition id
     const host =
-      doc.getElementById(existing.id) ??
-      doc.querySelector(`[data-composition-id="${CSS.escape(existing.id)}"]`);
+      findHost(existing) ?? doc.querySelector(`[data-composition-id="${CSS.escape(existing.id)}"]`);
     if (!host) return existing;
     const compSrc =
       host.getAttribute("data-composition-src") || host.getAttribute("data-composition-file");

package/src/player/store/playerStore.test.ts

@@ -1,6 +1,6 @@
 // @vitest-environment happy-dom
 import { describe, it, expect, beforeEach, vi } from "vitest";
-import { usePlayerStore, liveTime, type TimelineElement } from "./playerStore";
+import { usePlayerStore, liveTime, whenPreviewBooted, type TimelineElement } from "./playerStore";
 import { thumbnailRevisionOf } from "./thumbnailSlice";
 
 /** The playback/selection state `reset()` restores (persistent prefs asserted separately). */
@@ -343,9 +343,20 @@ describe("usePlayerStore", () => {
       const video = doc.createElement("video");
       Object.defineProperty(video, "readyState", { value: 0, configurable: true });
       doc.body.appendChild(video);
+      usePlayerStore.getState().markPreviewLoadStep(doc);
       return { doc, video };
     }
 
+    it("waits for the document's load step before marking it ready", async () => {
+      const doc = document.implementation.createHTMLDocument("composition");
+      usePlayerStore.getState().requestTimelineReady(doc);
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      expect(usePlayerStore.getState().timelineReady).toBe(false);
+
+      usePlayerStore.getState().markPreviewLoadStep(doc);
+      await vi.waitFor(() => expect(usePlayerStore.getState().timelineReady).toBe(true));
+    });
+
     it("resolves timelineReady once the doc's media settles", async () => {
       const { doc, video } = stalledVideoDoc();
       usePlayerStore.getState().requestTimelineReady(doc);
@@ -748,3 +759,26 @@ describe("liveTime", () => {
     expect(result).toBe(false);
   });
 });
+
+describe("whenPreviewBooted", () => {
+  it("resolves false for a project the user left before its preview booted", async () => {
+    usePlayerStore.setState({ timelineProjectId: "project-a", previewBooted: false });
+    const waitA = whenPreviewBooted("project-a");
+
+    usePlayerStore.getState().beginTimelineSession("project-b");
+    usePlayerStore.getState().markPreviewBooted();
+
+    await expect(waitA).resolves.toBe(false);
+    await expect(whenPreviewBooted("project-b")).resolves.toBe(true);
+  });
+
+  it("waits through the open of its own project, then resolves on that project's boot", async () => {
+    usePlayerStore.setState({ timelineProjectId: "project-a", previewBooted: true });
+    const waitB = whenPreviewBooted("project-b");
+
+    usePlayerStore.getState().beginTimelineSession("project-b");
+    usePlayerStore.getState().markPreviewBooted();
+
+    await expect(waitB).resolves.toBe(true);
+  });
+});

package/src/player/store/playerStore.ts

@@ -551,3 +551,32 @@ export const usePlayerStore = create<PlayerState>((set, get) => ({
 }));
 
 attachPlayerStoreDevHandle(usePlayerStore);
+
+export function isPreviewBooted(projectId: string): boolean {
+  const { previewBooted, timelineProjectId } = usePlayerStore.getState();
+  return previewBooted && timelineProjectId === projectId;
+}
+
+/** True once projectId's live preview has booted, false once another project replaces it.
+ * Open-time work the first frame does not need (server parses, lint) waits on it. */
+export function whenPreviewBooted(projectId: string): Promise<boolean> {
+  const openedFrom = usePlayerStore.getState().timelineProjectId;
+  let seen = false;
+  const settle = (state: PlayerState): boolean | null => {
+    if (state.timelineProjectId === projectId) {
+      seen = true;
+      return state.previewBooted ? true : null;
+    }
+    return seen || state.timelineProjectId !== openedFrom ? false : null;
+  };
+  return new Promise((resolve) => {
+    const now = settle(usePlayerStore.getState());
+    if (now !== null) return resolve(now);
+    const stop = usePlayerStore.subscribe((state) => {
+      const result = settle(state);
+      if (result === null) return;
+      stop();
+      resolve(result);
+    });
+  });
+}

package/src/player/store/readinessSlice.ts

@@ -8,26 +8,45 @@ import { settleCompositionReadiness } from "@hyperframes/core/composition-readin
 
 export interface PlaybackReadinessSlice {
   timelineReady: boolean;
+  /** Latched when the project's first preview shows its first frame (or fails), kept through edit
+   *  reloads, so work that must not compete with the boot waits for it once. */
+  previewBooted: boolean;
   setTimelineReady: (ready: boolean) => void;
+  markPreviewBooted: () => void;
   /** Sets timelineReady once doc's readiness inputs settle, or immediately
-   *  if doc is null. A wait a later call supersedes never wins the race. */
+   *  if doc is null. A wait a later call supersedes never wins the race.
+   *  Waits for doc's load step first: it pauses and rewinds the preview, so a
+   *  Play enabled before it would be undone. */
   requestTimelineReady: (doc: Document | null) => void;
+  /** Called by the preview's load step for the document it ran on. */
+  markPreviewLoadStep: (doc: Document) => void;
 }
 
 let timelineReadyGeneration = 0;
+const loadStepDocs = new WeakSet<Document>();
+let awaitingLoadStep: { doc: Document; generation: number } | null = null;
 
 /** For a full timeline reset: bumps the generation so any requestTimelineReady
  * wait in flight can never resolve into what replaced it. */
-export function resetPlaybackReadinessState(): Pick<PlaybackReadinessSlice, "timelineReady"> {
+export function resetPlaybackReadinessState(): Pick<
+  PlaybackReadinessSlice,
+  "timelineReady" | "previewBooted"
+> {
   timelineReadyGeneration++;
-  return { timelineReady: false };
+  return { timelineReady: false, previewBooted: false };
 }
 
 export function createPlaybackReadinessSlice(
   set: StoreApi<PlaybackReadinessSlice>["setState"],
 ): PlaybackReadinessSlice {
+  const settle = (doc: Document, generation: number) =>
+    settleCompositionReadiness(doc, () => {
+      if (generation === timelineReadyGeneration) set({ timelineReady: true });
+    });
   return {
     timelineReady: false,
+    previewBooted: false,
+    markPreviewBooted: () => set({ previewBooted: true }),
     setTimelineReady: (ready) => {
       timelineReadyGeneration++;
       set({ timelineReady: ready });
@@ -35,9 +54,18 @@ export function createPlaybackReadinessSlice(
     requestTimelineReady: (doc) => {
       const generation = ++timelineReadyGeneration;
       if (!doc) return set({ timelineReady: true });
-      settleCompositionReadiness(doc, () => {
-        if (generation === timelineReadyGeneration) set({ timelineReady: true });
-      });
+      if (!loadStepDocs.has(doc)) {
+        awaitingLoadStep = { doc, generation };
+        return;
+      }
+      settle(doc, generation);
+    },
+    markPreviewLoadStep: (doc) => {
+      loadStepDocs.add(doc);
+      if (awaitingLoadStep?.doc !== doc) return;
+      const { generation } = awaitingLoadStep;
+      awaitingLoadStep = null;
+      settle(doc, generation);
     },
   };
 }

package/src/utils/blockInstaller.ts

@@ -9,7 +9,6 @@ import { collectHtmlIds } from "./studioHelpers";
 import { generateId } from "./generateId";
 import { formatTimelineAttributeNumber } from "../player/components/timelineEditing";
 import { saveProjectFilesWithHistory } from "./studioFileHistory";
-import type { EditHistoryKind } from "./editHistory";
 import { extendRootDurationInSource } from "./rootDuration";
 import { deriveTimelineStoreKeyForDomId } from "../player/lib/timelineElementHelpers";
 
@@ -41,7 +40,6 @@ interface AddBlockOptions {
   writeProjectFile: (path: string, content: string) => Promise<void>;
   recordEdit: (entry: {
     label: string;
-    kind: EditHistoryKind;
     coalesceKey?: string;
     files: Record<string, { before: string; after: string }>;
   }) => Promise<void>;
@@ -234,7 +232,6 @@ export async function addBlockToProject(
     await saveProjectFilesWithHistory({
       projectId,
       label: `Add ${isBlock ? "block" : "component"}: ${block.title}`,
-      kind: "timeline",
       files: { [targetPath]: patchedContent },
       readFile: async () => originalContent,
       writeFile: writeProjectFile,

package/src/utils/previewPrefetch.test.ts

@@ -0,0 +1,22 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { prefetchPreviewForHash } from "./previewPrefetch";
+
+describe("prefetchPreviewForHash", () => {
+  afterEach(() => vi.unstubAllGlobals());
+
+  it("requests the opening project's preview once, not on every hash update", () => {
+    const fetchStub = vi.fn(() => Promise.resolve(new Response("")));
+    vi.stubGlobal("fetch", fetchStub);
+
+    prefetchPreviewForHash("#project/demo");
+    prefetchPreviewForHash("#project/demo?t=2&tab=design");
+    prefetchPreviewForHash("#project/other");
+    prefetchPreviewForHash("#settings");
+
+    expect(fetchStub.mock.calls.map(([url]) => new URL(String(url)).pathname)).toEqual([
+      "/api/projects/demo/preview",
+      "/api/projects/other/preview",
+    ]);
+  });
+});

package/src/utils/previewPrefetch.ts

@@ -0,0 +1,14 @@
+import { applyPreviewVariablesToUrl } from "../hooks/previewVariablesStore";
+import { buildProjectApiPath, parseProjectIdFromHash } from "./projectRouting";
+
+let prefetched: string | null = null;
+
+/** Requests the URL's project preview while Studio boots, so the server builds it in parallel. */
+export function prefetchPreviewForHash(hash: string): void {
+  const projectId = parseProjectIdFromHash(hash);
+  if (!projectId || projectId === prefetched) return;
+  prefetched = projectId;
+  const url = new URL(buildProjectApiPath(projectId, "/preview"), window.location.origin);
+  applyPreviewVariablesToUrl(url);
+  fetch(url).catch(() => undefined);
+}

package/src/utils/razorSplitTransaction.test.ts

@@ -133,7 +133,6 @@ describe("runAtomicCutTransaction", () => {
     expect(writeProjectFile).not.toHaveBeenCalled();
     expect(recordEdit).toHaveBeenCalledWith({
       label: "Split timeline clip",
-      kind: "timeline",
       files: { "index.html": { before: "before", after: "after" } },
     });
     expect(observe).toHaveBeenCalledWith("index.html", '"v1"');

package/src/utils/razorSplitTransaction.ts

@@ -181,7 +181,7 @@ export function runAtomicCutTransaction(input: RunAtomicCutInput): Promise<Atomi
       result.files.map((file) => [file.path, { before: file.before, after: file.after }]),
     );
     try {
-      await input.recordEdit({ label: input.label, kind: "timeline", files: snapshots });
+      await input.recordEdit({ label: input.label, files: snapshots });
     } catch (error) {
       try {
         await rollbackUnrecordedCut(result.files, input.writeProjectFile);

package/src/utils/sdkEditTransaction.ts

@@ -1,5 +1,4 @@
 import { openComposition, type Composition } from "@hyperframes/sdk";
-import type { EditHistoryKind } from "./editHistory";
 import { hashContent, markSelfWrite } from "../hooks/sdkSelfWriteRegistry";
 import { trackStudioEvent } from "./studioTelemetry";
 import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
@@ -32,7 +31,6 @@ export interface CutoverDeps {
   editHistory: {
     recordEdit: (entry: {
       label: string;
-      kind: EditHistoryKind;
       coalesceKey?: string;
       coalesceMs?: number;
       files: Record<string, { before: string; after: string }>;
@@ -248,7 +246,6 @@ async function writeAndRecord(
   try {
     await deps.editHistory.recordEdit({
       label: options?.label ?? "Edit layer",
-      kind: "manual",
       ...(options?.coalesceKey ? { coalesceKey: options.coalesceKey } : {}),
       ...(options?.coalesceMs != null ? { coalesceMs: options.coalesceMs } : {}),
       files: { [targetPath]: { before: originalContent, after } },