Skip to content

Commit 72e2f08

Browse files
xuanruliclaude
andauthored
feat(lint): dense motion re-sampling for content_overlap (#2746)
* feat(lint): dense motion re-sampling for content_overlap Transient text-on-text collisions during continuous motion (e.g. an orbiting label card crossing the center card) overlap for a fraction of a second that the sparse 9-point layout grid seeks straight past. The content_overlap detector is correct; it just never gets a sample at the crossing moment. Rerun ONLY content_overlap on an 8fps grid (text-only, cheap) when the composition animates; findings feed the existing persistence tiering unchanged. Co-Authored-By: Claude Opus 4.8 <[email protected]> * fix(lint): unconditional dense content_overlap pass + honor 500ms floor Round-1 blocker: the dense motion-overlap re-pass was gated on sparse-grid geometry fingerprints changing, so an animation aliased to the sparse grid (identical fingerprints, yet colliding between samples) bypassed the pass — exactly the transient false-negative it was built to catch. Remove the gate: the dense pass now runs unconditionally (bounded, text-only), driven by the composition timeline rather than a fingerprint heuristic. Round-2 follow-ups: - Persistence-tier drift: at 8fps, occurrences>=2 spans only ~125ms, not the ~500ms the design intends, and it short-circuited before the ms floor. content_overlap promotion now requires BOTH occurrences>=2 AND a literal firstSeen..lastSeen span >= 500ms, so the wall-clock floor is honored at any sampling density. Comment block updated to match. - Sample cap scales to hold a true 8fps grid up to ~75s (raised 120 -> 600) with an explicit note that longer comps degrade below 8fps to stay bounded. Tests: - Replaced the trivial "warning at every sample" test with a real between-grid regression: a collision living only inside (3.5,4.5) — a gap the sparse grid seeks past — is detected and, held ~750ms, promoted to error. - Replaced the now-invalid "skips when static" test with one asserting the dense pass runs even when sparse fingerprints are identical (aliased motion). - Added a tiering regression: two dense occurrences spanning ~125ms stay a warning (not error). Both new guards verified red before the fix. Co-Authored-By: Claude Opus 4.8 <[email protected]> * perf(lint): settle-free geometry seek for dense content_overlap pass The dense overlap re-pass did up to OVERLAP_MAX_SAMPLES full-settle seeks (120ms paint settle each, ~72s of pure sleep at the ceiling) even though collectOverlap only reads getBoundingClientRect geometry, valid synchronously after the timeline setTime. Add a settle-free DENSE_GEOMETRY_SEEK_OPTIONS + driver.seekGeometry used only by the dense loop; the base grid keeps full-settle driver.seek. Co-Authored-By: Claude Opus 4.8 <[email protected]> * test(lint): document + cover content_overlap 500ms boundary for sparse callers The occurrences>=2 AND heldMs>=500 promotion rule is a semantics change for sparse callers (--samples 20, --at, short comps) whose two samples can land <500ms apart. Document the change in the tiering comment and add boundary tests: 499ms span stays warning, 500ms span promotes to error. Co-Authored-By: Claude Opus 4.8 <[email protected]> * fix(lint): make dense content_overlap seek genuinely geometry-only Per review: DENSE_GEOMETRY_SEEK_OPTIONS only overrode settleMs, still inheriting animationFrameSettle:double + waitForFontsMs:500 → ~3 frame waits + font wait per seek → ~30s at the 600-sample cap. Geometry (getBoundingClientRect) is valid synchronously post-setTime, so drop all post-seek waits (animationFrameSettle:none, waitForFontsMs:0, settleMs:0). Add options-level regression locking the geometry-only contract. Also fix a stale comment name (detectMotionTextOverlap → collectMotionOverlapSamples). Co-Authored-By: Claude Opus 4.8 <[email protected]> * style: collapse multi-line comments to single lines Co-Authored-By: Claude Opus 4.8 <[email protected]> --------- Co-authored-by: Claude Opus 4.8 <[email protected]>
1 parent 3b3d4f5 commit 72e2f08

9 files changed

Lines changed: 174 additions & 19 deletions

File tree

‎packages/cli/src/capture/captureCompositionFrame.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ import { tmpdir } from "node:os";
33
import { join } from "node:path";
44
import { afterEach, describe, expect, it, vi } from "vitest";
55
import {
6+
AUDIT_SEEK_OPTIONS,
7+
DENSE_GEOMETRY_SEEK_OPTIONS,
68
captureRegionCrop,
79
clampCropRegion,
810
installPageFunctionGuard,
@@ -374,3 +376,15 @@ describe("installPageFunctionGuard", () => {
374376
expect(shim(marker)).toBe(marker);
375377
});
376378
});
379+
380+
describe("DENSE_GEOMETRY_SEEK_OPTIONS", () => {
381+
it("is genuinely geometry-only — no post-seek settle waits at the 600-sample cap", () => {
382+
// Dense pass must not inherit AUDIT's post-seek waits — geometry is valid synchronously after setTime, and waits multiply by sample count.
383+
expect(DENSE_GEOMETRY_SEEK_OPTIONS.animationFrameSettle).toBe("none");
384+
expect(DENSE_GEOMETRY_SEEK_OPTIONS.waitForFontsMs).toBe(0);
385+
expect(DENSE_GEOMETRY_SEEK_OPTIONS.settleMs).toBe(0);
386+
// AUDIT (the full-settle path used by the base grid) must still carry the waits.
387+
expect(AUDIT_SEEK_OPTIONS.animationFrameSettle).toBe("double");
388+
expect(AUDIT_SEEK_OPTIONS.settleMs).toBeGreaterThan(0);
389+
});
390+
});

