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

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

@@ -2,34 +2,20 @@ name: Tests
 on:
   workflow_dispatch:
   pull_request:
-env:
-  PURO_FLUTTER_VERSION: ""
-  FLUTTER_VERSION: ""
 jobs:
   test:
     name: Analyze and test
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
-      - name: Get Flutter version from .puro.json
-        id: puro_version
-        run: |
-          if [[ -f ".puro.json" ]]; then
-            flutter_version=$(jq -r '.env' .puro.json)
-            echo "PURO_FLUTTER_VERSION=$flutter_version" >> $GITHUB_ENV
-          else
-            echo "Warning: .puro.json not found, using default Flutter stable channel."
-            echo "PURO_FLUTTER_VERSION=stable" >> $GITHUB_ENV
-          fi
       - name: Setup Flutter
         uses: subosito/flutter-action@v2
         with:
           channel: "stable"
-          flutter-version: ${{ env.PURO_FLUTTER_VERSION == 'stable' && '' || env.FLUTTER_VERSION }}
       - name: Install dependencies
         run: flutter pub get
       - name: Analyze
         run: flutter analyze
       - name: Test
-        run: flutter test
+        run: flutter test

.gitignore

@@ -19,7 +19,7 @@ migrate_working_dir/
 # The .vscode folder contains launch configuration and tasks you configure in
 # VS Code which you may wish to be included in version control, so this line
 # is commented out by default.
-#.vscode/
+.vscode/
 
 # Flutter/Dart/Pub related
 # Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
@@ -51,5 +51,6 @@ app.*.map.json
 **/android/app/profile
 **/android/app/release
 
-# Puro
-!/.puro.json
+# Example builds
+**/example/.metadata
+**/example/web/

CHANGELOG.md

@@ -1,72 +1,258 @@
-## 2.0.0-dev
+## Unreleased
+
+### Arcane Framework
+
+- [NEW] `ArcaneApp` now owns and publishes a live service registry for
+  provider-aware static lookups.
+- [CHANGE] `Arcane.features`, `Arcane.auth`, `Arcane.theme`, and
+  `Arcane.environment` now prefer the live `ArcaneApp` registry instance when
+  available, then fall back to built-in singletons.
+- [BREAKING] `Arcane` is now a static utility surface (no instantiable
+  singleton constructor).
+- [BREAKING] Several `package:arcane_framework/src/...` import paths changed
+  (for example, `src/providers/...` -> `src/service/...` and
+  `src/services/reactive_theme/...` -> `src/services/theme/...`). Consumers
+  importing from `src` directly must update import paths.
+- [NEW] Added optional `ArcaneApp.builder` callback (TransitionBuilder style)
+  for capturing provider-aware build contexts from within `ArcaneApp`.
+- [DEPRECATED] `ArcaneApp.child` is now deprecated in favor of
+  `ArcaneApp.builder` (legacy child usage remains supported during migration).
+- [DEPRECATED] `BuildContext.serviceOfType<T>()` is now deprecated in favor of
+  `BuildContext.service<T>()`.
+
+### Environment Service
+
+- [NEW] Added `ArcaneEnvironmentService` as a singleton `ArcaneService` instance.
+- [CHANGE] Changed `ArcaneEnvironment` is no longer a `Cubit` and is now an
+  `InheritedWidget`.
+- [NEW] Added `Arcane.environment` shortcut for direct environment access.
+- [NEW] Added environment service to `Arcane.services` built-in list.
+- [CHANGE] `ArcaneEnvironmentProvider` is now a `StatefulWidget` instead of a
+  `StatelessWidget` with a `BlocProvider`.
+- [NEW] `ArcaneEnvironmentProvider` now provides methods for
+  `enableDebugMode()`, `disableDebugMode()` and `setEnvironment()`.
+- [NEW] Added `environmentChanges` stream for realtime environment updates.
+
+#### Migration Steps (ArcaneEnvironment)
+
+1. The `state` getter has been removed from `ArcaneEnvironment`. If you previously accessed environment state via `Arcane.environment.state`, update your code to use the new API:
+
+   - **Before:**
+
+     ```dart
+     final env = Arcane.environment.state;
+     ```
+
+   - **After:**
+
+     ```dart
+     final env = Arcane.environment.current;
+     ```
+
+2. If you were using `Cubit`-style APIs, migrate to the new `InheritedWidget`/`ValueNotifier`-based approach. See the README for updated usage examples.
+
+### Authentication Service
+
+- [BREAKING] `ArcaneAuthInterface.logout` now accepts optional
+  `onLoggedOut` callback parameters. `ArcaneAuthInterface` implementers must
+  update logout signature to accept optional `onLoggedOut`. See the migration
+  steps for further details.
+- [NEW] Added `statusChanges` stream to observe `AuthenticationStatus` updates.
+- [NEW] Added `signedInChanges` stream to observe sign-in state changes.
+- [FIX] Added stream lifecycle cleanup in `dispose` with safe lazy recreation.
+
+#### Migration Steps (ArcaneAuthInterface)
+
+1. Update `ArcaneAuthInterface` implementations to accept the new optional
+   `onLoggedOut` callback parameter in `logout(...)`.
+2. If your implementation performs cleanup side effects on logout, invoke
+   `onLoggedOut` when provided.
+3. Run tests to confirm your authentication adapter still satisfies your
+   login/logout flows.
+
+Before:
 
