@hyperframes/studio 0.8.75 → 0.8.76

package/src/player/lib/timelineElementHelpers.ts

@@ -428,14 +428,50 @@ 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 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 +481,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/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 } },

package/src/utils/studioFileHistory.test.ts

@@ -11,7 +11,6 @@ describe("saveProjectFilesWithHistory", () => {
     await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Move layer",
-      kind: "manual",
       files: { "index.html": "after" },
       readFile: async (path) => reads[path],
       writeFile: async (path, content) => {
@@ -23,7 +22,6 @@ describe("saveProjectFilesWithHistory", () => {
     expect(writes).toEqual({ "index.html": "after" });
     expect(recordEdit).toHaveBeenCalledWith({
       label: "Move layer",
-      kind: "manual",
       coalesceKey: undefined,
       files: { "index.html": { before: "before", after: "after" } },
     });
@@ -42,7 +40,6 @@ describe("saveProjectFilesWithHistory", () => {
     await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Delete timeline clip",
-      kind: "timeline",
       files: { "index.html": "removed+shrunk" },
       readFile: async () => "original",
       diskContent: { "index.html": "removed" },
@@ -67,7 +64,6 @@ describe("saveProjectFilesWithHistory", () => {
     await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Move layer",
-      kind: "manual",
       files: { "index.html": "after" },
       readFile: async () => "before",
       writeFile: async (path, _content, expectedContent) => {
@@ -85,7 +81,6 @@ describe("saveProjectFilesWithHistory", () => {
     const changedPaths = await saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Edit layer",
-      kind: "manual",
       files: { "index.html": "same" },
       readFile: async () => "same",
       writeFile,
@@ -109,7 +104,6 @@ describe("saveProjectFilesWithHistory", () => {
       saveProjectFilesWithHistory({
         projectId: "project-1",
         label: "Move layer",
-        kind: "manual",
         files: {
           "index.html": "index-after",
           "scene.html": "scene-after",
@@ -144,7 +138,6 @@ describe("saveProjectFilesWithHistory", () => {
       saveProjectFilesWithHistory({
         projectId: "project-1",
         label: "Move layer",
-        kind: "manual",
         files: {
           "index.html": "index-after",
           "scene.html": "scene-after",
@@ -178,7 +171,6 @@ describe("saveProjectFilesWithHistory", () => {
       saveProjectFilesWithHistory({
         projectId: "project-1",
         label: "Move layer",
-        kind: "manual",
         files: {
           "index.html": "index-after",
           "scene.html": "scene-after",
@@ -223,7 +215,6 @@ describe("saveProjectFilesWithHistory", () => {
     const save = saveProjectFilesWithHistory({
       projectId: "project-1",
       label: "Edit source",
-      kind: "source",
       files: { "index.html": "editor-after" },
       readFile,
       writeFile,

package/src/utils/studioFileHistory.ts

@@ -1,12 +1,10 @@
 import { buildProjectApiPath } from "./projectRouting";
 import type { MutableRefObject } from "react";
-import type { EditHistoryKind } from "./editHistory";
 import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
 import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
 
 export interface RecordEditInput {
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   coalesceMs?: number;
   files: Record<string, { before: string; after: string }>;
@@ -27,7 +25,6 @@ type ProjectFileWriter = (path: string, content: string, expectedContent?: strin
 interface SaveProjectFilesWithHistoryInput {
   projectId: string;
   label: string;
-  kind: EditHistoryKind;
   coalesceKey?: string;
   coalesceMs?: number;
   files: Record<string, string>;
@@ -65,7 +62,6 @@ export async function readProjectFileContent(pid: string, path: string): Promise
 
 export async function saveProjectFilesWithHistory({
   label,
-  kind,
   coalesceKey,
   coalesceMs,
   files,
@@ -93,7 +89,7 @@ export async function saveProjectFilesWithHistory({
         writtenPaths.push(path);
       }
 
-      await recordEdit({ label, kind, coalesceKey, coalesceMs, files: snapshots });
+      await recordEdit({ label, coalesceKey, coalesceMs, files: snapshots });
     } catch (error) {
       try {
         for (const path of writtenPaths.reverse()) {

package/src/utils/timelineCompositionInsert.ts

@@ -70,7 +70,6 @@ export async function commitTimelineCompositionInsertion(input: {
     try {
       await input.recordEdit({
         label: "Add composition to timeline",
-        kind: "timeline",
         files: { [input.targetPath]: { before: result.before, after: result.after } },
       });
     } catch (error) {