‎packages/cli/src/capture/captureCompositionFrame.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,14 @@ export const AUDIT_SEEK_OPTIONS = {
1818
settleMs: 120,
1919
} as const;
2020

21+
// Geometry-only seek for the dense content_overlap grid: getBoundingClientRect is valid synchronously after setTime, so drop all post-seek waits (rAF/font/sleep) that would multiply across the dense grid.
22+
export const DENSE_GEOMETRY_SEEK_OPTIONS = {
23+
...AUDIT_SEEK_OPTIONS,
24+
animationFrameSettle: "none",
25+
waitForFontsMs: 0,
26+
settleMs: 0,
27+
} as const;
28+
2129
export interface SeekCompositionTimelineOptions {
2230
fallbackToBridgeAndTimelines?: boolean;
2331
waitForPreferredSeekTargetMs?: number;

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,9 @@ function fakeDriver(overrides: Partial<CheckAuditDriver> = {}): CheckAuditDriver
147147
getCanvas: vi.fn(async () => ({ width: 1920, height: 1080 })),
148148
findAmbiguousSelectors: vi.fn(async (_selectors: string[]) => []),
149149
seek: vi.fn(async (_time: number) => undefined),
150+
seekGeometry: vi.fn(async (_time: number) => undefined),
150151
collectLayout: vi.fn(async (_time: number, _tolerance: number) => []),
152+
collectOverlap: vi.fn(async (_time: number) => []),
151153
collectLayoutGeometry: vi.fn(async () => `geometry-${geometryCallCount++}`),
152154
collectRotationSample: vi.fn(async (_time: number) => []),
153155
collectOffPivotRotationSample: vi.fn(async (time: number) => ({ time, samples: [] })),
@@ -1343,3 +1345,42 @@ describe("contrast candidate round-trip", () => {
13431345
expect(source).not.toMatch(/prepared\.map\(\(entry\) => entry\.candidate\)/);
13441346
});
13451347
});
1348+
1349+
describe("dense motion-overlap re-sampling", () => {
1350+
// Collision lives inside (3.5, 4.5), a gap the sparse base grid seeks past; only the 8fps dense pass observes it.
1351+
const inBetweenGridWindow = (time: number): boolean => time >= 3.6 && time <= 4.4;
1352+
1353+
it("detects a content_overlap that occurs ONLY between two sparse grid samples", async () => {
1354+
const driver = fakeDriver({
1355+
// Sparse base grid sees nothing at any base sample time.
1356+
collectLayout: vi.fn(async (_time: number) => []),
1357+
// The transient exists only strictly between base samples 3.5 and 4.5.
1358+
collectOverlap: vi.fn(async (time: number) =>
1359+
inBetweenGridWindow(time)
1360+
? [layoutIssue("warning", { time, code: "content_overlap" })]
1361+
: [],
1362+
),
1363+
});
1364+
const { report } = await runScenario(driver);
1365+
expect(driver.collectOverlap).toHaveBeenCalled();
1366+
expect(report.layout.findings.some((f) => f.code === "content_overlap")).toBe(true);
1367+
// Held ~750ms across the dense grid (>= the 500ms floor) -> promoted.
1368+
expect(report.layout.errorCount).toBeGreaterThan(0);
1369+
});
1370+
1371+
it("runs the dense pass even when sparse fingerprints are identical (aliased motion)", async () => {
1372+
// Aliased motion has identical fingerprints yet still collides between samples — the false-negative the removed gate caused.
1373+
const driver = fakeDriver({
1374+
collectLayoutGeometry: vi.fn(async () => "static"),
1375+
collectLayout: vi.fn(async (_time: number) => []),
1376+
collectOverlap: vi.fn(async (time: number) =>
1377+
inBetweenGridWindow(time)
1378+
? [layoutIssue("warning", { time, code: "content_overlap" })]
1379+
: [],
1380+
),
1381+
});
1382+
const { report } = await runScenario(driver);
1383+
expect(driver.collectOverlap).toHaveBeenCalled();
1384+
expect(report.layout.findings.some((f) => f.code === "content_overlap")).toBe(true);
1385+
});
1386+
});

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1425,6 +1425,16 @@
14251425
return issues;
14261426
};
14271427

