chore: add FreeRange range-analysis check

[thymikee]

What changed

• Add @chenglou/freerange as a development dependency and expose pnpm check:freerange.
• Run FreeRange in a dedicated GitHub Actions job.
• Resolve existing range-analysis findings in gesture clamping, Android recording-size scaling, and screenshot-diff overlays.

Why

FreeRange adds static numeric-range checks alongside TypeScript, catching unsafe non-finite arithmetic and invalid numeric inputs before merge.

Developer impact

Run pnpm check:freerange locally. The full project check takes roughly 70–75 seconds on a local development machine.

Validation

• pnpm format:check
• pnpm typecheck
• pnpm lint
• pnpm check:freerange (0 findings)
• pnpm exec vitest run src/contracts/scroll-gesture.test.ts
• pnpm check:tooling
• pnpm check:fallow --base origin/main

The broad unit suite's remaining runtime-hints failures reproduce only under parallel load; its test file passes in isolation.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-21 09:49 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.8 MB	1.8 MB	-738 B
JS gzip	574.5 kB	574.3 kB	-279 B
npm tarball	688.9 kB	688.7 kB	-200 B
npm unpacked	2.4 MB	2.4 MB	-272 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	22.1 ms	22.2 ms	+0.1 ms
CLI --help	46.6 ms	46.5 ms	-0.0 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli-help.js	-2.1 kB	-906 B
dist/src/registry.js	+1.0 kB	+524 B
dist/src/runtime.js	+187 B	+64 B
dist/src/tv-remote.js	+100 B	+25 B
dist/src/internal/daemon.js	+59 B	+14 B

[thymikee]

Two blockers before readiness:

1. The new FreeRange job cannot execute. The shared setup installs Node/pnpm, while the fr launcher execs bun; CI fails with bun: not found before any range analysis runs. Add a pinned Bun setup (or a supported runtime/invocation) and rerun the new gate.

2. Do not widen internal numeric contracts to number | undefined merely to satisfy the analyzer. GesturePoint coordinates and generated ScreenshotDiffRegion rect fields are guaranteed numbers; accepting undefined and silently mapping it to the lower bound weakens TypeScript’s ability to catch an invalid future caller and invents fallback behavior outside a trust boundary. Keep these parameters typed as number and guard the potentially non-finite arithmetic result locally (for example right/bottom or overflowed coordinates). Remove the missing-coordinate test unless a real producer can supply that state.

The PR is conflict-free and all other checks are green, but ready-for-human stays off while these code/CI findings remain.

[thymikee]

Re-review of b7bf068: the SHA-pinned Bun setup resolves the CI-launch blocker, and the FreeRange rerun now reaches the analysis step. The remaining type-contract finding is unchanged because this delta only modifies the workflow; the analyzer-driven number | undefined widening and missing-coordinate fallback/test are still present. No new regression in this commit. The PR is conflict-free, with FreeRange, Coverage, and several smoke jobs still running; ready-for-human remains off pending the code-contract correction.

[thymikee]

Re-review of 26ba5ed is clean. The numeric contracts are precise again, finite guards now sit at computed values rather than widening internal inputs, and the artificial undefined case is removed. The SHA-pinned Bun setup works and all 25 checks pass, including FreeRange with zero findings. The PR is non-draft, conflict-free, and ready for human review. Residual limitation: FreeRange fully analyzes 584/7,975 functions (312 partial; 7,079 unsupported), so this is a useful incremental gate rather than complete numeric proof.