-### Arcane
-
-- [FIX] The `Arcane` class is now `abstract`
-
-### ArcaneEnvironment
-
-- [CHANGE] The dependency on `flutter_bloc` has been removed.
-- [CHANGE] The feature has been completely rewritten as an inherited widget, rather than using a `Cubit`.
-- [NEW] The `ArcaneEnvironment` widget now includes the `maybeOf(context)` and `of(context)` service locators.
-- [NEW] An `ArcaneEnvironmentProvider` widget has been added. This is used by `ArcaneApp` but can also be used independently when not using the `ArcaneApp` widget.
-- [NEW] The `ArcaneEnvironment`
+```dart
+@override
+Future<Result<void, String>> logout() async {
+  // ...
+  return Result.ok(null);
+}
+```
 
-### ArcaneServiceProvider
+After:
 
-- [BREAKING] `ArcaneServiceProvider.of(context)` now returns a nullable instance, rather than throwing an exception.
+```dart
+@override
+Future<Result<void, String>> logout({
+  Future<void> Function()? onLoggedOut,
+}) async {
+  // ...
+  if (onLoggedOut != null) await onLoggedOut();
+  return Result.ok(null);
+}
+```
 
-### Authentication Service (ArcaneAuth)
+### Feature Flag Service
+
+- [CHANGE] Renamed service class `ArcaneFeatureFlags` to
+  `ArcaneFeatureFlagService`.
+- [NEW] Added backward compatibility typedef:
+  `typedef ArcaneFeatureFlags = ArcaneFeatureFlagService`.
+- [NEW] Added `enabledFeaturesChanges` stream to observe enabled feature
+  updates in realtime.
+- [FIX] Added stream lifecycle cleanup in `dispose` with safe lazy recreation.
+- [NEW] Added `ArcaneFeatureFlagProvider` (`InheritedWidget`) and
+  `ArcaneFeatureFlagsProvider` (`StatefulWidget`) for first-class feature-flag
+  integration in the widget tree.
+- [DEPRECATED] `ArcaneFeatureFlagsScope` has been renamed to
+  `ArcaneFeatureFlagProvider`.
+- [NEW] Added `BuildContext` convenience accessors for feature flags, including
+  `context.featureFlags`, `context.maybeFeatureFlags`,
+  `context.isFeatureEnabled(...)`, and `context.isFeatureDisabled(...)`.
+- [NEW] `ArcaneApp` now includes `ArcaneFeatureFlagsProvider` by default,
+  enabling rebuilds for widgets that depend on
+  `ArcaneFeatureFlagProvider.of(context)`.
+- [UPDATE] README now documents `ArcaneFeatureFlagProvider` and `ArcaneApp`
+  provider composition.
+
+### Theme Service
+
+- [CHANGE] Renamed `ArcaneReactiveTheme` to `ArcaneThemeService` for clearer
+  naming.
+- [NEW] Added backward compatibility typedef:
+  `typedef ArcaneReactiveTheme = ArcaneThemeService`.
+- [FIX] Theme initialization now respects `ThemeMode.system` and initializes
+  `ThemeData` using the effective brightness.
+- [FIX] `ArcaneThemeSwitcher` now initializes system-follow behavior once on
+  first dependency resolution.
+- [FIX] `ArcaneThemeSwitcher` now defaults to `followSystemTheme(context)` when
+  mounted under `ArcaneApp`, so system-follow is enabled by default and system
+  brightness changes are handled framework-side (no app-level observer needed).
+- [FIX] `switchTheme()` now toggles from the effective theme when current mode
+  is `ThemeMode.system` (system dark -> light, system light -> dark).
+- [CHANGE] `context.isDarkMode` now reflects effective app theme brightness
+  (`Theme.of(context).brightness`) instead of raw platform brightness.
+- [FIX] `followSystemTheme()` now reads platform brightness directly to avoid
+  coupling system-follow behavior to app theme overrides.
+- [NEW] Added assignment-style theme setters: `Arcane.theme.dark = ...` and
+  `Arcane.theme.light = ...` (in addition to `setDarkTheme` /
+  `setLightTheme`).
+- [FIX] Reactive theme stream controllers now close only during service dispose,
+  preventing stream shutdown when a single subscriber cancels.
+- [FIX] Setting a theme (e.g., dark) while in the opposite mode (e.g., light) no
+  longer changes the current brightness or rendered theme. Only the active
+  mode's theme updates the rendered appearance.
+- [NEW] Added `themeModeChanges` and `themeDataChanges` streams for realtime
+  theme updates.
+
+#### Migration Steps (ArcaneThemeService)
+
+1. Replace legacy `ThemeMode` reads from `Arcane.theme.systemTheme.value` with
+  `Arcane.theme.currentModeOf(context)` when configuring app `themeMode`.
+
+Before:
 
