feat(studio): record the layer name on each history entry's target (#7586)

* feat(studio): record the layer name on each history entry's target

* feat(studio): record the clip's name on timeline move and resize entries

* chore(studio): drop doc comments the names already carry
This commit is contained in:
Miguel Ángel
2026-11-12 05:41:31 +00:00
committed by GitHub
parent fc7cb1aad8
commit 4fad43db20
12 changed files with 174 additions and 32 deletions
@@ -23,6 +23,7 @@ export interface HistoryTarget {
hfId?: string;
selector?: string;
selectorIndex?: number;
name?: string;
}
export interface HistoryEntry {
@@ -477,6 +477,29 @@ describe("history routes", () => {
]);
});
it("keeps a target's layer name, trimmed and capped, and never as its only identity", async () => {
const { projectDir, call } = await demoProject();
writeFileSync(join(projectDir, "index.html"), "B");
await call("/claim", {
label: "Move layer",
paths: ["index.html"],
targets: [
{ file: "index.html", id: "title", name: " Title " },
{ file: "index.html", id: "long", name: "x".repeat(500) },
{ file: "index.html", id: "empty", name: " " },
{ file: "index.html", id: "typed", name: 7 },
{ file: "index.html", name: "Nameless but no identity" },
],
});
const { entries } = await (await call("")).json();
expect(entries[0].targets).toEqual([
{ file: "index.html", id: "title", name: "Title" },
{ file: "index.html", id: "long", name: "x".repeat(200) },
{ file: "index.html", id: "empty" },
{ file: "index.html", id: "typed" },
]);
});
it("end a window given idleMs by itself once its writes stop", async () => {
const { projectDir, call } = await demoProject();
@@ -66,6 +66,8 @@ function targetOf(item: unknown): HistoryTarget | null {
if (typeof fields.file !== "string") return null;
const target: HistoryTarget = { file: fields.file, ...identityOf(fields) };
if (!target.id && !target.hfId && !target.selector) return null;
const name = nameOf(fields.name);
if (name) target.name = name;
if (isSelectorIndex(fields.selectorIndex)) target.selectorIndex = fields.selectorIndex;
return target;
}
@@ -81,6 +83,13 @@ function identityOf(
return identity;
}
const MAX_TARGET_NAME = 200;
function nameOf(value: unknown): string | undefined {
if (typeof value !== "string") return undefined;
return value.trim().slice(0, MAX_TARGET_NAME) || undefined;
}
const isSelectorIndex = (value: unknown): value is number =>
typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
@@ -5,6 +5,7 @@ import type { PublishSdkSession } from "../utils/sdkCutover";
import type { StudioEditInFlight } from "../utils/studioPendingEdits";
import type { RuntimeTweenChange } from "./gsapRuntimePatch";
import type { KeyframeUsageAction } from "../utils/keyframeUsage";
import type { RecordEditInput } from "../utils/studioFileHistory";
/** The file a selection's GSAP write goes to. */
export function gsapWriteFile(
@@ -108,12 +109,7 @@ export interface GsapScriptCommitsParams {
activeCompPath: string | null;
previewIframeRef: React.RefObject<HTMLIFrameElement | null>;
editHistory: {
recordEdit: (entry: {
label: string;
coalesceKey?: string;
coalesceMs?: number;
files: Record<string, { before: string; after: string }>;
}) => Promise<void>;
recordEdit: (entry: RecordEditInput) => Promise<void>;
};
reloadPreview: () => void;
onCacheInvalidate: () => void;
@@ -380,6 +380,23 @@ describe("persistTimelineBatchEdit", () => {
expect(perMember).toContain('data-duration="9"');
});
it("files the move under every clip it moved, by identity and by the name the clip wears", async () => {
stubReadFileContent(SOURCE);
const recordEdit = vi.fn(async () => {});
await persistTimelineBatchEdit({
...batchInput([moveMember("a", 3, 0, 0), moveMember("b", 4, 1, 1)], []),
recordEdit,
});
expect(recordEdit).toHaveBeenCalledWith(
expect.objectContaining({
targets: [
{ file: "index.html", id: "a", name: "a" },
{ file: "index.html", id: "b", name: "b" },
],
}),
);
});
it("skips no-op members instead of aborting the batch (track-insert renumber)", async () => {
// A track-insert renumber can include a member whose attributes already
// hold the target values — its patch is string-identical. The batch must
@@ -492,6 +509,28 @@ describe("persistTimelineEdit", () => {
expect([...pending]).toEqual(["index.html"]);
});
it("files the edit under the clip it changed, by identity and by the name the clip wears", async () => {
vi.stubGlobal(
"fetch",
vi.fn(async () => ({ ok: true, json: async () => ({ content: SOURCE }) })),
);
const recordEdit = vi.fn(async () => {});
const element = el({ id: "a", tag: "video", domId: "a", start: 1, duration: 3 });
await persistTimelineEdit({
projectId: "p1",
element,
activeCompPath: "index.html",
label: "Move timeline clip",
buildPatches: (original, target) => buildTimelineMoveTimingPatch(original, target, 2, 3, 0),
writeProjectFile: async () => {},
recordEdit,
pendingTimelineEditPathRef: { current: new Set<string>() },
});
expect(recordEdit).toHaveBeenCalledWith(
expect.objectContaining({ targets: [{ file: "index.html", id: "a", name: "a" }] }),
);
});
it("still throws for a clip the file does not hold", async () => {
const { done, writes } = await runEdit("ghost", 2);
await expect(done).rejects.toThrow("Unable to patch timeline element ghost in index.html");
@@ -23,8 +23,10 @@ import {
} from "../player/lib/timelineElementHelpers";
import { resolveTimelinePlaybackRate } from "../player/components/timelineGroupEditing";
import {
editContextTarget,
saveProjectFilesWithHistory,
writeProjectFilesWithHistoryInQueue,
type EditContextTarget,
type RecordEditInput,
} from "../utils/studioFileHistory";
import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
@@ -140,6 +142,12 @@ export function buildPatchTarget(element: {
return null;
}
export type PatchTarget = NonNullable<ReturnType<typeof buildPatchTarget>>;
/** A clip's entry in the history: how to find the element again, and the name the clip wears on the timeline. */
function timelineEditTarget(path: string, element: TimelineElement): EditContextTarget | null {
const patchTarget = buildPatchTarget(element);
return patchTarget && editContextTarget(path, { ...patchTarget, label: element.label });
}
// The runtime re-reads data-start/data-duration from the DOM on each sync tick
// (packages/core/src/runtime/init.ts:1324-1368), so attribute mutations here are
// picked up automatically on the next frame without a rebind call.
@@ -354,6 +362,7 @@ export async function persistTimelineEdit(input: PersistTimelineEditInput): Prom
await saveProjectFilesWithHistory({
projectId: input.projectId,
label: input.label,
targets: [editContextTarget(targetPath, { ...patchTarget, label: input.element.label })],
coalesceKey: input.coalesceKey,
coalesceMs: input.coalesceMs,
files: {
@@ -457,6 +466,10 @@ export async function persistTimelineBatchEdit(
await saveProjectFilesWithHistory({
projectId: input.projectId,
label: input.label,
targets: input.changes.flatMap((change) => {
const path = change.element.sourceFile || input.activeCompPath || "index.html";
return timelineEditTarget(path, change.element) ?? [];
}),
coalesceKey: input.coalesceKey,
coalesceMs: input.coalesceMs,
files: Object.fromEntries([...changesByPath.keys()].map((path) => [path, buildFile(path)])),
@@ -1,4 +1,5 @@
import { buildProjectApiPath } from "../utils/projectRouting";
import { editContextTarget } from "../utils/studioFileHistory";
import { useCallback } from "react";
import { findUnsafeDomPatchValues } from "@hyperframes/core/studio-api/finite-mutation";
import { FONT_EXT } from "../utils/mediaTypes";
@@ -181,15 +182,9 @@ export function useDomEditCommits({
targets: batches
.filter((batch) => Object.hasOwn(files, batch.sourceFile))
.flatMap((batch) =>
batch.patches.map(({ target }) => ({
file: batch.sourceFile,
...(target.id && { id: target.id }),
...(target.hfId && { hfId: target.hfId }),
...(target.selector && { selector: target.selector }),
...(target.selectorIndex !== undefined && {
selectorIndex: target.selectorIndex,
}),
})),
batch.patches.map(({ target }) =>
editContextTarget(batch.sourceFile, target),
),
),
});
}
+2 -12
View File
@@ -20,7 +20,7 @@ import { countStudioManualEditSave } from "../components/editor/manualEditsDom";
import type { CutoverResult } from "../utils/sdkCutover";
import { reseekPreviewRuntime } from "./timelineTrackVisibility";
import { serializeStudioFileMutations } from "../utils/studioFileMutationCoordinator";
import { readProjectFileContent } from "../utils/studioFileHistory";
import { editContextTarget, readProjectFileContent } from "../utils/studioFileHistory";
import type { RecordEditInput } from "../utils/studioFileHistory";
export type { RecordEditInput } from "../utils/studioFileHistory";
@@ -160,17 +160,7 @@ export function useDomEditPersist({
await editHistory.recordEdit({
...history,
targets: [
{
file: targetPath,
...(selection.id && { id: selection.id }),
...(selection.hfId && { hfId: selection.hfId }),
...(selection.selector && { selector: selection.selector }),
...(selection.selectorIndex !== undefined && {
selectorIndex: selection.selectorIndex,
}),
},
],
targets: [editContextTarget(targetPath, selection)],
files: { [targetPath]: { before: originalContent, after: finalContent } },
});
return { patchData, patchedContent, finalContent };
@@ -898,6 +898,27 @@ describe("runCommit — instantPatch wiring", () => {
expect(deps.reloadPreview).not.toHaveBeenCalled();
});
it("files a gsap move under the layer it moved, by identity and by the name the person saw", async () => {
applySoftReload.mockReturnValue("applied");
mockFetchResult();
const deps = renderCommitHook();
await act(async () => {
await deps.api.commitMutation(
{ ...selection, label: "Title" },
{ x: 10 },
{ label: "Move layer", softReload: true },
);
});
expect(deps.recordEdit).toHaveBeenCalledWith(
expect.objectContaining({
label: "Move layer",
targets: [{ file: "index.html", id: "a", selector: "#a", name: "Title" }],
}),
);
});
it("batch capability posts ordered mutations and finalizes the result once", async () => {
applySoftReload.mockReturnValue("applied");
mockFetchResult();
@@ -1,6 +1,9 @@
import { useCallback, useMemo, useRef } from "react";
import { findUnsafeMutationValues } from "@hyperframes/core/studio-api/finite-mutation";
import { readProjectFileContent as readSharedProjectFileContent } from "../utils/studioFileHistory";
import {
editContextTarget,
readProjectFileContent as readSharedProjectFileContent,
} from "../utils/studioFileHistory";
import type { DomEditSelection } from "../components/editor/domEditingTypes";
import { usePlayerStore } from "../player/store/playerStore";
import {
@@ -323,12 +326,13 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
// the same animationId so their POSTs can't interleave. Held in a ref so the
// chain survives re-renders.
const serializerRef = useRef(createKeyedSerializer());
const recordMutationEdit = useCallback(async (targetPath: string, result: MutationResult, options: CommitMutationOptions) => {
const recordMutationEdit = useCallback(async (targetPath: string, selection: DomEditSelection, result: MutationResult, options: CommitMutationOptions) => {
if (result.before == null || result.after == null) return;
await editHistory.recordEdit({
label: options.label,
coalesceKey: options.coalesceKey,
coalesceMs: options.coalesceMs,
targets: [editContextTarget(targetPath, selection)],
files: { [targetPath]: { before: result.before, after: result.after } },
});
}, [editHistory]);
@@ -348,7 +352,7 @@ export function useGsapScriptCommits({ projectIdRef, activeCompPath, previewIfra
}
return;
}
await recordMutationEdit(targetPath, result, options);
await recordMutationEdit(targetPath, selection, result, options);
const nestedFiles = await settleNestedReads(
result.scriptText
? readNestedFiles(previewIframeRef.current, result.scriptText, (path) =>
@@ -1,5 +1,5 @@
import { describe, expect, it, vi } from "vitest";
import { saveProjectFilesWithHistory } from "./studioFileHistory";
import { editContextTarget, saveProjectFilesWithHistory } from "./studioFileHistory";
import { serializeStudioFileMutation } from "./studioFileMutationCoordinator";
describe("saveProjectFilesWithHistory", () => {
@@ -235,3 +235,31 @@ describe("saveProjectFilesWithHistory", () => {
);
});
});
describe("editContextTarget", () => {
it("names the element by identity and carries the layer name the person saw", () => {
expect(
editContextTarget("index.html", {
id: "title",
hfId: "hf-1",
selector: ".title",
selectorIndex: 0,
label: "Title",
}),
).toEqual({
file: "index.html",
id: "title",
hfId: "hf-1",
selector: ".title",
selectorIndex: 0,
name: "Title",
});
});
it("leaves the name out when the layer has none", () => {
expect(editContextTarget("index.html", { id: "title", label: "" })).toEqual({
file: "index.html",
id: "title",
});
});
});
+24 -1
View File
@@ -4,9 +4,24 @@ import type { MutableRefObject } from "react";
import { serializeStudioFileMutations } from "./studioFileMutationCoordinator";
import { createStudioSaveHttpError } from "./studioSaveDiagnostics";
import { studioApiFetch } from "./studioApiFetch";
import type { PatchTarget } from "./sourcePatcher";
export type EditContextTarget = HistoryTarget;
export function editContextTarget(
file: string,
target: PatchTarget & { label?: string },
): EditContextTarget {
return {
file,
...(target.id && { id: target.id }),
...(target.hfId && { hfId: target.hfId }),
...(target.selector && { selector: target.selector }),
...(target.selectorIndex !== undefined && { selectorIndex: target.selectorIndex }),
...(target.label && { name: target.label }),
};
}
export interface RecordEditInput {
targets?: EditContextTarget[];
label: string;
@@ -31,6 +46,7 @@ type ProjectFileWriter = (path: string, content: string, expectedContent?: strin
interface SaveProjectFilesWithHistoryInput {
projectId: string;
label: string;
targets?: EditContextTarget[];
coalesceKey?: string;
coalesceMs?: number;
files: Record<string, (contentInsideFileQueue: string) => string>;
@@ -107,6 +123,7 @@ export async function saveServerRewriteWithHistory(input: {
export async function writeProjectFilesWithHistoryInQueue({
label,
targets,
coalesceKey,
coalesceMs,
files,
@@ -134,7 +151,13 @@ export async function writeProjectFilesWithHistoryInQueue({
writtenPaths.push(path);
}
await recordEdit({ label, coalesceKey, coalesceMs, files: snapshots });
await recordEdit({
label,
coalesceKey,
coalesceMs,
...(targets?.length && { targets }),
files: snapshots,
});
} catch (error) {
try {
for (const path of writtenPaths.reverse()) {