@hyperframes/studio 0.8.81 → 0.8.83

package/src/hooks/timelineTimingSync.ts

@@ -7,10 +7,18 @@ import { applySoftReload, applySoftReloadFinalization } from "../utils/gsapSoftR
 import { furthestClipEndFromDocument } from "../player/lib/timelineElementHelpers";
 import type { RecordEditInput } from "../utils/studioFileHistory";
 import { patchDocumentRootDuration } from "./timelineEditingGsap";
-import { studioWriteHeaders } from "../utils/studioFileVersion";
-
-class GsapPreviewConvergenceError extends Error {}
-class GsapOwnershipProtocolError extends GsapPreviewConvergenceError {}
+import {
+  GsapOwnershipProtocolError,
+  GsapPreviewConvergenceError,
+  postGsapMutation,
+  requireGsapOwnershipProtocol,
+  rollbackOwnedMutation,
+  type GsapMutationStatus,
+} from "./gsapMutationClient";
+import {
+  serializeStudioFileMutations,
+  type StudioProjectFileWriter,
+} from "../utils/studioFileMutationCoordinator";
 
 export async function readFileContent(projectId: string, targetPath: string): Promise<string> {
   if (targetPath.includes("\0") || targetPath.includes("..")) {
@@ -29,51 +37,6 @@ export async function readFileContent(projectId: string, targetPath: string): Pr
   return data.content;
 }
 
-/** Verify rollback ownership support before any GSAP mutation can land. */
-async function requireGsapOwnershipProtocol(projectId: string): Promise<void> {
-  const response = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-capabilities`,
-  );
-  if (!response.ok) {
-    throw new GsapOwnershipProtocolError("Server does not support owned GSAP mutations");
-  }
-  const body = await response.json().catch(() => null);
-  if (!isRecord(body) || body.atomicOwnershipPairs !== true) {
-    throw new GsapOwnershipProtocolError("Invalid GSAP mutation capability response");
-  }
-}
-
-/** Atomically restore one GSAP mutation only while its exact output still owns
- * the file. The server performs compare + write synchronously, eliminating the
- * client GET→PUT window that could overwrite a successor edit. */
-async function rollbackOwnedMutation(
-  projectId: string,
-  targetPath: string,
-  expected: string,
-  restore: string,
-): Promise<"restored" | "conflict"> {
-  if (targetPath.includes("\0") || targetPath.includes("..")) {
-    throw new Error(`Unsafe path: ${targetPath}`);
-  }
-  const response = await fetch(
-    `/api/projects/${encodeURIComponent(projectId)}/gsap-mutation-rollback/${encodeURIComponent(targetPath)}`,
-    {
-      method: "POST",
-      // Deliberately unclaimed: a rollback runs because a mutation did not
-      // converge, so let the restored file reload the preview.
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ expected, restore }),
-    },
-  );
-  if (!response.ok) {
-    throw new Error(`Failed to restore ${targetPath}`);
-  }
-  const result = (await response.json()) as { restored?: unknown; conflict?: unknown };
-  if (result.restored === true && result.conflict === false) return "restored";
-  if (result.restored === false && result.conflict === true) return "conflict";
-  throw new Error(`Invalid restore response for ${targetPath}`);
-}
-
 /** Best-effort live-iframe wrapper for patchDocumentRootDuration (see timelineEditingGsap). */
 function patchIframeRootDuration(iframe: HTMLIFrameElement | null, contentEnd: number): void {
   try {
@@ -102,79 +65,6 @@ export function captureDurationRollback(iframe: HTMLIFrameElement | null): () =>
   };
 }
 
-/**
- * The bits of the server GSAP-mutation response the timeline edit path needs.
- * `scriptText` is the rewritten root GSAP script — feeding it to `applySoftReload`
- * swaps the runtime timeline in place (no iframe reload = no all-clips flash). Null
- * when the endpoint didn't return one (older server, or a multi-script comp the
- * soft path can't scope) — the caller then full-reloads when `mutated`, or
- * rebinds the runtime timing in place when nothing was rewritten (see
- * syncTimingEditPreview).
- */
-export type GsapMutationStatus = {
-  mutated: boolean;
-  scriptText: string | null;
-  /** Atomic whole-file ownership pair returned by the mutation endpoint. */
-  before?: string;
-  after?: string;
-};
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}
-
-function readMutationStatus(value: unknown): GsapMutationStatus {
-  if (
-    !isRecord(value) ||
-    typeof value.mutated !== "boolean" ||
-    typeof value.before !== "string" ||
-    typeof value.after !== "string" ||
-    value.mutated !== (value.before !== value.after) ||
-    ("changed" in value && value.changed !== value.mutated)
-  ) {
-    throw new GsapOwnershipProtocolError("Invalid owned GSAP mutation response");
-  }
-  return {
-    mutated: value.mutated,
-    scriptText: typeof value.scriptText === "string" ? value.scriptText : null,
-    before: value.before,
-    after: value.after,
-  };
-}
-
-function readMutationError(value: unknown, fallback: string): string {
-  if (isRecord(value) && typeof value.error === "string") return value.error;
-  return fallback;
-}
-
-async function postGsapMutation(
-  projectId: string,
-  filePath: string,
-  mutation: Record<string, unknown>,
-  fallback: string,
-): Promise<GsapMutationStatus> {
-  let response: Response;
-  try {
-    response = await fetch(
-      `/api/projects/${encodeURIComponent(projectId)}/gsap-mutations/${encodeURIComponent(filePath)}`,
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...studioWriteHeaders() },
-        body: JSON.stringify(mutation),
-      },
-    );
-  } catch (error) {
-    throw new GsapPreviewConvergenceError(`${fallback}: mutation outcome unknown`, {
-      cause: error,
-    });
-  }
-  const body: unknown = await response.json().catch(() => null);
-  if (!response.ok) {
-    throw new GsapPreviewConvergenceError(readMutationError(body, fallback));
-  }
-  return readMutationStatus(body);
-}
-
 /** Re-derive live timing windows without re-executing composition scripts.
  * Works for zero-GSAP compositions; false asks the caller to full-reload. */
 function rebindPreviewTiming(iframe: HTMLIFrameElement | null, currentTime: number): boolean {
@@ -341,7 +231,7 @@ async function rollbackAfterFailure(
 // The ledger, reverse rollback, final ownership check, and history fold are one
 // transaction; extracting phases would obscure which function owns convergence.
 // fallow-ignore-next-line complexity
-async function foldGsapMutationIntoHistory(input: {
+async function foldGsapMutationInQueue(input: {
   projectId: string;
   label: string;
   coalesceKey?: string;
@@ -411,6 +301,18 @@ async function foldGsapMutationIntoHistory(input: {
   return status;
 }
 
+// The mutations, the ownership read and any rollback hold every touched file's queue.
+function foldGsapMutationIntoHistory(
+  input: Parameters<typeof foldGsapMutationInQueue>[0] & {
+    writeFile: StudioProjectFileWriter;
+    paths: readonly string[];
+  },
+): Promise<GsapMutationStatus> {
+  return serializeStudioFileMutations(input.writeFile, input.paths, () =>
+    foldGsapMutationInQueue(input),
+  );
+}
+
 /**
  * Shift all GSAP animation positions targeting a given element by a time delta.
  * Calls the server-side GSAP mutation endpoint which uses the AST-based parser.
@@ -491,6 +393,7 @@ export function finishClipTimingFallback(input: {
   label: string;
   coalesceKey?: string;
   recordEdit: (edit: RecordEditInput) => Promise<void>;
+  writeProjectFile: StudioProjectFileWriter;
   edit: SingleClipGsapEdit;
 }): Promise<void> {
   const { projectId, targetPath, domId, edit } = input;
@@ -519,6 +422,8 @@ export function finishClipTimingFallback(input: {
       timingChanged && domId && projectId
         ? () =>
             foldGsapMutationIntoHistory({
+              writeFile: input.writeProjectFile,
+              paths: [targetPath],
               projectId,
               label: input.label,
               coalesceKey: input.coalesceKey,
@@ -552,6 +457,7 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
   errorLabel: string;
   coalesceKey?: string;
   recordEdit: (edit: RecordEditInput) => Promise<void>;
+  writeProjectFile: StudioProjectFileWriter;
   activeCompPath: string | null;
   changes: readonly C[];
   resolveChangePath: (element: TimelineElement) => string;
@@ -568,6 +474,8 @@ export async function finishGroupTimingGsapFallback<C extends { element: Timelin
     reloadPreview: input.reloadPreview,
     gsapMutation: () =>
       foldGsapMutationIntoHistory({
+        writeFile: input.writeProjectFile,
+        paths: input.changes.map((change) => input.resolveChangePath(change.element)),
         projectId: input.projectId,
         label: input.label,
         coalesceKey: input.coalesceKey,

package/src/hooks/timelineTrackVisibility.ts

@@ -9,11 +9,11 @@ import {
 } from "../player/components/timelineTrackDisplay";
 import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
 import { isAudioTimelineElement } from "../utils/timelineInspector";
-import { readTagSnippetByTarget, type PatchOperation } from "../utils/sourcePatcher";
+import type { PatchOperation } from "../utils/sourcePatcher";
 import {
-  applyPatchByTarget,
-  buildPatchTarget,
   findTimelineElementInIframe,
+  operationChanges,
+  patchTimelineChangesInSource,
   readFileContent,
   type RecordEditInput,
 } from "./timelineEditingHelpers";
@@ -149,38 +149,24 @@ async function setElementsHidden({
     property: "hidden",
     value: hidden ? "" : null,
   };
-  const originalByPath = new Map<string, string>();
-  const files: Record<string, string> = {};
-
-  try {
-    for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
-      let patchedContent = await readFileContent(projectId, targetPath);
-      originalByPath.set(targetPath, patchedContent);
-
-      for (const element of fileElements) {
-        const patchTarget = buildPatchTarget(element);
-        if (!patchTarget) {
-          throw new Error(`Timeline element ${element.id} is missing a patchable target`);
-        }
-        if (readTagSnippetByTarget(patchedContent, patchTarget) === undefined) {
-          throw new Error(`Unable to patch timeline element ${element.id} in ${targetPath}`);
-        }
-        patchedContent = applyPatchByTarget(patchedContent, patchTarget, hiddenOperation);
-      }
-
-      files[targetPath] = patchedContent;
+  const files: Record<string, (current: string) => string> = {};
+  for (const [targetPath, fileElements] of groupElementsByTargetPath(elements, activeCompPath)) {
+    files[targetPath] = (current) => {
       pendingTimelineEditPathRef.current.add(targetPath);
-    }
+      return patchTimelineChangesInSource(
+        current,
+        targetPath,
+        operationChanges(fileElements, hiddenOperation),
+      );
+    };
+  }
 
+  try {
     const changedPaths = await saveProjectFilesWithHistory({
       projectId,
       label,
       files,
-      readFile: async (path) => {
-        const original = originalByPath.get(path);
-        if (original !== undefined) return original;
-        return readFileContent(projectId, path);
-      },
+      readFile: (path) => readFileContent(projectId, path),
       writeFile: writeProjectFile,
       recordEdit,
     });

package/src/hooks/useAskAgentModal.test.tsx

@@ -0,0 +1,78 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { DomEditSelection } from "../components/editor/domEditing";
+import { useAskAgentModal } from "./useAskAgentModal";
+
+const copied = vi.hoisted(() => [] as string[]);
+vi.mock("../utils/clipboard", () => ({
+  copyTextToClipboard: async (text: string) => copied.push(text) > 0,
+}));
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  copied.length = 0;
+  vi.unstubAllGlobals();
+});
+
+describe("useAskAgentModal", () => {
+  it("sends the live element without the preview's lazy loading or look-ahead mark, keeping authored loading", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("offline")));
+    const element = document.createElement("div");
+    element.setAttribute("data-hf-upcoming", "");
+    element.innerHTML =
+      '<img src="plate.png" loading="lazy" data-hf-preview-lazy><img src="own.png" loading="eager">';
+    const selection: DomEditSelection = {
+      element,
+      label: "Plate",
+      tagName: "div",
+      sourceFile: "index.html",
+      compositionPath: "index.html",
+      isCompositionHost: false,
+      isInsideLockedComposition: false,
+      selector: "div",
+      selectorIndex: 0,
+      boundingBox: { x: 0, y: 0, width: 10, height: 10 },
+      textContent: "",
+      dataAttributes: {},
+      inlineStyles: {},
+      computedStyles: {},
+      textFields: [],
+      capabilities: {
+        canSelect: true,
+        canEditStyles: true,
+        canCrop: false,
+        canMove: true,
+        canResize: true,
+        canApplyManualOffset: false,
+        canApplyManualSize: false,
+        canApplyManualRotation: false,
+      },
+    };
+    let hook: ReturnType<typeof useAskAgentModal> | null = null;
+    function Harness() {
+      hook = useAskAgentModal({
+        projectId: "demo",
+        activeCompPath: "index.html",
+        projectDir: "/demo",
+        projectIdRef: { current: "demo" },
+        showToast: () => {},
+        domEditSelectionRef: { current: selection },
+        domEditSelection: selection,
+      });
+      return null;
+    }
+    const host = document.body.appendChild(document.createElement("div"));
+    await act(async () => createRoot(host).render(<Harness />));
+
+    await act(async () => hook!.handleAgentModalSubmit("Make it bigger"));
+
+    expect(copied[0]).toContain('<img src="plate.png"><img src="own.png" loading="eager">');
+    expect(copied[0]).not.toContain("data-hf-preview-lazy");
+    expect(copied[0]).not.toContain("data-hf-upcoming");
+  });
+});

package/src/hooks/useAskAgentModal.ts

@@ -4,6 +4,7 @@ import { useState, useCallback, useRef, useEffect } from "react";
 import { copyTextToClipboard } from "../utils/clipboard";
 import { readTagSnippetByTarget } from "../utils/sourcePatcher";
 import { toProjectAbsolutePath, type AgentModalAnchorPoint } from "../utils/studioHelpers";
+import { liveMarkupWithoutPreviewMarks } from "../utils/authoredSource";
 import { buildElementAgentPrompt, type DomEditSelection } from "../components/editor/domEditing";
 import { usePlayerStore } from "../player";
 
@@ -89,7 +90,8 @@ export function useAskAgentModal({
       if (!domEditSelection) return;
 
       const targetPath = domEditSelection.sourceFile || activeCompPath || "index.html";
-      const tagSnippet = agentPromptTagSnippet ?? domEditSelection.element.outerHTML;
+      const tagSnippet =
+        agentPromptTagSnippet ?? liveMarkupWithoutPreviewMarks(domEditSelection.element);
       const prompt = buildElementAgentPrompt({
         selection: domEditSelection,
         currentTime: usePlayerStore.getState().currentTime,

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

@@ -220,6 +220,27 @@ describe("copy takes a clip's saved markup, not the runtime's live styling", ()
   });
 });
 
+describe("copy of a clip missing from its saved file", () => {
+  it("takes the preview's markup without its lazy loading or look-ahead mark, keeping authored loading", async () => {
+    selectTitle();
+    const { clipboard, writes, files, iframe } = mountClipboard();
+    const title = iframe.contentDocument?.querySelector("h1") as Element;
+    title.setAttribute("data-hf-upcoming", "");
+    title.insertAdjacentHTML(
+      "beforeend",
+      '<img src="plate.png" loading="lazy" data-hf-preview-lazy><img src="own.png" loading="lazy">',
+    );
+    files["index.html"] = SAVED.replace(/<h1[\s\S]*<\/h1>/, "");
+    clipboard().handleCopy();
+    await clipboard().handlePaste();
+    expect(writes[0]).toMatch(
+      /<img src="plate.png" data-hf-id="[^"]+"><img src="own.png" loading="lazy"/,
+    );
+    expect(writes[0]).not.toContain("data-hf-preview-lazy");
+    expect(writes[0]).not.toContain("data-hf-upcoming");
+  });
+});
+
 const SUB_SELECTION = {
   hfId: SUB_HF_ID,
   selector: "h2",
@@ -338,3 +359,14 @@ describe("a copy that fails", () => {
     expect(deleted).toEqual([]);
   });
 });
+
+describe("with no DOM edit session", () => {
+  it("refuses copy, cut and duplicate when nothing is selected", async () => {
+    clearSelection();
+    const { clipboard, deleted } = mountClipboard();
+    expect(clipboard().handleCopy()).toBe(false);
+    expect(await clipboard().handleCut()).toBe(false);
+    expect(await clipboard().handleDuplicate()).toBe(false);
+    expect(deleted).toEqual([]);
+  });
+});

package/src/hooks/useClipboard.ts

@@ -23,6 +23,7 @@ import {
   authoredMarkup,
   findAuthoredElement,
   findAuthoredElementById,
+  liveMarkupWithoutPreviewMarks,
   parseSavedSource,
 } from "../utils/authoredSource";
 import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
@@ -33,7 +34,7 @@ interface RecordEditInput {
   files: Record<string, { before: string; after: string }>;
 }
 
-interface UseClipboardOptions {
+export interface UseClipboardOptions {
   projectId: string | null;
   activeCompPath: string | null;
   domEditSelectionRef: React.MutableRefObject<DomEditSelection | null>;
@@ -88,7 +89,9 @@ function getSelectedDomElement(
 
 function savedMarkupElseLive(saved: Document, live: Element, sourceFile: string): string {
   const authored = findAuthoredElement(saved, live) ?? findAuthoredElementById(saved, live);
-  return authored ? authoredMarkup(authored, live, sourceFile) : live.outerHTML;
+  return authored
+    ? authoredMarkup(authored, live, sourceFile)
+    : liveMarkupWithoutPreviewMarks(live);
 }
 
 async function readSavedMarkup(
@@ -356,21 +359,17 @@ export function useClipboard({
 
     const targetPath = activeCompPath || "index.html";
     try {
-      const originalContent = await readFileContent(pid, targetPath);
-      let patchedContent: string;
       let pastedIds: string[] = [];
-
-      if (payload.kind === "timeline-clip") {
+      const paste = (originalContent: string) => {
+        if (payload.kind !== "timeline-clip") return pasteElementHtml(originalContent, payload);
         const { currentTime, elements } = usePlayerStore.getState();
         const pasted = pasteTimelineClips(originalContent, payload.clips, currentTime, elements);
+        pastedIds = pasted.ids;
         // A clip pasted past the current composition end would exist in the
         // file but never appear on the timeline or in playback/export (the
         // root's data-duration is what actually bounds the render).
-        patchedContent = extendRootDurationInSource(pasted.content, pasted.requiredEnd);
-        pastedIds = pasted.ids;
-      } else {
-        patchedContent = pasteElementHtml(originalContent, payload);
-      }
+        return extendRootDurationInSource(pasted.content, pasted.requiredEnd);
+      };
 
       const label =
         payload.kind === "timeline-clip"
@@ -380,8 +379,8 @@ export function useClipboard({
       await saveProjectFilesWithHistory({
         projectId: pid,
         label,
-        files: { [targetPath]: patchedContent },
-        readFile: async () => originalContent,
+        files: { [targetPath]: paste },
+        readFile: (path) => readFileContent(pid, path),
         writeFile: writeProjectFile,
         recordEdit,
       });
@@ -422,17 +421,19 @@ export function useClipboard({
 
     try {
       const clips = await readClips(targets);
-      const originalContent = await readFileContent(pid, targetPath);
-      const liveElements = usePlayerStore.getState().elements;
-      const pasted = pasteTimelineClips(originalContent, clips, anchorTime, liveElements);
-      const patchedContent = extendRootDurationInSource(pasted.content, pasted.requiredEnd);
-      const ids = pasted.ids;
+      let ids: string[] = [];
+      const duplicate = (originalContent: string) => {
+        const liveElements = usePlayerStore.getState().elements;
+        const pasted = pasteTimelineClips(originalContent, clips, anchorTime, liveElements);
+        ids = pasted.ids;
+        return extendRootDurationInSource(pasted.content, pasted.requiredEnd);
+      };
 
       await saveProjectFilesWithHistory({
         projectId: pid,
         label: clipLabel("Duplicate", clips.length),
-        files: { [targetPath]: patchedContent },
-        readFile: async () => originalContent,
+        files: { [targetPath]: duplicate },
+        readFile: (path) => readFileContent(pid, path),
         writeFile: writeProjectFile,
         recordEdit,
       });

package/src/hooks/useDomEditCommits.test.tsx

@@ -1252,8 +1252,15 @@ describe("useDomEditCommits style persist handling", () => {
 
       const secondCommit = rendered.hook.handleDomStyleCommit("color", "green");
       await flushAsyncWork();
-      expect(patchCount).toBe(2);
+      // The newer commit waits for the older one in the file's queue.
+      expect(patchCount).toBe(1);
 
+      firstPatch.reject(new Error("server rejected blue"));
+      await firstCommit;
+      expect(element.style.getPropertyValue("color")).toBe("green");
+
+      await flushAsyncWork();
+      expect(patchCount).toBe(2);
       secondPatch.resolve(
         jsonResponse({
           ok: true,
@@ -1263,10 +1270,6 @@ describe("useDomEditCommits style persist handling", () => {
         }),
       );
       await secondCommit;
-      expect(element.style.getPropertyValue("color")).toBe("green");
-
-      firstPatch.reject(new Error("server rejected blue"));
-      await firstCommit;
 
       expect(element.style.getPropertyValue("color")).toBe("green");
     } finally {
@@ -1698,15 +1701,16 @@ describe("useDomEditCommits attribute persist handling", () => {
     try {
       // Older commit's persist stays pending (captures previousValue=null); the
       // newer commit captures previousValue="first-value" (the older commit's
-      // optimistic apply) and succeeds before the older one rejects. Without the
+      // optimistic apply) and is still queued when the older one rejects. Without the
       // per-key version guard, the stale rejection would revert to the older
       // commit's own previousValue (null) and stomp the newer commit's value.
       const firstCommit = rendered.hook.handleDomHtmlAttributeCommit("muted", "first-value");
       await act(async () => {
-        await rendered.hook.handleDomHtmlAttributeCommit("muted", "second-value");
+        const secondCommit = rendered.hook.handleDomHtmlAttributeCommit("muted", "second-value");
+        first.reject(new Error("stale request failed"));
+        await firstCommit;
+        await secondCommit;
       });
-      first.reject(new Error("stale request failed"));
-      await firstCommit;
 
       expect(element.getAttribute("muted")).toBe("second-value");
     } finally {