@rxova/journey-core 1.0.0-rc.3 → 1.0.1

package/dist/core/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Machine-readable reasons a journey can refuse to build or operate.
+ *
+ * Closed on purpose: consumers should be able to `switch` over it exhaustively.
+ * Adding a member is a minor change; removing or repurposing one is not done
+ * within a major.
+ */
+export type JourneyErrorCode = 
+/** A definition declared no steps. */
+"empty-definition"
+/** The same step id was declared twice. */
+ | "duplicate-step-id"
+/** A step id was referenced that the definition does not declare. */
+ | "unknown-step"
+/** `initial` names a step the definition does not declare. */
+ | "unknown-initial-step"
+/** A transition's `from` or `to` names a step that does not exist. */
+ | "dangling-transition"
+/** Two plugins claimed the same `name`. */
+ | "duplicate-plugin-name"
+/** Persistence was requested but no usable storage could be resolved. */
+ | "storage-unavailable"
+/** Navigation work's `commit` returned a promise; it must be synchronous. */
+ | "async-commit"
+/** A transition or work entry declared `label` as something other than a non-empty string. */
+ | "invalid-label"
+/** A transition or work entry declared `timeoutMs` as something other than a positive finite number. */
+ | "invalid-timeout";
+export type JourneyErrorDetails = {
+    /** The offending step id, where one caused the failure. */
+    readonly stepId?: string;
+    /** The offending event name, for transition failures. */
+    readonly event?: string;
+    /** The offending plugin name, for plugin failures. */
+    readonly pluginName?: string;
+};
+/**
+ * Every error core throws itself.
+ *
+ * Before this existed, distinguishing "duplicate plugin name" from "unknown step
+ * in transition" meant matching on the message text — which quietly made every
+ * message a compatibility promise. `code` is the stable contract; `message` is
+ * for humans and may be reworded in any release.
+ *
+ * Errors surfaced through `NavigationResult.error` and the `error` subscription
+ * event stay `unknown`: those carry whatever the caller's own work threw, which
+ * core cannot constrain.
+ */
+export declare class JourneyError extends Error {
+    readonly code: JourneyErrorCode;
+    readonly stepId: string | undefined;
+    readonly event: string | undefined;
+    readonly pluginName: string | undefined;
+    constructor(code: JourneyErrorCode, message: string, details?: JourneyErrorDetails, cause?: unknown);
+}
+/** Narrowing helper, so consumers need not import the class to test for it. */
+export declare const isJourneyError: (value: unknown) => value is JourneyError;

package/dist/core/helpers.d.cts

@@ -0,0 +1,40 @@
+import type { RuntimeTransition } from "./runtime.types.js";
+import type { StepAsyncState, TransitionInfo } from "./types.js";
+/** Hard cap on events processed from one raise cascade before it is dropped. */
+export declare const MAX_RAISED_EVENTS = 25;
+/**
+ * Key for definition-declared send work. Work belongs to an (origin step,
+ * event) pair, not to an event alone — the same event name can be declared
+ * from several steps with different work on each. Length-prefixing the step id
+ * keeps the key injective without reserving a separator character.
+ */
+export declare const eventWorkKey: (from: string, event: string) => string;
+/**
+ * How one edge is named in errors and timeout messages.
+ *
+ * A declared label wins outright — that is the point of declaring one. Without
+ * it the fallback still has to distinguish candidates that share an event and
+ * a target and differ only by guard, so it carries the declaration index:
+ * `submit[1] (login -> twofa)`.
+ */
+export declare const describeTransition: (transition: RuntimeTransition) => string;
+/**
+ * The public, generics-free view of an edge handed to step hooks. Built once
+ * per navigation and shared by the three hooks it runs — and left unfrozen,
+ * like the hook args it rides on, since it does not outlive them.
+ */
+export declare const transitionInfo: (transition: RuntimeTransition | null) => TransitionInfo | null;
+export declare const SUCCESS_ASYNC: StepAsyncState;
+export declare const LOADING_ASYNC: StepAsyncState;
+/**
+ * Own-property membership, for every guard that asks "is this a declared id?".
+ *
+ * `in` walks the prototype chain, so `"toString" in steps` is true for any
+ * object literal. Using it to validate step ids let `toString`, `constructor`,
+ * `__proto__`, `hasOwnProperty` and friends pass as declared steps — including
+ * ids arriving from a persisted record or a route parameter, which are not
+ * developer-authored. Own-property checks are the only correct test here.
+ */
+export declare const hasOwn: (target: object, key: string) => boolean;
+/** Subscriber exceptions are isolated so one listener cannot break the pipeline. */
+export declare function reportListenerError(error: unknown): void;

