test: contract tests and a benchmark harness (no src changes)

[chiefcll]

Why

This is the part of the 1.7 work that does not depend on 1.7: the contract
tests and the CPU benchmark harness written for it, adapted to run on main
(solid 1.6.4 on @solidtv/renderer 1.9). Landing them on main first shrinks
the 1.7 diff to the behaviour and performance changes themselves, and gives
1.7 a baseline: every test here passes (or is skipped with a note) on 1.6.4,
so whatever 1.7 changes shows up as a test it has to update or unskip, and
the benchmark measures 1.7 against the 1.6.4 release on the same scenarios.

What

• Contract tests (tests/contract-*.test.tsx, tests/publicApi.test.ts),
  through the public surface only: key handling and focus, states and styles,
  Row/Column/Grid/VirtualRow/VirtualGrid/Lazy navigation and scrolling, flex
  on both engines (flex.ts and flexLayout.ts), text props on the DOM
  renderer, node behaviour, the runtime export names of every entry point and
  the package.json exports map. +432 tests.
• Type contract (tests/contract-types.tsx): the public types apps augment
  with declare module '@solidtv/solid', and every type-only export name.
  pnpm tsc now runs tsc && tsc -p tests/tsconfig.contract.json, so the
  build, CI and the release (prepack → build) type-check it.
• Known 1.6.4 bugs and gaps are skipped with a BUG: or CONTRACT GAP
  note and the correct behaviour (23 skipped, 1 todo): fixing one means
  unskipping its test.
• Flex with text on the real WebGL renderer (tests/webgl,
  pnpm test:webgl): headless Chromium, renderer 1.9, an SDF font; final
  positions of text in flex containers, where SDF and DOM measurement differ.
• Test hygiene: spatialNavigation disposes its render and useHold.spec
  mocks a fresh module, so files pass in any order in one worker; the jsdom
  and browser configs exclude tests/webgl and bench, and the browser run
  leaves out the contract files that pin the jsdom DOM renderer.
• npm run bench (bench/, methodology in docs/perf/README.md):
  builds a bench app for arm A (the 1.6.4 release on npm renderer 1.9.3)
  and arm C (this working tree on the installed renderer), and measures
  key-press, state-change, node-creation and text-in-flex scenarios in
  headless Chromium under 6x CPU throttling: time per op (handler, microtask
  tail, frame), bytes allocated per op by owner, CPU profile self and
  inclusive time, and counts (flex passes, renderer writes, text layouts,
  loaded events).
• devDependencies: playwright pinned to 1.56.1 (the version
  @vitest/browser-playwright already used), terser, and
  @lightningtv/vite-hex-transform (it brings a second vite, 5.x, into the
  lockfile). Nothing new ships to npm: no runtime dependency, no src/
  change.

How to run

npx vitest run                                   # jsdom suite incl. the contract tests
VITE_USE_NEW_FLEX=true npx vitest run tests/contract-flex.test.tsx   # the JSX part on flexLayout.ts
pnpm tsc                                         # also type-checks tests/contract-types.tsx
npx playwright install chromium                  # once, for the next two
pnpm test:webgl                                  # WebGL flex/text tests
npm run bench -- --scenarios smoke --runs 1 --quick   # harness check
npm run bench                                    # full series: arms A,C, 3 runs, all modes

CI runs build, test and lint only: test:webgl and bench are manual.

Notes

• Arm A uses npm renderer 1.9.3; arm C uses whatever is installed, and the
  lockfile resolves the ^1.9.0 peer to 1.9.0. The two differ in small
  ways (loop pause/resume, the WebGL power preference, an enableClear
  branch). The summary lists each arm's Solid and renderer, and the A/C ratio
  is a noise floor only when they match.
• docs/perf/README.md is not linked from the docs sidebar.
• The Roboto (Apache-2.0) and Lato (OFL-1.1) MSDF atlases are copies of
  solid-demo-app's; each font folder has a README with the license and source.

Size and what to read

76 files, about +34,000 lines, but most of it is data: three MSDF font atlas
JSONs (+17,552 lines; with their PNG pages about 570 KB of fonts), 12 small
placeholder images for the bench (48 KB), and the lockfile (+633). The code to review is the test files
(about +10,700 lines, mostly tables of expected values), bench/ (about
+4,600 lines: run.mjs, harness/*.mjs, vite.config.ts,
prepare-arms.mjs, the scenarios) and docs/perf/README.md. Suggested
order: docs/perf/README.md, then one contract file (contract-keys or
contract-focus), then bench/run.mjs and bench/harness/probe.mjs.

Not included

No src/ change and no bug fix: the BUG: tests stay skipped. No renderer
2.0 code (the bench's renderer 2.x count hooks are kept, labelled, and never
install on 1.x). No benchmark results: summary.md is meant to be committed
with a measured series; raw JSON and profiles are gitignored.

Gates: npx vitest run 654 passed / 23 skipped / 1 todo (also in 3 shuffled
file orders and with VITE_USE_NEW_FLEX=true), pnpm tsc clean, pnpm lint
0 errors, pnpm test:webgl 14/14 on both flex engines.

🤖 Generated with Claude Code