fix(studio-server): a refused cut says which way it was refused (#7212)

This commit is contained in:
Miguel Ángel
2026-11-05 07:05:25 +00:00
committed by GitHub
parent d810bdbb27
commit 7050b9b5bb
4 changed files with 70 additions and 8 deletions
@@ -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");
@@ -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 = `<html><body><div data-composition-id="root"><div id="a" class="clip" data-start="2" data-duration="4"></div></div></body></html>`;
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 }],
@@ -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 = '<div id="a" data-start="0" data-duration="4">A</div><div id="bare">B</div>';
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 = '<div id="clip" data-start="0" data-duration="4">Clip</div>';
+10 -1
View File
@@ -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<SplitRefusal, string> = {
"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,
);
}