@modular-react/journeys 0.1.0 → 1.0.1

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { AbandonCtx } from '@modular-react/core';
+import { CatalogMeta } from '@modular-react/core';
+import { ChildOutcome } from '@modular-react/core';
 import { ComponentType } from 'react';
 import { EntryInputOf } from '@modular-react/core';
 import { EntryNamesOf } from '@modular-react/core';
@@ -7,6 +9,8 @@ import { ExitCtx } from '@modular-react/core';
 import { ExitNamesOf } from '@modular-react/core';
 import { ExitOutputOf } from '@modular-react/core';
 import { InstanceId } from '@modular-react/core';
+import { InvokeSpec } from '@modular-react/core';
+import { isJourneySystemAbort } from '@modular-react/core';
 import { JourneyDefinitionSummary } from '@modular-react/core';
 import { JourneyHandleRef } from '@modular-react/core';
 import { JourneyInstance } from '@modular-react/core';
@@ -14,13 +18,20 @@ import { JourneyPersistence } from '@modular-react/core';
 import { JourneyRuntime } from '@modular-react/core';
 import { JourneyStatus } from '@modular-react/core';
 import { JourneyStep } from '@modular-react/core';
+import { JourneySystemAbortReason } from '@modular-react/core';
+import { JourneySystemAbortReasonCode } from '@modular-react/core';
 import { MaybePromise } from '@modular-react/core';
 import { ModuleDescriptor } from '@modular-react/core';
 import { ModuleExitEvent } from '@modular-react/react';
 import { ModuleTypeMap } from '@modular-react/core';
 import { NavigationItemBase } from '@modular-react/core';
+import { ParentLink } from '@modular-react/core';
+import { PendingInvoke } from '@modular-react/core';
 import { ReactNode } from 'react';
 import { RegistryPlugin } from '@modular-react/core';
+import { ResumeBounceCounter } from '@modular-react/core';
+import { ResumeHandler } from '@modular-react/core';
+import { ResumeMap } from '@modular-react/core';
 import { SerializedJourney } from '@modular-react/core';
 import { StepSpec } from '@modular-react/core';
 import { TerminalCtx } from '@modular-react/core';
@@ -31,13 +42,44 @@ import { TransitionResult } from '@modular-react/core';
 
 export { AbandonCtx }
 
-/** Erased shape used by the registry — `any` on the generics lets the
+/**
+ * A transition handler with declared `targets` metadata attached. Functionally
+ * identical to the bare handler the journey runtime expects — the call
+ * signature is preserved verbatim, so the value drops directly into a
+ * `transitions[mod][entry][exit]` slot. The host's preloader walks
+ * `Object.values(perEntry)` and reads each handler's `.targets` to schedule
+ * speculative imports.
+ */
+export declare type AnnotatedTransitionHandler<THandler extends (ctx: any) => any, TTargets extends readonly (StepObjectRef | TerminalSentinel)[]> = THandler & {
+    readonly targets: TTargets;
+};
+
+/** Erased shape used by the registry — `any` on every generic lets the
  *  registry store definitions from different journeys side-by-side.
  *  Tightening to `unknown` breaks variance: `initialState: (input: TInput)
  *  => TState` for a specific journey is not assignable to
  *  `(input: unknown) => unknown` because function parameters are
- *  contravariant, so the registry would reject any concrete definition. */
-export declare type AnyJourneyDefinition = JourneyDefinition<ModuleTypeMap, any, any>;
+ *  contravariant, so the registry would reject any concrete definition.
+ *
+ *  TModules is also `any` (rather than `ModuleTypeMap`) so the structural
+ *  variance check on `ResumeMap`/`TransitionMap` does not strictly require
+ *  the wide form to carry every specific module key — `any` short-circuits
+ *  the property-by-property check and admits any concrete TModules. */
+export declare type AnyJourneyDefinition = JourneyDefinition<any, any, any, any, any>;
+
+export { ChildOutcome }
+
+/**
+ * Convenience wrapper for ordering two version strings. Returns -1 if `a`
+ * sorts before `b`, 1 if after, 0 if equal. Throws {@link SemverParseError}
+ * if either input is not a strict `MAJOR.MINOR.PATCH`.
+ *
+ * Useful for persisted-data compatibility checks: "is the version recorded
+ * on this saved blob older than the cutoff at which we changed the on-disk
+ * shape?". For matching against a range (`^1.0.0`, `>=1.5 <2`, …) use
+ * {@link satisfies} instead.
+ */
+export declare function compareVersions(a: string, b: string): number;
 
 /**
  * Create a journey runtime bound to a set of registered journeys. The
@@ -117,34 +159,43 @@ export declare function createWebStoragePersistence<TInput, TState>(options: Web
  * transitions, and the journey's private state.
  *
  * **Why the empty parens?** TypeScript can't partially infer generics: if
- * `defineJourney` took `<TModules, TState, TInput>` in a single call, you'd
- * either have to spell all three — losing the ability to infer `TInput`
- * from `initialState`'s parameter — or spell none, losing the ability to
- * narrow `TModules` / `TState`. The two-call shape splits the generics
- * so `TModules` + `TState` are explicit (first call) while `TInput` is
- * inferred from the definition object (second call).
+ * `defineJourney` took `<TModules, TState, TInput, TOutput>` in a single
+ * call, you'd either have to spell all four — losing the ability to infer
+ * `TInput` from `initialState`'s parameter — or spell none, losing the
+ * ability to narrow `TModules` / `TState`. The two-call shape splits the
+ * generics so `TModules` + `TState` (+ optional `TOutput`) are explicit
+ * (first call) while `TInput` is inferred from the definition object
+ * (second call).
  *
  * ```ts
- * defineJourney<OnboardingModules, OnboardingState>()({
+ * defineJourney<OnboardingModules, OnboardingState>()({ ... });
+ * defineJourney<OnboardingModules, OnboardingState, { token: string }>()({
  *   id: "customer-onboarding",
  *   version: "1.0.0",
  *   initialState: (input: { customerId: string }) => ({ ... }),
- *   // TInput is inferred as { customerId: string } here
  *   start: (state) => ({ module: "profile", entry: "review", input: { customerId: state.customerId } }),
- *   transitions: { ... },
+ *   transitions: {
+ *     billing: {
+ *       collect: {
+ *         done: ({ output }) => ({ complete: { token: output.token } }),
+ *         //                                  ^ checked against { token: string }
+ *       },
+ *     },
+ *   },
  * });
  * ```
  *
  * Zero runtime cost — the definition is returned unchanged.
  */
