Skip to content

Commit 2a0fa7f

Browse files
fix(cli): check fails a full-frame element that covers every other clip, naming it (#6572)
* fix(cli): check fails a full-frame element that covers every other clip, naming it * test(cli): shorten the cover scene helper's comment * chore(skills): refresh the manifest for the check reference * fix(cli): full-frame b-roll over a backdrop is not a covered canvas
1 parent 696ca8f commit 2a0fa7f

11 files changed

Lines changed: 244 additions & 13 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1197,6 +1197,12 @@ transparent. A fully transparent frame is treated as unread on purpose, since a
11971197
failed draw looks the same; mark text that sits under a cutout before its subject
11981198
enters with `data-layout-allow-occlusion`.
11991199

1200+
`canvas_covered` is an error when an opaque element spanning the canvas sits above
1201+
every other visible clip (shape, image, video or text) for most of the film, so the
1202+
frame shows only it: typically a full-frame background placed last in the DOM. It
1203+
names the covering element; a full-frame card shown on purpose takes
1204+
`data-layout-allow-occlusion`.
1205+
12001206
Contrast failures are errors, and each one reports the sampled foreground and
12011207
background colours, the measured ratio against the required one, and a
12021208
compliant colour you could use instead.
@@ -1239,7 +1245,7 @@ edges re-measured to about 0.01 s, and skipped for a `--range` check.
12391245
| `line_unread` | A reading-size line (30 px or taller at 1080) is on screen for less than its floor: 0.4 s for one or two words, otherwise three quarters of 0.5 s + 0.3 s a word. The film's last line needs 2 s. |
12401246
| `dead_stretch` | Nothing on screen changes for more than 3 s, by the same classifier `keepsMoving` uses. |
12411247
| `text_below_floor` | Text under 2.6% of the frame's short side (28 px on 1080) stays on screen 0.5 s or more. One finding per file lists every such element. |
1242-
| `first_frame_empty` | Frame 0 paints nothing but the background: no text, image, video, canvas or SVG. The first frame is the thumbnail on social players. |
1248+
| `first_frame_empty` | Frame 0 paints nothing but the background (no text, image, video, canvas or SVG), or an opaque element covers every other clip and is named. The first frame is the thumbnail on social players. |
12431249
| `film_silent` | A film longer than 15 s has no unmuted `<audio>` and no `<video>` with sound. |
12441250

12451251
Captions-track text (`data-track-kind="captions"`) and `data-layout-ignore`

‎packages/cli/src/commands/layout-audit.browser.js‎

Lines changed: 93 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1604,6 +1604,93 @@
16041604
};
16051605
}
16061606

