setOnscreenEntity method

@override Future<void> setOnscreenEntity(String entityIdentifier, String entityId, { 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

@override
Future<void> setOnscreenEntity(
  String entityIdentifier,
  String entityId, {
  String? title,
}) async {
  try {
    await methodChannel.invokeMethod('setOnscreenEntity', {
      'entityIdentifier': entityIdentifier,
      'entityId': entityId,
      'title': ?title,
    });
  } on MissingPluginException {
    // No-op on platforms that don't implement this (e.g., Android).
    // Onscreen awareness is iOS-specific.
  }
}