Live surfaces¶

	Garmin	Wear OS	Apple Watch
Status	—	🟡	⏳
Code	—	`wear/…/presentation/views/OtherViews.kt` (`AmbientView`), `wear/…/presentation/views/DashboardView.kt` (`drawTime`, `drawSpeed`), `wear/…/presentation/MainActivity.kt` (ambient observer), `wear/…/presentation/TrackingScreen.kt`, `wear/…/recording/TrackingService.kt`, `wear/…/tile/MainTileService.kt`, `wear/…/tile/LiveSurfaces.kt`, `wear/…/complication/MainComplicationService.kt`, `wear/src/main/AndroidManifest.xml`, `res/values/strings.xml`	—

Verified against code: 2026-10-13

Purpose¶

What the WatchApp shows outside its own instrument screens: the low-power layout while a track records, the recording notification and Ongoing Activity that lead back into the app, and the Tile and watch-face Complication that show SOG or the trip at a glance. They let the skipper look at the watch without waking the app, and get back into a running track in one tap.

Layout / behaviour¶

General rules for every surface:

A surface only reads the values the app already has; it never starts recording, changes the vessel state or uploads.
Tapping a surface opens the app on its current screen (the running track or the start list).
Numbers use the same rounding as the instrument screens, a dot as decimal separator, and the units kn and nm.

Garmin¶

None. A Connect IQ watch app has no glance, tile, complication or background service here. The app records only while it is open; leaving it ends or pauses the track (lifecycle.md). The FIT activity it records appears in Garmin's own activity history (recording.md). The instrument screens have no separate low-power layout; the device's display timeout applies (visual-system.md).

Wear OS¶

Low-power layout¶

The screen stays on while the recording screen is shown (instruments, Controls page, picker page): the app holds the screen on (FLAG_KEEP_SCREEN_ON), so the system's screen timeout does not apply. Some watches (OnePlus Watch 2) switch the display off at the timeout instead of giving apps ambient mode, even with Always-on screen on; SOG would then be gone. Other screens on top (stats, discard dialog, the picker opened by the header tap) use the system timeout.

After a set time without a touch or crown turn (setting Low Power Screen: 5, 10, 20 (default), 30, 45 or 60 s, alerts-and-auto-stats.md), and whenever the system puts the watch into ambient mode, the recording screen is replaced by a reduced layout on black: SOG and the time of day, each at the place and in the font the dashboard uses, so the eye finds them where it expects.

