Mastersam07 / Mastersam07/kaisel

refactor: scope stack entry IDs to router instances and add reset helper for global debug counters

Open
#53 0 comments 0 reactions 1 assignee View on GitHub

@Mastersam07 is already working on this.

Since Jul 20, 2026.

enhancement pkg:kaisel_core
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.