ensemble

ensemble is the core Flutter runtime for Ensemble's declarative app definitions.

Overview

This is a core runtime package. It loads Ensemble configuration, initializes providers and managers, interprets Ensemble definitions, registers widgets and actions, and exposes navigation helpers used by host apps such as starter.

Features

  • Provides the Ensemble singleton and EnsembleConfig model in lib/ensemble.dart.
  • Initializes Ensemble managers, configuration services, local assets, API providers, Firebase, and analytics providers.
  • Defines core actions such as navigation, timers, code execution, URL opening, file upload, OAuth, sockets, permissions, camera, Plaid, and authentication actions.
  • Maintains the core widget registry, including optional module extension points resolved through GetIt.

Installation / Setup

Add the runtime to a Flutter host app:

flutter pub add ensemble

For local development inside this repository, bootstrap the Melos workspace:

melos bootstrap

Usage

A source-verified host-app pattern is shown in starter/lib/main.dart:

await EnsembleModules().init();
runApp(EnsembleApp());

starter/lib/integrate_existing_app_with_Ensemble.dart also shows Ensemble().initialize() and Ensemble().navigateApp(context) for integrating Ensemble into an existing Flutter app.

Configuration

Configuration is loaded through EnsembleConfigService and EnsembleConfig in lib/ensemble.dart. Host apps provide app IDs, local or remote definitions, Firebase options, providers, secrets, and module registration through the starter app or generated module files.

When definitions.from is ensemble, the runtime initializes Firebase with the bundled public Ensemble project options in lib/firebase_options.dart. Firebase API keys identify the public demo project and are not treated as secrets; production host apps should provide their own project configuration where needed.

Platform Support

Platform Supported Notes
Android Unknown This package has no Android project; support depends on the host Flutter app.
iOS Unknown This package has no iOS project; support depends on the host Flutter app.
Web Unknown This package has no Web project; support depends on the host Flutter app.
macOS Unknown This package has no macOS project; support depends on the host Flutter app.
Windows Unknown This package has no Windows project; support depends on the host Flutter app.
Linux Unknown This package has no Linux project; support depends on the host Flutter app.

Permissions

No package-level platform manifests were found. Runtime actions and optional modules may require host-app permissions for camera, location, contacts, files, notifications, authentication, or other native capabilities.

API Reference

API Type Description
Ensemble Singleton class Initializes runtime services and provides navigation helpers.
EnsembleConfig Class Runtime configuration model.
EnsembleAction Base class Base for core action execution.
ActionType Enum Defines core action names parsed by the runtime.
widget_registry.dart Registry Maps Ensemble widget types to Flutter widget factories and optional module implementations.

Development

melos bootstrap
melos exec --scope="ensemble" -- flutter analyze
melos exec --scope="ensemble" -- flutter test

Testing

This package has a substantial test/ directory. Run package tests with melos exec --scope="ensemble" -- flutter test.

Additional technical documentation

  • Reusable Actions — app-level and page-level Actions, executeAction, scoped Import/Global/API, and events.
  • Layout widgets (tabs, ListView scroll) — EDL layout behavior in lib/layout.
  • Runtime security and data bindings — screen id validation for definition providers, saveFile naming, multipart upload path checks, ensemble.storage.clear() behavior and binding refresh, WebView TLS/reputation settings, global script handler payloads, and device metric bindings after rotation.

Related Packages / Modules

  • starter: host app template that initializes EnsembleModules and EnsembleApp.
  • Optional modules under modules/ implement runtime stubs and widgets resolved by this package.
  • Packages under packages/ provide supporting UI, parser, date, and integration utilities.

Notes for Contributors

  • Keep examples in sync with source code.
  • Update this README when public APIs, permissions, configuration, or platform support changes.
  • Do not document unverified behavior.

Libraries

