@modular-react/journeys 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,754 @@
+import { AbandonCtx } from '@modular-react/core';
+import { ComponentType } from 'react';
+import { EntryInputOf } from '@modular-react/core';
+import { EntryNamesOf } from '@modular-react/core';
+import { EntryTransitions } from '@modular-react/core';
+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 { JourneyDefinitionSummary } from '@modular-react/core';
+import { JourneyHandleRef } from '@modular-react/core';
+import { JourneyInstance } from '@modular-react/core';
+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 { 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 { ReactNode } from 'react';
+import { RegistryPlugin } from '@modular-react/core';
+import { SerializedJourney } from '@modular-react/core';
+import { StepSpec } from '@modular-react/core';
+import { TerminalCtx } from '@modular-react/core';
+import { TerminalOutcome } from '@modular-react/core';
+import { TransitionEvent as TransitionEvent_2 } from '@modular-react/core';
+import { TransitionMap } from '@modular-react/core';
+import { TransitionResult } from '@modular-react/core';
+
+export { AbandonCtx }
+
+/** Erased shape used by the registry — `any` on the generics 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>;
+
+/**
+ * Create a journey runtime bound to a set of registered journeys. The
+ * registry integration assembles this once at resolve time; the runtime is
+ * owned by the manifest and exposed as `manifest.journeys`.
+ *
+ * Passing an empty `registered` array yields a no-op runtime: every public
+ * method is safe to call, and `start()` will throw "unknown journey id" —
+ * matching the normal "not registered" failure mode and letting shells skip
+ * null-guards on `manifest.journeys`.
+ */
+export declare function createJourneyRuntime(registered: readonly RegisteredJourney[], options?: JourneyRuntimeOptions): JourneyRuntime;
+
+/**
+ * Map-backed `JourneyPersistence` for tests and SSR. Gives tests a
+ * canonical isolated store (no bleed between cases, no `localStorage`
+ * mocking) and keeps the runtime's persistence code paths exercised.
+ *
+ * On SSR, it's a safe "persistence is configured but nothing survives
+ * the request" mode — every start mints a fresh instance, and save /
+ * remove are no-ops from the client's perspective.
+ *
+ * ```ts
+ * const store = createMemoryPersistence<MyInput, MyState>({
+ *   keyFor: ({ journeyId, input }) => `${journeyId}:${input.id}`,
+ * });
+ *
+ * const runtime = createJourneyRuntime(
+ *   [{ definition: myJourney, options: { persistence: store } }],
+ *   { modules },
+ * );
+ *
+ * // Tests can assert directly against the store:
+ * expect(store.size()).toBe(1);
+ * ```
+ */
+export declare function createMemoryPersistence<TInput, TState>(options: MemoryPersistenceOptions<TInput, TState>): MemoryPersistence<TInput, TState>;
+
+/**
+ * `JourneyPersistence` backed by the Web Storage API
+ * (`localStorage` / `sessionStorage`). Covers the 80% case: a few KB of
+ * JSON per journey-per-customer, read on mount, written on every transition.
+ *
+ * SSR-safe — when `storage` resolves to `null` (server rendering, private
+ * modes where storage is disabled) all four methods no-op and `load`
+ * returns `null`, so the runtime mints a fresh instance as it would
+ * without persistence configured.
+ *
+ * Corrupt entries (invalid JSON) are removed lazily on `load` so a single
+ * bad write doesn't block future loads for the same key.
+ *
+ * ```ts
+ * export const journeyPersistence = createWebStoragePersistence<
+ *   OnboardingInput,
+ *   OnboardingState
+ * >({
+ *   keyFor: ({ journeyId, input }) =>
+ *     `journey:${input.customerId}:${journeyId}`,
+ * });
+ *
+ * // Tab-scoped, cleared when the tab closes:
+ * const sessionScoped = createWebStoragePersistence<MyInput, MyState>({
+ *   keyFor: ({ journeyId, input }) => `s:${input.id}:${journeyId}`,
+ *   storage: typeof sessionStorage !== "undefined" ? sessionStorage : null,
+ * });
+ * ```
+ *
+ * **Limits.** `localStorage` is synchronous and capped at ~5 MB per origin.
+ * Writes throw `QuotaExceededError` when full; the error bubbles so the
+ * app can surface it. If a journey holds large state or offline-first
+ * matters, write a custom adapter against IndexedDB.
+ */
+export declare function createWebStoragePersistence<TInput, TState>(options: WebStoragePersistenceOptions<TInput>): SyncJourneyPersistence<TState, TInput>;
+
+/**
+ * Declare a journey with full type inference on entry/exit contracts,
+ * 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).
+ *
+ * ```ts
+ * defineJourney<OnboardingModules, OnboardingState>()({
+ *   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: { ... },
+ * });
+ * ```
+ *
+ * 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>;
+
+/**
+ * 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.
+ */
+export declare function defineJourneyHandle<TModules extends ModuleTypeMap, TState, TInput>(def: JourneyDefinition<TModules, TState, TInput>): JourneyHandle<string, TInput>;
+
+/**
+ * Identity helper that ties a persistence adapter's `keyFor` input to a
+ * journey's `TInput` so callers get compile-time checking on per-customer /
+ * per-session keys. Zero runtime cost — the adapter is returned as-is.
+ *
+ * The return type preserves both `TInput` and `TState`, so shells calling
+ * `persistence.keyFor({ input })` *outside* the runtime (e.g. to probe
+ * storage before opening a journey tab) still see the journey's typed
+ * input shape — no `input: unknown` erasure at the boundary.
+ *
+ * ```ts
+ * interface CustomerInput { customerId: string }
+ *
+ * const journeyPersistence = defineJourneyPersistence<CustomerInput, MyState>({
+ *   keyFor: ({ input }) => `journey:${input.customerId}:onboarding`,
+ *   load:   (k) => backend.load(k),
+ *   save:   (k, b) => backend.save(k, b),
+ *   remove: (k) => backend.remove(k),
+ * });
+ *
+ * // Outside the runtime — `input` is typed as CustomerInput:
+ * const key = journeyPersistence.keyFor({
+ *   journeyId: "onboarding",
+ *   input: { customerId: "C-1" },
+ * });
+ * ```
+ */
+export declare function defineJourneyPersistence<TInput, TState>(adapter: JourneyPersistence<TState, TInput>): JourneyPersistence<TState, TInput>;
+
+export { EntryInputOf }
+
+export { EntryNamesOf }
+
+export { EntryTransitions }
+
+export { ExitCtx }
+
+export { ExitNamesOf }
+
+export { ExitOutputOf }
+
+export { InstanceId }
+
+/**
+ * Default shape the journeys plugin emits for each `nav`-carrying journey.
+ * When {@link JourneysPluginOptions.buildNavItem} is provided, the plugin
+ * hands this default (plus the journey's id and buildInput factory) to the
+ * adapter so apps can reshape the item into their narrowed `TNavItem`.
+ */
+export declare interface JourneyDefaultNavItem extends NavigationItemBase {
+    readonly label: string;
+    /**
+     * Always empty for a journey launcher — the dispatchable action lives in
+     * {@link JourneyDefaultNavItem.action}, so there is no URL to follow. An
+     * empty string keeps the structural `NavigationItemBase.to` satisfied
+     * without suggesting the shell should treat this item as a link.
+     */
+    readonly to: "";
+    readonly icon?: string | ComponentType<{
+        className?: string;
+    }>;
+    readonly group?: string;
+    readonly order?: number;
+    readonly hidden?: boolean;
+    readonly meta?: unknown;
+    readonly action: {
+        readonly kind: "journey-start";
+        readonly journeyId: string;
+        readonly buildInput?: (ctx?: unknown) => unknown;
+    };
+}
+
+export declare interface JourneyDefinition<TModules extends ModuleTypeMap, TState, TInput = void> {
+    readonly id: string;
+    readonly version: string;
+    readonly meta?: Readonly<Record<string, unknown>>;
+    readonly initialState: (input: TInput) => TState;
+    readonly start: (state: TState, input: TInput) => StepSpec<TModules>;
+    readonly transitions: TransitionMap<TModules, TState>;
+    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 onAbort?: (ctx: TerminalCtx<TState>, reason: unknown) => void;
+    readonly onHydrate?: (blob: SerializedJourney<TState>) => SerializedJourney<TState>;
+}
+
+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.
+ * 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.
+ */
+export declare type JourneyHandle<TId extends string = string, TInput = unknown> = JourneyHandleRef<TId, TInput>;
+
+export declare class JourneyHydrationError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+
+export { JourneyInstance }
+
+/**
+ * Nav contribution attached to a `registerJourney` call. The journeys plugin
+ * collects these at manifest time and emits them as navigation items tagged
+ * with an `action.kind = "journey-start"` so the shell's navbar dispatcher
+ * can start the journey instead of following a URL.
+ *
+ * `TInput` is the journey's input type — `buildInput` produces that shape
+ * from whatever context the dispatcher passes at click time. Keeping the
+ * context loosely typed (`unknown`) matches how the journeys plugin surfaces
+ * contributions to the framework; apps that want to narrow the context can
+ * provide a typed `buildNavItem` adapter (see
+ * {@link JourneysPluginOptions}.`buildNavItem`).
+ */
+export declare interface JourneyNavContribution<TInput = unknown> {
+    /** Display label. Apps that type-narrow labels should reshape via `buildNavItem`. */
+    readonly label: string;
+    /** Icon — string identifier or React component (matches `NavigationItem.icon`). */
+    readonly icon?: string | React.ComponentType<{
+        className?: string;
+    }>;
+    /** Grouping key for the navbar, same semantics as `NavigationItem.group`. */
+    readonly group?: string;
+    /** Sort order within the group (lower wins). */
+    readonly order?: number;
+    /** If true, registered but hidden from default navbar rendering. */
+    readonly hidden?: boolean;
+    /** App-owned metadata, opaque to the library. */
+    readonly meta?: unknown;
+    /**
+     * Optional factory that builds the journey's `input` at click time. The
+     * shell's navbar dispatcher calls this with whatever nav context the host
+     * provides (workspace id, current selection, etc.) and hands the result
+     * back to `runtime.start(handle, input)`. Omit when the journey has no
+     * input; pass a pure factory when it does.
+     */
+    readonly buildInput?: (ctx?: unknown) => TInput;
+}
+
+/**
+ * Signature for the optional typed adapter that reshapes the plugin's
+ * default nav item into the app's narrowed `TNavItem`. The adapter is
+ * called once per `nav`-carrying journey at manifest time.
+ */
+export declare type JourneyNavItemBuilder<TNavItem extends NavigationItemBase> = (defaults: JourneyDefaultNavItem, raw: JourneyNavContribution<unknown> & {
+    readonly journeyId: string;
+}) => TNavItem;
+
+/**
+ * Renders the current step of a journey instance. Host-agnostic — works in
+ * a tab, modal, route element, or plain `<div>`. On unmount while active,
+ * the instance is abandoned (deferred by a microtask so React 18/19
+ * StrictMode's simulated mount/unmount/mount cycle does not tear the
+ * instance down on its first visit).
+ */
+export declare function JourneyOutlet(props: JourneyOutletProps): ReactNode;
+
+export declare interface JourneyOutletErrorProps {
+    readonly moduleId: string;
+    readonly error: unknown;
+}
+
+export declare interface JourneyOutletNotFoundProps {
+    readonly moduleId: string;
+    readonly entry: string;
+}
+
+export declare interface JourneyOutletProps {
+    /**
+     * Runtime to drive the outlet against. Optional when a `<JourneyProvider>`
+     * is mounted above — the outlet reads the runtime from context in that
+     * case. Explicit prop overrides context, so one outlet can reach a
+     * different runtime when needed.
+     */
+    readonly runtime?: JourneyRuntime;
+    readonly instanceId: InstanceId;
+    /**
+     * Module descriptors the outlet resolves step components against.
+     * Optional — when omitted, the outlet pulls the descriptors the runtime
+     * was constructed with (the common case).
+     */
+    readonly modules?: Readonly<Record<string, ModuleDescriptor<any, any, any, any>>>;
+    readonly loadingFallback?: ReactNode;
+    readonly onFinished?: (outcome: TerminalOutcome) => void;
+    readonly onStepError?: (err: unknown, ctx: {
+        step: JourneyStep;
+    }) => JourneyStepErrorPolicy;
+    /**
+     * Cap on `retry` responses before the outlet falls back to `abort`. The
+     * counter increments on every retry from `onStepError` and is never reset,
+     * so a step that causes a downstream step to also throw cannot bypass the
+     * cap by bumping the step token. Default: 2.
+     */
+    readonly retryLimit?: number;
+    /**
+     * Rendered when the current step points at a module/entry that is not
+     * registered with the runtime. Defaults to a plain red notice.
+     */
+    readonly notFoundComponent?: ComponentType<JourneyOutletNotFoundProps>;
+    /**
+     * Rendered when a step component throws. Defaults to a plain red notice
+     * with the error message. Receives the raw error so shells can route it
+     * through their own reporting.
+     */
+    readonly errorComponent?: ComponentType<JourneyOutletErrorProps>;
+}
+
+export { JourneyPersistence }
+
+/**
+ * Provides the journey runtime to descendant `<JourneyOutlet>` nodes, and
+ * composes over `<ModuleExitProvider>` so module hosts (`<ModuleTab>`,
+ * `<ModuleRoute>`, anything using `useModuleExit`) see the shell's
+ * `onModuleExit` dispatcher without needing a second provider.
+ *
+ * Existing journey consumers do not need to change — `onModuleExit` keeps
+ * firing for every module exit emitted outside a journey step.
+ */
+export declare function JourneyProvider(props: JourneyProviderProps): ReactNode;
+
+export declare interface JourneyProviderProps {
+    readonly runtime: JourneyRuntime;
+    readonly onModuleExit?: JourneyProviderValue["onModuleExit"];
+    readonly children: ReactNode;
+}
+
+/**
+ * Shell-level context read by `<JourneyOutlet>` so callers don't have to
+ * thread `runtime` through every container that hosts a journey.
+ *
+ * `onModuleExit` is still surfaced here for backward compatibility with
+ * consumers that introspect the provider value. The actual dispatch now
+ * flows through `<ModuleExitProvider>` from `@modular-react/react`, which
+ * `<JourneyProvider>` mounts automatically. Prefer consuming
+ * `useModuleExit` / `useModuleExitDispatcher` from the react package
+ * directly in new code.
+ */
+export declare interface JourneyProviderValue {
+    /** Journey runtime — usually `manifest.journeys`. */
+    readonly runtime: JourneyRuntime;
+    /**
+     * Optional fallback invoked by `<ModuleTab>` / `<ModuleRoute>` after any
+     * local `onExit` prop has run. Wiring this at the provider level gives a
+     * shell global telemetry / tab-close forwarding without threading the
+     * callback through every host.
+     */
+    readonly onModuleExit?: (event: ModuleExitEvent) => void;
+}
+
+export declare interface JourneyRegisterOptions<TState = unknown, TInput = unknown> {
+    /**
+     * Fires after every transition. Registration-level hook runs after the
+     * definition-level `onTransition`. Useful for shell telemetry that
+     * doesn't belong in journey authoring code.
+     */
+    onTransition?: (ev: TransitionEvent_2) => void;
+    /**
+     * Fires when the journey reaches a `{ complete }` transition. Runs after
+     * the definition-level `onComplete` (both fire). Use for shell-level
+     * completion analytics.
+     */
+    onComplete?: (ctx: TerminalCtx<TState>, result: unknown) => void;
+    /**
+     * Fires when the journey aborts — either via a `{ abort }` transition, a
+     * thrown transition 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. When set, this handler supplies the transition
+     * result (typically `{ abort }`). When absent, the definition's handler
+     * is used. Use to swap out abandon behaviour for a specific deployment
+     * (e.g. a tab-close workflow that completes instead of aborting).
+     */
+    onAbandon?: (ctx: AbandonCtx<ModuleTypeMap, TState>) => TransitionResult<ModuleTypeMap, TState>;
+    /**
+     * Layered on top of the definition-level `onHydrate` — runs **after** the
+     * definition transforms the blob. Useful for shell-level migration of
+     * fields that the journey author doesn't know about (e.g. redacting
+     * environment-specific identifiers on load).
+     */
+    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.
+     */
+    onError?: (err: unknown, ctx: {
+        step: JourneyStep | null;
+    }) => void;
+    /**
+     * Optional. Without it, 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 or idempotent
+     * `start` (same input → same `instanceId`).
+     *
+     * Typed against both `TState` (for `load` / `save` payloads) and the
+     * journey's `TInput` (for `keyFor`) — pass a typed adapter built with
+     * {@link defineJourneyPersistence} to get end-to-end checking.
+     */
+    persistence?: JourneyPersistence<TState, TInput>;
+    /**
+     * Maximum number of entries to keep in `history` (and the matching
+     * `rollbackSnapshots`). Oldest entries are dropped once the cap is
+     * exceeded. Omit — or pass `0` or a negative number — for unbounded
+     * history (the default).
+     *
+     * **Caveat with `allowBack`.** A cap smaller than the deepest
+     * back-enabled chain will silently break `goBack` past the trim
+     * point — the rollback snapshot that `goBack` would restore is among
+     * the dropped entries. Treat `maxHistory` as "prune old entries that
+     * no one will ever navigate back to" rather than a hard window on
+     * `goBack` distance. If an app needs both back-navigation and a tight
+     * cap, size the cap to at least the longest user-reachable back chain.
+     */
+    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 is tagged with
+     * `action: { kind: "journey-start", journeyId, buildInput }`; the
+     * shell's navbar dispatcher starts the journey on click.
+     *
+     * Typed against the journey's `TInput` so `buildInput` returns the
+     * right shape end-to-end. Apps with a narrowed `TNavItem` should also
+     * pass a `buildNavItem` adapter on `journeysPlugin` to reshape the
+     * default item into the app's narrowed type.
+     */
+    nav?: JourneyNavContribution<TInput>;
+}
+
+export { JourneyRuntime }
+
+export declare interface JourneyRuntimeOptions {
+    readonly debug?: boolean;
+    /**
+     * Module descriptors keyed by id — the runtime needs them to resolve
+     * `allowBack` mode ('preserve-state' | 'rollback' | false) at goBack time.
+     * When omitted, `goBack` falls back to 'preserve-state' for any journey
+     * transition that opts in via `allowBack: true`.
+     */
+    readonly modules?: Readonly<Record<string, ModuleDescriptor<any, any, any, any>>>;
+}
+
+/**
+ * Creates the journeys plugin. Pass to `registry.use(journeysPlugin())` to
+ * enable journey registration and outlet rendering without the runtime
+ * packages depending on `@modular-react/journeys` directly.
+ *
+ * The plugin:
+ *   - contributes `registerJourney(...)` onto the registry (type-safe)
+ *   - validates contracts against registered modules at resolve time
+ *   - produces a `JourneyRuntime` on `manifest.extensions.journeys` (also
+ *     surfaced as the `manifest.journeys` convenience alias)
+ *   - wraps the provider stack in `<JourneyProvider runtime={...} />`
+ *
+ * **Instantiate per registry.** The returned object closes over a
+ * journey-registration list; passing the same instance to two
+ * `createRegistry()` calls causes them to share that list. Call
+ * `journeysPlugin()` once per registry.
+ */
+export declare function journeysPlugin<TNavItem extends NavigationItemBase = JourneyDefaultNavItem>(options?: JourneysPluginOptions<TNavItem>): RegistryPlugin<"journeys", JourneysPluginExtension, JourneyRuntime>;
+
+/**
+ * Methods the journeys plugin contributes to the registry. Registered
+ * plugins type-intersect with the base `ModuleRegistry` so shells call
+ * `registry.registerJourney(...)` with full type support.
+ */
+export declare interface JourneysPluginExtension {
+    /**
+     * Register a journey definition. The structural shape is validated
+     * immediately (missing `id` / `version` / `transitions` etc.);
+     * module-level contracts are validated at `resolveManifest()` /
+     * `resolve()` time.
+     *
+     * `options.persistence` is typed against the journey's state, and
+     * `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;
+}
+
+export declare interface JourneysPluginOptions<TNavItem extends NavigationItemBase = JourneyDefaultNavItem> {
+    /**
+     * Enable verbose transition / rollback logging in the runtime. Defaults to
+     * `false`; plugins propagate the registry-level debug flag when set.
+     */
+    readonly debug?: boolean;
+    /**
+     * Forwarded onto `<JourneyProvider>` as the shell-wide `onModuleExit`
+     * handler. Use it as a default place to close tabs / forward analytics
+     * when a module exit isn't consumed by an explicit prop.
+     */
+    readonly onModuleExit?: (event: {
+        readonly moduleId: string;
+        readonly entry: string;
+        readonly exit: string;
+        readonly output: unknown;
+        readonly tabId?: string;
+    }) => void;
+    /**
+     * Optional adapter that reshapes the plugin's default nav item into the
+     * app's narrowed `TNavItem`. Apps that use a typed `NavigationItem`
+     * alias (typed label union, typed action union, typed meta bag) should
+     * supply this so contributed items land in `manifest.navigation` with
+     * the correct narrowed type. When omitted, the plugin emits items as
+     * {@link JourneyDefaultNavItem} and the framework widens them to
+     * `TNavItem` at the assembly boundary.
+     */
+    readonly buildNavItem?: JourneyNavItemBuilder<TNavItem>;
+}
+
+export { JourneyStatus }
+
+export { JourneyStep }
+
+export declare type JourneyStepErrorPolicy = "abort" | "retry" | "ignore";
+
+/**
+ * Aggregated error thrown when one or more registered journeys reference
+ * module ids, entry names, or exit names that do not exist (or that
+ * disagree on `allowBack`). Mirrors the style of core's
+ * `validateDependencies` — accumulate all issues, throw once.
+ */
+export declare class JourneyValidationError extends Error {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+
+export { MaybePromise }
+
+/**
+ * `SyncJourneyPersistence` augmented with test-only inspection helpers
+ * (`size`, `entries`, `clear`). Methods are sync (no `MaybePromise`) so
+ * tests can `expect(store.load(k)).toEqual(blob)` without awaiting, and
+ * the value is still assignable to `JourneyPersistence<TState, TInput>`
+ * for `registerJourney({ persistence })`.
+ */
+export declare interface MemoryPersistence<TInput, TState> extends SyncJourneyPersistence<TState, TInput> {
+    /** Number of entries currently stored. */
+    readonly size: () => number;
+    /** Snapshot of all `[key, blob]` pairs. Each blob is cloned if cloning is enabled. */
+    readonly entries: () => ReadonlyArray<readonly [string, SerializedJourney<TState>]>;
+    /** Drop all entries. */
+    readonly clear: () => void;
+}
+
+export declare interface MemoryPersistenceOptions<TInput, TState> {
+    /** Same contract as `WebStoragePersistenceOptions.keyFor`. */
+    readonly keyFor: (ctx: {
+        journeyId: string;
+        input: TInput;
+    }) => string;
+    /**
+     * Optional seed entries. Handy for tests that want the runtime to find a
+     * pre-persisted journey on first `start()` without walking through the
+     * flow to produce the blob.
+     */
+    readonly initial?: Iterable<readonly [string, SerializedJourney<TState>]>;
+    /**
+     * When true (default), stored blobs are deep-cloned on both `save` and
+     * `load` so callers mutating the returned object can't corrupt the
+     * backing store. Set to `false` to skip the clone in hot test loops
+     * where you've verified nobody mutates the blob.
+     */
+    readonly clone?: boolean;
+}
+
+/**
+ * Host for a single module instance rendered outside any route — in a tab,
+ * modal, or panel. Default exit behavior delegates to the `onExit` callback
+ * provided by the shell; the module itself stays journey-unaware.
+ */
+export declare function ModuleTab<TInput = unknown>(props: ModuleTabProps<TInput>): ReactNode;
+
+/**
+ * Exit event fired by a module rendered inside a `<ModuleTab>`.
+ *
+ * Alias for {@link ModuleExitEvent} from `@modular-react/react` — kept as a
+ * named export for the workspace-tab entry point so existing imports keep
+ * compiling. Both types have the same shape.
+ */
+export declare type ModuleTabExitEvent = ModuleExitEvent;
+
+export declare interface ModuleTabProps<TInput = unknown> {
+    /** Full module descriptor — the shell looks this up by id. */
+    readonly module: ModuleDescriptor<any, any, any, any>;
+    /**
+     * Entry point name on the module. If omitted and the module exposes
+     * exactly one entry, that entry is used automatically. If the module
+     * exposes several entries, the name must be supplied — passing an
+     * unknown name renders an error notice. If `entry` is omitted and the
+     * module has no entry points, the component falls back to the legacy
+     * `component` field; passing `entry` to such a module instead renders
+     * the error notice so misconfiguration is surfaced.
+     */
+    readonly entry?: string;
+    readonly input?: TInput;
+    /** Opaque tab id threaded through to `onExit` for the shell to close it. */
+    readonly tabId?: string;
+    /**
+     * Called when the module emits an exit. Runs *before* the provider's
+     * global `onExit` dispatcher (via `<ModuleExitProvider>`, typically
+     * composed under `<JourneyProvider>`), so the shell can close the tab
+     * first and let the provider hook forward to analytics / routing.
+     */
+    readonly onExit?: (event: ModuleTabExitEvent) => void;
+}
+
+export { ModuleTypeMap }
+
+/** 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 { SerializedJourney }
+
+export { StepSpec }
+
+/**
+ * Narrowed variant of {@link JourneyPersistence} whose methods are
+ * guaranteed synchronous — `load` returns `SerializedJourney<TState> | null`
+ * (not `MaybePromise<…>`), `save`/`remove` return `void` (not
+ * `MaybePromise<void>`). Stock adapters return this shape so direct
+ * `.load(key)` callers don't need to discriminate sync vs async or cast
+ * away the promise half of the union.
+ *
+ * Structurally assignable to `JourneyPersistence<TState, TInput>`, so the
+ * value can still be passed to `registerJourney({ persistence })` without
+ * widening.
+ */
+export declare interface SyncJourneyPersistence<TState, TInput = unknown> {
+    readonly keyFor: (ctx: {
+        journeyId: string;
+        input: TInput;
+    }) => string;
+    readonly load: (key: string) => SerializedJourney<TState> | null;
+    readonly save: (key: string, blob: SerializedJourney<TState>) => void;
+    readonly remove: (key: string) => void;
+}
+
+export { TerminalCtx }
+
+export { TerminalOutcome }
+
+export { TransitionEvent_2 as TransitionEvent }
+
+export { TransitionMap }
+
+export { TransitionResult }
+
+/**
+ * Thrown when `runtime.start()` / `runtime.hydrate()` is called with a
+ * journey id that is not registered. Distinct class so shells can
+ * discriminate "this journey is gone after an upgrade, drop the tab"
+ * from transient or validation failures.
+ */
+export declare class UnknownJourneyError extends Error {
+    readonly journeyId: string;
+    constructor(journeyId: string, registered: readonly string[]);
+}
+
+/** Read the current provider value, or `null` when none is mounted. */
+export declare function useJourneyContext(): JourneyProviderValue | null;
+
+export declare function validateJourneyContracts(journeys: readonly RegisteredJourney[], modules: readonly ModuleDescriptor<any, any, any, any>[]): void;
+
+/**
+ * Shallow sanity check on a journey definition's own shape. Use this for
+ * authoring ergonomics; structural contract checks live in
+ * {@link validateJourneyContracts}.
+ */
+export declare function validateJourneyDefinition(def: AnyJourneyDefinition): readonly string[];
+
+export declare interface WebStoragePersistenceOptions<TInput> {
+    /**
+     * Compute the persistence key from the journey id and starting input.
+     * Must be deterministic — `runtime.start()` probes this key to find an
+     * existing instance and achieve idempotency.
+     */
+    readonly keyFor: (ctx: {
+        journeyId: string;
+        input: TInput;
+    }) => string;
+    /**
+     * The `Storage` instance to read from and write to. Accepts either a
+     * direct reference or a lazy getter; the getter is invoked on every
+     * call, which keeps SSR safe (the default returns `null` when
+     * `localStorage` is not defined on the global).
+     *
+     * Defaults to `globalThis.localStorage` (or `null` under SSR) when
+     * omitted or explicitly `undefined`. Pass `sessionStorage` for
+     * tab-scoped persistence, `null` to force the SSR no-op path, or any
+     * `Storage`-shaped stub for custom backends.
+     */
+    readonly storage?: Storage | null | (() => Storage | null);
+}
+
+export { }