feat(keys_highway_3d): key layout modes, lane-color opacity & octave lines

[LegionaryLeader]

Lane Opacity Slider
A new slider that affects the overall opacity of whatever color palette a user has selected
0% means no color, dark gray background for a clean look
100% is full vivid color
The current amount default will be set to 0%
The Opacity Slider is paired with another setting to automatically change its color to match:

The Octave Separator
This checkbox setting allows the user to add a little bit of visual clarity to their game by making the space between Lanes at all octave (B-C) a little wider, allowing your eyes to break the piano up into sections or blocks more easily
The default of this setting will be on

Highway Layouts
There are now 3 layouts available for users depending on how a player wants to see the piano
The original "Floating" - sharps & flats are physically higher than the naturals
"Non-floating" - sharps & flats are placed on the same height plane as the other keys
"Realistic Key Sizes" - Changes the note gems all to be a more realistic size, works best with colors off for the lane background
The default layout will be Realistic Key Sizes

Summary by CodeRabbit

• New Features

  • Added a Highway layout section for 3D Keys, with Sharps & flats modes (floating, flat, realistic) plus controls for lane color opacity, octave gaps, and octave line contrast.
  • Updated lane and note rendering to reflect the selected layout mode.

• Bug Fixes

  • Improved geometry/visual consistency across sharp/shading layouts.
  • Highway-layout settings now persist and apply on the next chart build.

• Documentation / Chores

  • Refreshed settings and help text, and bumped the plugin to v0.2.0.
  • Added coverage for the new layout controls and lane-span behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 5ae0125c-a397-4050-b75a-496ef4c17ed7

📥 Commits

Reviewing files that changed from the base of the PR and between 0e06844 and da5fb81.

📒 Files selected for processing (3)

• CHANGELOG.md
• plugins/keys_highway_3d/screen.js
• plugins/keys_highway_3d/tests/fx_settings.test.js

✅ Files skipped from review due to trivial changes (1)

• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (2)

• plugins/keys_highway_3d/tests/fx_settings.test.js
• plugins/keys_highway_3d/screen.js

---

📝 Walkthrough

Walkthrough

Adds sharp/flat highway layout modes to keys_highway_3d, with persisted sharp-mode selection, new lane opacity and octave controls, updated settings UI and docs, version and changelog updates, and tests covering the new geometry and settings behavior.

Changes

Highway Layout Feature

Layer / File(s)	Summary
Lane span geometry helpers and FX defaults plugins/keys_highway_3d/screen.js	Adds laneSpanFlat() and laneSpanReal() helpers for piano-shaped and physical-key-sized lane tiling, and expands FX_DEFAULTS with octaveGaps, laneOpacity, octaveContrast.
Sharp mode persisted setting and global setter plugins/keys_highway_3d/screen.js	Adds SHARP_MODES, readSharpModeSetting(), and window.keys3dSetSharpMode(id); wires _sharpMode into init() and the keys3d:settings handler.
Lane guide and note mesh rendering for new modes plugins/keys_highway_3d/screen.js	Reworks lane guide rendering with opacity/contrast-driven dividers, updates lane opacity computation, and adds flat/realistic note bar placement with sharp lift.
Test exports for new geometry helpers plugins/keys_highway_3d/screen.js	Extends __test export surface with the new sharp-mode and lane-span helpers.
Settings UI for highway layout controls plugins/keys_highway_3d/settings.html	Adds a "Highway layout" section with a sharp mode selector and lane opacity/octave controls, plus localStorage hydration and wording fixes.
Unit tests for FX defaults, persistence, and lane geometry plugins/keys_highway_3d/tests/fx_settings.test.js	Adds tests for FX defaults, keys3dSetFx persistence/clamping, sharpMode persistence, and laneSpanFlat/laneSpanReal geometry behavior.
Documentation, changelog, and version bump plugins/keys_highway_3d/README.md, CHANGELOG.md, plugins/keys_highway_3d/plugin.json	Adds highway-layout documentation, a changelog entry, and bumps plugin version from 0.1.2 to 0.2.0.
Non-functional comment/spelling cleanup plugins/keys_highway_3d/screen.js	Normalizes "colours" to "colors" in comments with no functional impact.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant SettingsUI
  participant window.keys3dSetSharpMode
  participant localStorage
  participant ScreenInstance

  SettingsUI->>window.keys3dSetSharpMode: select mode
  window.keys3dSetSharpMode->>localStorage: persist keys3d_bg_sharpMode
  window.keys3dSetSharpMode->>ScreenInstance: dispatch keys3d:settings
  ScreenInstance->>ScreenInstance: update _sharpMode

Loading

sequenceDiagram
  participant ScreenInstance
  participant buildKeyboardAndHighway
  participant buildNoteMeshes
  participant laneSpanFor

  ScreenInstance->>buildKeyboardAndHighway: build lane guides
  buildKeyboardAndHighway->>laneSpanFor: resolve lane geometry
  ScreenInstance->>buildNoteMeshes: build note bars
  buildNoteMeshes->>laneSpanFor: place notes by sharp mode

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main 3D highway layout and lane styling changes in the PR.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugins/keys_highway_3d/screen.js`:
- Around line 1318-1331: Update the sharp-mode default description in
readSharpModeSetting() to match the actual fallback value. The comment near
FX_LS_SHARPMODE and SHARP_MODES still says 'floating' is the default, but the
function returns 'realistic' when no setting is stored. Keep the documentation
and return value consistent by revising the stale comment text around
readSharpModeSetting().

In `@plugins/keys_highway_3d/settings.html`:
- Around line 308-310: Update the stale inline comment near hydrateFxBool in
settings.html so it matches the actual octaveGaps default state used by Keys
Highway 3D. The comment currently says octaveGaps defaults OFF, but the relevant
symbols FX_DEFAULTS.octaveGaps in screen.js and the keysh3d-fx-octavegaps
checkbox are both initialized as ON/checked by default. Keep the hydration call
unchanged and only correct the comment wording to avoid misleading maintainers.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 30f87574-e273-4b28-a8de-6245ef321cbc

📥 Commits

Reviewing files that changed from the base of the PR and between cb72c5a and 0e4b8b5.

📒 Files selected for processing (5)

• plugins/keys_highway_3d/README.md
• plugins/keys_highway_3d/plugin.json
• plugins/keys_highway_3d/screen.js
• plugins/keys_highway_3d/settings.html
• plugins/keys_highway_3d/tests/fx_settings.test.js