Skip to content

Commit 209e6e0

Browse files
feat(check): opt-in --layout proseCoverageFloor (#2834)
* feat(check): opt-in --layout proseCoverageFloor for text_occluded Keep the default prose coverage floor at 0.15 for all callers, and allow stricter agents (e.g. Zephyr) to lower it via --layout "proseCoverageFloor=0.05" without changing other layout gates. Co-authored-by: Cursor <[email protected]> * style(check): collapse --layout comments and docs to one line Co-authored-by: Cursor <[email protected]> * fix(check): strict proseCoverageFloor parse + pin 0.07 floor tests Reject trailing-garbage fractions that Number.parseFloat would accept, and pin the existing ~0.07 coverage fixture for default vs floor=0.05 (atomic labels unchanged) plus a collectLayout forwarding assertion. Co-authored-by: Cursor <[email protected]> * fix(check): share parseNumberStrict across layout and frame-check Sweep the sibling --frame-check tol parser (and caption fractions) onto the same strict Number() helper so trailing garbage cannot prefix-parse. Co-authored-by: Cursor <[email protected]> --------- Co-authored-by: Cursor <[email protected]>
1 parent 37295b3 commit 209e6e0

7 files changed

Lines changed: 177 additions & 23 deletions

File tree

‎packages/cli/src/commands/check.test.ts‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1141,6 +1141,57 @@ describe("frame-check flag grammar", () => {
11411141
});
11421142
expect(() => parseFrameCheck("bogus=1")).toThrow("Invalid --frame-check");
11431143
expect(() => parseFrameCheck("tol=-2")).toThrow("Invalid --frame-check");
1144+
expect(() => parseFrameCheck("tol=4px")).toThrow("Invalid --frame-check");
1145+
expect(() => parseFrameCheck("tol=2garbage")).toThrow("Invalid --frame-check");
1146+
});
1147+
});
1148+
1149+
describe("layout flag grammar", () => {
1150+
it("parses proseCoverageFloor and rejects malformed specs", async () => {
1151+
const { parseLayout } = await import("./check.js");
1152+
expect(parseLayout(undefined)).toBeUndefined();
1153+
expect(parseLayout("proseCoverageFloor=0.05")).toEqual({ proseCoverageFloor: 0.05 });
1154+
expect(parseLayout("proseCoverageFloor=0")).toEqual({ proseCoverageFloor: 0 });
1155+
expect(parseLayout("proseCoverageFloor=1")).toEqual({ proseCoverageFloor: 1 });
1156+
expect(() => parseLayout(true)).toThrow("Invalid --layout");
1157+
expect(() => parseLayout("")).toThrow("Invalid --layout");
1158+
expect(() => parseLayout("bogus=1")).toThrow("Invalid --layout");
1159+
expect(() => parseLayout("proseCoverageFloor=-0.1")).toThrow("Invalid --layout");
1160+
expect(() => parseLayout("proseCoverageFloor=1.1")).toThrow("Invalid --layout");
1161+
expect(() => parseLayout("proseCoverageFloor=0.05garbage")).toThrow("Invalid --layout");
1162+
expect(() => parseLayout("proseCoverageFloor=0.1%")).toThrow("Invalid --layout");
1163+
expect(() => parseLayout("proseCoverageFloor=")).toThrow("Invalid --layout");
1164+
});
1165+
1166+
it("threads --layout into the check pipeline options", async () => {
1167+
const { report } = await runScenario(fakeDriver());
1168+
const runPipeline = vi.fn(async (_project: ProjectDir, _options: CheckOptions) => report);
1169+
vi.spyOn(console, "log").mockImplementation(() => undefined);
1170+
const command = createCheckCommand({
1171+
resolveProject: () => PROJECT,
1172+
runPipeline,
1173+
withMeta: (value) => value,
1174+
});
1175+
1176+
await runCommand(command, {
1177+
rawArgs: ["--json", "--layout", "proseCoverageFloor=0.05"],
1178+
});
1179+
1180+
expect(runPipeline).toHaveBeenCalledWith(
1181+
PROJECT,
1182+
expect.objectContaining({
1183+
layout: { proseCoverageFloor: 0.05 },
1184+
}),
1185+
);
1186+
});
1187+
1188+
it("forwards layout options into driver.collectLayout", async () => {
1189+
const collectLayout = vi.fn(async (_time: number, _tolerance: number, _layout?: unknown) => []);
1190+
await runScenario(fakeDriver({ collectLayout }), { layout: { proseCoverageFloor: 0.05 } });
1191+
expect(collectLayout).toHaveBeenCalled();
1192+
expect(collectLayout).toHaveBeenCalledWith(expect.any(Number), expect.any(Number), {
1193+
proseCoverageFloor: 0.05,
1194+
});
11441195
});
11451196
});
11461197

