Skip to content

Commit 65b2299

Browse files
fix(engine): preserve static dedup across caption runs (#3438)
* fix(engine): preserve authored clip boundaries after normalization * perf(engine): bound static verification work across caption runs * fix(core): preserve explicit nonpositive timeline windows
1 parent dd0626a commit 65b2299

15 files changed

Lines changed: 901 additions & 261 deletions

‎packages/core/src/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,13 @@ export type {
5151

5252
export { parseSlideshowManifest, resolveSlideshow } from "./slideshow/index.js";
5353

54+
export type {
55+
AuthoredTimingValue,
56+
RawAuthoredTiming,
57+
AuthoredTimingWindow,
58+
} from "./runtime/authoredTiming.js";
59+
export { resolveAuthoredTimingWindow } from "./runtime/authoredTiming.js";
60+
5461
export {
5562
CANVAS_DIMENSIONS,
5663
VALID_CANVAS_RESOLUTIONS,
Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
import { describe, expect, it } from "vitest";
2+
3+
const timingModule = await import("./authoredTiming.js").catch(() => null);
4+
5+
describe("resolveAuthoredTimingWindow", () => {
6+
const resolve = (values: {
7+
start?: string | null;
8+
duration?: string | null;
9+
authoredDuration?: string | null;
10+
end?: string | null;
11+
authoredEnd?: string | null;
12+
}) => {
13+
expect(timingModule, "canonical authored timing helper must exist").not.toBeNull();
14+
return timingModule?.resolveAuthoredTimingWindow(values) ?? null;
15+
};
16+
17+
it("uses public timing before preserved timing and duration before end", () => {
18+
expect(
19+
resolve({
20+
start: "2",
21+
duration: "3",
22+
authoredDuration: "4",
23+
end: "20",
24+
authoredEnd: "30",
25+
}),
26+
).toEqual({ start: 2, duration: 3, end: 5 });
27+
});
28+
29+
it("falls back through preserved duration, public end, and preserved end", () => {
30+
expect(resolve({ start: "1", duration: "", authoredDuration: "2.5" })).toEqual({
31+
start: 1,
32+
duration: 2.5,
33+
end: 3.5,
34+
});
35+
expect(resolve({ start: "1", duration: "0", end: "4", authoredEnd: "8" })).toEqual({
36+
start: 1,
37+
duration: 3,
38+
end: 4,
39+
});
40+
expect(resolve({ start: "1", duration: "-1", end: "NaN", authoredEnd: "6" })).toEqual({
41+
start: 1,
42+
duration: 5,
43+
end: 6,
44+
});
45+
});
46+
47+
it("rejects unusable values and preserves a usable start-only window", () => {
48+
expect(resolve({ start: null, duration: "2" })).toBeNull();
49+
expect(resolve({ start: "Infinity", duration: "2" })).toBeNull();
50+
expect(resolve({ start: "1.25", duration: "NaN", end: "1.25" })).toEqual({
51+
start: 1.25,
52+
duration: null,
53+
end: null,
54+
});
55+
});
56+
57+
it.each([
58+
["blank public duration", { start: "0", duration: " ", authoredDuration: "2" }, 2],
59+
["invalid public duration", { start: "0", duration: "NaN", authoredDuration: "2" }, 2],
60+
["infinite public duration", { start: "0", duration: "Infinity", authoredDuration: "2" }, 2],
61+
["zero public duration", { start: "0", duration: "0", authoredDuration: "2" }, 2],
62+
["negative public duration", { start: "0", duration: "-2", authoredDuration: "2" }, 2],
63+
])("uses a usable preserved duration after %s", (_label, values, expectedEnd) => {
64+
expect(resolve(values)).toEqual({ start: 0, duration: 2, end: expectedEnd });
65+
});
66+
67+
it("uses preserved end when public end does not create a positive window", () => {
68+
expect(resolve({ start: "4", end: "3", authoredEnd: "5.5" })).toEqual({
69+
start: 4,
70+
duration: 1.5,
71+
end: 5.5,
72+
});
73+
});
74+
75+
it("clamps a finite negative absolute start before deriving the window", () => {
76+
expect(resolve({ start: "-1", duration: "3" })).toEqual({
77+
start: 0,
78+
duration: 3,
79+
end: 3,
80+
});
81+
});
82+
});
Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
export type AuthoredTimingValue = string | number | null | undefined;
2+
3+
export interface RawAuthoredTiming {
4+
start?: AuthoredTimingValue;
5+
duration?: AuthoredTimingValue;
6+
authoredDuration?: AuthoredTimingValue;
7+
end?: AuthoredTimingValue;
8+
authoredEnd?: AuthoredTimingValue;
9+
}
10+
11+
export interface AuthoredTimingWindow {
12+
start: number;
13+
duration: number | null;
14+
end: number | null;
15+
}
16+
17+
function finiteNumber(value: AuthoredTimingValue): number | null {
18+
if (value == null) return null;
19+
if (typeof value === "string" && value.trim() === "") return null;
20+
const parsed = typeof value === "number" ? value : Number(value);
21+
return Number.isFinite(parsed) ? parsed : null;
22+
}
23+
24+
export function resolveAuthoredTimingWindow(
25+
values: RawAuthoredTiming,
26+
): AuthoredTimingWindow | null {
27+
const parsedStart = finiteNumber(values.start);
28+
if (parsedStart == null) return null;
29+
const start = Math.max(0, parsedStart);
30+
31+
const publicDuration = finiteNumber(values.duration);
32+
const preservedDuration = finiteNumber(values.authoredDuration);
33+
const duration =
34+
publicDuration != null && publicDuration > 0
35+
? publicDuration
36+
: preservedDuration != null && preservedDuration > 0
37+
? preservedDuration
38+
: null;
39+
if (duration != null) return { start, duration, end: start + duration };
40+
41+
const publicEnd = finiteNumber(values.end);
42+
const preservedEnd = finiteNumber(values.authoredEnd);
43+
const end =
44+
publicEnd != null && publicEnd > start
45+
? publicEnd
46+
: preservedEnd != null && preservedEnd > start
47+
? preservedEnd
48+
: null;
49+
return { start, duration: end == null ? null : end - start, end };
50+
}

‎packages/core/src/runtime/startResolver.ts‎

Lines changed: 21 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,9 @@
11
import type { RuntimeTimelineLike } from "./types";
22
import { swallow } from "./diagnostics";
3+
import { resolveAuthoredTimingWindow } from "./authoredTiming";
34
import { readElementPlaybackRate } from "./media";
45
import { readMediaStart } from "./playbackRate";
5-
import { parseNumeric, parseStartExpression } from "./startExpression";
6-
7-
const AUTHORED_DURATION_ATTR = "data-hf-authored-duration";
8-
const AUTHORED_END_ATTR = "data-hf-authored-end";
9-
10-
function parseDurationAttr(element: Element): number | null {
11-
return parseNumeric(element.getAttribute("data-duration"));
12-
}
13-
14-
function parseEndAttr(element: Element): number | null {
15-
return parseNumeric(element.getAttribute("data-end"));
16-
}
17-
18-
function parseAuthoredDurationAttr(element: Element): number | null {
19-
return parseNumeric(element.getAttribute(AUTHORED_DURATION_ATTR));
20-
}
21-
22-
function parseAuthoredEndAttr(element: Element): number | null {
23-
return parseNumeric(element.getAttribute(AUTHORED_END_ATTR));
24-
}
6+
import { parseStartExpression } from "./startExpression";
257

268
export function createRuntimeStartTimeResolver(params: {
279
timelineRegistry?: Record<string, RuntimeTimelineLike | undefined>;
@@ -64,22 +46,27 @@ export function createRuntimeStartTimeResolver(params: {
6446
const cached = durationCache.get(element);
6547
if (cached !== undefined) return cached;
6648
let resolved: number | null = null;
67-
const durationAttr =
68-
parseDurationAttr(element) ??
69-
(includeAuthoredTimingAttrs ? parseAuthoredDurationAttr(element) : null);
70-
if (durationAttr != null && durationAttr > 0) {
71-
resolved = durationAttr;
49+
const durationTiming = resolveAuthoredTimingWindow({
50+
start: 0,
51+
duration: element.getAttribute("data-duration"),
52+
authoredDuration: includeAuthoredTimingAttrs
53+
? element.getAttribute("data-hf-authored-duration")
54+
: null,
55+
});
56+
if (durationTiming?.duration != null && durationTiming.duration > 0) {
57+
resolved = durationTiming.duration;
7258
}
7359
if (resolved == null || resolved <= 0) {
74-
const endAttr =
75-
parseEndAttr(element) ??
76-
(includeAuthoredTimingAttrs ? parseAuthoredEndAttr(element) : null);
77-
if (endAttr != null) {
78-
const start = resolveStartForElementInternal(element, 0);
79-
const delta = endAttr - start;
80-
if (Number.isFinite(delta) && delta > 0) {
81-
resolved = delta;
82-
}
60+
const start = resolveStartForElementInternal(element, 0);
61+
const endTiming = resolveAuthoredTimingWindow({
62+
start,
63+
end: element.getAttribute("data-end"),
64+
authoredEnd: includeAuthoredTimingAttrs
65+
? element.getAttribute("data-hf-authored-end")
66+
: null,
67+
});
68+
if (endTiming?.duration != null && endTiming.duration > 0) {
69+
resolved = endTiming.duration;
8370
}
8471
}
8572
if ((resolved == null || resolved <= 0) && isMediaElement(element)) {

‎packages/core/src/runtime/timeline.test.ts‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,39 @@
11
import { describe, it, expect, afterEach } from "vitest";
22
import { collectRuntimeTimelinePayload } from "./timeline";
33

4+
type TimelineTestWindow = Window & {
5+
__timelines?: Record<string, { duration: () => number }>;
6+
};
7+
48
describe("collectRuntimeTimelinePayload", () => {
59
afterEach(() => {
610
document.body.innerHTML = "";
7-
delete (window as any).__timelines;
11+
delete (window as TimelineTestWindow).__timelines;
812
});
913

1014
const defaultParams = { canonicalFps: 30 };
1115

16+
function appendTimedCompositionClip(
17+
id: string,
18+
duration: string,
19+
authoredDuration?: string,
20+
): HTMLDivElement {
21+
const root = document.createElement("div");
22+
root.setAttribute("data-composition-id", "main");
23+
root.setAttribute("data-duration", "10");
24+
document.body.appendChild(root);
25+
const clip = document.createElement("div");
26+
clip.id = id;
27+
clip.setAttribute("data-composition-id", id);
28+
clip.setAttribute("data-start", "0");
29+
clip.setAttribute("data-duration", duration);
30+
if (authoredDuration != null) {
31+
clip.setAttribute("data-hf-authored-duration", authoredDuration);
32+
}
33+
root.appendChild(clip);
34+
return clip;
35+
}
36+
1237
it("returns minimal payload for empty document", () => {
1338
const result = collectRuntimeTimelinePayload(defaultParams);
1439
expect(result.source).toBe("hf-preview");
@@ -664,6 +689,26 @@ describe("collectRuntimeTimelinePayload", () => {
664689
expect(result.durationInFrames).toBe(42 * 30);
665690
});
666691

692+
it("uses preserved duration when a normalized timeline clip retains public zero", () => {
693+
const clip = appendTimedCompositionClip("normalized-zero", "0", "3.5");
694+
695+
const result = collectRuntimeTimelinePayload(defaultParams);
696+
expect(result.clips.find((candidate) => candidate.id === clip.id)?.duration).toBe(3.5);
697+
});
698+
699+
it.each(["0", "-2"])(
700+
"drops an explicit nonpositive duration %s before timeline fallback",
701+
(duration) => {
702+
const clip = appendTimedCompositionClip("invalid-window", duration);
703+
(window as TimelineTestWindow).__timelines = {
704+
"invalid-window": { duration: () => 5 },
705+
};
706+
707+
const result = collectRuntimeTimelinePayload(defaultParams);
708+
expect(result.clips.find((candidate) => candidate.id === clip.id)).toBeUndefined();
709+
},
710+
);
711+
667712
it("discovers GSAP-animated scene elements via timeline introspection", () => {
668713
const root = document.createElement("div");
669714
root.setAttribute("data-composition-id", "main");

‎packages/core/src/runtime/timeline.ts‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import type {
55
RuntimeTimelineLike,
66
} from "./types";
77
import { stableClipId } from "./clipTree";
8+
import { resolveAuthoredTimingWindow } from "./authoredTiming";
89
import { swallow } from "./diagnostics";
910
import { readElementPlaybackRate, readElementPlaybackStart } from "./media";
1011
import { parseStrictFiniteTimingNumber, resolveNaturalMediaTimelineDuration } from "./playbackRate";
@@ -14,23 +15,32 @@ import { isSceneLikeCompositionId } from "../slideshow/index.js";
1415
import { COMPOSITION_CONTRACT_VERSION } from "../compositionContract.js";
1516
import { runtimeProtocolMetadata } from "./protocol.js";
1617

17-
const AUTHORED_DURATION_ATTR = "data-hf-authored-duration";
18-
const AUTHORED_END_ATTR = "data-hf-authored-end";
19-
2018
function parseNum(value: string | null | undefined): number | null {
2119
return parseStrictFiniteTimingNumber(value);
2220
}
2321

2422
function parseElementDurationAttr(element: Element): number | null {
25-
return (
26-
parseNum(element.getAttribute("data-duration")) ??
27-
parseNum(element.getAttribute(AUTHORED_DURATION_ATTR))
28-
);
23+
const publicDuration = element.getAttribute("data-duration");
24+
const authoredDuration = element.getAttribute("data-hf-authored-duration");
25+
const resolved = resolveAuthoredTimingWindow({
26+
start: 0,
27+
duration: publicDuration,
28+
authoredDuration,
29+
})?.duration;
30+
if (resolved != null) return resolved;
31+
const hasExplicitNonpositive = [publicDuration, authoredDuration]
32+
.map(parseNum)
33+
.some((duration) => duration != null && duration <= 0);
34+
return hasExplicitNonpositive ? 0 : null;
2935
}
3036

3137
function parseElementEndAttr(element: Element): number | null {
3238
return (
33-
parseNum(element.getAttribute("data-end")) ?? parseNum(element.getAttribute(AUTHORED_END_ATTR))
39+
resolveAuthoredTimingWindow({
40+
start: 0,
41+
end: element.getAttribute("data-end"),
42+
authoredEnd: element.getAttribute("data-hf-authored-end"),
43+
})?.end ?? null
3444
);
3545
}
3646

‎packages/engine/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,7 @@ export {
127127
isMemoryExhaustionError,
128128
type BeforeCaptureHook,
129129
type DiscardWarmupInnerCapture,
130+
type StaticVerificationOutcome,
130131
} from "./services/frameCapture.js";
131132
export {
132133
CaptureFailure,
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { describe, expect, it } from "vitest";
2+
import { computeAuthoredClipBoundaryFrames } from "./frameCapture.js";
3+
4+
describe("computeClipBoundaryFrames", () => {
5+
it("protects the normalized authored-duration disappearance neighborhood", async () => {
6+
const frames = computeAuthoredClipBoundaryFrames(
7+
[
8+
{
9+
start: "0",
10+
duration: null,
11+
authoredDuration: "3.5",
12+
end: null,
13+
authoredEnd: null,
14+
},
15+
],
16+
25,
17+
);
18+
19+
expect([...frames].sort((a, b) => a - b)).toEqual([0, 1, 87, 88, 89]);
20+
});
21+
22+
it("rounds fractional-fps start and end edges and applies precedence", async () => {
23+
const frames = computeAuthoredClipBoundaryFrames(
24+
[
25+
{
26+
start: "0.1",
27+
duration: "0",
28+
authoredDuration: "0.2",
29+
end: "9",
30+
authoredEnd: "10",
31+
},
32+
],
33+
23.976,
34+
);
35+
36+
expect(frames).toEqual(new Set([1, 2, 3, 6, 7, 8]));
37+
});
38+
39+
it("matches runtime clamping for a negative absolute start", () => {
40+
const frames = computeAuthoredClipBoundaryFrames([{ start: "-1", duration: "3" }], 25);
41+
expect(frames).toEqual(new Set([0, 1, 74, 75, 76]));
42+
});
43+
});

0 commit comments

Comments
 (0)