Calendarr-IOS/docs/superpowers/specs/2026-09-11-apple-watch-app-design.md

Apple Watch app and watch-face complications

Date: 2026-09-11 Status: implemented — pending on-device verification

Goal

Put "what is my next appointment" on the wrist as watch-face complications, with a tap-through app that shows a plain agenda list and lets the user narrow which calendars count. Nothing more.

Non-goals

• Creating or editing events on the watch. The snapshot is deliberately lossy — no notes, recurrence rules or permissions — which is enough to display a calendar and deliberately not enough to edit one. Editing would mean a second API client and is out of scope.
• Running without the iPhone. The watch is a read-only consumer of the phone's snapshot. Direct server access stays available as a later option (the server is reachable over HTTPS) but is not built now.
• Wear OS parity. A separate project with its own decision.

Platform floor

iOS 26 (unchanged) and watchOS 26. Nothing below that needs to work, so no availability branching.

Design rules

• No emojis as icons, anywhere — SF Symbols only (Image(systemName:)). An emoji renders differently on every platform and font, and complications tint SF Symbols with the watch face's colour, which an emoji ignores.
• Exactly one element per complication is marked widgetAccentable().
• The watch app's background stays black rather than following snapshot.theme; the always-on display and OLED make that the right choice. snapshot.theme supplies accents only.

Architecture

iPhone                                     Apple Watch
──────────────────────────────────         ──────────────────────────────
CalendarStore.publishWidgetSnapshot()
  ├─ SnapshotStore.write()   (App Group iOS)
  ├─ WidgetTimelineNotifier.reload()
  └─ WatchSyncService.push() ──WCSession──▶ WatchSnapshotReceiver
                                              ├─ SnapshotStore.write()  (App Group watchOS)
                                              ├─ SharedSessionStore.write()
                                              └─ WidgetCenter.reloadAllTimelines()
BGAppRefreshTask (new)
  └─ refresh → publishWidgetSnapshot()      Watch app foreground
                                              └─ sendMessage ──▶ pull when reachable

App Groups are per-device: the phone's container is not the watch's. The watch therefore receives the snapshot over WatchConnectivity and writes it into its own App Group container using the same SnapshotStore from CalendarrKit. One format, one reader, no drift — the watch is exactly the read-only consumer the CalendarrKit README already describes.

CalendarrAppGroup.current is already correct for watchOS: the #if os(macOS) || targetEnvironment(macCatalyst) guard falls through to the unprefixed identifier, which is what watchOS requires.

Module changes

Module	Change
CalendarrKit	Add .watchOS(.v26) to platforms. No code change — the Foundation-only constraint pays off here.
CalendarrKit	New Snapshot/WatchCoverage.swift: the transport trimming policy plus CalendarrSnapshot.trimmedForWatch(). Shared by sender and receiver so they cannot disagree about it.
iOS app	New Services/WatchSyncService.swift — WCSession sender, called from publishWidgetSnapshot().
iOS app	New Services/BackgroundRefresh.swift — BGAppRefreshTask that refreshes events, republishes the snapshot and pushes to the watch. Benefits the existing widgets too.
New target	CalendarrWatch (watchOS app): receiver, agenda, event detail, calendar filter.
New target	CalendarrWatchComplications (watchOS widget extension): the complications.

Transport

Trimming policy

WatchCoverage, mirroring the existing SnapshotCoverage:

• daysBehind = 1
• daysAhead = 14
• maxEvents = 120

trimmedForWatch() must narrow coverageStart/coverageEnd along with the events. Carrying 14 days of events while still claiming a 42-day window would make the watch render an empty week that it has no information about — the exact failure the README warns against. If the maxEvents cap truncates before daysAhead is reached, coverageEnd is pulled back to the start of the day of the last retained event.

Trimmed payload is roughly 20–30 KB, far below the WatchConnectivity limit.

Three delivery paths

Each one alone leaves a gap, so all three ship:

1. updateApplicationContext — the main path. Carries only the latest state, survives restarts, and has no queue to overflow. Delivered when the watch app next launches or wakes.
2. transferCurrentComplicationUserInfo — sent only when the next event changed identity (first event after now, compared by id and start). This is the only path that wakes the watch app while it is not running, which is why it exists; its daily budget (~50) is why it is not used for every write. Additionally rate-limited to at most 4 per hour.
3. sendMessage pull on watch app foreground — covers "I am looking at it right now and it is stale".

Payload is a property-list dictionary of Data blobs: snapshot, calendars, session, plus an integer schema matching CalendarrSnapshot.currentSchema. A receiver refuses a higher schema rather than guessing, same rule as the file format.

Only the watch app runs WCSession; a widget extension cannot. The extension always reads what the app last wrote.

Timeline strategy

This deliberately differs from the iOS provider, which emits 24 hourly entries (CalendarrTimelineProvider.swift). On the watch, entries are placed on event boundaries: now, plus every event start and end inside the next 24 hours, deduplicated and sorted, with hourly filler so at least 24 hours are covered, and capped at 100 entries. The complication then flips in the exact minute the next appointment changes, with no network call and no refresh budget spent.

Refresh policy is .atEnd. Data changes arrive by push; when the timeline simply runs out it regenerates from the same snapshot, which is cheap and correct.

Countdowns use Text(event.start, style: .timer), which updates live without consuming timeline entries and dims correctly on the always-on display.

Complication catalogue

Eight kinds. Families in brackets.

Kind	Families	Content
WatchNextEvent	rectangular, inline	Time, title, location
WatchCornerCountdown	corner	Value: live countdown. Curved label: "14:30 Zahnarzt"
WatchCornerTime	corner	Value: start time. Curved label: event title
WatchCountdown	circular, inline	Remaining time; circular draws a draining ring
WatchDate	circular, inline	Day number and month
WatchTodayCount	circular, inline	Number of events today
WatchNextTwo	rectangular	The next two events, time plus title
WatchDatePlusEvent	rectangular	Weekday and date plus the next event

