screenstack_sdk 3.1.1

Automated screenshot capture for Flutter apps. Configure routes, capture screens during CI/CD builds via FlightStack, and upload to ScreenStack device frames for App Store / Play Store assets.

Changelog

3.1.1

First pub.dev release from the new in-monorepo location at packages/screenstack_sdk/. Combines the unpublished 3.0.0 + 3.1.0 deltas:

• DeviceProfile + well-known constants (iphone15ProMax, iphone15Pro, iphoneSE, ipadPro129, pixel9Pro, pixel9, galaxyS25Ultra) and DeviceProfile.lookup(name) / DeviceProfile.wellKnown for string-keyed resolution.
• TestUserCredentials.fromEnv() reading SCREENSTACK_TEST_USER_EMAIL/PASSWORD/TOKEN/EXPIRES_AT injected by FlightStack at run time. Credentials never appear in manifest.json — only metadata flags.
• ScreenStackYaml.load() / .parse() reads a screenstack.yml and returns a ScreenStackConfig. Same file the JS SDK reads — one source of truth across both runtimes.
• captureScreenStackScreenshots now accepts deviceProfile and testUser named args; values flow into a richer manifest.json (sdk, runtime, deviceProfile, testUser metadata blocks at top level).
• Expired-credential guard refuses to start capture instead of failing mid-run.

3.1.0

New

• ScreenStackYaml — load a screenstack.yml file and convert it to a ScreenStackConfig so the Flutter SDK accepts the same single source of truth the JS SDK (@voostack/screenstack-sdk) reads. The file lives at the customer's repo root; the integration test calls ScreenStackYaml.load(...) instead of building config in Dart.

  final config = await ScreenStackYaml.load(
    'screenstack.yml',
    appBuilder: () => const MyApp(),
  );
  await captureScreenStackScreenshots(tester, binding, config);
  

  Schema accepts project, deviceProfile (well-known string or literal map), settleDelay, testUser.secretRef (FlightStack swaps for env vars at run time), and screens: with route + name + targets. Targets accept both "canvas/view" short-form strings and { canvas, view } maps. Per-call deviceProfile and testUser args win over what the YAML declares.

• DeviceProfile.lookup(name) + DeviceProfile.wellKnown — string → profile map keyed by the names the FlightStack mapping table uses (e.g. iphone-15-pro-max). Powers YAML resolution and lets customers thread profile names through env vars without importing the constants in Dart.

• yaml dependency added.

Repo location

The SDK was moved into the ScreenStack monorepo at packages/screenstack_sdk/. Previously at voo_flutter/packages/dev/screenstack_sdk. No code change needed on the consumer side — pub.dev still ships it as screenstack_sdk.

3.0.0

New

• DeviceProfile — describes the device the captures were taken on. Written into manifest.json so the FlightStack uploader can route captures to the right canvas view automatically. Ships with well-known constants (iphone15ProMax, iphone15Pro, iphoneSE, ipadPro129, pixel9Pro, pixel9, galaxyS25Ultra).
• TestUserCredentials — credentials the setup callback uses to sign in, sourced from env vars set by FlightStack at run time:
  • SCREENSTACK_TEST_USER_EMAIL
  • SCREENSTACK_TEST_USER_PASSWORD
  • SCREENSTACK_TEST_USER_TOKEN
  • SCREENSTACK_TEST_USER_EXPIRES_AT Use TestUserCredentials.fromEnv() instead of reading the environment directly. Credentials themselves are NEVER serialized into the manifest — only metadata (whether a password / bearer was provided, expiry).
• captureScreenStackScreenshots(..., DeviceProfile? deviceProfile, TestUserCredentials? testUser) — new optional parameters thread the above through to the manifest.
• ScreenStackConfig.deviceProfile and .testUser — also accept config-level defaults; per-call args win.
• Expired-credential guard — capture aborts before pumping the app if TestUserCredentials.isExpired is true, instead of failing mid-capture.

Manifest

manifest.json now starts with "sdk": "screenstack_sdk", "runtime": "flutter" so a single FlightStack uploader can disambiguate Flutter SDK and JS SDK output. New deviceProfile and testUser (metadata-only) blocks at the top level.

Breaking

The captureScreenStackScreenshots signature now has the two extra optional named parameters. Existing call sites compile unchanged. The manifest schema is additive — older uploaders that ignore unknown keys keep working.

2.0.3

• Reorder exports and streamline code structure across multiple files
• Update dependencies and fix formatting issues across multiple packages

2.0.2

Documentation

• Authentication guide: Comprehensive section on handling auth in screenshots
  • Option 1: Setup/teardown callbacks with Firebase, Supabase, custom examples
  • Option 2: Demo/screenshot mode pattern for bypassing auth
  • Option 3: Test-specific routes (e.g., /preview/dashboard)
• Environment variables: Guidance on storing secrets in CI/CD pipelines
• Best practices: Updated auth section with practical examples

2.0.1

New Features

• setup callback: Run authentication or data seeding before capture starts
• teardown callback: Run cleanup after capture completes
• ScreenStackCallback type: Type alias for setup/teardown functions

Example

await captureScreenStackScreenshots(
  tester,
  binding,
  config,
  setup: (tester, context) async {
    // Authenticate before capturing protected screens
    await AuthService.signIn(email: '[e-mail]', password: 'test');
    await tester.pumpAndSettle();
  },
  teardown: (tester, context) async {
    await AuthService.signOut();
  },
);

2.0.0

Breaking Changes

• captureScreenStackScreenshots() now returns CaptureSessionResult instead of void

New Features

• Multi-canvas support: Upload screenshots to multiple canvases simultaneously
• FrameTarget class: Type-safe canvas/view targeting with FrameTarget(canvas: 'iOS', view: 'Home')
• Screen class: Define routes with explicit upload targets
• ScreenStackConfig.advanced() constructor: For multi-canvas projects
• Screen.withPaths() factory: Parse targets from "canvas/view" string format
• FrameTarget.parse() factory: Create targets from path strings
• JSON manifest generation: manifest.json with capture results and targets
• CaptureResult class: Detailed results per captured screen
• CaptureSessionResult class: Session summary with success/failure counts
• Config validation: config.validate() returns list of configuration errors
• Per-screen settle delay: Override global delay for specific screens

Improvements

• Comprehensive library documentation with examples
• Better error messages for navigation failures
• Emoji-enhanced console output for capture progress
• effectiveName getter auto-generates filename from route if not specified

Documentation

• Complete API reference in README
• ScreenStack hierarchy explanation
• Workflow diagram
• Best practices and troubleshooting guide

1.0.0

• Initial release
• ScreenStackConfig class for type-safe configuration
• captureScreenStackScreenshots() helper for integration tests
• Support for go_router and Navigator navigation
• Configurable settle delay