davianspace_hosting_flutter 1.0.3

Enterprise-grade Flutter integration for DavianSpace hosting, connecting DI, lifecycle management, configuration, and logging to the widget tree.

Changelog

All notable changes to davianspace_hosting_flutter are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

1.0.3 — 2025-01-01

Added

Core Widgets

• ServiceProviderScope — InheritedWidget that exposes a ServiceProvider to the widget tree.

  • of(context) — looks up the nearest scope, throws a descriptive FlutterError with fix guidance when missing.
  • maybeOf(context) — returns null when no scope exists (useful for optional feature gates).
  • Identity-based updateShouldNotify — the root provider is created once at startup, so the scope never triggers spurious rebuilds.

• HostProvider — declarative StatefulWidget managing the full host lifecycle within the widget tree:

  • hostFactory async factory creates and returns a configured Host.
  • Automatic Host.start() in initState.
  • loadingBuilder / errorBuilder callbacks for async startup states.
  • Automatic Host.stop() and Host.dispose() on widget disposal and AppLifecycleState.detached.
  • mounted guard on every setState call — safe across async gaps.
  • Idempotent shutdown — calling stop/dispose multiple times is harmless.

Context Extensions

• ServiceResolution extension on BuildContext — six ergonomic resolution methods plus direct provider access:

  Method	Delegates to
  getService<T>()	ServiceProviderBase.getRequired<T>()
  tryGetService<T>()	ServiceProviderBase.tryGet<T>()
  getAllServices<T>()	ServiceProviderBase.getAll<T>()
  getKeyedService<T>(key)	ServiceProviderBase.getRequiredKeyed<T>(key)
  tryGetKeyedService<T>(key)	ServiceProviderBase.tryGetKeyed<T>(key)
  serviceProvider	Returns the ServiceProvider directly

Entry-Point Extensions

• FlutterHostRunner extension on Host — two entry-point methods:
  • runFlutterApp(builder) — synchronous startup; host is started before runApp is called.
  • runFlutterAppAsync(builder, {loadingWidget, errorBuilder}) — calls runApp immediately and starts the host in the background. A FutureBuilder renders the loading widget, then the error builder, or finally the application widget tree.
  • Both methods wrap the app in ServiceProviderScope and install a _HostLifecycleObserver that tears down the host on dispose / AppLifecycleState.detached.

Lifecycle Management

• _HostLifecycleObserver (internal) — WidgetsBindingObserver that requests graceful shutdown via ApplicationLifetime, stops the host, and disposes the DI container when the app is detached or the widget is removed from the tree.
• Fire-and-forget async shutdown in dispose() — required because Flutter's State.dispose() is synchronous.
• Double-shutdown protection via ApplicationLifetime guard.

Quality & Documentation

• Comprehensive widget test suite — 15 tests covering scope lookup, extension resolution, host lifecycle, async startup states, keyed service access, error propagation, and lifecycle-observer shutdown.
• Enterprise-grade README with three quick-start approaches, full API reference tables, error-handling matrix, and testing guidance.
• Architecture documentation (doc/architecture.md) describing design goals, component diagram, and threading/lifecycle safety guarantees.
• Contributing guidelines, security policy, and changelog.

Ecosystem Integration

• Depends on published first-party packages:

  Package	Role
  davianspace_hosting	Host builder / lifecycle
  davianspace_dependencyinjection	Service registration & resolution
  davianspace_logging	Structured logging
  davianspace_configuration	Layered configuration

---

[Unreleased]

No unreleased changes.