feat: add Home Screen widgets, SSE sitemap updates, and wide-display grid

[timbms]

Overview

Four features landing together:

1. Home Screen widget extension — interactive Switch widgets and a read-only Sensor widget backed by real-time SSE updates
2. SSE migration for sitemap pages — replaces the long-poll loop with a Server-Sent Events stream; widget state changes are applied in-place, reducing UI churn and data usage by ~6×
3. Wide-display sitemap grid — two-column adaptive grid on iPad; media rows (image, video, chart, webview, map) span full width, matching BasicUI behaviour
4. CarPlay support — sitemap-based favorites scene with real-time SSE updates; uses CPGridTemplate with openHAB SF symbol icons

Raises minimum deployment targets to iOS 18 / watchOS 11 / macOS 15 (required for interactive widget APIs and AsyncSequence.Failure / SE-0421).

---

Widget extension (openHABWidget)

Switch widgets

Three sizes backed by separate WidgetConfigurationIntents:

Size	Items	Configuration intent
Small	1 Switch item	SwitchSmallConfigurationAppIntent
Medium	2 Switch items	SwitchMediumConfigurationAppIntent
Large	4 Switch items	SwitchLargeConfigurationAppIntent

Each widget lets the user select a Home and then one or more Switch items. Tapping a switch sends the toggle command via SetSwitchItemIntent.

Sensor widget

Displays the current state of a Number or String item (e.g. temperature, humidity). Available in small and medium sizes. Refreshes every 5 minutes; also updated live via SSE.

Real-time widget updates

WidgetItemRegistry (new, OpenHABCore) — actor that tracks which items have active widgets using App Group UserDefaults (group.org.openhab.app), shared between the widget extension and the main app without IPC.

WidgetItemMonitor (new, main app) — started from AppDelegate on launch. Subscribes to ItemEventStream SSE events and calls WidgetCenter.shared.reloadTimelines(ofKind:) for all widget kinds when a tracked item's state changes. Stale registry entries are cleaned up each time the app becomes active.

---

Sitemap SSE migration

Network savings — measured with Proxyman over a ~30 s session with periodic state changes:

                         SSE session    Long-poll session
─────────────────────────────────────────────────────────
  /rest/sitemaps/…/…          44 KB          308 KB
  /rest/sitemaps/events/{id}   4 KB            —
─────────────────────────────────────────────────────────
  Total                        48 KB          308 KB   ← 6× less

Per state change, each long-poll round-trip returns ~38 KB of full page JSON; a typical SSE widget event is 100–300 bytes — roughly 100–300× smaller.

SitemapEventStream (new, OpenHABCore) — actor-isolated SSE connection manager: subscribes to the server's sitemap event endpoint, broadcasts SitemapEventMessage values (.alive, .sitemapChanged, .widget), reconnects with exponential backoff, and includes a 30 s watchdog to detect silently dead connections.

OpenAPIServiceProtocol — adds openHABSitemapWidgetEvents (returning any AsyncSequence<SitemapEventMessage, any Error> & Sendable) and openHABEvents. SSE event parsing and 404 → SitemapSseError.unsupported mapping are encapsulated inside OpenAPIService.

SitemapPageViewModel — after initial fetch, checks shouldUseSSE(); if true, hands off to startSSE and returns from the polling loop. applySseWidgetEvent applies widget delta events in-place via OpenHABWidget.apply(event:); falls back to full page reload when a widget is not found or its description changed. startLongPollingFallback sets ssePreferred = false and restarts polling.

OpenHABWidget.apply(event:) (new, OpenHABCore) — recursive in-place widget update from an OpenHABSitemapWidgetEvent. Returns .applied, .notFound, or .requiresPageReload.

---

Wide-display sitemap grid

On iPad (and any wide horizontal size class), sitemap pages now use a two-column adaptive grid via SitemapGridLayout. Media widgets — image, video, chart, webview, and map — are classified as full-width cells and span both columns, matching BasicUI.

