@modular-vue/journeys 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,996 @@
1
+ import { Component, ComputedRef, InjectionKey, MaybeRefOrGetter, PropType, ShallowRef, VNode } from "vue";
2
+ import { ModuleExitEvent, ModuleExitHandler } from "@modular-vue/vue";
3
+ import { AbandonCtx, AnnotatedTransitionHandler, AnyJourneyDefinition, ChildOutcome, EntryExitWildcardMap, EntryInputOf, EntryNamesOf, EntryTransitions, ExitCtx, ExitNamesOf, ExitNamesPairedWithEntry, ExitOnlyWildcardMap, ExitOutputOf, InstanceId, InstanceId as InstanceId$1, InvokeSpec, JourneyDefinition, JourneyDefinition as JourneyDefinition$1, JourneyDefinitionSummary, JourneyHandle, JourneyHandle as JourneyHandle$1, JourneyHydrationError, JourneyInstance, JourneyInstance as JourneyInstance$1, JourneyNavContribution, JourneyNavContribution as JourneyNavContribution$1, JourneyPersistence, JourneyRegisterOptions, JourneyRegisterOptions as JourneyRegisterOptions$1, JourneyRuntime, JourneyRuntime as JourneyRuntime$1, JourneyRuntimeOptions, JourneyStatus, JourneyStep, JourneyStep as JourneyStep$1, JourneyStepFor, JourneySync, JourneySyncAction, JourneySyncCallbackCtx, JourneySyncOptions, JourneySyncOptions as JourneySyncOptions$1, JourneySyncPort, JourneySyncPort as JourneySyncPort$1, JourneySystemAbortReason, JourneySystemAbortReasonCode, JourneyValidationError, MaybePromise, MemoryPersistence, MemoryPersistenceOptions, ModuleTypeMap, ParentLink, PendingInvoke, RegisteredJourney, ResumeBounceCounter, ResumeHandler, ResumeMap, SelectModuleCases, SelectModuleCasesPartial, SerializedJourney, StepRef, StepSpec, SyncJourneyPersistence, TerminalCtx, TerminalOutcome, TerminalOutcome as TerminalOutcome$1, TerminalSentinel, TransitionEvent, TransitionMap, TransitionResult, UnknownJourneyError, WebStoragePersistenceOptions, WildcardEntryInputOf, WildcardEntryNamesOf, WildcardExitNamesOf, WildcardExitOutputForEntry, WildcardExitOutputOf, WildcardTransitionMap, createJourneyRuntime, createJourneySync, createMemoryJourneySyncPort, createMemoryPersistence, createWebStoragePersistence, defaultStepPath, defineJourney, defineJourneyHandle, defineJourneyPersistence, defineTransition, invoke, isAnnotatedTransition, isTerminalSentinel, journeyStepPath, resolveJourneySyncAction, selectModule, selectModuleOrDefault, validateJourneyContracts, validateJourneyDefinition, validateJourneyGraph } from "@modular-frontend/journeys-engine";
4
+ import { ExitFn, ExitPointMap, ExitPointSchema, JourneyRuntime as JourneyRuntime$2, ModuleDescriptor, ModuleTypeMap as ModuleTypeMap$1, NavigationItemBase, RegistryPlugin, RuntimeMountAdapter, SemverParseError, UiComponent, compareVersions, isJourneySystemAbort, satisfies } from "@modular-frontend/core";
5
+
6
+ //#region src/provider.d.ts
7
+ /**
8
+ * Shell-level context read by `<JourneyOutlet>` (PR-31) and the instance
9
+ * composables so callers don't have to thread `runtime` through every
10
+ * container that hosts a journey. Analog of the React `JourneyContext` value.
11
+ *
12
+ * `onModuleExit` is still surfaced here for consumers that introspect the
13
+ * provider value. The actual dispatch flows through `<ModuleExitProvider>`
14
+ * from `@modular-vue/vue`, which `<JourneyProvider>` mounts automatically.
15
+ * Prefer consuming `useModuleExit` / `useModuleExitDispatcher` from the vue
16
+ * package directly in new code.
17
+ */
18
+ interface JourneyProviderValue {
19
+ /** Journey runtime — usually `manifest.journeys`. */
20
+ readonly runtime: JourneyRuntime$1;
21
+ /**
22
+ * Optional fallback invoked by module hosts (`<ModuleRoute>`, tabs) after
23
+ * any local `onExit` prop has run. Wiring this at the provider level gives a
24
+ * shell global telemetry / tab-close forwarding without threading the
25
+ * callback through every host.
26
+ */
27
+ readonly onModuleExit?: (event: ModuleExitEvent) => void;
28
+ }
29
+ /**
30
+ * Injection key holding the current {@link JourneyProviderValue}, or `null`
31
+ * when no `<JourneyProvider>` is mounted. Exported so tests and advanced hosts
32
+ * can provide the context directly.
33
+ */
34
+ declare const journeyKey: InjectionKey<JourneyProviderValue>;
35
+ /**
36
+ * Provides the journey runtime to descendant journey hosts, and composes over
37
+ * `<ModuleExitProvider>` so module hosts (`<ModuleRoute>`, anything using
38
+ * `useModuleExit`) see the shell's `onModuleExit` dispatcher without needing a
39
+ * second provider.
40
+ *
41
+ * Authored with `defineComponent` + a render function (no SFC compiler in the
42
+ * package build; see decision D4). The `runtime` is provided by identity at
43
+ * setup — matching the modules / navigation contexts (PR-10), it is resolved
44
+ * once from the manifest and does not swap on the same mount, and it is left
45
+ * un-proxied so identity checks against `manifest.journeys` hold. The
46
+ * `onModuleExit` handler is forwarded through the live `props` into
47
+ * `<ModuleExitProvider>` on every render, and the provided context value reads
48
+ * it through a getter, so a swapped handler reaches both descendant hosts and
49
+ * consumers that introspect `useJourneyContext().onModuleExit` (parity with the
50
+ * React provider, which rebuilds its value object each render).
51
+ *
52
+ * Existing journey consumers do not need to change — `onModuleExit` keeps
53
+ * firing for every module exit emitted outside a journey step.
54
+ */
55
+ declare const JourneyProvider: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
56
+ /** Journey runtime — usually `manifest.journeys`. */runtime: {
57
+ type: PropType<JourneyRuntime$1>;
58
+ required: true;
59
+ }; /** Shell-wide fallback dispatcher for module exits fired outside a step. */
60
+ onModuleExit: {
61
+ type: PropType<ModuleExitHandler>;
62
+ default: undefined;
63
+ };
64
+ }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
65
+ [key: string]: any;
66
+ }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
67
+ /** Journey runtime — usually `manifest.journeys`. */runtime: {
68
+ type: PropType<JourneyRuntime$1>;
69
+ required: true;
70
+ }; /** Shell-wide fallback dispatcher for module exits fired outside a step. */
71
+ onModuleExit: {
72
+ type: PropType<ModuleExitHandler>;
73
+ default: undefined;
74
+ };
75
+ }>> & Readonly<{}>, {
76
+ onModuleExit: ModuleExitHandler;
77
+ }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
78
+ /** Read the current provider value, or `null` when none is mounted. */
79
+ declare function useJourneyContext(): JourneyProviderValue | null;
80
+ //#endregion
81
+ //#region src/use-journey-state.d.ts
82
+ /**
83
+ * Sugar over {@link useJourneyInstance}: returns a `ComputedRef` of the
84
+ * instance's `state` (or `null` when the runtime / id / instance is
85
+ * unavailable). `TState` is the journey's state type — pass it at the call
86
+ * site.
87
+ *
88
+ * The React analog returns a plain `TState | null`; the Vue port returns a
89
+ * `ComputedRef` so it stays reactive in templates and `watch` (the PR-23
90
+ * convention for reactive-source composables). Read `.value` at the call site.
91
+ *
92
+ * Prefer {@link useJourneyInstance} when the host needs more than `state`
93
+ * (`step` / `status` / `terminalPayload`).
94
+ */
95
+ declare function useJourneyState<TState>(instanceId: MaybeRefOrGetter<InstanceId$1 | null>): ComputedRef<TState | null>;
96
+ /**
97
+ * Subscribe to a journey instance and return a `ShallowRef` of its full
98
+ * snapshot (`status`, `step`, `state`, `terminalPayload`, …), or `null` when
99
+ * no `<JourneyProvider>` is mounted or the id is unknown. Tearing-free via the
100
+ * `shallowRef` bridge in {@link useInstanceSnapshot}. The primitive of which
101
+ * {@link useJourneyState} is sugar; symmetric with
102
+ * {@link useActiveLeafJourneyInstance} for the leaf-walking case.
103
+ */
104
+ declare function useJourneyInstance(instanceId: MaybeRefOrGetter<InstanceId$1 | null>): ShallowRef<JourneyInstance$1 | null>;
105
+ /**
106
+ * Sugar over {@link useActiveLeafJourneyInstance}: returns a `ComputedRef` of
107
+ * the leaf instance's `state` as `TState`. `.value` is `null` when no
108
+ * provider, the root id is unknown, or the leaf has been forgotten.
109
+ *
110
+ * Prefer {@link useActiveLeafJourneyInstance} when the leaf can be any of
111
+ * several journeys — typing this composable as `<ParentState | ChildState>`
112
+ * leaves the caller without a discriminator, whereas the instance form gives a
113
+ * typed `inst.journeyId` to switch on.
114
+ */
115
+ declare function useActiveLeafJourneyState<TState>(rootInstanceId: MaybeRefOrGetter<InstanceId$1 | null>): ComputedRef<TState | null>;
116
+ /**
117
+ * Walks `activeChildId` from `rootInstanceId` down to the deepest descendant
118
+ * and returns a `ShallowRef` of that leaf's full `JourneyInstance`. The
119
+ * recommended primitive when the host doesn't know the leaf's depth (a parent
120
+ * that may or may not be in an invoked sub-flow) — pair with `inst.journeyId`
121
+ * as a discriminator instead of typing the state composable as a union and
122
+ * asserting manually. Re-subscribes as the chain grows (parent invokes a
123
+ * child, grandchild starts) or shrinks (child terminates and parent resumes).
124
+ *
125
+ * `.value` is `null` under the same conditions as {@link useJourneyInstance}.
126
+ */
127
+ declare function useActiveLeafJourneyInstance(rootInstanceId: MaybeRefOrGetter<InstanceId$1 | null>): ShallowRef<JourneyInstance$1 | null>;
128
+ //#endregion
129
+ //#region src/instance-hooks.d.ts
130
+ /**
131
+ * Subscribe to a single instance and return a `ShallowRef` of its current
132
+ * snapshot, or `null` when runtime / id is missing or the instance has been
133
+ * forgotten. The Vue analog of the React `useInstanceSnapshot` (which uses
134
+ * `useSyncExternalStore`): a `watchEffect` seeds the ref, subscribes, and
135
+ * re-subscribes whenever `instanceId` changes.
136
+ *
137
+ * `instanceId` accepts a plain value, a ref, or a getter. Reactive ids are
138
+ * the point of the leaf-walking composables: `useActiveLeafJourneyInstance`
139
+ * feeds a `ComputedRef` leaf id here, so the snapshot re-subscribes as the
140
+ * active chain grows (parent invokes a child) or shrinks (child terminates).
141
+ * The subscribe callback reads the *current* id so an in-flight notification
142
+ * that arrives after an id swap still resolves against the live instance.
143
+ *
144
+ * The `watchEffect` uses the default (pre) flush: the initial subscription is
145
+ * established synchronously at setup, runtime events push snapshots into the
146
+ * `shallowRef` synchronously (matching React's tearing-free reads), and only
147
+ * re-subscription on an id change is deferred to the next tick — so a
148
+ * changing-leaf test awaits `nextTick()` before the swap is observed.
149
+ */
150
+ declare function useInstanceSnapshot(runtime: JourneyRuntime$1 | null, instanceId: MaybeRefOrGetter<InstanceId$1 | null>): ShallowRef<JourneyInstance$1 | null>;
151
+ /**
152
+ * Walk `activeChildId` from `rootId` down to the deepest descendant, returning
153
+ * a `ShallowRef` of the full chain. Subscribes to every instance in the chain
154
+ * and re-subscribes as the chain grows / shrinks. Pass `enabled: false` to
155
+ * short-circuit the walk (collapses to `[rootId]`) — used by the outlet's
156
+ * `leafOnly` opt-out (PR-31). Null `runtime` / `rootId` yields an empty chain
157
+ * so callers can invoke this composable unconditionally even before a runtime
158
+ * is mounted.
159
+ *
160
+ * The dynamic per-instance subscriptions are managed by hand (as in the React
161
+ * source) rather than through Vue reactivity, since they rewire on runtime
162
+ * events, not on tracked dependencies. The `watchEffect` only re-runs — tearing
163
+ * down and rebuilding the whole chain — when `rootId` or `enabled` change.
164
+ */
165
+ declare function useCallChain(runtime: JourneyRuntime$1 | null, rootId: MaybeRefOrGetter<InstanceId$1 | null>, enabled: MaybeRefOrGetter<boolean>): ShallowRef<readonly InstanceId$1[]>;
166
+ /**
167
+ * Last id in the active chain — `rootId` when no child is in flight, `null`
168
+ * when runtime / rootId are missing. Returns a `ComputedRef` that tracks the
169
+ * chain, so feeding it to {@link useInstanceSnapshot} re-subscribes the
170
+ * snapshot as the leaf moves.
171
+ */
172
+ declare function useLeafId(runtime: JourneyRuntime$1 | null, rootId: MaybeRefOrGetter<InstanceId$1 | null>, enabled: MaybeRefOrGetter<boolean>): ComputedRef<InstanceId$1 | null>;
173
+ //#endregion
174
+ //#region src/mount-adapter.d.ts
175
+ /**
176
+ * Adapt a {@link JourneyRuntime} to the generic
177
+ * {@link RuntimeMountAdapter} shape so other packages can embed journeys
178
+ * without depending on this package directly. Today the only consumer is
179
+ * `@modular-vue/compositions` (zones with `kind: "journey"`):
180
+ *
181
+ * ```ts
182
+ * import { createJourneyMountAdapter } from "@modular-vue/journeys";
183
+ *
184
+ * const manifest = registry.resolveManifest();
185
+ * manifest.extensions.compositions.registerMountAdapter(
186
+ * "journey",
187
+ * createJourneyMountAdapter(manifest.extensions.journeys),
188
+ * );
189
+ * ```
190
+ *
191
+ * The wiring happens once after `resolveManifest()` and before mounting the
192
+ * app, so the composition outlet finds the adapter the first time a zone
193
+ * returns a `kind: "journey"` resolution. If the wiring is omitted, the
194
+ * zone renders its `errorComponent` with a clear "no adapter registered"
195
+ * message instead of throwing (see `CompositionOutlet`).
196
+ *
197
+ * The Vue analog of `@modular-react/journeys`'s `createJourneyMountAdapter`.
198
+ *
199
+ * Deviation from the React source, and why: React returns the bare
200
+ * `JourneyOutlet` as `Outlet` and lets it read the journey runtime from the
201
+ * `<JourneyProvider>` context that the journeys plugin threads app-wide. The
202
+ * Vue `<CompositionOutlet>` renders `adapter.Outlet` with only
203
+ * `{ instanceId, loadingFallback }` (no `runtime`), so the Vue adapter binds
204
+ * the runtime it was handed into a thin wrapper component. This makes the
205
+ * adapter self-contained — it mounts instances against exactly the runtime
206
+ * passed to `createJourneyMountAdapter`, whether or not a `<JourneyProvider>`
207
+ * sits above the composition outlet — rather than depending on an ambient
208
+ * context that must happen to hold the same runtime.
209
+ */
210
+ declare function createJourneyMountAdapter(runtime: JourneyRuntime$1): RuntimeMountAdapter;
211
+ //#endregion
212
+ //#region src/outlet.d.ts
213
+ type JourneyStepErrorPolicy = "abort" | "retry" | "ignore";
214
+ interface JourneyOutletNotFoundProps {
215
+ readonly moduleId: string;
216
+ readonly entry: string;
217
+ }
218
+ interface JourneyOutletErrorProps {
219
+ readonly moduleId: string;
220
+ readonly error: unknown;
221
+ }
222
+ /**
223
+ * Renders the current step of a journey instance. Host-agnostic — works in a
224
+ * tab, modal, route element, or plain `<div>`. On unmount while active, the
225
+ * instance is abandoned (deferred by a microtask so a same-tick handoff to a
226
+ * sibling outlet — outlet A unmounts, outlet B mounts against the same instance
227
+ * — does not tear the instance down: the deferred check consults the record's
228
+ * listener count and skips `end()` when another outlet is still subscribed).
229
+ *
230
+ * The Vue analog of the React `<JourneyOutlet>`. Authored with `defineComponent`
231
+ * + a render function (no SFC compiler in the package build; see decision D4).
232
+ * The instance snapshots come from the reactive `useInstanceSnapshot` /
233
+ * `useLeafId` composables (PR-30), so the outlet re-renders as the active call
234
+ * chain shifts (parent invokes a child, child terminates) and as the leaf's own
235
+ * step advances. Error-message prefixes are `[@modular-vue/journeys]`.
236
+ */
237
+ declare const JourneyOutlet: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
238
+ /**
239
+ * Runtime to drive the outlet against. Optional when a `<JourneyProvider>`
240
+ * is mounted above — the outlet reads the runtime from context in that
241
+ * case. Explicit prop overrides context, so one outlet can reach a
242
+ * different runtime when needed.
243
+ */
244
+ runtime: {
245
+ type: PropType<JourneyRuntime$1>;
246
+ default: undefined;
247
+ };
248
+ instanceId: {
249
+ type: PropType<InstanceId$1>;
250
+ required: true;
251
+ };
252
+ /**
253
+ * Module descriptors the outlet resolves step components against. Optional —
254
+ * when omitted, the outlet pulls the descriptors the runtime was constructed
255
+ * with (the common case).
256
+ */
257
+ modules: {
258
+ type: PropType<Readonly<Record<string, ModuleDescriptor<any, any, any, any>>>>;
259
+ default: undefined;
260
+ }; /** Rendered while the instance is in `loading` status. */
261
+ loadingFallback: {
262
+ type: PropType<VNode | (() => VNode)>;
263
+ default: undefined;
264
+ };
265
+ onFinished: {
266
+ type: PropType<(outcome: TerminalOutcome$1) => void>;
267
+ default: undefined;
268
+ };
269
+ onStepError: {
270
+ type: PropType<(err: unknown, ctx: {
271
+ step: JourneyStep$1;
272
+ }) => JourneyStepErrorPolicy>;
273
+ default: undefined;
274
+ };
275
+ /**
276
+ * When `false`, the outlet renders the instance you handed it directly, even
277
+ * if it has a child journey in flight. Set this when you compose two outlets
278
+ * to render parent and child side-by-side. When `true` (the default), the
279
+ * outlet walks the active call chain down to the leaf and renders the leaf.
280
+ */
281
+ leafOnly: {
282
+ type: BooleanConstructor;
283
+ default: boolean;
284
+ };
285
+ /**
286
+ * Cap on `retry` responses before the outlet falls back to `abort`. The
287
+ * counter increments on every retry and is never reset. Default: 2.
288
+ */
289
+ retryLimit: {
290
+ type: NumberConstructor;
291
+ default: number;
292
+ };
293
+ /**
294
+ * Rendered when the current step points at a module/entry that is not
295
+ * registered with the runtime. Defaults to a plain red notice.
296
+ */
297
+ notFoundComponent: {
298
+ type: PropType<Component>;
299
+ default: undefined;
300
+ };
301
+ /**
302
+ * Rendered when a step component throws. Defaults to a plain red notice with
303
+ * the error message. Receives the raw error so shells can route it through
304
+ * their own reporting.
305
+ */
306
+ errorComponent: {
307
+ type: PropType<Component>;
308
+ default: undefined;
309
+ };
310
+ /**
311
+ * Speculatively prefetch the chunks for entries reachable from the current
312
+ * step during idle time after mount. `"precise"` (default, alias `true`)
313
+ * reads declared `targets` from annotated handlers; `"aggressive"` preloads
314
+ * every entry referenced as a transition source or annotated target;
315
+ * `false` opts out. No effect for eager entries; SSR is a no-op.
316
+ */
317
+ preload: {
318
+ type: PropType<boolean | "precise" | "aggressive">;
319
+ default: string;
320
+ };
321
+ }>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
322
+ [key: string]: any;
323
+ }> | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
324
+ /**
325
+ * Runtime to drive the outlet against. Optional when a `<JourneyProvider>`
326
+ * is mounted above — the outlet reads the runtime from context in that
327
+ * case. Explicit prop overrides context, so one outlet can reach a
328
+ * different runtime when needed.
329
+ */
330
+ runtime: {
331
+ type: PropType<JourneyRuntime$1>;
332
+ default: undefined;
333
+ };
334
+ instanceId: {
335
+ type: PropType<InstanceId$1>;
336
+ required: true;
337
+ };
338
+ /**
339
+ * Module descriptors the outlet resolves step components against. Optional —
340
+ * when omitted, the outlet pulls the descriptors the runtime was constructed
341
+ * with (the common case).
342
+ */
343
+ modules: {
344
+ type: PropType<Readonly<Record<string, ModuleDescriptor<any, any, any, any>>>>;
345
+ default: undefined;
346
+ }; /** Rendered while the instance is in `loading` status. */
347
+ loadingFallback: {
348
+ type: PropType<VNode | (() => VNode)>;
349
+ default: undefined;
350
+ };
351
+ onFinished: {
352
+ type: PropType<(outcome: TerminalOutcome$1) => void>;
353
+ default: undefined;
354
+ };
355
+ onStepError: {
356
+ type: PropType<(err: unknown, ctx: {
357
+ step: JourneyStep$1;
358
+ }) => JourneyStepErrorPolicy>;
359
+ default: undefined;
360
+ };
361
+ /**
362
+ * When `false`, the outlet renders the instance you handed it directly, even
363
+ * if it has a child journey in flight. Set this when you compose two outlets
364
+ * to render parent and child side-by-side. When `true` (the default), the
365
+ * outlet walks the active call chain down to the leaf and renders the leaf.
366
+ */
367
+ leafOnly: {
368
+ type: BooleanConstructor;
369
+ default: boolean;
370
+ };
371
+ /**
372
+ * Cap on `retry` responses before the outlet falls back to `abort`. The
373
+ * counter increments on every retry and is never reset. Default: 2.
374
+ */
375
+ retryLimit: {
376
+ type: NumberConstructor;
377
+ default: number;
378
+ };
379
+ /**
380
+ * Rendered when the current step points at a module/entry that is not
381
+ * registered with the runtime. Defaults to a plain red notice.
382
+ */
383
+ notFoundComponent: {
384
+ type: PropType<Component>;
385
+ default: undefined;
386
+ };
387
+ /**
388
+ * Rendered when a step component throws. Defaults to a plain red notice with
389
+ * the error message. Receives the raw error so shells can route it through
390
+ * their own reporting.
391
+ */
392
+ errorComponent: {
393
+ type: PropType<Component>;
394
+ default: undefined;
395
+ };
396
+ /**
397
+ * Speculatively prefetch the chunks for entries reachable from the current
398
+ * step during idle time after mount. `"precise"` (default, alias `true`)
399
+ * reads declared `targets` from annotated handlers; `"aggressive"` preloads
400
+ * every entry referenced as a transition source or annotated target;
401
+ * `false` opts out. No effect for eager entries; SSR is a no-op.
402
+ */
403
+ preload: {
404
+ type: PropType<boolean | "precise" | "aggressive">;
405
+ default: string;
406
+ };
407
+ }>> & Readonly<{}>, {
408
+ runtime: JourneyRuntime$1;
409
+ modules: Readonly<Record<string, ModuleDescriptor<any, any, any, any>>>;
410
+ loadingFallback: VNode<import("vue").RendererNode, import("vue").RendererElement, {
411
+ [key: string]: any;
412
+ }> | (() => VNode);
413
+ onFinished: (outcome: TerminalOutcome$1) => void;
414
+ onStepError: (err: unknown, ctx: {
415
+ step: JourneyStep$1;
416
+ }) => JourneyStepErrorPolicy;
417
+ leafOnly: boolean;
418
+ retryLimit: number;
419
+ notFoundComponent: Component;
420
+ errorComponent: Component;
421
+ preload: boolean | "precise" | "aggressive";
422
+ }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
423
+ /**
424
+ * Returns a reactive `ShallowRef` of the call stack for an outlet's instance —
425
+ * root at index 0, the active leaf at the end, intermediate parents in between.
426
+ * Useful for shells that render layered presentations (parent underneath, child
427
+ * in a modal): mount the parent outlet with `leafOnly={false}` and the child
428
+ * outlet against `chain.value[chain.value.length - 1]`. Returns a ref (not a
429
+ * plain array) per the PR-30 reactive-source convention.
430
+ */
431
+ declare function useJourneyCallStack(runtime: JourneyRuntime$1, rootId: InstanceId$1): ShallowRef<readonly InstanceId$1[]>;
432
+ //#endregion
433
+ //#region src/journey-host.d.ts
434
+ interface UseJourneyHostOptions {
435
+ /**
436
+ * Runtime to start the journey on. Optional when a `<JourneyProvider>` is
437
+ * mounted above — the composable reads the runtime from context in that case.
438
+ */
439
+ readonly runtime?: JourneyRuntime$1;
440
+ }
441
+ interface JourneyHostState {
442
+ /**
443
+ * The instance this host owns. `null` until the component is mounted — the
444
+ * journey is started from `onMounted`, so it does not exist during the first
445
+ * render. `<JourneyHost>` renders `loadingFallback` for that frame.
446
+ */
447
+ readonly instanceId: ShallowRef<InstanceId$1 | null>;
448
+ readonly instance: ShallowRef<JourneyInstance$1 | null>;
449
+ /**
450
+ * The runtime this host resolved at setup — the one `instanceId` is
451
+ * meaningful to, and the one the host's own `<JourneyOutlet>` is given.
452
+ * Already `toRaw`-unwrapped.
453
+ *
454
+ * Normally identical to whatever a `<JourneyProvider>` above you would hand
455
+ * out, so a hand-placed outlet can keep resolving from context. It is
456
+ * exposed for the case where those two could differ: a shell that swaps its
457
+ * provider value mid-flight. The host does not follow such a swap (see
458
+ * "read once, at setup"), so this is the runtime to use if you want to be
459
+ * certain you are talking about the same journey the host started.
460
+ */
461
+ readonly runtime: JourneyRuntime$1;
462
+ /**
463
+ * How many steps the user has completed — `history.length`, so `0` on the
464
+ * first step. Rewinds when the journey does.
465
+ *
466
+ * There is deliberately no `stepCount` here. The total is not knowable from
467
+ * a running instance: a journey's next step is computed by a transition
468
+ * handler from live state, so nothing short of walking the transition graph
469
+ * can count the steps ahead — and a hand-passed total is exactly the
470
+ * duplicated flow encoding this API exists to remove. Deriving it from the
471
+ * graph is tracked separately.
472
+ */
473
+ readonly stepIndex: ComputedRef<number>;
474
+ }
475
+ /**
476
+ * Own a journey instance for the lifetime of a component: start it on mount,
477
+ * end and forget it on unmount. The Vue analog of the React
478
+ * `useJourneyHost`.
479
+ *
480
+ * This is the lifecycle half of "mount a journey"; `useJourneySync` is the URL
481
+ * half, and `<JourneyOutlet>` is the rendering half. {@link JourneyHost}
482
+ * packages the first and the last together.
483
+ *
484
+ * **`handle`, `input` and `runtime` are read once, at setup**, and are
485
+ * therefore plain values rather than the `MaybeRefOrGetter` the reactive
486
+ * composables in this package take. Changing them cannot restart the journey:
487
+ * silently abandoning a half-finished flow because a prop changed is never
488
+ * what the caller meant. To run a different journey — or to run it on a
489
+ * different runtime — remount: `<JourneyHost :key="journeyId" …>`. The React
490
+ * binding pins its runtime the same way.
491
+ *
492
+ * **Start means resume, when persistence is configured.** `runtime.start()`
493
+ * with a `persistence` adapter returns the in-flight instance for the same
494
+ * `keyFor(input)` rather than minting a new one, so a host that remounts (a
495
+ * route change, a tab switch) picks the journey back up where it was. Without
496
+ * persistence every mount starts a fresh instance.
497
+ */
498
+ declare function useJourneyHost<TInput>(handle: JourneyHandle$1<string, TInput, unknown>, input: TInput, options?: UseJourneyHostOptions): JourneyHostState;
499
+ interface JourneyHostSlotProps {
500
+ readonly instanceId: InstanceId$1;
501
+ readonly instance: JourneyInstance$1;
502
+ /** See {@link JourneyHostState.stepIndex}. */
503
+ readonly stepIndex: number;
504
+ /**
505
+ * The `<JourneyOutlet>` for this instance, already built with every outlet
506
+ * attribute passed to `<JourneyHost>`. Place it inside your chrome.
507
+ */
508
+ readonly outlet: VNode;
509
+ }
510
+ /**
511
+ * Mount a journey in one line:
512
+ * `<JourneyHost :handle="checkoutHandle" :input="{ cartId }" />`.
513
+ *
514
+ * Starts the journey on mount, renders its current step, and ends + forgets
515
+ * the instance on unmount — the wrapper every journey host ends up writing.
516
+ * The Vue analog of the React `<JourneyHost>`.
517
+ *
518
+ * **Outlet props pass through as attributes.** `inheritAttrs: false` plus an
519
+ * attrs spread onto the inner `<JourneyOutlet>` means every outlet prop
520
+ * (`onFinished`, `onStepError`, `errorComponent`, `preload`, …) works on
521
+ * `<JourneyHost>` without this component re-declaring — and drifting from —
522
+ * the outlet's prop list. `loadingFallback` is the one attr the host also
523
+ * reads itself, to cover the render before the instance exists — which is why
524
+ * it has to accept both spellings; see {@link readLoadingFallback}.
525
+ *
526
+ * For chrome around the step, use the default scoped slot:
527
+ *
528
+ * ```vue
529
+ * <JourneyHost :handle="checkoutHandle" :input="{ cartId }" @finished="goToReceipt">
530
+ * <template #default="{ stepIndex, outlet }">
531
+ * <Layout title="Checkout" :step="stepIndex">
532
+ * <component :is="outlet" />
533
+ * </Layout>
534
+ * </template>
535
+ * </JourneyHost>
536
+ * ```
537
+ *
538
+ * To deep-link the steps, call `useJourneySync` in the same component — the
539
+ * host owns the instance, the sync owns the URL, and neither knows about the
540
+ * other.
541
+ *
542
+ * See {@link useJourneyHost} for the lifecycle rules (the instance is fixed
543
+ * for the host's lifetime; `start` resumes when persistence is configured).
544
+ */
545
+ declare const JourneyHost: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
546
+ handle: {
547
+ type: PropType<JourneyHandle$1<string, any, any>>;
548
+ required: true;
549
+ };
550
+ /**
551
+ * The journey's `input`. Typed `any` because a `defineComponent` prop
552
+ * list cannot carry the handle's `TInput` through — reach for
553
+ * {@link useJourneyHost} in a `<script setup>` block when you want the
554
+ * input checked against the handle.
555
+ */
556
+ input: {
557
+ type: PropType<any>;
558
+ default: undefined;
559
+ };
560
+ /**
561
+ * Runtime to start the journey on, forwarded to the outlet. Optional when
562
+ * a `<JourneyProvider>` is mounted above.
563
+ */
564
+ runtime: {
565
+ type: PropType<JourneyRuntime$1>;
566
+ default: undefined;
567
+ };
568
+ }>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
569
+ [key: string]: any;
570
+ }> | VNode<import("vue").RendererNode, import("vue").RendererElement, {
571
+ [key: string]: any;
572
+ }>[] | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
573
+ handle: {
574
+ type: PropType<JourneyHandle$1<string, any, any>>;
575
+ required: true;
576
+ };
577
+ /**
578
+ * The journey's `input`. Typed `any` because a `defineComponent` prop
579
+ * list cannot carry the handle's `TInput` through — reach for
580
+ * {@link useJourneyHost} in a `<script setup>` block when you want the
581
+ * input checked against the handle.
582
+ */
583
+ input: {
584
+ type: PropType<any>;
585
+ default: undefined;
586
+ };
587
+ /**
588
+ * Runtime to start the journey on, forwarded to the outlet. Optional when
589
+ * a `<JourneyProvider>` is mounted above.
590
+ */
591
+ runtime: {
592
+ type: PropType<JourneyRuntime$1>;
593
+ default: undefined;
594
+ };
595
+ }>> & Readonly<{}>, {
596
+ input: any;
597
+ runtime: JourneyRuntime$1;
598
+ }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
599
+ //#endregion
600
+ //#region src/use-journey-sync.d.ts
601
+ interface UseJourneySyncOptions extends JourneySyncOptions$1 {
602
+ /**
603
+ * Runtime to sync against. Optional when a `<JourneyProvider>` is mounted
604
+ * above — the composable reads the runtime from context in that case. Read
605
+ * once at setup, matching how the other composables in this package resolve
606
+ * their runtime.
607
+ */
608
+ readonly runtime?: JourneyRuntime$1;
609
+ }
610
+ /**
611
+ * Keep a journey instance and the browser URL in step, in both directions:
612
+ * the journey advances and the URL follows; the user presses Back or Forward
613
+ * and the journey follows.
614
+ *
615
+ * The reconciler itself is framework- and router-neutral and lives in
616
+ * `@modular-frontend/journeys-engine`; this composable is the Vue lifetime
617
+ * wrapper around it, and the exact analog of the React `useJourneySync`. See
618
+ * `createJourneySync` in the engine for the full semantics (push-vs-replace
619
+ * rules, what a location can and cannot select, why the design is
620
+ * event-sourced rather than a diff).
621
+ *
622
+ * Supply a {@link JourneySyncPort} for vue-router. It is the only router-aware
623
+ * code in the picture:
624
+ *
625
+ * ```ts
626
+ * const router = useRouter();
627
+ * const route = useRoute();
628
+ * const port: JourneySyncPort = {
629
+ * read: () => String(route.params.step ?? ""),
630
+ * push: (path) => void router.push({ name: "checkout", params: { step: path } }),
631
+ * replace: (path) => void router.replace({ name: "checkout", params: { step: path } }),
632
+ * go: (delta) => router.go(delta),
633
+ * subscribe: (listener) => router.afterEach(() => listener()),
634
+ * };
635
+ *
636
+ * useJourneySync(instanceId, port, { stepToPath: (step) => step.entry });
637
+ * ```
638
+ *
639
+ * Conventions:
640
+ *
641
+ * - **`instanceId` accepts a plain value, a ref, or a getter**, and may be
642
+ * `null` — the composable no-ops until an id arrives, so it can be called at
643
+ * setup before the instance exists (as it must be under `useJourneyHost`,
644
+ * which starts the journey on mount). The sync re-attaches when the id
645
+ * changes.
646
+ * - **`port` and `options` may be plain, refs, or getters.** Both are read
647
+ * through a live holder rather than re-creating the reconciler, because
648
+ * re-creating it re-runs its initial reconcile — and that reconcile
649
+ * navigates. Pass a getter when the port itself depends on reactive state.
650
+ * Two things are read once rather than live: `port.subscribe`, called when
651
+ * the sync is created (so the subscription belongs to the port current at
652
+ * that moment), and `options.stepToPath`, captured then too (the engine
653
+ * needs a stable step->path mapping to resolve already-stamped history
654
+ * frames). Both are invisible for the normal case — a port over a stable
655
+ * router with a fixed mapping — but a port that subscribes to a *different*
656
+ * source later, or a mapping that changes, will not take effect until the
657
+ * sync is re-created. `onUnresolved`/`onBlocked` remain live. Change
658
+ * `instanceId` (or remount) to re-attach.
659
+ * - **The composable never starts or ends the instance.** It only navigates
660
+ * within a journey that is already running. Pair it with
661
+ * {@link JourneyHost}, which owns the lifecycle.
662
+ */
663
+ declare function useJourneySync(instanceId: MaybeRefOrGetter<InstanceId$1 | null>, port: MaybeRefOrGetter<JourneySyncPort$1>, options?: MaybeRefOrGetter<UseJourneySyncOptions>): void;
664
+ //#endregion
665
+ //#region src/module-tab.d.ts
666
+ /**
667
+ * Exit event fired by a module rendered inside a `<ModuleTab>`.
668
+ *
669
+ * Alias for {@link ModuleExitEvent} from `@modular-vue/vue` — kept as a named
670
+ * export for the workspace-tab entry point so existing imports keep compiling.
671
+ * Both types have the same shape.
672
+ */
673
+ type ModuleTabExitEvent = ModuleExitEvent;
674
+ /**
675
+ * Host for a single module instance rendered outside any route — in a tab,
676
+ * modal, or panel. Default exit behavior delegates to the `onExit` callback
677
+ * provided by the shell; the module itself stays journey-unaware. The Vue
678
+ * analog of the React `<ModuleTab>`.
679
+ *
680
+ * Authored with `defineComponent` + a render function (no SFC compiler in the
681
+ * package build; see decision D4). The exit binding is created once at setup
682
+ * via `useModuleExit` (Vue composables must run synchronously in `setup`),
683
+ * reading the current module id / resolved entry through getters so a host that
684
+ * swaps `module`/`entry` on the same instance still emits the right event.
685
+ *
686
+ * `inheritAttrs` is disabled and `input` is read from `attrs` so the component
687
+ * can tell "no `input` prop" apart from an explicit `input={undefined}` — Vue
688
+ * collapses both to `undefined` for a *declared* prop (an explicit `undefined`
689
+ * triggers the prop default), so the presence check has to look at the raw
690
+ * attrs bag, the analog of the React source's `"input" in props`.
691
+ */
692
+ declare const ModuleTab: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
693
+ /** Full module descriptor — the shell looks this up by id. */module: {
694
+ type: PropType<ModuleDescriptor<any, any, any, any>>;
695
+ required: true;
696
+ };
697
+ /**
698
+ * Entry point name on the module. If omitted and the module exposes exactly
699
+ * one entry, that entry is used automatically. If the module exposes several
700
+ * entries, the name must be supplied — passing an unknown name renders an
701
+ * error notice. If `entry` is omitted and the module has no entry points,
702
+ * the component falls back to the legacy `component` field; passing `entry`
703
+ * to such a module instead renders the error notice so misconfiguration is
704
+ * surfaced.
705
+ */
706
+ entry: {
707
+ type: StringConstructor;
708
+ default: undefined;
709
+ }; /** Opaque tab id threaded through to `onExit` for the shell to close it. */
710
+ tabId: {
711
+ type: StringConstructor;
712
+ default: undefined;
713
+ };
714
+ /**
715
+ * Called when the module emits an exit. Runs *before* the provider's global
716
+ * `onExit` dispatcher (via `<ModuleExitProvider>`, typically composed under
717
+ * `<JourneyProvider>`), so the shell can close the tab first and let the
718
+ * provider hook forward to analytics / routing.
719
+ */
720
+ onExit: {
721
+ type: PropType<(event: ModuleTabExitEvent) => void>;
722
+ default: undefined;
723
+ };
724
+ }>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
725
+ [key: string]: any;
726
+ }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
727
+ /** Full module descriptor — the shell looks this up by id. */module: {
728
+ type: PropType<ModuleDescriptor<any, any, any, any>>;
729
+ required: true;
730
+ };
731
+ /**
732
+ * Entry point name on the module. If omitted and the module exposes exactly
733
+ * one entry, that entry is used automatically. If the module exposes several
734
+ * entries, the name must be supplied — passing an unknown name renders an
735
+ * error notice. If `entry` is omitted and the module has no entry points,
736
+ * the component falls back to the legacy `component` field; passing `entry`
737
+ * to such a module instead renders the error notice so misconfiguration is
738
+ * surfaced.
739
+ */
740
+ entry: {
741
+ type: StringConstructor;
742
+ default: undefined;
743
+ }; /** Opaque tab id threaded through to `onExit` for the shell to close it. */
744
+ tabId: {
745
+ type: StringConstructor;
746
+ default: undefined;
747
+ };
748
+ /**
749
+ * Called when the module emits an exit. Runs *before* the provider's global
750
+ * `onExit` dispatcher (via `<ModuleExitProvider>`, typically composed under
751
+ * `<JourneyProvider>`), so the shell can close the tab first and let the
752
+ * provider hook forward to analytics / routing.
753
+ */
754
+ onExit: {
755
+ type: PropType<(event: ModuleTabExitEvent) => void>;
756
+ default: undefined;
757
+ };
758
+ }>> & Readonly<{}>, {
759
+ entry: string;
760
+ tabId: string;
761
+ onExit: (event: ModuleTabExitEvent) => void;
762
+ }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
763
+ //#endregion
764
+ //#region src/use-wait-for-exit.d.ts
765
+ /**
766
+ * Exit names whose schema declares a `void` output. The named-exit form
767
+ * of {@link WaitForExitTimeoutChannel} narrows to these so a deadline
768
+ * dispatching `resolve(name)` without an output is sound. Exits that
769
+ * require a payload must use the function form
770
+ * (`fire: (resolve) => resolve("name", payload)`).
771
+ */
772
+ type VoidExitName<TExits extends ExitPointMap> = { [K in keyof TExits & string]: TExits[K] extends ExitPointSchema<infer T> ? [T] extends [void] ? K : never : never }[keyof TExits & string];
773
+ /**
774
+ * One channel that races against the others. `resolve` is the wrapped exit
775
+ * dispatcher: calling it fires the named exit if no other channel has fired
776
+ * yet, and is a no-op otherwise. The subscriber returns its own teardown,
777
+ * which the composable calls **immediately** when any channel wins (not just on
778
+ * unmount) so the losing channels stop doing wakeups between dispatch and
779
+ * unmount.
780
+ *
781
+ * @example
782
+ * ```ts
783
+ * subscribe: (resolve) => {
784
+ * const handler = (msg: WsFrame) => {
785
+ * if (msg.type === "process-ready") resolve("ready", { process: msg.payload });
786
+ * };
787
+ * ws.on("message", handler);
788
+ * return () => ws.off("message", handler);
789
+ * }
790
+ * ```
791
+ */
792
+ type WaitForExitSubscribeChannel<TExits extends ExitPointMap> = (resolve: ExitFn<TExits>) => () => void;
793
+ /**
794
+ * Periodic check that fires when the answer is ready. The interval is torn
795
+ * down the moment any channel wins, so `check` is not invoked again after
796
+ * settle. `check` itself should still cancel its own outstanding async
797
+ * work on unmount where applicable (e.g. via `AbortController`).
798
+ *
799
+ * @example
800
+ * ```ts
801
+ * poll: {
802
+ * intervalMs: 3000,
803
+ * check: async (resolve) => {
804
+ * const process = await api.getTranslationProcess(projectId);
805
+ * if (process) resolve("ready", { process });
806
+ * },
807
+ * }
808
+ * ```
809
+ */
810
+ interface WaitForExitPollChannel<TExits extends ExitPointMap> {
811
+ readonly intervalMs: number;
812
+ readonly check: (resolve: ExitFn<TExits>) => void | Promise<void>;
813
+ }
814
+ /**
815
+ * Deadline arm. The simple form fires a named exit; the function form runs
816
+ * arbitrary code (e.g. dispatches a different exit based on `input`). Pass
817
+ * `0` or a negative `ms` to disable the timeout for a render without
818
+ * conditionally calling the composable.
819
+ *
820
+ * @example
821
+ * ```ts
822
+ * // Named form — exit must have a `void` output schema.
823
+ * timeout: { ms: 60_000, fire: "timedOut" }
824
+ *
825
+ * // Function form — choose the exit (and its payload) at deadline time.
826
+ * timeout: {
827
+ * ms: 60_000,
828
+ * fire: (resolve) => resolve("failed", { reason: "deadline-exceeded" }),
829
+ * }
830
+ * ```
831
+ */
832
+ type WaitForExitTimeoutChannel<TExits extends ExitPointMap> = {
833
+ readonly ms: number;
834
+ } & ({
835
+ readonly fire: VoidExitName<TExits>;
836
+ } | {
837
+ readonly fire: (resolve: ExitFn<TExits>) => void;
838
+ });
839
+ interface WaitForExitChannels<TExits extends ExitPointMap> {
840
+ /** Push channel — websocket, SSE, push notification, server-sent intent. */
841
+ readonly subscribe?: WaitForExitSubscribeChannel<TExits>;
842
+ /** Polling fallback. Omit when the push channel is reliable. */
843
+ readonly poll?: WaitForExitPollChannel<TExits>;
844
+ /** Deadline arm. Omit when no fallback is needed. */
845
+ readonly timeout?: WaitForExitTimeoutChannel<TExits>;
846
+ }
847
+ /**
848
+ * Wait for one of several async channels to fire and dispatch a journey
849
+ * exit when the first one resolves. Encapsulates the cancellation latch,
850
+ * channel teardown, and first-wins coordination so step components stay
851
+ * declarative. The Vue analog of the React `useWaitForExit` hook.
852
+ *
853
+ * Channel callbacks (`subscribe`, `poll.check`, `timeout.fire`) and the
854
+ * `exit` dispatcher are captured live, so changing their identity between
855
+ * renders does NOT restart the wait. The wait restarts on changes to scalar
856
+ * configuration (`poll.intervalMs`, `timeout.ms`, the timeout's named-exit
857
+ * form) so a deadline that genuinely shifts mid-wait is honored.
858
+ *
859
+ * Both `exit` and `channels` accept a plain value, a ref, or a getter
860
+ * ({@link MaybeRefOrGetter}) — because `setup` runs once, a caller whose
861
+ * channel configuration changes on the same instance should pass a getter (or
862
+ * a ref) so the wait re-arms on scalar changes and picks up the latest
863
+ * callbacks; plain values still work for hosts whose configuration is fixed for
864
+ * the mount. This mirrors how the React hook re-reads its props on re-render.
865
+ *
866
+ * Conventions:
867
+ *
868
+ * - At least one of `subscribe`, `poll`, `timeout` should be present.
869
+ * With none, the composable is a no-op until the component unmounts.
870
+ *
871
+ * - `resolve(name, output)` is the *latched* exit dispatcher. The latch
872
+ * is local to one arm cycle; the runtime's step-token mechanism is the
873
+ * global backstop (an exit dispatched after the step has advanced is
874
+ * dropped by the runtime even if the local latch were missing).
875
+ *
876
+ * - The composable does not own the journey-level "what does each exit mean"
877
+ * decision. That lives in the journey's `transitions` map. It only marshals
878
+ * the channels.
879
+ *
880
+ * - **First-wins teardown is immediate.** When any channel calls `resolve`,
881
+ * the *other* channels' teardowns run before the exit dispatches. A subscribe
882
+ * that synchronously calls `resolve` during setup still has its `unsubscribe`
883
+ * invoked; poll / timeout are not armed at all in that case.
884
+ *
885
+ * - The arm cycle is monolithic: changing any scalar dep (`pollInterval`,
886
+ * `timeoutMs`, the timeout's named-exit form) tears down *all* live channels
887
+ * and re-arms them. Callers that need independent per-channel lifecycles
888
+ * should split into multiple `useWaitForExit` calls or manage that channel
889
+ * themselves.
890
+ */
891
+ declare function useWaitForExit<TExits extends ExitPointMap>(exit: MaybeRefOrGetter<ExitFn<TExits>>, channels: MaybeRefOrGetter<WaitForExitChannels<TExits>>): void;
892
+ //#endregion
893
+ //#region src/plugin.d.ts
894
+ /**
895
+ * Methods the journeys plugin contributes to the registry. Registered plugins
896
+ * type-intersect with the base registry so shells call
897
+ * `registry.registerJourney(...)` with full type support. The neutral analog
898
+ * of the React `JourneysPluginExtension`.
899
+ */
900
+ interface JourneysPluginExtension {
901
+ /**
902
+ * Register a journey definition. The structural shape is validated
903
+ * immediately (missing `id` / `version` / `transitions` etc.); module-level
904
+ * contracts are validated at `resolveManifest()` / `resolve()` time.
905
+ *
906
+ * `options.persistence` is typed against the journey's state, and
907
+ * `options.nav.buildInput` is typed against the journey's input — pass a
908
+ * typed definition and both are checked end-to-end.
909
+ */
910
+ registerJourney<TModules extends ModuleTypeMap$1, TState, TInput, TOutput = unknown>(definition: JourneyDefinition$1<TModules, TState, TInput, TOutput>, options?: JourneyRegisterOptions$1<TState, TInput>): void;
911
+ }
912
+ /**
913
+ * Default shape the journeys plugin emits for each `nav`-carrying journey.
914
+ * When {@link JourneysPluginOptions.buildNavItem} is provided, the plugin
915
+ * hands this default (plus the journey's id and buildInput factory) to the
916
+ * adapter so apps can reshape the item into their narrowed `TNavItem`.
917
+ */
918
+ interface JourneyDefaultNavItem extends NavigationItemBase {
919
+ readonly label: string;
920
+ /**
921
+ * Always empty for a journey launcher — the dispatchable action lives in
922
+ * {@link JourneyDefaultNavItem.action}, so there is no URL to follow. An
923
+ * empty string keeps the structural `NavigationItemBase.to` satisfied
924
+ * without suggesting the shell should treat this item as a link.
925
+ */
926
+ readonly to: "";
927
+ readonly icon?: string | UiComponent<{
928
+ className?: string;
929
+ }>;
930
+ readonly group?: string;
931
+ readonly order?: number;
932
+ readonly hidden?: boolean;
933
+ readonly meta?: unknown;
934
+ readonly action: {
935
+ readonly kind: "journey-start";
936
+ readonly journeyId: string;
937
+ readonly buildInput?: (ctx?: unknown) => unknown;
938
+ };
939
+ }
940
+ /**
941
+ * Signature for the optional typed adapter that reshapes the plugin's default
942
+ * nav item into the app's narrowed `TNavItem`. The adapter is called once per
943
+ * `nav`-carrying journey at manifest time.
944
+ */
945
+ type JourneyNavItemBuilder<TNavItem extends NavigationItemBase> = (defaults: JourneyDefaultNavItem, raw: JourneyNavContribution$1<unknown> & {
946
+ readonly journeyId: string;
947
+ }) => TNavItem;
948
+ interface JourneysPluginOptions<TNavItem extends NavigationItemBase = JourneyDefaultNavItem> {
949
+ /**
950
+ * Enable verbose transition / rollback logging in the runtime. Defaults to
951
+ * `false`; plugins propagate the registry-level debug flag when set.
952
+ */
953
+ readonly debug?: boolean;
954
+ /**
955
+ * Forwarded onto `<JourneyProvider>` as the shell-wide `onModuleExit`
956
+ * handler. Use it as a default place to close tabs / forward analytics when
957
+ * a module exit isn't consumed by an explicit prop. Reuses the upstream
958
+ * `ModuleExitHandler` so the full `ModuleExitEvent` (incl. `routeId`) stays
959
+ * in sync with `@modular-vue/vue`.
960
+ */
961
+ readonly onModuleExit?: ModuleExitHandler;
962
+ /**
963
+ * Optional adapter that reshapes the plugin's default nav item into the
964
+ * app's narrowed `TNavItem`. Apps that use a typed `NavigationItem` alias
965
+ * (typed label union, typed action union, typed meta bag) should supply this
966
+ * so contributed items land in `manifest.navigation` with the correct
967
+ * narrowed type. When omitted, the plugin emits items as
968
+ * {@link JourneyDefaultNavItem} and the framework widens them to `TNavItem`
969
+ * at the assembly boundary.
970
+ */
971
+ readonly buildNavItem?: JourneyNavItemBuilder<TNavItem>;
972
+ }
973
+ /**
974
+ * Creates the journeys plugin. Pass to `registry.use(journeysPlugin())` (or
975
+ * `createRegistry({ plugins: [...] })`) to enable journey registration and
976
+ * outlet rendering without the runtime packages depending on
977
+ * `@modular-vue/journeys` directly. The Vue analog of the React
978
+ * `journeysPlugin`; the only framework-specific piece is `providers()`, which
979
+ * contributes a Vue `<JourneyProvider>` instead of a React one.
980
+ *
981
+ * The plugin:
982
+ * - contributes `registerJourney(...)` onto the registry (type-safe)
983
+ * - validates contracts against registered modules at resolve time
984
+ * - produces a `JourneyRuntime` on `manifest.extensions.journeys` (also
985
+ * surfaced as the `manifest.journeys` convenience alias)
986
+ * - wraps the provider stack in `<JourneyProvider :runtime="…" />`
987
+ *
988
+ * **Instantiate per registry.** The returned object closes over a
989
+ * journey-registration list; passing the same instance to two
990
+ * `createRegistry()` calls causes them to share that list. Call
991
+ * `journeysPlugin()` once per registry.
992
+ */
993
+ declare function journeysPlugin<TNavItem extends NavigationItemBase = JourneyDefaultNavItem>(options?: JourneysPluginOptions<TNavItem>): RegistryPlugin<"journeys", JourneysPluginExtension, JourneyRuntime$2>;
994
+ //#endregion
995
+ export { type AbandonCtx, type AnnotatedTransitionHandler, type AnyJourneyDefinition, type ChildOutcome, type EntryExitWildcardMap, type EntryInputOf, type EntryNamesOf, type EntryTransitions, type ExitCtx, type ExitNamesOf, type ExitNamesPairedWithEntry, type ExitOnlyWildcardMap, type ExitOutputOf, type InstanceId, type InvokeSpec, type JourneyDefaultNavItem, type JourneyDefinition, type JourneyDefinitionSummary, type JourneyHandle, JourneyHost, type JourneyHostSlotProps, type JourneyHostState, JourneyHydrationError, type JourneyInstance, type JourneyNavContribution, type JourneyNavItemBuilder, JourneyOutlet, type JourneyOutletErrorProps, type JourneyOutletNotFoundProps, type JourneyPersistence, JourneyProvider, type JourneyProviderValue, type JourneyRegisterOptions, type JourneyRuntime, type JourneyRuntimeOptions, type JourneyStatus, type JourneyStep, type JourneyStepErrorPolicy, type JourneyStepFor, type JourneySync, type JourneySyncAction, type JourneySyncCallbackCtx, type JourneySyncOptions, type JourneySyncPort, type JourneySystemAbortReason, type JourneySystemAbortReasonCode, JourneyValidationError, type JourneysPluginExtension, type JourneysPluginOptions, type MaybePromise, type MemoryPersistence, type MemoryPersistenceOptions, ModuleTab, type ModuleTabExitEvent, type ModuleTypeMap, type ParentLink, type PendingInvoke, type RegisteredJourney, type ResumeBounceCounter, type ResumeHandler, type ResumeMap, type SelectModuleCases, type SelectModuleCasesPartial, SemverParseError, type SerializedJourney, type StepRef, type StepSpec, type SyncJourneyPersistence, type TerminalCtx, type TerminalOutcome, type TerminalSentinel, type TransitionEvent, type TransitionMap, type TransitionResult, UnknownJourneyError, type UseJourneyHostOptions, type UseJourneySyncOptions, type WaitForExitChannels, type WaitForExitPollChannel, type WaitForExitSubscribeChannel, type WaitForExitTimeoutChannel, type WebStoragePersistenceOptions, type WildcardEntryInputOf, type WildcardEntryNamesOf, type WildcardExitNamesOf, type WildcardExitOutputForEntry, type WildcardExitOutputOf, type WildcardTransitionMap, compareVersions, createJourneyMountAdapter, createJourneyRuntime, createJourneySync, createMemoryJourneySyncPort, createMemoryPersistence, createWebStoragePersistence, defaultStepPath, defineJourney, defineJourneyHandle, defineJourneyPersistence, defineTransition, invoke, isAnnotatedTransition, isJourneySystemAbort, isTerminalSentinel, journeyKey, journeyStepPath, journeysPlugin, resolveJourneySyncAction, satisfies, selectModule, selectModuleOrDefault, useActiveLeafJourneyInstance, useActiveLeafJourneyState, useCallChain, useInstanceSnapshot, useJourneyCallStack, useJourneyContext, useJourneyHost, useJourneyInstance, useJourneyState, useJourneySync, useLeafId, useWaitForExit, validateJourneyContracts, validateJourneyDefinition, validateJourneyGraph };
996
+ //# sourceMappingURL=index.d.ts.map