Rate UI: track clubhead camera and add canonical 3D snap views

[d-sorgcodexagent]

Parent: #4218

Problem

During 3D swing/impact playback the moving clubhead can leave the useful camera focus after the user zooms. The animation also lacks deterministic camera presets for the standard golf-analysis views, making comparisons and online demonstrations harder than they should be.

Scope

Implement one shared camera-command contract and matched PyQt6/React adapters for every 3D swing and impact animation. Do not duplicate camera convention logic inside individual plots.

Acceptance criteria

• Add an explicit Track Clubhead control. While enabled, camera target/focus follows the clubhead using bounded, stable updates so the entire representative head remains visible without jitter or runaway rescaling.
• Preserve the user's zoom distance while tracking whenever possible; apply a documented minimum clearance and an opt-in Auto Fit fallback if the head would be clipped.
• Manual pan/orbit temporarily suspends tracking or updates the tracking offset predictably; the control clearly shows the active state and can re-center in one action.
• Add discoverable Face On, Down the Line, and Overhead snap-view buttons plus Reset/Auto Fit. Each command has one stable ID, tooltip, focus state, and keyboard-accessible action.
• Define all presets in the canonical target frame x=downrange, y=up, z=right: Down the Line looks from behind along +x, Overhead looks along -y, and Face On uses a documented lateral-side default with a deliberate handedness/side option rather than an implicit sign.
• Snap views preserve a useful subject target, scale, near/far clipping planes, and vertical axis. Repeated activation is idempotent and does not accumulate camera drift.
• Camera state is isolated per viewport so Impact, Swing, and multi-view layouts do not overwrite one another.
• Playback, pause, replay-from-end, loop, frame-step, granular speed, wheel zoom, and snap commands work in every combination without losing the clubhead or leaving controls stale.
• PyQt6 headless interaction tests and React component/Playwright tests cover command parity, focus tracking over the complete animation, manual override, resize/high-DPI behavior, and all three exact camera orientations.
• Rendered computer-control review is recorded at desktop and constrained window sizes; no clubhead clipping, camera jump, control collision, or inaccessible tooltip remains.
• User documentation, parity registry, and durable handoff files are updated in the same implementation commits.

Engineering constraints

Use RED-GREEN-REFACTOR TDD, a UI-neutral camera command/state contract, Design by Contract for finite camera vectors and valid frames, DRY adapters, and Law of Demeter boundaries. Do not infer a view convention from the current arbitrary camera pose.

[linear]

D-7667

[d-sorgcodexagent]

Implementation checkpoint: draft PR #4298 is now published at exact head 2095e748ddca2d7036bbd49a731528f5634daff9.

Current evidenced scope:

• shared Python/TypeScript camera state and canonical isometric, face-on (explicit side), down-the-line, and overhead views;
• bounded opt-in subject tracking with preserved zoom, manual-orbit suspension, Auto Fit, and Recenter;
• Tools PyQt Simulation/Flight and React Club/Impact/Flight adapters;
• accessible camera controls and deterministic previous/next frame stepping;
• 138 focused Python tests from the core slice, 39 focused Python/PyQt tests on the follow-up, full React 107 files / 650 tests, and 4 Playwright checks across desktop plus 520 x 900 at 2x DPR;
• TypeScript, zero-warning ESLint, Vite production build, Ruff/format, targeted mypy, manifest validation, and diff checks pass locally.

The issue remains open. Required remaining gates are protected current-head CI, independent review, native-font/manual visual QA, and UpstreamDrift consumer parity against an immutable protected Tools pin. Camera preference persistence remains tracked by parent workspace epic #4218; it is not being claimed by this slice.

[d-sorgcodexagent]

Exact repaired-stack propagation is now published on draft PR #4298 at a51e49e. The normal merge preserves original camera child 9ffd8d2 first and exact repaired #4288 parent 108a841 second; the PR base remains feat/4199-wind-workflow. Full composed Python/React/Rust/static/governance gates and four Playwright camera cases pass locally, and independent exact-tree review found no findings. Protected exact-head CI, required review, native rendered QA, preference persistence, UpstreamDrift parity, parent landing, and issue acceptance remain open; this does not close #4284 or #4218.

[d-sorgcodexagent]

Published the independently reviewed hosted-delta typing repair on draft PR #4298 at exact head 57942e64744a199e4fd7d604fe2eeb9faddd062a by a normal fast-forward push. The exact pinned MyPy 1.13 profile now passes all 33 changed production files, alongside 79 focused runtime tests and Ruff/format. Runtime values, canonical wire bytes, transforms, physics, and camera behavior are unchanged. Fresh protected current-head CI is now required; the obsolete failed job on a51e49e4d2e7f5b1985c802f8290ea7649e7927e will not be retried. This does not complete #4284 or #4218.

[d-sorgcodexagent]