-export declare const defineJourney: <TModules extends ModuleTypeMap, TState>() => <TInput = void>(definition: JourneyDefinition<TModules, TState, TInput>) => JourneyDefinition<TModules, TState, TInput>;
+export declare const defineJourney: <TModules extends ModuleTypeMap, TState, TOutput = unknown, TMeta extends { [K in keyof TMeta]: unknown; } = Record<string, unknown>>() => <TInput = void>(definition: JourneyDefinition<TModules, TState, TInput, TOutput, CatalogMeta & TMeta>) => JourneyDefinition<TModules, TState, TInput, TOutput, any>;
 
 /**
  * Build a handle from a journey definition. Runtime identity is just
  * `{ id: def.id }`; the returned object is typed so callers get
- * `input`-checking through the `start` overload.
+ * `input`-checking through the `start` overload and `outcome.payload`
+ * narrowing through a parent journey's resume handler.
  */
-export declare function defineJourneyHandle<TModules extends ModuleTypeMap, TState, TInput>(def: JourneyDefinition<TModules, TState, TInput>): JourneyHandle<string, TInput>;
+export declare function defineJourneyHandle<TModules extends ModuleTypeMap, TState, TInput, TOutput>(def: JourneyDefinition<TModules, TState, TInput, TOutput>): JourneyHandle<string, TInput, TOutput>;
 
 /**
  * Identity helper that ties a persistence adapter's `keyFor` input to a
@@ -175,6 +226,75 @@ export declare function defineJourneyHandle<TModules extends ModuleTypeMap, TSta
  */
 export declare function defineJourneyPersistence<TInput, TState>(adapter: JourneyPersistence<TState, TInput>): JourneyPersistence<TState, TInput>;
 
+/**
+ * Wrap a transition handler with a static declaration of every outcome it may
+ * take. Two effects:
+ *
+ *   1. **Runtime — preload precision.** `<JourneyOutlet>`'s default
+ *      `preload="precise"` mode reads `targets` and warms exactly those
+ *      entries' chunks during idle time, so navigating Next finds the
+ *      chunk already cached. Bare-function handlers contribute nothing
+ *      to precise mode (they fall back to `preload="aggressive"` if set).
+ *      Sentinel targets (`"complete"`, `"abort"`, `"invoke"`) carry no
+ *      chunk to preload — they are skipped.
+ *
+ *   2. **Type-level — the handler's return is constrained to the declared
+ *      arms.** Declaring `targets: [{ module: "plan", entry: "choose" }]`
+ *      means the handler may only return `{ next: ... }`; declaring
+ *      `targets: ["abort"]` means only `{ abort: ... }`; mixing both
+ *      allows either. Returning an undeclared arm is a compile error.
+ *
+ * **`targets` is mandatory.** A wrapped handler must enumerate every
+ * outcome it may take. If you don't want a declaration, use a bare
+ * function — the runtime invocation path is identical, and bare handlers
+ * sit out of precise-mode preload.
+ *
+ * Two call shapes:
+ *
+ * ```ts
+ * // Curried (recommended): bind the journey's generics once, get full
+ * // contextual typing on every wrapped handler. Naming convention mirrors
+ * // `selectModule` (a descriptive verb for the binder, not an
+ * // abbreviation — `tx` reads as "transaction" in most codebases).
+ * const transition = defineTransition<OnboardingModules, OnboardingState>();
+ *
+ * profileComplete: transition({
+ *   targets: [{ module: "plan", entry: "choose" }],
+ *   handle: ({ output, state }) => ({
+ *     state: { ...state, hint: output.hint },
+ *     next: { module: "plan", entry: "choose", input: ... },
+ *   }),
+ * }),
+ *
+ * // Mix step refs with sentinels for handlers that branch between
+ * // next and a terminal arm:
+ * checkout: transition({
+ *   targets: [{ module: "plan", entry: "choose" }, "abort"],
+ *   handle: ({ output }) =>
+ *     output.kind === "ok"
+ *       ? { next: { module: "plan", entry: "choose", input: ... } }
+ *       : { abort: { reason: "user-cancelled" } },
+ * }),
+ *
+ * // Bare: zero-config, no contextual narrowing. Targets accept any
+ * // `{ module: string; entry: string } | "complete" | "abort" | "invoke"`;
+ * // useful for one-off handlers or for journeys whose return literals
+ * // are already typed by an outer annotation.
+ * cancelled: defineTransition({
+ *   targets: ["abort"],
+ *   handle: () => ({ abort: { reason: "user-cancelled" } }),
+ * }),
+ * ```
+ */
+export declare function defineTransition<TModules extends ModuleTypeMap, TState = unknown, TOutput = unknown>(): TypedTransitionBinder<TModules, TState, TOutput>;
+
+export declare function defineTransition<THandler extends (ctx: any) => any, const TTargets extends readonly (StepObjectRef | TerminalSentinel)[]>(spec: DefineTransitionSpec<THandler, TTargets>): AnnotatedTransitionHandler<THandler, TTargets>;
+
+declare interface DefineTransitionSpec<THandler extends (ctx: any) => any, TTargets extends readonly (StepObjectRef | TerminalSentinel)[]> {
+    readonly targets: TTargets;
+    readonly handle: THandler;
+}
+
 export { EntryInputOf }
 
 export { EntryNamesOf }
