editor: upgrade snap grid and timeline jumps

[ChrisBeWithYou]

Summary

• expand the editor snap model with straight and triplet-friendly grid divisions
• split snap enabled state from grid division and expose it in the toolbar
• add timeline jump shortcuts for beats, notes, grid lines, and anchors

Testing

• node tests/snap_navigation.test.js
• node --check screen.js

Scope

• no loop-region changes
• no tempo-map UI rework beyond the shared navigation foundation

Summary by CodeRabbit

• New Features
  • Added snap enable/disable controls and a refreshed snap dropdown in the editor.
  • Extended timeline keyboard navigation with faster cursor jumping (beat, note, grid, and anchor modes).
  • Updated status-bar help text to reflect the new shortcuts.
• Bug Fixes
  • Snap preferences now reliably persist between sessions and stay synchronized with the editor UI/state.
• Tests
  • Expanded automated tests for snapping/spacing behavior, cursor jump regression, and navigation edge cases.

[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: a2439687-8afc-46ad-8105-d5b50845dd87

📥 Commits

Reviewing files that changed from the base of the PR and between 941e309 and 7800721.

📒 Files selected for processing (2)

• screen.js
• tests/snap_navigation.test.js

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

• screen.js

---

📝 Walkthrough

Walkthrough

This PR reworks the editor snap system and timeline navigation, adds snap preference persistence and UI wiring, updates keyboard shortcuts/help text, and expands coverage for the pure snap-navigation helpers.

Changes

Snap and Navigation Feature

Layer / File(s)	Summary
Snap options and pure navigation helpers screen.js	Defines SNAP_OPTIONS, pure next-time helpers for beat/grid snapping, and the updated snap state defaults.
Cursor jump and timeline navigation wiring screen.js	Adds cursor/scroll helpers, anchor and note time lookups, and keyboard routing for PageUp/PageDown and Arrow navigation.
Snap UI wiring, persistence, and exported controls screen.js, screen.html	Populates the snap dropdown, persists snap prefs, restores them on init, adds editorToggleSnap, and updates the snap UI markup and help text.
Snap navigation test suite tests/snap_navigation.test.js	Loads the pure snap-nav block and checks snap options plus beat/grid/list navigation behavior.

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

🚥 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 changes to snap grid behavior and timeline jump navigation.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch editor-snap-navigation

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (2)

screen.html (1)

116-116: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Status hint omits the Arrow-key equivalents.

Per the downstream onKeyDown handler, ArrowLeft/ArrowRight trigger the same navigation modes as PageUp/PageDown, but this help text only mentions PgUp/PgDn.

♻️ Suggested wording tweak

-        <span class="text-xs text-gray-600">Scroll: pan | Ctrl+scroll: zoom | PgUp/PgDn: beats | Shift+PgUp/PgDn: notes | Ctrl+Shift+PgUp/PgDn: grid | Alt+PgUp/PgDn: anchors</span>
+        <span class="text-xs text-gray-600">Scroll: pan | Ctrl+scroll: zoom | PgUp/PgDn or ←/→: beats | Shift+PgUp/PgDn: notes | Ctrl+Shift+PgUp/PgDn: grid | Alt+PgUp/PgDn: anchors</span>

🤖 Prompt for 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.

In `@screen.html` at line 116, The status hint text in screen.html is missing the
Arrow-key equivalents used by the downstream onKeyDown navigation logic. Update
the help copy next to the existing PgUp/PgDn references so it also mentions
ArrowLeft/ArrowRight for beats, notes, grid, and anchors, keeping the wording
aligned with the key handling in onKeyDown.

tests/snap_navigation.test.js (1)

1-70: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for note/anchor timeline jumps. _navigateTimeline() still has untested note and anchor branches; add a small test that drives those shortcuts too.

🤖 Prompt for 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.

In `@tests/snap_navigation.test.js` around lines 1 - 70, Add a small test in
snap_navigation.test.js that exercises the untested note and anchor branches
inside _navigateTimeline(), using the existing screen.js pure snap-nav helpers
as the entry point. Reuse the same test style to drive the timeline-jump
shortcut handling for note and anchor targets, and assert the returned
navigation times/selection behavior matches the expected forward and backward
jumps. Keep the new coverage alongside the current _nextBeatTime, _nextGridTime,
and _nextTimeInList tests so the _navigateTimeline() shortcuts are verified
without relying on line numbers.

🤖 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 `@screen.js`:
- Around line 100-126: Backward grid navigation in _nextGridTime currently scans
intervals from earliest to latest, so the dir < 0 path can return an older
sub-grid candidate instead of the nearest one below current. Update the backward
branch to iterate beats/intervals from later to earlier and keep the existing
candidate checks in _nextGridTime so cross-beat jumps pick the closest prior
snap point. Add a regression test covering a backward step across a beat
boundary with snapValue enabled.

---

Nitpick comments:
In `@screen.html`:
- Line 116: The status hint text in screen.html is missing the Arrow-key
equivalents used by the downstream onKeyDown navigation logic. Update the help
copy next to the existing PgUp/PgDn references so it also mentions
ArrowLeft/ArrowRight for beats, notes, grid, and anchors, keeping the wording
aligned with the key handling in onKeyDown.

In `@tests/snap_navigation.test.js`:
- Around line 1-70: Add a small test in snap_navigation.test.js that exercises
the untested note and anchor branches inside _navigateTimeline(), using the
existing screen.js pure snap-nav helpers as the entry point. Reuse the same test
style to drive the timeline-jump shortcut handling for note and anchor targets,
and assert the returned navigation times/selection behavior matches the expected
forward and backward jumps. Keep the new coverage alongside the current
_nextBeatTime, _nextGridTime, and _nextTimeInList tests so the
_navigateTimeline() shortcuts are verified without relying on line numbers.

🪄 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: 33c1aa55-1eb1-48f6-9b51-6e1a8af95140

📥 Commits

Reviewing files that changed from the base of the PR and between 5239d47 and 941e309.

📒 Files selected for processing (3)

• screen.html
• screen.js
• tests/snap_navigation.test.js

[byrongamatos]

Review + fix pass (Claude Code). Three fixes pushed (all JS suites green, 8 snap-nav tests):

1. Runtime crash: snapTime() referenced the removed SNAP_VALUES. The snap-model upgrade replaced SNAP_VALUES with SNAP_OPTIONS + a pure _snapTimeToGrid, but left the core snapTime() reading SNAP_VALUES[snapIdx] — a ReferenceError the moment any snap-aligned edit (drag/paste/nudge) runs. node --check only checks syntax and the snap-nav test only exercises the @pure block, so neither caught it. Delegated snapTime to _snapTimeToGrid (wired to SNAP_OPTIONS + the new S.snapEnabled), + a source guard against leftover SNAP_VALUES.
2. Backward grid navigation returned the wrong point. _nextGridTime walked intervals ascending for both directions, so backward from a cursor past the first beat jumped to the end of interval 0 (1.0 from a 1.5 cursor) instead of the grid point just before it (1.25). Now walks intervals in reverse for the backward case (+ tests).
3. [P3] Timeline shortcuts swallowed browser nav chords. The 'beat' fall-through matched any modifier combo, so Cmd+←/→ (Back/Forward) and Ctrl+PageUp/Down (tab switch) were preventDefault()'d while the editor was focused. Now matches only the four documented combos exactly.

[ChrisBeWithYou]

Superseded by #62, which re-does this snap-grid + timeline-jump work on top of the shortcut-profile stack (#53–#56) and resolves the Alt+Arrow collision with #55 (the profile system owns the key bindings; this PR's engine is kept). Closing in favor of #62.