Parent propagation repair is now published on draft PR #4298 at exact head 104503aac9779b195d46d38e8ed32611ffc8dfd7.

The existing camera child normally incorporates current base head 1e82f15026786ea0b08f78f4c001590ddce9ff39; camera production/test code did not conflict, and only four additive current-state handoff/spec files required reconciliation. No rebase, retarget, force-push, parent rewrite, or history rewrite was used.

Exact composed-tree evidence is green: 272 focused Python/PyQt tests, 110 React files / 670 tests, TypeScript, zero-warning ESLint, Vite production build, 26 Rust transfer/wire tests, pinned MyPy 1.13 across all 33 changed production files, Ruff, module-size, changed-Python policy, and whitespace checks. Fresh protected exact-head CI and review remain required. Native rendered/font QA, camera preference persistence, and immutable-pin UpstreamDrift parity remain open, so this does not close #4284 or #4218.

[d-sorgcodexagent]

Native camera QA continuation is published as draft PR #4331 at exact head ceb9b7d498df4a9a66ad339c5e29066b550f5e46, stacked normally on exact #4330 head d8176bb5863a35725199bb8357a5f000f9bdd3ba.

Windows-control inspection first verified Face On, Down the Line, Overhead, Reset, Track Clubhead, Auto Fit, Re-center, replay-from-end, pause, and loop behavior. It then caught a rendered-only Axes3D defect that state assertions missed: cached depth-axis labels/ticks remained visible even when the axis container reported hidden. The continuation now suppresses the depth axis container, label, line, pane, and tick artists, and restores a single-sided full frame for isometric/manual orbit in both Simulation and Flight.

Evidence: 11 focused camera tests; 33 camera/layout/workspace integration tests; Ruff/format; pinned MyPy 1.13 on the three changed production modules; and final native inspection at 1282 x 752 across all three snap views with no collapsed or duplicate depth labels. Physics, limits, tracking, zoom, camera angles, and React behavior are unchanged.

This remains partial: protected exact-head CI, review, dependency-ordered landing, broader camera preference persistence, and immutable UpstreamDrift parity remain open. Do not close #4284 yet.

[d-sorgcodexagent]

Camera prerequisite repair checkpoint:

• Draft PR fix(rate-of-closure): declutter orthographic camera axes #4331 is published at exact head e07e2a66a894c93b50c1ded308fc8902f2ff6c24, preserving child-first camera-polish history and current feat(rate): complete multi-view keyboard and workspace contracts #4330 parent 304a069b1777dcf8cf107de26caa3b9fbe96dbb3. The root SPEC is now truthfully updated to 1.14.30, so the exact Spec Check passes without an exemption label.
• Sibling draft PR fix(rate-ui): keep moving subjects framed by default #4303 is published at exact head 98cf35994488dd6f3d66916415bbc9f8e7c8bf3f, preserving its camera-default child and current fix(rate UI): keep toolstrip menus inside constrained viewports #4301 parent c653f9ff9193d6cdb8e11a13ad0001707e468a42. Its effective delta is again limited to the intended 17 camera/default-framing files.

Both candidates passed independent exact-head review and substantial PyQt6, React, Playwright, static, build, documentation, manifest, and diff gates before normal fast-forward pushes. Both are now mergeable drafts with fresh protected checks queued and no review decision. No rebase, retarget, force-push, parent rewrite, or CI retry was used.

This repairs prerequisites for the still-unimplemented versioned per-viewport camera-preference persistence slice. #4284/#4218 remain open for that persistence work, protected CI/review, dependency landing, immutable UpstreamDrift parity, and release.

[d-sorgcodexagent]

Camera preference persistence checkpoint: draft PR #4349 is published at exact head 3f4bb18526fc23390b4e03deb78b04804a6fc805, based on exact #4343 head 4ff103d9a6ef886099c180da560e8458d5e20b49 and normally composing exact #4331 e07e2a66a894c93b50c1ded308fc8902f2ff6c24 then #4303 98cf35994488dd6f3d66916415bbc9f8e7c8bf3f.

The independently reviewed implementation head f2d3be771a9ba1d17f5e8942484b3fb49c236527 delivers strict cross-runtime camera-preferences/v1, view-workspace v2 with deterministic v1 migration, QSettings/localStorage/File Save/Open persistence, and app-owned isolated preferences across Impact, Swing, and Flight adapters. It persists preset, explicit Face On side, bounded zoom, Track Clubhead, and Auto Fit; moving target, manual orientation/suspension, and per-frame updates remain transient.

Focused Python/PyQt, React, TypeScript, ESLint, build, Ruff, MyPy, manifest, docs, size, and diff evidence is green, and independent repaired-head review approved draft publication. Fresh protected CI/review, dependency landing, rendered Playwright/native qualification, immutable UpstreamDrift consumers, and final issue acceptance remain open. This does not close #4218 or #4284.