From 7050b9b5bbcca4552a5a76661bb782990508983d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Thu, 5 Nov 2026 07:05:25 +0000 Subject: [PATCH] fix(studio-server): a refused cut says which way it was refused (#7212) --- .../src/helpers/sourceMutation.ts | 25 ++++++++++++--- .../sourceMutationSplitAndGroup.test.ts | 10 ++++-- .../studio-server/src/routes/files.test.ts | 32 +++++++++++++++++++ packages/studio-server/src/routes/files.ts | 11 ++++++- 4 files changed, 70 insertions(+), 8 deletions(-) diff --git a/packages/studio-server/src/helpers/sourceMutation.ts b/packages/studio-server/src/helpers/sourceMutation.ts index 9d5413d689..75dce106af 100644 --- a/packages/studio-server/src/helpers/sourceMutation.ts +++ b/packages/studio-server/src/helpers/sourceMutation.ts @@ -417,12 +417,27 @@ export function probeElementInSource(source: string, target: SourceMutationTarge return probeElementsInSource(source, [target])[0] ?? false; } +/** Why a split changed nothing: the cut route says it, so a report names the cause and not just "rejected". */ +export type SplitRefusal = + | "target-not-found" + | "reference-without-range" + | "no-duration" + | "outside-clip"; + export interface SplitElementResult { html: string; matched: boolean; newId: string | null; + refusal?: SplitRefusal; } +const refused = (html: string, refusal: SplitRefusal): SplitElementResult => ({ + html, + matched: false, + newId: null, + refusal, +}); + function resolveElementTiming(el: Element): { start: number; duration: number; @@ -476,7 +491,7 @@ export function splitElementInHtml( ): SplitElementResult { const { document, wrappedFragment } = parseSourceDocument(source); const el = findTargetElement(document, target); - if (!el || !isHTMLElement(el)) return { html: source, matched: false, newId: null }; + if (!el || !isHTMLElement(el)) return refused(source, "target-not-found"); // An untimed wrapper whose row is its timed media's own window is a view of that // media: cut the media and leave the wrappers untimed. A GSAP scene keeps its own window. @@ -498,7 +513,7 @@ export function splitElementInHtml( const reference = readClipTiming(timed).startExpression; const startsAfter = reference?.kind === "reference" ? reference : null; if (startsAfter) { - if (!fallbackTiming) return { html: source, matched: false, newId: null }; + if (!fallbackTiming) return refused(source, "reference-without-range"); start = fallbackTiming.start; } // GSAP-animated elements carry their timing in the script, not in data-* attrs, @@ -509,12 +524,12 @@ export function splitElementInHtml( start = fallbackTiming.start; duration = fallbackTiming.duration; } + if (duration <= 0) return refused(source, "no-duration"); if ( - duration <= 0 || splitTime < start + SPLIT_BOUNDARY_EPSILON_S || splitTime > start + duration - SPLIT_BOUNDARY_EPSILON_S ) { - return { html: source, matched: false, newId: null }; + return refused(source, "outside-clip"); } newId = nextUniqueId(document, newId); @@ -523,7 +538,7 @@ export function splitElementInHtml( const secondDuration = duration - firstDuration; const clone = el.cloneNode(true); - if (!isHTMLElement(clone)) return { html: source, matched: false, newId: null }; + if (!isHTMLElement(clone)) return refused(source, "target-not-found"); clone.setAttribute("id", newId); dedupeClonedCompositionId(document, clone); clone.removeAttribute("data-hf-id"); diff --git a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts index 282f6a2371..e029c59102 100644 --- a/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts +++ b/packages/studio-server/src/helpers/sourceMutationSplitAndGroup.test.ts @@ -600,7 +600,12 @@ describe("splitElementInHtml — a start that names another clip", () => { it("leaves the file as it was for a cut before the clip's real start, instead of rewriting it to start at 0", () => { const source = after("b"); const result = splitElementInHtml(source, { id: "a" }, 2, "a-split", { start: 3, duration: 4 }); - expect(result).toEqual({ html: source, matched: false, newId: null }); + expect(result).toEqual({ + html: source, + matched: false, + newId: null, + refusal: "outside-clip", + }); }); it("refuses when it cannot know where the clip plays", () => { @@ -609,13 +614,14 @@ describe("splitElementInHtml — a start that names another clip", () => { html: source, matched: false, newId: null, + refusal: "reference-without-range", }); }); }); describe("splitElementInHtml — a cut the file's own timing does not allow", () => { const clip = `
`; - const untouched = { html: clip, matched: false, newId: null }; + const untouched = { html: clip, matched: false, newId: null, refusal: "outside-clip" }; it.each([ ["exactly at the clip's start", 2, { start: 2, duration: 4 }], diff --git a/packages/studio-server/src/routes/files.test.ts b/packages/studio-server/src/routes/files.test.ts index dc01f1ba5b..2a1d7b1bb7 100644 --- a/packages/studio-server/src/routes/files.test.ts +++ b/packages/studio-server/src/routes/files.test.ts @@ -1370,6 +1370,38 @@ describe("registerFileRoutes", () => { expect(readFileSync(join(projectDir, "b.html"), "utf-8")).toBe(beforeB); }); + it.each([ + ["a missing clip", { id: "ghost" }, 2, 4, "Cut target was not found in index.html"], + [ + "a cut past the clip's end", + { id: "a" }, + 9, + 4, + "Cut point was outside the clip's start and end in index.html", + ], + ])( + "says which way a cut was refused: %s", + async (_name, target, splitTime, elementDuration, said) => { + const projectDir = createProjectDir(); + const before = '
A
B
'; + writeFileSync(join(projectDir, "index.html"), before); + const app = new Hono(); + registerFileRoutes(app, createAdapter(projectDir)); + + const response = await postCutBatch(app, [ + { + path: "index.html", + expectedVersion: fileContentVersion(before), + targets: [{ target, originalId: target.id, splitTime, elementStart: 0, elementDuration }], + }, + ]); + + expect(response.status).toBe(400); + expect(((await response.json()) as { error: string }).error).toBe(said); + expect(readFileSync(join(projectDir, "index.html"), "utf-8")).toBe(before); + }, + ); + it("serializes rapid cuts so a stale successor cannot fragment the first result", async () => { const projectDir = createProjectDir(); const before = '
Clip
'; diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts index 1703e53283..30904162d2 100644 --- a/packages/studio-server/src/routes/files.ts +++ b/packages/studio-server/src/routes/files.ts @@ -104,6 +104,7 @@ import { isHTMLElement, type PatchOperation, type ElementRebase, + type SplitRefusal, } from "../helpers/sourceMutation.js"; import { ensureStudioFontFaceCss, isStudioFontFaceCss } from "../helpers/studioFontFace.js"; import { parseHTML } from "linkedom"; @@ -2564,6 +2565,14 @@ interface FoldedAtomicCutFile { } /** Fold every split and optional GSAP retarget for one file without touching disk. */ +const CUT_REFUSALS: Record = { + "target-not-found": "Cut target was not found", + "reference-without-range": + "Cut target starts after another clip and the cut sent no range for it", + "no-duration": "Cut target has no duration", + "outside-clip": "Cut point was outside the clip's start and end", +}; + async function foldAtomicCutFile( c: RouteContext, file: AtomicCutFileRequest, @@ -2609,7 +2618,7 @@ async function foldAtomicCutFile( }); if (!split.matched || !split.newId) { return c.json( - { error: `Cut target was not found or was outside its authored bounds in ${file.path}` }, + { error: `${CUT_REFUSALS[split.refusal ?? "target-not-found"]} in ${file.path}` }, 400, ); }