Summary

Shortcut tiles on Wear OS use domain-based fallback icons that don't reflect entity state — a lock always shows the same padlock icon, a switch always shows the same toggle. This change renders state-aware icons (e.g., locked vs unlocked padlock, powered vs unpowered outlet) and keeps them in sync with Home Assistant in real time.

Before: All lock entities show the same generic padlock icon.
After: Locked entities show a closed padlock, unlocked entities show an open padlock (and similar state-aware icons for other domains like covers, fans, switches).

How it works

• Real-time state via WebSocket: while the tile is visible, IntegrationRepository.getEntityUpdates(entityIds) drives a shared in-memory cache. No REST polling; no getEntities() batch over the full entity list.
• Cold-start warming: on first render, any shortcut entity not yet in the cache is fetched via parallel getEntity() calls bounded by a 2s timeout. If the network is slow the tile still renders on time using domain-default icons, and the cache fills in on the next render.
• Snapshot-per-render: onTileRequest freezes the cache into a TileSnapshot keyed by the resources version; onTileResourcesRequest looks the snapshot up again and generates bitmaps from the same frozen view. Resource IDs include the state (switch.foo@on vs switch.foo@off) so the Wear bitmap cache can't serve a stale image.
• Optimistic click: on tap, the cached state is flipped to the predicted post-tap value (for known toggle domains: switch, light, lock, cover, input_boolean, fan) before the layout is built. The WebSocket subscription reconciles shortly after. This avoids a framework quirk where requestUpdate() doesn't reliably trigger a re-render while a tile is visible.
• Lifecycle: subscription starts in onTileEnterEvent, stops in onTileLeaveEvent and onTileRemoveEvent. State survives service recreation via companion object.

Checklist

• New or updated tests have been added to cover the changes following the testing guidelines.
• The code follows the project's code style and best_practices.
• The changes have been thoroughly tested, and edge cases have been considered.
• Changes are backward compatible whenever feasible. Any breaking changes are documented in the changelog for users and/or in the code for developers depending on the relevance.

Tests

Pure-logic tests in ShortcutsTileStateTest cover:

• Resource-ID invariants (state suffixing, null/empty handling, mismatch detection)
• Snapshot immutability against later cache mutation
• LRU stash eviction and replacement
• The runtime race: cache mutation between onTileRequest and onTileResourcesRequest must not break the resource-ID invariant
• Optimistic click prediction per domain, plus safe no-op on unknown domains and unrecognized states

I did extensive manual testing loading this onto my actual watch and updating my actual entities. This was the only strategy that worked well. The UI very difficult to get right.

Screenshots

Fallback icons (no entity state):

State-aware icons (locked vs unlocked):

Notes

• Icon resolution uses Entity.getIcon() (already the app-wide pattern) for cached entities and falls back to getIcon(icon, domain, context) when the cache is cold.
• Hardcoded state strings ("on", "off", "locked", "unlocked", "open", "closed") match existing uses throughout Entity.kt and the wear module — these are part of Home Assistant's public API.
• Unknown domains and unrecognized states are a silent no-op on the optimistic path: the tap still fires the broadcast, the display stays on the current state, and the subscription updates it when the server confirms.