package/dist/core/helpers.d.ts

@@ -0,0 +1,40 @@
+import type { RuntimeTransition } from "./runtime.types.js";
+import type { StepAsyncState, TransitionInfo } from "./types.js";
+/** Hard cap on events processed from one raise cascade before it is dropped. */
+export declare const MAX_RAISED_EVENTS = 25;
+/**
+ * Key for definition-declared send work. Work belongs to an (origin step,
+ * event) pair, not to an event alone — the same event name can be declared
+ * from several steps with different work on each. Length-prefixing the step id
+ * keeps the key injective without reserving a separator character.
+ */
+export declare const eventWorkKey: (from: string, event: string) => string;
+/**
+ * How one edge is named in errors and timeout messages.
+ *
+ * A declared label wins outright — that is the point of declaring one. Without
+ * it the fallback still has to distinguish candidates that share an event and
+ * a target and differ only by guard, so it carries the declaration index:
+ * `submit[1] (login -> twofa)`.
+ */
+export declare const describeTransition: (transition: RuntimeTransition) => string;
+/**
+ * The public, generics-free view of an edge handed to step hooks. Built once
+ * per navigation and shared by the three hooks it runs — and left unfrozen,
+ * like the hook args it rides on, since it does not outlive them.
+ */
+export declare const transitionInfo: (transition: RuntimeTransition | null) => TransitionInfo | null;
+export declare const SUCCESS_ASYNC: StepAsyncState;
+export declare const LOADING_ASYNC: StepAsyncState;
+/**
+ * Own-property membership, for every guard that asks "is this a declared id?".
+ *
+ * `in` walks the prototype chain, so `"toString" in steps` is true for any
+ * object literal. Using it to validate step ids let `toString`, `constructor`,
+ * `__proto__`, `hasOwnProperty` and friends pass as declared steps — including
+ * ids arriving from a persisted record or a route parameter, which are not
+ * developer-authored. Own-property checks are the only correct test here.
+ */
+export declare const hasOwn: (target: object, key: string) => boolean;
+/** Subscriber exceptions are isolated so one listener cannot break the pipeline. */
+export declare function reportListenerError(error: unknown): void;

package/dist/core/machine.d.cts

@@ -0,0 +1,9 @@
+import type { JourneyRuntime } from "./runtime.js";
+import type { JourneyMachineBase } from "./types.js";
+/**
+ * Builds the stable machine surface over a runtime. The object (and every
+ * nested group) is created once — all changing state lives in the snapshot.
+ */
+export declare function buildMachineSurface(runtime: JourneyRuntime): JourneyMachineBase<unknown, string> & {
+    plugins: Readonly<Record<string, unknown>>;
+};

package/dist/core/machine.d.ts

@@ -0,0 +1,9 @@
+import type { JourneyRuntime } from "./runtime.js";
+import type { JourneyMachineBase } from "./types.js";
+/**
+ * Builds the stable machine surface over a runtime. The object (and every
+ * nested group) is created once — all changing state lives in the snapshot.
+ */
+export declare function buildMachineSurface(runtime: JourneyRuntime): JourneyMachineBase<unknown, string> & {
+    plugins: Readonly<Record<string, unknown>>;
+};

package/dist/core/runtime.d.cts

