@rxova/journey-core 0.7.0 → 1.0.0-rc.2

package/dist/types/machine.types.d.cts

@@ -0,0 +1,104 @@
+import type { JourneyComputed, JourneyDefaultEventType, JourneyDefinition, JourneyEqualityFn, JourneyJsonObject, JourneyPayloadFor, JourneyResolvedDefinition, JourneySelector, JourneySendEvent, JourneySendResult, JourneySnapshot, JourneyTerminal } from "./journey.types";
+import type { JourneyCompleteObservationEvent, JourneyLifecycleErrorPhase, JourneyObservationEvent, JourneyResetObservationEvent, JourneyStartObservationEvent, JourneyTerminateObservationEvent } from "./observation.types";
+/** Reasons why a machine snapshot changed. */
+export type JourneyMachineSnapshotReason = "async" | "context" | "navigation" | "reset" | "start" | "transition";
+export type JourneyLifecycleErrorContext<TStepId extends string> = {
+    phase: JourneyLifecycleErrorPhase;
+    from: TStepId;
+    to: TStepId | JourneyTerminal;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+};
+/** Setup context passed to journey plugins when a machine is created. */
+export type JourneyMachinePluginSetupContext<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>> = {
+    journey: JourneyDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+    resolvedJourney: JourneyResolvedDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+    options: {
+        requireExplicitCompletion: boolean;
+        defaultTimeoutMs: number | undefined;
+    };
+    buildInitialSnapshot: () => JourneySnapshot<TContext, TStepId>;
+};
+/** Snapshot-change details exposed to plugins. */
+export type JourneyMachinePluginSnapshotChange<TContext extends JourneyJsonObject, TStepId extends string> = {
+    previousSnapshot: JourneySnapshot<TContext, TStepId>;
+    snapshot: JourneySnapshot<TContext, TStepId>;
+    reason: JourneyMachineSnapshotReason;
+};
+/** Hooks returned from a journey plugin setup call. */
+export type JourneyMachinePluginHooks<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>, TExtension extends object = Record<never, never>> = {
+    hydrateSnapshot?: (snapshot: JourneySnapshot<TContext, TStepId>) => JourneySnapshot<TContext, TStepId>;
+    onSnapshotChange?: (change: JourneyMachinePluginSnapshotChange<TContext, TStepId>) => void;
+    augmentMachine?: (context: {
+        machine: JourneyMachine<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+        journey: JourneyDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+        resolvedJourney: JourneyResolvedDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+    }) => TExtension;
+    dispose?: () => void;
+};
+/** Plugin contract for extending journey machines without bloating the base entrypoint. */
+export type JourneyMachinePlugin = {
+    name: string;
+    __extension__?: object;
+    setup: <TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>>(context: JourneyMachinePluginSetupContext<TContext, TStepId, TEventMap, TStepMeta, THandlers>) => JourneyMachinePluginHooks<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+};
+type JourneyMachinePluginHooksFor<TPlugin, TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown>, TStepMeta, THandlers extends Record<string, unknown>> = TPlugin extends {
+    setup: (context: JourneyMachinePluginSetupContext<TContext, TStepId, TEventMap, TStepMeta, THandlers>) => infer THooks;
+} ? THooks : never;
+type JourneyMachinePluginExtensionFor<TPlugin, TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown>, TStepMeta, THandlers extends Record<string, unknown>> = TPlugin extends {
+    __extension__?: infer TExtension;
+} ? Exclude<TExtension, undefined> extends never ? JourneyMachinePluginHooksFor<TPlugin, TContext, TStepId, TEventMap, TStepMeta, THandlers> extends {
+    augmentMachine?: (...args: never[]) => infer THookExtension;
+} ? THookExtension : Record<never, never> : Exclude<TExtension, undefined> : JourneyMachinePluginHooksFor<TPlugin, TContext, TStepId, TEventMap, TStepMeta, THandlers> extends {
+    augmentMachine?: (...args: never[]) => infer THookExtension;
+} ? THookExtension : Record<never, never>;
+type UnionToIntersection<TValue> = [TValue] extends [never] ? Record<never, never> : (TValue extends unknown ? (value: TValue) => void : never) extends (value: infer TIntersection) => void ? TIntersection : Record<never, never>;
+type JourneyTypeParam<TValue> = TValue extends unknown ? unknown : never;
+/** Optional machine features and plugin registration. */
+export type JourneyMachineOptions<TPlugins extends readonly JourneyMachinePlugin[] = readonly JourneyMachinePlugin[]> = {
+    requireExplicitCompletion?: boolean;
+    defaultTimeoutMs?: number;
+    plugins?: TPlugins;
+    /**
+     * Called when a snapshot or event listener throws an unhandled error.
+     * Listener failures are isolated so they never block other listeners or
+     * the machine itself — use this hook to report them to your error
+     * monitoring system (e.g. Sentry, Datadog).
+     *
+     * @param error - The thrown value (may not be an `Error` instance).
+     * @param context - `"snapshot"` for `subscribe()` listeners,
+     *   `"event"` for `subscribeEvent()` listeners.
+     */
+    onListenerError?: (error: unknown, context: "snapshot" | "event") => void;
+    onLifecycleError?: (error: unknown, context: JourneyLifecycleErrorContext<string>) => void;
+};
+type JourneyPayloadForDefaultEvent<TEventMap extends Record<string, unknown>, TDefaultEvent extends JourneyDefaultEventType> = JourneyPayloadFor<TEventMap, TDefaultEvent>;
+/** Runtime machine API for reading snapshots, sending events, and controlling flow. */
+export type JourneyMachine<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>> = JourneyTypeParam<THandlers> & {
+    getSnapshot: () => JourneySnapshot<TContext, TStepId>;
+    getStepMeta: (stepId: TStepId) => TStepMeta | undefined;
+    getComputed: () => JourneyComputed<TStepId>;
+    startJourney: () => Promise<JourneySnapshot<TContext, TStepId>>;
+    send: (event: JourneySendEvent<TStepId, TEventMap>) => Promise<JourneySendResult<TContext, TStepId>>;
+    goToNextStep: () => Promise<JourneySendResult<TContext, TStepId>>;
+    goToStepById: (stepId: TStepId) => Promise<JourneySendResult<TContext, TStepId>>;
+    terminateJourney: (payload?: JourneyPayloadForDefaultEvent<TEventMap, "terminateJourney">) => Promise<JourneySendResult<TContext, TStepId>>;
+    completeJourney: (payload?: JourneyPayloadForDefaultEvent<TEventMap, "completeJourney">) => Promise<JourneySendResult<TContext, TStepId>>;
+    goToPreviousStep: (steps?: number) => Promise<JourneySendResult<TContext, TStepId>>;
+    goToLastVisitedStep: () => Promise<JourneySendResult<TContext, TStepId>>;
+    updateContext: (updater: (context: TContext) => TContext) => Promise<JourneySnapshot<TContext, TStepId>>;
+    clearStepError: (stepId?: TStepId) => Promise<JourneySnapshot<TContext, TStepId>>;
+    resetJourney: () => Promise<JourneySnapshot<TContext, TStepId>>;
+    dispose: () => void;
+    subscribe: (listener: () => void) => () => void;
+    subscribeSelector: <TSelected>(selector: JourneySelector<TContext, TStepId, TSelected>, listener: (next: TSelected, previous: TSelected) => void, equalityFn?: JourneyEqualityFn<TSelected>) => () => void;
+    subscribeEvent: (listener: (event: JourneyObservationEvent<TStepId, TEventMap>) => void) => () => void;
+    subscribeStart: (listener: (event: JourneyStartObservationEvent<TStepId>) => void) => () => void;
+    subscribeReset: (listener: (event: JourneyResetObservationEvent<TStepId>) => void) => () => void;
+    subscribeComplete: (listener: (event: JourneyCompleteObservationEvent<TStepId>) => void) => () => void;
+    subscribeTerminate: (listener: (event: JourneyTerminateObservationEvent<TStepId>) => void) => () => void;
+};
+/** Journey machine API augmented by plugin-provided extensions. */
+export type JourneyMachineWithPlugins<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>, TPlugins extends readonly JourneyMachinePlugin[] = readonly JourneyMachinePlugin[]> = JourneyMachine<TContext, TStepId, TEventMap, TStepMeta, THandlers> & UnionToIntersection<JourneyMachinePluginExtensionFor<TPlugins[number], TContext, TStepId, TEventMap, TStepMeta, THandlers>>;
+export {};