action/action_invokable
action/action_scope_util
action/app_setting
action/audio_player
action/badge_action
action/biometric_auth_action
action/bluetooth_action
action/bottom_sheet_actions
action/call_external_method
action/call_native_method
action/change_locale_actions
action/close_app
action/connectivity_action
action/device_security
action/dialog_actions
action/disable_hardware_navigation
action/drawer_actions
action/execute_action
action/execute_action_group_action
action/face_camera_actions
action/file_picker_action
action/get_network_info_action
action/getLocation
action/haptic_action
action/invoke_api_action
action/key_chain_actions
action/Log_event_action
action/misc_action
action/notification_actions
action/phone_contact_action
action/saveFile/download_stub
action/saveFile/download_web
action/saveFile/save_file
action/saveFile/save_mobile
action/secure_storage
action/sign_in_out_action
action/sign_in_with_verification_code_actions
action/stripe_actions
action/take_screenshot
action/toast_actions
action/upload_files_action
action/wakelock_action
action/wifi_action
controller/controller_mixins
ensemble
ensemble_app
ensemble_theme
firebase_options
framework/action
framework/all_countries
framework/apiproviders/api_provider
framework/apiproviders/firebase_functions/firebase_functions_api_provider
framework/apiproviders/firestore/firestore_api_provider
framework/apiproviders/firestore/firestore_app
framework/apiproviders/firestore/firestore_test_app
framework/apiproviders/firestore/firestore_types
framework/apiproviders/http_api_provider
framework/apiproviders/sse_api_provider
framework/app_info
framework/assets_service
framework/bindings
framework/cdn_asset_cache
framework/config
framework/config/url_parser_native
framework/config/url_parser_web
framework/data_context
framework/data_utils
framework/definition_providers/cdn_provider
framework/definition_providers/ensemble_provider
framework/definition_providers/host_cache_provider
framework/definition_providers/local_provider
framework/definition_providers/provider
framework/definition_providers/remote_provider
framework/definition_providers/screen_selector_security
framework/definition_providers/validation_provider
framework/device
framework/devmode
framework/dotenv_bundle
framework/encrypted_storage_manager
framework/ensemble_config_service
framework/ensemble_widget
framework/error_handling
framework/event
framework/event/change_locale_events
framework/extensions
framework/i18n_loader
framework/keychain_manager
framework/logging/console_log_provider
framework/logging/log_manager
framework/logging/log_provider
framework/model
framework/model/supported_language
framework/notification_manager
framework/permissions_manager
framework/route_observer
framework/scope
framework/screen_tracker
framework/secrets
framework/semantics_utils
framework/services/aria_label/aria_label_service
framework/services/aria_label/aria_label_service_stub
framework/services/aria_label/aria_label_service_web
framework/storage_manager
framework/stub/adobe_manager
framework/stub/analytics_provider
framework/stub/auth_context_manager
framework/stub/bluetooth
framework/stub/camera_manager
framework/stub/contacts_manager
framework/stub/ensemble_bracket
framework/stub/ensemble_chat
framework/stub/face_camera_manager
framework/stub/file_manager
framework/stub/location_manager
framework/stub/moengage_manager
framework/stub/network_info
framework/stub/oauth_controller
framework/stub/qr_code_scanner
framework/stub/remote_config
framework/stub/stripe_manager
framework/stub/token_manager
framework/stub/wifi_manager
framework/studio/studio_debugger
framework/studio/widget_layout_helper
framework/theme/default_theme
framework/theme/theme_loader
framework/theme/theme_manager
framework/theme_manager
framework/view/bottom_nav_page_group
framework/view/bottom_nav_page_view
framework/view/data_scope_widget
framework/view/has_selectable_text
framework/view/page
framework/view/page_group
framework/widget/colored_box_placeholder
framework/widget/custom_ink_splash
framework/widget/error_screen
framework/widget/has_children
framework/widget/icon
framework/widget/image
framework/widget/screen
framework/widget/toast
framework/widget/view_util
framework/widget/wallet_connect_modal
framework/widget/widget
host_platform_manager
html_shim
layout/app_scroller
layout/box/base_box_layout
layout/box/box_layout
layout/box/box_utils
layout/box/fitted_box_layout
layout/box/flex_box_layout
layout/data_grid
layout/ensemble_page_route
layout/flow
layout/form
layout/grid_view
layout/helpers/list_view_core
layout/list_view
layout/scroll_view
layout/stack
layout/tab/base_tab_bar
layout/tab/scrollable_tab_bar
layout/tab/tab_bar_controller
layout/tab_bar
layout/templated
layout/toggle_container
model/capabilities
model/item_template
model/pull_to_refresh
model/text_scale
model/transform_matrix
model/widget_models
module/auth_module
module/location_module
module/stripe_module
page_model
receive_intent_manager
screen_controller
util/chart_utils
util/debouncer
util/ensemble_utils
util/extensions
util/gesture_detector
util/input_formatter
util/input_validator
util/layout_utils
util/moengage_utils
util/notification/notification_base
util/notification/notification_mobile
util/notification/notification_web
util/notification_utils
util/platform
this is not meant to be used alone, but works in conjunction with platform_web.dart
util/platform_stub
util/platform_web
only import on web platform, use in conjunction with platform_stub.dart
util/upload_utils
util/utils
util/yaml_util
widget/accordion
widget/address
widget/address_url_builder
widget/avatar
widget/button
widget/calendar
widget/chart_highcharts_builder
widget/checkbox
widget/conditional
widget/confirmation_input
widget/countdown
widget/custom_widget/custom_widget
widget/custom_widget/custom_widget_model
widget/divider
widget/ensemble_icon
widget/external_widget
widget/fintech/finicityconnect/finicityconnect
widget/fintech/finicityconnect/finicityconnectstate
widget/fintech/finicityconnect/native/finicityconnectstate
widget/fintech/finicityconnect/native/unsupportedfinicityconnectstate
widget/fintech/finicityconnect/web/finicityconnectstate
widget/fintech/tabapayconnect
widget/form_daterange
widget/helpers/box_animation_composite
widget/helpers/box_wrapper
widget/helpers/ColorFilter_Composite
widget/helpers/controllers
This class contains helper controllers for our widgets.
widget/helpers/form_helper
widget/helpers/HasTextPlaceholder
widget/helpers/input_field_helper
widget/helpers/input_wrapper
widget/helpers/pull_to_refresh_container
widget/helpers/text_selection_helper
widget/helpers/tooltip_composite
This class contains helper controllers for our widgets.
widget/helpers/unfocus
widget/helpers/widgets
This class contains common widgets for use with Ensemble widgets.
widget/html
widget/icon_button
widget/image
widget/image_cropper
widget/input/form_date
widget/input/form_textfield
widget/input/form_time
widget/input/slider/composites/overlay_style
widget/input/slider/composites/thumb_style
widget/input/slider/composites/tick_mark_style
widget/input/slider/composites/track_style
widget/input/slider/composites/value_indicator_style
widget/input/slider/slider
widget/input/slider/slider_controller
widget/input/slider/slider_state
widget/input/taginput/taginput
widget/loading_container
widget/lottie/lottie
widget/lottie/lottiestate
widget/lottie/native/lottiestate
widget/lottie/web/lottiestate
widget/markdown
widget/progress_indicator
widget/qr_code
widget/radio/custom_radio_tile
widget/radio/radio_button
widget/radio/radio_button_controller
widget/radio/radio_group
widget/radio/styled_radio
widget/rating
widget/shape
widget/signature
widget/slidable
widget/spacer
widget/staggered_grid
widget/static_map
widget/stub_widgets
widget/switch
widget/text
widget/text/expandable_text
widget/text/span_definition
widget/Toggle
widget/toggle_button
widget/video
widget/visualization/barchart
widget/visualization/chart_defaults
widget/visualization/chart_js/chart_js
widget/visualization/chart_js/chart_js_state
widget/visualization/chart_js/native/chart_js_state
widget/visualization/chart_js/native/unsupported_chart_js_state
widget/visualization/chart_js/web/chart_js_state
widget/visualization/diagram
widget/visualization/line_area_chart
widget/visualization/topology_chart
widget/webview/native/unsupportedwebview
widget/webview/native/webviewstate
widget/webview/web/webviewstate
widget/webview/webview
widget/webview/webviewstate
widget/weeklyscheduler
widget/widget_registry
widget/widget_util
widget/youtube/native/unsupported_platform
widget/youtube/native/youtube_platform_native
widget/youtube/web/youtube_platform_web
widget/youtube/youtube
widget/youtube/youtubestate