feat(router)!: reboot router core with method-aware registration (#16)

* feat(router)!: reboot roux with immutable path-only API

- replace legacy mutable method-based router internals with Router(routes) + match(path)

- implement cursor-scanning lookup path and param stack in new matcher core

- add fresh router test suite and new benchmark scripts (compare + relic_compare)

- refresh README and example for the new API surface

BREAKING CHANGE: removes createRouter/addRoute/findRoute/findAllRoutes/removeRoute APIs and method-based matching; the new public API is Router<T>(routes: {...}) with match(String path).

* perf(router): optimize match hot path with static fast lookup

* perf(router): lazy materialize params for dynamic matches

* perf(router): reduce route-build allocations in compile

* chore: use map literal comprehensions for routes

Replace manual map construction and for-loop population with a map literal using a collection-for in bench/relic_compare.dart. Also simplify roux.Router instantiation by passing the routes map directly (relying on type inference). This makes the benchmark code more concise and idiomatic.

* perf(router): specialize static route compilation and cache-free build

* perf(router): fuse pattern normalization with compile scan

* feat(router): add incremental route registration and single-add benchmark

* feat(router): support method-aware route registration and matching

Author: medz

README.md

@@ -3,8 +3,8 @@
 [![Pub Version](https://img.shields.io/pub/v/roux?logo=dart)](https://pub.dev/packages/roux)
 [![Test](https://github.com/medz/roux/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/medz/roux/actions/workflows/test.yml)
 
-Lightweight, fast router for Dart with static, parameterized, and wildcard route
-matching.
+Lightweight, fast router for Dart with static, parameterized, and
+wildcard path matching.
 
 ## Install
 
@@ -23,71 +23,56 @@ flutter pub add roux
 ```dart
 import 'package:roux/roux.dart';
 
-final router = createRouter<String>();
-
-addRoute(router, 'GET', '/users', 'users');
-addRoute(router, 'GET', '/users/:id', 'user');
-addRoute(router, 'POST', '/users', 'create-user');
-addRoute(router, null, '/health', 'any-method');
+final router = Router<String>(
+  routes: {
+    '/': 'root',
+    '/users/all': 'users-all',
+    '/users/:id': 'users-id',
+    '/users/*': 'users-wildcard',
+    '/*': 'global-fallback',
+  },
+);
 
-final match = findRoute(router, 'GET', '/users/123');
-print(match?.data);   // user
+final match = router.match('/users/123');
+print(match?.data);   // users-id
 print(match?.params); // {id: 123}
-
-final all = findAllRoutes(router, 'GET', '/users/123');
-for (final m in all) {
-  print(m.data);
-}
 ```
 
 ## Route Syntax
 
 - Static: `/users`
 - Named param: `/users/:id`
-- Embedded params: `/files/:name.:ext`
-- Single-segment wildcard: `*` (unnamed, captured as `_0`, `_1`, ...)
-- Multi-segment wildcard: `**` (unnamed, captured as `_`) or `**:path` (named)
-- `**` can match an empty remainder; `**:name` requires at least one segment.
-- Escape literal tokens with `\\`: `/static\\:path/\\*/\\*\\*` matches
-  `/static%3Apath/*/**`
-- Paths are normalized to start with `/`.
-- Methods are case-insensitive. `null` uses the any-method token.
+- Wildcard tail: `/users/*`
+- Global fallback: `/*`
+
+Notes:
+- Paths must start with `/`.
+- `*` is only allowed as the final segment.
+- Embedded syntax like `/files/:name.:ext` is intentionally unsupported.
+- Matching is case-sensitive.
+- Trailing slash on input is ignored (`/users` equals `/users/`).
+- You can register routes via constructor (`Router(routes: {...})`) or
+  incrementally (`add` / `addAll`).
 
 ## Matching Order
 
-- Static > param > wildcard.
-- Method matching tries the requested method first, then the any-method token.
-
-## Options
-
-```dart
-final router = createRouter<String>(
-  caseSensitive: false,
-  anyMethodToken: 'any',
-);
-```
-
-## Examples
-
-### Any-method route
+1. Exact route (`/users/all`)
+2. Parameter route (`/users/:id`)
+3. Wildcard route (`/users/*`)
+4. Global fallback (`/*`)
 
-```dart
-addRoute(router, null, '/status', 'ok');
-```
+## Benchmarks
 
-### Find all matches
+Relic-style comparison benchmark:
 
-```dart
-final matches = findAllRoutes(router, 'GET', '/files/report.pdf');
-for (final m in matches) {
-  print(m.data);
-}
+```bash
+dart run bench/relic_compare.dart 500
 ```
 
-### Convert a pattern to RegExp
+Lookup scenario matrix benchmark:
 
-```dart
-final re = routeToRegExp('/users/:id');
+```bash
+dart run bench/compare.dart 500
 ```
 
 ## License

bench/add_single_compare.dart

@@ -0,0 +1,197 @@
+import 'package:benchmark_harness/perf_benchmark_harness.dart';
+import 'package:relic/relic.dart' as relic;
+import 'package:roux/roux.dart' as roux;
+import 'package:routingkit/routingkit.dart' as routingkit;
+
+const _sampleCount = 1024;
+const _defaultStaticValue = 1;
+const _defaultDynamicValue = 2;
+
+final _staticPatterns = List<String>.generate(
+  _sampleCount,
+  (i) => '/users/all_$i',
+  growable: false,
+);
+final _dynamicPatterns = List<String>.generate(
+  _sampleCount,
+  (i) => '/users/:id/orders/:orderId/item$i',
+  growable: false,
+);
+final _dynamicLookups = List<String>.generate(
+  _sampleCount,
+  (i) => '/users/user_$i/orders/order_$i/item$i',
+  growable: false,
+);
+
+var _sink = 0;
+var _cursor = 0;
+
+int _nextIndex() {
+  final index = _cursor;
+  _cursor = (_cursor + 1) & (_sampleCount - 1);
+  return index;
+}
+
+class _CollectingEmitter extends ScoreEmitterV2 {
+  final Map<String, double> runtimeByName = <String, double>{};
+
+  @override
+  void emit(
+    String testName,
+    double value, {
+    String metric = 'RunTime',
+    String unit = 'us',
+  }) {
+    if (metric == 'RunTime') {
+      runtimeByName[testName] = value;
+    }
+    print([testName, metric, value.toStringAsFixed(1), unit].join(';'));
+  }
+}
+
+abstract class _SingleAddBenchmark extends PerfBenchmarkBase {
+  _SingleAddBenchmark(Iterable<String> grouping, _CollectingEmitter emitter)
+    : super(grouping.join(';'), emitter: emitter);
+
+  @override
+  void exercise() => run();
+}
+
+class _StaticSingleAddRouxBenchmark extends _SingleAddBenchmark {
+  _StaticSingleAddRouxBenchmark(_CollectingEmitter emitter)
+    : super(['AddSingle', 'Static', 'Roux'], emitter);
+
+  @override
+  void run() {
+    final index = _nextIndex();
+    final route = _staticPatterns[index];
+    final router = roux.Router<int>();
+    router.add(route, _defaultStaticValue);
+    _sink ^= router.match(route)?.data ?? 0;
+  }
+}
+
+class _DynamicSingleAddRouxBenchmark extends _SingleAddBenchmark {
+  _DynamicSingleAddRouxBenchmark(_CollectingEmitter emitter)
+    : super(['AddSingle', 'Dynamic', 'Roux'], emitter);
+
+  @override
+  void run() {
+    final index = _nextIndex();
+    final route = _dynamicPatterns[index];
+    final lookup = _dynamicLookups[index];
+    final router = roux.Router<int>();
+    router.add(route, _defaultDynamicValue);
+    _sink ^= router.match(lookup)?.data ?? 0;
+  }
+}
+
+class _StaticSingleAddRoutingkitBenchmark extends _SingleAddBenchmark {
+  _StaticSingleAddRoutingkitBenchmark(_CollectingEmitter emitter)
+    : super(['AddSingle', 'Static', 'Routingkit'], emitter);
+
+  @override
+  void run() {
+    final index = _nextIndex();
+    final route = _staticPatterns[index];
+    final router = routingkit.createRouter<int>();
+    router.add('GET', route, _defaultStaticValue);
+    _sink ^= router.find('GET', route)?.data ?? 0;
+  }
+}
+
+class _DynamicSingleAddRoutingkitBenchmark extends _SingleAddBenchmark {
+  _DynamicSingleAddRoutingkitBenchmark(_CollectingEmitter emitter)
+    : super(['AddSingle', 'Dynamic', 'Routingkit'], emitter);
+
+  @override
+  void run() {
+    final index = _nextIndex();
+    final route = _dynamicPatterns[index];
+    final lookup = _dynamicLookups[index];
+    final router = routingkit.createRouter<int>();
+    router.add('GET', route, _defaultDynamicValue);
+    _sink ^= router.find('GET', lookup)?.data ?? 0;
+  }
+}
+
+class _StaticSingleAddRelicBenchmark extends _SingleAddBenchmark {
+  _StaticSingleAddRelicBenchmark(_CollectingEmitter emitter)
+    : super(['AddSingle', 'Static', 'Relic'], emitter);
+
+  @override
+  void run() {
+    final index = _nextIndex();
+    final route = _staticPatterns[index];
+    final router = relic.Router<int>();
+    router.get(route, _defaultStaticValue);
+    _sink ^= router.lookup(relic.Method.get, route).asMatch.value;
+  }
+}
+
+class _DynamicSingleAddRelicBenchmark extends _SingleAddBenchmark {
+  _DynamicSingleAddRelicBenchmark(_CollectingEmitter emitter)
+    : super(['AddSingle', 'Dynamic', 'Relic'], emitter);
+
+  @override
+  void run() {
+    final index = _nextIndex();
+    final route = _dynamicPatterns[index];
+    final lookup = _dynamicLookups[index];
+    final router = relic.Router<int>();
+    router.get(route, _defaultDynamicValue);
+    _sink ^= router.lookup(relic.Method.get, lookup).asMatch.value;
+  }
+}
+
+void main() {
+  print('single add benchmark (benchmark_harness/perf_benchmark_harness)');
+  print('scenario: create empty router, add one route, verify by one lookup');
+  print(
+    'samples=$_sampleCount (pre-generated patterns to avoid constant folding)',
+  );
+  print('format=test;metric;value;unit');
+  print('lower is better (us)');
+
+  final emitter = _CollectingEmitter();
+  for (final benchmark in <_SingleAddBenchmark>[
+    _StaticSingleAddRoutingkitBenchmark(emitter),
+    _StaticSingleAddRelicBenchmark(emitter),
+    _StaticSingleAddRouxBenchmark(emitter),
+    _DynamicSingleAddRoutingkitBenchmark(emitter),
+    _DynamicSingleAddRelicBenchmark(emitter),
+    _DynamicSingleAddRouxBenchmark(emitter),
+  ]) {
+    benchmark.report();
+  }
+
+  _printRelative(
+    emitter.runtimeByName,
+    baseline: 'Routingkit',
+    title: 'routingkit / roux',
+  );
+  _printRelative(
+    emitter.runtimeByName,
+    baseline: 'Relic',
+    title: 'relic / roux',
+  );
+  print('sink=$_sink');
+}
+
+void _printRelative(
+  Map<String, double> results, {
+  required String baseline,
+  required String title,
+}) {
+  final keyStaticBase = 'AddSingle;Static;$baseline';
+  final keyStaticRoux = 'AddSingle;Static;Roux';
+  final keyDynamicBase = 'AddSingle;Dynamic;$baseline';
+  final keyDynamicRoux = 'AddSingle;Dynamic;Roux';
+
+  final staticRatio = results[keyStaticBase]! / results[keyStaticRoux]!;
+  final dynamicRatio = results[keyDynamicBase]! / results[keyDynamicRoux]!;
+
+  print('\nrelative ($title, >1 means roux is faster)');
+  print('single add static  ${staticRatio.toStringAsFixed(2)}x');
+  print('single add dynamic ${dynamicRatio.toStringAsFixed(2)}x');
+}