# @modular-react/journeys

Typed, serializable workflows that compose several modules. A journey declares how one module's exit feeds the next module's entry; the modules themselves stay journey-unaware - they just declare what input they accept and what outcomes they can emit.

Use this package when a domain flow spans multiple modules with **shared state** (e.g. "confirm the customer's profile → branch into plan selection → collect a payment or activate a free trial"), and you want:

- typed end-to-end module boundaries,
- serializable state so a mid-flow reload or hand-off survives,
- a single place that owns transitions, instead of cross-cutting glue inside module stores.

Routes, slots, navigation, workspaces - none of that changes. Journeys sit **on top** of the existing framework. Apps that don't register a journey incur nothing beyond the package being statically linked.

## Prerequisite reading

- [Shell Patterns (Fundamentals)](../../docs/shell-patterns.md)
- [Workspace Patterns](../../docs/workspace-patterns.md)

## Contents

- [Installation](#installation)
- [Mental model](#mental-model)
- [Quickstart shortcut: scaffold the journey package](#quickstart-shortcut-scaffold-the-journey-package) - `create journey` if you bootstrapped with the modular-react CLI
- [Quickstart](#quickstart) - the 5-step path from zero to a running journey
- [Core concepts](#core-concepts) - entries, exits, `allowBack`, lifecycle, statuses, keys
- [Authoring patterns](#authoring-patterns) - module entries, exits, loading flows, **event-driven wait (websocket / SSE + polling + timeout)**, `goBack` opt-in, **lazy entry-points (code-splitting)**
- [Journey definition patterns](#journey-definition-patterns) - branching, `selectModule` dispatch, terminals, state rewrites, bounded history, module compatibility, **`defineTransition` (auto-preload + narrowed handler return)**, **wildcard transitions + shared exit contracts**
- [Composing journeys (invoke / resume)](#composing-journeys-invoke--resume) - call out to a child journey mid-flow and resume on its outcome
  - [Cycle and recursion safety](#cycle-and-recursion-safety) - cycle / depth / undeclared-child / bounce-limit guards and how to tune them
- [Runtime surface](#runtime-surface) - the `JourneyRuntime` you get back from `manifest.journeys`
- [Journey handles](#journey-handles) - typed tokens for `runtime.start(handle, input)`
- [`JourneyProvider` + context](#journeyprovider--context)
- [Persistence](#persistence) - adapters, key design, save queue, hydrate vs start, versioning
- [Rendering - `JourneyOutlet`](#rendering--journeyoutlet) - props, error policies, host rules
- [Hosting a journey - `JourneyHost`](#hosting-a-journey---journeyhost) - start on mount, end + forget on unmount, step index
- [Deep-linking steps - `useJourneySync`](#deep-linking-steps---usejourneysync) - journey ↔ URL in both directions, ports, what a URL can and cannot select
- [Hosting plain modules - `ModuleTab`](#hosting-plain-modules--moduletab)
- [Observation hooks](#observation-hooks)
- [Testing](#testing) - module-level, pure simulator, integration, persistence adapters
- [Integration patterns](#integration-patterns) - tabs, modals, routes, wizards, command palette
- [Embedding a journey in a composition zone](#embedding-a-journey-in-a-composition-zone) - wiring `createJourneyMountAdapter` so a `@modular-react/compositions` zone can mount a journey
- [Debugging](#debugging) - dev-mode warnings and introspection
- [Errors, races, and edge cases](#errors-races-and-edge-cases)
- [Limitations](#limitations)
- [TypeScript inference notes](#typescript-inference-notes)
- [API reference](#api-reference)
- [Example projects](#example-projects)

## Installation

The journey runtime is already a transitive dependency of `@react-router-modules/runtime` and `@tanstack-react-modules/runtime`. Install it directly only when the shell needs to type against journey types (usually it does):

```bash
pnpm add @modular-react/journeys
```

Peer deps: `@modular-react/core`, `@modular-react/react`, `react`, `react-dom`.

If you scaffolded your project with the modular-react CLI, you can scaffold a journey package the same way - see [§ Quickstart shortcut: scaffold the journey package](#quickstart-shortcut-scaffold-the-journey-package) below.

## Using this with Vue

There's a full Vue 3 binding: **`@modular-vue/journeys`** (peer deps
`@modular-frontend/core`, `@modular-vue/vue`, `vue`). The journey _engine_ —
`defineJourney`, transitions, branching, persistence, rewind, the runtime,
handles, `selectModule*`, and every type — is framework-neutral (it lives in
`@modular-frontend/journeys-engine`) and is re-exported identically by both
bindings, so **journey definitions and module entry/exit contracts are written
exactly the same way** whichever framework you ship.

What changes is the UI layer:

- Import the outlet, provider, plugin, and composables from `@modular-vue/journeys`
  instead of `@modular-react/journeys`. `<JourneyOutlet>`, `<ModuleTab>`,
  `<JourneyProvider>`, `journeysPlugin()`, `useJourneyState`, `useWaitForExit`
  all have the same names and roles.
- Journey steps are module-entry SFCs: `defineProps<ModuleEntryProps<Input, Exits>>()`
  and call the typed `exit(name, payload)` — the analog of the React entry
  component's props.
- The subscription composables return **Vue refs** rather than plain values
  (e.g. `useJourneyState` → `ComputedRef<TState | null>`), matching the rest of
  the Vue binding; read `.value` in `<script>`, auto-unwrapped in `<template>`.

See [`examples/vue/customer-onboarding-journey`](../../examples/vue/customer-onboarding-journey)
for a runnable branching, persisted journey, and
[Getting started with Vue Router](../../docs/getting-started-vue-router.md) for
the surrounding shell setup. The React code below uses React imports and JSX;
translate the imports and the entry components to SFCs for Vue — the journey and
module contracts are unchanged.

## Mental model

Three roles, strictly separated:

| Role        | Owns                                                                                                        | Does NOT know about                                  |
| ----------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Module**  | Its entry components, input types, exit names, exit output types.                                           | Journeys. Who opens it. What comes next.             |
| **Journey** | The modules it composes (by type), transitions between entry/exit pairs, shared state.                      | Shell. Tabs. Routes.                                 |
| **Shell**   | Registering modules + journeys, mounting `<JourneyOutlet>` inside its container (tab, route, modal, panel). | Any specific journey's logic, state, or transitions. |

## Quickstart shortcut: scaffold the journey package

If you used the modular-react CLI to bootstrap your project, you can skip writing the journey package boilerplate by hand. Run:

```bash
# React Router
npx @react-router-modules/cli create journey customer-onboarding \
  --modules profile,plan,billing --persistence

# TanStack Router
npx @tanstack-react-modules/cli create journey customer-onboarding \
  --modules profile,plan,billing --persistence
```

That generates `journeys/customer-onboarding/` with a typed `defineJourney` definition, a `defineJourneyHandle` token, type-only imports for each named module, and (with `--persistence`) a `createWebStoragePersistence` adapter at `shell/src/customer-onboarding-persistence.ts`. It also installs `journeysPlugin()` on the shell's registry and adds `registry.registerJourney(...)`. The `start` step and per-module `transitions` map are left as `// TODO` comments - fill those in by working through the steps below.

If you're not using the CLI (or you want to understand the moving parts before reaching for it), the manual walkthrough follows.

## Quickstart

### 1. Declare a module's entry and exit vocabulary

Modules import only from `@modular-react/core`:

```ts
// modules/profile/src/exits.ts
// Each key here is an *exit name* the profile module can emit. The generic on
// `defineExit<T>()` declares the `output` payload shape that exit ships. The
// journey's transition map (see step 2) keys handlers off these exact names.
import { defineExit } from "@modular-react/core";
import type { PlanHint } from "./types.js";

export const profileExits = {
  profileComplete: defineExit<{ customerId: string; hint: PlanHint }>(),
  readyToBuy: defineExit<{ customerId: string; amount: number }>(),
  needsMoreDetails: defineExit<{ customerId: string; missing: string }>(),
  cancelled: defineExit(), // no output payload
} as const;
export type ProfileExits = typeof profileExits;
```

```tsx
// modules/profile/src/ReviewProfile.tsx
import type { ModuleEntryProps } from "@modular-react/core";
import type { ProfileExits } from "./exits.js";

export function ReviewProfile({
  input,
  exit,
}: ModuleEntryProps<{ customerId: string }, ProfileExits>) {
  const customer = useCustomer(input.customerId);
  const hint = suggestPlan(customer);

  if (customer.readiness === "needs-details") {
    return (
      <button
        onClick={() =>
          exit("needsMoreDetails", {
            customerId: input.customerId,
            missing: customer.readinessDetail,
          })
        }
      >
        Flag for back-office
      </button>
    );
  }
  return (
    <>
      <ProfileSummary customer={customer} hint={hint} />
      <button onClick={() => exit("profileComplete", { customerId: input.customerId, hint })}>
        Pick a plan
      </button>
      {customer.readiness === "self-serve" && (
        <button
          onClick={() =>
            exit("readyToBuy", {
              customerId: input.customerId,
              amount: selfServeAmount(customer),
            })
          }
        >
          Skip ahead - charge now
        </button>
      )}
      <button onClick={() => exit("cancelled")}>Cancel</button>
    </>
  );
}
```

```ts
// modules/profile/src/index.ts
import { defineModule, defineEntry, schema } from "@modular-react/core";
import { profileExits } from "./exits.js";
import { ReviewProfile } from "./ReviewProfile.js";

export default defineModule({
  id: "profile", // module id - referenced by journeys as `module: "profile"`
  version: "1.0.0",
  exitPoints: profileExits, // the full exit vocabulary shared by every entry on this module
  entryPoints: {
    // Each key here is an *entry name* - a typed way to open this module.
    // Journeys reference it as `entry: "review"`.
    review: defineEntry({
      component: ReviewProfile,
      input: schema<{ customerId: string }>(), // `input` shape passed when the entry is opened
    }),
  },
});
```

The `exits` const pattern (define once, share between component typing and module descriptor) is the canonical shape. `schema<T>()` is a **type-only** brand - zero runtime work.

### 2. Declare the journey

```ts
// journeys/customer-onboarding/src/journey.ts
import { defineJourney } from "@modular-react/journeys";
import type profileModule from "@myorg/module-profile";
import type planModule from "@myorg/module-plan";
import type billingModule from "@myorg/module-billing";

type Modules = {
  readonly profile: typeof profileModule;
  readonly plan: typeof planModule;
  readonly billing: typeof billingModule;
};

interface OnboardingState {
  customerId: string;
  hint: PlanHint | null;
  selectedPlan: SubscriptionPlan | null;
}

export const customerOnboardingJourney = defineJourney<Modules, OnboardingState>()({
  id: "customer-onboarding",
  version: "1.0.0",
  initialState: ({ customerId }: { customerId: string }) => ({
    customerId,
    hint: null,
    selectedPlan: null,
  }),
  start: (s) => ({ module: "profile", entry: "review", input: { customerId: s.customerId } }),
  // The `transitions` map is nested three levels deep:
  //   1. module id   - which composed module (matches a key in `Modules` above)
  //   2. entry name  - which entry on that module the handler covers
  //   3. exit name   - which exit fired by that entry triggers the handler
  // Each leaf is a pure function returning the next step, a state rewrite,
  // a `complete`, or an `abort`.
  transitions: {
    profile: {
      // module id - matches the `profile` key in `Modules` above
      review: {
        // entry name on the `profile` module - see `entryPoints.review` in modules/profile/src/index.ts
        // Exit names below are the keys of `profileExits` declared in modules/profile/src/exits.ts.
        profileComplete: ({ output, state }) => ({
          state: { ...state, hint: output.hint },
          next: {
            module: "plan",
            entry: "choose",
            input: { customerId: state.customerId, hint: output.hint },
          },
        }),
        readyToBuy: ({ output }) => ({
          next: {
            module: "billing",
            entry: "collect",
            input: { customerId: output.customerId, amount: output.amount },
          },
        }),
        needsMoreDetails: ({ output }) => ({
          abort: { reason: "profile-incomplete", missing: output.missing },
        }),
        cancelled: () => ({ abort: { reason: "rep-cancelled" } }),
      },
    },
    // …transitions for `plan` and `billing` follow the same module -> entry -> exit shape.
  },
});
```

Module imports are `import type` - the journey never pulls a module into its bundle. Runtime resolution happens by id against the registry.

### 3. Register the journey in the shell

Attach the journeys plugin to enable `registry.registerJourney`. Without `.use(journeysPlugin())` the method isn't on the base registry:

```ts
import { createRegistry } from "@react-router-modules/runtime"; // or @tanstack-react-modules/runtime
import { journeysPlugin } from "@modular-react/journeys";
import { customerOnboardingJourney } from "@myorg/journey-customer-onboarding";

const registry = createRegistry<AppDeps, AppSlots>({ stores, services }).use(
  // Call once per registry - the plugin closes over its own registration
  // list. The optional `onModuleExit` is the shell-wide dispatcher for
  // module exits fired outside a journey step (see "`JourneyProvider` +
  // context" below).
  journeysPlugin({
    onModuleExit: (ev) => workspace.closeTab(ev.tabId),
  }),
);

registry.register(profileModule);
registry.register(planModule);
registry.register(billingModule);

// All registration options shown below are optional - a bare
// `registry.registerJourney(customerOnboardingJourney)` is valid and
// gives you an in-memory journey with no reload recovery.
registry.registerJourney(customerOnboardingJourney, {
  persistence: defineJourneyPersistence<OnboardingInput, OnboardingState>({
    keyFor: ({ input }) => `journey:${input.customerId}:customer-onboarding`,
    load: (k) => backend.loadJourney(k),
    save: (k, b) => backend.saveJourney(k, b),
    remove: (k) => backend.deleteJourney(k),
  }),
  // Cap `history` growth for long-running journeys. See the caveat in
  // [Bounded history (`maxHistory`)](#pattern--bounded-history-maxhistory).
  // maxHistory: 50,
});

export const manifest = registry.resolveManifest();
```

`registry.registerJourney` validates the definition's **structural shape** right away (missing `id` / `version` / `transitions` etc. throw a `JourneyValidationError`). The deeper **contract check** - that every module id, entry name, exit name, and `allowBack` pairing actually matches the registered modules - runs at `resolveManifest()` / `resolve()` time.

`defineJourneyPersistence<TInput, TState>` is the recommended shape for the adapter: it ties `keyFor`'s `input` to the journey's `TInput` so no `as { customerId: string }` cast is needed, and typechecks `load` / `save` against the journey's state end-to-end. Plain objects matching `JourneyPersistence` still work if you prefer.

### 4. Render the journey in a tab (or any container)

The plugin mounts `<JourneyProvider>` automatically - descendant `<JourneyOutlet>` / `<ModuleTab>` nodes read the runtime (and the plugin-level `onModuleExit`) from context with no extra wiring. Just render the outlet wherever the step should live:

```tsx
import { JourneyOutlet, ModuleTab } from "@modular-react/journeys";

function TabContent({ tab, manifest }: { tab: Tab; manifest: ResolvedManifest }) {
  if (tab.kind === "module") {
    return (
      <ModuleTab
        module={manifest.moduleDescriptors[tab.moduleId]}
        entry={tab.entry}
        input={tab.input}
        tabId={tab.tabId}
        // The plugin's `onModuleExit` fires automatically for every module
        // tab; pass `onExit` only for a per-tab override (typically "close
        // this tab").
        onExit={(ev) => workspace.closeTab(tab.tabId)}
      />
    );
  }
  return (
    <JourneyOutlet
      instanceId={tab.instanceId}
      loadingFallback={<LoadingSpinner />}
      onFinished={(outcome) => workspace.closeTab(tab.tabId)}
    />
  );
}
```

If the shell needs to reach a different runtime from the same tree (multi-tenant dashboards, split-screen agents), mount an explicit `<JourneyProvider runtime={otherRuntime}>` locally - the explicit prop wins over the plugin's provider. The manual-mount path is also still how you'd wire journeys in a shell that doesn't use `@react-router-modules/runtime` / `@tanstack-react-modules/runtime` at all.

`manifest.journeys` is always a runtime - even when no journey is registered it's a no-op runtime whose `listDefinitions()` / `listInstances()` return empty and whose `start()` throws the usual "unknown journey id" error. Shells don't need to null-guard it.

### 5. Open the journey

Export a **handle** alongside the journey definition so callers can open it with a typed `input` without importing the journey's runtime code:

```ts
// journeys/customer-onboarding/src/index.ts
import { defineJourneyHandle } from "@modular-react/journeys";
export const customerOnboardingHandle = defineJourneyHandle(customerOnboardingJourney);
```

The shell (or any module) then passes the handle to `runtime.start`. Typically this lives inside an `openTab`-style service so the workspace bookkeeping and the journey start are one call-site:

```ts
// In the shell, with `manifest.journeys` in scope:
const instanceId = manifest.journeys.start(customerOnboardingHandle, { customerId });
workspace.addJourneyTab({
  instanceId,
  journeyId: customerOnboardingHandle.id,
  input: { customerId },
  title: `Onboarding - ${customerName}`,
});
```

See the [customer-onboarding-journey example](../../examples/react-router/customer-onboarding-journey/) for a complete working shell, including the dispatcher that also handles the string-id form used by plugin-contributed navbar actions.

## Core concepts

### Entry points and exit points on a module

Two additive (optional) fields on `ModuleDescriptor`:

| Field         | Shape                                                                                                                                                      | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entryPoints` | `{ [name]: { component, input?, allowBack?, buildInput? } }`<br>or `{ [name]: { lazy: () => import("./X"), fallback?, input?, allowBack?, buildInput? } }` | Typed ways to open the module. A module can expose several. Each entry is either eager (a directly-bound component) or lazy (a dynamic-import factory — see [Pattern - lazy entry-points](#pattern---lazy-entry-points-code-splitting-per-step)). `buildInput?: (state) => TInput` derives the step's input from the host journey's state at every entry — see [Pattern - `buildInput` for re-entered forms](#pattern---buildinput-for-re-entered-forms). |
| `exitPoints`  | `{ [name]: { output? } }`                                                                                                                                  | The module's full outcome vocabulary.                                                                                                                                                                                                                                                                                                                                                                                                                     |

`ModuleEntryProps<TInput, TExits>` typed props for the component - `{ input, exit, goBack?, goForward? }`, with `exit(name, output)` cross-checked against `TExits` at compile time. `goForward` is the inverse of `goBack` — present only when the future / redo stack has an entry to restore (i.e. the user just called `goBack` and no fresh exit has cleared the redo target). Most shells wire Forward at the shell level (browser button); the per-component prop is for steps that surface an in-page redo control.

Exits are **module-level, not per-entry** - every entry on a module shares the same `exitPoints` vocabulary. The journey's transition map (not the module) decides which exits a given entry actually uses, so two entries on the same module can map the same exit name to entirely different next steps.

### `mountKinds` — opting an entry out of journeys

Some entries belong to a single host surface. A panel designed for a composition zone reads composition state via `useCompositionDispatch` / `useCompositionEmit` and has no use for `exit`/`goBack`/`goForward` — mounting it as a journey step would silently strand the user. Conversely, a journey-shaped step has nowhere to dispatch composition events from a composition zone.

`defineEntry({ mountKinds: [...] })` lets an entry declare which hosts it accepts:

```ts
defineEntry({
  component: CheckoutStep,
  input: schema<{ amount: number }>(),
  mountKinds: ["journey"], // journey only — composition selectors reject this entry
});

defineEntry({
  component: EditorPanel,
  input: schema<{ documentId: string }>(),
  mountKinds: ["composition"], // composition only — journey transitions reject this entry
});

defineEntry({
  component: SharedHeader,
  input: schema<void>(),
  mountKinds: ["journey", "composition"], // both — the default if omitted
});
```

Enforcement runs in two places:

1. **Compile time** — `StepSpec<TModules>` filters out entries that don't include `"journey"`. A transition handler returning `{ module, entry, input }` for a composition-only entry is a type error at the transition site; the diagnostic enumerates the entries that ARE journey-mountable on that module.
2. **Render time** — if a step ever resolves to a composition-only entry through a type-bypass path (a dynamic id, an `as never` cast), the journey outlet renders a clear error fallback instead of mounting the wrong-surface panel.

Backward compatibility: omitting `mountKinds` is treated as "every surface" — pre-v1.5 modules continue to work in journeys and compositions without changes.

The annotation captures _intent_, not _capability_: a module can declare `mountKinds: ["journey", "composition"]` and still ship a component that crashes outside a journey. The compile-time filter trusts the declaration; a panel that calls `exit(...)` inside a composition zone gets a separate dev-warn (see the compositions package).

### `allowBack` - three values

Declared per entry on the module, opted-in per transition on the journey. Both must agree for `goBack` to appear.

| Value              | What happens on goBack                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `'preserve-state'` | History pops; journey state is untouched.                                                                                             |
| `'rollback'`       | History pops AND journey state reverts to the snapshot taken before this step was entered (shallow clone - treat state as immutable). |
| `false` / absent   | `goBack` is `undefined` in the component's props. Don't render the back button.                                                       |

The journey's transition map matches with `allowBack: true` on the exit block:

```ts
transitions: {
  plan: {                 // module id
    choose: {             // entry name on the `plan` module
      allowBack: true,    // journey-side opt-in (paired with the entry's `allowBack` declaration)
      choseStandard: …,   // exit name -> handler (omitted)
    },
  },
}
```

A `resolveManifest()` error surfaces if the two sides disagree.

### `goForward` — redoing a `goBack`

Each `goBack` pushes the step it rewinds from (plus state + rollback snapshot) onto a per-instance **future stack**. `runtime.goForward(id)` (or `ModuleEntryProps.goForward?.()`) pops the top of that stack and restores the runtime to the rewound step. The captured _post-transition_ state wins — for a `rollback`-mode entry, edits the user made between the rewind and the redo are discarded.

Key points:

- **Not gated by `allowBack`.** The future entry was created by a `goBack` that already passed both opt-ins; the inverse is always valid.
- **Not the same as re-firing the exit.** Transition handlers don't re-run on `goForward`, so API calls / telemetry / persistence in the handler body fire once, not twice. If business logic needs to re-execute, the shell fires the exit itself.
- **Not symmetric with `goBack` on `buildInput`.** `goBack` re-runs `buildInput` against the rolled-back state. `goForward` trusts the step's captured `input` verbatim (the input was already built against the same state being restored; re-running a non-pure `buildInput` would diverge from what the original transition produced).
- **Cleared by any fresh exit.** A `{ next | complete | abort }` arm wipes the future stack (matches browsers — a new navigation drops Forward). `invoke` leaves it intact (parent step doesn't advance while a child runs).
- **Transient.** Not persisted: reload always starts with an empty future stack, same as opening a new browser tab.
- **Inspectable.** `JourneyInstance.future: readonly JourneyStep[]` exposes the stack so shells can gate a Forward button on `instance.future.length > 0` without reaching into runtime internals. Top of stack is the next step a redo would land on.

### Breadcrumb / edit-and-revisit wizards

A long wizard typically wants a breadcrumb header so the user can click step 4 while on step 8, edit a field, then walk forward through every intermediate step (5 → 6 → 7 → 8) without losing data already entered downstream. The journey runtime ships the primitive for this: **`runtime.rewindTo(id, historyIndex)`**, a transactional multi-step `goBack`.

```ts
// Render breadcrumbs from JourneyInstance.history plus the current
// step (which isn't in `history`). Gate each historical chip on
// canRewindTo so opt-outs disable the affordance instead of silently
// no-opping; the current chip is the "you are here" marker and isn't
// clickable.
function Breadcrumbs({ instanceId, runtime }: { instanceId: InstanceId; runtime: JourneyRuntime }) {
  const instance = useJourneyInstance(instanceId);
  return (
    <nav>
      {instance.history.map((frame, i) => (
        <button
          key={i}
          disabled={!runtime.canRewindTo(instanceId, i)}
          onClick={() => runtime.rewindTo(instanceId, i)}
        >
          {frame.moduleId}.{frame.entry}
        </button>
      ))}
      {instance.step && (
        <span aria-current="step">
          {instance.step.moduleId}.{instance.step.entry}
        </span>
      )}
    </nav>
  );
}
```

For this round-trip to preserve data correctly, the journey has to be authored with three rules in mind:

1. **`allowBack: "preserve-state"` on every entry along the wizard path.** A `"rollback"` entry restores its pre-transition snapshot on the way back, which discards anything the user typed on later steps. `"preserve-state"` keeps the accumulated state intact so downstream form data is still in `state` after the rewind.
2. **`buildInput(state)` on every entry.** Each step re-derives its `input` from accumulated journey state on every (re-)entry. Without it, a form returned to via `rewindTo` (or even a single `goBack`) renders against the snapshot frozen at the original push — meaning data the user has since added is invisible to the form.
3. **Transition handlers stay pure routing.** When the user clicks `Next` forward after editing, every intermediate transition fires again so each step revalidates against the new state — that's the **point** of forcing forward re-traversal (an early edit may change which options are valid downstream). This only works safely under the [transition handler purity rules](#transition-handlers-are-pure-and-synchronous): handlers must be deterministic functions of `state` + `output`, and any side-effectful work belongs in a [loading entry point](#pattern---a-loading-entry-point-for-async-work) so a replay doesn't double-fire it.

`rewindTo` is **atomic**: it walks the chain of frames it would leave and rejects the whole call if any one fails the back opt-in (transition `allowBack: true` + entry `allowBack !== false`). That means a non-rewindable step in the middle of the path can't strand the user halfway through — `canRewindTo` will return `false` and the breadcrumb chip stays disabled.

`rewindTo` is **not a fast-forward**. It only rewinds. To return to the most recent step after editing, the user walks forward via the normal `Next` flow — and that's intentional, not a missing feature. Re-running each intermediate transition is what lets the journey revalidate downstream choices against the user's edit. If you want a redo-without-handler-replay (the user clicked the breadcrumb by mistake), that's `goForward` — the future stack built by `rewindTo` matches what N successive `goBack` calls would have built, so a single `goForward` undoes one step at a time.

### Transition handlers are pure and synchronous

- No `await`.
- No React hooks.
- No store/service access.
- No side effects.

If a transition needs to fetch data between steps, put the fetch inside a dedicated loading entry point on a module - the module fetches in `useEffect` and exits with the loaded data. Side effects live in the observation hooks (`onTransition`, `onAbandon`, `onComplete`, `onAbort`), which are free to be noisy.

### Journey lifecycle

```text
user triggers exit('X', output)
  → runtime checks step token matches (stale callbacks are dropped)
  → runs transition handler (pure)
  → commits state + step + history atomically
  → fires onTransition (definition first, then registration option)
  → if terminal: fires onComplete / onAbort
  → schedules persistence.save (serialized per instance)
  → JourneyOutlet re-renders with new step or terminal state
```

A step-token counter guards against double-click and stale callbacks: any `exit()` / `goBack()` captured at mount time is dropped silently if the current step has moved on.

### Instance statuses

`JourneyInstance.status` runs through four values:

| Status        | When                                                                                            | `step`                   | `<JourneyOutlet>` renders          |
| ------------- | ----------------------------------------------------------------------------------------------- | ------------------------ | ---------------------------------- |
| `'loading'`   | Async `persistence.load()` is in flight (first paint after `start()`).                          | `null`                   | `loadingFallback`                  |
| `'active'`    | The normal running state - `step` points at the module/entry currently on screen.               | `{ moduleId, entry, … }` | The step component                 |
| `'completed'` | Terminal. A transition returned `{ complete }`.                                                 | `null`                   | `null` (after firing `onFinished`) |
| `'aborted'`   | Terminal. A transition returned `{ abort }`, the outlet unmounted, or `runtime.end` was called. | `null`                   | `null` (after firing `onFinished`) |

Terminal instances stay in memory (so late subscribers can read `terminalPayload`) until you call `runtime.forget(id)` / `runtime.forgetTerminal()`.

### Keys, idempotency, and "resume vs new"

When persistence is configured, `runtime.start(journeyId, input)` is **idempotent per persistence key**: two calls with inputs that resolve to the same `keyFor` return the same `instanceId`. This is the mechanism that turns "open the Alice onboarding tab" into "resume Alice's onboarding tab" on reload - no explicit `resume()` API is needed. See [Persistence](#persistence) for the probe rules.

Without persistence, every `start()` mints a fresh instance. Two calls = two independent journeys that happen to share a journey id.

## Authoring patterns

Patterns below are small, composable recipes - most real apps use two or three of them together.

### Pattern - an exits const shared between the component and the descriptor

The canonical module shape: define exits once, consume them from the component (for a typed `exit` prop) and from the descriptor (for validation). No duplication.

```ts
// modules/profile/src/exits.ts
export const profileExits = {
  profileComplete: defineExit<{ customerId: string; hint: PlanHint }>(),
  cancelled: defineExit(),
} as const;
export type ProfileExits = typeof profileExits;
```

```tsx
// modules/profile/src/ReviewProfile.tsx
export function ReviewProfile({
  input,
  exit,
}: ModuleEntryProps<{ customerId: string }, ProfileExits>) {
  /* exit('profileComplete', { customerId: input.customerId, hint }) is type-checked */
}
```

```ts
// modules/profile/src/index.ts
export default defineModule({
  id: "profile",
  version: "1.0.0",
  exitPoints: profileExits,
  entryPoints: {
    review: defineEntry({ component: ReviewProfile, input: schema<{ customerId: string }>() }),
  },
});
```

Note: `defineModule` is called **without** shell-level generics in this example. That keeps the descriptor's literal type (including the narrow `entryPoints` / `exitPoints` keys) preserved so the journey definition can cross-check transitions against `typeof moduleDescriptor`. A typed shell can still enforce `AppDependencies` / `AppSlots` via `defineModule<AppDeps, AppSlots>()` at the call site if desired - the tradeoff is that the narrow entry/exit types must be recovered via `typeof` in the journey's module map either way.

### Pattern - a module exposing several entries

```ts
export default defineModule({
  id: "billing",
  version: "1.0.0",
  exitPoints: billingExits,
  entryPoints: {
    collect: defineEntry({ component: CollectPayment, input: schema<CollectInput>() }),
    startTrial: defineEntry({ component: StartTrial, input: schema<TrialInput>() }),
  },
});
```

The journey's transition map targets `{ module: 'billing', entry: 'collect' }` or `'startTrial'` - the discriminated `StepSpec` enforces that `input` matches the chosen entry.

### Pattern - lazy entry-points (code-splitting per step)

For heavy steps (rich editors, charting libraries, large vendor bundles) declare `lazy: () => import('./HeavyStep')` instead of `component:`. The runtime wraps the resolved component in `React.lazy` + `<Suspense>` for you and exposes an idempotent `preload()` that the outlet calls during idle time (see [auto-preload](#pattern---declared-targets-with-definetransition-auto-preload--narrowed-return-type)). This eliminates the per-entry `LazyXxxStep.tsx` wrapper consumers used to write to get past the descriptor's "must be a function" validation.

```tsx
// modules/billing/src/index.ts
import { defineEntry, defineModule, schema } from "@modular-react/core";
import { billingExits } from "./exits.js";

export default defineModule({
  id: "billing",
  version: "1.0.0",
  exitPoints: billingExits,
  entryPoints: {
    collect: defineEntry({
      lazy: () => import("./CollectPayment.js"),
      fallback: <PaymentSkeleton />, // optional <Suspense fallback>
      input: schema<{ customerId: string; amount: number }>(),
    }),
  },
});
```

Rules:

- **Eager and lazy are mutually exclusive at the type level.** Declaring both `component` and `lazy` on the same entry is a TypeScript error (and a `validateModuleEntryExit` issue — defense in depth). Declaring neither is also flagged.
- **`fallback` only on lazy entries.** Eager entries don't suspend, so the field is typed `never` on `EagerModuleEntryPoint`. Trying to pass it would be confusing — make the trap visible at the type level.
- **Importer signature matches `React.lazy`.** Standard `() => import("./X")` works (default export). The runtime also normalizes a module that exports the component directly, so `() => Promise.resolve(MyComponent)` works in tests.
- **The lazy import is memoized per entry-object identity** via a process-local `WeakMap` in `@modular-react/react`. A descriptor is fetched at most once across all renders, hot reloads producing fresh descriptor objects get fresh wrappers, and StrictMode's double-mount is safe.
- **Manual prefetch** is exposed via `preloadEntry(entry)` from `@modular-react/react` — useful for hover-prefetch UIs (`onMouseEnter={() => preloadEntry(entry)}`), navigation gestures, or warming a chunk from a `useEffect` that knows the user is about to advance.
- **Errors from the import** propagate through Suspense and are caught by the outlet's existing `StepErrorBoundary`, going through `onStepError` (`abort | retry | ignore`) just like a component throw. A permanently-failing import re-throws the cached rejection on retry; the existing `retryLimit` budget applies.
- **SSR**: `React.lazy` resolution is server-renderable in React 19+; the auto-preload effect is browser-only (no `useEffect` on the server).

### Pattern - a loading entry point for async work

Transitions are pure and synchronous. When a step needs to fetch data between user actions, put the fetch inside a **loading entry** on the next module; that module fires an exit with the loaded data, and the journey transitions from that exit as usual. Use `useWaitForExit` to dispatch the exit when the fetch resolves — it owns the first-wins latch, unmount cleanup, and the step-token guard so the component stays declarative.

```tsx
// modules/risk/src/LoadRiskReport.tsx
import { useWaitForExit } from "@modular-react/journeys";

export function LoadRiskReport({
  input,
  exit,
}: ModuleEntryProps<{ customerId: string }, RiskExits>) {
  useWaitForExit(exit, {
    subscribe: (resolve) => {
      const controller = new AbortController();
      api
        .fetchRiskReport(input.customerId, { signal: controller.signal })
        .then((report) => resolve("reportReady", { report }))
        .catch((err) => {
          if (controller.signal.aborted) return;
          resolve("failed", { reason: String(err) });
        });
      return () => controller.abort();
    },
  });

  return <LoadingSpinner label="Computing risk…" />;
}
```

```ts
// journey - same module -> entry -> exit nesting as the Quickstart example.
transitions: {
  account: {                  // `account` module id
    review: {                 // `review` entry on the account module
      needsRiskCheck: ({ output }) => ({   // exit fired by ReviewAccount when a risk check is needed
        next: { module: "risk", entry: "load", input: { customerId: output.customerId } },
      }),
    },
  },
  risk: {                     // `risk` module id
    load: {                   // `load` entry - the LoadRiskReport component shown above
      reportReady: ({ output, state }) => ({   // exit fired when the async fetch resolves
        state: { ...state, risk: output.report },
        next: { module: "decisions", entry: "choose", input: { risk: output.report } },
      }),
      failed: ({ output }) => ({ abort: { reason: "risk-check-failed", detail: output.reason } }),
    },
  },
}
```

Returning `() => controller.abort()` from `subscribe` tears down the in-flight request if the user clicks `goBack` before the fetch resolves. The runtime would drop a stale `exit('reportReady', …)` via step tokens anyway (see [step tokens](#errors-races-and-edge-cases)), and `useWaitForExit`'s latch would drop a late `resolve(...)`, but cancelling the network work avoids the spurious request. The next pattern leans on the same helper to combine a push channel, a polling fallback, and a deadline — that's where the helper earns its keep — but the single-fetch shape above is the canonical form for the simple case too.

### Pattern - event-driven wait with timeout

When the next step depends on an event the backend pushes — a websocket message, an SSE frame, a long-poll resolution, anything outside the plain request/response cycle — the shape is the [loading-entry pattern above](#pattern---a-loading-entry-point-for-async-work) with two additions: a polling fallback in case the push channel drops a message, and a deadline that decides what happens when nothing arrives. The wait still lives inside a step component that fires an exit; the journey owns what each exit means. `useWaitForExit` composes the three channels so the call site stays declarative.

```tsx
// modules/projects/src/WaitForTranslationProcess.tsx
import { useWaitForExit } from "@modular-react/journeys";

export function WaitForTranslationProcess({
  input,
  exit,
}: ModuleEntryProps<{ projectId: string }, WaitExits>) {
  useWaitForExit(exit, {
    // Push channel — websocket, SSE, push notification: whichever transport
    // the app uses. The hook doesn't care.
    subscribe: (resolve) =>
      events.on(`translation-process:${input.projectId}`, (process) =>
        resolve("ready", { process }),
      ),
    // Polling fallback for missed push frames.
    poll: {
      intervalMs: 3000,
      check: async (resolve) => {
        const process = await api.getTranslationProcess(input.projectId);
        if (process) resolve("ready", { process });
      },
    },
    // Deadline arm — the journey decides whether that's a recoverable exit
    // ("editor opens with no preloaded process") or an abort.
    timeout: { ms: 60_000, fire: "timedOut" },
  });

  return <Spinner label="Preparing translation…" />;
}
```

```ts
// journey - both exits transition forward; the journey decides whether to
// branch on the timeout or treat both arms identically.
transitions: {
  projects: {
    waitForTranslationProcess: {
      ready: ({ output }) => ({
        next: { module: "editor", entry: "open", input: { process: output.process } },
      }),
      timedOut: () => ({
        next: { module: "editor", entry: "open", input: { process: null } },
      }),
    },
  },
}
```

What this shape gives you that a "submit, then `useEffect(() => navigate(...), [...])` in shell code" hand-roll does not:

- **Single owner of the transition.** `useWaitForExit` latches on the first dispatched exit and immediately tears down the losing channels; later resolutions are dropped. The hand-rolled equivalent has to maintain its own `settled` flag _and_ make sure no effect re-fires after navigation — easy to get wrong when a router commit churns the `navigate` reference back through the effect's dep array, or when a stale "timed out" flag survives from a previous submission. Step tokens (see [Errors, races, and edge cases](#errors-races-and-edge-cases)) are a runtime-level backstop that protects both forms equally; the helper's contribution is making the local latch declarative.
- **Push / poll live outside of query callbacks.** The push subscription and the polling fallback live inside `useWaitForExit`'s effect, which is a fine place for side effects. The hand-rolled equivalent often ends up putting `navigate(...)` (or other side effects) inside a react-query `refetchInterval` callback — RQ schedules that callback during render-phase work and expects it to be pure, so a side effect there is what turns "advance once" into "re-fire on every commit."
- **Fresh latches per attempt.** Each push of `waitForTranslationProcess` mounts a fresh component with a fresh latch. There is no journey-scoped equivalent of "the previous submission's `timedOut` flag is still set, so the next submission navigates instantly."

`useWaitForExit`'s timeout has two forms: pass `fire: "exitName"` when the deadline dispatches a no-payload exit (the common case), or `fire: (resolve) => resolve("fallback", payload)` when the deadline needs to compute its output. The named form is constrained at the type level to exits whose schema declares a `void` output, so an exit that needs a payload won't compile in the named form.

If the journey would treat `ready` and `timedOut` identically (same next module + input shape, no state divergence), collapse them into one exit on the module's side. Two exits are only worth it when the journey's downstream — state writes, next module, telemetry — diverges between the success and timeout paths.

### Pattern - optional exits (entries that don't emit every exit)

A module's `exitPoints` declares its **full** vocabulary. Individual entries don't have to emit every exit, and individual journeys don't have to handle every exit. If an entry fires an exit that has no handler in the current journey, the call is ignored and a dev-mode warning is logged - useful during refactors but usually a bug. Keep the exit vocabulary tight and prune unused exits.

### Pattern - `allowBack` on an entry, `allowBack: true` on the transition

For `goBack` to appear in the component's props, **both sides** must opt in:

```ts
// module - declares the entry's back behaviour
entryPoints: {
  choose: defineEntry({ component: ChoosePlan, input: schema<ChooseInput>(), allowBack: "preserve-state" }),
}

// journey - opts that entry into back navigation
transitions: {
  plan: {                  // module id
    choose: {              // entry name on `plan` (matches the entry above)
      allowBack: true,     // journey-side opt-in
      // …exit handlers keyed by exit name…
    },
  },
}
```

Mismatched declarations are caught at `resolveManifest()` / `resolve()` time via `validateJourneyContracts` - the journey's `allowBack: true` with an entry that declared `allowBack: false` (or omitted it) is an aggregated validation error, not a runtime surprise.

### Pattern - `buildInput` for re-entered forms

Without `buildInput`, a step's `input` is captured at first push and reused on every later entry — so a back-navigated form re-renders against the snapshot it was opened with, not the values accumulated by the user's later edits. `buildInput` flips that default: the runtime calls it on every step entry (initial start, forward push, `goBack` pop, resume-into-step) AND when a resume bumps state on the same step without advancing it. The returned value becomes the live `input`. Two excluded cases: (1) an `{ invoke }` arm carrying `state` — the parent's form is paused while the child runs, so rebuilding the hidden input would be wasted work; `buildInput` re-fires naturally on the resume's `{ next }`. (2) `runtime.goForward` — the redo restores a captured step whose `input` was already built against the same state being restored, so re-deriving would diverge from what the original transition produced.

```ts
interface ProjectState {
  readonly draftName: string;
  readonly draftSourceLang: string;
}

interface NameInput {
  readonly previousName: string;
}

const nameModule = defineModule({
  id: "name",
  version: "1.0.0",
  exitPoints: { next: defineExit<{ name: string }>() },
  entryPoints: {
    edit: defineEntry({
      component: NameForm,
      input: schema<NameInput>(),
      allowBack: "preserve-state",
      // Annotate `state` with the hosting journey's TState — the module
      // surface itself stays journey-agnostic (typed `unknown`).
      buildInput: (state: ProjectState) => ({ previousName: state.draftName }),
    }),
  },
});
```

Because `buildInput` owns the input, `StepSpec` makes the transition's `input` field **optional** for an entry that declares it — omit it entirely. Stamping a value still type-checks (handy mid-migration), but the runtime ignores it whenever `buildInput` is declared and, in `debug` mode, warns once when the stamped value would have differed from `buildInput`'s output, so the divergence is observable. The optionality applies everywhere a step is produced: inline `{ next }` literals, `journey.start`, `defineTransition`, and `selectModule`.

```ts
transitions: {
  source: {
    pick: {
      allowBack: true,
      next: ({ state, output }) => ({
        state: { ...state, draftSourceLang: output.lang },
        // `name.edit` declares `buildInput`, so `input` is optional here —
        // omit it; the runtime derives `previousName` from state on entry.
        next: { module: "name", entry: "edit" },
      }),
    },
  },
},
```

When the user back-navigates from a later step to this one, `buildInput(state)` runs again and the form sees the latest `draftName` — no React context, no `useEffect`-syncing local form state to journey state.

`buildInput` must be pure and synchronous; it runs on the runtime's hot path. **A throw aborts the instance with `{ reason: "build-input-threw", moduleId, entry, error }`** (a member of `JourneySystemAbortReason`) rather than entering with a half-built or stale input — leaving the form mounted with the pre-throw cached input would silently mis-render against accumulated state, which is exactly the bug `buildInput` exists to fix. Use `isJourneySystemAbort` to narrow.

#### Notes

- **State typing is on the author.** The module surface types `state` as `unknown` because modules don't know which journey hosts them. Two equivalent patterns for annotating it:

  ```ts
  // 1. Inline parameter annotation — terse, no extra import.
  buildInput: (state: ProjectState) => ({ previousName: state.draftName }),

  // 2. `buildInputFor<TState>()` wrapper — exported from `@modular-react/core`.
  //    Use this when the inline pattern trips your tsconfig
  //    (`strictFunctionTypes` can flag the narrowed `state` parameter as not
  //    assignable to the declared `(state: unknown) => TInput`), or when you
  //    just prefer named-generic positions over arrow-parameter annotations.
  buildInput: buildInputFor<ProjectState>()((state) => ({
    previousName: state.draftName,
  })),
  ```

  Neither pattern verifies that `ProjectState` matches the host journey's actual `TState` — modules are journey-agnostic, so the cross-cut isn't expressible at the entry-declaration site. A wrong `TState` annotation passes silently in both forms. Treat journey-level integration / harness tests as the safety net.

- **Step identity churns when `buildInput` is declared.** Each entry allocates a fresh `{ moduleId, entry, input }` object even when the derived `input` is structurally identical to the prior render's. Consumers relying on `instance.step` reference equality for memoization (`onTransition` listeners, custom `useSyncExternalStore` selectors) should compare by `(step.moduleId, step.entry)` or by a structural diff on `step.input`. Entries without `buildInput` keep the cache-on-push identity guarantee.

> **Testing tip — always pass `options.modules` for `simulateJourney`.** Without it the runtime can't resolve module descriptors, so `buildInput` falls back to the cached handler-supplied input (silently degrading the behaviour under test) and `validateJourneyContracts` warnings about unbound modules surface in test output. The `modules` option is typed as `Record<string, ModuleDescriptor<any, any, any, any>>` — the bivariant `any` on `TNavItem` means a heterogeneous map like `{ name: nameModule, email: emailModule }` passes structurally even when the host app narrows `TNavItem` to a custom action type. No `as unknown as` cast required.
>
> ```ts
> simulateJourney(journey, input, {
>   modules: { name: nameModule, email: emailModule },
> });
> ```

## Journey definition patterns

### Pattern - branching on exit name

Most journeys branch by picking a different `next` step per exit name. `StepSpec`'s discriminated union means `input` on each branch is type-checked against the target entry:

```ts
profile: {                                    // module id
  review: {                                   // entry name on `profile`
    profileComplete: ({ output, state }) => ({   // exit name -> branch into the `plan` module
      state: { ...state, hint: output.hint },
      next: { module: "plan", entry: "choose", input: { customerId: state.customerId, hint: output.hint } },
    }),
    readyToBuy: ({ output }) => ({               // different exit -> branch into `billing` instead
      next: { module: "billing", entry: "collect", input: { customerId: output.customerId, amount: output.amount } },
    }),
  },
},
```

### Pattern - declared targets with `defineTransition` (auto-preload + narrowed return type)

Wrap a handler with `defineTransition` to declare every outcome it may take — both next-step destinations and terminal arms. Two effects from one declaration:

1. **Runtime — preload precision.** `<JourneyOutlet>`'s default `preload="precise"` mode reads `targets` and warms exactly the declared next-step chunks during idle time, so navigating Next finds the chunk already cached.
2. **Type-level — the handler's return is constrained to the declared arms.** Returning an arm that wasn't declared (e.g. `abort` when only `next` was declared) is a compile error.

`targets` accepts a mixed array of:

- `{ module, entry }` — same shape as `next:` minus the runtime-computed `input`. One per next-step candidate.
- `"complete"` / `"abort"` / `"invoke"` — string sentinels for the terminal arms. Declaring `"complete"` permits `{ complete: ... }` returns; `"abort"` permits `{ abort: ... }`; `"invoke"` permits `{ invoke: ... }` (the journey's `invokes:` field remains the closed-set declaration the runtime cycle-guards check against — the sentinel is just "this handler may invoke something").

The helper has two call shapes:

- **Curried (recommended)** — `defineTransition<TModules, TState>()` binds the journey's generics once. Handlers wrapped with the returned binder get `targets` autocompleted to valid step refs + sentinels and the handler's return narrowed to the declared arms.
- **Bare** — `defineTransition({ targets, handle })` for one-off use. `targets` accepts any well-formed step-ref / sentinel without TModules-level checking; the handler's return is not contextually narrowed.

`targets` is **mandatory on every `defineTransition` call** — the wrapper's whole point is to enumerate the possible outcomes, and an empty/missing array would silently sit out of precise-mode preload while looking annotated. If you don't want to declare outcomes, use a bare function — the runtime invocation path is identical.

```ts
import { defineJourney, defineTransition } from "@modular-react/journeys";

// Bind the journey's generics once — every `transition({ ... })` call below
// gets autocomplete on `targets` and contextual narrowing on `next`. Naming
// mirrors `selectModule`: a descriptive verb for the binder, not an
// abbreviation (`tx` reads as "transaction" in most codebases).
const transition = defineTransition<OnboardingModules, OnboardingState>();

export const onboardingJourney = defineJourney<OnboardingModules, OnboardingState>()({
  // ...
  transitions: {
    profile: {
      review: {
        // Multi-target next: outlet preloads BOTH chunks during the idle
        // window after profile/review mounts. Handler return is narrowed
        // to `{ next: planChoose | billingCollect }` — returning `abort`
        // here would be a compile error.
        profileComplete: transition({
          targets: [
            { module: "plan", entry: "choose" },
            { module: "billing", entry: "collect" },
          ],
          handle: ({ output, state }) => ({
            state: { ...state, hint: output.hint },
            next:
              output.hint === "cheap"
                ? {
                    module: "plan",
                    entry: "choose",
                    input: { customerId: state.customerId, hint: output.hint },
                  }
                : {
                    module: "billing",
                    entry: "collect",
                    input: { customerId: state.customerId, amount: 0 },
                  },
          }),
        }),
        // Mixed: handler may advance OR abort. Both arms are declared.
        review: transition({
          targets: [{ module: "plan", entry: "choose" }, "abort"],
          handle: ({ output }) =>
            output.ok
              ? {
                  next: {
                    module: "plan",
                    entry: "choose",
                    input: { customerId: "c", hint: "cheap" },
                  },
                }
              : { abort: { reason: "rejected" } },
        }),
        // Terminal-only: declaring `"abort"` lets the catalog harvester
        // surface the abort flag without an AST walk over the handler body,
        // and constrains the return to just the abort arm at compile time.
        cancelled: transition({
          targets: ["abort"],
          handle: () => ({ abort: { reason: "user-cancelled" } }),
        }),
      },
    },
  },
});
```

Why explicit declarations rather than inferring from the handler body? Handler bodies are dynamic (`next: cond ? A : B`) and may have side effects, so the runtime can't safely run them speculatively to enumerate destinations. One declarative line per wrapped transition is the trade-off — and it doubles as the catalog's authoritative outcome map (no AST walking for `aborts` / `completes` flags either).

**Bare-function handlers still work.** The runtime invocation path is identical, and they sit out of precise-mode preload (`preload="aggressive"` is the fallback). Migrate handlers that fan out to heavy steps first; everything else stays as-is.

### Pattern - branching on state/output inside a handler

Handlers are plain functions - branch with `if` / `switch` on output or state. Return whichever `TransitionResult` makes sense.

```ts
review: {                                  // entry name (the surrounding module key is omitted for brevity)
  done: ({ output, state }) =>             // exit name fired by the `review` entry
    output.needsKyc
      ? { next: { module: "kyc", entry: "collect", input: { customerId: state.customerId } } }
      : { complete: { reason: "ok" } },
}
```

### Pattern - exhaustive state-driven module dispatch (`selectModule`)

When a transition needs to dispatch to one of N modules based on a discriminator (a value picked earlier in the flow, a kind from the previous module's output, etc.), a hand-written `switch` works but loses two things: exhaustiveness when the discriminator's union grows, and per-branch input narrowing without per-branch ceremony. `selectModule<TModules>()` collapses both into one declarative call:

```ts
import { selectModule } from "@modular-react/journeys";

const select = selectModule<IntegrationModules>();

chooser: {                                  // module id - the picker module
  pick: {                                   // entry name on `chooser` - renders the integration list
    chosen: ({ output, state }) => ({       // exit fired when the user picks an integration
      state: { ...state, selected: output.kind },
      next: select(output.kind, {
        // Each key below is a target module id; `entry` / `input` are checked against that module.
        github:     { entry: "configure", input: { workspaceId: state.workspaceId, repo: output.repo } },
        strapi:     { entry: "configure", input: { workspaceId: state.workspaceId, url: output.url } },
        contentful: { entry: "configure", input: { workspaceId: state.workspaceId, spaceId: output.spaceId } },
      }),
    }),
  },
},
```

The cases object is `Record<TKey, …>`, so adding a new value to the discriminator's union without a matching branch is a compile error. Each case's `entry` is type-narrowed against that module's `entryPoints`; `input` is checked against that entry - pasting a `strapi`-shaped input under the `github` key fails at the call site.

**Limit.** The discriminator key must equal the target module id. When they differ (e.g. `tier: "free" | "paid"` dispatching to module ids `trial-onboarding` / `billing-onboarding`), fall back to a `switch` returning `next` per branch - the helper's value is the exhaustiveness + per-branch typing, not the lookup itself.

### Pattern - fallback dispatch (`selectModuleOrDefault`)

When most discriminator values funnel into a generic module and only a few warrant their own dedicated step, use the sibling `selectModuleOrDefault` - it accepts a partial cases map plus an explicit fallback `StepSpec`:

```ts
import { selectModuleOrDefault } from "@modular-react/journeys";

const select = selectModuleOrDefault<IntegrationModules>();

chooser: {                                  // module id - the picker module
  pick: {                                   // entry name on `chooser`
    chosen: ({ output, state }) => ({       // exit fired with the chosen integration kind
      state: { ...state, selected: output.kind },
      next: select(
        output.kind,
        {
          // Keys are target module ids. Only github + strapi earn dedicated configure steps.
          github: { entry: "configure", input: { workspaceId: state.workspaceId, repo: "..." } },
          strapi: { entry: "configure", input: { workspaceId: state.workspaceId } },
        },
        // contentful, notion, future kinds - all flow through the
        // generic configure step.
        { module: "generic", entry: "configure", input: { workspaceId: state.workspaceId, kind: output.kind } },
      ),
    }),
  },
},
```

It's a separate function, not a third argument on `selectModule`, so the _exhaustive_ call site is visually distinct from the _fallback-allowed_ one - adding a third argument later can't silently disable the missing-branch compile error.

**When to prefer which.** Pick `selectModule` (exhaustive) if every discriminator value gets its own dedicated module - the missing-case error is the whole point. Pick `selectModuleOrDefault` (fallback) when you have a real catch-all module: most kinds funnel through generic shape, only a handful warrant tailored UI. A third-party plugin system that lets new integration kinds appear at runtime always wants the fallback form, since the journey can't know every kind ahead of time.

#### Pairing with slot-driven discovery

`selectModule` / `selectModuleOrDefault` plays well with the slots system for the common "chooser → specific" shape:

- Each module contributes itself to a shared slot (e.g. `slots: { integrations: [{ id: "github", label: "GitHub", … }] }`).
- The chooser module reads `useSlots<AppSlots>().integrations` and renders one row per contribution - staying agnostic of which integrations exist.
- The journey's `chosen` transition uses `selectModule(Or)` to dispatch on the picked id.

Slots drive presentation (dynamic, discoverable); the journey owns dispatch (typed, statically declared). See [`examples/react-router/integration-setup-journey/`](../../examples/react-router/integration-setup-journey/) for an end-to-end example with both forms exercised by Playwright.

### Pattern - wildcard transitions (`wildcardTransitions`)

Cross-cutting outcomes - `cancelled`, `error`, `back`, `signedOut` - tend to be emitted by many modules and handled the same way. Rather than copy the same handler under every `transitions[mod][entry]` block, declare it once on `wildcardTransitions`. Two precision tiers:

```ts
defineJourney<Modules, State>()({
  // …id, version, initialState, start…
  transitions: {
    // exact handlers — one per [module][entry][exit] triple.
    profile:  { review:  { approved: ({ output }) => ({ next: ... }) } },
    billing:  { confirm: { approved: ({ output }) => ({ complete: ... }) } },
  },
  wildcardTransitions: {
    // tier 2 — module unknown, entry + exit known.
    // Fires when no exact handler matches AND the active step's entry name is "review".
    byEntryAndExit: {
      review: {
        cancelled: ({ output }) => ({ abort: { reason: "user-cancelled" } }),
      },
    },
    // tier 3 — module + entry both unknown.
    // Fires when no exact handler and no byEntryAndExit handler matches.
    byExit: {
      error: ({ output, state }) => ({
        state: { ...state, lastError: output.code },
        next: { module: "errorScreen", entry: "show", input: { code: output.code } },
      }),
    },
  },
});
```

**Resolution precedence.** The runtime tries three locations in this order, first hit wins:

1. `transitions[currentMod][currentEntry][exit]` - exact, all three known.
2. `wildcardTransitions.byEntryAndExit[currentEntry][exit]` - module wildcarded.
3. `wildcardTransitions.byExit[exit]` - module + entry both wildcarded.

So a more specific handler always preempts a less specific one. No flag, no merge step - just lookup order.

**Type narrowing on the wildcard's `output`.** Because the source module is unknown at the wildcard call site, the handler's `output` type is the **intersection** of `ExitOutputOf` across the matching modules. If those modules' exits emit different shapes, `output` collapses to fields every variant guarantees (or `never`, if the shapes are incompatible). The fix is to share a single `defineExitContract` value across modules - see the next pattern.

**`input` typing.** A `byEntryAndExit` handler's `input` is the intersection of `EntryInputOf<TModules[M], E>` across modules that declare entry `E` (the entry name is known, so this is sharper than tier 3). A `byExit` handler's `input` is `unknown` (entry is also unknown) - read step context via `onTransition` if you need it.

**Validation at registration time.** Every wildcard slot is checked. The checks have deliberately different scopes:

| Check                                                                                                                                 | Scope                                                                                                                                                                                                                                                                                    | Effect                                                                                      |
| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Live-key.** `byExit["nope"]` no module emits, or `byEntryAndExit["review"]["typo"]` no module pairs.                                | App-wide (every registered module). The journey may navigate to modules via `next` transitions whose targets aren't statically introspectable, so narrowing this would false-reject legitimate wildcards. The check's job is typo detection, which a loose scope serves better.          | `JourneyValidationError`                                                                    |
| **Contract consistency.** Modules sharing a wildcard slot must use the same `ExitContract` instance for the exit.                     | Journey-scoped (modules keyed under `def.transitions`). The wildcard's typed `output` is determined by the modules the journey actually navigates to; an unrelated registry module that happens to use a different contract for the same exit name must not produce a spurious mismatch. | `JourneyValidationError`                                                                    |
| **Tier-overlap.** Same exit declared under both `byEntryAndExit[E][X]` and `byExit[X]`; `byExit` is unreachable from entry `E`.       | n/a — only inspects the journey's own `wildcardTransitions`.                                                                                                                                                                                                                             | `console.warn` (sometimes deliberate).                                                      |
| **Shape.** `wildcardTransitions`, `byEntryAndExit`, `byExit`, and inner entry maps must be plain objects (rejects `null` and arrays). | n/a — structural.                                                                                                                                                                                                                                                                        | `JourneyValidationError` with the actual rejected kind in the message (e.g. `"got array"`). |

### Pattern - shared exit contracts (`defineExitContract`)

Wildcard transitions read across modules - so when several modules emit the same kind of exit (`cancelled`, `error`, ...), the journey wants a _single_ output shape regardless of which module fired. A **shared exit contract** locks that shape in: define it once, reference the same value as the schema for every module's exit. Two effects:

1. **Wildcard `output` narrows to a single typed shape** - the contract's `T`, not the intersection.
2. **Cross-module shape consistency is enforced at registration** - if two modules emit `cancelled` with different contract instances, `validateJourneyContracts` throws.

```ts
// shared/exits.ts — shared across the modules that emit these
import { defineExitContract } from "@modular-react/core";
import { z } from "zod";

// Type-only contract — declared TOutput, no runtime validation.
export const errorContract = defineExitContract<{ code: string }>("error");

// Schema-backed contract — TOutput inferred from the schema, runtime
// validates payloads at every emit. Works with any StandardSchemaV1
// implementation: Zod, Valibot, ArkType, ...
export const cancelledContract = defineExitContract("cancelled", z.object({ reason: z.string() })); // ExitContract<{ reason: string }>
```

```ts
// modules/profile/exits.ts and modules/billing/exits.ts — both reference
// the same contract values. Identity is what makes consistency cheap.
import { defineExit } from "@modular-react/core";
import { cancelledContract, errorContract } from "../../shared/exits.js";

export const profileExits = {
  approved: defineExit<{ profileId: string }>(),
  cancelled: cancelledContract, // shared
  error: errorContract, // shared
} as const;
```

**Runtime validation.** When the contract carries a schema, the runtime validates every payload at `exit()` emit - _before_ any handler runs - and aborts the journey with a typed system reason on issues:

| Outcome                                     | System abort reason          | Payload                                                   |
| ------------------------------------------- | ---------------------------- | --------------------------------------------------------- |
| Payload fails schema                        | `exit-payload-invalid`       | `{ exit, issues: ReadonlyArray<StandardSchemaV1.Issue> }` |
| Schema returns a Promise (async refinement) | `exit-payload-invalid-async` | `{ exit }`                                                |

Both reasons flow through the existing `isJourneySystemAbort()` predicate. Async schemas are rejected because the journey runtime is intentionally synchronous - put async refinement work inside a loading entry point on a module instead. Schemas that throw during validation surface as a normal `transition-error` abort and fire `onError`.

**Why Standard Schema, not Zod-direct.** `@standard-schema/spec` is a type-only package (~0 bytes runtime, single interface) that Zod, Valibot, ArkType, and others all implement. Consumers pick the schema lib that fits; this package stays library-agnostic. Same approach TanStack Router uses for search-param validation.

**Validation lifecycle.** `validateJourneyContracts` is a **registration-time snapshot** — it sees the modules registered with the registry at the moment `resolveManifest()` / `resolve()` runs, and the runtime is rebuilt with the same snapshot in the same tick. So in normal lifecycles (plugins, route-driven entry loading, HMR re-bundle, fresh test setup), every module change re-triggers `resolve()` which re-runs validation — coverage stays current.

**Runtime drift spot-check.** For bypass cases (direct `createJourneyRuntime` use, plugin composition that adds modules after validation, test mocks that swap descriptors between resolves), the runtime adds a lazy belt-and-suspenders check that mirrors the validator's contract-consistency scope: at the first dispatch of each contract-based exit fired by a journey, it walks the dispatching journey's _own_ modules (those keyed under `def.transitions`, intersected with the runtime's module map) and emits a warning if two of them declare the same exit via _different_ `ExitContract` instances. The result is cached per `[journeyId, exitName]` pair, so the per-pair cost is paid once and the hot path is amortized free. Gated on the runtime's `debug` flag at the call site — production builds pay nothing (no function call, no Set lookup, no walk).

### Pattern - terminal with structured payload

`complete` and `abort` both take `unknown` - pass any shape you want. Consumers read it via `instance.terminalPayload` or the `outcome.payload` arg to `onFinished`.

```ts
// `paid` here is an exit name (the surrounding `<module>: { <entry>: { … } }` keys are omitted).
paid: ({ output }) => ({ complete: { kind: "paid", reference: output.reference, amount: output.amount } }),
```

### Pattern - overriding `state` during a transition

Every handler is free to rewrite state:

```ts
// `choseStandard` is an exit name on some <module>.<entry> (keys omitted for brevity).
choseStandard: ({ output, state }) => ({
  state: { ...state, selectedPlan: output.plan },
  next: { module: "billing", entry: "collect", input: { customerId: state.customerId, amount: output.plan.monthly } },
}),
```

If you omit `state`, the incoming state is preserved. Writing `state: undefined` is treated as an explicit write (for state types that allow it) - the key `"state"` being _present_ is what signals intent.

### Pattern - keeping state immutable

Snapshots captured for `allowBack: 'rollback'` are **shallow clones**. Deep mutation of nested values corrupts the snapshot. Treat state as immutable - return a new object every time. In dev mode the runtime shallow-freezes the snapshot so a top-level mutation throws loudly.

### Pattern - bounded history (`maxHistory`)

Register with a cap to prevent unbounded growth in long-running journeys:

```ts
registry.registerJourney(journey, { maxHistory: 50 });
```

Caveat: a cap smaller than the deepest reachable back-chain silently breaks `goBack` past the trim point (the rollback snapshot `goBack` would restore is among the dropped entries). Size it to at least the longest user-reachable back chain, or treat it as a hard "no-one will navigate back this far" window.

Omitting `maxHistory`, or passing `0` or a negative number, leaves history unbounded.

### Pattern - module compatibility (`moduleCompat`)

A journey is implicitly coupled to the **exit names**, **input shapes**, and **`allowBack` semantics** of every module it references in `transitions`. When those modules ship from other teams, a backwards-incompatible bump on the other side ("we renamed `success` to `done`") would otherwise only surface at runtime — when the user actually navigated to the now-broken step.

`moduleCompat` is a registration-time guard: declare the npm-style version range your journey was authored against, and the journeys plugin checks it against each module's `version` field at `resolveManifest()` time. An incompatible deployment refuses to come up at all instead of silently breaking one user mid-flow.

```ts
defineJourney<OnboardingModules, OnboardingState>()({
  id: "customer-onboarding",
  version: "1.0.0",
  moduleCompat: {
    profile: "^1.0.0",
    plan: ">=1.5.0 <2.0.0",
    // multiple major lines accepted explicitly
    billing: "^2.0.0 || ^3.0.0",
  },
  initialState: () => ({
    /* ... */
  }),
  start: () => ({
    module: "profile",
    entry: "review",
    input: {
      /* ... */
    },
  }),
  transitions: {
    /* ... */
  },
});
```

What the validator does at `resolveManifest()` time:

| Situation                                      | Result                                                               |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| Range admits the registered module's `version` | OK.                                                                  |
| Range does not admit it                        | `JourneyValidationError` listing journey id, module, range, version. |
| Range names a module that isn't registered     | `JourneyValidationError` ("not registered").                         |
| Range string is malformed                      | `JourneyValidationError` echoing the offending input.                |
| Module's own `version` is malformed            | `JourneyValidationError` ("unparseable version").                    |

All issues are accumulated and reported in one error so a deployment with several mismatched teams sees the full list in one CI run, not one bug at a time.

**Range syntax.** A subset of npm semver: caret (`^1.2.3`), tilde (`~1.2.3`), x-range (`1.x`, `1.2.x`, `*`), comparators (`>=1.2.3`, `<2.0.0`, `=1.2.3`), AND (whitespace-separated), OR (`||`-separated), and hyphen ranges (`1.2.3 - 2.0.0`). Pre-release tags and build metadata are not supported — module versions in this framework are stable releases by contract.

**Why a custom semver implementation?** The full `semver` package handles a much wider grammar than this use-case needs and parses regex-heavy on every call. The journeys-internal subset was originally cross-checked against `semver@7.7.4` and ran ~5× faster on the cached path and ~1.7× faster on one-shot parses on a representative grid; see [`bench/semver.bench.ts`](bench/semver.bench.ts) for the historic numbers and a self-contained benchmark of the local implementation. The cross-checked outcomes are frozen as a fixture grid in [`src/semver.test.ts`](src/semver.test.ts) so any regression in our implementation is caught without keeping `semver` as a devDependency. If a range or version is outside the supported subset the parser throws synchronously, so an untested edge case fails loudly at registration rather than as a silent "no match."

**When to omit it.** Modules that you and the journey ship together (same team, same release cadence, same monorepo) gain nothing from a compat declaration — the structural validators (`transitions` referencing real modules / entries / exits) already catch shape drift. The compat check earns its keep when the journey and a module are versioned independently.

**Coverage is opt-in, not exhaustive.** `moduleCompat` is a one-way declaration: any module you list there is checked against the registered version, and a stale entry naming a module that isn't registered fails loudly. But a module the journey actually transitions through and _doesn't_ list in `moduleCompat` is silently fine — the validator does not require coverage for every module referenced by `transitions`. List the modules whose compatibility you care about; omit the rest. Module ids are also typed against the journey's `TModules` map, so a typo on a known module id is a compile error.

## Composing journeys (invoke / resume)

Sometimes mid-flow you need to detour into a _different_ journey — e.g. inside checkout the customer needs to verify identity, or inside an integration setup the user needs to add a new credential. The parent journey suspends, the child runs to a terminal, the parent picks up where it left off with the child's terminal payload in hand, and continues. Modular-react models this as a **subroutine**: one new transition primitive (`invoke`) plus a **named resume** handler that fires when the child terminates.

The model is deliberately narrow: a parent can have at most one in-flight child per step, the parent's step doesn't change while the child runs, the parent advances only via the resume, and end-ing the parent cascades to the child. If you genuinely need parallel sub-flows (rare), call `runtime.start()` directly and own the bookkeeping — that path remains available.

### The shape

A transition handler returns an `{ invoke: { handle, input, resume } }` arm instead of `{ next | complete | abort }`. Build it with the typed `invoke()` helper — a bare object literal **does not** cross-check `input` against the handle's `TInput` (the discriminated-union arm declares `InvokeSpec<unknown, unknown>` so the runtime can dispatch on any handle). The parent's journey definition declares a sibling `resumes` map mirroring `transitions`:

```ts
import { defineJourney, defineJourneyHandle, invoke } from "@modular-react/journeys";
import { verifyIdentityHandle } from "verify-identity-journey";
//        ^ exported from the child's package via defineJourneyHandle.

defineJourney<CheckoutModules, CheckoutState, { token: string }>()({
  id: "checkout",
  version: "1.0.0",
  initialState: (input: { orderId: string }) => ({ orderId: input.orderId, token: null }),
  start: (s) => ({ module: "checkout", entry: "review", input: { orderId: s.orderId } }),
  transitions: {
    checkout: {
      review: {
        // Exit handler dispatches an invoke instead of next. `invoke()`
        // threads the handle's TInput / TOutput through to `input` and
        // the resume so a wrong-shaped `input` is a compile error.
        requestPayment: ({ state }) =>
          invoke({
            handle: verifyIdentityHandle, // typed handle, see "Journey handles"
            input: { customerId: state.customerId },
            resume: "afterIdentity", // names the resume below
          }),
      },
    },
  },
  resumes: {
    checkout: {
      review: {
        // outcome is ChildOutcome<TVerifyOutput> — completed has a typed
        // payload; aborted carries reason. Both are surfaced; you decide.
        afterIdentity: ({ state, outcome }) =>
          outcome.status === "completed"
            ? {
                state: { ...state, token: outcome.payload.token },
                next: {
                  module: "billing",
                  entry: "collect",
                  input: { orderId: state.orderId, token: outcome.payload.token },
                },
              }
            : { abort: { reason: "identity-failed", cause: outcome.reason } },
      },
    },
  },
});
```

The child journey is a totally normal `defineJourney` — it doesn't know it's being invoked. It declares its `TInput` (input from the parent) and its `TOutput` (the third generic on `defineJourney<TModules, TState, TOutput>()`, narrowing the type of `complete` payloads). Its handle, exported via `defineJourneyHandle(childJourney)`, carries both as phantom types so `invoke()` checks `input` and the parent's resume sees `outcome.payload` typed end-to-end.

### Why named resumes (and not closures)

You might expect `invoke` to take a `resume: (ctx) => ...` closure. We deliberately don't — closures don't survive a persistence reload. Naming the resume keeps everything serializable: the parent's blob records `pendingInvoke.resumeName`, the runtime looks up `def.resumes[mod][entry][name]` on hydrate, and the call chain restores exactly. See the persistence section below for the round-trip details.

Resume names live in their own keyspace from exit names — the lookup tables are siblings, not the same map. **One authoring rule, enforced at registration time:** a resume name must not collide with any exit name on the **same module** (not the same entry — the broader scope catches the typical "I meant a transition handler, not a resume" mistake). `validateJourneyContracts` rejects the registration with an explicit message naming the offender, so a typo at authoring time fails loudly instead of becoming a silent `invoke-unknown-resume` later.

### Lifecycle and edge cases

| Situation                                                                             | Behavior                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Child completes                                                                       | Parent's named resume fires with `{ status: "completed", payload }` (typed).                                                                                                                                                                                                          |
| Child aborts (its own `{ abort }` or `runtime.end`)                                   | Parent's named resume fires with `{ status: "aborted", reason }`. Author decides whether to recover or propagate.                                                                                                                                                                     |
| Parent ended while child active                                                       | Cascade — link is severed first, then the child is ended with terminal payload `{ reason: "parent-ended", parentId, cause: <end-reason> }`, then the parent runs its own `onAbandon` and aborts independently. The resume does **not** fire (the link was nulled before the cascade). |
| Child invokes a grandchild                                                            | Same machinery; the resume bubbles up the chain. The runtime maintains parent links and a reverse map; nothing special.                                                                                                                                                               |
| Parent fires an exit while child is in flight                                         | Dropped with a debug warn — the parent advances only via resume.                                                                                                                                                                                                                      |
| Invoke names an unknown journey id                                                    | Parent aborts immediately with reason `invoke-unknown-journey`. `onError` fires with `phase: "invoke"`.                                                                                                                                                                               |
| Invoke names a resume that isn't declared on the current step                         | Parent aborts with reason `invoke-unknown-resume`. `onError` fires with `phase: "invoke"`.                                                                                                                                                                                            |
| Resume name vanished between invoke and child terminal (definition upgraded mid-flow) | Parent aborts with reason `resume-missing` (carrying `resume` and `childJourneyId`). `onError` fires with `phase: "resume"`.                                                                                                                                                          |
| Resume handler throws                                                                 | Parent aborts with reason `resume-threw`, `error` carries the throw. `onError` fires with `phase: "resume"`.                                                                                                                                                                          |
| Resume handler returns a Promise                                                      | Parent aborts with reason `resume-returned-promise`. Resumes must be sync and pure, like exit handlers.                                                                                                                                                                               |
| Hydrate: child blob missing on reload                                                 | Parent stays `active` with `activeChildId` set; exits remain blocked. The shell decides whether to load the child later or `runtime.end` the parent to give up.                                                                                                                       |

### Outlet behavior

`<JourneyOutlet>` walks the active call chain by default and renders the _leaf_. If the parent has invoked a child, the parent's component disappears and the child's component takes over the same outlet — matching the subroutine intuition. The chain re-renders when any link changes.

For a layered presentation (parent visible underneath, child in a modal), pass `leafOnly={false}` on the outer outlet to keep it on the parent's step, and mount a sibling outlet against `instance.activeChildId` (or use `useJourneyCallStack`) for the child:

```tsx
import { JourneyOutlet, useJourneyCallStack } from "@modular-react/journeys";

function CheckoutPanel({ instanceId }: { instanceId: InstanceId }) {
  const chain = useJourneyCallStack(runtime, instanceId);
  // `chain[length - 1]` is the active *leaf*. For shallow nesting that's
  // the immediate child; for parent → child → grandchild the modal will
  // surface the grandchild instead. Use `instance.activeChildId` directly
  // if you specifically want the immediate child.
  const leafId = chain.length > 1 ? chain[chain.length - 1] : null;
  return (
    <>
      <JourneyOutlet runtime={runtime} instanceId={instanceId} leafOnly={false} />
      {leafId ? (
        <Modal>
          <JourneyOutlet runtime={runtime} instanceId={leafId} />
        </Modal>
      ) : null}
    </>
  );
}
```

`onFinished` on a `<JourneyOutlet>` fires for the **root** instance only — it's the journey the caller mounted. Child terminations are observed via the parent's resume handler, not the outer outlet.

### Persistence (round-tripping invoke state)

When a parent has an in-flight child, `serialize()` emits `pendingInvoke` on the parent and `parentLink` on the child:

```jsonc
// parent blob
{
  // ...standard fields
  "pendingInvoke": {
    "childJourneyId": "verify-identity",
    "childInstanceId": "ji_abc",
    "childPersistenceKey": "verify-identity:cust-42",
    "resumeName": "afterIdentity"
  }
}

// child blob
{
  // ...standard fields
  "parentLink": { "parentInstanceId": "ji_xyz", "resumeName": "afterIdentity" }
}
```

`childPersistenceKey` is `string | null` — it's `null` when the child journey has no persistence adapter configured. The parent still tracks `childInstanceId` in memory, but on a process restart the child can't be reloaded from storage and the parent will land in the "child blob missing" state described in the lifecycle table.

**Auto-rehydrate.** Calling `runtime.start(parentHandle, input)` on a fresh runtime against the same persistence backing will pull the parent blob, see the `pendingInvoke.childPersistenceKey`, and load the child blob automatically — recursing into grandchildren if the child blob carries its own `pendingInvoke`. Shells only need to `start()` the root; the leaf comes back along with its parents.

After every hydrate path (sync start, async start, explicit `runtime.hydrate`), the runtime relinks every in-memory pair via the `parent` / `activeChildId` fields. Order doesn't matter — hydrate the parent first, then the child, or vice versa; the link reconciles either way. A parent whose `activeChildId` references a not-yet-loaded child stays `active` (exits blocked) until the child arrives.

If the child's blob is gone for good (TTL expired, manual remove, or no persistence configured on the child), the shell decides recovery: keep the parent suspended, or `runtime.end(parent)` to give up. The runtime does not auto-abort, because that would race with multi-step hydrates that legitimately load the parent first.

### Telemetry: `TransitionEvent.kind`

Every event a registered `onTransition` hook receives now carries a `kind` discriminator:

```ts
onTransition: (ev) => {
  if (ev.kind === "step") metrics.record("journey.hop", { id: ev.journeyId });
  if (ev.kind === "invoke")
    metrics.record("journey.invoke", { id: ev.journeyId, child: ev.child?.journeyId });
  if (ev.kind === "resume")
    metrics.record("journey.resume", { id: ev.journeyId, resume: ev.resume });
};
```

A consumer that only cares about top-level steps filters `kind === "step"`. Otherwise read `ev.child` on invokes and `ev.outcome` / `ev.resume` on resumes.

### Testing

The simulator drives both modes:

```ts
import { simulateJourney } from "@modular-react/journeys";

// Drive a real child sub-simulator end-to-end:
const sim = simulateJourney(
  parentJourney,
  { orderId: "O-1" },
  {
    children: [verifyIdentityJourney],
  },
);
sim.fireExit("requestPayment");
sim.activeChild!.fireExit("verified", { token: "T" }); // child runs to terminal
expect(sim.currentStep.entry).toBe("collect"); // parent has resumed

// Or mock the child's outcome to unit-test the parent's resume in isolation:
const sim2 = simulateJourney(
  parentJourney,
  { orderId: "O-2" },
  {
    children: [verifyIdentityJourney],
  },
);
sim2.fireExit("requestPayment");
sim2.completeChild({ token: "T-MOCK" }); // synthesize completed
expect(sim2.state.token).toBe("T-MOCK");

sim2.abortChild({ code: "denied" }); // synthesize aborted — reason reaches the resume as-is, no wrap
```

`completeChild` uses the runtime's standard transition machinery — `onComplete`, `onTransition`, persistence, and the parent's resume hook all fire as they would for a real `{ complete }`.

### What this is _not_

- **Not shared state.** Each journey owns its `TState`; communication is exclusively via `input` (down) and `outcome.payload` (up). Preserves the mental-model boundary.
- **Not concurrent spawn.** A parent has at most one active invocation. If you need parallel children, call `runtime.start()` directly and store ids in state — but you give up the typed resume linking, the persisted `pendingInvoke` / `parentLink` round-trip, the `activeChildId` chain that `<JourneyOutlet>` walks, and the cascade-end semantics. Everything becomes shell-managed.
- **Not back-navigation across the boundary.** `goBack` stays scoped to a journey's own history. To return from a child without completing, fire an exit that maps to `{ abort }`; the parent's resume handler decides what to do.

### Cycle and recursion safety

Composing journeys creates a _call graph_ — A invokes B, which invokes C, possibly back into A. Without guards, a cycle becomes either an infinite chain that exhausts memory or a same-step bouncing resume that pegs the CPU. Modular-react ships **four layered guards**, three at runtime (always on) plus an opt-in static check at registration time. Every guard surfaces through the existing `onError` channel with `phase: "invoke"` (or `"resume"`) and aborts the offending parent with a discoverable reason — same vocabulary as the other validation aborts.

| Guard                       | When it fires                                                                                                                                                                                                                            | Abort reason              | Default                              |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------ |
| **Static cycle detection**  | Registration time, when every journey on the cycle path declares its `invokes` set. Throws `JourneyValidationError` listing the cycle path (e.g. `cycle detected: "A" → "B" → "A"`).                                                     | (registration error)      | always on when `invokes` is declared |
| **invoke-undeclared-child** | Runtime invoke time, when the parent journey declared an `invokes` array but the dispatched handle id is not in it. Catches dynamic-dispatch typos.                                                                                      | `invoke-undeclared-child` | always on when `invokes` is declared |
| **invoke-cycle**            | Runtime invoke time, when the target journey id already appears on the active parent chain. Catches cycles that the static check missed (because some journey on the cycle omitted `invokes`).                                           | `invoke-cycle`            | always on                            |
| **invoke-stack-overflow**   | Runtime invoke time, when admitting the new child would push the chain depth past the resolved cap. The cap is the **minimum** of every non-undefined `maxCallStackDepth` across the active chain (ancestors + parent + would-be child). | `invoke-stack-overflow`   | `maxCallStackDepth: 16`              |
| **resume-bounce-limit**     | Runtime resume time, when a resume returns `{ invoke }` for the Nth consecutive time at the _same parent step_ (the counter resets when the parent's step actually advances).                                                            | `resume-bounce-limit`     | `maxResumeBouncesPerStep: 8`         |

#### Declaring the call set (`invokes`)

The strongest line of defense is opt-in: list every child handle the journey can dispatch to.

```ts
import { defineJourney, defineJourneyHandle, invoke } from "@modular-react/journeys";
import { verifyIdentityHandle } from "verify-identity-journey";
import { addPaymentMethodHandle } from "add-payment-method-journey";

defineJourney<CheckoutModules, CheckoutState>()({
  id: "checkout",
  version: "1.0.0",
  // Closed set — the runtime rejects any other handle at invoke time, and
  // the registry runs cycle detection across the declared graph at boot.
  invokes: [verifyIdentityHandle, addPaymentMethodHandle],
  // ...transitions / resumes that may dispatch invoke() to either handle.
});
```

When **every** journey in a registration declares `invokes`, the registry's `validateJourneyContracts` (which calls `validateJourneyGraph` internally before its own structural checks) builds the full directed graph and rejects the whole registration on a cycle:

```
JourneyValidationError: Invalid journey registration:
  - journey invoke cycle detected: "checkout" → "verify-identity" → "checkout"
```

The cycle check is **already part of the standard registry validation pipeline** — you do not need to opt in. Authors who want to run the graph check by hand (e.g. while composing registrations across plugin boundaries before handing them to the registry) can call `validateJourneyGraph(journeys)` directly; both functions throw `JourneyValidationError` with the same per-cycle message format.

When some journeys omit `invokes`, the static check is incomplete (their out-edges are unknown), so the runtime guards remain the safety net. There is no penalty for omitting `invokes`; it's purely a confidence dial.

#### Tuning `maxCallStackDepth`

Set on the journey's registration options. Any journey in the chain can lower the cap; none can raise it. Setting it to `1` blocks `invoke` from this journey outright (useful for "leaf" journeys that should never spawn children).

```ts
registry.registerJourney(checkoutJourney, {
  maxCallStackDepth: 4, // checkout is happy to host up to 3 nested children
  persistence: ...,
});
```

The resolved cap on each `invoke` is `min(non-undefined options across [ancestors..., parent, child])`, falling back to `16`. The strictest journey in the chain wins, which means a cautious utility journey can lower the cap for any composition that includes it without coordinating with the other journeys.

`0`, negative, or non-finite values are treated as "no opinion" (consistent with `maxHistory`) so a misconfigured `0` cannot silently disable the guard.

#### Tuning `maxResumeBouncesPerStep`

A "bounce" is a resume that returns `{ invoke }` instead of advancing the parent's step. Counted per-parent, scoped to the parent's current step (not the parent's instance) — so a flow that legitimately retries a sub-flow several times in a row is fine, as long as the parent eventually advances. The counter resets whenever the parent's step actually changes (`{ next | complete | abort }` from any source).

```ts
registry.registerJourney(checkoutJourney, {
  maxResumeBouncesPerStep: 3, // verify, fail, retry, fail, retry → abort
});
```

The bounce cap is per-parent — only the parent's own option governs (children don't see the parent's resumes and have no business voting). The counter is **persisted on the parent's blob** as `resumeBouncesAtStep`, so a hostile or accidental reload-bounce-reload-bounce sequence cannot reset the budget through storage. `0`, negative, or non-finite values fall through to the library default of `8`.

#### Failure surface

All four guards abort the offending parent with a structured `terminalPayload` that's safe to log. The shapes:

```ts
// invoke-undeclared-child
{ reason: "invoke-undeclared-child", parentJourneyId: "...", childJourneyId: "...", exit: "..." }

// invoke-cycle (chain mirrors the printed warning — cycle portion only,
// pre-cycle prefix dropped, duplicate target id appears at both ends)
{ reason: "invoke-cycle", childJourneyId: "B", chain: ["B", "C", "D", "B"], exit: "..." }

// invoke-stack-overflow (chain is the full ancestors → parent → child)
{ reason: "invoke-stack-overflow", depth: 17, cap: 16, chain: ["a", "b", ..., "p"], exit: "..." }

// resume-bounce-limit
{ reason: "resume-bounce-limit", cap: 8, count: 9, resume: "afterChild" }
```

Each one fires the registration's `onError` first (with `phase: "invoke"` for the first three, `phase: "resume"` for the last), so telemetry still observes the underlying control-plane failure even when the abort itself is what reaches the user.

**Typed narrowing.** The four guards above plus every other runtime-emitted abort (`invoke-unknown-journey`, `invoke-unknown-resume`, `resume-missing`, `resume-threw`, `transition-error`, …) share a single discriminated union, `JourneySystemAbortReason`. Pair it with the `isJourneySystemAbort` predicate to narrow against author-supplied aborts (`{ abort: "user-cancelled" }`, `{ abort: { reason: "user-thing" } }`, etc.), which the predicate excludes by checking the `reason` against the closed set of system codes:

```ts
import { isJourneySystemAbort } from "@modular-react/journeys";

resumes: {
  checkout: {
    review: {
      afterIdentity: ({ outcome }) => {
        if (outcome.status !== "aborted") return /* ... */;
        if (isJourneySystemAbort(outcome.reason)) {
          // outcome.reason is now the discriminated union — switch on `reason`
          // for typed access to per-arm fields:
          switch (outcome.reason.reason) {
            case "invoke-cycle":
              metrics.record("invoke_cycle", { chain: outcome.reason.chain });
              break;
            case "resume-bounce-limit":
              metrics.record("bounce_limit", { cap: outcome.reason.cap });
              break;
          }
        } else {
          // author-supplied abort (e.g. `{ abort: { code: "denied" } }`) —
          // narrow as you would any other unknown payload.
        }
        return { abort: outcome.reason };
      },
    },
  },
},
```

The `JourneySystemAbortReasonCode` literal-string union is also exported if you only need the code list (e.g. for a `Set` membership check or a switch over an external classification).

## Runtime surface

`manifest.journeys` implements `JourneyRuntime`:

```ts
interface JourneyRuntime {
  /**
   * Handle form (preferred) - `input` is type-checked against the handle's
   * phantom `TInput`. See "Journey handles" below for the pattern.
   */
  start<TId extends string, TInput>(
    handle: JourneyHandleRef<TId, TInput>,
    input: TInput,
  ): InstanceId;
  /**
   * String-id form - accepts any `input`. Useful for dynamic dispatch
   * where the id only exists at runtime (e.g. a navbar action carrying
   * `{ kind: "journey-start", journeyId }`).
   */
  start<TInput>(journeyId: string, input: TInput): InstanceId;

  /**
   * Explicit hydrate from a caller-supplied blob. Persistence-unlinked:
   * the hydrated instance doesn't claim a persistence key and won't be
   * saved back. Useful for read-only audit/replay views.
   */
  hydrate<TState>(journeyId: string, blob: SerializedJourney<TState>): InstanceId;

  getInstance(id: InstanceId): JourneyInstance | null;
  listInstances(): readonly InstanceId[];
  listDefinitions(): readonly JourneyDefinitionSummary[];

  /**
   * Cheap predicate for "is this journey id known to this runtime?"
   * Useful when rehydrating persisted shell state (tabs, task queue, …)
   * to drop entries for journeys renamed or removed between deploys -
   * avoids routing expected drops through the `UnknownJourneyError`
   * exception channel.
   */
  isRegistered(journeyId: string): boolean;

  /** Subscribe to changes on one instance. Returns unsubscribe. */
  subscribe(id: InstanceId, listener: () => void): () => void;

  /**
   * Pop the active step back to the previous one. Equivalent to the
   * `goBack` prop the host hands the active step's component, but
   * addressable by id so a shell that owns its own back button
   * (browser `popstate`, hardware back, breadcrumb) can wire it
   * directly. No-op when the id is unknown, the instance is terminal
   * / loading, a child journey is in flight, the transition didn't
   * opt into `allowBack: true`, the registered module entry declares
   * `allowBack: false`, or history is empty. Matches the closure form
   * on `ModuleEntryProps.goBack`.
   */
  goBack(id: InstanceId): void;

  /**
   * Redo the most recent `goBack` — restore the captured post-transition
   * `state` + `step` so the runtime lands back where the user just
   * rewound from. Lets shells wire browser Forward (or a redo button)
   * to journey navigation instead of letting the URL drift ahead of
   * the runtime. Does NOT re-run the transition handler; the captured
   * state wins, so for `rollback`-mode entries any edits made between
   * the rewind and the redo are discarded. No-op when the future
   * stack is empty (any fresh exit clears it, matching browser
   * back/forward semantics).
   */
  goForward(id: InstanceId): void;

  /**
   * Predicate that mirrors the guards in `goBack`. Returns `true` iff
   * calling `goBack(id)` right now would actually rewind a step. Lets
   * shells gate the visual state of a Back button authoritatively
   * without duplicating the runtime's transition/entry opt-in logic.
   * Returns `false` for unknown / terminal / loading instances, when a
   * child journey is in flight, when history is empty, when the
   * journey transition does not declare `allowBack: true`, or when the
   * registered module entry declares `allowBack: false` (an entry
   * without a registered descriptor inherits the journey's opt-in —
   * matches the simulator fallback on `JourneyRuntimeOptions.modules`).
   */
  canGoBack(id: InstanceId): boolean;

  /**
   * Predicate that mirrors the guards in `goForward`. Returns `true`
   * iff calling `goForward(id)` right now would actually restore a
   * redo target.
   */
  canGoForward(id: InstanceId): boolean;

  /**
   * End an instance. Fires `onAbandon` if still active; no-op if already
   * terminal or unknown. A plain `end()` applies whatever `onAbandon`
   * returns — so a non-terminal result (`{ next }` / `{ invoke }`) advances
   * the flow and leaves the instance **active**, not terminal. Pass
   * `{ force: true }` for a teardown caller (an unmounting host/outlet) that
   * must end up terminal: a terminal `onAbandon` result is still honoured,
   * but a non-terminal one is coerced to an abort so `forget()` can drop the
   * record instead of leaking a live instance.
   */
  end(id: InstanceId, reason?: unknown, options?: { readonly force?: boolean }): void;

  /** Drop a terminal instance from memory. No-op on active/loading. */
  forget(id: InstanceId): void;

  /**
   * Cancel an instance AND discard its persisted blob — `end(id, reason,
   * { force: true })` + `forget(id)` in one call. The "throw the flow away"
   * affordance a Cancel button wants, addressable by id so a shell never
   * re-derives `persistence.keyFor(input)` to remove the blob by hand. (Ending
   * is what deletes persistence: any terminal transition removes the blob, and
   * a *soft* close that keeps it for resume simply does not end the instance.)
   */
  discard(id: InstanceId, reason?: unknown): void;

  /** Drop every terminal instance in one call. Returns the drop count. */
  forgetTerminal(): number;
}
```

Both `start` overloads resolve to the same runtime call; the handle form only exists to type-check `input`. Prefer handles in new code - see [Journey handles](#journey-handles) for the full pattern.

### When to call which

| Situation                                                             | Use                                                              |
| --------------------------------------------------------------------- | ---------------------------------------------------------------- |
| User clicks "start customer onboarding".                              | `runtime.start(onboardingHandle, { customerId })` - handle form. |
| Dynamic dispatch (navbar action / command palette with an opaque id). | `runtime.start(action.journeyId, input)` - string-id form.       |
| Reloading the shell and restoring tabs from localStorage.             | `runtime.start(…)` again - persistence resumes.                  |
| Filter persisted shell state before calling `start()`.                | `runtime.isRegistered(journeyId)` - cheap pre-check.             |
| Read-only "show me what this journey looked like in audit log #1234". | `runtime.hydrate(journeyId, blob)` - no persistence.             |
| Shell wants to react to state changes (tab title, breadcrumb).        | `runtime.subscribe(id, listener)`                                |
| User closes a journey tab before it completes.                        | Let `<JourneyOutlet>` unmount - it calls `end()`.                |
| Shell explicitly cancels (e.g. "end shift").                          | `runtime.end(id, { reason: 'end-of-shift' })`                    |
| A "Cancel" button that throws the flow away AND its saved progress.   | `runtime.discard(id)` - end + forget + remove blob, in one call. |
| Long-running workspace accumulated finished journeys; free memory.    | `runtime.forgetTerminal()`                                       |
| After `onFinished`, prune this specific terminal instance.            | `runtime.forget(id)`                                             |

### `listDefinitions()` and `listInstances()`

Primarily useful for diagnostics, command palettes, or admin tooling. A "launch journey" picker can render `runtime.listDefinitions()` directly; a "which journeys are open for this user" debug panel can walk `runtime.listInstances()` and `getInstance(id)`.

### Journey handles

A **journey handle** is a typed token a journey package exports so shells and modules can open it with a correctly-shaped `input` without importing the journey's runtime code. Export one per journey:

```ts
// journeys/customer-onboarding/src/customer-onboarding.ts
import { defineJourney, defineJourneyHandle } from "@modular-react/journeys";

export const customerOnboardingJourney = defineJourney<Modules, State>()({
  id: "customer-onboarding",
  version: "1.0.0",
  initialState: ({ customerId }: { customerId: string }) => ({
    /* … */
  }),
  /* … */
});

// Publish a handle alongside the journey definition - same package, same file.
export const customerOnboardingHandle = defineJourneyHandle(customerOnboardingJourney);
```

At the call site, pass the handle to `runtime.start`:

```ts
import { customerOnboardingHandle } from "@myorg/journey-customer-onboarding";

const instanceId = runtime.start(customerOnboardingHandle, { customerId: "C-1" });
// input is type-checked end-to-end - wrong shape = compile error.
```

`defineJourneyHandle(def)` returns `{ id: def.id }` at runtime; the input-type check lives entirely in the type system (the `__input` field is phantom - no value, never read). This is why modules and shells can `import type`-only from a journey package and still get full `input` checking without pulling the journey definition into their bundle.

Why handles exist:

- **No runtime coupling.** A module that launches a journey imports the handle via `import type` - the journey's transition code never enters the module's bundle.
- **Type-safe `input`.** The handle carries `TInput` as a phantom; `runtime.start(handle, input)` is the overload that type-checks it. The string-id form accepts any input and is the right call only for dynamic dispatch (e.g. a nav action carrying an opaque `journeyId`).
- **Single canonical id.** `handle.id === def.id` at runtime; dedup/lookup code can compare handles or ids interchangeably without casing on which one it received.

The string-id `start()` overload stays supported precisely because plugin-contributed nav items carry `{ kind: "journey-start", journeyId }` - a dispatcher can't hold a handle reference for every registered journey, so it falls back to the string form.

## `JourneyProvider` + context

`JourneyProvider` supplies the runtime (and an optional `onModuleExit` fallback) to descendant `<JourneyOutlet>` and `<ModuleTab>` nodes via context. Mount it once at the top of the shell:

```tsx
<JourneyProvider runtime={manifest.journeys} onModuleExit={manifest.onModuleExit}>
  <AppRoutes />
</JourneyProvider>
```

Explicit `runtime` / `modules` props on `<JourneyOutlet>` still win - useful when a single tree needs to reach two distinct runtimes (split-screen agents, multi-tenant dashboards). `useJourneyContext()` exposes the current value (or `null` when no provider is mounted) for shells that need the runtime for non-React-rendering work - e.g. opening a new tab from a command-palette handler.

Because `useJourneyContext()` can return `null`, examples that use the non-null assertion (`useJourneyContext()!.runtime`) are only safe **inside a tree where the provider is guaranteed to be mounted** - typically the subtree below `<JourneyProvider>` in your shell. In code paths that can legitimately run outside the provider (e.g. a shared utility callable from both journey-aware and journey-unaware hosts), null-check the return value instead and fall back to whatever the caller supplied.

## Persistence

**Persistence is optional.** Skip it and journeys live in memory only - every `runtime.start()` mints a fresh instance and nothing is written to storage. Add an adapter when you want reload recovery (resuming after a refresh) or idempotent `start` (the same input returning the same `instanceId`).

When you do want it, plug an adapter in at registration. The preferred shape is `defineJourneyPersistence<TInput, TState>` - it types `keyFor`'s `input` against the journey's `TInput` and `load` / `save` against its `TState`, so there's no `as` cast at the call site:

```ts
import { defineJourneyPersistence } from "@modular-react/journeys";

registry.registerJourney(journey, {
  persistence: defineJourneyPersistence<OnboardingInput, OnboardingState>({
    keyFor: ({ journeyId, input }) => `journey:${input.customerId}:${journeyId}`,
    load: (key) => backend.loadJourney(key),
    save: (key, blob) => backend.saveJourney(key, blob),
    remove: (key) => backend.deleteJourney(key),
  }),
});
```

A plain object matching `JourneyPersistence<TState>` still works if you'd rather not use the helper.

### Registering multiple journeys

A shell registering more than one journey has two safe shapes for persistence and one tempting trap.

**Safe — one typed adapter per journey.** Declare each `createWebStoragePersistence<TInput, TState>` (or `defineJourneyPersistence<TInput, TState>`) call against its own journey's types and pass it to that journey's `registerJourney`. This is what `examples/react-router/journey-invoke` and `examples/tanstack-router/journey-invoke` do — separate `checkoutPersistence` and `verifyIdentityPersistence` exports, each typed to its own journey's state. Use this shape when the setup expression is short and you don't mind repeating it.

**Safe — a generic factory.** Wrap the setup in a `makeJourneyPersistence<TInput, TState>()` helper and invoke it per `registerJourney`. Use this shape when the setup expression is long (custom SSR guards, lazy `storage` getters, shared `keyFor` scheme) and you want a single source of truth without per-call repetition:

```ts
import { createWebStoragePersistence, type SyncJourneyPersistence } from "@modular-react/journeys";

interface AppJourneyKey {
  readonly userId: string;
  readonly tenantId: string;
}

const sessionStorageOrNull: Storage | null =
  typeof window !== "undefined" && typeof window.sessionStorage !== "undefined"
    ? window.sessionStorage
    : null;

function makeJourneyPersistence<TInput extends AppJourneyKey, TState>(): SyncJourneyPersistence<
  TState,
  TInput
> {
  return createWebStoragePersistence<TInput, TState>({
    keyFor: ({ journeyId, input }) => `journey:${journeyId}:${input.tenantId}:${input.userId}`,
    storage: sessionStorageOrNull,
  });
}

registry.registerJourney(onboardingJourney, {
  persistence: makeJourneyPersistence<OnboardingInput, OnboardingState>(),
});
registry.registerJourney(checkoutJourney, {
  persistence: makeJourneyPersistence<CheckoutInput, CheckoutState>(),
});
```

Each factory call binds the calling journey's concrete `TInput`/`TState`, so the variance check passes without an `as` cast on either the definition or the adapter. The factory composes with `defineJourneyPersistence<TInput, TState>` for hand-rolled backends — same per-journey call shape, the helper just types `keyFor`/`load`/`save`/`remove` against the journey's types.

**Trap — one shared adapter typed `<unknown, TInput>`.** The shape that DRY instinct lands on if you're not careful: one `persistence` object reused across every `registerJourney` call, declared once with `TState` widened to `unknown` so it "fits everywhere". It doesn't. `JourneyDefinition.start(state: TState, ...)` puts `TState` in a contravariant position; the variance check rejects `unknown` against any concrete state. TypeScript infers `TState = unknown` from the `persistence` arg, then reports the mismatch against the journey-definition arg (the first arg) — not against `persistence` itself — surfacing as:

```
Argument of type 'JourneyDefinition<OnboardingState, AppJourneyKey>' is not assignable
to parameter of type 'JourneyDefinition<unknown, AppJourneyKey>'.
  Types of property 'start' are incompatible.
    ...
    Type 'unknown' is not assignable to type 'OnboardingState'.
```

Reach for one of the two safe shapes above instead — both are zero-cost at runtime.

```ts
import { createWebStoragePersistence, type SyncJourneyPersistence } from "@modular-react/journeys";

// One persistence to rule them all... or so you think.
export const sharedJourneyPersistence: SyncJourneyPersistence<unknown, AppJourneyKey> =
  createWebStoragePersistence<AppJourneyKey, unknown>({
    keyFor: ({ journeyId, input }) => `journey:${journeyId}:${input.tenantId}:${input.userId}`,
  });

// Both calls fail at the journey-definition arg (first arg), not at the declaration above:
// TS infers TState=unknown from `persistence`, then rejects the typed
// `JourneyDefinition<…, OnboardingState>` because its `start(state)` is contravariant in TState.
registry.registerJourney(onboardingJourney, {
  // Error reported on `onboardingJourney`: 'unknown' is not assignable to 'OnboardingState'.
  persistence: sharedJourneyPersistence,
});
registry.registerJourney(checkoutJourney, {
  // Error reported on `checkoutJourney`: 'unknown' is not assignable to 'CheckoutState'.
  persistence: sharedJourneyPersistence,
});
```

### Stock adapters: `createWebStoragePersistence` and `createMemoryPersistence`

Two factories ship with the package so common setups don't have to reimplement the same 20 lines of SSR guards and JSON handling. Both return values satisfying `JourneyPersistence<TState, TInput>` - pass them directly to `registerJourney({ persistence })`.

**`createWebStoragePersistence` - the 80% case (localStorage / sessionStorage).** Backed by the synchronous Web Storage API, SSR-safe, cleans up corrupt entries on read. Matches the sizing profile of most journey state (a few KB of JSON, per user, read-on-mount):

```ts
import { createWebStoragePersistence } from "@modular-react/journeys";

// Defaults to localStorage (or no-ops under SSR).
export const journeyPersistence = createWebStoragePersistence<OnboardingInput, OnboardingState>({
  keyFor: ({ journeyId, input }) => `journey:${input.customerId}:${journeyId}`,
});

registry.registerJourney(customerOnboardingJourney, { persistence: journeyPersistence });
```

Under the hood: `load` runs `JSON.parse` with a catch that calls `removeItem(key)` so a single bad write doesn't wedge future loads; `save` runs `JSON.stringify` and lets `QuotaExceededError` bubble so the app can surface it; all three methods no-op when `storage` resolves to `null`.

You can swap the backing store by passing a `storage` option:

```ts
// Tab-scoped - state dies with the tab.
createWebStoragePersistence<MyInput, MyState>({
  keyFor: ({ journeyId, input }) => `s:${input.id}:${journeyId}`,
  storage: typeof sessionStorage !== "undefined" ? sessionStorage : null,
});

// Lazy getter - re-evaluated per call. Useful when storage availability can
// flip after hydration (feature-detect then flip a flag).
createWebStoragePersistence<MyInput, MyState>({
  keyFor: ({ journeyId, input }) => `j:${input.id}:${journeyId}`,
  storage: () => (canUseStorage() ? localStorage : null),
});
```

Pick this adapter unless your state is large (>~1 MB per origin), you need offline-first guarantees, or **concurrent tabs writing the same key** is a correctness concern - the synchronous Web Storage API has no cross-tab write coordination, so the last `save` wins and can silently clobber a concurrent transition from another tab. For those cases, write a custom IndexedDB adapter against the same `JourneyPersistence` interface.

**`createMemoryPersistence` - for tests and SSR.** `Map`-backed, zero IO. The primary use case is tests: a fresh store per test avoids bleed between cases, and the runtime's persistence code paths stay exercised without `localStorage` mocks.

```ts
import { createMemoryPersistence } from "@modular-react/journeys";

const store = createMemoryPersistence<OnboardingInput, OnboardingState>({
  keyFor: ({ journeyId, input }) => `${journeyId}:${input.customerId}`,
});

// Pre-seed for a resume test - the runtime finds the blob on first start():
const seeded = createMemoryPersistence<OnboardingInput, OnboardingState>({
  keyFor: ({ journeyId, input }) => `${journeyId}:${input.customerId}`,
  initial: [["onboarding:C-1", existingBlob]],
});

// Test-only helpers (not on JourneyPersistence) - useful for assertions:
expect(store.size()).toBe(1);
expect(store.entries()).toMatchObject([...]);
store.clear();
```

Blobs are deep-cloned on both `save` and `load` by default so mutating the stored or returned object can't corrupt the other. Pass `clone: false` only in hot test loops where you've verified nobody mutates the blob.

Also valid as an SSR "persistence is configured but nothing survives the request" mode: no server state leaks into rendered HTML, and `start()` on the client re-probes from scratch. For an SSR shell that wants real client-side persistence, pick the adapter based on where the code runs - `createMemoryPersistence` on the server, `createWebStoragePersistence` on the client - so the server render produces no cross-request state and the client picks up from `localStorage` as normal.

Guarantees:

- **Idempotent `start`** - two `runtime.start(journeyId, input)` calls yielding the same `keyFor` return the same `instanceId`. Useful for reload recovery (same customer → same active journey). The key is namespaced internally by `journeyId`, so two journeys whose `keyFor` happens to return the same string can't alias onto the same instance.
- **Saves are serialized per instance** - at most one `save()` in flight; follow-up changes coalesce into a single pending save. Errors are logged but never block a transition.
- **Automatic cleanup of dead blobs** - when `start()` reads a terminal / corrupt / unmigrateable blob, the runtime calls `remove(key)` before minting a fresh instance. `remove` is also called when an active instance transitions to `completed` / `aborted`.
- **`remove` waits for in-flight `save`** - a terminal transition that fires while a `save()` is still in flight defers the `remove()` until the save settles, so adapters that don't serialize their own ops can't see a `save` land _after_ a `remove` and leave an orphaned blob.
- **Bulk terminal cleanup** - `runtime.forgetTerminal()` drops every terminal instance from memory in one call. Useful for long-running workspaces that accumulate finished journeys over a session.

### Key design - picking the right `keyFor`

`keyFor({ journeyId, input })` is the **only** identity contract the runtime has with your storage. Get it right and reload recovery is automatic; get it wrong and journeys alias onto each other's state.

Common shapes:

| Scope                              | `keyFor`                                                           | Effect                                                                                           |
| ---------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| One journey per customer           | `` `journey:${input.customerId}:${journeyId}` ``                   | Reload resumes. Opening the same customer's journey twice = same tab/instance.                   |
| One journey per session            | include a session id in `input` and the key                        | Each agent shift gets a fresh slate; different shifts don't collide.                             |
| One journey per (customer, matter) | `` `journey:${input.customerId}:${input.matterId}:${journeyId}` `` | Supports concurrent journeys for the same customer on distinct matters.                          |
| Strictly per start                 | include a `nonce` in `input` and the key                           | Never resumes; every `start()` is a new journey. Use when the semantic is "new flow every time". |

`keyFor` deliberately does **not** receive `instanceId` - probing happens before one exists, and mixing the two forms has historically produced subtle key mismatches.

The runtime namespaces keys internally by `journeyId`, so two **different** journeys whose `keyFor` happens to return the same string still resolve to distinct instances - a journey you register in a shared shell can't be aliased onto an unrelated journey's storage by accident. The adapter sees only the user-defined portion of the key; the internal namespace never reaches your storage calls.

### Sync vs async `load`

`load()` may return `SerializedJourney | null` synchronously **or** a `Promise<SerializedJourney | null>`. The runtime accommodates both:

- **Sync** (the onboarding example's localStorage adapter): the instance transitions straight from the initial state to `active` on the same tick. `<JourneyOutlet>`'s `loadingFallback` is never visible.
- **Async** (backend adapters): the instance is minted in `status: 'loading'` with state seeded from `initialState(input)` (so consumers never see `undefined` state), then either hydrated from the resolved blob or transitioned to a fresh start if the probe returns `null` / a terminal / a corrupt blob.

### Save queue

`save()` is serialized **per instance**:

- At most one `save()` in flight per instance.
- Concurrent state changes during a save coalesce into a single "next save" slot (later changes overwrite earlier pending saves).
- `remove()` on a terminal transition cancels any queued save.
- Errors are caught and logged; the instance stays in memory and continues accepting transitions.

This guarantees your backend never sees out-of-order writes for one journey, even with rapid clicks and slow IO.

### Explicit `runtime.hydrate` vs `runtime.start`

They serve different purposes:

| You want to…                                                       | Call                                                            |
| ------------------------------------------------------------------ | --------------------------------------------------------------- |
| Open / resume a live journey for a user, with persistence wiring.  | `runtime.start(id, input)`                                      |
| Render a **read-only** audit/replay view of a stored blob.         | `runtime.hydrate(id, blob)`                                     |
| Inspect a completed journey from an audit log without resuming it. | `runtime.hydrate(id, blob)` - terminal blobs are accepted here. |

`hydrate` is **persistence-unlinked**: the instance is created with no persistence key, so no save happens when its state changes (there's nothing for state to change into anyway on a terminal blob). If you genuinely want to resume a non-live blob, delete the storage record and let `start()` mint a fresh one.

`hydrate` of a terminal blob also **does not fire `onComplete` / `onAbort`** - those already fired on the original live run when the blob was produced, and firing them again on audit replay would double-count analytics. `onTransition` is silent for the same reason. If you need a signal that a terminal hydrate occurred, observe `runtime.getInstance(id).status` directly after the call returns.

### Versioning

Every serialized blob carries the journey's `version`. On hydrate:

- **Default (strict):** throw `JourneyHydrationError` if `blob.version !== definition.version`. The error message names "version mismatch".
- **With `onHydrate`:** the hook receives the loaded blob and returns the blob to use (possibly after migration). Throwing from `onHydrate` aborts the hydrate. The wrapped error names `onHydrate` (so callers can distinguish a migrator bug from a true version mismatch) and the original throw is preserved on `.cause` for logging / re-raising.

`runtime.start()` (the persistence-aware path) treats both failure modes the same: the stale blob is discarded via `persistence.remove(key)` and a fresh instance is minted under the same key. The distinction matters for `runtime.hydrate()`, where the caller is the one deciding what to do with the error.

Always supply `onHydrate` in production apps that ship new journey versions over time. A minimal pattern:

```ts
onHydrate: (blob) => {
  switch (blob.version) {
    case "1.0.0":
      return blob;
    case "0.9.0":
      return migrateFrom09(blob);
    default:
      throw new JourneyHydrationError(`unknown version ${blob.version}`);
  }
};
```

If migration would be destructive or the blob is no longer trusted, let `onHydrate` throw - the runtime discards the blob via `persistence.remove(key)` and mints a fresh instance under the same key. That's usually preferable to resuming into a malformed state.

### Stale steps (renamed or removed modules)

Versioning guards the _shape_ of a blob, but a blob can go stale in a subtler way: its saved **active step** can name a `(moduleId, entry)` that no longer exists - the module was renamed or removed, or the flow was relocated to a different module - while the blob's `version` still matches. Hydrating that step as-is would only render the outlet's "no entry on the registered modules" notice, with no path forward.

The runtime reconciles the (post-`onHydrate`) blob's active step against the registered modules and treats an unresolvable step exactly like a version mismatch:

- **`runtime.start()`** discards the blob via `persistence.remove(key)` and mints a fresh instance under the same key. This is the default - no `onHydrate` required. With `debug: true` the runtime logs a one-line warning naming the unresolved step so a clean restart doesn't read as silent data loss.
- **`runtime.hydrate()`** throws a `JourneyHydrationError` naming the offending step. It's persistence-unlinked, so it can't restart on its own - the caller decides whether to drop the instance or `start()` a fresh one.

Two caveats:

- The check is scoped to the **active step**. History entries (which drive `goBack`) are left untouched - discarding an otherwise-valid in-flight journey because a _past_ step was renamed is more disruptive than the stale back-button it would guard against.
- It only runs when the runtime was created with a module map; a module-less runtime has nothing to validate against and trusts the blob.

Restarting on a stale step is the right default for most apps - journeys are typically persisted for convenience, not as a source of truth. If you do need to preserve in-flight journeys across a rename, rewrite the step in `onHydrate` (it runs first, so a rewritten step that resolves is kept as-is).

### Rehydrating shell-level work (tabs, task queues, drafts)

Shells that persist user work outside the journey (tabs pointing at journey instances, a task queue, a draft list) need a rehydration pass on boot. The shape is inherently app-specific - every shell has a different "persisted work" concept - so the runtime doesn't ship a helper. Write the loop yourself, but discriminate failure modes:

```ts
import { UnknownJourneyError } from "@modular-react/journeys";

for (const tab of persistedTabs) {
  if (!journeys.isRegistered(tab.journeyId)) {
    // The journey was renamed or removed between deploys. Expected after
    // version skew; drop the tab cleanly.
    tabsStore.getState().removeTab(tab.tabId);
    continue;
  }
  try {
    const resolvedId = journeys.start(tab.journeyId, tab.input);
    if (resolvedId !== tab.instanceId) {
      tabsStore.getState().updateTab(tab.tabId, { instanceId: resolvedId });
    }
  } catch (err) {
    if (err instanceof UnknownJourneyError) {
      // Raced with a concurrent unregister; same policy as the pre-check.
      tabsStore.getState().removeTab(tab.tabId);
      continue;
    }
    // A real bug (corrupted input, throwing onHydrate, invariant violation).
    // Drop so the shell still boots, but warn loudly and surface it to the user.
    notifyUser(`We couldn't restore tab "${tab.title}"`, err);
    tabsStore.getState().removeTab(tab.tabId);
  }
}
```

Two things worth underlining:

- `runtime.isRegistered(id)` is a cheap pre-filter. It's not sufficient on its own (a tab might rehydrate fine past the id check and still fail on validation or a user `onHydrate` throw), but it keeps the expected-drop path out of the exception channel so real bugs stand out in logs.
- **Don't silently drop in production.** The example shells in this repo use `console.warn` only because they're examples. A real shell should surface the drop to the user - an in-app banner ("We couldn't restore N tab(s)"), an affordance to report the offending blob, or a quarantine store so support can replay it. Users lose trust fast when work vanishes without explanation.

## Rendering - `JourneyOutlet`

### Props

```ts
interface JourneyOutletProps {
  /** Runtime override - usually inherited from <JourneyProvider>. */
  runtime?: JourneyRuntime;
  /** The instance to render. Required. */
  instanceId: InstanceId;
  /** Module descriptors override - usually inherited from the runtime. */
  modules?: Readonly<Record<string, ModuleDescriptor<any, any, any, any>>>;
  /** Shown while status === 'loading'. */
  loadingFallback?: ReactNode;
  /** Fired once when the instance terminates. */
  onFinished?: (outcome: TerminalOutcome) => void;
  /** Error policy for the step's component. Default: 'abort'. */
  onStepError?: (err: unknown, ctx: { step: JourneyStep }) => "abort" | "retry" | "ignore";
  /** Global retry cap per instance (retries do NOT reset on step change). Default: 2. */
  retryLimit?: number;
  /**
   * Replaces the default red notice when the current step points at a
   * `(moduleId, entry)` pair the runtime doesn't resolve to a registered
   * module+entry. Shells almost always want to brand this.
   */
  notFoundComponent?: ComponentType<JourneyOutletNotFoundProps>;
  /**
   * Replaces the default red notice when a step component throws.
   * Receives the raw error so shells can route it through their own
   * error-reporting pipeline.
   */
  errorComponent?: ComponentType<JourneyOutletErrorProps>;
  /**
   * Speculatively prefetch chunks for entries reachable from the current
   * step during idle time after mount, so navigating Next finds the
   * bundle hot.
   *
   *   "precise" (default, alias `true`) — read declared `targets` from
   *     `defineTransition({ targets, handle })`-annotated handlers on
   *     the current step's transitions. Preload exactly those entries.
   *     Bare handlers contribute nothing.
   *   "aggressive" — preload every entry referenced anywhere in the
   *     journey's `transitions` map. Useful for unmigrated journeys.
   *   false — opt out entirely.
   *
   * No effect for eager (`component:`) entries — their import is
   * already resolved. SSR is a no-op (the preload effect is browser-only).
   */
  preload?: boolean | "precise" | "aggressive";
}

interface JourneyOutletNotFoundProps {
  readonly moduleId: string;
  readonly entry: string;
}

interface JourneyOutletErrorProps {
  readonly moduleId: string;
  readonly error: unknown;
}

interface TerminalOutcome {
  status: "completed" | "aborted";
  payload: unknown; // value passed to complete(…) or abort(…)
  instanceId: InstanceId;
  journeyId: string;
}
```

### Typical usage

With a `<JourneyProvider>` mounted above, `instanceId` is the only required prop:

```tsx
<JourneyOutlet
  instanceId={tab.instanceId}
  loadingFallback={<LoadingSpinner />}
  onFinished={(outcome) => {
    // outcome = { status, payload, instanceId, journeyId }
    workspace.closeTab(tab.tabId);
  }}
  onStepError={(err, { step }) => "abort" | "retry" | "ignore"}
  retryLimit={2}
/>
```

Without the provider (or when you want to point at a different runtime), pass `runtime` and optionally `modules` explicitly - they always win over context:

```tsx
<JourneyOutlet
  runtime={manifest.journeys}
  instanceId={tab.instanceId}
  modules={manifest.moduleDescriptors}
  // …
/>
```

What it does:

1. Subscribes to the instance via `useSyncExternalStore`.
2. Renders `loadingFallback` while the async persistence `load` is in flight.
3. Resolves `step.module` + `step.entry` against the module map (prop, or the one the runtime was built with) and renders its component with a freshly bound `{ input, exit, goBack? }`. Lazy entries are wrapped in `React.lazy` + `<Suspense fallback={entry.fallback ?? loadingFallback ?? null}>` automatically — see [Pattern - lazy entry-points](#pattern---lazy-entry-points-code-splitting-per-step).
4. Wraps the step in an error boundary and applies `onStepError` policy. Retries count against `retryLimit` globally per instance (the counter does **not** reset when a retry advances the step), so a throwing component can't bypass the cap by bumping the step token. Lazy import failures surface through this same boundary.
5. Fires `onFinished` exactly once when the instance terminates; the outcome carries `{ status, payload, instanceId, journeyId }` so analytics can correlate without re-reading props.
6. On unmount while still `active` **or** `loading`, abandons the instance via `runtime.end(id, { reason: 'unmounted' }, { force: true })`. The `force` guarantees the instance ends even if `onAbandon` returns a non-terminal `{ next }` — an unmounting outlet can't host a next step, so a plain `end()` would leave it stranded and active. Two defenses keep the instance alive when it should stay: StrictMode's simulated mount/unmount/remount cycle (same component, same `mountedRef`) and back-to-back independent outlets that hand off to each other (checked via `record.listeners.size`).
7. After each step mounts, schedules a `requestIdleCallback` (with a `setTimeout(_, 0)` fallback) to call `preload()` on every entry reachable from the current step (per `preload` mode — see the prop docs above). Effect cancels on step change so a fast advance doesn't race with the previous step's preload set.

### Error policies in depth

`onStepError` runs on every thrown error during a step's render or effects. Pick a policy per error:

| Policy     | Behavior                                                                                            |
| ---------- | --------------------------------------------------------------------------------------------------- |
| `'abort'`  | Default. The outlet calls `runtime.end(id, { reason: 'component-error', error })`.                  |
| `'retry'`  | Re-mount the step with a fresh React key. Counted against `retryLimit` per instance (not per step). |
| `'ignore'` | Keep the module error boundary UI in place until the user transitions away via another action.      |

The retry counter is deliberately per-instance: a step that throws, auto-retries, transitions, and the next step also throws cannot bypass the cap by resetting via a step-token bump. When you truly need per-step retries, increment `retryLimit` and live with the larger overall budget, or classify errors in `onStepError` and `'abort'` on everything except a specific retryable pattern.

### Outlet hosts - rules of thumb

- Render the outlet wherever the step should live - tab body, modal body, route element, panel, wizard card. It doesn't care.
- A tab that represents a journey should be the outlet's **only** long-lived mount. Unmounting = abandon. Don't swap an outlet for a placeholder and expect the journey to survive.
- For wizards that live inside a single always-mounted container (no tab changes), you can mount the outlet inside a `<details>` or a collapsed panel and the instance stays alive even when visually hidden.

## Hosting a journey - `JourneyHost`

`<JourneyOutlet>` renders a journey that is already running. Something still has to start it, and end it when the user leaves. `<JourneyHost>` is that something:

```tsx
<JourneyHost handle={checkoutHandle} input={{ cartId }} />
```

That is a complete, correct journey route. The host starts the journey on mount, renders its current step, and ends + forgets the instance on unmount.

### Props

`<JourneyHost>` accepts **every `<JourneyOutlet>` prop** and forwards it, so error and loading policy stay exactly where they were. On top of those:

```ts
interface JourneyHostProps<TInput> {
  handle: JourneyHandle<string, TInput, unknown>;
  input: TInput; // optional exactly when the handle's TInput is void
  runtime?: JourneyRuntime; // defaults to the <JourneyProvider>'s
  children?: (host: {
    instanceId: InstanceId;
    instance: JourneyInstance;
    stepIndex: number;
    outlet: ReactNode;
  }) => ReactNode;
}
```

`loadingFallback` covers the first render too, before the instance exists.

For chrome around the step, pass a render-prop child and place the ready-built `outlet`:

```tsx
<JourneyHost handle={checkoutHandle} input={{ cartId }} onFinished={goToReceipt}>
  {({ stepIndex, outlet }) => (
    <Layout title="Checkout" step={stepIndex}>
      {outlet}
    </Layout>
  )}
</JourneyHost>
```

`useJourneyHost(handle, input, options?)` is the same lifecycle without the rendering, for hosts that want to lay out the outlet themselves. It returns `{ instanceId, instance, runtime, stepIndex }`. The returned `runtime` is the one the host pinned at mount and the one `instanceId` is valid on — normally the same one a `<JourneyProvider>` would hand you, so a hand-placed outlet can keep resolving from context; it is there for the case where a shell swaps its provider value mid-flight, which the host deliberately does not follow.

### Behavior

- **The instance is fixed for the host's lifetime.** `handle`, `input` and `runtime` are read once, at mount. Changing them later does **not** restart the journey — silently abandoning a half-finished flow because a prop identity changed is never what the caller meant. To run a different journey — or the same journey with different `input`, or on a different runtime — remount by giving the host a `key` that encodes whatever identity should trigger the restart, e.g. `<JourneyHost key={`${journeyId}:${cartId}`} …>`. A key that tracks only part of it (say `journeyId`) will not remount when the rest changes. (An `instanceId` only means anything on the runtime that started it, so following a swapped runtime could only strand the host against one that has never heard of the instance.)
- **Start means resume, when persistence is configured.** `runtime.start()` with a `persistence` adapter returns the in-flight instance for the same `keyFor(input)` instead of minting a new one, so a host that remounts (route change, tab switch) picks the journey back up where it was. Without persistence, every mount starts a fresh instance. See [Keys, idempotency, and "resume vs new"](#keys-idempotency-and-resume-vs-new).
- **The journey starts from an effect, not during render.** `runtime.start()` mutates the runtime and may write to persistence, and a render React discards or replays would duplicate that. So `instanceId` is `null` for the first render and the host shows `loadingFallback` — this is also why `useState(() => runtime.start(…))`, the obvious hand-rolled version, is unsafe under StrictMode: its initializer runs twice and React keeps only one result. With deterministic persistence both calls converge on the same instance (the second `start` resumes the first), so the damage is bounded; but without idempotent persistence the discarded call leaks a live instance per mount. Starting from the effect sidesteps the question entirely.
- **Unmount ends _and_ forgets.** `runtime.end(id, { reason: "unmounted" }, { force: true })` then `runtime.forget(id)`, deferred one microtask so StrictMode's mount/unmount/mount cycle does not tear the journey down on its first visit. `<JourneyOutlet>` on its own only ends; forgetting is what stops terminal records accumulating in a long-lived shell. The `force` is what makes "ends" reliable: `onAbandon` may return a non-terminal `{ next }` (or `{ invoke }`), which on a plain `end()` would advance the flow to a step no host renders and leave the instance active — `forget()` would then no-op and the instance (and its persistence key) would leak. Forcing coerces that to an abort while still honouring a terminal `onAbandon` choice (complete/abort).
- **Nesting an outlet is fine.** The host renders one internally, and the two deferred teardowns are safe in either order — `end` no-ops on a terminal instance, and both force, so whichever runs first terminates and the other no-ops. That also means `onAbandon` runs once per unmount, not once per teardown.

### `stepIndex`, and the absence of `stepCount`

`stepIndex` is `history.length` — how many steps the user has completed, `0` on the first step. It rewinds when the journey does.

There is deliberately no `stepCount`. A journey's next step is computed by a transition handler from live state, so the total is not knowable from a running instance — and a hand-passed total is exactly the duplicated flow encoding that a progress API should be removing, not requiring. Deriving the sequence from the transition graph is a separate piece of work; until it lands, render "Step 3" rather than "Step 3 of 7", or pass your own total if your flow really is fixed-length.

## Deep-linking steps - `useJourneySync`

`useJourneySync` keeps a journey instance and the browser URL in step, in both directions: the journey advances and the URL follows; the user presses Back or Forward and the journey follows.

```tsx
function CheckoutRoute() {
  const { instanceId } = useJourneyHost(checkoutHandle, { cartId });
  useJourneySync(instanceId, port, { stepToPath: (step) => step.entry });
  return instanceId ? <JourneyOutlet instanceId={instanceId} /> : <Skeleton />;
}
```

The host owns the instance, the sync owns the URL, and neither knows about the other.

The reconciler itself is framework- and router-neutral — it lives in `@modular-frontend/journeys-engine` as `createJourneySync`, is shared with `@modular-vue/journeys`, and is tested without a DOM. This hook is the React lifetime wrapper.

### The port

The only router-aware code is a `JourneySyncPort`, which you write:

```ts
interface JourneySyncPort {
  read(): string; // the current location, in whatever space stepToPath produces
  push(path: string): void; // navigate, adding a history entry
  replace(path: string): void; // navigate, replacing the current entry
  go?(delta: number): void; // relative history navigation, if the router has it
  subscribe(listener: () => void): () => void;
}
```

Paths are **opaque strings** to the sync — it only compares them for equality. So the port owns every routing concern the sync should not know about: the base path, whether the step lives in a path segment or a search param, and any encoding.

TanStack Router:

```ts
const port = useMemo<JourneySyncPort>(
  () => ({
    read: () => router.state.location.pathname.replace(/^\/checkout\//, ""),
    push: (path) => router.navigate({ to: "/checkout/$step", params: { step: path } }),
    replace: (path) =>
      router.navigate({ to: "/checkout/$step", params: { step: path }, replace: true }),
    go: (delta) => router.history.go(delta),
    subscribe: (listener) => router.subscribe("onResolved", listener),
  }),
  [router],
);
```

React Router:

```ts
const navigate = useNavigate();

const port = useMemo<JourneySyncPort>(
  () => ({
    // Read the browser's own location, not React Router's `useLocation()`.
    // This port subscribes to `popstate`, and when that listener fires React
    // Router's state update can still be batched — a `useLocation()` value
    // (or a ref tracking it) can point at the *previous* path for the length
    // of the event. `window.location` is the source `popstate` reports on and
    // is always current inside the handler, so `read()` never sees a stale
    // path and miss a change. (Routers that expose their committed location
    // synchronously — TanStack's `router.state.location` — can read that
    // instead.)
    read: () => window.location.pathname.replace(/^\/checkout\//, ""),
    push: (path) => navigate(`/checkout/${path}`),
    replace: (path) => navigate(`/checkout/${path}`, { replace: true }),
    go: (delta) => navigate(delta),
    subscribe: (listener) => {
      window.addEventListener("popstate", listener);
      return () => window.removeEventListener("popstate", listener);
    },
  }),
  [navigate],
);
```

The port need not be memoized for correctness — the hook reads through to whatever you passed on the latest render, so an inline literal will not rebuild the reconciler. `onUnresolved` and `onBlocked` are read the same live way. Two things are read **once**, when the sync is created, and changing them later has no effect until it is re-created (change `instanceId` or remount): `port.subscribe` — the subscription belongs to the port current at that moment — and `stepToPath`, because the engine needs a stable step→path mapping to resolve the history frames the port has already stamped, and a mapping that changed mid-flight would strand previously visited paths as unresolved.

`createMemoryJourneySyncPort()` is an in-memory port over an array of entries — for tests, and for headless hosts that want journey history semantics without a browser.

### What a URL can and cannot select

This is the part worth reading before wiring it up.

A journey's step is derived from its state, and `JourneyStep` carries no identity — it is `{ moduleId, entry, input }` and nothing more. There is no `goToStep`, and there could not be one: landing on "review" requires the state the earlier steps produced. **So a URL cannot navigate a journey to an arbitrary step.** The only positions it can select are ones the journey has already been to (`history`) or just rewound from (`future`):

| The location names…                  | The sync…                                               |
| ------------------------------------ | ------------------------------------------------------- |
| the current step                     | does nothing                                            |
| a frame in `history`                 | `runtime.rewindTo(id, index)`                           |
| a frame in `future`                  | `runtime.goForward(id)`, as many times as it takes      |
| anything else                        | fires `onUnresolved` and **does not navigate**          |
| a frame the journey refuses to leave | re-asserts the current step's URL and fires `onBlocked` |

So `onUnresolved` is where a stale bookmark, or a click on a nav link out of the flow, lands. The sync deliberately does not force the URL back there — that would trap a user who navigated away on purpose. Decide for yourself: `runtime.end(…)` to abandon, or navigate to the journey's real step to bounce a stale link. It is **not** fired for the initial reconcile: at mount the URL has not been stamped with a step yet, and a host that ends the journey on this callback would otherwise kill the instance it just started. (A stale deep link is handled by the same rule — the journey starts at its real first step and the sync rewrites the URL to match.)

`onBlocked` fires when the frame is real but the runtime will not move to it: the transition did not opt in with `allowBack: true`, the entry declares `allowBack: false`, or a child journey is in flight. The sync re-asserts the current step — the standard "block the Back button" shape, where the URL snaps forward and the user stays put. When the port supplies `go`, it walks the browser forward by exactly the rejected distance, so a multi-entry jump that was refused (`c → a` through the history menu) leaves the whole `[a, b, c]` run intact rather than collapsing it. Without `go` it falls back to `push`, which is truthful but truncates the forward entries (the same cost the advance path documents below). Use the callback to explain why, not to navigate.

### Push, replace, and the forward stack

Push vs. replace follows the journey's own depth (`history.length`):

- **advancing** pushes an entry, so Back has somewhere to go;
- **rewinding from inside the journey** (a step's `goBack` prop, an in-app Back button) uses `port.go(-n)` so the browser's forward stack survives and Forward redoes the step;
- **a refused Back** (a location the journey will not rewind to) walks the browser forward by the rejected distance with `port.go(+n)` — the same amount it was asked to go back — restoring the stack exactly and leaving the intermediate entries addressable; without `go`, it `push`es the current step instead, which truncates whatever was ahead;
- **the first sync** replaces, since the host's own navigation already spent an entry getting here.

`go` is optional, and its absence changes the two `go`-based cases above, each to a different fallback. An **in-app rewind** falls back to `replace`: the URL stays truthful but the forward entry is dropped, so Forward will not redo the step. A **refused Back** falls back to `push`: the URL is corrected to the current step, but pushing from the earlier entry the browser is sitting on truncates whatever was ahead. Both keep the URL honest and both forfeit forward entries — only the mechanics differ. Supply `go` only when the journey owns a contiguous run of history entries; if your shell pushes unrelated entries mid-journey, `go(-n)` can land outside the flow (the sync reports that through `onUnresolved` rather than guessing, but the fallback would have been safer).

### Give steps distinct paths

`stepToPath` defaults to `` `${moduleId}/${entry}` `` and should be **pure, stable, and injective**. Two frames that map to the same string are indistinguishable to the sync: it resolves to the nearest occurrence to the current step, which is right for one Back press out of a loop and wrong for three. A path is all the browser hands back, so the sync cannot do better. If a journey revisits an entry with different meaning (an edit-then-review loop), fold the distinguishing bit into the path — `step.input` is available:

```ts
// `step.input` is `unknown`, so narrow (or cast) it before reading a field.
stepToPath: (step) =>
  step.entry === "review" ? `review/${(step.input as { itemId: string }).itemId}` : step.entry;
```

### Nested journeys

A sync tracks exactly the instance you give it — **it does not follow child journeys.** When that instance `invoke`s a child, the parent pauses on its invoking step and the child runs on its own instance; the sync keeps mirroring the parent's (paused) step, and a Back press against it resolves through `onBlocked` — "a child journey is in flight" is one of the refusal reasons above. It deliberately does not splice the child's `history`/`future` into the URL: a child's steps are its own URL space, and encoding two instances' histories in one path would make neither addressable. To deep-link inside a child, mount a second sync on the child instance (typically from the child's own host). A single path that encodes both levels is out of scope for this primitive.

### Terminal journeys

Once a journey completes or aborts, `step` is `null` and the sync **leaves the URL alone**. Where a finished journey sends the user is the host's call — wire it in `onFinished`.

## Hosting plain modules - `ModuleTab`

`<ModuleTab>` is the non-journey counterpart: it renders a single module entry outside a route, and forwards exits to a shell-provided callback (plus the provider-level `onModuleExit`).

### Props

```ts
interface ModuleTabProps<TInput = unknown> {
  module: ModuleDescriptor<any, any, any, any>;
  entry?: string; // defaults to the module's sole entry when unambiguous
  input?: TInput;
  tabId?: string; // opaque passthrough for the onExit callback
  onExit?: (event: {
    moduleId: string;
    entry: string;
    exit: string;
    output: unknown;
    tabId?: string;
  }) => void;
}
```

### Behavior

- If `entry` is omitted and the module has **one** entry, it's used automatically. If it has several, an error notice is rendered asking for the `entry` prop.
- `exit(name, output)` calls `onExit` first (for the per-tab override - typically "close this tab"), then the provider-level `onModuleExit` (for analytics / global telemetry).
- When a module predates entry points and only declares a legacy `component`, `<ModuleTab>` renders that - entry/exit contracts are strictly opt-in.

```tsx
function TabContent({ tab, moduleDescriptors, workspace }: Props) {
  if (tab.kind === "module") {
    return (
      <ModuleTab
        module={moduleDescriptors[tab.moduleId]}
        entry={tab.entry}
        input={tab.input}
        tabId={tab.tabId}
        onExit={(ev) => workspace.closeTab(tab.tabId)}
      />
    );
  }
  return (
    <JourneyOutlet instanceId={tab.instanceId} onFinished={() => workspace.closeTab(tab.tabId)} />
  );
}
```

## Observation hooks

```ts
defineJourney<…>()({
  onTransition: (ev)         => analytics.track('journey.step', ev),
  onAbandon:    ({ step })   => step?.moduleId === 'billing'
    ? { abort: { reason: 'payment-abandoned' } }
    : { abort: { reason: 'abandoned' } },
  onComplete:   (ctx, result)=> analytics.track('journey.complete', { ctx, result }),
  onAbort:      (ctx, reason)=> analytics.track('journey.abort', { ctx, reason }),
  onHydrate:    (blob)       => migrateIfNeeded(blob),
});
```

`onAbandon` is the only observation hook that returns a `TransitionResult` - the runtime uses it to decide the terminal state after `runtime.end(id, reason)`. Default: `{ abort: { reason: 'abandoned' } }`. The hook is also allowed to return `{ complete: … }` (rare, usually for "save a partial outcome on shutdown") or `{ next: … }` to reroute into another module entry instead of terminating - `runtime.end(id)` then keeps the journey alive on the rerouted step. Treat the reroute branch as an escape hatch: it can surprise callers that expect `end()` to be, well, an end. Exceptions from any hook are caught and logged; they never block the transition.

Registration options can supply an extra `onTransition` that fires after the definition's - handy when the shell wants host-level analytics without coupling it into the journey module.

Every `TransitionEvent` carries a `kind: "step" | "invoke" | "resume"` discriminator plus optional `child` / `outcome` / `resume` fields. Hooks that only care about top-level steps should filter on `kind === "step"`; consumers that want the full picture read the extra fields. See [Telemetry: `TransitionEvent.kind`](#telemetry-transitioneventkind) for the full breakdown. The registration-level `onError` carries a `phase: "step" | "invoke" | "resume" | "abandon"` discriminator on its `ctx` so a control-plane failure (a thrown resume, an unknown invoke handle) is distinguishable from a step-component throw.

## Testing

### Module-level - `renderModule({ entry, exit })`

No journey runtime involved; the `exit` callback is a test spy.

```ts
import { renderModule } from "@react-router-modules/testing"; // or @tanstack-react-modules/testing

const exit = vi.fn();
await renderModule(accountModule, {
  entry: "review",
  input: { customerId: "C-1" },
  exit,
  deps: {
    /* … */
  },
});
// assert UI, click buttons, assert exit was called with the right (name, output)
```

### Journey-level pure - `simulateJourney`

Headless. No React. Fires exits against the transition graph and exposes state / step / history / status plus a recorded `transitions` stream for assertions on analytics rules without wiring an `onTransition` by hand.

```ts
import { simulateJourney } from "@modular-react/journeys/testing";

const sim = simulateJourney(customerOnboardingJourney, { customerId: "C-1" });
// `currentStep` is `step` with a non-null assertion baked in: throws if the
// journey has terminated, so test assertions on the live path stay terse.
// Use `sim.step` (which is `JourneyStep | null`) when a null is expected.
expect(sim.currentStep.moduleId).toBe("profile");

sim.fireExit("profileComplete", {
  customerId: "C-1",
  hint: { suggestedTier: "pro", rationale: "12 seats" },
});
expect(sim.currentStep.moduleId).toBe("plan");
expect(sim.state.hint?.suggestedTier).toBe("pro");

sim.fireExit("choseStandard", { plan: { tier: "pro", monthly: 79 } });
expect(sim.currentStep.moduleId).toBe("billing");

// Initial start + two hops since the simulator started.
expect(sim.transitions).toHaveLength(3);
expect(sim.transitions.at(-1)!.to?.moduleId).toBe("billing");

// Once the journey terminates, `sim.terminalPayload` mirrors the value
// passed to `complete` / `abort`; `sim.serialize()` returns the exact blob
// shape a persistence adapter would see (useful for pinning round-trip
// invariants without reaching into runtime internals).
sim.fireExit("paid", { reference: "PAY-1", amount: 79 });
expect(sim.terminalPayload).toEqual({ kind: "paid", reference: "PAY-1", amount: 79 });
expect(sim.serialize().status).toBe("completed");
```

### Integration - `renderJourney`

Mounts `<JourneyOutlet>` inside a minimal registry.

```ts
import { renderJourney } from "@react-router-modules/testing";

const { getByText, runtime, instanceId } = renderJourney(customerOnboardingJourney, {
  modules: [profileModule, planModule, billingModule],
  input: { customerId: "C-1" },
  deps: {
    /* … */
  },
});
```

### Common assertion shapes

```ts
// A journey finishes with a specific payload
sim.fireExit("paid", { reference: "PAY-123", amount: 100 });
expect(sim.status).toBe("completed");
expect(sim.state.outcome).toEqual({ kind: "paid", reference: "PAY-123", amount: 100 });

// An abandon path
sim.end({ reason: "shift-ended" });
expect(sim.status).toBe("aborted");

// goBack restores state (allowBack: 'rollback')
sim.fireExit("choseStandard", { plan: PRO });
expect(sim.state.selectedPlan).toEqual(PRO);
sim.goBack();
expect(sim.state.selectedPlan).toBeNull();

// Analytics ordering
expect(sim.transitions.map((t) => t.exit)).toEqual(["profileComplete", "choseStandard", "paid"]);
```

### Testing persistence adapters

Drive the adapter with a fake storage map:

```ts
const store = new Map<string, string>();
const persistence = defineJourneyPersistence<MyInput, MyState>({
  keyFor: ({ journeyId, input }) => `journey:${input.customerId}:${journeyId}`,
  load: (k) => {
    const raw = store.get(k);
    return raw ? JSON.parse(raw) : null;
  },
  save: (k, b) => {
    store.set(k, JSON.stringify(b));
  },
  remove: (k) => {
    store.delete(k);
  },
});

// assert `store` entries after key transitions
```

For the full integration - including reload recovery - mount `renderJourney` with the adapter wired into registration, fire exits, then unmount + remount and check the state resumed.

## Integration patterns

Journeys are container-agnostic. Four common integration shapes:

### Pattern - tabbed workspace (recommended)

Shell maintains a list of open tabs. A tab either renders `<ModuleTab>` (plain module) or `<JourneyOutlet>` (journey). Closing a tab unmounts the outlet → abandons the journey. Completion fires `onFinished` → shell closes the tab.

```tsx
function TabContent({ tab }: { tab: Tab }) {
  if (tab.kind === "journey") {
    return (
      <JourneyOutlet
        instanceId={tab.instanceId}
        loadingFallback={<Spinner />}
        onFinished={() => workspace.closeTab(tab.tabId)}
      />
    );
  }
  return (
    <ModuleTab
      module={descriptors[tab.moduleId]}
      entry={tab.entry}
      input={tab.input}
      tabId={tab.tabId}
      onExit={() => workspace.closeTab(tab.tabId)}
    />
  );
}
```

See [`examples/react-router/customer-onboarding-journey/`](../../examples/react-router/customer-onboarding-journey/) and [`examples/tanstack-router/customer-onboarding-journey/`](../../examples/tanstack-router/customer-onboarding-journey/) for end-to-end implementations.

### Pattern - modal-hosted journey

For a one-shot flow that should block the rest of the UI (KYC top-up, mandatory re-auth):

```tsx
function JourneyModal({ journeyId, input, onClose }: Props) {
  const runtime = useJourneyContext()!.runtime;
  const [instanceId] = useState(() => runtime.start(journeyId, input));

  return (
    <Dialog open onClose={onClose}>
      <JourneyOutlet instanceId={instanceId} loadingFallback={<Spinner />} onFinished={onClose} />
    </Dialog>
  );
}
```

Dismissing the dialog unmounts the outlet → `onAbandon` fires. If you'd rather persist the journey across dismissals, keep the outlet mounted inside a hidden element and toggle dialog visibility only.

### Pattern - full-page route

Mount `<JourneyOutlet>` as a route element. The journey lives as long as the user stays on that route - a route change unmounts it and abandons the instance. Combine with `runtime.hydrate(blob)` to resume from a URL-bound audit blob.

```tsx
// react-router element:
<Route path="/onboarding/:customerId" element={<OnboardingPage />} />;

// OnboardingPage:
function OnboardingPage() {
  const { customerId } = useParams();
  const runtime = useJourneyContext()!.runtime;
  const [instanceId] = useState(() => runtime.start("customer-onboarding", { customerId }));
  return <JourneyOutlet instanceId={instanceId} onFinished={() => nav("/")} />;
}
```

### Pattern - embedded wizard panel

A journey driven inside an always-mounted panel (e.g. a side drawer). The outlet stays mounted even when the panel is collapsed - the instance survives toggle.

```tsx
<aside style={{ display: collapsed ? "none" : "block" }}>
  <JourneyOutlet instanceId={instanceId} />
</aside>
```

Only unmount the outlet when you truly want to abandon.

### Pattern - command-palette launcher

No extra React - the runtime is accessible anywhere via `useJourneyContext()` or a shell-level reference. Command handlers call `runtime.start(…)` and the shell's tab service mounts the outlet:

```ts
palette.register("onboarding:start", async ({ customerId }) => {
  workspace.openTab({ kind: "journey", id: "customer-onboarding", input: { customerId } });
});
```

## Embedding a journey in a composition zone

When a screen hosts several modules side-by-side and one of them is itself a multi-step journey, the `@modular-react/compositions` outlet can render the journey through a `RuntimeMountAdapter`. The journeys package ships a one-line factory that wraps a `JourneyRuntime` into the adapter shape compositions expect:

```ts
import { createJourneyMountAdapter } from "@modular-react/journeys";

// After `registry.resolve()`, before mounting React:
manifest.extensions.compositions.registerMountAdapter(
  "journey",
  createJourneyMountAdapter(manifest.extensions.journeys),
);
```

A composition zone whose selector returns `{ kind: "journey", handle, input }` will then resolve through the registered adapter — the composition outlet mints (or reuses a cached) journey instance and renders `<JourneyOutlet>` for it. The journey runs with its own state, history, and persistence; the composition's scoped store and the journey's state stay separate.

The adapter forwards `start` and `end` to the journey runtime: when the composition zone rolls over to a different journey resolution, the previously-cached journey instance is `runtime.end()`-ed via the adapter so it doesn't outlive its outlet.

Wiring is one-directional today — the compositions runtime consumes adapters; the journeys runtime does not (yet) register them. Embedding a composition inside a journey step is still done by mounting `<CompositionOutlet>` directly inside the step's component, not through this seam. See [`@modular-react/compositions`'s "Runtime mount adapters" section](../compositions/README.md#runtime-mount-adapters) for the host side.

## Debugging

The runtime enables dev-mode logs automatically when `process.env.NODE_ENV !== 'production'`. Signals to watch for:

| Message                                                                                                  | Meaning                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Stale exit("X") dropped on instance <id>`                                                               | A captured `exit` callback fired after the step advanced. Expected after double-clicks; suspicious if it floods the console.                              |
| `No transition for exit("X") on <module>.<entry>`                                                        | The component fired an exit the journey doesn't map. Usually a missing transition handler, or a refactor left a dead exit.                                |
| `Transition handler for <module>.<entry>."X" returned a Promise`                                         | A handler returned a thenable - illegal. The runtime aborts the journey. Move async into a loading entry.                                                 |
| `Journey "<id>" declares allowBack for <module>.<entry> but the runtime was created without the module…` | `createJourneyRuntime` was called without `modules` wired, so the back button can't be resolved. Use the registry-built runtime.                          |
| `onTransition / onAbandon / onComplete / onAbort threw`                                                  | Observation hook exception. Caught; the transition still commits. Fix the hook.                                                                           |
| `persistence.load / save / remove rejected / threw`                                                      | Storage error. Transitions continue in memory; the last good blob stays on disk.                                                                          |
| `hydrate after async load failed`                                                                        | Stored blob could not be hydrated (version mismatch without migrator, rollbackSnapshots length mismatch). The runtime discards the blob and starts fresh. |

To introspect a running journey by hand:

```ts
const runtime = manifest.journeys;
const ids = runtime.listInstances();
for (const id of ids) {
  const inst = runtime.getInstance(id);
  console.log(id, inst?.status, inst?.step, inst?.history.length);
}
```

For a fully-headless trace, drive a scenario through `simulateJourney` and inspect `sim.transitions`.

## Errors, races, and edge cases

- **Two exits in rapid succession** - step tokens guarantee the first wins; later calls are dropped.
- **Exit fired from an unmounted component** - same mechanism: token mismatch, drop.
- **Component throws during render or effect** - wrapped in an error boundary; `onStepError` decides (`'abort' | 'retry' | 'ignore'`). `'retry'` is capped by `retryLimit` (default 2) counted globally per instance; a throwing step that advances into another throwing step cannot reset the budget.
- **Async transition handler** - illegal. A handler that returns a `Promise` aborts the journey with `{ reason: 'transition-returned-promise' }` and logs an error in dev. Put async work inside a loading entry point on a module instead.
- **User closes the tab mid-journey** - `JourneyOutlet` unmounts → `runtime.end(id, { reason: 'unmounted' })` → `onAbandon` fires → instance becomes `aborted`. If the unmount happens while the instance is still in `loading` (persistence probe hasn't settled), the instance is transitioned straight to `aborted` without firing `onAbandon` - the journey never actually started.
- **Same journey, same persistence key, different input** - the persisted blob wins. The new input is discarded. Apps that want new inputs to reset should `runtime.end(oldId)` (and optionally clear the persistence key) first, or include a nonce in the key.
- **Terminal or corrupt persisted blob** - `start()` deletes it via `persistence.remove(key)` before minting a fresh instance, so stale blobs don't pile up in storage across reloads.
- **Hydrate blob whose `rollbackSnapshots` length disagrees with `history`** - rejected with `JourneyHydrationError`. Use `onHydrate` to migrate or pad the blob.
- **Duplicate `instanceId` on hydrate** - `runtime.hydrate()` throws if an instance with that id is already live. Call `forget(id)` first if the replace-in-place is intentional.
- **Circular transitions** - allowed; `history` grows. Long-running journeys should use `maxHistory` or be designed to terminate.
- **Circular invocations across journeys** - guarded. The four-layer safety net (static cycle check + runtime same-id, depth-cap, and resume-bounce-cap) aborts the offending parent with `invoke-cycle`, `invoke-stack-overflow`, `invoke-undeclared-child`, or `resume-bounce-limit` — see [Cycle and recursion safety](#cycle-and-recursion-safety) for tuning the caps and declaring the call set up-front.
- **Deep mutation of journey state corrupts rollback snapshots** - snapshots are **shallow clones**, so a mutation that reaches into nested objects updates the snapshot too. Treat state as immutable; produce new objects rather than mutating in place. In development the runtime shallow-freezes each captured snapshot, so a top-level mutation throws immediately - deep mutations still slip through.
- **Runtime input validation is not built in** - `schema<T>()` is type-only and gives you compile-time checking on entry inputs. The runtime does not validate at the boundary. If `start()` / `hydrate()` inputs come from untrusted sources (URL params, server payloads), wire `zod` / `valibot` / your validator of choice in front of them.
- **A module bumped past the journey's `moduleCompat` range** - `resolveManifest()` throws `JourneyValidationError` listing every mismatched (journey, module, range, registered version) tuple at once. The deployment refuses to come up; bump the journey's `moduleCompat`, downgrade the module, or fix the journey's transitions to match the module's new contract. See [Pattern - module compatibility (`moduleCompat`)](#pattern---module-compatibility-modulecompat).

## Limitations

Things that aren't implemented today but may land later - these are gaps, not architectural choices.

- **No URL reflection of journey state.** Journeys are route-agnostic by design. Deep-linking into a mid-journey step is currently an app-level concern (read URL → `runtime.hydrate` → mount outlet).

Cross-references for things that are sometimes mistaken for limitations:

- _"Transitions can't be async."_ True, by design - see [Transition handlers are pure and synchronous](#transition-handlers-are-pure-and-synchronous).
- _"Exits are module-level, not per-entry."_ Same - see [Entry points and exit points on a module](#entry-points-and-exit-points-on-a-module).
- _"`history` grows unbounded by default."_ Configurable - see [Pattern - bounded history (`maxHistory`)](#pattern--bounded-history-maxhistory) and the rollback-snapshot caveat there.
- _"State mutation can corrupt rollback snapshots."_ Treat state as immutable - see the snapshot bullet in [Errors, races, and edge cases](#errors-races-and-edge-cases).
- _"There's no runtime input validation."_ `schema<T>()` is type-only - see the validation bullet in [Errors, races, and edge cases](#errors-races-and-edge-cases).

## TypeScript inference notes

The journey type surface is designed so a handful of explicit generics produce end-to-end checking across modules, journey, and persistence. A few things to know:

### `defineJourney` is curried

```ts
export const journey = defineJourney<MyModules, MyState>()({
  initialState: (input: { customerId: string }) => ({
    /* … */
  }),
  // ^^^^^ TInput is inferred from `initialState`'s parameter
});

// Add TOutput as the third generic to narrow `complete` payloads (and the
// type a parent's resume sees on `outcome.payload` when this journey is
// invoked):
export const childJourney = defineJourney<ChildModules, ChildState, { token: string }>()({
  /* …complete: { token: ... } is type-checked against { token: string } */
});
```

`TModules` and `TState` are supplied explicitly; the optional third generic `TOutput` narrows the journey's terminal payload (defaults to `unknown`); `TInput` is inferred from `initialState` so you don't repeat the shape. If you ever need to constrain `TInput` explicitly (e.g. for a shared starter-input type), annotate the `initialState` parameter.

### The module type map is per-journey, not global

```ts
type OnboardingModules = {
  readonly profile: typeof profileModule;
  readonly plan: typeof planModule;
  readonly billing: typeof billingModule;
};
```

All imports are `import type` - modules are **not** pulled into the journey's bundle. Don't hoist a shared `AppModules` across every journey in the app: unrelated journeys pay each other's type-check cost and churn together on unrelated changes.

### `StepSpec` is a discriminated union

`StepSpec<TModules>` expands to `{ module: 'profile'; entry: 'review'; input: {…} } | { module: 'plan'; entry: 'choose'; input: {…} } | …`. Every transition result that returns `{ next: … }` narrows the `input` type against the target entry. You cannot type-check your way into passing a wrong-shaped input - but only if the modules in the type map expose narrow `entryPoints` / `exitPoints` literals (i.e. the module descriptor was typed via `const` + `as const` or via `defineModule` called without shell-level generics - the canonical authoring pattern in [Authoring patterns](#authoring-patterns)).

`JourneyStepFor<TModules>` is the snapshot counterpart — same per-entry input narrowing, but keyed by `moduleId` / `entry` (matching the persisted `JourneyStep` shape) instead of `module` / `entry`. The simulator's `step` / `currentStep` / `history` use this typed form, so tests can assert on `step.input` without a `Record<string, unknown>` cast. The runtime itself stores history as the wide `JourneyStep<unknown>`; the narrow union surfaces at the simulator / harness boundary.

### `schema<T>()` is a type brand, not a validator

```ts
input: schema<{ customerId: string }>();
```

Returns an empty object whose type carries `T`. Zero runtime cost and zero validation. For runtime validation, wire zod/valibot inside the component (or at the `workspace.openTab` boundary) until `validateInput` lands in core.

### `defineJourneyPersistence<TInput, TState>` ties the adapter to the journey

```ts
const persistence = defineJourneyPersistence<OnboardingInput, OnboardingState>({
  keyFor: ({ input }) => `journey:${input.customerId}:onboarding`, // input typed as OnboardingInput
  save: (k, b) => api.save(k, b), // b typed as SerializedJourney<OnboardingState>
  load: (k) => api.load(k),
  remove: (k) => api.remove(k),
});
```

Without the helper, `input` on `keyFor` is `unknown`; with it, every callback is end-to-end typed.

## API reference

Every export you're likely to call, grouped by role.

### From `@modular-react/core` (module authors)

| Export                                           | Signature                                                                                                                   | Purpose                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defineEntry`                                    | overloaded — `<T>(e: EagerModuleEntryPoint<T> \| LazyModuleEntryPoint<T>) => same`                                          | Identity helper. Two forms: eager (`{ component, input?, allowBack?, buildInput? }`) or lazy (`{ lazy: () => import(…), fallback?, input?, allowBack?, buildInput? }`). Mutually exclusive at the type level.                                                                                                                                                                                            |
| `buildInputFor`                                  | `<TState>() => <TInput>(fn: (state: TState) => TInput) => (state: unknown) => TInput`                                       | Curried typed wrapper for `defineEntry({ buildInput })`. Bakes the host journey's `TState` into the factory's `state` parameter, returning the `(state: unknown) => TInput` shape the entry expects. Alternative to inline `(state: TState) =>` annotations — pick this one if `strictFunctionTypes` flags the inline pattern. See [Pattern - `buildInput`](#pattern---buildinput-for-re-entered-forms). |
| `defineExit`                                     | `<T = void>() => ExitPointSchema<T>`                                                                                        | Identity helper for an exit-point literal. Zero runtime cost.                                                                                                                                                                                                                                                                                                                                            |
| `defineExitContract`                             | overloaded — `<T>(kind) => ExitContract<T>` or `<S extends StandardSchemaV1>(kind, schema) => ExitContract<InferOutput<S>>` | Shared exit contract identity. Use the same returned value as the schema for an exit on every module that emits it - the journey's wildcard transitions then narrow `output` to the contract's `T` and (when a schema is provided) the runtime validates payloads at every emit. See [Pattern - shared exit contracts](#pattern---shared-exit-contracts-defineexitcontract).                             |
| `isExitContract`                                 | `(schema: unknown) => schema is ExitContract<unknown>`                                                                      | Type predicate distinguishing a contract from a plain `ExitPointSchema`. Used by the journey runtime and validators; exported for custom hosts.                                                                                                                                                                                                                                                          |
| `ExitContract`                                   | `{ kind: string; schema?: StandardSchemaV1; output? }`                                                                      | Shape of a shared contract. Extends `ExitPointSchema`; carries an identity (`kind`) and an optional Standard Schema for runtime validation.                                                                                                                                                                                                                                                              |
| `schema`                                         | `<T>() => InputSchema<T>`                                                                                                   | Type-only brand used to carry an input/output shape. Zero runtime cost.                                                                                                                                                                                                                                                                                                                                  |
| `ModuleEntryProps`                               | `<TInput, TExits extends ExitPointMap = {}>`                                                                                | Typed props for an entry component: `{ input, exit, goBack? }`.                                                                                                                                                                                                                                                                                                                                          |
| `ModuleEntryPoint`                               | `EagerModuleEntryPoint<T> \| LazyModuleEntryPoint<T>`                                                                       | Discriminated union — eager (`component`) or lazy (`lazy`).                                                                                                                                                                                                                                                                                                                                              |
| `EagerModuleEntryPoint` / `LazyModuleEntryPoint` | `{ component, input?, allowBack?, lazy?: never }` / `{ lazy, fallback?, input?, allowBack?, component?: never }`            | The two branches of the union, exported for callers that want to type a single variant explicitly.                                                                                                                                                                                                                                                                                                       |
| `LazyEntryComponent`                             | `() => Promise<{ default: ComponentType<…> } \| ComponentType<…>>`                                                          | Importer signature accepted by `defineEntry({ lazy })`. Both default-export and direct-export module shapes are normalized at runtime.                                                                                                                                                                                                                                                                   |
| `ExitPointSchema`                                | `{ output? }`                                                                                                               | Exit-point descriptor shape.                                                                                                                                                                                                                                                                                                                                                                             |
| `ExitFn`                                         | `<TExits>(name, output?) => void`                                                                                           | The function signature `exit` gets on an entry component.                                                                                                                                                                                                                                                                                                                                                |
| `EntryPointMap` / `ExitPointMap`                 | `Record<string, ModuleEntryPoint<any>>` / `Record<string, ExitPointSchema<any>>`                                            | Map shapes on `ModuleDescriptor`.                                                                                                                                                                                                                                                                                                                                                                        |

### Authoring (`@modular-react/journeys`)

| Export                        | Signature                                                                                                                                  | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `defineJourney`               | `<TModules, TState, TOutput?>() => <TInput>(def: JourneyDefinition<TModules, TState, TInput, TOutput>) => def`                             | Identity helper with full inference on transitions and state. Curried so `TInput` infers from `initialState`. The optional third generic `TOutput` narrows `complete` payloads (and a parent's resume `outcome.payload` when invoked).                                                                                                                                                                                                                                                                                                            |
| `defineJourneyHandle`         | `<TModules, TState, TInput, TOutput>(def) => JourneyHandle<string, TInput, TOutput>`                                                       | Builds a typed token from a journey definition so modules and shells can call `runtime.start(handle, input)` without importing the journey's runtime code. Carries `TOutput` so a parent's resume sees `outcome.payload` typed end-to-end.                                                                                                                                                                                                                                                                                                        |
| `invoke`                      | `<TInput, TOutput>({ handle, input, resume }) => { invoke: InvokeSpec<TInput, TOutput> }`                                                  | Typed builder for the `{ invoke }` arm of `TransitionResult`. Cross-checks `input` against the handle's `TInput` — a bare object literal won't. See [Composing journeys](#composing-journeys-invoke--resume).                                                                                                                                                                                                                                                                                                                                     |
| `validateJourneyGraph`        | `(journeys: readonly RegisteredJourney[]) => void`                                                                                         | Static cycle check over the directed graph derived from each journey's `invokes` field. Run automatically by `validateJourneyContracts`; exported separately for shells that compose registrations across plugin boundaries. See [Cycle and recursion safety](#cycle-and-recursion-safety).                                                                                                                                                                                                                                                       |
| `isJourneySystemAbort`        | `(payload: unknown) => payload is JourneySystemAbortReason`                                                                                | Type guard that narrows an `unknown` abort payload to the runtime's discriminated `JourneySystemAbortReason` union. Returns `false` for author-supplied aborts so a `{ abort: { reason: "user-cancelled" } }` does not collide with the system codes. See [Cycle and recursion safety - Failure surface](#cycle-and-recursion-safety).                                                                                                                                                                                                            |
| `selectModule`                | `<TModules>() => <TKey>(key, cases) => StepSpec<TModules>`                                                                                 | Exhaustive state-driven dispatch helper for transition handlers - see [the pattern](#pattern---exhaustive-state-driven-module-dispatch-selectmodule). Missing branches are a compile error.                                                                                                                                                                                                                                                                                                                                                       |
| `selectModuleOrDefault`       | `<TModules>() => <TKey>(key, cases, fallback) => StepSpec<TModules>`                                                                       | Sibling of `selectModule` accepting a partial cases map plus an explicit fallback `StepSpec` - see [the pattern](#pattern---fallback-dispatch-selectmoduleordefault). Use when most discriminator values funnel through a generic module.                                                                                                                                                                                                                                                                                                         |
| `defineTransition`            | curried: `<TModules, TState?, TOutput?>() => (spec) => handle & { targets }`<br>bare: `<THandler, TTargets>(spec) => handle & { targets }` | Wraps a transition handler with declared `targets` — a mixed array of `{ module, entry }` step refs and `"complete"` / `"abort"` / `"invoke"` sentinels. Required on every wrapped handler; narrows the handler's return to the declared arms (returning an undeclared arm is a compile error). The outlet's default `preload="precise"` mode reads the step refs to warm chunks during idle time; sentinels are skipped. See [Pattern - declared targets](#pattern---declared-targets-with-definetransition-auto-preload--narrowed-return-type). |
| `isTerminalSentinel`          | `(value: unknown) => value is "complete" \| "abort" \| "invoke"`                                                                           | Type guard for the terminal sentinels accepted in `targets`. Exposed for hosts that introspect a wrapped handler's targets and want to separate step refs from terminal arms.                                                                                                                                                                                                                                                                                                                                                                     |
| `isAnnotatedTransition`       | `(value: unknown) => boolean`                                                                                                              | Type guard for `defineTransition`-wrapped handlers. The outlet's preloader uses it; exported for custom hosts that walk a journey's `transitions` map.                                                                                                                                                                                                                                                                                                                                                                                            |
| `defineJourneyPersistence`    | `<TInput, TState>(adapter) => JourneyPersistence<TState, TInput>`                                                                          | Types `keyFor`'s `input` against `TInput`, `load`/`save` against `TState`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `createWebStoragePersistence` | `<TInput, TState>({ keyFor, storage? }) => JourneyPersistence<TState, TInput>`                                                             | Stock `localStorage` / `sessionStorage` adapter. SSR-safe, auto-clears corrupt JSON entries. Pass `storage` to override the backing store.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `createMemoryPersistence`     | `<TInput, TState>({ keyFor, initial?, clone? }) => MemoryPersistence<TInput, TState>`                                                      | `Map`-backed adapter for tests/SSR. Exposes `size()` / `entries()` / `clear()`. Deep-clones on `save` and `load` by default.                                                                                                                                                                                                                                                                                                                                                                                                                      |

### Rendering + context (`@modular-react/journeys`)

| Export                         | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JourneyProvider`              | Context provider for the runtime and optional `onModuleExit`. Mount once at the shell root.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `useJourneyContext`            | Reads the current provider value, or `null`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `JourneyOutlet`                | Renders the current step of a journey instance. Handles loading, error boundary, terminal, and abandon-on-unmount. By default walks the active call chain and renders the leaf — pass `leafOnly={false}` for layered presentations.                                                                                                                                                                                                                                                                                             |
| `useJourneyCallStack`          | `(runtime, rootId) => readonly InstanceId[]` — returns the live root → … → leaf chain. Subscribes to every link so the array re-resolves when the chain shifts.                                                                                                                                                                                                                                                                                                                                                                 |
| `JourneyHost`                  | `<JourneyHost handle={h} input={i} />` — starts the journey on mount, renders its step, ends + forgets the instance on unmount. Accepts and forwards every `JourneyOutlet` prop; pass a render-prop child to place the ready-built `outlet` inside your own chrome. The instance is fixed for the host's lifetime (remount with a `key` to switch journeys). See [Hosting a journey](#hosting-a-journey---journeyhost).                                                                                                         |
| `useJourneyHost`               | `<TInput>(handle, input, options?) => { instanceId, instance, runtime, stepIndex }` — the lifecycle half of `JourneyHost` without the rendering. `instanceId` is `null` for the first render: the journey is started from an effect, since starting during render would duplicate instances on a render React discards. `runtime` is the one the host pinned at mount and the one `instanceId` is valid on. `stepIndex` is `history.length`; there is deliberately no `stepCount` (it is not knowable from a running instance). |
| `useJourneySync`               | `(id: InstanceId \| null, port: JourneySyncPort, options?) => void` — keeps a journey and the URL in step both ways: the journey advances and the URL follows; Back/Forward drive `rewindTo`/`goForward`. Wraps the neutral `createJourneySync`. Tolerates a `null` id, and reads the port and callbacks through refs so inline literals don't rebuild (and re-navigate) the reconciler. See [Deep-linking steps](#deep-linking-steps---usejourneysync).                                                                        |
| `useJourneyInstance`           | `(id: InstanceId \| null) => JourneyInstance \| null` — subscribes to a single instance via `useSyncExternalStore` and returns its full snapshot (`status`, `step`, `state`, `terminalPayload`, …). Reads the runtime from `<JourneyProvider>`; returns `null` for unknown ids or no provider. Tearing-free under concurrent React. Prefer this when a host needs more than `state`.                                                                                                                                            |
| `useJourneyState`              | `<TState>(id: InstanceId \| null) => TState \| null` — sugar over `useJourneyInstance(id)?.state`. Use when the caller only needs `state` and the journey's `TState` is known at the call site.                                                                                                                                                                                                                                                                                                                                 |
| `useActiveLeafJourneyInstance` | `(rootId: InstanceId \| null) => JourneyInstance \| null` — **the recommended primitive when the host doesn't know the leaf's depth.** Walks `activeChildId` from the root to the active leaf and returns the leaf's full `JourneyInstance`. `inst.journeyId` is a natural discriminator when the leaf may be the root parent OR any invoked descendant. Re-subscribes as the chain grows / shrinks.                                                                                                                            |
| `useActiveLeafJourneyState`    | `<TState>(rootId: InstanceId \| null) => TState \| null` — sugar over `useActiveLeafJourneyInstance(rootId)?.state`. Returns a single `T`, so callers whose leaf can be any of several journeys must type it as `<ParentState \| ChildState>` and discriminate manually — usually that's a sign the caller actually wants `useActiveLeafJourneyInstance` and `inst.journeyId` to switch on.                                                                                                                                     |
| `useWaitForExit`               | `<TExits>(exit, channels) => void` — for step components that wait on an async backend event. Composes a push `subscribe` channel, a `poll` channel, and a `timeout` arm with first-wins-latched dispatch and unmount cleanup. Channel-callback identities are ref'd internally, so callback churn between renders doesn't restart the wait; scalar shape changes (`poll.intervalMs`, `timeout.ms`, named timeout exit) do. See [Pattern - event-driven wait with timeout](#pattern---event-driven-wait-with-timeout).          |
| `ModuleTab`                    | Renders a single module entry outside a route. Non-journey counterpart to `JourneyOutlet`.                                                                                                                                                                                                                                                                                                                                                                                                                                      |

### Runtime + validation (`@modular-react/journeys`)

| Export                        | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `createJourneyRuntime`        | Low-level runtime factory. Normally called by the registry; exported for advanced use (test harnesses, custom hosts).                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `validateJourneyContracts`    | Cross-checks a journey's transitions and `moduleCompat` against registered modules. Runs automatically at `resolveManifest()` / `resolve()`; exported for custom validation flows.                                                                                                                                                                                                                                                                                                                                                     |
| `validateJourneyDefinition`   | Structural sanity check on a definition's own shape. Runs automatically in `registerJourney`.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `satisfies(version, range)`   | Re-exported from `@modular-react/core` for back-compat. Tests a `MAJOR.MINOR.PATCH` version against the npm-semver subset used by `moduleCompat`. Exported for apps that want to run the same compatibility math outside the journeys validator (e.g. checking a saved blob's recorded version against a current journey's compat range). See [Pattern - module compatibility (`moduleCompat`)](#pattern---module-compatibility-modulecompat) for the supported syntax. New callers should import from `@modular-react/core` directly. |
| `compareVersions(a, b)`       | Re-exported from `@modular-react/core`. Order two version strings lexicographically by `(major, minor, patch)`. Returns `-1` / `0` / `1`. Useful for "is this saved blob older than the cutoff?" comparisons; for matching against a range use `satisfies`.                                                                                                                                                                                                                                                                            |
| `SemverParseError`            | Re-exported from `@modular-react/core`. Thrown by `satisfies` / `compareVersions` on malformed input.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `createJourneySync`           | `(runtime, id, port, options?) => { sync, stop }` — the framework- and router-neutral journey ↔ location reconciler behind `useJourneySync`, re-exported from `@modular-frontend/journeys-engine` and shared with `@modular-vue/journeys`. Reach for it directly only outside React (a headless host, a custom lifetime); in a component, prefer the hook.                                                                                                                                                                             |
| `resolveJourneySyncAction`    | `(instance, path, stepToPath?) => JourneySyncAction` — the pure decision table the reconciler acts on: does this location mean `none`, `rewind` at an index, `forward` by N, or `unresolved`? No runtime calls, no navigation. Exported so hosts can pre-compute what a link would do (e.g. to disable a breadcrumb the journey would refuse).                                                                                                                                                                                         |
| `journeyStepPath`             | `(instance, stepToPath?) => string \| null` — the location an instance's current step should be at, or `null` when there is no step to represent (`loading`, or terminal). `null` means "leave the URL alone", not "clear it".                                                                                                                                                                                                                                                                                                         |
| `defaultStepPath`             | `(step) => "moduleId/entry"` — the default `stepToPath`. Injective for journeys that visit each entry at most once per run.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `stepPathFromDefinition`      | `(definition, fallback?) => stepToPath` — builds a `stepToPath` from a journey's per-step `steps[module][entry].path` metadata, so a declared `JourneyStepMeta.path` drives the URL. Steps without a `path` fall through to `fallback` (default `defaultStepPath`). Pass the result as the sync's `stepToPath` to opt in.                                                                                                                                                                                                              |
| `createMemoryJourneySyncPort` | In-memory `JourneySyncPort` over an array of entries, modelling a browser stack (`push` truncates the forward entries, `go` clamps). For tests, and for headless hosts that want journey history semantics without a browser.                                                                                                                                                                                                                                                                                                          |
| `JourneyValidationError`      | Aggregated validation error. `.issues: readonly string[]`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `JourneyHydrationError`       | Thrown from `hydrate` / async-load when the blob is unusable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `UnknownJourneyError`         | Thrown from `runtime.start(journeyId, input)` when `journeyId` is not registered. Catch this specifically in shell-state rehydration loops (see [Rehydrating shell-level work](#rehydrating-shell-level-work-tabs-task-queues-drafts)); surface anything else as a real bug.                                                                                                                                                                                                                                                           |

### Runtime methods (the `JourneyRuntime` returned as `manifest.journeys`)

| Method                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start(handle, input)`                  | **Preferred.** Start or resume an instance via a handle (`defineJourneyHandle`); `input` is type-checked end-to-end. Idempotent per persistence key.                                                                                                                                                                                                                                                                                                                                               |
| `start(journeyId, input)`               | String-id form for dynamic dispatch (e.g. navbar `{ kind: "journey-start", journeyId }`). Accepts any `input`.                                                                                                                                                                                                                                                                                                                                                                                     |
| `hydrate(journeyId, blob)`              | Explicit read-only hydrate. Persistence-unlinked. Returns `InstanceId`.                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `getInstance(id)`                       | Current snapshot of an instance, or `null`. Stable-identity between changes (for `useSyncExternalStore`).                                                                                                                                                                                                                                                                                                                                                                                          |
| `listInstances()` / `listDefinitions()` | Enumerate. Useful for admin tooling.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `isRegistered(journeyId)`               | Cheap "is this id known?" predicate. Use to filter persisted shell state before calling `start()` - keeps the expected-drop path out of the exception channel.                                                                                                                                                                                                                                                                                                                                     |
| `subscribe(id, listener)`               | Subscribe to change notifications for one instance. Returns unsubscribe.                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `goBack(id)`                            | Pop the active step back to the previous one. Equivalent to the `goBack` prop on `ModuleEntryProps`, but addressable by id so a shell wiring browser-Back / `popstate` / breadcrumb navigation doesn't have to capture the step component's closure through a context. No-op when the id is unknown, the instance is terminal / loading, a child is in flight, the transition didn't opt into `allowBack: true`, the registered module entry declares `allowBack: false`, or history is empty.     |
| `goForward(id)`                         | Inverse of `goBack` — re-applies the most recent rewind by restoring the captured post-transition state + step. No-op when the id is unknown, terminal / loading, a child is in flight, or the future stack is empty. Does NOT re-run transition handlers; the captured state wins.                                                                                                                                                                                                                |
| `rewindTo(id, historyIndex)`            | Transactional multi-step `goBack` — rewinds to the frame at `JourneyInstance.history[historyIndex]` in one call. Atomic: if any intermediate frame would fail the back opt-in, the whole call is a no-op. After success the future stack is shape-identical to one built by N successive `goBack` calls, so `goForward` continues to redo one step at a time. Designed for shell-owned breadcrumb navigation — see [Breadcrumb / edit-and-revisit wizards](#breadcrumb--edit-and-revisit-wizards). |
| `canRewindTo(id, historyIndex)`         | Predicate companion to `rewindTo`. Returns `true` iff calling `rewindTo(id, historyIndex)` right now would actually move the step. Gates breadcrumb affordances without duplicating the back-opt-in walk.                                                                                                                                                                                                                                                                                          |
| `canGoBack(id)` / `canGoForward(id)`    | Read-only predicates that mirror the guards in `goBack` / `goForward` — returns `true` iff the corresponding call would actually move. Lets a shell-owned Back / Forward toolbar gate enable-state authoritatively without duplicating the runtime's transition/entry opt-in logic.                                                                                                                                                                                                                |
| `end(id, reason?)`                      | Force-terminate. Fires `onAbandon` if active; treats `loading` as a direct abort without firing `onAbandon`.                                                                                                                                                                                                                                                                                                                                                                                       |
| `forget(id)` / `forgetTerminal()`       | Drop terminal instances from memory. `forget` is a no-op on active/loading; `forgetTerminal` batches them all.                                                                                                                                                                                                                                                                                                                                                                                     |

### Registration options (passed to `registry.registerJourney`)

```ts
interface JourneyRegisterOptions<TState = unknown, TInput = unknown> {
  /**
   * Fires after every transition, in addition to the definition's
   * `onTransition`. Useful for shell telemetry that doesn't belong in
   * journey authoring code.
   */
  onTransition?: (ev: TransitionEvent) => void;
  /**
   * Fires when the journey reaches `{ complete }`. Runs after the
   * definition-level `onComplete` (both fire). Shell-level completion
   * analytics belong here.
   */
  onComplete?: (ctx: TerminalCtx<TState>, result: unknown) => void;
  /**
   * Fires on abort (via `{ abort }` transition, a thrown handler, or
   * `runtime.end(id)`). Runs after the definition-level `onAbort`.
   */
  onAbort?: (ctx: TerminalCtx<TState>, reason: unknown) => void;
  /**
   * Overrides the definition's `onAbandon` when `runtime.end(id)` is
   * called on an active instance. Use to swap abandon behaviour for a
   * specific deployment (e.g. "save as completed on end-of-shift" vs
   * the journey author's default "abort").
   */
  onAbandon?: (ctx: AbandonCtx) => TransitionResult;
  /**
   * Layered on top of the definition-level `onHydrate` - runs **after**
   * the definition transforms the blob. Useful for shell-level migrations
   * the journey author doesn't know about (redacting env-specific ids on
   * load, etc.).
   */
  onHydrate?: (blob: SerializedJourney<TState>) => SerializedJourney<TState>;
  /**
   * Observation-only error hook. Fires whenever a step component throws,
   * a transition handler throws, an invoke fails validation (unknown
   * journey id, unknown resume name, `runtime.start` itself threw), a
   * resume handler throws, or a custom `onAbandon` crashes. The runtime
   * still aborts / retries according to the outlet's `onStepError`
   * policy - use this for telemetry, not control flow.
   *
   * The `phase` discriminator lets telemetry distinguish a step-render
   * throw from a control-plane failure: `"step"` for component throws,
   * `"invoke"` for invoke validation / start failures, `"resume"` for
   * resume-handler throws and resume-name lookup failures at child
   * terminal time, `"abandon"` for a custom `onAbandon` crash.
   */
  onError?: (
    err: unknown,
    ctx: {
      step: JourneyStep | null;
      phase: "step" | "invoke" | "resume" | "abandon";
    },
  ) => void;
  /**
   * Optional. Without it, journeys live in memory only - every
   * `runtime.start()` mints a fresh instance and nothing is written to
   * storage.
   */
  persistence?: JourneyPersistence<TState>;
  /**
   * Maximum `history` entries retained (oldest dropped). See the caveat
   * with `allowBack` below.
   */
  maxHistory?: number;
  /**
   * Optional nav contribution. When set, the journeys plugin emits a
   * navigation item for this journey so pure launchers don't need a
   * shadow module to host them. The contributed item carries
   * `action: { kind: "journey-start", journeyId, buildInput }`; the
   * shell's navbar dispatcher starts the journey on click.
   */
  nav?: JourneyNavContribution<TInput>;
  /**
   * Cap on the depth of an in-flight invoke chain that includes this
   * journey. Resolved as the **minimum** non-undefined `maxCallStackDepth`
   * across the active chain (ancestors + parent + child). Default: `16`.
   * See [Cycle and recursion safety](#cycle-and-recursion-safety).
   */
  maxCallStackDepth?: number;
  /**
   * Cap on consecutive resume bounces at the same parent step (a "bounce"
   * is a resume returning `{ invoke }` instead of advancing). Default:
   * `8`. Per-parent only — children don't influence their parent's budget.
   */
  maxResumeBouncesPerStep?: number;
}

interface JourneyNavContribution<TInput = unknown> {
  label: string;
  icon?: string | React.ComponentType<{ className?: string }>;
  group?: string;
  order?: number;
  hidden?: boolean;
  meta?: unknown;
  /** Builds the journey's `input` at click time. Typed against `TInput`. */
  buildInput?: (ctx?: unknown) => TInput;
}
```

#### Journey-contributed nav

Set `options.nav` on `registerJourney` when the journey is reachable from a top-level navbar entry without a dedicated launcher module. The journeys plugin collects every `nav` block at manifest time and merges them into `manifest.navigation` alongside module-contributed items. Items the plugin emits carry an `action: { kind: "journey-start", journeyId, buildInput }` - the framework stays agnostic about how the shell dispatches the action; the shell's navbar renderer switches on `action` to start the journey via `runtime.start(journeyId, buildInput?.())`.

Apps with a narrowed `TNavItem` (typed i18n labels, typed action union, typed meta bag) should supply a `buildNavItem` adapter on `journeysPlugin({ buildNavItem })` to reshape the plugin's default item into the app-narrowed type:

```ts
journeysPlugin<AppNavItem>({
  buildNavItem: (defaults, raw) => ({
    ...defaults,
    meta: { analytics: `launch-${raw.journeyId}` },
  }),
});
```

See the React Router example shell (`examples/react-router/customer-onboarding-journey/shell/`) for an end-to-end wiring: the `quick-bill` journey surfaces itself as the navbar "Start a quick bill" button; the shell's `TopNav` component renders items based on whether they carry an `action` or a plain `to`.

### Serialized shape (persistence)

```ts
interface SerializedJourney<TState> {
  definitionId: string;
  version: string;
  instanceId: string;
  status: "active" | "completed" | "aborted";
  step: { moduleId: string; entry: string; input: unknown } | null;
  history: ReadonlyArray<{ moduleId: string; entry: string; input: unknown }>;
  /** Index-aligned with `history`; `null` for entries without a rollback snapshot. */
  rollbackSnapshots?: ReadonlyArray<TState | null>;
  /** Present only on terminal blobs - mirrors the transition's `complete`/`abort` payload. */
  terminalPayload?: unknown;
  state: TState;
  startedAt: string;
  updatedAt: string;
  /**
   * Set when this instance has invoked a child journey that hasn't yet
   * resumed. `childPersistenceKey` is `null` when the child journey has
   * no persistence configured. Cleared on resume / cascade-end.
   */
  pendingInvoke?: {
    childJourneyId: string;
    childInstanceId: string;
    childPersistenceKey: string | null;
    resumeName: string;
  };
  /**
   * Set on a child instance whose parent invoked it. Mirrors the
   * parent's `pendingInvoke` so a child blob loaded out-of-order on
   * reload still knows which parent to resume.
   */
  parentLink?: {
    parentInstanceId: string;
    resumeName: string;
  };
}
```

### Testing (`@modular-react/journeys/testing`)

| Export               | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `simulateJourney`    | Headless simulator: fires exits / goBack, exposes `step` / `currentStep` (throws if terminal) / `state` / `history` / `status` / `transitions` / `terminalPayload` / `serialize()`, no React. Generic over `<TModules, TState, TInput, TOutput = unknown>` so a journey with a typed terminal payload is assignable without `as unknown as Parameters<…>[0]`. `step` / `currentStep` / `history` are typed as `JourneyStepFor<TModules>`, so narrowing on `step.entry` surfaces the entry's `input` type. Pass `options.modules` to opt into `buildInput` resolution and `allowBack` mode lookup. |
| `JourneySimulator`   | Type for the object returned by `simulateJourney`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `createTestHarness`  | Wraps a live `JourneyRuntime` so tests can fire exits, call `goBack`, and inspect instance internals without mounting `<JourneyOutlet>`. Replaces reaching for `getInternals` directly.                                                                                                                                                                                                                                                                                                                                                                                                           |
| `JourneyTestHarness` | Type returned by `createTestHarness`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### From the router runtime packages

| Export                                    | Purpose                                                                                                     |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `registry.registerJourney(def, options?)` | Adds a journey to the registry. Structural check runs immediately; contract check at resolve time.          |
| `manifest.journeys`                       | The `JourneyRuntime` bound to the resolved registry. Always non-null (no-op when no journey is registered). |
| `manifest.moduleDescriptors`              | Map of module id → descriptor. Consumed by `<ModuleTab>` and by any code rendering a module entry directly. |
| `ResolveManifestOptions.onModuleExit`     | Shell-level fallback for module exits fired through `<ModuleTab>`. Wire to analytics or global tab-close.   |

## Example projects

Complete, runnable walk-throughs live under `examples/`:

- [`examples/react-router/customer-onboarding-journey/`](../../examples/react-router/customer-onboarding-journey/) - React Router integration.
- [`examples/tanstack-router/customer-onboarding-journey/`](../../examples/tanstack-router/customer-onboarding-journey/) - TanStack Router integration with the same modules and journey.

Each `customer-onboarding-journey` example demonstrates:

- `defineEntry` / `defineExit` across three modules (profile, plan, billing).
- `defineJourney` composing them with typed transitions and a shared state.
- `registry.registerJourney(...)` with a localStorage persistence adapter - reload the page mid-flow and the tab resumes at the last step.
- A minimal tabbed shell mounting `<JourneyOutlet>` and `<ModuleTab>` side-by-side.
- `WorkspaceActions.openTab({ kind: 'journey', … })` as the shell-facing API, with `openModuleTab` kept as a `@deprecated` shim.

The `integration-setup-journey` examples demonstrate the [`selectModule` / `selectModuleOrDefault`](#pattern--exhaustive-state-driven-module-dispatch-selectmodule) dispatch helpers paired with slot-driven discovery:

- [`examples/react-router/integration-setup-journey/`](../../examples/react-router/integration-setup-journey/) - React Router integration with Playwright coverage of every dispatch branch.
- [`examples/tanstack-router/integration-setup-journey/`](../../examples/tanstack-router/integration-setup-journey/) - TanStack Router mirror.

What they show:

- A generic `integration-picker` module that reads `useSlots<AppSlots>().integrations` and renders a row per contributing module - the picker stays agnostic of which integrations exist.
- Modules contribute themselves to the `integrations` slot at registration time. Two of them (`github`, `strapi`) own dedicated configure components; two (`contentful`, `notion`) are headless `defineSlots` modules with no UI.
- The journey's `chosen` transition uses `selectModuleOrDefault` to route github + strapi to their dedicated steps and funnel everything else through `generic-integration`.
- An inline note on when to swap to `selectModule` (exhaustive) instead - useful if every kind earns its own dedicated module.

The `journey-invoke` examples demonstrate [Composing journeys (invoke / resume)](#composing-journeys-invoke--resume) — a parent (`checkout`) suspends mid-flow to run a child (`verify-identity`), picks up the child's typed terminal payload, and continues:

- [`examples/react-router/journey-invoke/`](../../examples/react-router/journey-invoke/) - React Router integration.
- [`examples/tanstack-router/journey-invoke/`](../../examples/tanstack-router/journey-invoke/) - TanStack Router mirror.

What they show:

- The `invoke()` helper threading the child handle's `TInput` / `TOutput` through to the parent's transition — wrong-shaped `input` is a compile error.
- The sibling `resumes` map keyed identically to `transitions`, with a `ChildOutcome<TOutput>` discriminated union narrowing `outcome.payload` for the completed branch.
- Both parent and child registered with persistence adapters — reload mid-verification and the runtime auto-rehydrates the call chain via `pendingInvoke.childPersistenceKey` and relinks parent ↔ child.
- A `<JourneyOutlet>` rendering the leaf of the active call chain (the default), plus `useJourneyCallStack` driving a small "call stack" banner.
- An `onTransition` hook that filters on `kind` to log invoke / resume hops distinctly from ordinary step transitions.