Waking: a touch (on release) or a crown turn brings back the page that was open before. That input does nothing else: a tap on the state header does not also open the picker. An alert or auto-stats overlay also brings the recording screen back, so the overlay is seen.
Brightness: unchanged (the watch's own setting); the black background keeps the OLED draw low.

Element	Position	Font / size	Colour	Content & format	Constraints
Background	Full screen	—	Black `0x000000`	—	—
Clock	x 0.50 centred, y 0.12 (dashboard: cellHeight × 0.6)	Numerals font	Light grey `0xAAAAAA`	`H:MM`, 24-hour, read at draw time: `9:05`	Ignores the watch's 12/24-hour setting, as the dashboard
SOG	x 0.50 centred, y 0.34 (dashboard: cellHeight × 1.70)	sog (hero) font	White `0xFFFFFF`	Knots, one decimal: `6.8`. No unit	From 10 kn the tens digit is in the header font, as on the dashboard (dashboard.md)

Refresh: when it appears, on each system ambient update and every 5 s, so SOG stays current. The 1 Hz recording continues in the background.
Not shown: vessel state, track timer, the touch-lock badge. In the system's ambient mode alert overlays are not drawn either; an alert still vibrates and sounds, and its overlay is visible only if the screen wakes within its 6 s (alerts-and-auto-stats.md).
No system clock is drawn on top: the app registers no TimeText while recording.
Paused track: none; a paused track is not on screen (lifecycle.md).

Recording notification and Ongoing Activity¶

While a track records, a foreground service keeps GPS, barometer and the 1 Hz tick running. It shows:

Item	Content
Notification channel	id `track`, name `Track recording`, low importance (no sound, no pop-up)
Notification	Title `Recording track`; small icon `ic_sail_notification`; ongoing (can't be swiped away), category workout; shown immediately
Ongoing Activity	Same icon on the watch face and in recents; status text `Recording track`. Static: no live values
Tap	Opens the app (single top), i.e. back to the running track

Both appear when a track starts or is resumed and disappear when it is paused, stopped or discarded (the service stops itself as soon as the track is paused). A paused track has no notification. The app asks for the notification permission at start (lifecycle.md).

Tile¶

One Tile, named SailEver, built with the Wear Material 3 primary layout.

Situation	Title	Main (display medium)	Label (body medium)	Edge button
Track recording	`SailEver`	SOG `6.8 kn` (one decimal)	`<state -ing label> · <track distance> nm`, one decimal: `Sailing · 12.4 nm`	`Open`
Track paused, app still running	`SailEver`	`paused`	`<state -ing label>`	`Resume`
Track paused, app closed since	`SailEver`	`paused`	`Track in progress`	`Resume`
A trip exists, no track open	`SailEver`	Trip distance `95.5 nm` (one decimal)	`<n> tracks`	`Open`
No trip yet	`SailEver`	`SailEver`	`No trip yet`	`Start`

Tap: the whole Tile and the button open the app. They don't resume or start anything themselves; the button text only names what the user does next.
Refresh: the app asks for a new Tile on start, resume, pause, stop and discard of a track and on each vessel state change. While the app holds a track (recording or paused), the Tile also asks for a refresh every 60 s; otherwise only on request.
Preview in the Tile picker: res/drawable/tile_preview.png (drawable-round/ on round watches).

Complication¶

One data source, named SailEver SOG, type short text only. Text and title by situation:

Situation	Text	Title
Track recording	SOG, one decimal: `6.8`	`kn`
Track paused, app still running	`PAUSE`	`SailEver`
A trip exists, no track in memory	Trip distance, no decimals: `96`	`nm`
No trip yet	`SAIL`	`SailEver`
Preview in the watch-face editor	`5.2`	`kn`

Content description for screen readers: SailEver <text> <title>.
Tap: opens the app.
Refresh: every 300 s (the system's update period), plus on the same events as the Tile. The SOG on the watch face can therefore be up to 5 minutes old.

Apple Watch¶

⏳ From apple_watch_port_plan.md:

Always-On: a reduced-luminance layout (isLuminanceReduced) for the running track (plan §3, phase 3). For a paused track the pause view takes the Always-On style: black, time, battery, paused (plan §1.2).
Complication and Smart Stack widget showing SOG and vessel state (plan §3, phase 6).
Action button (Ultra) bound to an App Intent that opens the vessel state picker (input.md).
The workout session keeps recording alive with the screen off, and the system shows its workout indicator. Content, refresh and tap actions are not decided yet.

States and edge cases¶

Situation	Wear OS behaviour
App killed while recording	Notification and Ongoing Activity vanish with the service. Tile and Complication fall back to the trip (no track in memory). The next launch ends the track (lifecycle.md)
No location permission	The notification still shows; the track records time and state without positions, SOG `0.0`
No GPS fix	Ambient, Tile and Complication show SOG `0.0`
Single-track trip	Tile label reads `1 tracks` (see Known deviations)

Known deviations¶

Complication ignores a stored paused track. After the app was closed with a paused track, the Complication shows the trip distance instead of PAUSE; the Tile correctly shows paused (MainComplicationService.onComplicationRequest checks only the engine in memory, not TripStore.isPausedTrack). Its code comment also says PAUSED while the text is PAUSE.
Tile plural: the label is always <n> tracks, so a one-track trip reads 1 tracks.