@@ -189,6 +309,54 @@ export { ExitOutputOf }
 
 export { InstanceId }
 
+/**
+ * Typed builder for the `{ invoke }` arm of `TransitionResult`. The union
+ * arm itself declares `InvokeSpec<unknown, unknown>` — bare object literals
+ * like `{ invoke: { handle, input, resume } }` therefore won't catch a
+ * mismatch between `input` and the handle's `TInput`. Going through this
+ * helper threads both `TInput` and `TOutput` from the handle into `input`
+ * (which must be assignable) and the returned spec, so authors get
+ * end-to-end checking at the call site:
+ *
+ * ```ts
+ * confirmAge: ({ state }) =>
+ *   invoke({
+ *     handle: verifyIdentityHandle,    // TInput = { customerId: string }
+ *     input: { customerId: state.id }, // checked against TInput
+ *     resume: "afterAgeVerified",
+ *   }),
+ * ```
+ *
+ * The runtime treats the result identically to a hand-built literal — the
+ * only purpose is the compile-time check.
+ */
+export declare function invoke<TInput, TOutput>(spec: {
+    readonly handle: JourneyHandleRef<string, TInput, TOutput>;
+    readonly input: TInput;
+    readonly resume: string;
+}): {
+    readonly invoke: InvokeSpec<TInput, TOutput>;
+};
+
+export { InvokeSpec }
+
+/**
+ * Narrow a value to the annotated form. Used by the auto-preloader to read
+ * `targets` from a handler without trusting structural lookups on `unknown`.
+ * Each target must be either a `{ module, entry }` string-pair or one of
+ * the recognized sentinel strings.
+ */
+export declare function isAnnotatedTransition(value: unknown): value is AnnotatedTransitionHandler<(ctx: any) => any, readonly (StepObjectRef | TerminalSentinel)[]>;
+
+export { isJourneySystemAbort }
+
+/**
+ * Narrow a value to one of the recognized {@link TerminalSentinel} strings.
+ * Exposed for hosts that introspect a wrapped handler's targets and want to
+ * separate step refs from terminal arms without a string-equality dance.
+ */
+export declare function isTerminalSentinel(value: unknown): value is TerminalSentinel;
+
 /**
  * Default shape the journeys plugin emits for each `nav`-carrying journey.
  * When {@link JourneysPluginOptions.buildNavItem} is provided, the plugin
@@ -218,16 +386,102 @@ export declare interface JourneyDefaultNavItem extends NavigationItemBase {
     };
 }
 
-export declare interface JourneyDefinition<TModules extends ModuleTypeMap, TState, TInput = void> {
+export declare interface JourneyDefinition<TModules extends ModuleTypeMap, TState, TInput = void, TOutput = unknown, TMeta extends {
+    [K in keyof TMeta]: unknown;
+} = Record<string, unknown>> {
     readonly id: string;
     readonly version: string;
-    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly meta?: Readonly<CatalogMeta & TMeta>;
     readonly initialState: (input: TInput) => TState;
     readonly start: (state: TState, input: TInput) => StepSpec<TModules>;
-    readonly transitions: TransitionMap<TModules, TState>;
+    readonly transitions: TransitionMap<TModules, TState, TOutput>;
+    /**
+     * Resume handlers fired when a child journey `invoke`d from a parent
+     * step terminates. Keyed by `[moduleId][entryName][resumeName]` — the
+     * runtime looks up `resumes[currentMod][currentEntry][invokeSpec.resume]`
+     * at child terminal time and applies the result as the parent's next
+     * transition. Optional — journeys that never invoke can omit it.
+     */
+    readonly resumes?: ResumeMap<TModules, TState, TOutput>;
+    /**
+     * Closed set of journey handles this journey may invoke from any of its
+     * transitions (or from a resume that returns `{ invoke }`). Strongly
+     * recommended for any journey that uses `invoke`:
+     *
+     * 1. **Static cycle detection.** When every journey in a registration
+     *    declares `invokes`, the registry runs a graph-level cycle check
+     *    at validation time and rejects the registration with a path like
+     *    `cycle detected: A → B → A` — far easier to diagnose than the
+     *    runtime `invoke-cycle` abort.
+     * 2. **Runtime arrival check.** At invoke time the runtime verifies
+     *    that the dispatched handle id appears in `invokes`; an unexpected
+     *    handle aborts the parent with reason `invoke-undeclared-child`,
+     *    catching dynamic dispatch bugs (a transition that branches on
+     *    `output` and lands on a handle the author never intended).
+     *
+     * Omit only when the call set is genuinely dynamic (e.g. a host that
+     * receives child handles from a slot contribution at runtime). The
+     * runtime cycle / depth / bounce guards still apply in that case;
+     * they just no longer have a static graph to cross-check against.
+     *
+     * Self-loops (a journey listing its own handle) are reported as a
+     * cycle — by construction they would also blow the call-stack guard
+     * at runtime.
+     */
+    readonly invokes?: ReadonlyArray<JourneyHandleRef<string, any, any>>;
+    /**
+     * Expected module version ranges, keyed by the `id` of a module declared
+     * in `TModules`. The keys are constrained to that map so a typo in a
+     * module id is a compile error rather than a registration-time issue
+     * ("requires module 'profil' but it is not registered"). The journeys
+     * plugin checks each entry at registry resolve time against the
+     * actually-registered module's `version` field; any incompatibility
+     * fails assembly with a {@link JourneyValidationError} listing every
+     * mismatch at once.
+     *
+     * **Why declare this even though the journey already references modules
+     * by id in `transitions`?** A journey that mixes in a module from another
+     * team is implicitly coupled to that module's exit-name and input-shape
+     * contract. The id-and-shape match holds today, but a backwards-
+     * incompatible bump on the other side ("we renamed the `success` exit
+     * to `done`") would otherwise only surface at runtime when the journey
+     * actually navigates to that step. Adding a compat declaration moves
+     * that failure to startup so an incompatible deployment refuses to come
+     * up at all, instead of breaking a single user mid-flow.
+     *
+     * The range syntax is an npm-style subset: caret, tilde, x-range,
+     * comparators, AND, OR, and hyphen — see the README's
+     * "Pattern - module compatibility (`moduleCompat`)" section for the
+     * exhaustive list. Pre-release tags and build metadata are not
+     * supported. Module ids in this map are typed against `TModules` so
+     * a typo is a compile error; an entry naming a module that genuinely
+     * isn't registered (e.g. via the erased `AnyJourneyDefinition` path)
+     * is reported with a dedicated "module not registered" issue.
+     *
+     * Optional. A journey that omits this field opts out of compatibility
+     * enforcement entirely; the existing structural validators
+     * (`transitions` referencing real modules / entries / exits) still run.
+     *
+     * @example
+     * ```ts
+     * defineJourney<OnboardingModules, OnboardingState>()({
+     *   id: "onboarding",
+     *   version: "1.0.0",
+     *   moduleCompat: {
+     *     profile: "^1.0.0",
+     *     billing: "^2.0.0 || ^3.0.0",
+     *     plan: ">=1.5.0 <2.0.0",
+     *   },
+     *   // ...
+     * });
+     * ```
+     */
+    readonly moduleCompat?: {
+        readonly [K in keyof TModules & string]?: string;
+    };
     readonly onTransition?: (ev: TransitionEvent_2<TModules, TState>) => void;