@@ -0,0 +1,115 @@
+import { JourneyStore } from "./store.js";
+import type { AnyNavigationWork, AnySendWork, RuntimeConfig } from "./runtime.types.js";
+import type { ContextUpdater, NavigationResult } from "./types.js";
+export declare class JourneyRuntime {
+    readonly store: JourneyStore<unknown, string>;
+    readonly pluginApis: Record<string, unknown>;
+    private readonly config;
+    private status;
+    private timeline;
+    private currentIndex;
+    private context;
+    private outcome;
+    private visitCounts;
+    private entryAsync;
+    private pending;
+    private disposed;
+    /** One-shot seed for the first start(); restart() always enters fresh. */
+    private restoreSeed;
+    /** Bumped by terminate/restart/dispose so stale hook continuations bail out. */
+    private generation;
+    private raiseQueue;
+    private processingRaised;
+    private lastPluginExtensions;
+    /** The last built snapshot — the sharing baseline for buildSnapshot(). */
+    private lastSnapshot;
+    private readonly frozenStepOrder;
+    /**
+     * Per-step registration stacks, innermost last. Resolution is last-wins, but
+     * a stack (rather than a single slot) is what lets an unregister restore the
+     * registration it shadowed — two owners guarding one step is the normal case
+     * for component-scoped wrappers, and dropping to "ungated" when the newer one
+     * unmounts would fail silently.
+     */
+    private readonly transitionListeners;
+    private readonly disposeCallbacks;
+    private readonly snapshotDerivers;
+    constructor(config: RuntimeConfig);
+    start(): boolean;
+    pause(): boolean;
+    resume(): boolean;
+    complete(payload?: unknown): boolean;
+    terminate(payload?: unknown): boolean;
+    restart(): boolean;
+    dispose(): void;
+    updateContext(updater: ContextUpdater<unknown>): void;
+    clearAsyncError(): void;
+    goToStepById(id: string): Promise<NavigationResult>;
+    goToPreviousStep(n?: number): Promise<NavigationResult>;
+    goToNextStep(work?: AnyNavigationWork): Promise<NavigationResult>;
+    goToLastVisitedStep(): Promise<NavigationResult>;
+    /** Linear-only: declared-order index navigation, delegating to `goToStepById`. */
+    goToStepByIndex(index: number): Promise<NavigationResult>;
+    /** Graph-only primary verb; also drives raised events. */
+    send(type: string, payload?: unknown, work?: AnySendWork): Promise<NavigationResult>;
+    /**
+     * Work-carrying send: the async runs *before* routing, so its `commit` can
+     * stage the very context the guards are then evaluated against. Guards stay
+     * sync and pure — the work supplies facts, the definition still picks the
+     * edge.
+     *
+     * The machine holds its position for the whole `working` phase (`pending.to`
+     * is null: there is no target yet). If no candidate is enabled once the
+     * context is staged, the staged context is discarded and nothing is
+     * published — either the send routed and committed, or neither happened.
+     */
+    private sendWithWork;
+    private setupPlugins;
+    private currentStepId;
+    private eventFor;
+    /**
+     * `context` is explicit so a work-carrying `send` can evaluate guards against
+     * the context its `commit` just staged, rather than the committed one.
+     * `result` is the work's run result during that same routing pass; outside a
+     * work send (plain sends, snapshot introspection) guards see it as undefined.
+     */
+    private isEnabled;
+    /** First enabled candidate for `event` from the current step, in declaration order. */
+    private resolveTransition;
+    private checkNavigable;
+    private setStatus;
+    /** Re-derives `snapshot.plugins` after plugin taps ran post-publish. */
+    private refreshPluginSnapshot;
+    private blocked;
+    private hookArgs;
+    private invokeEffect;
+    /**
+     * `overrideMs` is the declaring edge's own budget. It wins over
+     * `defaultTimeoutMs` so that one slow third-party call does not force every
+     * other edge onto the slow one's budget; `undefined` falls back to the
+     * global, and a global of `undefined` means no bound at all.
+     */
+    private withTimeout;
+    /** Entry on start()/restart(): no onLeave, `from` is null, event is null. */
+    private enterInitialStep;
+    private runNavigation;
+    /**
+     * Publishes the position change and any staged context in one snapshot, then
+     * awaits the post-commit effects. Shared by plain navigation and by a
+     * work-carrying `send`, which reaches here only once its target is resolved.
+     */
+    private commitAndSettle;
+    /** Shared commit bookkeeping for navigations and the initial entry. */
+    private commitEntry;
+    /** Post-commit effects: step `onLeave`, transition effect, then step `onEnter`. */
+    private runEntryEffects;
+    /**
+     * Raised events run FIFO after the transition settles; a cascade longer than
+     * {@link MAX_RAISED_EVENTS} is dropped and surfaced as an `error` event.
+     */
+    private processRaisedEvents;
+    private isCurrent;
+    private staleResult;
+    private publish;
+    private buildSnapshot;
+}