1428+
// Reruns only the overlap detector (same threshold, no new surface) on a fine grid for the dense motion re-sampling pass.
1429+
window.__hyperframesOverlapAudit = function auditOverlap(options) {
1430+
const time = options && typeof options.time === "number" ? options.time : 0;
1431+
const root =
1432+
document.querySelector("[data-composition-id][data-width][data-height]") ||
1433+
document.querySelector("[data-composition-id]") ||
1434+
document.body;
1435+
return contentOverlapIssues(root, time);
1436+
};
1437+
14281438
// Frozen-sweep guard (#U10, checkPipeline.ts): a compact per-sample
14291439
// fingerprint of every visible element's box + opacity, in DOM order. Node
14301440
// calls this once per seeked grid point and compares the strings across the

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

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
33
import type { Page } from "puppeteer-core";
44
import {
55
AUDIT_SEEK_OPTIONS,
6+
DENSE_GEOMETRY_SEEK_OPTIONS,
67
DEFAULT_ZOOM_PADDING_PX,
78
DEFAULT_ZOOM_SCALE,
89
captureRegionCrop,
@@ -348,7 +349,12 @@ function createPageDriver(page: Page, setTime: (time: number) => void): CheckAud
348349
setTime(time);
349350
await seekCompositionTimeline(page, time, AUDIT_SEEK_OPTIONS);
350351
},
352+
seekGeometry: async (time) => {
353+
setTime(time);
354+
await seekCompositionTimeline(page, time, DENSE_GEOMETRY_SEEK_OPTIONS);
355+
},
351356
collectLayout: (time, tolerance) => collectLayout(page, time, tolerance),
357+
collectOverlap: (time) => collectOverlap(page, time),
352358
collectLayoutGeometry: () => collectLayoutGeometry(page),
353359
collectRotationSample: (time) => collectRotationSample(page, time),
354360
collectOffPivotRotationSample: (time) => collectOffPivotRotationSample(page, time),
@@ -464,6 +470,19 @@ async function collectLayout(
464470
return anchorLayoutIssues(page, raw.flatMap(parseLayoutIssue));
465471
}
466472

