mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* fix(cli): check no longer calls films moved by SVG masks, strokes or canvas static The frozen-sweep guard compared DOM-channel fingerprints only, which never see SVG mask and clip contents, stroke dashes, or canvas and WebGL pixels. Before reporting sweep_static, check now compares the rendered frames at the same sample times; a still verdict stands only when every frame is identical. * fix(cli): keepsMoving also trusts rendered frames, compared above render noise keepsMoving read the same DOM liveness channels as the sweep guard, so mask, stroke and canvas motion failed it as frozen. A span it calls frozen now gets a frame capture every half maxStaticSec, and spans split where the frames change. Frames are compared in the page, decoded like the contrast pass, and count as moved only when at least 16 pixels change by more than 24/255, so antialiasing and dither noise cannot make a still film pass. * fix(cli): scoped frame checks see only the scope's own paint A keepsMoving scope's capture now hides every box outside the scope's subtree, so a still title over a moving background stays frozen. A span marks only the frames that still hold its signature, so a span that starts at a cut keeps its first frame. A scope that matched nothing stays motion_selector_missing. The sweep counts a frame change only if the first sample time still renders its first frame, so wall-clock paint is not read as motion under seek.
279 lines
9.4 KiB
TypeScript
279 lines
9.4 KiB
TypeScript
import type { LayoutIssue, LayoutRect } from "./layoutAudit.js";
|
||
import type { MotionAssertion } from "./motionSpec.js";
|
||
|
||
/** Opacity at/above which an element counts as "appeared" (RFC: opacity ≥ threshold). */
|
||
const APPEAR_OPACITY = 0.5;
|
||
/** Pixels an element may exceed the canvas edge before it counts as off-frame. */
|
||
const FRAME_TOLERANCE = 1;
|
||
/** Default longest allowed fully-static window for keepsMoving, in seconds. */
|
||
export const DEFAULT_MAX_STATIC_SEC = 2;
|
||
|
||
export interface FrameSample {
|
||
rect: LayoutRect;
|
||
opacity: number;
|
||
visible: boolean;
|
||
}
|
||
|
||
/** One seeked frame of the dense motion grid. */
|
||
export interface MotionFrame {
|
||
time: number;
|
||
/** Per asserted selector: its sample this frame, or null when it matched nothing. */
|
||
data: Record<string, FrameSample | null>;
|
||
/** Liveness signature per scope ("*" = whole canvas; otherwise a withinSelector). */
|
||
liveness: Record<string, string>;
|
||
}
|
||
|
||
export interface Canvas {
|
||
width: number;
|
||
height: number;
|
||
}
|
||
|
||
const ZERO_RECT: LayoutRect = { left: 0, top: 0, right: 0, bottom: 0, width: 0, height: 0 };
|
||
|
||
export function ambiguousIssue(selector: string): LayoutIssue {
|
||
return {
|
||
code: "motion_selector_ambiguous",
|
||
severity: "error",
|
||
time: 0,
|
||
selector,
|
||
message: `${selector} matches multiple elements — use a more specific selector so the assertion targets exactly one.`,
|
||
rect: ZERO_RECT,
|
||
fixHint:
|
||
"Use #id or :nth-child() instead of a class selector when multiple elements share the same class.",
|
||
};
|
||
}
|
||
|
||
function round(value: number): number {
|
||
return Math.round(value * 100) / 100;
|
||
}
|
||
|
||
function everMatched(frames: MotionFrame[], selector: string): boolean {
|
||
return frames.some((frame) => frame.data[selector] != null);
|
||
}
|
||
|
||
/** First frame where the selector is visible at/above the appear threshold. */
|
||
function firstAppear(
|
||
frames: MotionFrame[],
|
||
selector: string,
|
||
): { time: number; rect: LayoutRect } | null {
|
||
for (const frame of frames) {
|
||
const sample = frame.data[selector];
|
||
if (sample && sample.visible && sample.opacity >= APPEAR_OPACITY) {
|
||
return { time: frame.time, rect: sample.rect };
|
||
}
|
||
}
|
||
return null;
|
||
}
|
||
|
||
function missingIssue(selector: string, time: number): LayoutIssue {
|
||
return {
|
||
code: "motion_selector_missing",
|
||
severity: "error",
|
||
time,
|
||
selector,
|
||
message: `${selector} matched no element in any sampled frame — check the selector`,
|
||
rect: ZERO_RECT,
|
||
fixHint: "Verify the selector exists in the composition and is spelled correctly.",
|
||
};
|
||
}
|
||
|
||
function appearsBy(frames: MotionFrame[], selector: string, bySec: number): LayoutIssue[] {
|
||
if (!everMatched(frames, selector)) return [missingIssue(selector, 0)];
|
||
const appear = firstAppear(frames, selector);
|
||
if (appear && appear.time <= bySec) return [];
|
||
return [
|
||
{
|
||
code: "motion_appears_late",
|
||
severity: "error",
|
||
time: appear ? appear.time : bySec,
|
||
selector,
|
||
message: appear
|
||
? `appears at ${round(appear.time)}s but should be visible by ${round(bySec)}s (check its entrance reveal fires under seek)`
|
||
: `never reaches visible opacity but should be visible by ${round(bySec)}s (check its entrance reveal fires under seek)`,
|
||
rect: appear ? appear.rect : ZERO_RECT,
|
||
fixHint:
|
||
"The renderer seeks a paused timeline; a forward-only reveal can be skipped. Ensure the entrance is applied at this time, not only played through.",
|
||
},
|
||
];
|
||
}
|
||
|
||
function before(frames: MotionFrame[], a: string, b: string): LayoutIssue[] {
|
||
const issues: LayoutIssue[] = [];
|
||
if (!everMatched(frames, a)) issues.push(missingIssue(a, 0));
|
||
if (!everMatched(frames, b)) issues.push(missingIssue(b, 0));
|
||
if (issues.length > 0) return issues;
|
||
|
||
const appearA = firstAppear(frames, a);
|
||
const appearB = firstAppear(frames, b);
|
||
const timeA = appearA ? appearA.time : Number.POSITIVE_INFINITY;
|
||
const timeB = appearB ? appearB.time : Number.POSITIVE_INFINITY;
|
||
if (timeA < timeB) return [];
|
||
|
||
const label = (t: number) => (Number.isFinite(t) ? `${round(t)}s` : "never");
|
||
return [
|
||
{
|
||
code: "motion_out_of_order",
|
||
severity: "error",
|
||
time: Number.isFinite(timeA) ? timeA : 0,
|
||
selector: a,
|
||
message: `${a} should appear before ${b}, but ${a} appears at ${label(timeA)} and ${b} at ${label(timeB)} — reorder the entrances`,
|
||
rect: appearA ? appearA.rect : ZERO_RECT,
|
||
fixHint: `Make ${a}'s entrance land before ${b}'s on the timeline.`,
|
||
},
|
||
];
|
||
}
|
||
|
||
function isOffFrame(r: LayoutRect, canvas: Canvas): boolean {
|
||
return (
|
||
r.left < -FRAME_TOLERANCE ||
|
||
r.top < -FRAME_TOLERANCE ||
|
||
r.right > canvas.width + FRAME_TOLERANCE ||
|
||
r.bottom > canvas.height + FRAME_TOLERANCE
|
||
);
|
||
}
|
||
|
||
// Note: off-frame check uses sample.visible (opacity ≥ 0.2 from the browser sampler);
|
||
// the first-appear anchor uses APPEAR_OPACITY (0.5). Elements fading in between those
|
||
// thresholds are tracked for position but don't start the window — intentional.
|
||
function staysInFrame(frames: MotionFrame[], selector: string, canvas: Canvas): LayoutIssue[] {
|
||
if (!everMatched(frames, selector)) return [missingIssue(selector, 0)];
|
||
const appear = firstAppear(frames, selector);
|
||
if (!appear) return [];
|
||
|
||
for (const frame of frames) {
|
||
const sample = frame.data[selector];
|
||
if (frame.time < appear.time || !sample || !sample.visible) continue;
|
||
if (!isOffFrame(sample.rect, canvas)) continue;
|
||
const r = sample.rect;
|
||
return [
|
||
{
|
||
code: "motion_off_frame",
|
||
severity: "error",
|
||
time: frame.time,
|
||
selector,
|
||
message: `${selector} drifts off the ${canvas.width}×${canvas.height} canvas at ${round(frame.time)}s (box ${r.left},${r.top}→${r.right},${r.bottom})`,
|
||
rect: r,
|
||
fixHint:
|
||
"Clamp the element's motion so its box stays within the canvas for the whole shot.",
|
||
},
|
||
];
|
||
}
|
||
return [];
|
||
}
|
||
|
||
export function frozenSpans(
|
||
frames: MotionFrame[],
|
||
scope: string,
|
||
maxStaticSec: number,
|
||
): { start: number; end: number }[] {
|
||
const spans: { start: number; end: number }[] = [];
|
||
const first = frames[0];
|
||
if (!first) return spans;
|
||
let runStart = first.time;
|
||
let runSig = first.liveness[scope] ?? "";
|
||
const flush = (end: number) => {
|
||
if (end - runStart > maxStaticSec) spans.push({ start: runStart, end });
|
||
};
|
||
|
||
let lastTime = runStart;
|
||
for (const frame of frames.slice(1)) {
|
||
lastTime = frame.time;
|
||
const sig = frame.liveness[scope] ?? "";
|
||
if (sig !== runSig) {
|
||
flush(frame.time);
|
||
runStart = frame.time;
|
||
runSig = sig;
|
||
}
|
||
}
|
||
flush(lastTime);
|
||
return spans;
|
||
}
|
||
|
||
function keepsMoving(
|
||
frames: MotionFrame[],
|
||
within: string | undefined,
|
||
maxStaticSec: number,
|
||
): LayoutIssue[] {
|
||
// "*" is reserved for whole-canvas scope; motionSpec.ts rejects it as a user-supplied withinSelector.
|
||
const scope = within ?? "*";
|
||
if (within && frames.every((frame) => !frame.liveness[scope])) {
|
||
return [missingIssue(within, 0)];
|
||
}
|
||
return frozenSpans(frames, scope, maxStaticSec).map(({ start, end }) => ({
|
||
code: "motion_frozen",
|
||
severity: "error",
|
||
time: start,
|
||
selector: within ?? "composition",
|
||
message: `nothing moves${within ? ` within ${within}` : ""} between ${round(start)}s and ${round(end)}s (${round(end - start)}s static) — should keep moving`,
|
||
rect: ZERO_RECT,
|
||
fixHint: "Add or extend motion so no shot freezes for this long, or shorten the static hold.",
|
||
}));
|
||
}
|
||
|
||
/**
|
||
* Evaluate motion assertions against the dense `element × time` matrix.
|
||
* Pure — no browser. Findings reuse the LayoutIssue shape and flow through
|
||
* inspect's existing dedupe/collapse/limit/format pipeline.
|
||
*/
|
||
export function evaluateMotion(
|
||
frames: MotionFrame[],
|
||
assertions: MotionAssertion[],
|
||
canvas: Canvas,
|
||
): LayoutIssue[] {
|
||
if (frames.length === 0) return [];
|
||
return assertions.flatMap((assertion) => {
|
||
switch (assertion.kind) {
|
||
case "appearsBy":
|
||
return appearsBy(frames, assertion.selector, assertion.bySec);
|
||
case "before":
|
||
return before(frames, assertion.a, assertion.b);
|
||
case "staysInFrame":
|
||
return staysInFrame(frames, assertion.selector, canvas);
|
||
case "keepsMoving":
|
||
return keepsMoving(
|
||
frames,
|
||
assertion.withinSelector,
|
||
assertion.maxStaticSec ?? DEFAULT_MAX_STATIC_SEC,
|
||
);
|
||
}
|
||
});
|
||
}
|
||
|
||
export function assertionTargets(assertion: MotionAssertion): {
|
||
selectors: string[];
|
||
scopes: string[];
|
||
} {
|
||
switch (assertion.kind) {
|
||
case "appearsBy":
|
||
case "staysInFrame":
|
||
return { selectors: [assertion.selector], scopes: [] };
|
||
case "before":
|
||
return { selectors: [assertion.a, assertion.b], scopes: [] };
|
||
case "keepsMoving":
|
||
return { selectors: [], scopes: [assertion.withinSelector ?? "*"] };
|
||
default: {
|
||
const exhaustive: never = assertion;
|
||
void exhaustive;
|
||
return { selectors: [], scopes: [] };
|
||
}
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Selectors and liveness scopes the in-page sampler must read for a spec.
|
||
* Selectors feed the per-element matrix; scopes feed keepsMoving liveness.
|
||
*/
|
||
export function collectSamplingTargets(assertions: MotionAssertion[]): {
|
||
selectors: string[];
|
||
livenessScopes: string[];
|
||
} {
|
||
const selectors = new Set<string>();
|
||
const scopes = new Set<string>();
|
||
for (const assertion of assertions) {
|
||
const targets = assertionTargets(assertion);
|
||
for (const selector of targets.selectors) selectors.add(selector);
|
||
for (const scope of targets.scopes) scopes.add(scope);
|
||
}
|
||
return { selectors: [...selectors], livenessScopes: [...scopes] };
|
||
}
|