mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
## What it catches A gauge needle / clock hand / dial pointer / radar sweep that rotates about the **wrong pivot** — the recovered center-of-rotation sits far from the dial hub (e.g. `transform-origin` at the needle base or SVG element edge instead of the dial center). Visually the needle "wobbles" or orbits off-axis instead of sweeping cleanly about the hub. This is a genuine gap in the current checks: `rotation_pivot_drift` (#2741) provably **cannot** catch it — a correct sweeping needle's bbox-center orbits identically to a broken one, so only a **dial-hub reference** distinguishes them. This is the separate hub-referenced check that analysis called for. ## How it works - Sampler maps 2 material endpoints per frame via `getScreenCTM` (honors the actual rendered transform, independent of `svgOrigin`). - Resolves the dial hub = shared center of the modal set of static concentric circles, or the arc-center of the largest static near-circular path (Kasa circle fit). - Fits a circle to the endpoint trajectory to recover the true center-of-rotation; flags drift `> 0.35 * pointer_length`. One warning per hub. - Never fires without a resolvable hub. Walks the rotation reference to the composition root (not the `<svg>`) so a pointer rotated by a `div` ancestor is measured correctly. - Multi-body guard: `>= 2` bodies at distinct angular positions on one hub = orbit/atom system, not a dial → suppressed. ## Corpus evidence (autonomous geometry-fuzz run, 81 fuzzed diagrams) - **7 / 7 true positives, 0 false positives across all 81 samples.** - Assigned TPs: fuzz005, fuzz017, fuzz032. Bonus TPs: fuzz044, fuzz056, fuzz068, fuzz080. - **The Gemini-3.6 video-judge itself MISSED all 4 bonus TPs** (`vlm_has_defects: false`) — the deterministic hub-reference check beats the VLM on this defect class. - FPs driven to 0 by the two principled guards above: fuzz016 (planet arc rotated by a `div` ancestor) cleared by root-walk; fuzz055 (atom) cleared by the multi-body guard. - fuzz080 reads as a false positive to the connector check but is a true positive here — confirms the architectural boundary between the two checks is drawn correctly. ## Validation - Autonomous Gemini-3.6 **video**-judge fuzz run to surface candidate defects, then a **deterministic FP sweep** across all 81 rendered compositions (not VLM-gated — code inspection is the arbiter, since the VLM both over- and under-calls this class). - 9 unit tests (`checkPipeline.offPivotRotation.test.ts`) + full check suite pass; `bun run build` green. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
253 lines
9.3 KiB
TypeScript
253 lines
9.3 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
|
|
import { countAngularBodies, detectOffPivotRotation } from "./checkPipeline.js";
|
|
import type { OffPivotFrame, OffPivotRotationSample } from "./checkTypes.js";
|
|
|
|
/** A sample carrying its frame time, for test ergonomics; {@link toFrames}
|
|
* re-hoists the time into the on-the-wire {@link OffPivotFrame} envelope. */
|
|
type TimedSample = OffPivotRotationSample & { time: number };
|
|
|
|
/** One needle sample; defaults describe a sizable pointer on a hub at (500,500). */
|
|
function sample(overrides: Partial<TimedSample> = {}): TimedSample {
|
|
return {
|
|
time: 0,
|
|
selector: "#needle",
|
|
ax: 0,
|
|
ay: 0,
|
|
bx: 0,
|
|
by: 0,
|
|
len: 200,
|
|
angle: 0,
|
|
hx: 500,
|
|
hy: 500,
|
|
hr: 220,
|
|
hubCount: 3,
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
/** Merge per-selector timed samples into the time-hoisted frame envelope the
|
|
* detector consumes (all samples sharing a time land in one frame). */
|
|
function toFrames(...groups: TimedSample[][]): OffPivotFrame[] {
|
|
const byTime = new Map<number, OffPivotRotationSample[]>();
|
|
for (const { time, ...rest } of groups.flat()) {
|
|
const frame = byTime.get(time);
|
|
if (frame) frame.push(rest);
|
|
else byTime.set(time, [rest]);
|
|
}
|
|
return [...byTime.entries()]
|
|
.sort(([a], [b]) => a - b)
|
|
.map(([time, samples]) => ({ time, samples }));
|
|
}
|
|
|
|
interface SweepOptions {
|
|
/** Center the endpoints actually orbit (the recovered center-of-rotation). */
|
|
cx: number;
|
|
cy: number;
|
|
/** Screen hub the check compares the recovered center against. */
|
|
hx?: number;
|
|
hy?: number;
|
|
selector?: string;
|
|
frames?: number;
|
|
spreadDeg?: number;
|
|
/** Outer/inner material-point radii; both share one angle so the pointer is
|
|
* rigid (constant separation |a-b| = rOuter - rInner). */
|
|
rOuter?: number;
|
|
rInner?: number;
|
|
/** Per-frame inner-radius growth — breaks rigidity (endpoint deformation). */
|
|
innerGrowth?: number;
|
|
hubCount?: number;
|
|
}
|
|
|
|
/** A rigid pointer swept about `(cx,cy)`: two material points on one radial line
|
|
* orbit that center, so their separation is constant (rigid body). */
|
|
function sweep(options: SweepOptions): TimedSample[] {
|
|
const {
|
|
cx,
|
|
cy,
|
|
hx = 500,
|
|
hy = 500,
|
|
selector = "#needle",
|
|
frames = 6,
|
|
spreadDeg = 180,
|
|
rOuter = 100,
|
|
rInner = 40,
|
|
innerGrowth = 0,
|
|
hubCount = 3,
|
|
} = options;
|
|
return Array.from({ length: frames }, (_, i) => {
|
|
const deg = frames <= 1 ? 0 : (spreadDeg * i) / (frames - 1);
|
|
const rad = (deg * Math.PI) / 180;
|
|
const inner = rInner + innerGrowth * i;
|
|
const ax = cx + rOuter * Math.cos(rad);
|
|
const ay = cy + rOuter * Math.sin(rad);
|
|
const bx = cx + inner * Math.cos(rad);
|
|
const by = cy + inner * Math.sin(rad);
|
|
return sample({
|
|
selector,
|
|
time: i,
|
|
angle: deg,
|
|
ax,
|
|
ay,
|
|
bx,
|
|
by,
|
|
len: Math.hypot(ax - bx, ay - by),
|
|
hx,
|
|
hy,
|
|
hubCount,
|
|
});
|
|
});
|
|
}
|
|
|
|
describe("detectOffPivotRotation", () => {
|
|
it("fires when the recovered center-of-rotation is far from the dial hub", () => {
|
|
// Rigid pointer orbits (500,300) — 200px above the hub at (500,500).
|
|
const findings = detectOffPivotRotation(toFrames(sweep({ cx: 500, cy: 300 })));
|
|
expect(findings).toHaveLength(1);
|
|
const [f] = findings;
|
|
expect(f?.code).toBe("off_pivot_rotation");
|
|
expect(f?.severity).toBe("warning");
|
|
expect(f?.selector).toBe("#needle");
|
|
expect(f?.message).toContain("200px");
|
|
expect(f?.fixHint).toContain("hub");
|
|
});
|
|
|
|
it("does not fire on a correctly-hubbed needle (center-of-rotation on the hub)", () => {
|
|
expect(detectOffPivotRotation(toFrames(sweep({ cx: 500, cy: 500 })))).toHaveLength(0);
|
|
});
|
|
|
|
it("does not fire with fewer than the minimum (overdetermined) samples", () => {
|
|
// Blocker-1 core: any 3 non-collinear points fit a circle with ~0 residual,
|
|
// so a 3-sample "clean circle" guard is vacuous. Below 5 samples we refuse.
|
|
expect(detectOffPivotRotation(toFrames(sweep({ cx: 500, cy: 300, frames: 4 })))).toHaveLength(
|
|
0,
|
|
);
|
|
expect(detectOffPivotRotation(toFrames(sweep({ cx: 500, cy: 300, frames: 5 })))).toHaveLength(
|
|
1,
|
|
);
|
|
});
|
|
|
|
it("does not fire on arbitrary 3-point endpoint deformation (the reviewer repro)", () => {
|
|
// Three arbitrary non-collinear endpoint positions: geometrically they fit a
|
|
// circle exactly, but there are too few samples to be an overdetermined fit.
|
|
const group = [
|
|
sample({ time: 0, angle: 0, ax: 600, ay: 300, bx: 540, by: 300 }),
|
|
sample({ time: 1, angle: 90, ax: 505, ay: 402, bx: 500, by: 341 }),
|
|
sample({ time: 2, angle: 180, ax: 402, ay: 305, bx: 461, by: 299 }),
|
|
];
|
|
expect(detectOffPivotRotation(toFrames(group))).toHaveLength(0);
|
|
});
|
|
|
|
it("does not fire when the tracked points deform (non-rigid) even with >=5 samples", () => {
|
|
// Endpoint A traces a clean wide circle about (500,300) — a naive fit would
|
|
// recover a 200px-off center and flag it — but the inner point drifts outward
|
|
// each frame, so the figure is deforming, not rotating rigidly.
|
|
const group = sweep({ cx: 500, cy: 300, frames: 6, innerGrowth: 8 });
|
|
expect(detectOffPivotRotation(toFrames(group))).toHaveLength(0);
|
|
});
|
|
|
|
it("does not fire when the >=5-sample trajectory is not a clean circle (high residual)", () => {
|
|
// Rigid separation (len constant) but the points jitter along a rough path,
|
|
// not one circle — the overdetermined RMS-residual guard rejects it.
|
|
const scatter = [
|
|
[600, 300],
|
|
[520, 420],
|
|
[470, 260],
|
|
[610, 350],
|
|
[430, 400],
|
|
[560, 250],
|
|
];
|
|
const group = scatter.map(([ax, ay], i) =>
|
|
sample({
|
|
time: i,
|
|
angle: i * 40,
|
|
ax: ax ?? 0,
|
|
ay: ay ?? 0,
|
|
bx: (ax ?? 0) - 60,
|
|
by: ay ?? 0,
|
|
len: 60,
|
|
}),
|
|
);
|
|
expect(detectOffPivotRotation(toFrames(group))).toHaveLength(0);
|
|
});
|
|
|
|
it("does not fire when the pointer barely sweeps (fixed tilt)", () => {
|
|
expect(
|
|
detectOffPivotRotation(toFrames(sweep({ cx: 500, cy: 300, spreadDeg: 10 }))),
|
|
).toHaveLength(0);
|
|
});
|
|
|
|
it("does not fire when no dial hub is resolvable", () => {
|
|
const group = sweep({ cx: 500, cy: 300 }).map((s) => ({
|
|
...s,
|
|
hx: null,
|
|
hy: null,
|
|
hubCount: 0,
|
|
}));
|
|
expect(detectOffPivotRotation(toFrames(group))).toHaveLength(0);
|
|
});
|
|
|
|
it("does not fire when the hub has too few concentric circles", () => {
|
|
const group = sweep({ cx: 500, cy: 300 }).map((s) => ({ ...s, hubCount: 1 }));
|
|
expect(detectOffPivotRotation(toFrames(group))).toHaveLength(0);
|
|
});
|
|
|
|
it("requires the hub to be present for a sustained majority, not just the last frame", () => {
|
|
// Hub resolves only on the final frame; every earlier frame lacks it. A
|
|
// single-frame hub is not a reliable anchor — suppression is structural.
|
|
const group = sweep({ cx: 500, cy: 300 }).map((s, i, all) =>
|
|
i === all.length - 1 ? s : { ...s, hx: null, hy: null, hubCount: 0 },
|
|
);
|
|
expect(detectOffPivotRotation(toFrames(group))).toHaveLength(0);
|
|
});
|
|
|
|
it("collapses nested candidates on the same hub to a single finding", () => {
|
|
const group = sweep({ cx: 500, cy: 300 });
|
|
const child = sweep({ cx: 500, cy: 300, selector: "#needle > path:nth-of-type(1)" });
|
|
const findings = detectOffPivotRotation(toFrames(group, child));
|
|
expect(findings).toHaveLength(1);
|
|
expect(findings[0]?.selector).toBe("#needle");
|
|
});
|
|
|
|
it("suppresses multiple distinct bodies orbiting one hub (orbit/atom system)", () => {
|
|
// Two rigid bodies at DIFFERENT angular positions about the same hub — an
|
|
// orbit/radial system, not a single dial pointer.
|
|
const bodyA = sweep({ cx: 700, cy: 500, selector: "#electron-a" });
|
|
const bodyB = sweep({ cx: 300, cy: 500, selector: "#electron-b" });
|
|
expect(detectOffPivotRotation(toFrames(bodyA, bodyB))).toHaveLength(0);
|
|
});
|
|
|
|
it("flags one off-pivot hand on a multi-hand clock whose sibling hands are correctly hubbed", () => {
|
|
// Analog clock: three hands on one hub at (500,500). Two are correctly
|
|
// hubbed (center-of-rotation on the hub → not eligible findings); one is
|
|
// off-pivot (orbits (500,300), 200px above the hub). The multi-body
|
|
// suppression must count only ELIGIBLE candidates — the two hubbed hands
|
|
// are not orbiting bodies, so the lone off-pivot hand is NOT suppressed.
|
|
const offPivot = sweep({ cx: 500, cy: 300, selector: "#hand-second" });
|
|
const hubbedA = sweep({ cx: 500, cy: 500, selector: "#hand-hour" });
|
|
const hubbedB = sweep({ cx: 500, cy: 500, selector: "#hand-minute" });
|
|
const findings = detectOffPivotRotation(toFrames(offPivot, hubbedA, hubbedB));
|
|
expect(findings).toHaveLength(1);
|
|
expect(findings[0]?.selector).toBe("#hand-second");
|
|
});
|
|
|
|
it("returns nothing for an empty sample set", () => {
|
|
expect(detectOffPivotRotation([])).toHaveLength(0);
|
|
});
|
|
});
|
|
|
|
describe("countAngularBodies (multi-body / orbit-atom suppression guard)", () => {
|
|
it("collapses tightly-clustered angles to a single body", () => {
|
|
expect(countAngularBodies([10, 12, 13, -8])).toBe(1);
|
|
});
|
|
|
|
it("counts well-separated angular positions as distinct bodies", () => {
|
|
expect(countAngularBodies([0, 90, 180])).toBe(3);
|
|
});
|
|
|
|
it("wraps around 360 so 350 and 5 are the same body", () => {
|
|
expect(countAngularBodies([350, 5])).toBe(1);
|
|
expect(countAngularBodies([])).toBe(0);
|
|
});
|
|
});
|