openbridge-webcomponents watch-radial-instruments.instructions.md

Watch & Radial Instruments

These instructions apply to the circular/radial watch-based instrument system, including the core obc-watch renderer and all navigation instruments that use it.

⚠️ IMPORTANT: Interconnected Components

All components in this system are tightly interconnected and share the same rendering core:

• watch.ts ↔ instrument-radial.ts ↔ compass.ts ↔ heading.ts ↔ rudder.ts ↔ wind.ts ↔ speed-gauge.ts ↔ gauge-radial.ts ↔ azimuth-thruster.ts ↔ roll.ts ↔ rot-sector.ts

When implementing a new feature or changing existing behavior:

1. Shared circular rendering belongs in watch.ts - it is the single source of truth for anything more than one instrument draws. Genuinely component-specific logic stays local: compass-sector owns its bespoke FOV compression, and pitch/roll/pitch-roll/pitch-roll-heave own their coupled buildFrame contracts (see "Shared frame computation"). Do not move those into the shared renderer — doing so changes every other instrument.
2. Changes to watch.ts affect ALL instruments that use it
3. If adding a new visual element, add it to watch.ts as a configurable option, not to individual instruments
4. Navigation instruments are thin wrappers that configure obc-watch and add domain-specific overlays
5. instrument-radial.ts is a reusable building block that wraps obc-watch for generic gauge use cases

Before completing any change, verify:

• watch.ts has the core rendering logic
• Helper modules (tickmark.ts, advice.ts, label.ts, etc.) are updated if needed
• All consuming instruments still render correctly
• ViewBox coordination is maintained across layers
• Responsive scaling works at different sizes

Architecture Overview

The watch-based instrument system follows a core renderer + thin wrapper pattern: