feat(framework): Overhauls framework core, services, and app integration for 2.0.0

[hanskokx]

Consolidates various improvements and new features across the Arcane framework, focusing on enhanced service management, reactive updates, and a more streamlined API for application integration. This release significantly refactors core services, introduces new provider patterns, and improves overall usability and extensibility.

Key Changes

• Unified Service Management: ArcaneApp now centrally manages service registration, allowing built-in services (Arcane.features, Arcane.auth, Arcane.theme, Arcane.environment) to prefer instances registered with ArcaneApp and fall back to singletons when no provider is available.
• Reactive Core: Introduces stream-based updates for authentication (statusChanges, signedInChanges), feature flags (enabledFeaturesChanges), logging (logStream), and theming (themeModeChanges, themeDataChanges), enabling more granular and reactive UI updates.
• Logging Enhancements: Implements a robust logging interceptor system (LogInterceptor) for pre-processing log messages, provides optional lifecycle management for logging interfaces (LoggingInitializable), and adds support for tagging destinations with @LoggingFeature.
• Improved Theming: Renames ArcaneReactiveTheme to ArcaneThemeService for clarity, introduces assignment-style theme setters (Arcane.theme.dark = ...), and refines system theme following and theme mode detection logic.
• Flexible Feature Flags: Renames ArcaneFeatureFlags to ArcaneFeatureFlagService, adds ArcaneFeatureFlagProvider for widget tree integration, and provides convenient BuildContext extensions.
• Modernized Environment Management: Replaces the ArcaneEnvironment Cubit with a ValueNotifier-backed ArcaneEnvironmentService and an InheritedWidget provider, offering better integration and direct access via Arcane.environment.
• Streamlined ArcaneApp Integration: Introduces ArcaneApp.builder to provide a provider-aware BuildContext immediately at app root, deprecating the child property for improved developer experience.
• Dependency Management: Removes the direct flutter_bloc dependency and relaxes version constraints for result_monad, arcane_helper_utils, and arcane_analysis to any.

Breaking Changes

• Arcane Class: Now a static utility surface; no longer instantiable. Consumers directly importing from package:arcane_framework/src/... must update paths (e.g., src/providers/... to src/service/...).
• ArcaneApp: The child property is deprecated; prefer builder for constructing the app root with a provider-aware BuildContext.
• Service Locators: BuildContext.serviceOfType() is deprecated; use BuildContext.service() instead.
• Authentication Service: ArcaneAuthInterface.logout now accepts an optional onLoggedOut callback. Implementers must update their method signature.
• Feature Flag Service: ArcaneFeatureFlags is renamed to ArcaneFeatureFlagService. A typedef is provided for backward compatibility, but update to the new name is recommended. ArcaneFeatureFlagsScope is renamed to ArcaneFeatureFlagProvider.
• Theme Service: ArcaneReactiveTheme is renamed to ArcaneThemeService. A typedef is provided for backward compatibility, but update to the new name is recommended. The legacy ThemeMode read from Arcane.theme.systemTheme.value should be replaced with Arcane.theme.currentModeOf(context).
• Environment Service: The state getter has been removed from ArcaneEnvironment; use Arcane.environment.current instead. The AuthenticationStatus.debug status has been removed.
• Logging Interface: LoggingInterface no longer includes built-in singleton state (initialized and init getters/methods are removed). Implement LoggingInitializable for interfaces requiring setup logic.

How to Test

1. Run the example app: Navigate to example/ and run flutter run.
2. Verify Service Interactions:
   • Toggle features, environment, and theme modes using the respective cards.
   • Observe log messages in the console and the "Logging" section of the app.
   • Sign in/out and check authentication status updates.
   • Interact with the "Services" card to register/remove the custom FavoriteColorService and change colors, observing dynamic theme updates.
3. Inspect Logs: Ensure log messages appear as expected, including additional metadata (e.g., persistent metadata toggle) and proper level filtering (e.g., feature flag for logging).
4. Check UI Responsiveness: Confirm that UI elements react dynamically to changes in feature flags, environment, and theme, especially the interactive elements in the example.
5. Validate Build/Analyze: Run flutter pub get, flutter analyze, and flutter test from the root of the repository to ensure all checks pass.

Review Focus

• API Ergonomics: Review the new API patterns for ArcaneApp.builder, BuildContext extensions for services, feature flags, and themes for intuitiveness and ease of use.
• Stream Integration: Verify the correct usage and disposal of stream controllers and subscriptions for all reactive services, particularly in the example app's widget lifecycles.
• Logging Interceptors: Examine the implementation of LogInterceptor and LoggingInitializable to ensure they provide robust and flexible control over log events.
• Backward Compatibility: Confirm that typedefs and deprecated aliases for renamed services function as expected during migration, and the impact of other breaking changes is clear.
• Performance: Assess any potential performance implications from the new provider and stream architecture.
• Test Coverage: Review the updated tests for new features and refactored logic, ensuring comprehensive validation.

UI Changes

The example application has been completely refactored to demonstrate the new API. Please include before/after screenshots or GIFs of the example app's UI to visualize the changes in structure and functionality.

[Copilot]

Pull request overview

This PR is the 2.0.0 overhaul of the Arcane framework. It restructures the public surface around a static Arcane utility class plus an ArcaneApp-managed service registry, renames the core feature flag and theme services, replaces the bloc-based environment with an InheritedWidget + ValueNotifier model, and reworks logging to add LogEvent/LogInterceptor, optional LoggingInitializable lifecycle, and a lazily-recreated logStream. The example app, README, CHANGELOG, dependencies, and CI are all updated to match, and Mockito-generated mocks are replaced with mocktail + hand-written fakes.

Changes:

• Centralized service management: ArcaneApp owns a live ValueNotifier<List<ArcaneService>> registry that Arcane.features/auth/theme/environment resolve from before falling back to singletons.
• Reactive APIs across services: new statusChanges/signedInChanges/enabledFeaturesChanges/themeModeChanges/themeDataChanges/environmentChanges streams, plus LogEvent and LogInterceptor for logging.
• API renames + ergonomics: ArcaneFeatureFlags → ArcaneFeatureFlagService, ArcaneReactiveTheme → ArcaneThemeService, ArcaneApp.builder, context.service<T>(), Environment value object, deprecated typedefs/getters for compatibility.

Reviewed changes

Copilot reviewed 51 out of 53 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
lib/arcane_framework.dart	Updates public exports to new service/ and theme/ paths and new providers.
lib/src/arcane.dart	Converts Arcane to a static utility with registry-aware service getters and skipAutodetection log flag.
lib/src/arcane_app.dart	Reworks into a StatefulWidget with builder, merged built-in services, and provider composition.
lib/src/service/arcane_service.dart	New base class with ofType/requiredOfType helpers; parts in service_provider + extensions.
lib/src/service/service_provider.dart	New InheritedNotifier-based provider with mutation helpers.
lib/src/service/service_provider_extensions.dart	Adds service<T>/requiredService<T> and deprecates serviceOfType<T>.
lib/src/providers/service_provider.dart	Removes the legacy provider implementation.
lib/src/services/authentication/authentication_service.dart	Adds streams, removes debug status coupling, simplifies setDebug/setNormal; introduces a missing-return bug on logOut.
lib/src/services/authentication/authentication_interface.dart	Adds optional onLoggedOut/onLoggedIn callbacks to interface.
lib/src/services/authentication/authentication_enums.dart	Drops AuthenticationStatus.debug and the Environment enum.
lib/src/services/environment/environment_service.dart	New singleton service backed by ValueNotifier + broadcast stream.
lib/src/services/environment/environment_provider.dart	Syncs InheritedWidget with the new service and exposes setEnvironment.
lib/src/services/environment/environment_interface.dart	New Environment value object with built-in debug/normal.
lib/src/services/feature_flags/feature_flags_service.dart	Renames service, adds enabledFeaturesChanges, reworks reset/listener semantics.
lib/src/services/feature_flags/feature_flags_provider.dart	New InheritedWidget + StatefulWidget providers with deprecated alias typedef.
lib/src/services/feature_flags/feature_flags_context_extensions.dart	New BuildContext helpers for feature flags.
lib/src/services/feature_flags/feature_flags_extensions.dart	Updates doc references to new service name.
lib/src/services/logging/logging_service.dart	Adds interceptors, per-interface registration, lazy logStream, optional initialization.
lib/src/services/logging/logging_interface.dart	Removes singleton lifecycle; adds LoggingInitializable/LoggingInitialization/@LoggingFeature.
lib/src/services/logging/log_event.dart	New LogEvent value object with sentinel-based copyWith.
lib/src/services/logging/log_interceptor.dart	New interceptor type + context; doc example uses wrong callback signature.
lib/src/services/theme/theme_service.dart	New ArcaneThemeService with effective-mode toggling, assignment setters, lazy streams.
lib/src/services/theme/theme_switcher.dart	Subscribes to streams and triggers system-follow on first dependency resolution.
lib/src/services/theme/theme_extensions.dart	Switches isDarkMode to effective theme brightness.
lib/src/services/theme/arcane_theme.dart	Minor constructor reorder.
lib/src/services/reactive_theme/reactive_theme_service.dart	Removes legacy reactive theme implementation.
test/*	Replaces Mockito-generated mocks with mocktail/hand-written fakes; adds coverage for streams, providers, interceptors, environment switching, theme regressions.
example/**	Rewrites example app to demonstrate new APIs, providers, and stream lifecycles.
README.md / CHANGELOG.md	Comprehensive rewrite covering new APIs and migration steps.
pubspec.yaml	Drops flutter_bloc, mockito, build_runner, dependency_overrides; loosens version pins.
.github/workflows/analyze-and-unit-test.yaml	Adds a build_runner step that conflicts with the dropped dependency.
.puro.json / .gitignore / example/.vscode/launch.json	Tooling and ignore-list adjustments.

Comments suppressed due to low confidence (1)

.github/workflows/analyze-and-unit-test.yaml:33

• This CI step runs dart run build_runner build -d, but build_runner has been removed from pubspec.yaml's dev_dependencies and the repository no longer contains any @GenerateMocks/@GenerateNiceMocks annotations (the generated *.mocks.dart files were deleted as part of this PR). Running this command in CI will fail with a "Could not find package 'build_runner'" error and there is nothing for it to generate. Either remove this CI step or re-add build_runner to dev_dependencies if it is still required for some other purpose.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 51 out of 53 changed files in this pull request and generated 5 comments.