1607+
// canvas_covered: an opaque element over most of the canvas with every other painted clip beneath it.
1608+
const COVER_CANVAS_SHARE = 0.9;
1609+
const COVERED_CONTENT_SHARE = 0.9;
1610+
1611+
function paintsOwnContent(element) {
1612+
return (
1613+
hasOwnTextCandidate(element, true) ||
1614+
FRAME_MEDIA_TAGS.has(element.tagName.toUpperCase()) ||
1615+
hasPaint(getComputedStyle(element))
1616+
);
1617+
}
1618+
1619+
function onCanvasRect(element, rootRect) {
1620+
const rect = toRect(element.getBoundingClientRect());
1621+
const left = Math.max(rect.left, rootRect.left);
1622+
const top = Math.max(rect.top, rootRect.top);
1623+
const right = Math.min(rect.right, rootRect.right);
1624+
const bottom = Math.min(rect.bottom, rootRect.bottom);
1625+
return right > left && bottom > top
1626+
? rectFromOrigin(left, top, right - left, bottom - top)
1627+
: null;
1628+
}
1629+
1630+
// Topmost first, and a centre probe before the grid: a backdrop under its content clears on the first clip.
1631+
function isBuried(element, rootRect) {
1632+
const rect = onCanvasRect(element, rootRect);
1633+
if (!rect) return true;
1634+
if (!occluderAt(element, rect.left + rect.width / 2, rect.top + rect.height / 2)) return false;
1635+
return occlusionCoverage(element, [rect]).coveredFraction >= COVERED_CONTENT_SHARE;
1636+
}
1637+
1638+
function spansCanvas(element, rootRect) {
1639+
const rect = toRect(element.getBoundingClientRect());
1640+
return intersectionArea(rect, rootRect) >= rectArea(rootRect) * COVER_CANVAS_SHARE;
1641+
}
1642+
1643+
function visibleElementsIn(root) {
1644+
return Array.from(root.querySelectorAll("*")).filter((element) =>
1645+
isVisibleElement(element, 0.05),
1646+
);
1647+
}
1648+
1649+
// Only frame 0 asks: the craft sweep samples at 8 fps and the scan restores hit testing on every node.
1650+
function canvasCoverAt(root, rootRect) {
1651+
const restoreHits = restoreHitTesting(root);
1652+
try {
1653+
return canvasCoveredIssue(root, rootRect, visibleElementsIn(root), 0);
1654+
} finally {
1655+
restoreHits();
1656+
}
1657+
}
1658+
1659+
function canvasCoveredIssue(root, rootRect, elements, time) {
1660+
for (const cover of elements) {
1661+
if (cover === root || hasAllowOcclusionFlag(cover) || !spansCanvas(cover, rootRect)) continue;
1662+
// A buried backdrop is not a lost clip: full-frame b-roll over a background is the film.
1663+
const beneath = elements.filter(
1664+
(element) =>
1665+
element !== cover &&
1666+
!element.contains(cover) &&
1667+
paintsOwnContent(element) &&
1668+
!spansCanvas(element, rootRect),
1669+
);
1670+
if (
1671+
beneath.length === 0 ||
1672+
!beneath.reverse().every((element) => isBuried(element, rootRect))
1673+
)
1674+
continue;
1675+
// Last: an opaque check reads a video's frame, which a backdrop under its content never needs.
1676+
const rect = toRect(cover.getBoundingClientRect());
1677+
if (!isOpaqueOccluder(cover, rect.left + rect.width / 2, rect.top + rect.height / 2))
1678+
continue;
1679+
return {
1680+
code: "canvas_covered",
1681+
severity: "error",
1682+
time,
1683+
selector: uniqueSelectorFor(cover),
1684+
message:
1685+
"An opaque element covers the canvas above every other visible clip, so the frame shows only it.",
1686+
rect: toRect(cover.getBoundingClientRect()),
1687+
fixHint:
1688+
"Move the full-frame element below the content (earlier in the DOM or a lower z-index / track), or mark a deliberate full-frame card with data-layout-allow-occlusion.",
1689+
};
1690+
}
1691+
return null;
1692+
}
1693+
16071694
function layoutOffset(element) {
16081695
let left = 0;
16091696
let top = 0;
@@ -2410,9 +2497,7 @@
24102497
document.querySelector("[data-composition-id]") ||
24112498
document.body;
24122499
const rootRect = rootRectFor(root);
2413-
const elements = Array.from(root.querySelectorAll("*")).filter((element) =>
2414-
isVisibleElement(element, 0.05),
2415-
);
2500+
const elements = visibleElementsIn(root);
24162501
const issues = [];
24172502
const matteResults = new Map();
24182503
videoAlphaFrames = new Map();
@@ -2429,6 +2514,8 @@
24292514
const invisible = invisibleTextIssue(element, time);
24302515
if (invisible) issues.push(invisible);
24312516
}
2517+
const covered = canvasCoveredIssue(root, rootRect, elements, time);
2518+
if (covered) issues.push(covered);
24322519
} finally {
24332520
restoreHits();
24342521
}
@@ -2617,13 +2704,14 @@
26172704
return false;
26182705
}
26192706

