setOnscreenEntity method

Future<void> setOnscreenEntity(
  1. String entityIdentifier,
  2. String entityId, {
  3. String? title,
})

Binds the entity currently shown on screen to an NSUserActivity so Siri and Apple Intelligence can resolve references like "this" (#56).

Call this as the user navigates, passing the primary entity for the current screen (entityIdentifier = the entity type identifier, entityId = the instance id). Creates/updates the current user activity and makes it current. Call clearOnscreenEntity when leaving the screen.

PoC status: the user-activity lifecycle (becomeCurrent / targetContentIdentifier) uses stable APIs and works today. The actual NSUserActivity.appEntityIdentifier AppEntity association is iOS 26+ and needs the concrete entity type — see the on-device PoC note in docs/adr/0004-onscreen-awareness-feasibility.md. iOS-only; a no-op elsewhere.

Implementation

Future<void> setOnscreenEntity(
  String entityIdentifier,
  String entityId, {
  String? title,
}) {
  throw UnimplementedError('setOnscreenEntity() has not been implemented.');
}