-    readonly onAbandon?: (ctx: AbandonCtx<TModules, TState>) => TransitionResult<TModules, TState>;
-    readonly onComplete?: (ctx: TerminalCtx<TState>, result: unknown) => void;
+    readonly onAbandon?: (ctx: AbandonCtx<TModules, TState>) => TransitionResult<TModules, TState, TOutput>;
+    readonly onComplete?: (ctx: TerminalCtx<TState>, result: TOutput) => void;
     readonly onAbort?: (ctx: TerminalCtx<TState>, reason: unknown) => void;
     readonly onHydrate?: (blob: SerializedJourney<TState>) => SerializedJourney<TState>;
 }
@@ -236,14 +490,16 @@ export { JourneyDefinitionSummary }
 
 /**
  * Lightweight token a journey exports so modules and shells can open it
- * with a typed `input` without pulling in the journey's runtime code.
+ * with a typed `input` (and a typed `outcome.payload` when invoked from a
+ * parent journey) without pulling in the journey's runtime code.
  * Structurally identical to `JourneyHandleRef` in `@modular-react/core` —
  * re-exported here so authors have a single canonical name to import.
  *
- * The `__input` field is phantom: it never holds a value at runtime, it
- * only carries the input type for the `start(handle, input)` overload.
+ * The `__input` and `__output` fields are phantom: they never hold values
+ * at runtime, they only carry types for the `start(handle, input)`
+ * overload and a parent journey's resume handler signature.
  */