473+
async function collectOverlap(page: Page, time: number): Promise<AnchoredLayoutIssue[]> {
474+
const raw = await page.evaluate(
475+
(options: { time: number }) => {
476+
const audit = Reflect.get(window, "__hyperframesOverlapAudit");
477+
if (typeof audit !== "function") return [];
478+
const result = Reflect.apply(audit, window, [options]);
479+
return Array.isArray(result) ? result : [];
480+
},
481+
{ time },
482+
);
483+
return anchorLayoutIssues(page, raw.flatMap(parseLayoutIssue));
484+
}
485+
467486
async function collectLayoutGeometry(page: Page): Promise<string> {
468487
return page.evaluate(() => {
469488
const geometry = Reflect.get(window, "__hyperframesLayoutGeometry");

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

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -417,9 +417,42 @@ async function collectGridSamples(
417417
collected.screenshots.push({ time, pngBase64: capture.pngBase64 });
418418
}
419419
}
420+
await collectMotionOverlapSamples(driver, grid, collected);
420421
return collected;
421422
}
422423

424+
// Dense grid catches mid-motion text collisions the sparse layout grid seeks past; text-only overlap collection is cheap enough to afford it.
425+
const OVERLAP_SAMPLE_FPS = 8;
426+
// Ceiling that bounds dense seeks; past ~75s the grid degrades below 8fps rather than growing the seek budget without limit.
427+
const OVERLAP_MAX_SAMPLES = 600;
428+
429+
function buildOverlapSampleTimes(duration: number): number[] {
430+
if (!Number.isFinite(duration) || duration <= 0) return [];
431+
const count = Math.min(
432+
OVERLAP_MAX_SAMPLES,
433+
Math.max(2, Math.ceil(duration * OVERLAP_SAMPLE_FPS) + 1),
434+
);
435+
const step = duration / (count - 1);
436+
return mergeSampleTimes(
437+
Array.from({ length: count }, (_, index) => Math.round(index * step * 1000) / 1000),
438+
);
439+
}
440+
441+
/** Reruns content_overlap on a fine grid, unconditionally rather than gated on fingerprint change, since an animation aliased to the sparse grid collides between identical-fingerprint samples. */
442+
async function collectMotionOverlapSamples(
443+
driver: CheckAuditDriver,
444+
grid: SampleGrid,
445+
collected: GridSamples,
446+
): Promise<void> {
447+
const baseTimes = new Set(grid.layoutSamples);
448+
for (const time of buildOverlapSampleTimes(grid.duration)) {
449+
if (baseTimes.has(time)) continue;
450+
// Settle-free seek: collectOverlap reads getBoundingClientRect geometry, valid synchronously after setTime, so the dense pass skips the per-seek paint settle.
451+
await driver.seekGeometry(time);
452+
collected.layoutIssues.push(...(await driver.collectOverlap(time)));
453+
}
454+
}
455+
423456
// Frozen-sweep guard (#U10): compositions this short can legitimately hold a
424457
// single static frame the whole time (a title card) — never flag those.
425458
const SWEEP_STATIC_MIN_DURATION_SEC = 3;

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,7 +173,11 @@ export interface CheckAuditDriver {
173173
getCanvas(): Promise<Canvas>;
174174
findAmbiguousSelectors(selectors: string[]): Promise<AnchoredLayoutIssue[]>;
175175
seek(time: number): Promise<void>;
176+
/** Settle-free seek for the geometry-only dense content_overlap pass; only collectOverlap consumes it, and getBoundingClientRect is valid synchronously after setTime. */
177+
seekGeometry(time: number): Promise<void>;
176178
collectLayout(time: number, tolerance: number): Promise<AnchoredLayoutIssue[]>;
179+
/** content_overlap only, for the dense re-sampling grid — catches transient text collisions the sparse grid seeks past. */
180+
collectOverlap(time: number): Promise<AnchoredLayoutIssue[]>;
177181
/** Frozen-sweep guard (#U10): an opaque per-sample geometry+opacity
178182
* fingerprint of the current seeked state, for detecting a timeline that
179183
* never advances under seek. See layout-audit.browser.js. */

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,47 @@ describe("persistence-tiered severity (#U10)", () => {
227227
expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 2 });
228228
});
229229