package/dist/core/runtime.d.ts

@@ -0,0 +1,115 @@
+import { JourneyStore } from "./store.js";
+import type { AnyNavigationWork, AnySendWork, RuntimeConfig } from "./runtime.types.js";
+import type { ContextUpdater, NavigationResult } from "./types.js";
+export declare class JourneyRuntime {
+    readonly store: JourneyStore<unknown, string>;
+    readonly pluginApis: Record<string, unknown>;
+    private readonly config;
+    private status;
+    private timeline;
+    private currentIndex;
+    private context;
+    private outcome;
+    private visitCounts;
+    private entryAsync;
+    private pending;
+    private disposed;
+    /** One-shot seed for the first start(); restart() always enters fresh. */
+    private restoreSeed;
+    /** Bumped by terminate/restart/dispose so stale hook continuations bail out. */
+    private generation;
+    private raiseQueue;
+    private processingRaised;
+    private lastPluginExtensions;
+    /** The last built snapshot — the sharing baseline for buildSnapshot(). */
+    private lastSnapshot;
+    private readonly frozenStepOrder;
+    /**
+     * Per-step registration stacks, innermost last. Resolution is last-wins, but
+     * a stack (rather than a single slot) is what lets an unregister restore the
+     * registration it shadowed — two owners guarding one step is the normal case
+     * for component-scoped wrappers, and dropping to "ungated" when the newer one
+     * unmounts would fail silently.
+     */
+    private readonly transitionListeners;
+    private readonly disposeCallbacks;
+    private readonly snapshotDerivers;
+    constructor(config: RuntimeConfig);
+    start(): boolean;
+    pause(): boolean;
+    resume(): boolean;
+    complete(payload?: unknown): boolean;
+    terminate(payload?: unknown): boolean;
+    restart(): boolean;
+    dispose(): void;
+    updateContext(updater: ContextUpdater<unknown>): void;
+    clearAsyncError(): void;
+    goToStepById(id: string): Promise<NavigationResult>;
+    goToPreviousStep(n?: number): Promise<NavigationResult>;
+    goToNextStep(work?: AnyNavigationWork): Promise<NavigationResult>;
+    goToLastVisitedStep(): Promise<NavigationResult>;
+    /** Linear-only: declared-order index navigation, delegating to `goToStepById`. */
+    goToStepByIndex(index: number): Promise<NavigationResult>;
+    /** Graph-only primary verb; also drives raised events. */
+    send(type: string, payload?: unknown, work?: AnySendWork): Promise<NavigationResult>;
+    /**
+     * Work-carrying send: the async runs *before* routing, so its `commit` can
+     * stage the very context the guards are then evaluated against. Guards stay
+     * sync and pure — the work supplies facts, the definition still picks the
+     * edge.
+     *
+     * The machine holds its position for the whole `working` phase (`pending.to`
+     * is null: there is no target yet). If no candidate is enabled once the
+     * context is staged, the staged context is discarded and nothing is
+     * published — either the send routed and committed, or neither happened.
+     */
+    private sendWithWork;
+    private setupPlugins;
+    private currentStepId;
+    private eventFor;
+    /**
+     * `context` is explicit so a work-carrying `send` can evaluate guards against
+     * the context its `commit` just staged, rather than the committed one.
+     * `result` is the work's run result during that same routing pass; outside a
+     * work send (plain sends, snapshot introspection) guards see it as undefined.
+     */
+    private isEnabled;
+    /** First enabled candidate for `event` from the current step, in declaration order. */
+    private resolveTransition;
+    private checkNavigable;
+    private setStatus;
+    /** Re-derives `snapshot.plugins` after plugin taps ran post-publish. */
+    private refreshPluginSnapshot;
+    private blocked;
+    private hookArgs;
+    private invokeEffect;
+    /**
+     * `overrideMs` is the declaring edge's own budget. It wins over
+     * `defaultTimeoutMs` so that one slow third-party call does not force every
+     * other edge onto the slow one's budget; `undefined` falls back to the
+     * global, and a global of `undefined` means no bound at all.
+     */
+    private withTimeout;
+    /** Entry on start()/restart(): no onLeave, `from` is null, event is null. */
+    private enterInitialStep;
+    private runNavigation;
+    /**
+     * Publishes the position change and any staged context in one snapshot, then
+     * awaits the post-commit effects. Shared by plain navigation and by a
+     * work-carrying `send`, which reaches here only once its target is resolved.
+     */
+    private commitAndSettle;
+    /** Shared commit bookkeeping for navigations and the initial entry. */
+    private commitEntry;
+    /** Post-commit effects: step `onLeave`, transition effect, then step `onEnter`. */
+    private runEntryEffects;
+    /**
+     * Raised events run FIFO after the transition settles; a cascade longer than
+     * {@link MAX_RAISED_EVENTS} is dropped and surfaced as an `error` event.
+     */
+    private processRaisedEvents;
+    private isCurrent;
+    private staleResult;
+    private publish;
+    private buildSnapshot;
+}

