Files
hyperframes/packages/cli/src/utils/checkPipeline.offPivotRotation.test.ts
T
Xuanru Li e710a1686f feat(lint): add off_pivot_rotation hub-referenced layout check (#2744)
## 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)
2026-07-24 17:38:58 -07:00

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);
});
});