Ensemble

The ensemble_auth module provides concrete implementations for authentication services and sign-in widgets within Ensemble applications. It integrates with the core ensemble package by registering implementations for auth context, tokens, OAuth, and various sign-in methods via GetIt.

Key capabilities include:

• Sign-in Methods: Google, Apple, Microsoft, Anonymous, Custom-token, and Verification-code sign-in.
• Widgets: Pre-built UI components like SignInWithGoogle, SignInWithApple, ConnectWithGoogle, and ConnectWithMicrosoft.
• Management: Token management and OAuth flow handling.

The package provides access to three main icon sets:

• Material Design Icons: Google's icon set. Accessed via MaterialIcons.iconMap['icon_name'].
• Remix Icons: An open-source library with 2,000+ icons (v4.2.0). Accessed via Remix.iconMap['icon_name'].
• Font Awesome Icons: A professional toolkit with 1,600+ free icons (v6.5.1). Accessed via FontAwesome.iconMap['icon_name'].

The ensemble_ts_interpreter executes JavaScript code within Flutter applications by following a three-stage pipeline:

1. Parsing: JavaScript source code (as a String) is passed to the parsejs_null_safety parser.
2. AST Generation: The parser produces an Abstract Syntax Tree (AST).
3. Interpretation: The JSInterpreter (defined in newjs_interpreter.dart) performs a recursive traversal of the AST to execute logic, calculations, and UI state bindings, resulting in Dart objects.

This model allows you to run JavaScript logic directly inside your Dart/Flutter environment without a separate JS engine.

Reusable Actions are named, parameterized workflows that can be invoked from any screen using the executeAction command. They act as self-contained units of logic that can include their own imports, global JavaScript functions, and API definitions.

There are two types of Actions:

1. App-level Actions: Defined in separate YAML files under an actions/ directory (for local apps) or within the Studio resources artifact Actions map. These are globally available.
2. Page-level Actions: Defined inline within a screen's YAML using an Action: block. Page-level actions override app-level actions if they share the same name.

Each execution of an action creates a child scope, ensuring that its inputs, imports, APIs, and Global code do not leak into the caller's scope unless explicitly communicated via events.

The behavior of the file picker changes based on the source and allowedExtensions provided:

• source: files (or omitted): Uses FileType.custom if allowedExtensions is set; otherwise, it allows any file type.
• source: gallery:
  • Maps image extensions (jpg, jpeg, png, gif, bmp) to the image picker.
  • Maps video extensions (mp4, avi, mkv, flv, wmv) to the video picker.
  • If no recognized extension is present, it picks mixed media.
• allowCompression: Defaults to true.
• allowMultiple: Defaults to false.
• Cancellation: Cancelling the picker returns no files and triggers the onError callback if provided.

The Interval class represents a time span between two DateTime objects. It provides methods for checking containment, intersection, and union of time ranges.

import 'package:ensemble_date/ensemble_date.dart';

final start = DateTime(2023, 1, 1);
final end = DateTime(2023, 1, 31);
final interval = Interval(start, end);

final dateToCheck = DateTime(2023, 1, 15);
final isIncluded = interval.includes(dateToCheck);

final otherInterval = Interval(DateTime(2023, 1, 15), DateTime(2023, 2, 1));
final intersection = interval.intersection(otherInterval);

Ensemble uses EnsembleRouteExitReason to distinguish why a route was removed. This ensures that programmatic navigation is not confused with user-initiated back actions.

Exit Reasons:

• back: A real user-initiated pop.
• replaced: The route was replaced (e.g., via Navigator.pushReplacement).
• historyReconciled: The route was removed during declarative reconciliation.
• rootCleared: The route was removed during a clear-all operation (e.g., Navigator.pushAndRemoveUntil).

Callback Behavior:

• The onNavigateBack callback is attached to the destination route's popped future.
• Crucially, onNavigateBack only executes when the recorded reason is back. It will not be invoked during reconciliation, replacement, or clear-all operations, even though those operations dispose of the route widgets normally.

The cache automatically deletes assets that have not been used for 30 days. The expiry calculation uses the following logic:

ageTimestamp = lastUsedAt ?? downloadedAt

Implications:

• Used assets: Expire 30 days after their last real use (lastUsedAt).
• Prefetched but unused assets: Expire 30 days after they were downloaded (downloadedAt).
• Cleanup process: Occurs in the background after the cache state is loaded or a new manifest is saved. It removes files from the local asset_cache/assets/ directory and removes metadata from asset-cache.json without blocking the main thread.

Screen tracking in Ensemble represents actual visibility, not just structural membership in the Navigator.

Lazy historical routes (routes reconstructed during reconciliation) behave differently than standard routes:

• Their structural didPush is ignored by the screen tracker.
• Reconciliation removal silently purges them from tracking history.
• Popping onto a lazy route removes the outgoing tracked route without restoring a stale screen.
• A Screen widget only publishes itself to the tracker when it is actually materialized and revealed to the user.

Important: Do not attempt to make screen tracking respond to every lazy route push, as this will corrupt analytics by reporting screens the user has never actually seen.