‎packages/cli/src/commands/check.ts‎

Lines changed: 58 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import {
1616
type CheckReport,
1717
type CheckSection,
1818
} from "../utils/checkPipeline.js";
19-
import type { CaptionZoneOptions, FrameCheckOptions } from "../utils/checkTypes.js";
19+
import type { CaptionZoneOptions, FrameCheckOptions, LayoutOptions } from "../utils/checkTypes.js";
2020

2121
export const examples: Example[] = [
2222
["Run the full verification gate", "hyperframes check"],
@@ -120,6 +120,10 @@ export function createCheckCommand(
120120
description:
121121
'Bare --frame-check uses defaults (tol=2px, severity=warning, seek=.5; breach floor=max(120px, 6% of shorter canvas edge)); or pass "severity=error;seek=.25,.75;tol=4" to tune',
122122
},
123+
layout: {
124+
type: "string",
125+
description: 'Layout knobs: "proseCoverageFloor=0.05" (0–1; default 0.15).',
126+
},
123127
},
124128
async run({ args }) {
125129
const asJson = args.json === true;
@@ -168,6 +172,7 @@ function parseCheckOptions(args: Record<string, unknown>): CheckOptions {
168172
snapshots: args.snapshots === true,
169173
captionZone: parseCaptionZone(args["caption-zone"]),
170174
frameCheck: parseFrameCheck(args["frame-check"]),
175+
layout: parseLayout(args.layout),
171176
autoProxy: args.proxy as boolean | undefined,
172177
};
173178
}
@@ -176,6 +181,8 @@ const CAPTION_ZONE_FIELDS = new Set(["x0", "y0", "x1", "y1", "severity", "seek"]
176181

177182
const FRAME_CHECK_FIELDS = new Set(["severity", "seek", "tol"]);
178183

184+
const LAYOUT_FIELDS = new Set(["proseCoverageFloor"]);
185+
179186
// Mirrors --caption-zone's spec grammar so the EF bridge's severity/seek/tol
180187
// options survive the migration instead of being silently dropped by a
181188
// boolean flag (bare --frame-check keeps today's defaults).
@@ -206,8 +213,8 @@ function parseFrameCheckFields(value: string): Map<string, string> {
206213

207214
function parseFrameCheckTolerance(raw: string | undefined): number | undefined {
208215
if (raw === undefined) return undefined;
209-
const tol = Number.parseFloat(raw);
210-
if (!Number.isFinite(tol) || tol < 0) throw frameCheckError();
216+
const tol = parseNumberStrict(raw);
217+
if (tol === null || tol < 0) throw frameCheckError();
211218
return tol;
212219
}
213220

@@ -217,6 +224,52 @@ function frameCheckError(): Error {
217224
);
218225
}
219226

227+
/** Parse `--layout "proseCoverageFloor=0.05"` (semicolon-separated key=value, like caption-zone). */
228+
export function parseLayout(value: unknown): LayoutOptions | undefined {
229+
if (value === undefined || value === null || value === false) return undefined;
230+
if (value === true || value === "") throw layoutError();
231+
if (typeof value !== "string") throw layoutError();
232+
const fields = parseLayoutFields(value);
233+
const proseCoverageFloor = parseProseCoverageFloor(fields.get("proseCoverageFloor"));
234+
if (proseCoverageFloor === undefined) throw layoutError();
235+
return { proseCoverageFloor };
236+
}
237+
238+
function parseLayoutFields(value: string): Map<string, string> {
239+
const fields = new Map<string, string>();
240+
for (const part of value.split(";")) {
241+
const trimmed = part.trim();
242+
if (!trimmed) continue;
243+
const separator = trimmed.indexOf("=");
244+
if (separator <= 0) throw layoutError();
245+
const key = trimmed.slice(0, separator).trim();
246+
const entry = trimmed.slice(separator + 1).trim();
247+
if (!LAYOUT_FIELDS.has(key) || fields.has(key)) throw layoutError();
248+
fields.set(key, entry);
249+
}
250+
return fields;
251+
}
252+
253+
function parseProseCoverageFloor(raw: string | undefined): number | undefined {
254+
if (raw === undefined) return undefined;
255+
const floor = parseNumberStrict(raw);
256+
if (floor === null || floor < 0 || floor > 1) throw layoutError();
257+
return floor;
258+
}
259+
260+
function layoutError(): Error {
261+
return new Error(
262+
'Invalid --layout: use "proseCoverageFloor=0.05" with a fraction from 0 to 1 (inclusive)',
263+
);
264+
}
265+
266+
/** Reject trailing garbage that Number.parseFloat would silently accept (`4px`, `0.05abc`). */
267+
function parseNumberStrict(raw: string): number | null {
268+
if (raw === "") return null;
269+
const value = Number(raw);
270+
return Number.isFinite(value) ? value : null;
271+
}
272+
220273
function parseCaptionZone(value: unknown): CaptionZoneOptions | undefined {
221274
if (value === undefined || value === null) return undefined;
222275
const fields = parseCaptionFields(captionZoneString(value));
@@ -279,8 +332,8 @@ function requiredCaptionFraction(fields: Map<string, string>, key: string): numb
279332

280333
function captionFraction(value: string | undefined): number | null {
281334
if (value === undefined || value === "") return null;
282-
const parsed = Number(value);
283-
return Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : null;
335+
const parsed = parseNumberStrict(value);
336+
return parsed !== null && parsed >= 0 && parsed <= 1 ? parsed : null;
284337
}
285338

286339
function captionSeverity(value: string | undefined): "error" | "warning" | undefined {

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

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -935,7 +935,8 @@
935935
// (the pre-#U10 behaviour). Longer prose survives a nibbled edge; only flag
936936
// once a real share of it is covered — see `occludedTextIssue`.
937937
const ATOMIC_LABEL_MAX_CHARS = 16;
938-
const PROSE_COVERAGE_FLOOR = 0.15;
938+
// Default prose floor — callers may lower via auditLayout({ proseCoverageFloor }).
939+
const DEFAULT_PROSE_COVERAGE_FLOOR = 0.15;
939940

940941
function isAtomicLabel(text) {
941942
return text.length > 0 && text.length <= ATOMIC_LABEL_MAX_CHARS && !/\s/.test(text);
@@ -995,12 +996,8 @@
995996
return false;
996997
}
997998

998-
// Catches the blind spot the overflow checks miss: text that fits its box
999-
// perfectly but is covered by a later sibling/overlay. An atomic label
1000-
// (short, no whitespace) flags at any coverage; ordinary prose only flags
1001-
// once coveredFraction clears PROSE_COVERAGE_FLOOR, since a sliver of edge
1002-
// cover on a paragraph is usually a styling artifact, not a reading defect.
1003-
function occludedTextIssue(element, time) {
999+
// text_occluded: atomic labels flag at any hit; prose needs coveredFraction >= proseCoverageFloor (default 0.15).
1000+
function occludedTextIssue(element, time, proseCoverageFloor) {
10041001
if (hasAllowOcclusionFlag(element)) return null;
10051002
if (!hasVisibleTextInk(element)) return null;
10061003
const textRect = textRectFor(element, true);
@@ -1012,7 +1009,7 @@
10121009
textRects.length > 0 ? textRects : [textRect],
10131010
);
10141011
if (!occluder) return null;
1015-
if (!isAtomicLabel(text) && coveredFraction < PROSE_COVERAGE_FLOOR) return null;
1012+
if (!isAtomicLabel(text) && coveredFraction < proseCoverageFloor) return null;
10161013
return {
10171014
code: "text_occluded",
10181015
severity: "error",
@@ -1420,6 +1417,10 @@
14201417
const time = options && typeof options.time === "number" ? options.time : 0;
14211418
const tolerance =
14221419
options && typeof options.tolerance === "number" ? Math.max(0, options.tolerance) : 2;
1420+
const proseCoverageFloor =
1421+
options && typeof options.proseCoverageFloor === "number"
1422+
? Math.min(1, Math.max(0, options.proseCoverageFloor))
1423+
: DEFAULT_PROSE_COVERAGE_FLOOR;
14231424
const root =
14241425
document.querySelector("[data-composition-id][data-width][data-height]") ||
14251426
document.querySelector("[data-composition-id]") ||
@@ -1437,7 +1438,7 @@
14371438
const clipped = clippedTextIssue(element, time, tolerance);
14381439
if (clipped) issues.push(clipped);
14391440
issues.push(...textOverflowIssues(element, root, rootRect, time, tolerance));
1440-
const occluded = occludedTextIssue(element, time);
1441+
const occluded = occludedTextIssue(element, time, proseCoverageFloor);
14411442
if (occluded) issues.push(occluded);
14421443
const invisible = invisibleTextIssue(element, time);
14431444
if (invisible) issues.push(invisible);

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

Lines changed: 33 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1786,6 +1786,26 @@ describe("layout-audit.browser occlusion", () => {
17861786
expect(issues.some((issue) => issue.code === "text_occluded")).toBe(false);
17871787
});
17881788

1789+
it("flags ~0.07 prose when proseCoverageFloor is lowered to 0.05", () => {
1790+
const issues = auditCoverageScene({
1791+
text: "This paragraph is long enough to read as ordinary prose, not a label.",
1792+
hitCount: 2,
1793+
proseCoverageFloor: 0.05,
1794+
});
1795+
const occluded = issues.find((issue) => issue.code === "text_occluded");
1796+
expect(occluded).toBeDefined();
1797+
expect(occluded?.coveredFraction).toBe(0.07);
1798+
});
1799+
1800+
it("still flags an atomic label at ~0.07 when proseCoverageFloor is 0.05", () => {
1801+
const issues = auditCoverageScene({
1802+
text: "SUBSCRIBE",
1803+
hitCount: 2,
1804+
proseCoverageFloor: 0.05,
1805+
});
1806+
expect(issues.some((issue) => issue.code === "text_occluded")).toBe(true);
1807+
});
1808+
17891809
it("flags prose once coverage clears the 0.15 floor", () => {
17901810
// 5/27 ≈ 0.185, comfortably over the ~0.15 prose floor.
17911811
const issues = auditCoverageScene({
@@ -2042,6 +2062,7 @@ function occlusionProbePoints(textRect: RectInput): Array<{ x: number; y: number
20422062
function auditCoverageScene(options: {
20432063
text: string;
20442064
hitCount: number;
2065+
proseCoverageFloor?: number;
20452066
}): ReturnType<typeof runAudit> {
20462067
const textRect = { left: 200, top: 500, width: 600, height: 80 };
20472068
document.body.innerHTML = `
@@ -2065,7 +2086,11 @@ function auditCoverageScene(options: {
20652086
return document.getElementById(isHit ? "overlay" : "headline");
20662087
};
20672088
installAuditScript();
2068-
return runAudit();
2089+
return runAudit(
2090+
options.proseCoverageFloor === undefined
2091+
? undefined
2092+
: { proseCoverageFloor: options.proseCoverageFloor },
2093+
);
20692094
}
20702095

20712096
function auditOcclusionScene(options: {
@@ -2318,13 +2343,17 @@ interface AuditIssue {
23182343
coveredFraction?: number;
23192344
}
23202345

2321-
function runAudit(): AuditIssue[] {
2346+
function runAudit(options?: { proseCoverageFloor?: number }): AuditIssue[] {
23222347
const audit = (
23232348
window as unknown as {
2324-
__hyperframesLayoutAudit: (options: { time: number; tolerance: number }) => AuditIssue[];
2349+
__hyperframesLayoutAudit: (options: {
2350+
time: number;
2351+
tolerance: number;
2352+
proseCoverageFloor?: number;
2353+
}) => AuditIssue[];
23252354
}
23262355
).__hyperframesLayoutAudit;
2327-
return audit({ time: 1, tolerance: 2 });
2356+
return audit({ time: 1, tolerance: 2, ...options });
23282357
}
23292358

23302359
function selectedRangeElement(selected: Node | null): Element | null {

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

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ import type {
4242
ContrastAuditEntry,
4343
ContrastCapture,
4444
GeometryCandidateRequest,
45+
LayoutOptions,
4546
MotionSpecResolution,
4647
OffPivotFrame,
4748
OffPivotRotationSample,
@@ -353,7 +354,7 @@ function createPageDriver(page: Page, setTime: (time: number) => void): CheckAud
353354
setTime(time);
354355
await seekCompositionTimeline(page, time, DENSE_GEOMETRY_SEEK_OPTIONS);
355356
},
356-
collectLayout: (time, tolerance) => collectLayout(page, time, tolerance),
357+
collectLayout: (time, tolerance, layout) => collectLayout(page, time, tolerance, layout),
357358
collectOverlap: (time) => collectOverlap(page, time),
358359
collectLayoutGeometry: () => collectLayoutGeometry(page),
359360
collectRotationSample: (time) => collectRotationSample(page, time),
@@ -457,15 +458,22 @@ async function collectLayout(
457458
page: Page,
458459
time: number,
459460
tolerance: number,
461+
layout?: LayoutOptions,
460462
): Promise<AnchoredLayoutIssue[]> {
461463
const raw = await page.evaluate(
462-
(options: { time: number; tolerance: number }) => {
464+
(options: { time: number; tolerance: number; proseCoverageFloor?: number }) => {
463465
const audit = Reflect.get(window, "__hyperframesLayoutAudit");
464466
if (typeof audit !== "function") return [];
465467
const result = Reflect.apply(audit, window, [options]);
466468
return Array.isArray(result) ? result : [];
467469
},
468-
{ time, tolerance },
470+
{
471+
time,
472+
tolerance,
473+
...(typeof layout?.proseCoverageFloor === "number"
474+
? { proseCoverageFloor: layout.proseCoverageFloor }
475+
: {}),
476+
},
469477
);
470478
return anchorLayoutIssues(page, raw.flatMap(parseLayoutIssue));
471479
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -380,7 +380,7 @@ async function collectGridSamples(
380380
// that render time — never a stale bbox from an earlier/later sample.
381381
const issuesAtTime: AnchoredLayoutIssue[] = [];
382382
if (layoutSet.has(time)) {
383-
const layoutIssues = await driver.collectLayout(time, options.tolerance);
383+
const layoutIssues = await driver.collectLayout(time, options.tolerance, options.layout);
384384
collected.layoutIssues.push(...layoutIssues);
385385
issuesAtTime.push(...layoutIssues);
386386
collected.geometrySignatures.push(await driver.collectLayoutGeometry());

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

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ export interface CheckOptions {
1818
snapshots: boolean;
1919
captionZone?: CaptionZoneOptions;
2020
frameCheck?: FrameCheckOptions;
21+
/** Opt-in layout-audit knobs (`--layout "proseCoverageFloor=0.05"`). Defaults stay in the browser audit. */
22+
layout?: LayoutOptions;
2123
/** Explicit --proxy/--no-proxy override; undefined preserves project config. */
2224
autoProxy?: boolean;
2325
}
@@ -37,6 +39,12 @@ export interface FrameCheckOptions {
3739
seek?: number[];
3840
}
3941

42+
/** Layout-audit tuning passed through to `__hyperframesLayoutAudit`. All fields optional. */
43+
export interface LayoutOptions {
44+
/** Prose `text_occluded` coveredFraction floor (0–1; default 0.15); atomic labels still flag at any hit. */
45+
proseCoverageFloor?: number;
46+
}
47+
4048
export type CheckSeverity = "error" | "warning" | "info";
4149

4250
export interface CheckBbox {
@@ -175,7 +183,11 @@ export interface CheckAuditDriver {
175183
seek(time: number): Promise<void>;
176184
/** Settle-free seek for the geometry-only dense content_overlap pass; only collectOverlap consumes it, and getBoundingClientRect is valid synchronously after setTime. */
177185
seekGeometry(time: number): Promise<void>;
178-
collectLayout(time: number, tolerance: number): Promise<AnchoredLayoutIssue[]>;
186+
collectLayout(
187+
time: number,
188+
tolerance: number,
189+
layout?: LayoutOptions,
190+
): Promise<AnchoredLayoutIssue[]>;
179191
/** content_overlap only, for the dense re-sampling grid — catches transient text collisions the sparse grid seeks past. */
180192
collectOverlap(time: number): Promise<AnchoredLayoutIssue[]>;
181193
/** Frozen-sweep guard (#U10): an opaque per-sample geometry+opacity

0 commit comments

Comments
 (0)