Explain bugs with app state

Screenshots and logs may not reveal the state behind a bug. Artifacts let your Flutter app provide explicit snapshots, such as state JSON or a support bundle, that people and agents can retain with the session.

1. Implement a state provider

This provider exposes one JSON snapshot. Its callback reads selected app state when the host requests the artifact, so each capture reflects that moment.

import 'dart:convert';
import 'package:ansight_flutter/ansight.dart';

class AppStateArtifactProvider implements AnsightArtifactProvider {
  const AppStateArtifactProvider(this.readState);

  final Map<String, Object?> Function() readState;

  @override
  AnsightArtifactProviderDescriptor get descriptor =>
      const AnsightArtifactProviderDescriptor(
        id: 'app.state',
        name: 'App state',
      );

  @override
  Future<List<AnsightArtifactDefinition>> query() async =>
      const <AnsightArtifactDefinition>[
        AnsightArtifactDefinition(
          id: 'state',
          name: 'Current app state',
          kind: 'snapshot',
          mimeType: 'application/json',
          fileName: 'app-state.json',
        ),
      ];

  @override
  Future<AnsightArtifactPayload> create(AnsightArtifactRequest request) async {
    if (request.artifactId != 'state') {
      throw ArgumentError.value(request.artifactId, 'artifactId', 'Unknown artifact');
    }

    return AnsightArtifactPayload.text(
      jsonEncode(readState()),
      mimeType: 'application/json',
      fileName: 'app-state.json',
      name: 'Current app state',
      kind: 'snapshot',
    );
  }
}

query() advertises what can be requested; create() produces the payload. The SDK handles the binary transfer to the host for both text and byte payloads.

2. Register it in the development build

After initializing Ansight using Flutter Setup, register the provider inside the same development-build guard. Replace the sample values with reads from your app’s current state; return only JSON-serializable fields that are safe to export.

final registration = await Ansight.instance.registerArtifactProvider(
  AppStateArtifactProvider(
    () => <String, Object?>{
      'screen': 'checkout',
      'pendingSyncCount': 2,
    },
  ),
);

Keep the returned registration if you need to remove the provider later with await registration.unregister(). Registration exposes artifacts.query and artifacts.request; the readOnly tool guard used in the setup guide allows both tools.

3. Request a snapshot

With the host running and the development app connected, find its session ID:

ansight session list --connected --json

Replace <session-id> in the following commands with that ID. Query the available exports, then request this provider’s state artifact:

ansight app call <session-id> artifacts.query --arguments '{}' --json
ansight app call <session-id> artifacts.request \
  --arguments '{"providerId":"app.state","artifactId":"state"}' --json

The query result should include provider app.state with artifact state. The request creates app-state.json; a successful tool result queues its transfer to the host.

4. Verify the captured file

Confirm that the host retained the transferred snapshot:

ansight artifact list --session-id <session-id> --provider app.state --json

Look for logicalId: "state" and app-state.json in paths. Copy the entry’s artifactId, which identifies this captured snapshot rather than the provider’s logical state definition, and export it:

ansight session artifact export <session-id> \
  --snapshot-id <artifact-id> --path app-state.json --output ./app-state.json

Open the exported file. With the sample callback above, it contains:

{"screen":"checkout","pendingSyncCount":2}

If no snapshot is listed yet, check the request result and rerun the list after the transfer finishes. If the provider is missing from the query, check that registration completed in the connected app and its tool guard permits read access.

For larger exports, return an AnsightArtifactPayload with bytes and an appropriate MIME type and file name. Keep providers limited to development workflows, redact secrets before creating the payload, and expose only the data the investigation needs.