ext/hyperframes
2
0
Fork 0
mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-08 19:06:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(studio): harden composition timeline reliability (#2615)

Browse Source 
* fix(studio): preserve composition playback continuity

* feat(studio): drag compositions into the timeline

* fix(studio): collapse expanded composition move aliases

* fix(studio): make timeline cuts atomic

* fix(studio): group inspector gesture history

* test(studio): cover masked text selection

* fix(studio): harden composition timeline reliability

* fix(studio): satisfy CI source gates

* fix(studio): harden composition mutation requests
This commit is contained in:
Miguel Ángel
2026-07-17 14:15:30 -04:00
committed by GitHub
parent 2be8a62c00
commit 2b65b4efce
93 changed files with 3925 additions and 758 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/studio/src/hooks/useRazorSplit.ts
+78 -350
View File
@@ -1,15 +1,10 @@
import { useCallback, useRef } from "react";
import type { TimelineElement } from "../player";
import { usePlayerStore } from "../player";
import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
import { getTimelineElementLabel, collectHtmlIds } from "../utils/studioHelpers";
import { getTimelineElementLabel } from "../utils/studioHelpers";
import { trackStudioRazorSplit } from "../telemetry/events";
import {
canSplitElementAt,
selectSplittableElements,
buildPatchTarget,
readFileContent,
} from "../utils/timelineElementSplit";
import { canSplitElementAt, selectSplittableElements } from "../utils/timelineElementSplit";
import { buildAtomicCutIntents, runAtomicCutTransaction } from "../utils/razorSplitTransaction";
import type { RecordEditInput } from "./timelineEditingHelpers";
interface UseRazorSplitOptions {
@@ -21,246 +16,10 @@ interface UseRazorSplitOptions {
recordEdit: (input: RecordEditInput) => Promise<void>;
domEditSaveTimestampRef: React.MutableRefObject<number>;
reloadPreview: () => void;
/**
* Resync the in-memory SDK session after the server-side split write (the
* split-element / split-gsap endpoints write the file directly, so the SDK's
* linkedom doc is now stale). This reload is read-only; the split endpoint owns
* the final on-disk bytes and history baseline. Every other server-side-write
* timeline path (move / resize / delete / drop / visibility) also resyncs.
*/
forceReloadSdkSession?: () => void;
isRecordingRef?: React.RefObject<boolean>;
}
function generateSplitId(existingIds: string[], baseId: string): string {
let newId = `${baseId}-split`;
let suffix = 2;
while (existingIds.includes(newId)) {
newId = `${baseId}-split-${suffix++}`;
}
return newId;
}
async function splitHtmlElement(
projectId: string,
targetPath: string,
patchTarget: NonNullable<ReturnType<typeof buildPatchTarget>>,
splitTime: number,
newId: string,
elementStart: number,
elementDuration: number,
): Promise<{ ok: boolean; changed?: boolean; content?: string; version: string }> {
const response = await fetch(
`/api/projects/${projectId}/file-mutations/split-element/${encodeURIComponent(targetPath)}`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
target: patchTarget,
splitTime,
newId,
elementStart,
elementDuration,
}),
},
);
if (!response.ok) throw new Error("Split request failed");
const data = (await response.json()) as {
ok: boolean;
changed?: boolean;
content?: string;
version?: string;
};
const version = data.version ?? response.headers.get("etag");
if (!version) throw new Error("Split response did not include a content version");
return { ...data, version };
}
// fallow-ignore-next-line complexity
async function splitGsapAnimations(
projectId: string,
targetPath: string,
originalId: string,
newId: string,
splitTime: number,
elementStart: number,
elementDuration: number,
): Promise<{ content: string | null; version?: string; skippedSelectors?: string[] }> {
const response = await fetch(
`/api/projects/${projectId}/gsap-mutations/${encodeURIComponent(targetPath)}`,
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
type: "split-animations",
originalId,
newId,
splitTime,
elementStart,
elementDuration,
}),
},
);
if (!response.ok) {
const errorBody = (await response.json().catch(() => null)) as { error?: string } | null;
if (errorBody?.error === "no GSAP script found in file") {
return { content: null };
}
throw new Error(errorBody?.error ?? `GSAP animation split failed (${response.status})`);
}
const data = (await response.json()) as {
ok?: boolean;
after?: string;
version?: string;
skippedSelectors?: string[];
};
return {
content: data.ok && data.after ? data.after : null,
version: data.version ?? response.headers.get("etag") ?? undefined,
skippedSelectors: data.skippedSelectors,
};
}
function getOriginalContent(originals: ReadonlyMap<string, string>, path: string): string {
const original = originals.get(path);
if (original === undefined) {
throw new Error(`Missing original contents for ${path}`);
}
return original;
}
async function restoreFilesToOriginal(
originals: ReadonlyMap<string, string>,
snapshots: ReadonlyMap<string, { before: string; after: string }>,
writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
): Promise<void> {
for (const [path, snapshot] of snapshots) {
await writeProjectFile(path, getOriginalContent(originals, path), snapshot.after);
}
}
async function readOriginalFiles(
pid: string,
elements: TimelineElement[],
activeCompPath: string | null,
): Promise<Map<string, string>> {
const originals = new Map<string, string>();
for (const element of elements) {
const path = element.sourceFile || activeCompPath || "index.html";
if (!originals.has(path)) {
originals.set(path, await readFileContent(pid, path));
}
}
return originals;
}
async function splitElementsAtTime(
pid: string,
elements: TimelineElement[],
splitTime: number,
activeCompPath: string | null,
originals: ReadonlyMap<string, string>,
snapshots: Map<string, { before: string; after: string }>,
writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
observeProjectFileVersion?: (path: string, version: string | null) => void,
): Promise<number> {
let count = 0;
for (const element of elements) {
const result = await executeSplit(
pid,
element,
splitTime,
activeCompPath,
writeProjectFile,
observeProjectFileVersion,
);
if (!result.changed) continue;
snapshots.set(result.targetPath, {
before: getOriginalContent(originals, result.targetPath),
after: result.patchedContent,
});
await writeProjectFile(result.targetPath, result.patchedContent, result.patchedContent);
count++;
}
return count;
}
// fallow-ignore-next-line complexity
async function executeSplit(
pid: string,
element: TimelineElement,
splitTime: number,
activeCompPath: string | null,
writeProjectFile: (path: string, content: string, expectedContent?: string) => Promise<void>,
observeProjectFileVersion?: (path: string, version: string | null) => void,
): Promise<{
targetPath: string;
originalContent: string;
patchedContent: string;
changed: boolean;
skippedSelectors?: string[];
}> {
const patchTarget = buildPatchTarget(element);
if (!patchTarget) throw new Error("Clip is missing a patchable target.");
const targetPath = element.sourceFile || activeCompPath || "index.html";
const originalContent = await readFileContent(pid, targetPath);
const newId = generateSplitId(collectHtmlIds(originalContent), element.domId || "clip");
// An expanded sub-comp child arrives in MASTER-timeline coordinates — both its
// `start` and the incoming `splitTime` are offset by the host's master start
// (expandedParentStart) — but its `sourceFile` is the sub-comp, whose clips are
// authored in LOCAL time. Rebase both onto local time before the server patches
// the file, exactly as TimelinePane.handleSplitElement does for non-razor edits.
// Root-level clips (no expandedParentStart) are already local, so pass through.
const basis = element.expandedParentStart;
const localSplitTime = basis === undefined ? splitTime : Math.max(0, splitTime - basis);
const localElementStart = basis === undefined ? element.start : element.start - basis;
const splitResult = await splitHtmlElement(
pid,
targetPath,
patchTarget,
localSplitTime,
newId,
localElementStart,
element.duration,
);
if (!splitResult.ok) throw new Error("Failed to split clip.");
if (!splitResult.changed) {
return { targetPath, originalContent, patchedContent: originalContent, changed: false };
}
observeProjectFileVersion?.(targetPath, splitResult.version);
let patchedContent =
typeof splitResult.content === "string" ? splitResult.content : originalContent;
let skippedSelectors: string[] | undefined;
if (element.domId) {
try {
const gsapResult = await splitGsapAnimations(
pid,
targetPath,
element.domId,
newId,
localSplitTime,
localElementStart,
element.duration,
);
if (gsapResult.content) patchedContent = gsapResult.content;
if (gsapResult.version) observeProjectFileVersion?.(targetPath, gsapResult.version);
if (gsapResult.skippedSelectors?.length) skippedSelectors = gsapResult.skippedSelectors;
} catch (gsapError) {
// GSAP mutation failed — the HTML split already wrote to disk.
// Restore the original content to avoid a corrupt half-split state.
await writeProjectFile(targetPath, originalContent, patchedContent);
throw gsapError;
}
}
return { targetPath, originalContent, patchedContent, changed: true, skippedSelectors };
}
export function useRazorSplit({
projectId,
activeCompPath,
@@ -276,140 +35,109 @@ export function useRazorSplit({
const projectIdRef = useRef(projectId);
projectIdRef.current = projectId;
const synchronize = useCallback(() => {
let failure: unknown;
try {
forceReloadSdkSession?.();
} catch (error) {
failure = error;
}
try {
reloadPreview();
} catch (error) {
failure ??= error;
}
if (failure) throw failure;
}, [forceReloadSdkSession, reloadPreview]);
const runCut = useCallback(
async (elements: readonly TimelineElement[], splitTime: number, mode: "single" | "all") => {
const pid = projectIdRef.current;
if (!pid || elements.length === 0) return;
const intents = buildAtomicCutIntents(elements, splitTime, activeCompPath);
const requestedCount = intents.reduce((count, file) => count + file.targets.length, 0);
const label =
mode === "single"
? "Split timeline clip"
: `Split ${requestedCount} clips at ${splitTime.toFixed(2)}s`;
// Server writes arrive through the watcher before React can refresh. Keep
// the existing short self-write window active for this owned transaction.
domEditSaveTimestampRef.current = Date.now();
const result = await runAtomicCutTransaction({
projectId: pid,
intents,
label,
writeProjectFile,
recordEdit,
observeProjectFileVersion,
synchronize,
});
trackStudioRazorSplit({ mode, count: result.splitCount });
if (result.syncFailed) {
showToast(
"Cut was saved, but Studio could not refresh it. Reload the preview to resynchronize.",
"error",
);
}
if (result.skippedSelectors.length > 0) {
showToast(
`Some animations use non-ID selectors (${result.skippedSelectors.join(", ")}) and were not retargeted`,
"info",
);
}
return result;
},
[
activeCompPath,
domEditSaveTimestampRef,
observeProjectFileVersion,
recordEdit,
showToast,
synchronize,
writeProjectFile,
],
);
const handleRazorSplit = useCallback(
// fallow-ignore-next-line complexity
async (element: TimelineElement, splitTime: number) => {
if (isRecordingRef?.current) {
showToast("Cannot edit timeline while recording", "error");
return;
}
const pid = projectIdRef.current;
if (!pid || !canSplitElementAt(element, splitTime)) return;
if (!canSplitElementAt(element, splitTime)) return;
try {
const { targetPath, originalContent, patchedContent, changed, skippedSelectors } =
await executeSplit(
pid,
element,
splitTime,
activeCompPath,
writeProjectFile,
observeProjectFileVersion,
);
if (!changed) {
showToast("Failed to split clip — playhead may be outside the clip", "error");
return;
}
domEditSaveTimestampRef.current = Date.now();
await saveProjectFilesWithHistory({
projectId: pid,
label: "Split timeline clip",
kind: "timeline",
files: { [targetPath]: patchedContent },
readFile: async () => originalContent,
writeFile: writeProjectFile,
recordEdit,
});
// Server writes bypass the SDK session, so reopen it before refreshing
// the preview. The split response already owns the final persisted bytes.
forceReloadSdkSession?.();
reloadPreview();
trackStudioRazorSplit({ mode: "single", count: 1 });
const result = await runCut([element], splitTime, "single");
if (!result) return;
if (result.syncFailed) return;
showToast(`Split ${getTimelineElementLabel(element)} at ${splitTime.toFixed(2)}s`, "info");
if (skippedSelectors?.length) {
showToast(
`Some animations use non-ID selectors (${skippedSelectors.join(", ")}) and were not retargeted`,
"info",
);
}
} catch (error) {
const message = error instanceof Error ? error.message : "Failed to split timeline clip";
showToast(message, "error");
}
},
[
activeCompPath,
recordEdit,
showToast,
writeProjectFile,
observeProjectFileVersion,
domEditSaveTimestampRef,
reloadPreview,
forceReloadSdkSession,
isRecordingRef,
],
[isRecordingRef, runCut, showToast],
);
const handleRazorSplitAll = useCallback(
// fallow-ignore-next-line complexity
async (splitTime: number) => {
if (isRecordingRef?.current) {
showToast("Cannot edit timeline while recording", "error");
return;
}
const pid = projectIdRef.current;
if (!pid) return;
const { elements } = usePlayerStore.getState();
const splittable = selectSplittableElements(elements, splitTime);
const splittable = selectSplittableElements(usePlayerStore.getState().elements, splitTime);
if (splittable.length === 0) return;
let originals = new Map<string, string>();
const finalSnapshots = new Map<string, { before: string; after: string }>();
try {
originals = await readOriginalFiles(pid, splittable, activeCompPath);
const splitCount = await splitElementsAtTime(
pid,
splittable,
splitTime,
activeCompPath,
originals,
finalSnapshots,
writeProjectFile,
observeProjectFileVersion,
);
if (splitCount === 0) return;
domEditSaveTimestampRef.current = Date.now();
await recordEdit({
label: `Split ${splitCount} clips at ${splitTime.toFixed(2)}s`,
kind: "timeline",
files: Object.fromEntries(finalSnapshots),
});
// Resync the stale SDK doc after the batched server write (see the
// single-split path above for why this precedes the reload).
forceReloadSdkSession?.();
reloadPreview();
trackStudioRazorSplit({ mode: "all", count: splitCount });
showToast(`Split ${splitCount} clips at ${splitTime.toFixed(2)}s`, "info");
const result = await runCut(splittable, splitTime, "all");
if (!result) return;
if (result.syncFailed) return;
showToast(`Split ${result.splitCount} clips at ${splitTime.toFixed(2)}s`, "info");
} catch (error) {
// Best-effort rollback — a failing restore write must not swallow the
// original error's toast, which is what tells the user the split failed.
try {
await restoreFilesToOriginal(originals, finalSnapshots, writeProjectFile);
} catch {
/* leave disk as-is; the original failure is reported below */
}
const message = error instanceof Error ? error.message : "Failed to split clips";
showToast(message, "error");
}
},
[
activeCompPath,
recordEdit,
showToast,
writeProjectFile,
observeProjectFileVersion,
domEditSaveTimestampRef,
reloadPreview,
forceReloadSdkSession,
isRecordingRef,
],
[isRecordingRef, runCut, showToast],
);
return { handleRazorSplit, handleRazorSplitAll };