feat(highway_3d): extend the camera bridge for touch controls

[saleemk]

What

Extend the existing opt-in 3D Highway camera bridge with:

• positive projectionZoom control using PerspectiveCamera.zoom
• normalized viewOffsetX and viewOffsetY
• focal board anchoring for pinch gestures
• caller-owned anchor correction readout
• per-panel bridge ownership under splitscreen
• complete projection, view-offset, and anchor cleanup

This allows touch camera consumers to provide image-style pinch zoom and pan without replacing the renderer's existing auto-framing or camera ownership.

When the resolved bridge is absent or disabled, stock framing remains in control. Existing pose fields and Camera Director behavior remain compatible.

feedpak surface

• This PR does not change how the app reads/writes feedpaks (manifest keys, pack files, folder layout)
• This PR changes the feedpak surface, with the specification change landing first through the FEP process

Testing

Automated:

• node --check plugins/highway_3d/screen.js
• node --test tests/js/highway_3d_wide_fov.test.js
• node --test tests/js/*.test.js
• Focused tests: 36 passed
• Full JavaScript suite: 1139 passed

Manual:

• phone portrait and landscape
• tablet portrait and landscape
• pinch zoom and focal retention
• two-finger pan
• reset view
• orientation transitions
• renderer cleanup and re-entry
• stock behavior with the bridge inactive

Checklist

• CHANGELOG.md [Unreleased] updated
• Tests added/updated for new behaviour
• Commits are DCO signed off (git commit -s)

Summary by CodeRabbit

• New Features

  • Added an opt-in Free Camera bridge for advanced 3D camera controls, including orbit, height, zoom, tilt, and pan.
  • Added projection zoom and view-offset support for more precise camera framing.
  • Added board-anchor controls and readouts to help maintain object positioning during camera movement.
  • Added support for global or per-panel camera bridge configurations.

• Bug Fixes

  • Improved camera state restoration after resizing, capture, or context changes.
  • Added safeguards to prevent invalid camera values from disrupting rendering.

[coderabbitai]

📝 Walkthrough

Walkthrough

The free-camera bridge gains projection zoom, normalized view offsets, board-anchor retention, and readouts. Camera lifecycle paths reset the new state, while source-based tests cover projection updates, caching, tilt behavior, anchor safety, ownership, and cleanup.

Changes

Free-camera bridge integration

Layer / File(s)	Summary
Bridge contract and camera setup plugins/highway_3d/FREECAM_BRIDGE.md, plugins/highway_3d/screen.js	The bridge documentation and per-panel camera setup now cover projection zoom, view offsets, board anchors, readouts, safe defaults, and panel-specific resolution.
Projection and board-anchor state plugins/highway_3d/screen.js	Projection helpers, cached view offsets, board-anchor capture and retention, safe readout publishing, and lifecycle resets are implemented.
Free-camera behavior validation tests/js/highway_3d_wide_fov.test.js	Tests validate bridge resolution, projection updates, offset caching, tilt behavior, anchor safety, readouts, ownership, retention, and teardown cleanup.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• got-feedBack/feedBack#823: Establishes the per-panel Free Cam bridge resolver used by this camera integration.

Suggested reviewers: topkoa, byrongamatos

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: extending the highway_3d camera bridge for touch controls.
Description check	✅ Passed	The description covers the required What, feedpak surface, and checklist sections, with testing details added; it is mostly complete.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}