-- [FIX] Switching between `Environment.normal` and `Environment.debug` now correctly notifies subscribers
-- [BREAKING] Switching between environments now remembers the previous authentication status (e.g., switching to debug mode and then back to normal mode will now remember whether you were authenticated or unauthenticated in normal mode when you switched to debug mode.)
+```dart
+MaterialApp(
+  theme: Arcane.theme.light,
+  darkTheme: Arcane.theme.dark,
+  themeMode: Arcane.theme.systemTheme.value,
+)
+```
 
-### Feature Flags Service (ArcaneFeatureFlags)
+After:
 
-- [NEW] A `reset` method has been added, which will remove all enabled features and de-initialize the service.
+```dart
+MaterialApp(
+  theme: Arcane.theme.light,
+  darkTheme: Arcane.theme.dark,
+  themeMode: Arcane.theme.currentModeOf(context),
+)
+```
 
-### Logging Service (ArcaneLogger)
+### Arcane Logger
+
+- [NEW] Added `logStream` for realtime log subscriptions.
+- [NEW] Added explicit `dispose` cleanup for logger stream resources.
+- [BREAKING] `LoggingInterface` no longer includes built-in singleton-style
+  initialization state.
+- [NEW] Added optional lifecycle capability via `LoggingInitializable` and
+  `LoggingInitialization`.
+- [NEW] Added optional `feature` tag support via `@LoggingFeature(...)`
+  annotation.
+- [CHANGE] `initializeInterfaces()` now initializes only interfaces that
+  implement `LoggingInitializable`; other interfaces are skipped.
+- [NEW] Added a `skipAutodetection` parameter to `Arcane.log` (defaults to
+  `false`) that, when enabled, skips detection of the `module`, `method`, and
+  file/line number where logs originated from.
+- [NEW] Added the `LogInterceptor` class which can (optionally) be added to
+  `ArcaneLogger` to pre-process log messages before they are sent to the
+  registered `ArcaneLoggingInterface`(s).
+
+#### Migration Steps (LoggingInterface)
+
+1. Remove `initialized` and `init` from interfaces that do not require startup
+  work.
+2. If an interface requires startup/lifecycle management, add
+  `LoggingInitialization` (or implement `LoggingInitializable`) and move
+  setup logic into `init()`.
+3. Update `log(...)` implementations to guard behavior with `initialized` only
+  for interfaces that opted into initialization.
+4. Run tests to verify interface registration and logging behavior still match
+  expectations.
+
+Before:
 