2620-
window.__hyperframesCraftSample = function collectCraftSample() {
2707+
window.__hyperframesCraftSample = function collectCraftSample(options) {
26212708
const root =
26222709
document.querySelector("[data-composition-id][data-width][data-height]") ||
26232710
document.querySelector("[data-composition-id]") ||
26242711
document.body;
26252712
const rootRect = rootRectFor(root);
26262713
const parts = craftTextParts(root, rootRect);
2714+
const cover = options && options.withCover ? canvasCoverAt(root, rootRect) : null;
26272715
const holds = [root, ...Array.from(root.querySelectorAll("[data-hold]"))].filter((element) =>
26282716
element.hasAttribute("data-hold"),
26292717
);
@@ -2632,6 +2720,7 @@
26322720
parts,
26332721
held: holds.some((element) => isPaintedBox(element, rootRect)),
26342722
painted: paintsContent(root, rootRect, parts),
2723+
coveredBy: cover ? cover.selector : null,
26352724
signature: shared
26362725
? shared.compositionSignature(shared.compositionRoot(), { quantize: true })
26372726
: "",

‎packages/cli/src/commands/layout-audit.browser.test.ts‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3645,6 +3645,100 @@ function auditCoverageScene(options: {
36453645
);
36463646
}
36473647

3648+
describe("layout-audit.browser canvas_covered", () => {
3649+
afterEach(() => {
3650+
vi.restoreAllMocks();
3651+
document.body.innerHTML = "";
3652+
delete (document as unknown as { elementsFromPoint?: unknown }).elementsFromPoint;
3653+
delete (window as unknown as { __hyperframesLayoutAudit?: unknown }).__hyperframesLayoutAudit;
3654+
});
3655+
3656+
it("names a full-frame rect painted above every other clip", () => {
3657+
expect(auditCoverScene("above").filter((issue) => issue.code === "canvas_covered")).toEqual([
3658+
expect.objectContaining({ selector: "#bg-rect", severity: "error" }),
3659+
]);
3660+
});
3661+
3662+
it("leaves a full-frame background below the content alone", () => {
3663+
expect(auditCoverScene("below").some((issue) => issue.code === "canvas_covered")).toBe(false);
3664+
});
3665+
3666+
it("leaves full-frame b-roll over a backdrop alone", () => {
3667+
document.body.innerHTML = `
3668+
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
3669+
<div id="bg"></div>
3670+
<img id="broll" src="broll.jpg" alt="" />
3671+
</div>
3672+
`;
3673+
const full = rect({ left: 0, top: 0, width: 1920, height: 1080 });
3674+
installGeometry(
3675+
{ root: full, bg: full, broll: full },
3676+
{ bg: { backgroundColor: "rgb(16, 24, 48)" } },
3677+
);
3678+
(document as unknown as { elementsFromPoint: () => Element[] }).elementsFromPoint = () =>
3679+
["broll", "bg", "root"].map((id) => document.getElementById(id) as Element);
3680+
installAuditScript();
3681+
expect(runAudit().some((issue) => issue.code === "canvas_covered")).toBe(false);
3682+
});
3683+
3684+
it("leaves a full-frame background over an empty layout box alone", () => {
3685+
expect(
3686+
auditCoverScene("above", "", "empty").some((issue) => issue.code === "canvas_covered"),
3687+
).toBe(false);
3688+
});
3689+
3690+
it("names the cover for text under it too", () => {
3691+
expect(
3692+
auditCoverScene("above", "", "text").filter((issue) => issue.code === "canvas_covered"),
3693+
).toEqual([expect.objectContaining({ selector: "#bg-rect" })]);
3694+
});
3695+
3696+
it("leaves a deliberate full-frame card marked data-layout-allow-occlusion alone", () => {
3697+
const issues = auditCoverScene("above", "data-layout-allow-occlusion");
3698+
expect(issues.some((issue) => issue.code === "canvas_covered")).toBe(false);
3699+
});
3700+
});
3701+
3702+
/** A 1920x1080 stage: a shape, a line of text or an unpainted box, with a full-frame rect above or below. */
3703+
function auditCoverScene(
3704+
order: "above" | "below",
3705+
coverAttrs = "",
3706+
content: "shape" | "text" | "empty" = "shape",
3707+
): ReturnType<typeof runAudit> {
3708+
document.body.innerHTML = `
3709+
<div id="root" data-composition-id="main" data-width="1920" data-height="1080">
3710+
<div id="shape">${content === "text" ? "Headline copy" : ""}</div>
3711+
<div id="bg-rect" ${coverAttrs}></div>
3712+
</div>
3713+
`;
3714+
const shapeRect = rect({ left: 200, top: 700, width: 200, height: 200 });
3715+
installGeometry(
3716+
{
3717+
root: rect({ left: 0, top: 0, width: 1920, height: 1080 }),
3718+
shape: shapeRect,
3719+
shapeText: shapeRect,
3720+
"bg-rect": rect({ left: 0, top: 0, width: 1920, height: 1080 }),
3721+
},
3722+
{
3723+
...(content === "shape" ? { shape: { backgroundColor: "rgb(249, 115, 22)" } } : {}),
3724+
"bg-rect": { backgroundColor: "rgb(15, 27, 61)" },
3725+
},
3726+
);
3727+
const byId = (id: string) => document.getElementById(id) as Element;
3728+
(
3729+
document as unknown as { elementsFromPoint: (x: number, y: number) => Element[] }
3730+
).elementsFromPoint = (x, y) => {
3731+
const onShape =
3732+
x >= shapeRect.left && x <= shapeRect.right && y >= shapeRect.top && y <= shapeRect.bottom;
3733+
if (!onShape) return [byId("bg-rect"), byId("root")];
3734+
return (order === "above" ? ["bg-rect", "shape", "root"] : ["shape", "bg-rect", "root"]).map(
3735+
byId,
3736+
);
3737+
};
3738+
installAuditScript();
3739+
return runAudit();
3740+
}
3741+
36483742
function auditOcclusionScene(options: {
36493743
headlineAttrs?: string;
36503744
overlayAttrs?: string;

‎packages/cli/src/utils/checkBrowser.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1001,17 +1001,19 @@ export function createPageDriver(
10011001
}
10021002

10031003
async function collectCraftFrame(page: Page, time: number): Promise<CraftFrame> {
1004-
const raw = await page.evaluate(() => {
1004+
const raw = await page.evaluate((withCover: boolean) => {
10051005
const sample = Reflect.get(window, "__hyperframesCraftSample");
1006-
return typeof sample === "function" ? Reflect.apply(sample, window, []) : null;
1007-
});
1006+
return typeof sample === "function" ? Reflect.apply(sample, window, [{ withCover }]) : null;
1007+
}, time <= 1e-3);
10081008
const record = isRecord(raw) ? raw : {};
10091009
const parts = Reflect.get(record, "parts");
1010+
const coveredBy = stringValue(record, "coveredBy");
10101011
return {
10111012
time,
10121013
parts: Array.isArray(parts) ? parts.flatMap(parseCraftTextPart) : [],
10131014
held: booleanValue(record, "held") ?? false,
10141015
painted: booleanValue(record, "painted") ?? true,
1016+
...(coveredBy ? { coveredBy } : {}),
10151017
signature: stringValue(record, "signature") ?? "",
10161018
};
10171019
}
@@ -2119,6 +2121,7 @@ const LAYOUT_ISSUE_CODES: readonly LayoutIssueCode[] = [
21192121
"content_overlap",
21202122
"visibility_escapes_segment",
21212123
"text_occluded",
2124+
"canvas_covered",
21222125
"video_alpha_unread",
21232126
"text_not_painted",
21242127
"caption_zone_collision",

‎packages/cli/src/utils/checkTypes.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,7 @@ export interface CraftFrame {
237237
/** A data-hold element is on screen: stillness here is deliberate. */
238238
held: boolean;
239239
painted: boolean;
240+
coveredBy?: string;
240241
signature: string;
241242
}
242243

‎packages/cli/src/utils/craftAudit.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -254,6 +254,12 @@ describe("first_frame_empty", () => {
254254
expect(findings[0]?.message).toContain("references/review.md");
255255
});
256256

257+
it("names the element covering frame 0, even when content is painted beneath it", () => {
258+
const findings = detectFirstFrameEmpty([frameAt(0, [], { coveredBy: "#bg-rect" })]);
259+
expect(findings).toHaveLength(1);
260+
expect(findings[0]?.message).toContain("covered by #bg-rect");
261+
});
262+
257263
it("does not warn when the title is already on screen at 0 s", () => {
258264
expect(detectFirstFrameEmpty([frameAt(0, [], { painted: true })])).toEqual([]);
259265
expect(detectFirstFrameEmpty([frameAt(0.5, [], { painted: false })])).toEqual([]);

‎packages/cli/src/utils/craftAudit.ts‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,17 @@ function filmFinding(
115115

116116
export function detectFirstFrameEmpty(frames: CraftFrame[]): CraftFinding[] {
117117
const first = frames[0];
118-
if (!first || first.time > 1e-3 || first.painted) return [];
118+
if (!first || first.time > 1e-3) return [];
119+
if (first.coveredBy) {
120+
return [
121+
filmFinding(
122+
"first_frame_empty",
123+
0,
124+
`Frame 0 is covered by ${first.coveredBy}: an opaque element over the canvas hides every other clip, and the first frame is the thumbnail on social players. Move it below the content; see canvas_covered.`,
125+
),
126+
];
127+
}
128+
if (first.painted) return [];
119129
return [
120130
filmFinding(
121131
"first_frame_empty",

‎packages/cli/src/utils/layoutAudit.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,16 @@ describe("layoutAudit helpers", () => {
136136
});
137137
});
138138

139+
it("keeps canvas_covered an error only when the canvas is covered for most of the film", () => {
140+
const covered = (times: number[], samples: number) =>
141+
collapseStaticLayoutIssues(
142+
times.map((time) => ({ ...issue("canvas_covered", "error"), time })),
143+
samples,
144+
)[0]?.severity;
145+
expect(covered([1, 2, 3, 4, 5], 8)).toBe("error");
146+
expect(covered([7, 8], 8)).toBe("info");
147+
});
148+
139149
it("formats issues with timestamp, selector, container, and fix hint", () => {
140150
const formatted = formatLayoutIssue({
141151
...issue("text_box_overflow", "error"),

‎packages/cli/src/utils/layoutAudit.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ export type LayoutIssueCode =
1818
| "content_overlap"
1919
| "visibility_escapes_segment"
2020
| "text_occluded"
21+
| "canvas_covered"
2122
| "video_alpha_unread"
2223
| "text_not_painted"
2324
| "caption_zone_collision"
@@ -263,7 +264,7 @@ export function collapseStaticLayoutIssues(
263264
const multiSampleRun = sampleCount > 1;
264265

265266
return [...groups.values()].map(({ issue, firstSeen, lastSeen, occurrences, times }) =>
266-
applyPersistenceTier(
267+
tierIssue(
267268
{
268269
...issue,
269270
firstSeen,
@@ -273,6 +274,7 @@ export function collapseStaticLayoutIssues(
273274
times: [...new Set(times)].sort((a, b) => a - b),
274275
},
275276
multiSampleRun,
277+
sampleCount,
276278
),
277279
);
278280
}
@@ -298,6 +300,16 @@ export function longestContiguousRun(times: number[]): number[] {
298300
return longest.length === 0 || span(run) > span(longest) ? run : longest;
299301
}
300302

303+
/** A full-frame card or a fade to colour covers the canvas briefly; most of the film is a blank stage. */
304+
function coverTier(issue: LayoutIssue, sampleCount: number): LayoutIssue {
305+
return (issue.occurrences ?? 1) * 2 >= sampleCount ? issue : { ...issue, severity: "info" };
306+
}
307+
308+
function tierIssue(issue: LayoutIssue, multiSampleRun: boolean, sampleCount: number): LayoutIssue {
309+
if (multiSampleRun && issue.code === "canvas_covered") return coverTier(issue, sampleCount);
310+
return applyPersistenceTier(issue, multiSampleRun);
311+
}
312+
301313
/**
302314
* Held-duration severity tiering (#U10). A finding observed at only one
303315
* sample among several (held 0ms) is an entrance/exit transient, not a held

‎skills-manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
"files": 77
1111
},
1212
"hyperframes-cli": {
13-
"hash": "433959bc422463f4",
13+
"hash": "19e8e8f081dabdfd",
1414
"files": 13
1515
},
1616
"hyperframes-registry": {

0 commit comments

Comments
 (0)