Mastersam07 / Mastersam07/kaisel
refactor: scope stack entry IDs to router instances and add reset helper for global debug counters
@Mastersam07 is already working on this.
Since Jul 20, 2026.
- Dominant language
- Dart
- Stars
- 69
- Forks
- 2
- Avg merge
- 18m
- Merged PRs (30d)
- 9
Description
[authored by Randal, assisted by Gemini]
## Problem
Currently, `kaisel` uses global static counters for page entry IDs and debug transition ordering:
1. `KaiselStackEntry._nextId` is a global static counter used to assign unique IDs to entries on the navigation stack:
https://github.com/Mastersam07/kaisel/blob/dev/packages/kaisel_core/lib/src/kaisel_router.dart#L132
2. `_originSeq` is a global static variable used to order transitions across routers and shell branches for DevTools:
https://github.com/Mastersam07/kaisel/blob/dev/packages/kaisel_core/lib/src/kaisel_router.dart#L10
Global mutable state is problematic because:
- It can cause flaky/non-hermetic unit tests if tests leak state or run in parallel.
- It prevents concurrent isolation if multiple router instances or isolated tests are executed in the same process.
## Proposed Solution
### 1. Scope `KaiselStackEntry` IDs to `KaiselRouter`
Because page keys only need to be unique within a single router's page stack, we can make the counter an instance property of the router:
- Update `KaiselStackEntry` to take `id` in its constructor:
```dart
class KaiselStackEntry {
KaiselStackEntry(this.route, this.id);
final R route;
final int id;
}
```
- Maintain an instance-level counter in `KaiselRouter` (`int _nextEntryId = 0;`) and pass it during entry creation (e.g. `_nextEntryId++`).
### 2. Add a Reset Helper for `_originSeq`
Since `_originSeq` must remain global to synchronize events across different router instances for DevTools, we can expose a reset helper in the private `framework.dart` exports so tests can reset it in `setUp`:
```dart
/// Resets the global debug sequence counters. Used to keep tests hermetic.
@visibleForTesting
void debugResetKaiselCounters() {
assert(() {
_originSeq = 0;
return true;
}());
}
```
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.