230+
it("keeps a content_overlap that spans under the 500ms floor as a warning, even with 2 occurrences", () => {
231+
// Two dense-pass occurrences ~125ms apart are under the held-duration floor, so occurrences>=2 alone must not promote to error.
232+
const collapsed = collapseStaticLayoutIssues(
233+
[
234+
{ ...issue("content_overlap", "warning"), time: 4.0 },
235+
{ ...issue("content_overlap", "warning"), time: 4.125 },
236+
],
237+
73,
238+
);
239+
240+
expect(collapsed).toHaveLength(1);
241+
expect(collapsed[0]).toMatchObject({ severity: "warning", occurrences: 2 });
242+
});
243+
244+
it("does NOT promote content_overlap whose two occurrences span exactly 499ms (under the floor)", () => {
245+
// Boundary: a span one millisecond short of the 500ms floor stays a warning — guards the AND-tighten for sparse callers.
246+
const collapsed = collapseStaticLayoutIssues(
247+
[
248+
{ ...issue("content_overlap", "warning"), time: 4.0 },
249+
{ ...issue("content_overlap", "warning"), time: 4.499 },
250+
],
251+
73,
252+
);
253+
254+
expect(collapsed).toHaveLength(1);
255+
expect(collapsed[0]).toMatchObject({ severity: "warning", occurrences: 2 });
256+
});
257+
258+
it("promotes content_overlap whose two occurrences span exactly 500ms (at the floor)", () => {
259+
const collapsed = collapseStaticLayoutIssues(
260+
[
261+
{ ...issue("content_overlap", "warning"), time: 4.0 },
262+
{ ...issue("content_overlap", "warning"), time: 4.5 },
263+
],
264+
73,
265+
);
266+
267+
expect(collapsed).toHaveLength(1);
268+
expect(collapsed[0]).toMatchObject({ severity: "error", occurrences: 2 });
269+
});
270+
230271
it("promotes a held, canvas-scale canvas_overflow breach from info to warning", () => {
231272
const breach = {
232273
...issue("canvas_overflow", "info"),

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

Lines changed: 4 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -181,21 +181,7 @@ export function dedupeLayoutIssues(issues: LayoutIssue[]): LayoutIssue[] {
181181
return result;
182182
}
183183

184-
// Persistence-tier thresholds (#U10, adapted from Adam Rosler's visual-linter
185-
// design). The approach doc frames these as held-duration floors — ignore
186-
// under ~250ms, re-promote content_overlap at >= ~500ms — measured against
187-
// the SAME firstSeen/lastSeen span this collapse step already tracks. At the
188-
// default 9-sample grid over a multi-second composition, a single collapsed
189-
// occurrence is held 0ms (one entrance/exit transient sample) and two
190-
// collapsed occurrences are already >= one sample-to-sample gap, which is
191-
// well past 500ms — so "held under 250ms" reduces to `occurrences <= 1` and
192-
// "held >= 500ms" reduces to `occurrences >= 2`. Tiering below is written in
193-
// those sample-count terms (the mapping the approach doc asks to document),
194-
// with the literal ms span (CONTENT_OVERLAP_HELD_ERROR_MS) kept as a fallback
195-
// for callers whose samples really are spaced close enough together for the
196-
// ms floor to matter on its own (dense `--at`/`--at-transitions` runs). The
197-
// ~250ms ignore floor needs no separate constant — see the occurrences <= 1
198-
// branch below.
184+
// Persistence-tier thresholds (#U10): occurrences>=2 alone can't imply the 500ms floor under dense 8fps sampling, so content_overlap promotion requires a literal firstSeen..lastSeen span >= 500ms — stricter for sparse callers too.
199185
const CONTENT_OVERLAP_HELD_ERROR_MS = 500;
200186
const HELD_ACROSS_SAMPLES_MIN_OCCURRENCES = 2;
201187

@@ -317,11 +303,10 @@ function isCanvasBreachHeldLarge(issue: LayoutIssue, occurrences: number): boole
317303
return overlapX > 0 && overlapY > 0;
318304
}
319305

320-
// Split out of applyPersistenceTier so the two independent "held long enough"
321-
// signals (sample count vs. wall-clock span) read as one boolean question
322-
// instead of adding a third compound branch to the tiering ladder above.
306+
// Split out of applyPersistenceTier so the compound "held long enough" test reads as one boolean question.
323307
function isContentOverlapHeldLongEnough(issue: LayoutIssue, occurrences: number): boolean {
324-
if (occurrences >= HELD_ACROSS_SAMPLES_MIN_OCCURRENCES) return true;
308+
// Two samples measure a span, but under dense 8fps sampling that span must still clear the wall-clock floor.
309+
if (occurrences < HELD_ACROSS_SAMPLES_MIN_OCCURRENCES) return false;
325310
const firstSeen = issue.firstSeen ?? issue.time;
326311
const lastSeen = issue.lastSeen ?? issue.time;
327312
const heldMs = (lastSeen - firstSeen) * 1000;

0 commit comments

Comments
 (0)