# NavigationState

Stores the backend-neutral history list, active index, and optional pending transition.

## Signatures

```ts
export type NavigationState = {
    readonly entries: ReadonlyArray<Destination>;
    readonly index: number;
    readonly transition: Option.Option<Transition>;
};
```

## Why

Provider adapters can share one tested transition state machine while retaining control over the
actual browser, native, or in-memory commit operation.

## Ownership and lifetime

This immutable snapshot acquires no resources. The RefSubject passed to
{@link makeNavigationCore} owns successive snapshots for its provider Scope.

## Property: entries

Committed entries in traversal order.

## Property: entries: Why

The active entry, traversal bounds, and keyed lookup all derive from one ordered snapshot.

## Property: entries: Ownership and lifetime

The snapshot retains this array by reference. Provider code replaces the snapshot rather than
mutating the array while a transition is running.

## Property: index

Zero-based active entry index.

## Property: index: Why

Back, forward, and current-entry reads share the same cursor into `entries`.

## Property: index: Ownership and lifetime

The index belongs to this immutable snapshot and changes only when the provider publishes a
replacement snapshot. Callers must keep it within the `entries` bounds.

## Property: transition

Pending transition, cleared on commit, cancellation, redirect failure, or interruption.

## Property: transition: Why

Consumers can distinguish proposed work from the destination at the committed `index`.

## Property: transition: Ownership and lifetime

The provider retains `Some(transition)` only while that transition is current. Cleanup compares
identity before clearing it so an interrupted older transition cannot erase a newer one.