package/dist/core/runtime.types.d.cts

@@ -0,0 +1,112 @@
+import type { AnyJourneyPlugin, ContextUpdater, JourneyEventObject, JourneySnapshot, NavigationDirection, NavigationWork, NavigationResult, StepHookArgs } from "./types.js";
+/** Internal, kind-agnostic hook shapes (public typing lives in the creators). */
+export type AnyHookArgs = StepHookArgs<unknown, string, JourneyEventObject>;
+export type AnyOnEffect = (args: AnyHookArgs) => void | Promise<void>;
+export type AnyNavigationWork = NavigationWork<unknown, string, JourneySnapshot, unknown>;
+/**
+ * Send work runs before routing, so unlike navigation work it has no `to` or
+ * `direction` to report — the target is not chosen yet. It carries the event
+ * that triggered it and the machine's handlers instead.
+ */
+export type AnySendWorkArgs = {
+    readonly snapshot: JourneySnapshot;
+    readonly from: string;
+    readonly event: JourneyEventObject;
+    readonly handlers: unknown;
+};
+export type AnySendWork = {
+    readonly run: (args: AnySendWorkArgs) => unknown;
+    readonly commit?: (args: AnySendWorkArgs & {
+        readonly result: unknown;
+        readonly updateContext: (updater: ContextUpdater<unknown>) => void;
+    }) => unknown;
+    /** Per-entry budget for `run`; falls back to `defaultTimeoutMs` when unset. */
+    readonly timeoutMs?: number;
+    /** Name used for this work in timeout and error messages. */
+    readonly label?: string;
+};
+export type RuntimeStep = {
+    readonly metadata: unknown;
+    readonly onEnter?: AnyOnEffect;
+    readonly onLeave?: AnyOnEffect;
+};
+export type RuntimeTransition = {
+    readonly event: string;
+    readonly from: string;
+    readonly to: string;
+    /**
+     * Position among the candidates `from` declares for `event`. Identifies an
+     * unlabelled edge in errors, where `event` and `to` may be shared by several
+     * candidates that differ only by guard.
+     */
+    readonly index: number;
+    /** The edge's declared name, used in place of the positional description. */
+    readonly label?: string;
+    /** Per-edge budget for `onTransition`; falls back to `defaultTimeoutMs`. */
+    readonly timeoutMs?: number;
+    /**
+     * `result` is the run result while routing a work send, and undefined
+     * everywhere else (plain sends, snapshot introspection).
+     */
+    readonly when?: (args: {
+        context: unknown;
+        handlers: unknown;
+        result?: unknown;
+    }) => boolean;
+    readonly onTransition?: AnyOnEffect;
+};
+export type RuntimeConfig = {
+    readonly kind: "linear" | "graph";
+    /** Declaration order (linear: the navigation order; graph: for totals only). */
+    readonly stepIds: readonly string[];
+    readonly steps: Readonly<Record<string, RuntimeStep>>;
+    readonly initial: string;
+    /** Overrides `initial` for the entry on start()/restart(). */
+    readonly startAt?: string;
+    readonly initialContext: unknown;
+    /** Graph only: flattened transitions map in declaration order. */
+    readonly transitions: readonly RuntimeTransition[];
+    /**
+     * Graph only: work declared on an event in the definition, keyed by
+     * {@link eventWorkKey} — two steps may declare different work for the same
+     * event name, so the origin step is part of the key.
+     */
+    readonly eventWork?: Readonly<Record<string, AnySendWork>>;
+    readonly handlers: unknown;
+    readonly autoStart: boolean;
+    readonly defaultTimeoutMs: number | undefined;
+    /** Routes isolated subscriber failures; defaults to the console reporter. */
+    readonly onListenerError?: (error: unknown) => void;
+    /**
+     * Seeds the first `start()` from a persisted record instead of a fresh
+     * entry at `startAt ?? initial`. Consumed once — `restart()` always goes
+     * fresh. Factories only pass a record that validated against the definition.
+     */
+    readonly restore?: {
+        readonly context: unknown;
+        readonly timeline: readonly string[];
+        readonly currentIndex: number;
+    };
+    readonly plugins: readonly AnyJourneyPlugin[];
+};
+/**
+ * The reason half of a failed navigation. `from`/`to` are deliberately absent:
+ * `blocked()` is the single place that knows both, and it fills them in when
+ * building the public `NavigationResult`. Deriving this straight from
+ * `NavigationResult` would force every internal call site to repeat them.
+ */
+export type NavigationFailure = Omit<Extract<NavigationResult, {
+    ok: false;
+}>, "from" | "to">;
+export type TimelineOp = {
+    readonly kind: "pointer";
+    readonly index: number;
+} | {
+    readonly kind: "append";
+};
+export type WorkDirection = NavigationDirection;
+export type TransitionListener = (info: {
+    from: string | null;
+    to: string;
+    snapshot: JourneySnapshot;
+}) => void;