-- [NEW] A `logStream` has been added. This will stream all log messages that are sent to `ArcaneLogger`. These messages are not processed by any registered `LoggingInterface`.
-- [BREAKING] Invoking the `log` method no longer throws an exception if `ArcaneLogger` has not been initialized. Log messages will always be sent to the `logStream` and will only be sent to the registered `LoggingInterface`s if the `init` method has ben invoked.
-- [FIX] Automatic file and line number detection has been improved, both in terms of performance and in reliability.
-- [NEW] In addition to the existing `registerInterfaces` method, a new `registerInterface` method has been added.
-- [NEW] The following methods have been added: `unregisterInterface`, `unregisterInterfaces`, and `unregisterAllInterfaces`.
-- [NEW] Added a `reset` method that clears all registered interfaces, clears all persistent metadata, and de-initializes `ArcaneLogger`
+```dart
+class DebugConsole implements LoggingInterface {
+  @override
+  bool get initialized => true;
 
-### Theme (ArcaneTheme)
+  @override
+  Future<LoggingInterface?> init() async => this;
 
-- [NEW] Added the `ArcaneTheme` inherited widget
-- [NEW] Added `themeMode` extension to `BuildContext` to get the current `ThemeMode` (e.g., light/dark)
-- [BREAKING] Completely rewrote `ArcaneReactiveTheme`
-- [NEW] Added the `ArcaneThemeSwitcher` widget.
+  @override
+  void log(String message, {Map<String, Object?>? metadata, Level? level}) {}
+}
+```
 
-#### ArcaneReactiveTheme
+After:
 
-- [NEW] The `isFollowingSystemTheme` getter has been added.
-- [NEW] The `themeModeChanges` getter will stream events when the `ThemeMode` changes (e.g., light/dark)
-- [NEW] The `themeDataChanges` getter will stream events when the current `ThemeData` changes
-- [NEW] The `systemThemeMode` getter will return the OS-level brightness (e.g., light/dark)
-- [BREAKING] The `currentMode` getter was renamed to `currentThemeMode`
-- [NEW] The `currentTheme` getter was added to retrieve the current `ThemeData`.
-- [BREAKING] The `systemTheme` getter was replaced by the `systemThemeMode` getter
-- [NEW] A `currentModeOf(context)` getter was added. Using this value will trigger a rebuild when the mode changes.
-- [CHANGE] The `switchTheme` method now (optionally) takes in a `ThemeMode` parameter. If it is omitted, the new mode will be automatically determined.
-- [FIX] The `followSystemTheme` method will now correctly trigger widget rebuilds under the correct circumstances.
-- [FIX] Invoking the `setDarkTheme` and `setLightTheme` methods will trigger widget rebuilds under the correct circumstances.
+```dart
+class DebugConsole extends LoggingInterface {
+  @override
+  void log(String message, {Map<String, Object?>? metadata, Level? level}) {}
+}
+```
 
-#### ArcaneThemeSwitcher
+- For SDK-backed loggers, opt into initialization with the mixin.
 
-- [NEW] This new widget will, when added to the widget tree, trigger rebuilds when the theme mode or theme style is updated via `ArcaneTheme`/`ArcaneReactiveTheme`.
-- [NEW] This widget has been added to `ArcaneApp`.
+```dart
+class ExternalLogger extends LoggingInterface with LoggingInitialization {
+  @override
+  Future<void> init() async {
+    if (initialized) return;
+    // Start SDK.
+    await super.init();
+  }
 
-### Testing
+  @override
+  void log(String message, {Map<String, Object?>? metadata, Level? level}) {
+    if (!initialized) return;
+    // Send to SDK.
+  }
+}
+```
 
-- [NEW] Tests have been written for much of the framework.
+- If desired, adopt `feature` for destination-aware filtering in interceptors.
 
-### Example
+### Dependencies
 
-- [FIX] The example has been completely reworked. It now includes examples of all features that Arcane has to offer
+- [CHANGE] Relaxed `result_monad` constraint from `^2.3.2` to `any`.
+- [CHANGE] Removed direct `flutter_bloc` dependency.
+- [CHANGE] Updated `collection` from `^1.18.0` to `^1.19.0`.
+- [CHANGE] Relaxed `arcane_helper_utils` constraint from `^1.4.7` to `any`.
 
 ## 1.2.5