-export declare type JourneyHandle<TId extends string = string, TInput = unknown> = JourneyHandleRef<TId, TInput>;
+export declare type JourneyHandle<TId extends string = string, TInput = unknown, TOutput = unknown> = JourneyHandleRef<TId, TInput, TOutput>;
 
 export declare class JourneyHydrationError extends Error {
     constructor(message: string, options?: ErrorOptions);
@@ -337,6 +593,19 @@ export declare interface JourneyOutletProps {
     readonly onStepError?: (err: unknown, ctx: {
         step: JourneyStep;
     }) => JourneyStepErrorPolicy;
+    /**
+     * When `false`, the outlet renders the instance you handed it directly,
+     * even if it has a child journey in flight. Set this when you compose
+     * two outlets to render parent and child side-by-side or in a modal —
+     * the parent outlet stays on the parent's step, and a sibling outlet
+     * keyed off `instance.activeChildId` renders the child.
+     *
+     * When `true` (the default), the outlet walks the active call chain
+     * from the supplied `instanceId` down to the leaf and renders the leaf,
+     * matching the subroutine intuition: a child takes over the same
+     * outlet for the duration of its run.
+     */
+    readonly leafOnly?: boolean;
     /**
      * Cap on `retry` responses before the outlet falls back to `abort`. The
      * counter increments on every retry from `onStepError` and is never reset,
@@ -355,6 +624,36 @@ export declare interface JourneyOutletProps {
      * through their own reporting.
      */
     readonly errorComponent?: ComponentType<JourneyOutletErrorProps>;
+    /**
+     * Speculatively prefetch the chunks for entries reachable from the
+     * current step during idle time after mount, so the next click finds
+     * its 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-function handlers contribute nothing (this is the precise
+     *     mode's whole point — no guessing).
+     *
+     *   `"aggressive"` — preload every entry that appears as a transition
+     *     source OR as a declared `target` of any annotated handler in the
+     *     journey's `transitions` map. The destination-side pass catches
+     *     terminal-only steps that have no outbound transitions of their
+     *     own (e.g. a freshly-added receipt screen reachable from `next:`
+     *     but not yet wired with its own exits). A step reachable only
+     *     via `definition.start` AND with no outbound transitions of its
+     *     own is the one remaining static gap — but such a step can only
+     *     be the current step on first mount (no exits → no advance), and
+     *     the skip-current logic already excludes it. Useful when handlers
+     *     are not annotated and the journey is small enough that warming
+     *     all candidates is cheap.
+     *
+     *   `false` — opt out entirely.
+     *
+     * Has no effect for eager (`component:`) entries — their import is
+     * already resolved. Effects only fire in the browser; SSR is a no-op.
+     */
+    readonly preload?: boolean | "precise" | "aggressive";
 }
 
 export { JourneyPersistence }
@@ -434,12 +733,16 @@ export declare interface JourneyRegisterOptions<TState = unknown, TInput = unkno
      */
     onHydrate?: (blob: SerializedJourney<TState>) => SerializedJourney<TState>;
     /**
-     * Fires when a step component throws or a transition handler throws for
-     * an instance of this journey. Observation-only — the runtime still
-     * aborts / retries according to the outlet's `onStepError` policy.
+     * Fires when a step component throws, a transition handler throws,
+     * or an invoke / resume / abandon hook throws. Observation-only — the
+     * runtime still aborts / retries according to the outlet's
+     * `onStepError` policy. The `phase` discriminator lets telemetry
+     * distinguish a component throw (`"step"`) from an invoke/resume
+     * control-plane failure or 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
@@ -480,6 +783,58 @@ export declare interface JourneyRegisterOptions<TState = unknown, TInput = unkno
      * default item into the app's narrowed type.
      */
     nav?: JourneyNavContribution<TInput>;
+    /**
+     * Cap on the depth of an in-flight invoke chain that includes this
+     * journey. The depth is the number of *active* journey instances in
+     * the chain — a root parent on its own is depth 1, a parent with one
+     * in-flight child is depth 2, etc. When an invoke would push depth
+     * beyond `maxCallStackDepth`, the parent aborts with reason
+     * `invoke-stack-overflow` (the child is never started) and the
+     * registration's `onError` fires with `phase: "invoke"`.
+     *
+     * The runtime resolves the effective limit as the **minimum** of every
+     * non-undefined `maxCallStackDepth` across the active chain (ancestors
+     * + the new parent + the would-be child's own setting). The most
+     * restrictive journey wins, so a cautious utility journey can lower
+     * the cap for any flow that includes it without coordinating with the
+     * other journeys.
+     *
+     * Default: `16`. Set lower for journeys whose call graphs are known
+     * to be shallow; raise it (carefully) only for genuinely deep
+     * compositions. Setting it to `1` blocks `invoke` from this journey
+     * outright.
+     *
+     * `0`, negative, or non-finite values are treated as "no opinion" and
+     * fall through to the next journey's setting (or the library default
+     * if no journey in the chain expresses an opinion). This matches the
+     * `maxHistory` convention so a misconfigured `0` cannot accidentally
+     * disable the guard.
+     */
+    maxCallStackDepth?: number;
+    /**
+     * Cap on consecutive resume "bounces" at the *same* parent step. A
+     * bounce is a resume that returns `{ invoke }` (re-invoking a child
+     * instead of advancing the parent's step). The counter increments on
+     * every resume that returns `{ invoke }` and resets to zero whenever
+     * the parent's step actually advances (`{ next | complete | abort }`
+     * from any source). When the counter would exceed
+     * `maxResumeBouncesPerStep`, the parent aborts with reason
+     * `resume-bounce-limit`; the child whose terminal triggered the
+     * over-the-limit bounce is *not* re-invoked.
+     *
+     * The counter is persisted on the parent's blob (see
+     * `SerializedJourney.resumeBouncesAtStep`) so a reload-bounce sequence
+     * cannot reset the budget by round-tripping through storage.
+     *
+     * Default: `8`. Raise it for flows that legitimately retry a sub-flow
+     * many times in a row; lower it for paranoia. The check uses the
+     * parent's setting only — children do not influence their parent's
+     * bounce budget.
+     *
+     * `0`, negative, or non-finite values fall through to the library
+     * default (matches `maxCallStackDepth` and `maxHistory`).
+     */
+    maxResumeBouncesPerStep?: number;
 }
 
 export { JourneyRuntime }
