react-wizard-engine 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1083 @@
+import * as react from 'react';
+import { ReactNode, RefObject } from 'react';
+export { I as IWizardBackArrowIconProps, a as IWizardButtonProps, b as IWizardComponents, W as WizardComponentsProvider, u as useWizardComponents } from './components-provider-bC3_zfyb.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Flat list of step states — the raw array form a tree is built from.
+ */
+type IWizardState<Step extends string, Category extends string, Branch extends string = string> = Array<IWizardStepState<Step, Category, Branch>>;
+
+interface IWizardEntityState {
+    /**
+     * Is a step currently shown on the screen.
+     * Can be mutated only by wizard itself via navigation methods like wizard.go/next/back etc.
+     *
+     * NOTE: on mobile multiple steps can be active but only the last one will be on the screen.
+     */
+    readonly isActive: boolean;
+    /**
+     * Is a step completed.
+     *
+     * Can be set in step options or will be automatically completed with wizard navigation
+     * progress with methods like wizard.go/next/back etc.
+     */
+    readonly isCompleted: boolean;
+    /**
+     * Is a step can be activated.
+     * Similar to React conditional rendering.
+     *
+     * Can be changed via **wizard.showStep/hideStep**
+     */
+    readonly isShow: boolean;
+    /**
+     * Is a step was skipped.
+     * This is an alternative to "isCompleted", but the main difference is that you can skip at any point
+     *
+     * Can be changed via **wizard.skipCategory**
+     */
+    readonly isSkipped: boolean;
+}
+
+interface IWizardStepState<Step extends string, Category extends string, Branch extends string = string> extends IWizardEntityState {
+    readonly branches: Branch[];
+    readonly categoryId: Category;
+    readonly htmlIndex: number;
+    readonly id: Step;
+}
+
+interface IWizardCategoryState<Step extends string, Category extends string, Branch extends string = string> extends IWizardEntityState {
+    readonly activeStepIndex: number;
+    readonly activeSteps: Array<IWizardStepState<Step, Category, Branch>>;
+    readonly branches: Branch[];
+    readonly completedSteps: Array<IWizardStepState<Step, Category, Branch>>;
+    readonly firstActiveStep: IWizardStepState<Step, Category, Branch>;
+    readonly firstStep: IWizardStepState<Step, Category, Branch>;
+    readonly htmlIndex: number;
+    readonly id: Category;
+    /** is completed OR skipped */
+    readonly isPassed: boolean;
+    readonly lastActiveStep: IWizardStepState<Step, Category, Branch>;
+    readonly lastStep: IWizardStepState<Step, Category, Branch>;
+    readonly nextStep: IWizardStepState<Step, Category, Branch> | null | undefined;
+    /** completed OR skipped steps */
+    readonly passedSteps: Array<IWizardStepState<Step, Category, Branch>>;
+    readonly prevStep: IWizardStepState<Step, Category, Branch> | null | undefined;
+    readonly shownSteps: Array<IWizardStepState<Step, Category, Branch>>;
+    /** Step from what category was skipped, -1 if not skipped */
+    readonly skippedAt: number;
+    readonly skippedSteps: Array<IWizardStepState<Step, Category, Branch>>;
+    readonly steps: Array<IWizardStepState<Step, Category, Branch>>;
+}
+
+interface IWizardBranchState<Step extends string, Category extends string, Branch extends string = string> {
+    readonly activeCategories: Array<IWizardCategoryState<Step, Category, Branch>>;
+    readonly activeCategory: IWizardCategoryState<Step, Category, Branch>;
+    readonly activeCategoryIndex: number;
+    readonly categories: Array<IWizardCategoryState<Step, Category, Branch>>;
+    readonly completedCategories: Array<IWizardCategoryState<Step, Category, Branch>>;
+    readonly firstCategory: IWizardCategoryState<Step, Category, Branch>;
+    /** NOTE: not HTMLIndex, just a regular index. */
+    getShownCategories(fromIndex: number, toIndex: number): Array<IWizardCategoryState<Step, Category, Branch>>;
+    getShownCategoryIndex(category: IWizardCategoryState<Step, Category, Branch>): number;
+    readonly id: Branch;
+    readonly lastCategory: IWizardCategoryState<Step, Category, Branch>;
+    readonly nextCategory: IWizardCategoryState<Step, Category, Branch> | null | undefined;
+    /** completed OR skipped categories */
+    readonly passedCategories: Array<IWizardCategoryState<Step, Category, Branch>>;
+    readonly prevCategory: IWizardCategoryState<Step, Category, Branch> | null | undefined;
+    readonly shownCategories: Array<IWizardCategoryState<Step, Category, Branch>>;
+    readonly skippedCategories: Array<IWizardCategoryState<Step, Category, Branch>>;
+}
+
+/**
+ * Wizard tree state subtype for the initial tree.
+ */
+type IWizardInitTreeState<Step extends string, Category extends string, Branch extends string = string> = IWizardTreeState<Step, Category, Branch>;
+interface IWizardTreeState<Step extends string, Category extends string, Branch extends string = string> {
+    readonly activeBranch: IWizardBranchState<Step, Category, Branch>;
+    readonly activeCategory: IWizardCategoryState<Step, Category, Branch>;
+    readonly activeSteps: Array<IWizardStepState<Step, Category, Branch>>;
+    readonly branches: Array<IWizardBranchState<Step, Category, Branch>>;
+    readonly branchMap: Record<Branch, IWizardBranchState<Step, Category, Branch>>;
+    readonly categoryMap: Record<Category, IWizardCategoryState<Step, Category, Branch>>;
+    readonly id: string;
+    readonly lastActiveStep: IWizardStepState<Step, Category, Branch>;
+    readonly state: IWizardState<Step, Category, Branch>;
+    readonly stepMap: Record<Step, IWizardStepState<Step, Category, Branch>>;
+}
+/**
+ * Terminal "complete" tree state. See `WizardExitTreeState` for the rationale on
+ * keeping this as a class.
+ */
+declare class WizardCompleteTreeState<Step extends string, Category extends string, Branch extends string = string> {
+    readonly originTree: Readonly<IWizardTreeState<Step, Category, Branch>>;
+    readonly state: "complete";
+    constructor(originTree: Readonly<IWizardTreeState<Step, Category, Branch>>);
+}
+/**
+ * Terminal "exit" tree state. Carries the originating tree so listeners can read
+ * what state the wizard exited from. Kept as a class so the navigation pipeline can
+ * branch on it via `instanceof`.
+ */
+declare class WizardExitTreeState<Step extends string, Category extends string, Branch extends string = string> {
+    readonly originTree: Readonly<IWizardTreeState<Step, Category, Branch>>;
+    readonly state: "exit";
+    constructor(originTree: Readonly<IWizardTreeState<Step, Category, Branch>>);
+}
+
+/**
+ * Pure factory for `IWizardBranchState`.
+ */
+declare function buildWizardBranchState<Step extends string, Category extends string, Branch extends string = string>(id: Branch, categories: ReadonlyArray<IWizardCategoryState<Step, Category, Branch>>): IWizardBranchState<Step, Category, Branch>;
+/**
+ * Pure factory for `IWizardCategoryState`. Groups steps into shown/active/completed/skipped/passed
+ * buckets, then derives all relational fields.
+ */
+declare function buildWizardCategoryState<Step extends string, Category extends string, Branch extends string = string>(id: Category, htmlIndex: number, steps: ReadonlyArray<IWizardStepState<Step, Category, Branch>>): IWizardCategoryState<Step, Category, Branch>;
+/**
+ * Pure factory for `IWizardTreeState`. Builds stepMap, groups steps by category in declaration order,
+ * groups categories by branch (a category may belong to multiple branches), and
+ * picks the active branch.
+ */
+declare function buildWizardTreeState<Step extends string, Category extends string, Branch extends string = string>(state: ReadonlyArray<IWizardStepState<Step, Category, Branch>>, activeBranchId?: Branch | null): IWizardTreeState<Step, Category, Branch>;
+
+/**
+ * Default per-step entity state.
+ */
+declare const wizardDefaultState: IWizardEntityState;
+/**
+ * Default branch id when steps don't declare branches.
+ */
+declare const wizardDefaultBranch = "main";
+
+type MutableStepState<Step extends string, Category extends string, Branch extends string> = {
+    -readonly [K in keyof IWizardStepState<Step, Category, Branch>]: IWizardStepState<Step, Category, Branch>[K];
+};
+/**
+ * Mutator for wizard tree state. Fluent API: clone an existing tree, mutate
+ * flat per-step flags, then call `build()` to produce a fully-derived (and
+ * rule-validated) tree.
+ */
+declare class WizardTreeStateBuilder<Step extends string, Category extends string, Branch extends string = string> {
+    private readonly branch;
+    private readonly state;
+    constructor(treeState: Readonly<IWizardTreeState<Step, Category, Branch>>, branch?: Branch | null);
+    static validate<Step extends string, Category extends string, Branch extends string = string>(tree: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    /** Activate completed steps + the next step after the last completed one. */
+    activateCategory(categoryId: Category): this;
+    /** Activate first shown step of a category; deactivate the rest. */
+    activateFirstStep(categoryId: Category): this;
+    activateStep(step: Step): this;
+    build(): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    /** Build a terminal complete tree (skips rule validation since the tree is sealed). */
+    buildComplete(): Readonly<WizardCompleteTreeState<Step, Category, Branch>>;
+    /** Build a terminal exit tree (skips rule validation since the tree is sealed). */
+    buildExit(): Readonly<WizardExitTreeState<Step, Category, Branch>>;
+    completeCategory(categoryId: Category): this;
+    completeStep(step: Step): this;
+    deactivateCategory(categoryId: Category): this;
+    deactivateStep(step: Step): this;
+    getCategoryStepStates(categoryId: Category): Array<MutableStepState<Step, Category, Branch>>;
+    /** Reset every step in the tree to `wizardDefaultState`. */
+    getResetTree(): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    getStepState(step: Step): MutableStepState<Step, Category, Branch>;
+    hideCategory(categoryId: Category): this;
+    hideStep(step: Step): this;
+    /** Reset category steps from `from` index onward; deactivate all but first. */
+    resetCategory(categoryId: Category, from?: number): this;
+    showCategory(categoryId: Category): this;
+    showStep(step: Step): this;
+    skipCategory(categoryId: Category): this;
+    skipCategoryUncompleted(categoryId: Category): this;
+    uncompleteStep(step: Step): this;
+    unskipCategory(categoryId: Category): this;
+}
+
+declare class WizardNavigation<Step extends string, Category extends string, Branch extends string = string> {
+    readonly from: Readonly<IWizardTreeState<Step, Category, Branch>>;
+    readonly to: Readonly<IWizardTreeState<Step, Category, Branch>> | WizardCompleteTreeState<Step, Category, Branch> | WizardExitTreeState<Step, Category, Branch>;
+    readonly direction: 'back' | 'next';
+    readonly id: string;
+    readonly isCategoryChanging: boolean;
+    readonly isComplete: boolean;
+    readonly isExit: boolean;
+    readonly isScrollChanging: boolean;
+    readonly isSkipping: boolean;
+    constructor(from: Readonly<IWizardTreeState<Step, Category, Branch>>, to: Readonly<IWizardTreeState<Step, Category, Branch>> | WizardCompleteTreeState<Step, Category, Branch> | WizardExitTreeState<Step, Category, Branch>);
+    static getDirection(from: Readonly<IWizardTreeState<string, string>>, to: Readonly<IWizardTreeState<string, string>>): 'back' | 'next';
+    static isCategoryChanging(from: Readonly<IWizardTreeState<string, string>>, to: Readonly<IWizardTreeState<string, string>>): boolean;
+    static isScrollChanging(from: Readonly<IWizardTreeState<string, string>>, to: Readonly<IWizardTreeState<string, string>>): boolean;
+    /**
+     * Navigation counted as skipped when Category "A" was "active" and not "skipped" before transition
+     * and became "inactive" and "skipped" after transition.
+     */
+    static isSkipping(from: Readonly<IWizardTreeState<string, string>>, to: Readonly<IWizardTreeState<string, string>>, direction?: 'back' | 'next'): boolean;
+}
+
+type IWizardResolverHook<Step extends string, Category extends string, Branch extends string = string> = (navigation: WizardNavigation<Step, Category, Branch>) => boolean | Promise<boolean>;
+
+/**
+ * Per-category-aware wizard config options. Adds a category-keyed translation map
+ * for the wizard header and the four resolver hooks consumed by the navigation pipeline.
+ */
+interface IWizardConfigOptions<Category extends string = string> extends IWizardGeneralConfigOptions {
+    /** Object with translation to get wizard header point title by category key. If no option no text will appear */
+    headerI18n: null | Record<Category, string>;
+    resolveCategoryChange: IWizardResolverHook<string, Category, string>;
+    resolveCategoryComplete: IWizardResolverHook<string, Category, string>;
+    resolveCategoryEnter: IWizardResolverHook<string, Category, string>;
+    resolveStepChange: IWizardResolverHook<string, Category, string>;
+}
+/**
+ * General (non-category-aware) wizard config options.
+ */
+interface IWizardGeneralConfigOptions {
+    /** Class for wizard back btn */
+    backBtnClass: string;
+    /** Back text for wizard back btn. 'Back' is default */
+    backBtnText: string;
+    /** Title for 'Finish' category */
+    doneDotText: string;
+    /**
+     * Use for debugging.
+     *
+     * When "events" log all internal navigation events to the console.
+     * When "state" log only state changes.
+     * When "none" no logs will be shown.
+     *
+     * Default is 'none'
+     */
+    enableTracing: 'events' | 'none' | 'state';
+    /** 'Finish' is default */
+    finishText: string;
+    /** Whether click on active category in header will reset category. Default true */
+    isActiveCategoryClickReset: boolean;
+    /** If true every time user presses back it will set a step as not completed. Default is true */
+    isBackResetCompleted: boolean;
+    /** To show done dot in header steps. Default false */
+    isDoneDot: boolean;
+    /**
+     * When moving forward into a completed category, start from its first step.
+     * By default, the wizard remembers your progress (you land on the last completed
+     * or the next uncompleted step). With this option enabled, progress is still
+     * tracked but ignored on forward transitions — you always begin from the first step.
+     * On backward transitions, the last completed step is still shown.
+     * @default false
+     */
+    isShowFirstStepOnCategoryChange: boolean;
+    /** Condition to show default wizard header */
+    isShowWizardHeader: boolean;
+    /** Condition to show default wizard header dots */
+    isShowWizardHeaderSteps: boolean;
+    /** Class for wizard next btn */
+    nextBtnClass: string;
+    /** Next text between category steps. 'Next' is default */
+    nextBtnText: string;
+    /** Next text between categories. 'Continue' is default */
+    nextCategoryText: string;
+    /** Will silence error handled by wizard. Use for debugging. Default is false. Use !environment.production in your project */
+    silenceErrors: boolean;
+    /** Is header will scroll with the page. Default true */
+    stickyHeader: boolean;
+    /** Prefix for data stored in different storages like LocalStorage. Can't be dynamically changed */
+    storagePrefix?: number | string;
+}
+
+interface IWizardStepButtonOptions {
+    /** Custom node for the step button */
+    btnTemplate?: ReactNode | undefined;
+    /** Text of next step btn. Default is got from WizardConfig */
+    btnText?: string;
+    /**
+     * If true pressing enter will trigger wizard.next(). Default: true
+     * NOTE: listener for "enter" pressing lives in the React next-button component;
+     * without it this option won't fire.
+     */
+    isEnterTriggerNext: boolean;
+    /** Whether to show wizard default next button. Default: true */
+    isShowNextBtn: boolean;
+    /** Disable 'next' btn if not valid */
+    isValid: boolean;
+}
+interface IWizardStepHeaderOptions {
+    /** Default: true */
+    isShowBackBtn: boolean;
+    /** Show close button in wizard-dashboard-header. Default: true */
+    isShowCloseBtn: boolean;
+    /** Default: true */
+    isShowHeader: boolean;
+    /** Default: true */
+    isShowHeaderSteps: boolean;
+}
+interface IWizardStepOptions extends IWizardStepButtonOptions, IWizardStepHeaderOptions {
+}
+
+/**
+ * Base contract for wizard tree-state initializers. Each initializer in a chain
+ * receives the result of the previous one (and the original HTML tree) and may
+ * mutate the active step / category / completion based on persisted state, URL
+ * params, server data, etc.
+ */
+declare abstract class WizardInitializer<Step extends string, Category extends string, Branch extends string = string> {
+    abstract getState(tree: Readonly<IWizardTreeState<Step, Category, Branch>>, htmlTree: Readonly<IWizardTreeState<Step, Category, Branch>>): Promise<Readonly<IWizardTreeState<Step, Category, Branch>>> | Readonly<IWizardTreeState<Step, Category, Branch>>;
+}
+
+/**
+ * Default initializer: if the tree already has an active step, return it as-is.
+ * Otherwise activate the first non-passed category (or the active category as
+ * a fallback) so the wizard always boots with a valid active step.
+ */
+declare class WizardDefaultInitializer<Step extends string, Category extends string, Branch extends string = string> extends WizardInitializer<Step, Category, Branch> {
+    getState(tree: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+}
+
+declare enum WizardEventType {
+    Complete = "complete",
+    Exit = "exit",
+    NavigationCancelled = "navigation_cancelled",
+    NavigationEnd = "navigation_end",
+    NavigationError = "navigation_error",
+    NavigationIgnored = "navigation_ignored",
+    NavigationStart = "navigation_start",
+    ResolveEnd = "resolve_end",
+    ResolveStart = "resolve_start",
+    ScrollEnd = "scroll_end",
+    ScrollStart = "scroll_start",
+    StepHide = "step_hide",
+    StepShow = "step_show"
+}
+
+/**
+ * General parent event for all wizard events.
+ */
+declare abstract class WizardEvent<Step extends string, Category extends string, Branch extends string = string> {
+    readonly navigation?: WizardNavigation<Step, Category, Branch> | undefined;
+    abstract readonly type: WizardEventType;
+    /** @param navigation - Specific navigation data associated with event */
+    constructor(navigation?: WizardNavigation<Step, Category, Branch> | undefined);
+}
+declare class WizardCompleteEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.Complete;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+/**
+ * Exit can be triggered in 2 ways:
+ *   - as a part of navigation (with navigation data)
+ *   - before wizard init, where no state exists yet
+ */
+declare class WizardExitEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly type: WizardEventType.Exit;
+}
+declare class WizardNavigationCancelledEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly reason: 'new_navigation' | 'resolver';
+    readonly type: WizardEventType.NavigationCancelled;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>, reason: 'new_navigation' | 'resolver');
+}
+declare class WizardNavigationEndEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.NavigationEnd;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardNavigationErrorEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.NavigationError;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardNavigationIgnoredEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly reason: 'same_navigation';
+    readonly type: WizardEventType.NavigationIgnored;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>, reason: 'same_navigation');
+}
+declare class WizardNavigationStartEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.NavigationStart;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardResolveEndEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.ResolveEnd;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardResolveStartEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.ResolveStart;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardScrollEndEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.ScrollEnd;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardScrollStartEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.ScrollStart;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardStepHideEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.StepHide;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+declare class WizardStepShowEvent<Step extends string, Category extends string, Branch extends string = string> extends WizardEvent<Step, Category, Branch> {
+    readonly navigation: WizardNavigation<Step, Category, Branch>;
+    readonly type: WizardEventType.StepShow;
+    constructor(navigation: WizardNavigation<Step, Category, Branch>);
+}
+
+/**
+ * Base contract for wizard lifecycle listeners.
+ */
+declare abstract class WizardListener<Step extends string, Category extends string, Branch extends string = string> {
+    onDestroy(_tree: Readonly<IWizardTreeState<Step, Category, Branch>>): void;
+    onEvent(_event: WizardEvent<Step, Category, Branch>): void;
+    onInit(_tree: Readonly<IWizardTreeState<Step, Category, Branch>>): void;
+    onTreeChange(_tree: Readonly<IWizardTreeState<Step, Category, Branch>>): void;
+}
+
+/**
+ * Minimal structural shape of `WizardConfig` used by the completed-progress
+ * strategy for its `isBackResetCompleted` interaction warning.
+ */
+interface IWizardProgressConfigLike {
+    readonly isBackResetCompleted: boolean;
+}
+/**
+ * Minimal structural shape of `WizardLog` used by the completed-progress
+ * strategy to surface a configuration warning.
+ */
+interface IWizardProgressLogLike {
+    error(error: Error): void;
+}
+/**
+ * Strategy for calculating wizard progress (per-category percentage 0-100).
+ */
+declare abstract class WizardProgressStrategy<Step extends string, Category extends string, Branch extends string = string> {
+    abstract getProgress(tree: Readonly<IWizardTreeState<Step, Category, Branch>>): Record<Category, number>;
+}
+
+/**
+ * Default progress strategy: progress to the last active step of each category.
+ * Past categories report 100; future ones report 0; the active category reports
+ * `(activeSteps.length - 1) * 100 / shownSteps.length`.
+ */
+declare class WizardActiveProgressStrategy<Step extends string, Category extends string, Branch extends string = string> extends WizardProgressStrategy<Step, Category, Branch> {
+    getProgress(tree: Readonly<IWizardTreeState<Step, Category, Branch>>): Record<Category, number>;
+}
+
+/**
+ * Where the wizard should scroll. Accepts an element directly, a React-style
+ * ref object, or a getter — the last two resolve lazily, which is required
+ * when the container lives behind a ref (refs are populated after the engine
+ * is built). When omitted, the strategy scrolls the page (`window`).
+ */
+type WizardScrollContainer = (() => HTMLElement | null) | HTMLElement | null | {
+    readonly current: HTMLElement | null;
+};
+/**
+ * Strategy for scrolling between steps in the wizard.
+ *
+ * Backed by native `Element.scrollIntoView({ behavior, block })`. Smooth/instant
+ * variants ship as separate strategies. A scroll container can be attached via
+ * `setContainer` (typically by the engine, fed from `withScrollContainer`); the
+ * container takes over scroll-to-top from `window`. Step-anchored scrolls keep
+ * using `scrollIntoView`, which already walks up to the nearest scrollable
+ * ancestor, so the container does not need to be re-resolved per element.
+ */
+declare abstract class WizardScrollStrategy<Step extends string, Category extends string, Branch extends string = string> {
+    protected static projectToTree: <Step_1 extends string, Category_1 extends string, Branch_1 extends string>(target: Readonly<IWizardTreeState<Step_1, Category_1, Branch_1>> | WizardCompleteTreeState<Step_1, Category_1, Branch_1> | WizardExitTreeState<Step_1, Category_1, Branch_1>) => Readonly<IWizardTreeState<Step_1, Category_1, Branch_1>>;
+    protected container?: WizardScrollContainer;
+    /** Called by the navigation pipeline after `setState` lands a new tree. */
+    abstract onNavigate(navigation: WizardNavigation<Step, Category, Branch>): Promise<boolean>;
+    /** Called when toggling step/category visibility (instant scroll by default). */
+    onToggle(navigation: WizardNavigation<Step, Category, Branch>): Promise<boolean>;
+    /**
+     * Imperative scroll-to-top of the configured container (or window). Useful
+     * for surfacing top-of-page state — e.g. an error banner — after a failed
+     * submit, without re-running the navigation pipeline.
+     */
+    scrollToTop(behavior?: 'auto' | 'smooth'): Promise<boolean>;
+    setContainer(container?: WizardScrollContainer): void;
+}
+/**
+ * Internal helper: scroll to a step by element id (or to the top for `null`).
+ * SSR-safe (no-op when `document` is unavailable). Honors `prefers-reduced-motion`
+ * by silently downgrading 'smooth' to 'auto'. When `container` is provided, the
+ * scroll-to-top case targets that element instead of `window`.
+ */
+declare function scrollToStep(stepId: null | string | undefined, behavior: 'auto' | 'instant' | 'smooth', container?: WizardScrollContainer): Promise<boolean>;
+
+/**
+ * Minimal structural shape of `WizardConfig` used by the smooth scroll strategy.
+ * Phase 7 replaces this with the concrete class.
+ */
+interface IWizardScrollConfigLike {
+    readonly isMobile: boolean;
+}
+/**
+ * Smooth-scroll strategy. Scrolls to the active step on every navigation;
+ * downgrades to instant scroll on category transitions, on mobile, and when
+ * `prefers-reduced-motion: reduce` is set.
+ */
+declare class WizardSmoothScrollStrategy<Step extends string, Category extends string, Branch extends string = string> extends WizardScrollStrategy<Step, Category, Branch> {
+    private readonly wizardConfig?;
+    constructor(wizardConfig?: IWizardScrollConfigLike | undefined);
+    onNavigate(navigation: WizardNavigation<Step, Category, Branch>): Promise<boolean>;
+}
+
+/**
+ * Minimal structural shape of `WizardConfig` used by visibility strategies.
+ * Phase 7 replaces this with the concrete class.
+ */
+interface IWizardVisibilityConfigLike {
+    readonly isMobile: boolean;
+}
+/**
+ * Strategy for calculating which wizard steps are visible (mounted in the DOM).
+ */
+declare abstract class WizardVisibilityStrategy<Step extends string, Category extends string, Branch extends string = string> {
+    abstract isStepVisible(step: IWizardStepState<Step, Category, Branch>, tree: Readonly<IWizardTreeState<Step, Category, Branch>>): boolean;
+}
+
+/**
+ * Default visibility: show all active steps of the active category on desktop;
+ * show only the last active step on mobile.
+ */
+declare class WizardDefaultVisibilityStrategy<Step extends string, Category extends string, Branch extends string = string> extends WizardVisibilityStrategy<Step, Category, Branch> {
+    private readonly wizardConfig;
+    constructor(wizardConfig: IWizardVisibilityConfigLike);
+    isStepVisible(step: IWizardStepState<Step, Category, Branch>, tree: Readonly<IWizardTreeState<Step, Category, Branch>>): boolean;
+}
+
+/**
+ * Show only the last active step of the category.
+ */
+declare class WizardLastActiveVisibilityStrategy<Step extends string, Category extends string, Branch extends string = string> extends WizardVisibilityStrategy<Step, Category, Branch> {
+    isStepVisible(step: IWizardStepState<Step, Category, Branch>, tree: Readonly<IWizardTreeState<Step, Category, Branch>>): boolean;
+}
+
+interface WizardEngineOptions<Step extends string, Category extends string, Branch extends string = string> {
+    activeBranch?: Branch;
+    config?: Partial<IWizardConfigOptions<Category>>;
+    initializers?: ReadonlyArray<WizardInitializer<Step, Category, Branch>>;
+    listeners?: ReadonlyArray<WizardListener<Step, Category, Branch>>;
+    scrollContainer?: WizardScrollContainer;
+    state: ReadonlyArray<WizardEngineStepRegistration<Step, Category, Branch>>;
+    strategies?: WizardEngineStrategies<Step, Category, Branch>;
+}
+/**
+ * Step-shape descriptor passed to the engine when constructing it. The full
+ * `WizardStep` per-step UI control object lives in the React adapter (Phase 15);
+ * the engine itself only needs the flat per-step state plus the categoryId so
+ * it can build a tree.
+ */
+type WizardEngineStepRegistration<Step extends string, Category extends string, Branch extends string = string> = IWizardStepState<Step, Category, Branch>;
+interface WizardEngineStrategies<Step extends string, Category extends string, Branch extends string = string> {
+    progress?: WizardProgressStrategy<Step, Category, Branch>;
+    scroll?: WizardScrollStrategy<Step, Category, Branch>;
+    visibility?: WizardVisibilityStrategy<Step, Category, Branch>;
+}
+/**
+ * Top-level wizard façade. Framework-free: pass plain objects in, subscribe via
+ * `subscribe()` / `on()`, control via the imperative methods.
+ */
+declare class WizardEngine<Step extends string, Category extends string, Branch extends string = string> {
+    get configOptions(): Readonly<IWizardConfigOptions<Category>>;
+    get isInitialized(): boolean;
+    get lastActiveStep(): IWizardStepState<Step, Category, Branch>;
+    get progress(): Record<Category, number>;
+    get shapeId(): string;
+    get steps(): Readonly<Record<Step, IWizardStepState<Step, Category, Branch>>>;
+    get tree(): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    private committed;
+    private readonly config;
+    private disposed;
+    private readonly initialBranch?;
+    private initialized;
+    private readonly initialState;
+    private readonly initService;
+    private readonly listeners;
+    private readonly log;
+    private readonly navService;
+    private readonly pendingPostInitTasks;
+    private readonly progressStrategy;
+    private readonly scrollStrategy;
+    private readonly stateService;
+    private readonly store;
+    private readonly visibilityStrategy;
+    constructor(options: WizardEngineOptions<Step, Category, Branch>);
+    back(): Promise<boolean>;
+    backCategory(): Promise<boolean>;
+    commitRegistration(): Promise<void>;
+    completeWizard(): Promise<boolean>;
+    dispose(): void;
+    exitWizard(): Promise<boolean>;
+    getTreeSnapshot: () => Readonly<IWizardTreeState<Step, Category, Branch>>;
+    go(tree: Readonly<IWizardTreeState<Step, Category, Branch>>): Promise<boolean>;
+    goToCategory(category: Category): Promise<boolean>;
+    hideCategory(category: Category): Promise<boolean>;
+    hideStep(step: Step | Step[]): Promise<boolean>;
+    isStepVisible(stepId: Step): boolean;
+    next(branch?: Branch | null): Promise<boolean>;
+    nextCategory(branch?: Branch | null): Promise<boolean>;
+    on(type: '*' | WizardEvent<Step, Category, Branch>['type'], handler: (event: WizardEvent<Step, Category, Branch>) => void): () => void;
+    resetActiveCategory(from?: number): Promise<boolean>;
+    resetCategory(category: Category, from?: number): Promise<boolean>;
+    resetWizard(): Promise<boolean>;
+    scrollToTop(behavior?: 'auto' | 'smooth'): Promise<boolean>;
+    showCategory(category: Category): Promise<boolean>;
+    showStep(step: Step | Step[]): Promise<boolean>;
+    skipActiveCategory(): Promise<boolean>;
+    skipCategory(category?: Category): Promise<boolean>;
+    subscribe: (listener: () => void) => (() => void);
+    toggleCategory(category: Category, show: boolean): Promise<boolean>;
+    toggleStep(step: Step | Step[], show: boolean): Promise<boolean>;
+    private runOrQueue;
+}
+
+/**
+ * Aggregated provider props — what `<WizardProvider>` (Phase 15) consumes and
+ * passes through to `new WizardEngine(...)`. Built up by chaining `with*`
+ * helpers via `composeWizardProviders(...)`.
+ */
+interface IWizardProviderProps<Step extends string, Category extends string, Branch extends string = string> {
+    config: Partial<IWizardConfigOptions<Category>>;
+    initializers: Array<WizardInitializer<Step, Category, Branch>>;
+    listeners: Array<WizardListener<Step, Category, Branch>>;
+    scrollContainer?: WizardScrollContainer;
+    strategies: WizardEngineStrategies<Step, Category, Branch>;
+}
+/**
+ * Modifier function — receives the props in flight, mutates them, returns void.
+ * Each `with*` helper returns one of these.
+ */
+type WizardProviderMod<Step extends string, Category extends string, Branch extends string = string> = (props: IWizardProviderProps<Step, Category, Branch>) => void;
+declare function composeWizardProviders<Step extends string, Category extends string, Branch extends string = string>(...mods: Array<WizardProviderMod<Step, Category, Branch>>): IWizardProviderProps<Step, Category, Branch>;
+declare const withConfig: <Step extends string = string, Category extends string = string, Branch extends string = string>(options: Partial<IWizardConfigOptions<Category>>) => WizardProviderMod<Step, Category, Branch>;
+declare const withInitializer: <Step extends string, Category extends string, Branch extends string = string>(initializer: WizardInitializer<Step, Category, Branch>) => WizardProviderMod<Step, Category, Branch>;
+declare const withListener: <Step extends string, Category extends string, Branch extends string = string>(listener: WizardListener<Step, Category, Branch>) => WizardProviderMod<Step, Category, Branch>;
+declare const withScrollStrategy: <Step extends string, Category extends string, Branch extends string = string>(strategy: WizardScrollStrategy<Step, Category, Branch>) => WizardProviderMod<Step, Category, Branch>;
+/**
+ * Point the wizard's scroll strategy at a specific element instead of the
+ * window. Pass a getter when the container lives behind a React ref so the
+ * element resolves at scroll time, after commit.
+ */
+declare const withScrollContainer: <Step extends string = string, Category extends string = string, Branch extends string = string>(container: WizardScrollContainer) => WizardProviderMod<Step, Category, Branch>;
+declare const withProgressStrategy: <Step extends string, Category extends string, Branch extends string = string>(strategy: WizardProgressStrategy<Step, Category, Branch>) => WizardProviderMod<Step, Category, Branch>;
+declare const withVisibilityStrategy: <Step extends string, Category extends string, Branch extends string = string>(strategy: WizardVisibilityStrategy<Step, Category, Branch>) => WizardProviderMod<Step, Category, Branch>;
+
+declare class WizardError extends Error {
+    readonly name: string;
+    constructor(message?: string);
+}
+declare class WizardInitializationError extends WizardError {
+    readonly name: string;
+}
+declare class WizardNavigationError extends WizardError {
+    readonly name: string;
+}
+declare class WizardResolverError extends WizardError {
+    readonly name: string;
+}
+
+/**
+ * Minimal structural shape of `WizardConfig` consumed by `WizardLog` —
+ * it reads `enableTracing` and `silenceErrors` only. Phase 7's `WizardConfig`
+ * class structurally satisfies this interface (it exposes `getOptions()`).
+ */
+interface IWizardLogConfigLike {
+    getOptions(): Pick<IWizardConfigOptions, 'enableTracing' | 'silenceErrors'>;
+}
+/**
+ * Console-based logger. Respects `config.enableTracing` for `trace()` and
+ * `config.silenceErrors` for `WizardError` instances.
+ */
+declare class WizardLog {
+    private readonly wizardConfig;
+    constructor(wizardConfig: IWizardLogConfigLike);
+    error(e: unknown): void;
+    trace(...args: unknown[]): void;
+}
+
+/**
+ * Runs the registered initializer chain on top of the HTML-derived tree to
+ * produce the boot state. Validates step uniqueness and active-branch presence
+ * before delegating to the chain.
+ */
+declare class WizardInitializerService<Step extends string, Category extends string, Branch extends string = string> {
+    private readonly wizardLog;
+    private readonly wizardInitializers;
+    constructor(wizardLog: WizardLog, wizardInitializers: ReadonlyArray<WizardInitializer<Step, Category, Branch>>);
+    getInitialState(state: ReadonlyArray<IWizardStepState<Step, Category, Branch>>, activeBranch?: Branch): Promise<Readonly<IWizardTreeState<Step, Category, Branch>>>;
+    private validateActiveBranch;
+    private validateHtmlTree;
+}
+
+type ConfigListener<Category extends string> = (config: Readonly<IWizardConfigOptions<Category>>) => void;
+/**
+ * Holds the merged wizard config and notifies subscribers on change.
+ *
+ * Multiple `setOptions` calls within one microtask coalesce into a single
+ * notification.
+ */
+declare class WizardConfig<Category extends string = string> {
+    /**
+     * Whether the wizard is rendering on a mobile viewport. Used by the default
+     * visibility and scroll strategies. The React adapter (Phase 15) updates this
+     * via a media-query subscription; in plain Node (tests/SSR), it stays `false`.
+     */
+    isMobile: boolean;
+    get options(): Readonly<IWizardConfigOptions<Category>>;
+    private current;
+    private disposed;
+    private readonly listeners;
+    private notifyScheduled;
+    constructor(overrides?: Partial<IWizardConfigOptions<Category>>);
+    dispose(): void;
+    getOptions(): Readonly<IWizardConfigOptions<Category>>;
+    setOptions(options: Partial<IWizardConfigOptions<Category>>): this;
+    subscribe(listener: ConfigListener<Category>): () => void;
+    private scheduleNotify;
+}
+
+type StoreListener = () => void;
+/**
+ * Holds the current wizard tree, exposes a `useSyncExternalStore`-shaped
+ * subscription, and gates `setState` calls behind `init()`.
+ */
+declare class WizardStore<Step extends string, Category extends string, Branch extends string = string> {
+    private readonly storagePrefix?;
+    readonly initOnce: Promise<Readonly<IWizardTreeState<Step, Category, Branch>>>;
+    get shapeId(): string;
+    private _shapeId;
+    private current;
+    private disposed;
+    private initialTree;
+    private readonly listeners;
+    private resolveInitOnce;
+    constructor(storagePrefix?: number | string | undefined);
+    dispose(): void;
+    getTreeSnapshot(): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    init(initialTree: Readonly<IWizardTreeState<Step, Category, Branch>>): void;
+    setState(tree: Readonly<IWizardTreeState<Step, Category, Branch>>): void;
+    subscribe: (listener: StoreListener) => (() => void);
+}
+
+/**
+ * Pure-ish next-tree computations. Each method returns a target tree (or a
+ * terminal exit/complete subtype) without mutating the store. Methods accept an
+ * optional `tree` argument; when omitted they read from the store's current
+ * snapshot.
+ */
+type WizardStateResult<Step extends string, Category extends string, Branch extends string> = Readonly<IWizardTreeState<Step, Category, Branch>> | WizardCompleteTreeState<Step, Category, Branch> | WizardExitTreeState<Step, Category, Branch>;
+declare class WizardStateService<Step extends string, Category extends string, Branch extends string = string> {
+    private readonly wizardStore;
+    private readonly wizardConfig;
+    constructor(wizardStore: WizardStore<Step, Category, Branch>, wizardConfig: WizardConfig<Category>);
+    completeCategory(category: Category, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    goToCategory(categoryId: Category, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    hideCategory(categoryId: Category, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    hideStep(step: Step, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    next(branch?: Branch | null, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    nextCategory(branch?: Branch | null, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    prev(tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    prevCategory(tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    resetCategory(category: Category, from?: number, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    resetTree(tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    showCategory(categoryId: Category, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    showStep(step: Step, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): Readonly<IWizardTreeState<Step, Category, Branch>>;
+    skipCategory(category: Category, tree?: Readonly<IWizardTreeState<Step, Category, Branch>>): WizardStateResult<Step, Category, Branch>;
+    private currentTree;
+    private projectShownCategory;
+    private projectShownStep;
+}
+
+/**
+ * Async navigation pipeline. Each `navigate()` (or `showStep` / `hideStep` /
+ * `exitWizard` / `completeWizard`) emits a strict ordering of events:
+ *
+ *   NavigationStart → ResolveStart → resolver chain → ResolveEnd → setState →
+ *   StepShow/StepHide (visibility flips) → ScrollStart → scroll strategy →
+ *   ScrollEnd → NavigationEnd (or Exit/Complete for terminals)
+ *
+ * Race semantics: a new navigate() while another is in flight aborts the prior
+ * one (emits `NavigationCancelled('new_navigation')` and resolves the prior
+ * Promise to `false`). Resolver returning `false` or rejecting emits
+ * `NavigationCancelled('resolver')`. Resolver throwing emits `NavigationError`.
+ */
+declare class WizardNavigationService<Step extends string, Category extends string, Branch extends string = string> {
+    private readonly wizardStore;
+    private readonly wizardConfig;
+    private readonly wizardStateService;
+    private readonly wizardScrollStrategy;
+    get isNavigating(): boolean;
+    private disposed;
+    private readonly emitter;
+    private inFlight;
+    private prevSuccessId;
+    constructor(wizardStore: WizardStore<Step, Category, Branch>, wizardConfig: WizardConfig<Category>, wizardStateService: WizardStateService<Step, Category, Branch>, wizardScrollStrategy: WizardScrollStrategy<Step, Category, Branch>);
+    completeWizard(): Promise<boolean>;
+    dispose(): void;
+    exitWizard(): Promise<boolean>;
+    hideCategory(categoryId: Category): Promise<boolean>;
+    hideStep(step: Step | Step[]): Promise<boolean>;
+    navigate(to: WizardStateResult<Step, Category, Branch>): Promise<boolean>;
+    on(type: '*' | WizardEvent<Step, Category, Branch>['type'], handler: (event: WizardEvent<Step, Category, Branch>) => void): () => void;
+    showCategory(categoryId: Category): Promise<boolean>;
+    showStep(step: Step | Step[]): Promise<boolean>;
+    private commitTree;
+    private emitVisibilityFlips;
+    private hide;
+    private invokeResolver;
+    private isAbortReason;
+    private projectTree;
+    private runResolverChain;
+    private show;
+}
+
+type Listener<E> = (event: E) => void;
+/**
+ * Tiny typed event emitter. Subscribers can listen to a specific event type
+ * (matched on `event.type`) or via the `'*'` wildcard. Returns an unsubscribe
+ * handle from `on()`.
+ */
+declare class TypedEmitter<E extends {
+    type: string;
+}> {
+    private readonly map;
+    dispose(): void;
+    emit(event: E): void;
+    on(type: '*' | E['type'], handler: Listener<E>): () => void;
+}
+
+/**
+ * Base contract every wizard tree-state rule must implement.
+ *
+ * Rules run on every freshly built tree before it's published; any rule that
+ * fails throws a `WizardError`, aborting the build. This keeps invariants
+ * (single active category, no skipped-but-active step, etc.) checked centrally.
+ */
+declare abstract class WizardRule {
+    abstract verify(tree: Readonly<IWizardTreeState<string, string>>): never | void;
+}
+
+declare class WizardActiveStepRule extends WizardRule {
+    verify({ lastActiveStep }: Readonly<IWizardTreeState<string, string>>): void;
+}
+
+declare class WizardPassedPrevCategoriesRule extends WizardRule {
+    verify({ activeBranch, activeCategory }: Readonly<IWizardTreeState<string, string>>): void;
+}
+
+declare class WizardPassedPrevStepsRule extends WizardRule {
+    verify({ activeCategory }: Readonly<IWizardTreeState<string, string>>): void;
+}
+
+/**
+ * Default rule chain run by `WizardTreeStateBuilder.validate(tree)` on every build.
+ */
+declare const wizardRules: WizardRule[];
+
+declare class WizardShownActiveCategoryRule extends WizardRule {
+    verify({ activeCategory }: Readonly<IWizardTreeState<string, string>>): void;
+}
+
+declare class WizardSingleActiveCategoryRule extends WizardRule {
+    verify({ activeBranch }: Readonly<IWizardTreeState<string, string>>): void;
+}
+
+declare const wizardDefaultConfig: IWizardConfigOptions;
+
+declare enum WizardCategoryDirection {
+    Backward = "backward",
+    Forward = "forward"
+}
+
+interface IWizardBackComponentProps {
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Back button. Calls `wizard.back()` on click. Wrap a custom button via
+ * `asChild` to compose with shadcn variants.
+ */
+declare function WizardBack(props: IWizardBackComponentProps): react_jsx_runtime.JSX.Element;
+
+interface IWizardCategoryComponentProps<Category extends string> {
+    categoryId: Category;
+    children: ReactNode;
+}
+/**
+ * Wrapper that renders its children only while the named category is active.
+ */
+declare function WizardCategory<Category extends string>(props: IWizardCategoryComponentProps<Category>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Default wizard header — renders an optional back button and the visual
+ * stepper. Gates on `config.isShowWizardHeader`, reserves space when the back
+ * button is hidden, and forwards click handlers that delegate to
+ * `wizard.goToCategory` / `wizard.resetCategory`.
+ */
+declare function WizardHeader<Category extends string = string>(): react_jsx_runtime.JSX.Element | null;
+
+interface IWizardNextComponentProps {
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * Next button. Calls `wizard.next()` on click. Use `asChild` to compose with a
+ * custom button.
+ *
+ * The default label is contextual:
+ * - `nextBtnText` (default "Next") within a category
+ * - `nextCategoryText` (default "Continue") on the last step of a non-final category
+ * - `finishText` (default "Finish") on the last step of the last category
+ */
+declare function WizardNext(props: IWizardNextComponentProps): react_jsx_runtime.JSX.Element;
+
+interface IWizardCategoryView<Step extends string, Category extends string> {
+    id: Category;
+    isActive: boolean;
+    state: WizardCategoryViewState;
+    subSteps: ReadonlyArray<{
+        id: Step;
+        isActive: boolean;
+    }>;
+}
+type WizardCategoryViewState = 'active' | 'completed' | 'pending' | 'skipped';
+/**
+ * Projects the wizard's active branch into a normalized list for navigation
+ * surfaces (rail, stepper). Pure projection — re-renders on tree change via
+ * `useWizard`.
+ */
+declare function useWizardCategoriesView<Step extends string, Category extends string, Branch extends string = string>(): ReadonlyArray<IWizardCategoryView<Step, Category>>;
+
+interface IWizardRailProps<Step extends string, Category extends string> {
+    canAccessCategory?: (category: IWizardCategoryView<Step, Category>) => boolean;
+    className?: string;
+    headerI18n?: Partial<Record<Category, ReactNode>>;
+    subStepLabels?: Partial<Record<Step, ReactNode>>;
+}
+/**
+ * Vertical category rail for full-page wizard layouts. Renders one button per
+ * shown category with dot state, expands the active category to surface its
+ * sub-steps when present, and dispatches `wizard.goToCategory` on click.
+ *
+ * Pure consumer of `useWizard` — no local state.
+ */
+declare function WizardRail<Step extends string, Category extends string, Branch extends string = string>(props: IWizardRailProps<Step, Category>): react_jsx_runtime.JSX.Element;
+
+interface IWizardStepComponentProps<Step extends string> {
+    children: ReactNode;
+    id: Step;
+}
+/**
+ * Renders children only when the active visibility strategy reports the step
+ * as visible. Delegates to `WizardEngine.isStepVisible(id)` so swapping the
+ * strategy via `withVisibilityStrategy(...)` actually changes mount behavior.
+ */
+declare function WizardStep<Step extends string>(props: IWizardStepComponentProps<Step>): react_jsx_runtime.JSX.Element | null;
+
+type WizardStepperDotState = 'active' | 'completed' | 'pending' | 'skipped';
+interface IWizardStepperDotProps {
+    clickable?: boolean;
+    isLast?: boolean;
+    label?: string;
+    onClick?: () => void;
+    progress: number;
+    state: WizardStepperDotState;
+}
+/**
+ * Single dot in `WizardStepper`. Renders a 12px circle with a trailing track
+ * fill (sized by `progress` 0-100) unless `isLast`. Optional label sits above.
+ *
+ * Visual states map to project semantic status tokens
+ * (`success-bg`, `success-text`, `success-border`, `border`, `muted-foreground`).
+ */
+declare function WizardStepperDot(props: IWizardStepperDotProps): react_jsx_runtime.JSX.Element;
+
+interface IWizardStepperProps<Category extends string> {
+    canAccessCategory?: (category: IWizardCategoryState<string, Category, string>) => boolean;
+    categories: ReadonlyArray<IWizardCategoryState<string, Category, string>>;
+    doneDot?: {
+        text: string;
+    };
+    headerI18n?: null | Record<Category, string>;
+    onCategoryClick?: (category: IWizardCategoryState<string, Category, string>) => void;
+    progress: Record<Category, number>;
+}
+/**
+ * Pure-presentational horizontal stepper. Renders one `WizardStepperDot` per
+ * category with the per-category progress fill on the trailing track, plus an
+ * optional trailing "done" dot.
+ */
+declare function WizardStepper<Category extends string>(props: IWizardStepperProps<Category>): react_jsx_runtime.JSX.Element;
+
+/**
+ * React context exposing the active `WizardEngine` instance to descendants.
+ * `null` outside a `<WizardProvider>` — `useWizard()` throws a clear error.
+ */
+declare const WizardEngineContext: react.Context<WizardEngine<string, string, string> | null>;
+
+interface IWizardProviderComponentProps<Step extends string, Category extends string, Branch extends string = string> extends Partial<IWizardProviderProps<Step, Category, Branch>> {
+    activeBranch?: Branch;
+    children: ReactNode;
+    state: ReadonlyArray<IWizardStepState<Step, Category, Branch>>;
+}
+/**
+ * Top-level wizard provider. Captures the boot options once via lazy
+ * `useState`, then constructs a fresh `WizardEngine` inside an effect so React
+ * 19 Strict Mode's mount/unmount/remount cycle does not leave a permanently
+ * disposed engine in shared state. The engine is disposed on unmount.
+ *
+ * Idiomatic shape:
+ * ```tsx
+ * <WizardProvider state={...} {...composeWizardProviders(withConfig(...))}>
+ *   <WizardLayout>...</WizardLayout>
+ * </WizardProvider>
+ * ```
+ */
+declare function WizardProvider<Step extends string, Category extends string, Branch extends string = string>(props: IWizardProviderComponentProps<Step, Category, Branch>): react_jsx_runtime.JSX.Element | null;
+
+interface IWizardEngineRefCaptureProps<Step extends string, Category extends string> {
+    engineRef: RefObject<null | WizardEngine<Step, Category>>;
+}
+/**
+ * Holds a ref to the live `WizardEngine`. Place `<WizardEngineRefCapture
+ * engineRef={ref} />` inside `<WizardProvider>` so a form's submit handler
+ * (which sits outside the provider) can navigate the wizard programmatically.
+ */
+declare function useWizardEngineRef<Step extends string, Category extends string>(): RefObject<null | WizardEngine<Step, Category>>;
+declare function WizardEngineRefCapture<Step extends string, Category extends string>({ engineRef, }: IWizardEngineRefCaptureProps<Step, Category>): null;
+
+type WildcardOrType<E extends {
+    type: string;
+}> = '*' | E['type'];
+/**
+ * Subscribe to a wizard event type (or all events with `'*'`). The handler is
+ * stored in a ref so updating it across renders doesn't resubscribe — the
+ * subscription is bound to the type only.
+ */
+declare function useWizardEvent<Step extends string, Category extends string, Branch extends string = string>(type: WildcardOrType<WizardEvent<Step, Category, Branch>>, handler: (event: WizardEvent<Step, Category, Branch>) => void): void;
+
+/**
+ * Subscribe to a single step's state. Re-renders only when this step's slice
+ * changes (compared by `Object.is` on each flag). Returns the step state, or
+ * `null` if the engine doesn't know about this id.
+ */
+declare function useWizardStep<Step extends string, Category extends string = string, Branch extends string = string>(stepId: Step): IWizardStepState<Step, Category, Branch> | null;
+
+/**
+ * Returns the active `WizardEngine` instance and re-renders the consumer on
+ * every tree change. Throws if used outside a `<WizardProvider>`.
+ *
+ * Engine identity is stable across renders.
+ */
+declare function useWizard<Step extends string, Category extends string, Branch extends string = string>(): WizardEngine<Step, Category, Branch>;
+
+export { type IWizardBranchState, type IWizardCategoryState, type IWizardConfigOptions, type IWizardEntityState, type IWizardInitTreeState, type IWizardProgressConfigLike, type IWizardProgressLogLike, type IWizardProviderProps, type IWizardResolverHook, type IWizardScrollConfigLike, type IWizardStepOptions, type IWizardStepState, type IWizardTreeState, type IWizardVisibilityConfigLike, TypedEmitter, WizardActiveProgressStrategy, WizardActiveStepRule, WizardBack, WizardCategory, WizardCategoryDirection, WizardCompleteEvent, WizardCompleteTreeState, WizardConfig, WizardDefaultInitializer, WizardDefaultVisibilityStrategy, WizardEngine, WizardEngineContext, type WizardEngineOptions, WizardEngineRefCapture, type WizardEngineStepRegistration, type WizardEngineStrategies, WizardError, WizardEvent, WizardEventType, WizardExitEvent, WizardExitTreeState, WizardHeader, WizardInitializationError, WizardInitializer, WizardInitializerService, WizardLastActiveVisibilityStrategy, WizardListener, WizardLog, WizardNavigation, WizardNavigationCancelledEvent, WizardNavigationEndEvent, WizardNavigationError, WizardNavigationErrorEvent, WizardNavigationIgnoredEvent, WizardNavigationService, WizardNavigationStartEvent, WizardNext, WizardPassedPrevCategoriesRule, WizardPassedPrevStepsRule, WizardProgressStrategy, WizardProvider, type WizardProviderMod, WizardRail, WizardResolveEndEvent, WizardResolveStartEvent, WizardResolverError, WizardRule, type WizardScrollContainer, WizardScrollEndEvent, WizardScrollStartEvent, WizardScrollStrategy, WizardShownActiveCategoryRule, WizardSingleActiveCategoryRule, WizardSmoothScrollStrategy, type WizardStateResult, WizardStateService, WizardStep, WizardStepHideEvent, WizardStepShowEvent, WizardStepper, WizardStepperDot, type WizardStepperDotState, WizardStore, WizardTreeStateBuilder, WizardVisibilityStrategy, buildWizardBranchState, buildWizardCategoryState, buildWizardTreeState, composeWizardProviders, scrollToStep, useWizard, useWizardCategoriesView, useWizardEngineRef, useWizardEvent, useWizardStep, withConfig, withInitializer, withListener, withProgressStrategy, withScrollContainer, withScrollStrategy, withVisibilityStrategy, wizardDefaultBranch, wizardDefaultConfig, wizardDefaultState, wizardRules };