1 Developer Guidelines

dallasgroot edited this page 2026-04-08 16:35:40 -07:00

Table of Contents

• Developer Guidelines
• Visualizer Constraints
• State & Lifecycle Rules
• UI & Apple Framework Guidelines

Developer Guidelines

Before contributing or modifying the codebase, strictly adhere to the following rules:

Visualizer Constraints

1. DO NOT refactor WavePhysics or Canvas rendering: The MitsuhaVisualizerView is heavily optimized using Catmull-Rom splines, touch ripples, temporal viscosity, and phase-shifted depth shadows. Modifications will degrade performance and visual quality.
2. WaveStateCache Continuity: Rely on WaveStateCache and matchedGeometryEffect(id: "visWave") to morph the wave instead of cutting.

State & Lifecycle Rules

3. DO NOT make AudioPlayer.currentTime or duration @Published: This will trigger 10Hz full-view-hierarchy rerenders. Leaf views must poll via local Timer.publish.
4. Silence Markers are Inverted: silence_start represents where trailing silence begins. silence_end represents where leading silence ends.
5. Navidrome Virtual Paths: song.path is an ID3-derived virtual string, not a reliable 1:1 filesystem path. Use the Companion API's 4-tier resolution strategy for file lookups.
6. Album Grouping: Navidrome groups albums by album_artist, not artist.

UI & Apple Framework Guidelines

7. No Menus in Now Playing: Do not use Menu inside NowPlayingView as it causes _UIReparentingView errors. Use Button + .sheet.
8. No watchOS Context Menus: Do not use .contextMenu on watchOS (deprecated). Use .swipeActions.
9. No UIScreen: UIScreen.main is deprecated in iOS 26. Use GeometryReader.
10. Sheet Presentation: Do not use sheet(isPresented:) combined with if let logic due to timing bugs. Use sheet(item:).
11. Status Bar Isolation: Never use .preferredColorScheme to try and flip status bar icons—it will break the app's Dark Mode. Use the NavidromeHostingController delegate.