SitemapGridLayout (new) — groups SitemapRowInput items into sections and row groups; classifies cells as half-width or full-width based on widget type.

SitemapPresentationPolicy (new) — decides between list and grid presentation based on horizontal size class; drives SitemapPageView layout switching.

EmbeddingRowInputView — media rows now use standard regularInsets (16 pt leading/trailing) instead of zero-inset edge-to-edge bleed.

Image rows — KFImage (static images, charts) gets frame(maxWidth: .infinity) so landscape images fill the available width. KFAnimatedImage (GIFs) uses AnimatedGIFFrameModifier which computes an exact frame from the GIF's natural aspect ratio via onGeometryChange (no GeometryReader).

Video rows — fixed frame(height: 200) removed; height is now driven by aspectRatio(contentMode: .fit) + frame(maxWidth: .infinity).

---

CarPlay support

CarPlay presents a sitemap-based favorites scene configurable in Settings → CarPlay.

CarPlaySceneDelegate (new) — manages the CPTemplateApplicationSceneDelegate lifecycle. On connect, loads the configured sitemap and renders it as a CPGridTemplate with openHAB SF symbol icons (mapped from openHAB icon names). Subscribes to SitemapEventStream SSE events and applies widget updates in real time; reconnects on network change or watchdog timeout.

• Sitemap selection is stored in Preferences as carPlaySitemapName
• SF symbol mapping replaces remote icon fetches to keep CarPlay rendering fast and offline-capable
• Shows a placeholder CPListTemplate when no compatible sitemap widgets are found or CarPlay is not yet configured
• Entitlements updated to include com.apple.developer.carplay-maps (via openHAB-CarPlay.entitlements)

---

ItemEventStream improvements

• SSE watchdog — background task checks every 10 s whether any event has been received in the last 30 s; reconnects automatically on silence
• Self-contained network monitoring — startMonitoringNetworkIfNeeded keeps the network-change loop alive for the actor's lifetime; startMonitoringNetwork now returns immediately instead of blocking

iOS 17 clean-up

Removes the #available(iOS 17) guard and the hand-rolled NWPathMonitor.paths() compatibility shim from NWPathMonitoring.swift now that iOS 16 is no longer supported.

---

Test plan

Widgets

• Add a small/medium/large Switch widget to the Home Screen; configure a Home and items
• Tap a switch in the widget → toggle command sent, widget state updates
• Add a Sensor widget; verify current item state is displayed
• Change item state via openHAB UI → widget refreshes within seconds (SSE) while app is active
• Background / lock screen: widget refreshes on next 5-minute timeline reload

Sitemap SSE

• SSE-capable server (openHAB ≥ 3.3): sitemap updates arrive as widget events without full page reloads
• Server without SSE (openHAB < 3.3): falls back to long-polling via the existing JSON REST API
• Network drop mid-SSE: reconnects and triggers a page refresh to recover missed events
• Server restart: watchdog detects stale connection within 30 s and reconnects
• Force-airplane-mode then restore: polling recovers without hang

Wide-display grid

• Open a sitemap on iPad (or wide iPhone landscape) → rows appear in a two-column grid
• Image, video, chart, webview, and map widgets span full width; other widgets share a half-width cell
• Landscape images fill the available width without cropping
• GIF images preserve their aspect ratio at full width
• Video rows resize proportionally with the available width (no fixed 200 pt height)
• On compact width (iPhone portrait) → standard list layout unchanged

CarPlay

• Connect a CarPlay-capable device or use the CarPlay simulator in Xcode
• Without a sitemap configured: placeholder screen is shown with setup instructions
• Configure a sitemap in Settings → CarPlay; reconnect → grid of items appears with SF symbol icons
• Change item state via openHAB UI → CarPlay grid updates in real time via SSE
• Network drop mid-SSE: CarPlay reconnects and refreshes automatically
• No compatible widgets in the sitemap: placeholder list is shown instead of an empty grid

[Copilot]

Copilot reviewed 65 out of 68 changed files in this pull request and generated no comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 66 out of 69 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.