package/dist/types/machine.types.d.ts

@@ -0,0 +1,104 @@
+import type { JourneyComputed, JourneyDefaultEventType, JourneyDefinition, JourneyEqualityFn, JourneyJsonObject, JourneyPayloadFor, JourneyResolvedDefinition, JourneySelector, JourneySendEvent, JourneySendResult, JourneySnapshot, JourneyTerminal } from "./journey.types";
+import type { JourneyCompleteObservationEvent, JourneyLifecycleErrorPhase, JourneyObservationEvent, JourneyResetObservationEvent, JourneyStartObservationEvent, JourneyTerminateObservationEvent } from "./observation.types";
+/** Reasons why a machine snapshot changed. */
+export type JourneyMachineSnapshotReason = "async" | "context" | "navigation" | "reset" | "start" | "transition";
+export type JourneyLifecycleErrorContext<TStepId extends string> = {
+    phase: JourneyLifecycleErrorPhase;
+    from: TStepId;
+    to: TStepId | JourneyTerminal;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+};
+/** Setup context passed to journey plugins when a machine is created. */
+export type JourneyMachinePluginSetupContext<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>> = {
+    journey: JourneyDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+    resolvedJourney: JourneyResolvedDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+    options: {
+        requireExplicitCompletion: boolean;
+        defaultTimeoutMs: number | undefined;
+    };
+    buildInitialSnapshot: () => JourneySnapshot<TContext, TStepId>;
+};
+/** Snapshot-change details exposed to plugins. */
+export type JourneyMachinePluginSnapshotChange<TContext extends JourneyJsonObject, TStepId extends string> = {
+    previousSnapshot: JourneySnapshot<TContext, TStepId>;
+    snapshot: JourneySnapshot<TContext, TStepId>;
+    reason: JourneyMachineSnapshotReason;
+};
+/** Hooks returned from a journey plugin setup call. */
+export type JourneyMachinePluginHooks<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>, TExtension extends object = Record<never, never>> = {
+    hydrateSnapshot?: (snapshot: JourneySnapshot<TContext, TStepId>) => JourneySnapshot<TContext, TStepId>;
+    onSnapshotChange?: (change: JourneyMachinePluginSnapshotChange<TContext, TStepId>) => void;
+    augmentMachine?: (context: {
+        machine: JourneyMachine<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+        journey: JourneyDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+        resolvedJourney: JourneyResolvedDefinition<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+    }) => TExtension;
+    dispose?: () => void;
+};
+/** Plugin contract for extending journey machines without bloating the base entrypoint. */
+export type JourneyMachinePlugin = {
+    name: string;
+    __extension__?: object;
+    setup: <TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>>(context: JourneyMachinePluginSetupContext<TContext, TStepId, TEventMap, TStepMeta, THandlers>) => JourneyMachinePluginHooks<TContext, TStepId, TEventMap, TStepMeta, THandlers>;
+};
+type JourneyMachinePluginHooksFor<TPlugin, TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown>, TStepMeta, THandlers extends Record<string, unknown>> = TPlugin extends {
+    setup: (context: JourneyMachinePluginSetupContext<TContext, TStepId, TEventMap, TStepMeta, THandlers>) => infer THooks;
+} ? THooks : never;
+type JourneyMachinePluginExtensionFor<TPlugin, TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown>, TStepMeta, THandlers extends Record<string, unknown>> = TPlugin extends {
+    __extension__?: infer TExtension;
+} ? Exclude<TExtension, undefined> extends never ? JourneyMachinePluginHooksFor<TPlugin, TContext, TStepId, TEventMap, TStepMeta, THandlers> extends {
+    augmentMachine?: (...args: never[]) => infer THookExtension;
+} ? THookExtension : Record<never, never> : Exclude<TExtension, undefined> : JourneyMachinePluginHooksFor<TPlugin, TContext, TStepId, TEventMap, TStepMeta, THandlers> extends {
+    augmentMachine?: (...args: never[]) => infer THookExtension;
+} ? THookExtension : Record<never, never>;
+type UnionToIntersection<TValue> = [TValue] extends [never] ? Record<never, never> : (TValue extends unknown ? (value: TValue) => void : never) extends (value: infer TIntersection) => void ? TIntersection : Record<never, never>;
+type JourneyTypeParam<TValue> = TValue extends unknown ? unknown : never;
+/** Optional machine features and plugin registration. */
+export type JourneyMachineOptions<TPlugins extends readonly JourneyMachinePlugin[] = readonly JourneyMachinePlugin[]> = {
+    requireExplicitCompletion?: boolean;
+    defaultTimeoutMs?: number;
+    plugins?: TPlugins;
+    /**
+     * Called when a snapshot or event listener throws an unhandled error.
+     * Listener failures are isolated so they never block other listeners or
+     * the machine itself — use this hook to report them to your error
+     * monitoring system (e.g. Sentry, Datadog).
+     *
+     * @param error - The thrown value (may not be an `Error` instance).
+     * @param context - `"snapshot"` for `subscribe()` listeners,
+     *   `"event"` for `subscribeEvent()` listeners.
+     */
+    onListenerError?: (error: unknown, context: "snapshot" | "event") => void;
+    onLifecycleError?: (error: unknown, context: JourneyLifecycleErrorContext<string>) => void;
+};
+type JourneyPayloadForDefaultEvent<TEventMap extends Record<string, unknown>, TDefaultEvent extends JourneyDefaultEventType> = JourneyPayloadFor<TEventMap, TDefaultEvent>;
+/** Runtime machine API for reading snapshots, sending events, and controlling flow. */
+export type JourneyMachine<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>> = JourneyTypeParam<THandlers> & {
+    getSnapshot: () => JourneySnapshot<TContext, TStepId>;
+    getStepMeta: (stepId: TStepId) => TStepMeta | undefined;
+    getComputed: () => JourneyComputed<TStepId>;
+    startJourney: () => Promise<JourneySnapshot<TContext, TStepId>>;
+    send: (event: JourneySendEvent<TStepId, TEventMap>) => Promise<JourneySendResult<TContext, TStepId>>;
+    goToNextStep: () => Promise<JourneySendResult<TContext, TStepId>>;
+    goToStepById: (stepId: TStepId) => Promise<JourneySendResult<TContext, TStepId>>;
+    terminateJourney: (payload?: JourneyPayloadForDefaultEvent<TEventMap, "terminateJourney">) => Promise<JourneySendResult<TContext, TStepId>>;
+    completeJourney: (payload?: JourneyPayloadForDefaultEvent<TEventMap, "completeJourney">) => Promise<JourneySendResult<TContext, TStepId>>;
+    goToPreviousStep: (steps?: number) => Promise<JourneySendResult<TContext, TStepId>>;
+    goToLastVisitedStep: () => Promise<JourneySendResult<TContext, TStepId>>;
+    updateContext: (updater: (context: TContext) => TContext) => Promise<JourneySnapshot<TContext, TStepId>>;
+    clearStepError: (stepId?: TStepId) => Promise<JourneySnapshot<TContext, TStepId>>;
+    resetJourney: () => Promise<JourneySnapshot<TContext, TStepId>>;
+    dispose: () => void;
+    subscribe: (listener: () => void) => () => void;
+    subscribeSelector: <TSelected>(selector: JourneySelector<TContext, TStepId, TSelected>, listener: (next: TSelected, previous: TSelected) => void, equalityFn?: JourneyEqualityFn<TSelected>) => () => void;
+    subscribeEvent: (listener: (event: JourneyObservationEvent<TStepId, TEventMap>) => void) => () => void;
+    subscribeStart: (listener: (event: JourneyStartObservationEvent<TStepId>) => void) => () => void;
+    subscribeReset: (listener: (event: JourneyResetObservationEvent<TStepId>) => void) => () => void;
+    subscribeComplete: (listener: (event: JourneyCompleteObservationEvent<TStepId>) => void) => () => void;
+    subscribeTerminate: (listener: (event: JourneyTerminateObservationEvent<TStepId>) => void) => () => void;
+};
+/** Journey machine API augmented by plugin-provided extensions. */
+export type JourneyMachineWithPlugins<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>, TStepMeta = unknown, THandlers extends Record<string, unknown> = Record<never, never>, TPlugins extends readonly JourneyMachinePlugin[] = readonly JourneyMachinePlugin[]> = JourneyMachine<TContext, TStepId, TEventMap, TStepMeta, THandlers> & UnionToIntersection<JourneyMachinePluginExtensionFor<TPlugins[number], TContext, TStepId, TEventMap, TStepMeta, THandlers>>;
+export {};