package/dist/core/runtime.types.d.ts

@@ -0,0 +1,112 @@
+import type { AnyJourneyPlugin, ContextUpdater, JourneyEventObject, JourneySnapshot, NavigationDirection, NavigationWork, NavigationResult, StepHookArgs } from "./types.js";
+/** Internal, kind-agnostic hook shapes (public typing lives in the creators). */
+export type AnyHookArgs = StepHookArgs<unknown, string, JourneyEventObject>;
+export type AnyOnEffect = (args: AnyHookArgs) => void | Promise<void>;
+export type AnyNavigationWork = NavigationWork<unknown, string, JourneySnapshot, unknown>;
+/**
+ * Send work runs before routing, so unlike navigation work it has no `to` or
+ * `direction` to report — the target is not chosen yet. It carries the event
+ * that triggered it and the machine's handlers instead.
+ */
+export type AnySendWorkArgs = {
+    readonly snapshot: JourneySnapshot;
+    readonly from: string;
+    readonly event: JourneyEventObject;
+    readonly handlers: unknown;
+};
+export type AnySendWork = {
+    readonly run: (args: AnySendWorkArgs) => unknown;
+    readonly commit?: (args: AnySendWorkArgs & {
+        readonly result: unknown;
+        readonly updateContext: (updater: ContextUpdater<unknown>) => void;
+    }) => unknown;
+    /** Per-entry budget for `run`; falls back to `defaultTimeoutMs` when unset. */
+    readonly timeoutMs?: number;
+    /** Name used for this work in timeout and error messages. */
+    readonly label?: string;
+};
+export type RuntimeStep = {
+    readonly metadata: unknown;
+    readonly onEnter?: AnyOnEffect;
+    readonly onLeave?: AnyOnEffect;
+};
+export type RuntimeTransition = {
+    readonly event: string;
+    readonly from: string;
+    readonly to: string;
+    /**
+     * Position among the candidates `from` declares for `event`. Identifies an
+     * unlabelled edge in errors, where `event` and `to` may be shared by several
+     * candidates that differ only by guard.
+     */
+    readonly index: number;
+    /** The edge's declared name, used in place of the positional description. */
+    readonly label?: string;
+    /** Per-edge budget for `onTransition`; falls back to `defaultTimeoutMs`. */
+    readonly timeoutMs?: number;
+    /**
+     * `result` is the run result while routing a work send, and undefined
+     * everywhere else (plain sends, snapshot introspection).
+     */
+    readonly when?: (args: {
+        context: unknown;
+        handlers: unknown;
+        result?: unknown;
+    }) => boolean;
+    readonly onTransition?: AnyOnEffect;
+};
+export type RuntimeConfig = {
+    readonly kind: "linear" | "graph";
+    /** Declaration order (linear: the navigation order; graph: for totals only). */
+    readonly stepIds: readonly string[];
+    readonly steps: Readonly<Record<string, RuntimeStep>>;
+    readonly initial: string;
+    /** Overrides `initial` for the entry on start()/restart(). */
+    readonly startAt?: string;
+    readonly initialContext: unknown;
+    /** Graph only: flattened transitions map in declaration order. */
+    readonly transitions: readonly RuntimeTransition[];
+    /**
+     * Graph only: work declared on an event in the definition, keyed by
+     * {@link eventWorkKey} — two steps may declare different work for the same
+     * event name, so the origin step is part of the key.
+     */
+    readonly eventWork?: Readonly<Record<string, AnySendWork>>;
+    readonly handlers: unknown;
+    readonly autoStart: boolean;
+    readonly defaultTimeoutMs: number | undefined;
+    /** Routes isolated subscriber failures; defaults to the console reporter. */
+    readonly onListenerError?: (error: unknown) => void;
+    /**
+     * Seeds the first `start()` from a persisted record instead of a fresh
+     * entry at `startAt ?? initial`. Consumed once — `restart()` always goes
+     * fresh. Factories only pass a record that validated against the definition.
+     */
+    readonly restore?: {
+        readonly context: unknown;
+        readonly timeline: readonly string[];
+        readonly currentIndex: number;
+    };
+    readonly plugins: readonly AnyJourneyPlugin[];
+};
+/**
+ * The reason half of a failed navigation. `from`/`to` are deliberately absent:
+ * `blocked()` is the single place that knows both, and it fills them in when
+ * building the public `NavigationResult`. Deriving this straight from
+ * `NavigationResult` would force every internal call site to repeat them.
+ */
+export type NavigationFailure = Omit<Extract<NavigationResult, {
+    ok: false;
+}>, "from" | "to">;
+export type TimelineOp = {
+    readonly kind: "pointer";
+    readonly index: number;
+} | {
+    readonly kind: "append";
+};
+export type WorkDirection = NavigationDirection;
+export type TransitionListener = (info: {
+    from: string | null;
+    to: string;
+    snapshot: JourneySnapshot;
+}) => void;

