@hyperframes/studio 0.7.59 → 0.7.61

package/src/player/lib/timelineIframeHelpers.ts

@@ -12,6 +12,7 @@
 
 import type { TimelineElement } from "../store/playerStore";
 import type { IframeWindow } from "./playbackTypes";
+import { readClipTiming } from "@hyperframes/core/composition-contract";
 import {
   getTimelineElementSelector,
   getTimelineElementSourceFile,
@@ -38,6 +39,9 @@ export function normalizePreviewViewport(doc: Document, win: Window): void {
   win.scrollTo({ top: 0, left: 0, behavior: "auto" });
 }
 
+// Legacy recovery retained until versioned composition manifests complete
+// their compatibility soak across published CDN runtimes.
+// fallow-ignore-next-line complexity
 export function autoHealMissingCompositionIds(doc: Document): void {
   const compositionIdRe = /data-composition-id=["']([^"']+)["']/gi;
   const referencedIds = new Set<string>();
@@ -258,6 +262,141 @@ export function stopScrubPreviewAudio(): void {
 // Enrich missing compositions from DOM
 // ---------------------------------------------------------------------------
 
+function timelineDuration(iframeWin: IframeWindow, compositionId: string): number {
+  return (
+    (
+      iframeWin.__timelines?.[compositionId] as { duration?: () => number } | undefined
+    )?.duration?.() ?? 0
+  );
+}
+
+function createTimedElementLookup(doc: Document): Map<string, Element> {
+  const timedById = new Map<string, Element>();
+  for (const timed of doc.querySelectorAll("[data-start]")) {
+    for (const id of [
+      timed.id,
+      timed.getAttribute("data-hf-id"),
+      timed.getAttribute("data-composition-id"),
+    ]) {
+      if (id) timedById.set(id, timed);
+    }
+  }
+  return timedById;
+}
+
+function createReferenceEndResolver(
+  timedById: ReadonlyMap<string, Element>,
+  iframeWin: IframeWindow,
+): (refId: string, visiting: ReadonlySet<string>) => number | null {
+  const resolveEnd = (refId: string, visiting: ReadonlySet<string>): number | null => {
+    if (visiting.has(refId)) return null;
+    const referenced = timedById.get(refId);
+    if (!referenced) return null;
+    const next = new Set(visiting).add(refId);
+    const timing = readClipTiming(referenced, {
+      resolveReferenceEnd: (nestedId) => resolveEnd(nestedId, next),
+    });
+    if (timing.end != null) return timing.end;
+    const compositionId = referenced.getAttribute("data-composition-id");
+    const duration = compositionId ? timelineDuration(iframeWin, compositionId) : 0;
+    return timing.start == null || duration <= 0 ? null : timing.start + duration;
+  };
+  return resolveEnd;
+}
+
+function clampCompositionWindow(
+  start: number,
+  duration: number,
+  rootDuration: number,
+): { start: number; duration: number } | null {
+  if (!Number.isFinite(duration) || duration <= 0) return null;
+  const safeStart = Number.isFinite(start) ? start : 0;
+  if (!Number.isFinite(rootDuration) || rootDuration <= 0) {
+    return { start: safeStart, duration };
+  }
+  if (safeStart >= rootDuration) return null;
+  const clamped = Math.min(duration, Math.max(0, rootDuration - safeStart));
+  return clamped > 0 ? { start: safeStart, duration: clamped } : null;
+}
+
+function nonEmpty(value: string, fallback: string): string {
+  return value || fallback;
+}
+
+function optionalNonEmpty(value: string | null): string | undefined {
+  return value || undefined;
+}
+
+function attachCompositionSource(
+  entry: TimelineElement,
+  element: HTMLElement,
+  compositionSrc: string | null,
+): TimelineElement {
+  if (compositionSrc) return { ...entry, compositionSrc };
+  const innerVideo = element.querySelector("video[src]");
+  if (!innerVideo) return entry;
+  return { ...entry, src: optionalNonEmpty(innerVideo.getAttribute("src")), tag: "video" };
+}
+
+function buildMissingCompositionEntry(params: {
+  doc: Document;
+  iframeWin: IframeWindow;
+  element: HTMLElement;
+  compositionId: string;
+  rootDuration: number;
+  fallbackIndex: number;
+  resolveEnd: (refId: string, visiting: ReadonlySet<string>) => number | null;
+}): TimelineElement | null {
+  const { doc, iframeWin, element, compositionId, rootDuration, fallbackIndex, resolveEnd } =
+    params;
+  const timing = readClipTiming(element, {
+    resolveReferenceEnd: (refId) => resolveEnd(refId, new Set([compositionId])),
+  });
+  const window = clampCompositionWindow(
+    timing.start ?? 0,
+    timing.duration ?? timelineDuration(iframeWin, compositionId),
+    rootDuration,
+  );
+  if (!window) return null;
+
+  const preferredId = nonEmpty(element.id, compositionId);
+  const compositionSrc =
+    element.getAttribute("data-composition-src") ?? element.getAttribute("data-composition-file");
+  const selector = getTimelineElementSelector(element);
+  const sourceFile = getTimelineElementSourceFile(element);
+  const selectorIndex = getTimelineElementSelectorIndex(doc, element, selector);
+  const label = getTimelineElementDisplayLabel({
+    id: preferredId,
+    label: element.getAttribute("data-timeline-label") ?? element.getAttribute("data-label"),
+    tag: element.tagName,
+  });
+  const identity = buildTimelineElementIdentity({
+    preferredId,
+    label,
+    fallbackIndex,
+    domId: optionalNonEmpty(element.id),
+    selector,
+    selectorIndex,
+    sourceFile,
+  });
+  const entry: TimelineElement = {
+    id: identity.id,
+    label,
+    key: identity.key,
+    tag: element.tagName.toLowerCase(),
+    start: window.start,
+    duration: window.duration,
+    track: timing.trackIndex,
+    domId: optionalNonEmpty(element.id),
+    hfId: optionalNonEmpty(element.getAttribute("data-hf-id")),
+    selector,
+    selectorIndex,
+    sourceFile,
+    zIndex: readTimelineElementZIndex(element),
+  };
+  return attachCompositionSource(entry, element, compositionSrc);
+}
+
 /**
  * Scan the iframe DOM for composition hosts missing from the current
  * timeline elements and add them.  The CDN runtime often fails to resolve
@@ -279,117 +418,24 @@ export function buildMissingCompositionElements(
   const hosts = doc.querySelectorAll("[data-composition-id][data-start]");
   const missing: TimelineElement[] = [];
 
-  hosts.forEach((host) => {
+  const resolveEnd = createReferenceEndResolver(createTimedElementLookup(doc), iframeWin);
+
+  for (const host of hosts) {
     const el = host as HTMLElement;
     const compId = el.getAttribute("data-composition-id");
-    if (!compId || compId === rootCompId) return;
-    if (existingIds.has(el.id) || existingIds.has(compId)) return;
-
-    // Resolve start: numeric or element-reference
-    const startAttr = el.getAttribute("data-start") ?? "0";
-    let start = parseFloat(startAttr);
-    if (isNaN(start)) {
-      const ref =
-        doc.getElementById(startAttr) ||
-        doc.querySelector(`[data-composition-id="${CSS.escape(startAttr)}"]`);
-      if (ref) {
-        const refStartAttr = ref.getAttribute("data-start") ?? "0";
-        let refStart = parseFloat(refStartAttr);
-        // Recursively resolve one level of reference for the ref's own start
-        if (isNaN(refStart)) {
-          const refRef =
-            doc.getElementById(refStartAttr) ||
-            doc.querySelector(`[data-composition-id="${CSS.escape(refStartAttr)}"]`);
-          const rrStart = parseFloat(refRef?.getAttribute("data-start") ?? "0") || 0;
-          const rrCompId = refRef?.getAttribute("data-composition-id");
-          const rrDur =
-            parseFloat(refRef?.getAttribute("data-duration") ?? "") ||
-            (rrCompId
-              ? ((
-                  iframeWin.__timelines?.[rrCompId] as { duration?: () => number } | undefined
-                )?.duration?.() ?? 0)
-              : 0);
-          refStart = rrStart + rrDur;
-        }
-        const refCompId = ref.getAttribute("data-composition-id");
-        const refDur =
-          parseFloat(ref.getAttribute("data-duration") ?? "") ||
-          (refCompId
-            ? ((
-                iframeWin.__timelines?.[refCompId] as { duration?: () => number } | undefined
-              )?.duration?.() ?? 0)
-            : 0);
-        start = refStart + refDur;
-      } else {
-        start = 0;
-      }
-    }
-
-    // Resolve duration from data-duration or GSAP timeline
-    let dur = parseFloat(el.getAttribute("data-duration") ?? "");
-    if (isNaN(dur) || dur <= 0) {
-      dur =
-        (
-          iframeWin.__timelines?.[compId] as { duration?: () => number } | undefined
-        )?.duration?.() ?? 0;
-    }
-    if (!Number.isFinite(dur) || dur <= 0) return;
-    if (!Number.isFinite(start)) start = 0;
-    if (Number.isFinite(rootDuration) && rootDuration > 0) {
-      if (start >= rootDuration) return;
-      dur = Math.min(dur, Math.max(0, rootDuration - start));
-      if (dur <= 0) return;
-    }
-
-    const trackStr = el.getAttribute("data-track-index");
-    const track = trackStr != null ? parseInt(trackStr, 10) : 0;
-    // fallow-ignore-next-line code-duplication
-    const compSrc =
-      el.getAttribute("data-composition-src") || el.getAttribute("data-composition-file");
-    const selector = getTimelineElementSelector(el);
-    const sourceFile = getTimelineElementSourceFile(el);
-    const selectorIndex = getTimelineElementSelectorIndex(doc, el, selector);
-    const label = getTimelineElementDisplayLabel({
-      id: el.id || compId || null,
-      label: el.getAttribute("data-timeline-label") ?? el.getAttribute("data-label"),
-      tag: el.tagName,
-    });
-    const identity = buildTimelineElementIdentity({
-      preferredId: el.id || compId || null,
-      label,
+    if (!compId || compId === rootCompId) continue;
+    if (existingIds.has(el.id) || existingIds.has(compId)) continue;
+    const entry = buildMissingCompositionEntry({
+      doc,
+      iframeWin,
+      element: el,
+      compositionId: compId,
+      rootDuration,
       fallbackIndex: missing.length,
-      domId: el.id || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
+      resolveEnd,
     });
-    const entry: TimelineElement = {
-      id: identity.id,
-      label,
-      key: identity.key,
-      tag: el.tagName.toLowerCase(),
-      start,
-      duration: dur,
-      track: isNaN(track) ? 0 : track,
-      domId: el.id || undefined,
-      hfId: el.getAttribute("data-hf-id") || undefined,
-      selector,
-      selectorIndex,
-      sourceFile,
-      zIndex: readTimelineElementZIndex(el),
-    };
-    if (compSrc) {
-      entry.compositionSrc = compSrc;
-    } else {
-      // Inline composition — expose inner video for thumbnails
-      const innerVideo = el.querySelector("video[src]");
-      if (innerVideo) {
-        entry.src = innerVideo.getAttribute("src") || undefined;
-        entry.tag = "video";
-      }
-    }
-    missing.push(entry);
-  });
+    if (entry) missing.push(entry);
+  }
 
   // Patch existing elements that are missing compositionSrc
   let patched = false;

package/src/utils/domEditSaveQueue.test.ts

@@ -114,4 +114,23 @@ describe("dom edit save queue", () => {
     expect(onOpen).not.toHaveBeenCalled();
     queue.destroy();
   });
+
+  it("pauses immediately on a file conflict instead of retrying stale work", async () => {
+    const onOpen = vi.fn();
+    const queue = createDomEditSaveQueue({ failureThreshold: 5, onOpen });
+
+    await expect(
+      queue.enqueue(async () => {
+        throw new StudioSaveHttpError("File changed elsewhere", 409);
+      }),
+    ).rejects.toThrow("File changed elsewhere");
+
+    expect(onOpen).toHaveBeenCalledWith({
+      consecutiveFailures: 1,
+      errorMessage: "File changed elsewhere",
+      statusCode: 409,
+    });
+    await expect(queue.enqueue(async () => {})).rejects.toThrow("Auto-save is paused");
+    queue.destroy();
+  });
 });

package/src/utils/domEditSaveQueue.ts

@@ -59,7 +59,8 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
       return result;
     } catch (error) {
       consecutiveFailures += 1;
-      if (consecutiveFailures >= failureThreshold) open(error);
+      if (getStudioSaveStatusCode(error) === 409 || consecutiveFailures >= failureThreshold)
+        open(error);
       throw error;
     }
   };

package/src/utils/sdkCutover.test.ts

@@ -223,7 +223,7 @@ describe("sdkCutoverPersist", () => {
       target: "hf-abc",
       styles: { color: "red", opacity: "0.5" },
     });
-    expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html></html>");
+    expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html></html>", "before");
     expect(deps.reloadPreview).toHaveBeenCalled();
   });
 
@@ -852,7 +852,11 @@ describe("sdkDeletePersist", () => {
     const result = await sdkDeletePersist("hf-abc", "before", "/comp.html", session, deps);
     expect(result.status).toBe("committed");
     expect(session!.removeElement).toHaveBeenCalledWith("hf-abc");
-    expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html>after</html>");
+    expect(deps.writeProjectFile).toHaveBeenCalledWith(
+      "/comp.html",
+      "<html>after</html>",
+      "before",
+    );
   });
 
   it("records edit history with before/after diff", async () => {
@@ -937,7 +941,11 @@ describe("sdkTimingPersist", () => {
       duration: 5,
       trackIndex: 1,
     });
-    expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html>after</html>");
+    expect(deps.writeProjectFile).toHaveBeenCalledWith(
+      "/comp.html",
+      "<html>after</html>",
+      "<html>before</html>",
+    );
   });
 
   it("captures before-state before setTiming dispatch", async () => {
@@ -1158,7 +1166,11 @@ describe("sdkGsapTweenPersist", () => {
       "hf-box",
       expect.objectContaining({ method: "to" }),
     );
-    expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html>after</html>");
+    expect(deps.writeProjectFile).toHaveBeenCalledWith(
+      "/comp.html",
+      "<html>after</html>",
+      "<html>before</html>",
+    );
   });
 
   it("returns false for kind=add when element not found", async () => {
@@ -1262,7 +1274,11 @@ describe("sdkGsapKeyframePersist", () => {
       position: 50,
       value: { opacity: 0.5 },
     });
-    expect(deps.writeProjectFile).toHaveBeenCalledWith("/comp.html", "<html>after</html>");
+    expect(deps.writeProjectFile).toHaveBeenCalledWith(
+      "/comp.html",
+      "<html>after</html>",
+      "<html>before</html>",
+    );
     expect(deps.reloadPreview).toHaveBeenCalled();
   });
 

package/src/utils/sdkEditTransaction.ts

@@ -37,7 +37,7 @@ export interface CutoverDeps {
    * Must be bound to one project. Its identity plus path scopes the shared
    * mutation queue used by every whole-file writer in that project.
    */
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>;
   reloadPreview: () => void;
   domEditSaveTimestampRef: MutableRefObject<number>;
   refresh?: (after: string) => void;
@@ -148,13 +148,14 @@ function isCutoverResult(value: CandidateEdit | CutoverResult): value is Cutover
 async function rollbackWrite(
   targetPath: string,
   originalContent: string,
+  expectedCurrentContent: string,
   deps: CutoverDeps,
   cause: Error,
 ): Promise<Error> {
   try {
     deps.domEditSaveTimestampRef.current = Date.now();
     markSelfWrite(targetPath, originalContent);
-    await deps.writeProjectFile(targetPath, originalContent);
+    await deps.writeProjectFile(targetPath, originalContent, expectedCurrentContent);
     return cause;
   } catch (rollbackError) {
     return new AggregateError(
@@ -174,7 +175,7 @@ async function writeAndRecord(
   deps.domEditSaveTimestampRef.current = Date.now();
   markSelfWrite(targetPath, after);
   try {
-    await deps.writeProjectFile(targetPath, after);
+    await deps.writeProjectFile(targetPath, after, originalContent);
   } catch (error) {
     return asCutoverError(error);
   }
@@ -188,7 +189,7 @@ async function writeAndRecord(
     });
     return null;
   } catch (error) {
-    return rollbackWrite(targetPath, originalContent, deps, asCutoverError(error));
+    return rollbackWrite(targetPath, originalContent, after, deps, asCutoverError(error));
   }
 }
 

package/src/utils/studioFileHistory.ts

@@ -14,7 +14,7 @@ export interface RecordEditInput {
 export interface DomEditCommitBaseParams {
   activeCompPath: string | null;
   showToast: (message: string, tone?: "error" | "info") => void;
-  writeProjectFile: (path: string, content: string) => Promise<void>;
+  writeProjectFile: ProjectFileWriter;
   domEditSaveTimestampRef: MutableRefObject<number>;
   editHistory: { recordEdit: (entry: RecordEditInput) => Promise<void> };
   projectIdRef: MutableRefObject<string | null>;
@@ -22,6 +22,8 @@ export interface DomEditCommitBaseParams {
   clearDomSelection: () => void;
 }
 
+type ProjectFileWriter = (path: string, content: string, expectedContent?: string) => Promise<void>;
+
 interface SaveProjectFilesWithHistoryInput {
   projectId: string;
   label: string;
@@ -30,7 +32,7 @@ interface SaveProjectFilesWithHistoryInput {
   coalesceMs?: number;
   files: Record<string, string>;
   readFile: (path: string) => Promise<string>;
-  writeFile: (path: string, content: string) => Promise<void>;
+  writeFile: ProjectFileWriter;
   recordEdit: (entry: RecordEditInput) => Promise<void>;
 }
 
@@ -71,7 +73,7 @@ export async function saveProjectFilesWithHistory({
     const writtenPaths: string[] = [];
     try {
       for (const path of changedPaths) {
-        await writeFile(path, snapshots[path].after);
+        await writeFile(path, snapshots[path].after, snapshots[path].before);
         writtenPaths.push(path);
       }
 
@@ -79,7 +81,7 @@ export async function saveProjectFilesWithHistory({
     } catch (error) {
       try {
         for (const path of writtenPaths.reverse()) {
-          await writeFile(path, snapshots[path].before);
+          await writeFile(path, snapshots[path].before, snapshots[path].after);
         }
       } catch (rollbackError) {
         throw new AggregateError(

package/src/utils/studioFileVersion.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { studioExpectedFileVersion, studioFileContentVersion } from "./studioFileVersion";
+
+describe("studioFileContentVersion", () => {
+  it("matches the strong SHA-256 ETag format used by studio-server", async () => {
+    await expect(studioFileContentVersion("abc")).resolves.toBe(
+      '"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"',
+    );
+  });
+
+  it("keeps an explicit content precondition authoritative over cached state", async () => {
+    const versions = new Map<string, string | null>([
+      ["stale.html", await studioFileContentVersion("stale")],
+      ["newer.html", await studioFileContentVersion("newer")],
+      ["missing.html", null],
+    ]);
+    const expectedVersion = await studioFileContentVersion("expected");
+
+    expect(await studioExpectedFileVersion(versions, "stale.html", "expected")).toBe(
+      expectedVersion,
+    );
+    expect(await studioExpectedFileVersion(versions, "newer.html", "expected")).toBe(
+      expectedVersion,
+    );
+    expect(await studioExpectedFileVersion(versions, "missing.html", "expected")).toBe(
+      expectedVersion,
+    );
+  });
+
+  it("keeps known-missing and untracked files distinct without explicit content", async () => {
+    const versions = new Map<string, string | null>([["missing.html", null]]);
+
+    expect(await studioExpectedFileVersion(versions, "missing.html")).toBeNull();
+    expect(await studioExpectedFileVersion(versions, "untracked.html")).toBeUndefined();
+  });
+});

package/src/utils/studioFileVersion.ts

@@ -0,0 +1,23 @@
+/** Browser-safe SHA-256 version matching studio-server's strong ETag format. */
+export async function studioFileContentVersion(content: string): Promise<string> {
+  const bytes = new TextEncoder().encode(content);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  const hex = Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join(
+    "",
+  );
+  return `"sha256:${hex}"`;
+}
+
+/** Prefer an explicit content precondition, then the version observed during the read. */
+export async function studioExpectedFileVersion(
+  versions: ReadonlyMap<string, string | null>,
+  path: string,
+  expectedContent?: string,
+): Promise<string | null | undefined> {
+  if (expectedContent !== undefined) return studioFileContentVersion(expectedContent);
+  return versions.get(path);
+}
+
+export function createStudioWriteToken(): string {
+  return globalThis.crypto.randomUUID();
+}

package/src/utils/studioSaveDiagnostics.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import {
+  StudioFileConflictError,
   StudioSaveHttpError,
   StudioSaveNetworkError,
   buildStudioSaveFailureProperties,
@@ -8,6 +9,23 @@ import {
 } from "./studioSaveDiagnostics";
 
 describe("studio save diagnostics", () => {
+  it("preserves conflict versions and both sides for explicit recovery UI", () => {
+    const error = new StudioFileConflictError({
+      filePath: "index.html",
+      currentVersion: '"sha256:new"',
+      currentContent: "external",
+      attemptedContent: "local",
+    });
+
+    expect(getStudioSaveStatusCode(error)).toBe(409);
+    expect(error).toMatchObject({
+      filePath: "index.html",
+      currentVersion: '"sha256:new"',
+      currentContent: "external",
+      attemptedContent: "local",
+    });
+  });
+
   it("builds save_failure properties with stable diagnostics", () => {
     const error = new StudioSaveHttpError("Failed to save index.html (503)", 503);
 

package/src/utils/studioSaveDiagnostics.ts

@@ -35,6 +35,27 @@ export class StudioSaveNetworkError extends Error {
   }
 }
 
+export class StudioFileConflictError extends StudioSaveHttpError {
+  readonly filePath: string;
+  readonly currentVersion: string | null;
+  readonly currentContent: string | null;
+  readonly attemptedContent: string;
+
+  constructor(input: {
+    filePath: string;
+    currentVersion: string | null;
+    currentContent: string | null;
+    attemptedContent: string;
+  }) {
+    super(`Save conflict: ${input.filePath} changed outside this Studio session`, 409);
+    this.name = "StudioFileConflictError";
+    this.filePath = input.filePath;
+    this.currentVersion = input.currentVersion;
+    this.currentContent = input.currentContent;
+    this.attemptedContent = input.attemptedContent;
+  }
+}
+
 function readNumericProperty(value: object, key: string): number | undefined {
   const record = value as Record<string, unknown>;
   const property = record[key];