package/dist/types/observation.types.d.cts

@@ -0,0 +1,83 @@
+import type { JourneySendEvent, JourneyTerminal } from "./journey.types";
+export type JourneyLifecycleErrorPhase = "step.onLeave" | "transition.onLeave" | "step.onEnter" | "transition.onEnter";
+export type JourneyStartObservationEvent<TStepId extends string> = {
+    type: "journey.start";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyResetObservationEvent<TStepId extends string> = {
+    type: "journey.reset";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyTransitionStartObservationEvent<TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = {
+    type: "transition.start";
+    from: TStepId;
+    event: JourneySendEvent<TStepId, TEventMap>;
+    timestamp: number;
+};
+export type JourneyTransitionSuccessObservationEvent<TStepId extends string> = {
+    type: "transition.success";
+    from: TStepId;
+    to: TStepId | JourneyTerminal;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+    timestamp: number;
+};
+export type JourneyTransitionErrorObservationEvent<TStepId extends string> = {
+    type: "transition.error";
+    from: TStepId;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+    error: unknown;
+    timestamp: number;
+};
+export type JourneyLifecycleErrorObservationEvent<TStepId extends string> = {
+    type: "lifecycle.error";
+    phase: JourneyLifecycleErrorPhase;
+    from: TStepId;
+    to: TStepId | JourneyTerminal;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+    error: unknown;
+    timestamp: number;
+};
+export type JourneyStepExitObservationEvent<TStepId extends string> = {
+    type: "step.exit";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyStepEnterObservationEvent<TStepId extends string> = {
+    type: "step.enter";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyCompleteObservationEvent<TStepId extends string> = {
+    type: "journey.completed";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyTerminateObservationEvent<TStepId extends string> = {
+    type: "journey.terminated";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyPreviousNavigationObservationEvent<TStepId extends string> = {
+    type: "navigation.previous";
+    from: TStepId;
+    to: TStepId;
+    requestedSteps: number;
+    appliedSteps: number;
+    timestamp: number;
+};
+export type JourneyLastVisitedNavigationObservationEvent<TStepId extends string> = {
+    type: "navigation.lastVisited";
+    from: TStepId;
+    to: TStepId;
+    timestamp: number;
+};
+/** Observation events emitted by the machine lifecycle/event stream. */
+export type JourneyObservationEvent<TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = JourneyStartObservationEvent<TStepId> | JourneyResetObservationEvent<TStepId> | JourneyTransitionStartObservationEvent<TStepId, TEventMap> | JourneyTransitionSuccessObservationEvent<TStepId> | JourneyTransitionErrorObservationEvent<TStepId> | JourneyLifecycleErrorObservationEvent<TStepId> | JourneyStepExitObservationEvent<TStepId> | JourneyStepEnterObservationEvent<TStepId> | JourneyCompleteObservationEvent<TStepId> | JourneyTerminateObservationEvent<TStepId> | JourneyPreviousNavigationObservationEvent<TStepId> | JourneyLastVisitedNavigationObservationEvent<TStepId>;

package/dist/types/observation.types.d.ts

@@ -0,0 +1,83 @@
+import type { JourneySendEvent, JourneyTerminal } from "./journey.types";
+export type JourneyLifecycleErrorPhase = "step.onLeave" | "transition.onLeave" | "step.onEnter" | "transition.onEnter";
+export type JourneyStartObservationEvent<TStepId extends string> = {
+    type: "journey.start";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyResetObservationEvent<TStepId extends string> = {
+    type: "journey.reset";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyTransitionStartObservationEvent<TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = {
+    type: "transition.start";
+    from: TStepId;
+    event: JourneySendEvent<TStepId, TEventMap>;
+    timestamp: number;
+};
+export type JourneyTransitionSuccessObservationEvent<TStepId extends string> = {
+    type: "transition.success";
+    from: TStepId;
+    to: TStepId | JourneyTerminal;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+    timestamp: number;
+};
+export type JourneyTransitionErrorObservationEvent<TStepId extends string> = {
+    type: "transition.error";
+    from: TStepId;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+    error: unknown;
+    timestamp: number;
+};
+export type JourneyLifecycleErrorObservationEvent<TStepId extends string> = {
+    type: "lifecycle.error";
+    phase: JourneyLifecycleErrorPhase;
+    from: TStepId;
+    to: TStepId | JourneyTerminal;
+    eventType: string;
+    transitionId: string | null;
+    label?: string;
+    error: unknown;
+    timestamp: number;
+};
+export type JourneyStepExitObservationEvent<TStepId extends string> = {
+    type: "step.exit";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyStepEnterObservationEvent<TStepId extends string> = {
+    type: "step.enter";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyCompleteObservationEvent<TStepId extends string> = {
+    type: "journey.completed";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyTerminateObservationEvent<TStepId extends string> = {
+    type: "journey.terminated";
+    stepId: TStepId;
+    timestamp: number;
+};
+export type JourneyPreviousNavigationObservationEvent<TStepId extends string> = {
+    type: "navigation.previous";
+    from: TStepId;
+    to: TStepId;
+    requestedSteps: number;
+    appliedSteps: number;
+    timestamp: number;
+};
+export type JourneyLastVisitedNavigationObservationEvent<TStepId extends string> = {
+    type: "navigation.lastVisited";
+    from: TStepId;
+    to: TStepId;
+    timestamp: number;
+};
+/** Observation events emitted by the machine lifecycle/event stream. */
+export type JourneyObservationEvent<TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = JourneyStartObservationEvent<TStepId> | JourneyResetObservationEvent<TStepId> | JourneyTransitionStartObservationEvent<TStepId, TEventMap> | JourneyTransitionSuccessObservationEvent<TStepId> | JourneyTransitionErrorObservationEvent<TStepId> | JourneyLifecycleErrorObservationEvent<TStepId> | JourneyStepExitObservationEvent<TStepId> | JourneyStepEnterObservationEvent<TStepId> | JourneyCompleteObservationEvent<TStepId> | JourneyTerminateObservationEvent<TStepId> | JourneyPreviousNavigationObservationEvent<TStepId> | JourneyLastVisitedNavigationObservationEvent<TStepId>;

package/dist/types/persistence.types.d.cts

@@ -0,0 +1,34 @@
+import type { JourneyJsonObject, JourneySnapshotStateBase } from "./journey.types";
+export type JourneyPersistedState<TContext extends JourneyJsonObject, TStepId extends string> = {
+    version: number;
+    snapshot: JourneySnapshotStateBase<TContext, TStepId>;
+};
+export type JourneyStorage = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+export type JourneyPersistenceOptions<TContext extends JourneyJsonObject, TStepId extends string> = {
+    key: string;
+    storage?: JourneyStorage;
+    version?: number;
+    clearOnReset?: boolean;
+    allowList?: readonly string[];
+    blockList?: readonly string[];
+    serialize?: (value: JourneyPersistedState<TContext, TStepId>) => string;
+    deserialize?: (value: string) => unknown;
+    migrate?: (value: unknown, persistedVersion: number) => JourneySnapshotStateBase<TContext, TStepId>;
+    onError?: (error: unknown) => void;
+};
+export type ResolvedPersistence<TContext extends JourneyJsonObject, TStepId extends string> = {
+    key: string;
+    storage: JourneyStorage;
+    version: number;
+    clearOnReset: boolean;
+    allowList?: readonly string[];
+    blockList: readonly string[];
+    serialize: (value: JourneyPersistedState<TContext, TStepId>) => string;
+    deserialize: (value: string) => unknown;
+    migrate?: (value: unknown, persistedVersion: number) => JourneySnapshotStateBase<TContext, TStepId>;
+    onError?: (error: unknown) => void;
+};

package/dist/types/persistence.types.d.ts

@@ -1,41 +1,34 @@
-import type { JourneyStatus } from "./journey.types";
-export type JourneyPersistedSnapshot<TContext, TStepId extends string, TStepMeta = unknown> = {
-    currentStepId: TStepId;
-    history: {
-        timeline: readonly TStepId[];
-        index: number;
-    };
-    context: TContext;
-    status: JourneyStatus;
-    visited: Record<TStepId, boolean>;
-    stepMeta: Record<TStepId, TStepMeta>;
-};
-export type JourneyPersistedState<TContext, TStepId extends string, TStepMeta = unknown> = {
+import type { JourneyJsonObject, JourneySnapshotStateBase } from "./journey.types";
+export type JourneyPersistedState<TContext extends JourneyJsonObject, TStepId extends string> = {
     version: number;
-    snapshot: JourneyPersistedSnapshot<TContext, TStepId, TStepMeta>;
+    snapshot: JourneySnapshotStateBase<TContext, TStepId>;
 };
 export type JourneyStorage = {
     getItem: (key: string) => string | null;
     setItem: (key: string, value: string) => void;
     removeItem: (key: string) => void;
 };
-export type JourneyPersistenceOptions<TContext, TStepId extends string, TStepMeta = unknown> = {
+export type JourneyPersistenceOptions<TContext extends JourneyJsonObject, TStepId extends string> = {
     key: string;
     storage?: JourneyStorage;
     version?: number;
     clearOnReset?: boolean;
-    serialize?: (value: JourneyPersistedState<TContext, TStepId, TStepMeta>) => string;
+    allowList?: readonly string[];
+    blockList?: readonly string[];
+    serialize?: (value: JourneyPersistedState<TContext, TStepId>) => string;
     deserialize?: (value: string) => unknown;
-    migrate?: (value: unknown, persistedVersion: number) => JourneyPersistedSnapshot<TContext, TStepId, TStepMeta>;
+    migrate?: (value: unknown, persistedVersion: number) => JourneySnapshotStateBase<TContext, TStepId>;
     onError?: (error: unknown) => void;
 };
-export type ResolvedPersistence<TContext, TStepId extends string, TStepMeta> = {
+export type ResolvedPersistence<TContext extends JourneyJsonObject, TStepId extends string> = {
     key: string;
     storage: JourneyStorage;
     version: number;
     clearOnReset: boolean;
-    serialize: (value: JourneyPersistedState<TContext, TStepId, TStepMeta>) => string;
+    allowList?: readonly string[];
+    blockList: readonly string[];
+    serialize: (value: JourneyPersistedState<TContext, TStepId>) => string;
     deserialize: (value: string) => unknown;
-    migrate?: (value: unknown, persistedVersion: number) => JourneyPersistedSnapshot<TContext, TStepId, TStepMeta>;
+    migrate?: (value: unknown, persistedVersion: number) => JourneySnapshotStateBase<TContext, TStepId>;
     onError?: (error: unknown) => void;
 };

package/dist/types/replay.types.d.cts

@@ -0,0 +1,35 @@
+import type { JourneyMachineSnapshotReason } from "./machine.types";
+import type { JourneyJsonObject, JourneySnapshot } from "./journey.types";
+import type { JourneyObservationEvent } from "./observation.types";
+/** Snapshot entry captured by the replay plugin. */
+export type JourneyReplaySnapshotEntry<TContext extends JourneyJsonObject, TStepId extends string> = {
+    kind: "snapshot";
+    timestamp: number;
+    reason: JourneyMachineSnapshotReason;
+    snapshot: JourneySnapshot<TContext, TStepId>;
+};
+/** Observation event entry captured by the replay plugin. */
+export type JourneyReplayEventEntry<TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = {
+    kind: "event";
+    timestamp: number;
+    event: JourneyObservationEvent<TStepId, TEventMap>;
+};
+/** Ordered replay entry captured from a live machine session. */
+export type JourneyReplayEntry<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = JourneyReplaySnapshotEntry<TContext, TStepId> | JourneyReplayEventEntry<TStepId, TEventMap>;
+/** Full replay session captured from a journey machine. */
+export type JourneyReplaySession<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = {
+    version: 1;
+    initialSnapshot: JourneySnapshot<TContext, TStepId> | null;
+    entries: JourneyReplayEntry<TContext, TStepId, TEventMap>[];
+    truncated: boolean;
+};
+/** Runtime options for the replay plugin. */
+export type JourneyReplayPluginOptions = {
+    maxEntries?: number;
+    captureEvents?: boolean;
+    captureSnapshots?: boolean;
+};
+/** Serialization options for `exportReplaySession()`. */
+export type JourneyReplayExportOptions = {
+    pretty?: boolean;
+};

package/dist/types/replay.types.d.ts

@@ -0,0 +1,35 @@
+import type { JourneyMachineSnapshotReason } from "./machine.types";
+import type { JourneyJsonObject, JourneySnapshot } from "./journey.types";
+import type { JourneyObservationEvent } from "./observation.types";
+/** Snapshot entry captured by the replay plugin. */
+export type JourneyReplaySnapshotEntry<TContext extends JourneyJsonObject, TStepId extends string> = {
+    kind: "snapshot";
+    timestamp: number;
+    reason: JourneyMachineSnapshotReason;
+    snapshot: JourneySnapshot<TContext, TStepId>;
+};
+/** Observation event entry captured by the replay plugin. */
+export type JourneyReplayEventEntry<TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = {
+    kind: "event";
+    timestamp: number;
+    event: JourneyObservationEvent<TStepId, TEventMap>;
+};
+/** Ordered replay entry captured from a live machine session. */
+export type JourneyReplayEntry<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = JourneyReplaySnapshotEntry<TContext, TStepId> | JourneyReplayEventEntry<TStepId, TEventMap>;
+/** Full replay session captured from a journey machine. */
+export type JourneyReplaySession<TContext extends JourneyJsonObject, TStepId extends string, TEventMap extends Record<string, unknown> = Record<never, never>> = {
+    version: 1;
+    initialSnapshot: JourneySnapshot<TContext, TStepId> | null;
+    entries: JourneyReplayEntry<TContext, TStepId, TEventMap>[];
+    truncated: boolean;
+};
+/** Runtime options for the replay plugin. */
+export type JourneyReplayPluginOptions = {
+    maxEntries?: number;
+    captureEvents?: boolean;
+    captureSnapshots?: boolean;
+};
+/** Serialization options for `exportReplaySession()`. */
+export type JourneyReplayExportOptions = {
+    pretty?: boolean;
+};