package/dist/core/store.d.cts

@@ -0,0 +1,31 @@
+import type { JourneyEventPayloads, JourneySnapshot, JourneySubscriptionEvent, Unsubscribe } from "./types.js";
+/**
+ * Snapshot holder + subscription hub. Snapshots are immutable and rebuilt by
+ * the runtime; the store only distributes them.
+ */
+export declare class JourneyStore<TContext, TStepId extends string> {
+    private snapshot;
+    private readonly listeners;
+    private readonly eventListeners;
+    private disposed;
+    private readonly onListenerError;
+    constructor(initial: JourneySnapshot<TContext, TStepId>, onListenerError?: (error: unknown) => void);
+    /**
+     * Isolation stays unconditional; the configured reporter only routes the
+     * report. Internal, but reachable from the runtime so plugin-boundary
+     * failures land in the same place as subscriber failures.
+     */
+    report(error: unknown): void;
+    getSnapshot(): JourneySnapshot<TContext, TStepId>;
+    /** Replaces the snapshot and notifies every subscriber. */
+    publish(next: JourneySnapshot<TContext, TStepId>): void;
+    /**
+     * Notifies on every committed snapshot. Deriving a slice and skipping
+     * unchanged values is the caller's job — in React that is `useSelector`,
+     * which has to own the comparison anyway to keep render identity stable.
+     */
+    subscribe(listener: () => void): Unsubscribe;
+    subscribeEvent<TEvent extends JourneySubscriptionEvent>(event: TEvent, listener: (payload: JourneyEventPayloads<TContext, TStepId>[TEvent]) => void): Unsubscribe;
+    emit<TEvent extends JourneySubscriptionEvent>(event: TEvent, payload: JourneyEventPayloads<TContext, TStepId>[TEvent]): void;
+    dispose(): void;
+}