refactor: slim machine API and remove built-in devtools (#33)

* refactor: remove built-in devtools layer

* refactor(machine): simplify to command-only runtime API

* refactor(api): tighten machine dispatch and public surface

Author: medz

CHANGELOG.md

@@ -1,5 +1,17 @@
 ## Unreleased
 
+### Changed
+
+- Removed `package:unrouter/devtools.dart` and all built-in inspector/replay
+  implementations to keep the package focused on core routing and machine APIs.
+- Simplified docs, tests, and example app to match the slimmer public surface.
+- Simplified machine API to command-first dispatch by removing declarative
+  action/envelope layers and related schema contracts.
+- Tightened machine/controller public surface: merged dispatch entrypoint into
+  `machine.dispatch<T>()`, removed `typedTimeline`, removed public
+  `routeRequest` command, and stopped exporting controller lifecycle/composer
+  APIs from `package:unrouter/unrouter.dart`.
+
 ## 0.8.0
 
 ### Added

README.md

@@ -7,7 +7,7 @@ A URL-first typed router for Flutter.
 - Typed route objects via `RouteData`
 - Route matching powered by `roux`
 - Browser history integration via `unstory`
-- Core API by default, optional machine and devtools layers
+- Core API by default with an optional machine layer
 
 ## Install
 
@@ -18,8 +18,7 @@ flutter pub add unrouter
 ## Entrypoints
 
 - `package:unrouter/unrouter.dart`: core routing API
-- `package:unrouter/machine.dart`: machine commands/actions
-- `package:unrouter/devtools.dart`: inspector/panel/replay tooling
+- `package:unrouter/machine.dart`: machine commands
 
 Import `unrouter.dart` explicitly. Other entrypoints do not re-export core APIs.
 
@@ -85,14 +84,11 @@ flutter pub get
 flutter run -d chrome
 ```
 
-Open `/debug` (or tap the bug icon) for inspector/panel/replay diagnostics.
-
 ## Docs
 
 - Overview: `doc/README.md`
 - Getting started: `doc/getting_started.md`
 - Core routing: `doc/core_routing.md`
 - Machine API: `doc/machine_api.md`
-- Devtools: `doc/devtools.md`
-- Contracts: `doc/state_envelope.md`, `doc/machine_action_envelope_schema.md`
+- Contracts: `doc/state_envelope.md`
 - Benchmark guide: `doc/router_benchmarking.md`

doc/README.md

@@ -8,17 +8,11 @@ This folder contains user-facing guides and reference notes for `unrouter`.
   and wire `MaterialApp.router`.
 - [Core routing guide](core_routing.md): route definitions, guards, redirects,
   loaders, and shell branches.
-- [Machine API guide](machine_api.md): typed command/action dispatch and action
-  envelope flows.
-- [Devtools guide](devtools.md): inspector widget, bridge, panel, replay, and
-  `/debug` integration.
+- [Machine API guide](machine_api.md): typed command dispatch and machine
+  timeline usage.
 - [Router benchmarking](router_benchmarking.md): behavior parity and performance
   comparison workflow.
 
 ## Reference contracts
 
 - [State envelope](state_envelope.md): `history.state` format and compatibility.
-- [Machine action envelope schema](machine_action_envelope_schema.md): schema
-  and event version contract for machine action envelopes.
-- [Replay persistence examples](replay_persistence_examples.md): storage adapter
-  patterns for replay persistence.

doc/devtools.md

@@ -14,8 +14,7 @@ import 'package:unrouter/unrouter.dart';
 
 Use additional entrypoints only when needed:
 
-- `package:unrouter/machine.dart`: machine command/action APIs.
-- `package:unrouter/devtools.dart`: inspector, panel, and replay tooling.
+- `package:unrouter/machine.dart`: machine command APIs.
 
 ## Minimal typed router
 
@@ -79,5 +78,4 @@ context.unrouter.pop(7);
 ## Next reads
 
 - Core behavior and advanced route features: `doc/core_routing.md`
-- Debug and diagnostics tooling: `doc/devtools.md`
-- Command/action machine API: `doc/machine_api.md`
+- Command machine API: `doc/machine_api.md`

doc/getting_started.md

@@ -13,66 +13,29 @@ import 'package:unrouter/unrouter.dart';
 final machine = context.unrouterMachineAs<AppRoute>();
 ```
 
-## Dispatch typed commands
+## Dispatch commands
 
 ```dart
-machine.dispatchTyped<void>(UnrouterMachineCommand.goUri(Uri(path: '/')));
-final pushed = machine.dispatchTyped<Future<Object?>>(
+machine.dispatch<void>(UnrouterMachineCommand.goUri(Uri(path: '/')));
+final pushed = machine.dispatch<Future<Object?>>(
   UnrouterMachineCommand.pushUri(Uri(path: '/users/42')),
 );
-final canBack = machine.dispatchTyped<bool>(UnrouterMachineCommand.back());
-```
-
-## Dispatch declarative actions
-
-```dart
-machine.dispatchAction<void>(
-  UnrouterMachineAction.navigateRoute(
-    const UserRoute(id: 7),
-    mode: UnrouterMachineNavigateMode.replace,
-  ),
-);
-```
-
-## Use action envelopes
-
-Action envelopes expose explicit state for command outcomes:
-
-- `accepted`
-- `rejected`
-- `deferred`
-- `completed`
-
-```dart
-final envelope = machine.dispatchActionEnvelope<Future<int?>>(
-  UnrouterMachineAction.pushRoute<UserRoute, int>(const UserRoute(id: 8)),
-);
-
-if (envelope.isDeferred) {
-  final value = await envelope.value;
-  debugPrint('deferred value: $value');
-}
-
-if (envelope.isRejected) {
-  debugPrint('reject code: ${envelope.rejectCode}');
-  debugPrint('reject failure: ${envelope.failure?.toJson()}');
-}
+final canBack = machine.dispatch<bool>(UnrouterMachineCommand.back());
 ```
 
 ## Inspect machine state and transitions
 
 ```dart
 final machineState = machine.state;
 final rawTimeline = machine.timeline;
-final typedTimeline = machine.typedTimeline;
+final typedTimeline = machine.timeline
+    .map((entry) => entry.typed)
+    .toList(growable: false);
 ```
 
 Typed transitions classify payload shape by kind:
 
-- `actionEnvelope`
 - `navigation`
 - `route`
 - `controller`
 - `generic`
-
-See `doc/machine_action_envelope_schema.md` for schema compatibility details.