WatchDate, WatchTodayCount and WatchCountdown are ports of the existing lock-screen widgets in LockScreenWidgetViews.swift, which already render accessoryCircular, accessoryRectangular and accessoryInline.

Which face shows what

A round Infograph-style face has no rectangular slot: it offers four corners and a circular sub-dial. The rectangular kinds therefore only appear on Modular-family faces. Since the user's face is round, accessoryCorner is the primary slot and gets the most attention; the rectangular kinds still ship because they are cheap and cover the other faces.

accessoryCorner

New and watchOS-only. The curved bezel text comes from .widgetLabel { Text(...) } — WidgetKit lays it along the edge, so no manual arc drawing.

The hard constraint: a corner holds one value plus the curved label. A second inner line runs into the curved text and must not be attempted. Both corner kinds therefore carry a single value and put the context in the label.

Two content variants ship rather than one, because they share the whole data path and differ only in formatting — the user picks on the watch face. A date-in-the-corner variant was considered and dropped: it carries no appointment information, which is the whole point of the complication.

watchOS tints complications monochrome using the watch face's colour, so per-calendar colours are not available in complications. Calendar colours appear in the app only.

Watch app

• Agenda — a scrolling list grouped by day, day headers, one row per event with a leading bar in the event's colour, time range or all-day label, and title. Covers the trimmed window; days outside snapshot.covers(date) are not rendered as empty but greyed with a note.
• Event detail — title, time, location, calendar name. Read-only.
• Calendar filter — one row per calendar from readCalendars(), rendered as a Button with an SF Symbol checkbox (checkmark.square.fill / square) plus the calendar's colour dot. Deliberately not a watchOS Toggle: its switch reads as a state indicator you wait on rather than a control you tap.

The background stays black rather than following snapshot.theme, because the always-on display and OLED make black the right choice on the watch. snapshot.theme is used for accents only.

Calendar filter semantics

Stored in the watch's App Group UserDefaults under watchHiddenCalendarKeys: [String], so the widget extension reads the same value and one toggle affects every complication at once.

The snapshot already excludes hidden and banished calendars, so the watch filter narrows further and never contradicts the phone. CalendarSelectionIntent is ported so a complication can override the app-level filter, but the in-app toggles are the primary path: intent configuration is awkward to operate on the watch face itself.

Error and empty states

SnapshotReadResult already covers most of them. One case is new.

State	Display
.neverWritten / nothing received yet	"Open Calendarr on your iPhone once"
.loggedOut	"Sign in on your iPhone" — never show the previous events
.incompatible	"Update the watch app"
outside covers(date)	Greyed with a note, never rendered as "nothing scheduled"
Snapshot present but visibly old	Show writtenAt as "as of …" rather than implying freshness

The last one has no iPhone equivalent: the phone writes its own cache, so it is never stale in a way the reader cannot see. The watch can hold a snapshot from days ago because the phone was unreachable, and must say so.

iOS background refresh

• Register BGAppRefreshTaskRequest with identifier com.scarriffleservices.calendarr.ios.refresh in CalendarrApp, rescheduling after every run with earliestBeginDate 30 minutes out.
• Info.plist needs BGTaskSchedulerPermittedIdentifiers and the fetch background mode.
• The task fetches the coverage window, calls publishWidgetSnapshot(), and lets the existing call chain reload widgets and push to the watch. It must finish well inside the ~30 s budget and set an expiration handler.

iOS decides when this runs; frequency follows how the user actually opens the app. This improves freshness, it does not guarantee it.

Build, signing and distribution

• Bundle identifiers: com.scarriffleservices.calendarr.ios.watchkitapp and com.scarriffleservices.calendarr.ios.watchkitapp.complications. The .watchkitapp suffix is required for a companion watch app; WKCompanionAppBundleIdentifier points at the iOS app.
• Both new targets need com.apple.security.application-groups set to group.com.scarriffleservices.calendarr, unprefixed.
• No keychain access group on the watch: there is no token there to protect.
• Register both bundle IDs and enable the App Group for them in the developer portal.
• App Store Connect: a watch app is not a new app record, it is a new target in the existing one — a normal version submission and a normal review. Watch screenshots are additionally required.
• The server needs no change at all.

Risks

1. Xcode does not currently support the test device. Xcode 26.6 ships the watchOS 26.5 SDK; the target watch runs watchOS 27 beta. Installing builds on it needs an Xcode with watchOS 27 support. Code can be written and built against watchOS 26 in the meantime, but on-device verification is blocked until that Xcode is installed. This is the first thing to resolve.
2. WatchConnectivity background delivery is opportunistic and cannot be verified on this machine — only on a real paired device.
3. Complication push budget. Path 2 is deliberately rate-limited; if pushes are exhausted, freshness silently degrades to path 1. The stale-snapshot display state is what keeps that honest rather than wrong.
4. First run is a chicken-and-egg. The watch app can be installed before the phone has ever pushed. The empty state must name the fix rather than look broken.
5. App review may ask for demo credentials, since the app needs a self-hosted server to show anything.

Verification

Per the project's working rules, this machine builds but does not run apps:

xcodebuild -project "Calendarr iOS.xcodeproj" -scheme CalendarrWatch \
  -sdk watchsimulator CODE_SIGNING_ALLOWED=NO build
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift build   # CalendarrKit
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test

Behaviour, layout and complication refresh are verified by the user on the device. Nothing about the look is asserted here.

Later, not now

• Direct HTTPS fetch from the watch, for freshness independent of the phone.
• Creating events on the watch.
• Wear OS equivalent.