@@ -530,7 +885,7 @@ export declare interface JourneysPluginExtension {
      * `options.nav.buildInput` is typed against the journey's input — pass a
      * typed definition and both are checked end-to-end.
      */
-    registerJourney<TModules extends ModuleTypeMap, TState, TInput>(definition: JourneyDefinition<TModules, TState, TInput>, options?: JourneyRegisterOptions<TState, TInput>): void;
+    registerJourney<TModules extends ModuleTypeMap, TState, TInput, TOutput = unknown>(definition: JourneyDefinition<TModules, TState, TInput, TOutput>, options?: JourneyRegisterOptions<TState, TInput>): void;
 }
 
 export declare interface JourneysPluginOptions<TNavItem extends NavigationItemBase = JourneyDefaultNavItem> {
@@ -569,6 +924,10 @@ export { JourneyStep }
 
 export declare type JourneyStepErrorPolicy = "abort" | "retry" | "ignore";
 
+export { JourneySystemAbortReason }
+
+export { JourneySystemAbortReasonCode }
+
 /**
  * Aggregated error thrown when one or more registered journeys reference
  * module ids, entry names, or exit names that do not exist (or that
@@ -662,16 +1021,242 @@ export declare interface ModuleTabProps<TInput = unknown> {
 
 export { ModuleTypeMap }
 
+/**
+ * Narrow the handler return type to only the arms whose targets are declared.
+ * - `{ module, entry }` in targets → `next:` arm allowed (with `input` typed
+ *   against the chosen entry). Multiple refs collapse into one `next:` key
+ *   whose value is the union of step specs.
+ * - `"complete"` in targets → `complete:` arm allowed.
+ * - `"abort"` in targets → `abort:` arm allowed.
+ * - `"invoke"` in targets → `invoke:` arm allowed.
+ *
+ * Declaring an arm in targets but never returning it is fine (over-declaring
+ * is conservative for preload). Returning an arm that wasn't declared is a
+ * compile error — the wrapped handler can't drift past the declaration.
+ */
+declare type NarrowedTransitionResult<TModules extends ModuleTypeMap, TState, TOutput, TTargets extends readonly StepRef<TModules>[]> = (Extract<TTargets[number], StepObjectRef> extends never ? never : {
+    readonly next: StepSpecFromRef<TModules, Extract<TTargets[number], StepObjectRef>>;
+    readonly state?: TState;
+}) | (Extract<TTargets[number], "complete"> extends never ? never : {
+    readonly complete: TOutput;
+    readonly state?: TState;
+}) | (Extract<TTargets[number], "abort"> extends never ? never : {
+    readonly abort: unknown;
+    readonly state?: TState;
+}) | (Extract<TTargets[number], "invoke"> extends never ? never : {
+    readonly invoke: InvokeSpec<unknown, unknown>;
+    readonly state?: TState;
+});
+
+export { ParentLink }
+
+export { PendingInvoke }
+
 /** Internal registration record — definition + options kept together. */
 export declare interface RegisteredJourney<TState = unknown, TInput = unknown> {
     readonly definition: AnyJourneyDefinition;
     readonly options: JourneyRegisterOptions<TState, TInput> | undefined;
 }
 
+export { ResumeBounceCounter }
+
+export { ResumeHandler }
+
+export { ResumeMap }
+
+/**
+ * Convenience wrapper that parses both inputs and runs satisfaction. Use
+ * this for one-shot checks; for hot loops, parse once and pass the cached
+ * {@link ParsedRange} to {@link satisfiesParsed}.
+ */
+export declare function satisfies(version: string, range: string): boolean;
+
+/**
+ * Curried helper for state-driven module dispatch in a transition handler.
+ *
+ * `selectModule<TModules>()` binds the journey's module map; the inner call
+ * takes a discriminator (`key`) whose value names the next module and a
+ * cases object that supplies the entry + input for each branch. Returns a
+ * `StepSpec` ready to drop into `{ next }`.
+ *
+ * **Why curry on `TModules`?** Same partial-inference reason as
+ * `defineJourney`: TypeScript can't infer `TKey` while we're also forcing
+ * `TModules` to be specified — splitting the calls lets us spell the module
+ * map once and let the discriminator's union flow naturally into `TKey`.
+ *
+ * **Exhaustive by design.** The cases object is `Record<TKey, …>`, so when
+ * `key` is a union literal (`"github" | "strapi" | "contentful"`),
+ * forgetting a branch is a compile error. When you want a default-everything
+ * fallback instead of branch-by-branch coverage, use
+ * {@link selectModuleOrDefault}.
+ *
+ * **What you get:**
+ * - **Per-branch input checking** — each case's `entry` and `input` are
+ *   typed against the module the branch dispatches to. You can't paste a
+ *   `strapi`-shaped input under the `github` key.
+ * - **One state-spread instead of N** — call sites no longer repeat
+ *   `{ state, next: { … } }` per branch.
+ *
+ * **Limit:** the discriminator key must equal the target module id. When
+ * the discriminator differs from the id (e.g. `tier: "free" | "paid"`
+ * dispatching to module ids `trial-onboarding` / `billing-onboarding`),
+ * fall back to a `switch` returning `next` per branch — that case isn't
+ * common enough yet to justify a second helper.
+ *
+ * @example
+ * ```ts
+ * import { selectModule } from "@modular-react/journeys";
+ *
+ * const select = selectModule<IntegrationModules>();
+ *
+ * chosen: ({ output, state }) => ({
+ *   state: { ...state, selected: output.kind },
+ *   next: select(output.kind, {
+ *     github:     { entry: "configure", input: { workspaceId: state.workspaceId } },
+ *     strapi:     { entry: "configure", input: { workspaceId: state.workspaceId } },
+ *     contentful: { entry: "configure", input: { workspaceId: state.workspaceId } },
+ *   }),
+ * }),
+ * ```
+ *
+ * Zero runtime cost beyond an object lookup.
+ */
+export declare const selectModule: <TModules extends ModuleTypeMap>() => <TKey extends keyof TModules & string>(key: TKey, cases: SelectModuleCases<TModules, TKey>) => StepSpec<TModules>;
+
+/**
+ * Cases map for the exhaustive form `selectModule(key, cases)` — one case
+ * per discriminator value. Each case's `entry` is narrowed against that
+ * module's `entryPoints`; `input` is checked against that entry. Missing a
+ * key is a compile error, so a journey gains exhaustiveness for free when
+ * the discriminator is a union literal.
+ */
+export declare type SelectModuleCases<TModules extends ModuleTypeMap, TKey extends keyof TModules & string> = {
+    readonly [M in TKey]: StepCaseFor<TModules, M>;
+};
+
+/**
+ * Cases map for the fallback form `selectModuleOrDefault(key, cases,
+ * fallback)`. Every case is optional and any discriminator value not
+ * present in `cases` falls through to the explicit fallback `StepSpec`.
+ * `TKey` is intentionally widened to `string` so callers can pass a
+ * discriminator that includes values outside the module map (the fallback
+ * handles them).
+ *
+ * Keys are constrained to `Extract<TKey, keyof TModules>` so a typo on a
+ * module id still errors — the looseness is only on TKey itself, not on
+ * which module ids the cases object accepts.
+ */
+export declare type SelectModuleCasesPartial<TModules extends ModuleTypeMap, TKey extends string> = {
+    readonly [M in Extract<TKey, keyof TModules & string>]?: StepCaseFor<TModules, M>;
+};
+
+/**
+ * Sibling of {@link selectModule} that allows partial cases plus an
+ * explicit fallback `StepSpec`. Use when most discriminator values funnel
+ * into a generic module and only a few warrant their own specific
+ * dispatch.
+ *
+ * Kept as a separate function (rather than a third argument on
+ * `selectModule`) so that the *exhaustive* call site is visually
+ * distinct from the *fallback-allowed* one — losing exhaustiveness in
+ * `selectModule` by accidentally adding a third argument later would
+ * silently disable the missing-branch compile error.
+ *
+ * The cases object is `Partial<Record<TKey, …>>`; any discriminator value
+ * not present uses `fallback`. The fallback is a full `StepSpec`
+ * (carrying its own `module`) since it isn't keyed by the discriminator.
+ *
+ * @example
+ * ```ts
+ * import { selectModuleOrDefault } from "@modular-react/journeys";
+ *
+ * const select = selectModuleOrDefault<IntegrationModules>();
+ *
+ * chosen: ({ output, state }) => ({
+ *   state: { ...state, selected: output.kind },
+ *   next: select(
+ *     output.kind,
+ *     {
+ *       github: { entry: "configure", input: { workspaceId: state.workspaceId, repo: output.repo } },
+ *     },
+ *     { module: "generic", entry: "configure", input: { workspaceId: state.workspaceId, kind: output.kind } },
+ *   ),
+ * }),
+ * ```
+ */
+export declare const selectModuleOrDefault: <TModules extends ModuleTypeMap>() => <TKey extends string>(key: TKey, cases: SelectModuleCasesPartial<TModules, TKey>, fallback: StepSpec<TModules>) => StepSpec<TModules>;
+
+export declare class SemverParseError extends Error {
+    constructor(message: string);
+}
+
 export { SerializedJourney }
 
+/**
+ * One case in a `selectModule` map: an entry name on module `M` plus the
+ * matching input shape. The mapped object union is collapsed via the
+ * indexed-access trick at the end so the resulting type is a discriminated
+ * union over the module's entries (the same shape `StepSpec` uses).
+ */
+declare type StepCaseFor<TModules extends ModuleTypeMap, M extends keyof TModules & string> = {
+    [E in EntryNamesOf<TModules[M]> & string]: {
+        readonly entry: E;
+        readonly input: EntryInputOf<TModules[M], E>;
+    };
+}[EntryNamesOf<TModules[M]> & string];
+
+/**
+ * Type predicate that splits a `StepRef` into its step-ref vs sentinel arms.
+ * Object refs land in the `next:` arm; sentinels gate the terminal arms.
+ */
+declare type StepObjectRef = {
+    readonly module: string;
+    readonly entry: string;
+};
+
+/**
+ * Reference to one possible outcome of a transition handler. Used by
+ * {@link defineTransition} to declare every branch the handler may take;
+ * the host's auto-preloader reads the `{ module, entry }` entries to warm
+ * chunks for next-step candidates from the current step, and the catalog
+ * harvester reads the sentinels to derive `aborts` / `completes` flags
+ * without an AST walk over the handler body.
+ *
+ * The `{ module, entry }` shape mirrors the `next:` field handlers return —
+ * a step ref is just `StepSpec` without the runtime-computed `input` —
+ * so authors don't flip between two notations for the same idea.
+ *
+ * When `TModules` is bound (via the curried `defineTransition<TModules>()`
+ * binder), `module` narrows to `keyof TModules` and `entry` narrows to that
+ * module's `entryPoints` keys.
+ */
+export declare type StepRef<TModules extends ModuleTypeMap> = {
+    [M in keyof TModules & string]: {
+        [E in EntryNamesOf<TModules[M]> & string]: {
+            readonly module: M;
+            readonly entry: E;
+        };
+    }[EntryNamesOf<TModules[M]> & string];
+}[keyof TModules & string] | TerminalSentinel;
+
 export { StepSpec }
 
+/**
+ * Build the `next.{ module, entry, input }` shape for one declared step ref.
+ * Distributes over a union of refs so multiple targets produce a union of
+ * step specs under a single `next:` key (rather than separate `{ next: A }`
+ * vs `{ next: B }` arms — the latter would reject conditional handler
+ * returns like `next: cond ? planRef : billingRef`).
+ */
+declare type StepSpecFromRef<TModules extends ModuleTypeMap, TRef> = TRef extends {
+    readonly module: infer M;
+    readonly entry: infer E;
+} ? M extends keyof TModules & string ? E extends EntryNamesOf<TModules[M]> & string ? {
+    readonly module: M;
+    readonly entry: E;
+    readonly input: EntryInputOf<TModules[M], E>;
+} : never : never : never;
+
 /**
  * Narrowed variant of {@link JourneyPersistence} whose methods are
  * guaranteed synchronous — `load` returns `SerializedJourney<TState> | null`
@@ -698,12 +1283,42 @@ export { TerminalCtx }
 
 export { TerminalOutcome }
 
+/**
+ * Sentinel value declaring a non-`next` outcome on a wrapped transition
+ * handler. Mixed into the `targets:` array alongside `{ module, entry }`
+ * step refs so a single declaration captures every branch the handler
+ * may take.
+ *
+ *   - `"complete"` — handler may return `{ complete: ... }` (terminates).
+ *   - `"abort"` — handler may return `{ abort: ... }` (terminates with abort).
+ *   - `"invoke"` — handler may return `{ invoke: { handle, input, resume } }`
+ *     (suspends the parent, runs a child journey). The specific handle is
+ *     not type-narrowed here — the journey definition's `invokes` field
+ *     remains the closed-set declaration the runtime cycle / undeclared-
+ *     child guards check against.
+ */
+export declare type TerminalSentinel = "complete" | "abort" | "invoke";
+
 export { TransitionEvent_2 as TransitionEvent }
 
 export { TransitionMap }
 
 export { TransitionResult }
 
+/**
+ * Curried binder used by {@link defineTransition} to thread the journey's
+ * `TModules` / `TState` / `TOutput` into the handler's contextual return
+ * type — `next.module` / `next.entry` and the choice of arms (`next` vs
+ * `complete` vs `abort` vs `invoke`) check against the bound generics
+ * instead of widening to plain `string` / accepting any arm.
+ */
+declare interface TypedTransitionBinder<TModules extends ModuleTypeMap, TState, TOutput> {
+    <const TTargets extends readonly StepRef<TModules>[], TEntryInput = unknown, TExitOutput = unknown>(spec: {
+        readonly targets: TTargets;
+        readonly handle: (ctx: ExitCtx<TState, TExitOutput, TEntryInput>) => NarrowedTransitionResult<TModules, TState, TOutput, TTargets>;
+    }): AnnotatedTransitionHandler<(ctx: ExitCtx<TState, TExitOutput, TEntryInput>) => TransitionResult<TModules, TState, TOutput>, TTargets>;
+}
+
 /**
  * Thrown when `runtime.start()` / `runtime.hydrate()` is called with a
  * journey id that is not registered. Distinct class so shells can
@@ -715,6 +1330,19 @@ export declare class UnknownJourneyError extends Error {
     constructor(journeyId: string, registered: readonly string[]);
 }
 
+/**
+ * Returns the call stack for an outlet's instance — root at index 0, the
+ * active leaf at the end, intermediate parents in between. Useful for
+ * shells that render layered presentations (e.g. parent visible
+ * underneath, child in a modal): mount the parent outlet with
+ * `leafOnly={false}` and the child outlet against `chain[chain.length - 1]`.
+ *
+ * Subscribes to every instance in the chain so the array re-resolves
+ * when the chain shifts. Length is at least 1 (the root) for any
+ * registered instance.
+ */
+export declare function useJourneyCallStack(runtime: JourneyRuntime, rootId: InstanceId): readonly InstanceId[];
+
 /** Read the current provider value, or `null` when none is mounted. */
 export declare function useJourneyContext(): JourneyProviderValue | null;
 
@@ -727,6 +1355,36 @@ export declare function validateJourneyContracts(journeys: readonly RegisteredJo
  */
 export declare function validateJourneyDefinition(def: AnyJourneyDefinition): readonly string[];
 
+/**
+ * Verify the directed graph of journey-to-journey invocations, derived
+ * from each registered journey's `invokes` declaration, contains no
+ * cycles. A cycle in the static graph would, at runtime, manifest as
+ * either an infinite chain (depth-limited by `maxCallStackDepth`) or a
+ * same-id-on-stack abort — both are recoverable but late. The graph
+ * check turns the same mistake into a registration-time error citing
+ * the cycle path.
+ *
+ * Run automatically as part of {@link validateJourneyContracts}. Exposed
+ * separately so shells that compose registrations (e.g. plugin chaining)
+ * can run the graph check on a partial slice without invoking the full
+ * contracts validator. Throws {@link JourneyValidationError} when one or
+ * more cycles are detected.
+ *
+ * **What's checked.** The graph only spans journeys whose `invokes`
+ * field is declared as an array. Edges to journey ids that are not
+ * present in `journeys` are ignored — those will fail at runtime with
+ * `invoke-unknown-journey`, not as cycle reports. Self-loops (a journey
+ * that lists its own handle) are reported as a one-cycle.
+ *
+ * **What's NOT checked.** Journeys that omit `invokes` contribute no
+ * edges; a cycle that runs through such a journey will not be caught
+ * statically, and the runtime guards (`invoke-cycle`,
+ * `invoke-stack-overflow`) remain the safety net. Authors who want
+ * full static coverage should declare `invokes` on every journey that
+ * uses `invoke()`.
+ */
+export declare function validateJourneyGraph(journeys: readonly RegisteredJourney[]): void;
+
 export declare interface WebStoragePersistenceOptions<TInput> {
     /**
      * Compute the persistence key from the journey id and starting input.