/**
 * vapor-chamber — Core plugins (sync)
 *
 * logger, validator, history, debounce, throttle, authGuard, optimistic, optimisticUndo
 */
import type { Command, Plugin, CommandBus } from './command-bus';
/**
 * Logger plugin - logs all commands and results
 *
 * Successful dispatches log at 'info', failed dispatches at 'error'.
 * The default `level: 'info'` shows both (unchanged output); raise it to
 * 'warn' or 'error' to hide successful dispatches and only see failures.
 *
 * @example
 * bus.use(logger()); // ⚡ cartAdd — everything, as before
 *
 * @example
 * // Failures only, with fixed-width [  OK  ] / [ FAIL ] badges
 * // (colored via %c in browsers, plain brackets in Node)
 * bus.use(logger({ level: 'error', badges: true }));
 */
export declare function logger(options?: {
    collapsed?: boolean;
    filter?: (cmd: Command) => boolean;
    /** Minimum level to log. Ok results log at 'info', failures at 'error'. Default: 'info'. */
    level?: 'debug' | 'info' | 'warn' | 'error';
    /** Prefix the group label with a fixed-width [  OK  ] / [ FAIL ] badge. Default: false. */
    badges?: boolean;
}): Plugin;
/**
 * Validator plugin - validate commands before execution
 */
export declare function validator(rules: {
    [action: string]: (cmd: Command) => string | null;
}): Plugin;
/**
 * History plugin - tracks command history for undo/redo
 *
 * v0.3.0: undo() now executes the inverse handler if the command was
 * registered with { undo: fn } via bus.register(). Falls back to
 * data-only pop if no inverse handler exists.
 */
export interface HistoryState {
    past: Command[];
    future: Command[];
    canUndo: boolean;
    canRedo: boolean;
}
export declare function history(options?: {
    maxSize?: number;
    filter?: (cmd: Command) => boolean;
    /** Reference to the command bus — enables undo() to execute inverse handlers */
    bus?: CommandBus;
    /**
     * Action name to register as the undo trigger (e.g. 'cart.undo'). The plugin
     * registers the bus handler itself and ALWAYS excludes this action from
     * recording — even if `filter` would match it. Without this, a hand-wired
     * `bus.register('cart.undo', () => h.undo())` records the trigger command
     * into history (clearing the redo stack and burying real entries), so undo
     * works once and redo never enables. Requires `bus`.
     */
    undoAction?: string;
    /** Action name to register as the redo trigger. Same semantics as undoAction. */
    redoAction?: string;
}): Plugin & {
    getState: () => HistoryState;
    undo: () => Command | undefined;
    redo: () => Command | undefined;
    clear: () => void;
    /** Unregister the undoAction/redoAction bus handlers (no-op if none). */
    dispose: () => void;
};
/**
 * Debounce plugin - debounce specific actions
 *
 * v0.3.0 FIX: Stores the latest next() closure and re-invokes it after the
 * debounce period. Returns { pending: true } synchronously.
 */
export declare function debounce(actions: string[], wait: number): Plugin & {
    dispose(): void;
};
/**
 * Throttle plugin - execute immediately, then block for wait period
 */
export declare function throttle(actions: string[], wait: number): Plugin & {
    dispose(): void;
};
/**
 * Auth guard plugin - blocks protected commands when not authenticated.
 */
export declare function authGuard(options: {
    isAuthenticated: () => boolean;
    protected: string[];
    onUnauthenticated?: (cmd: Command) => void;
}): Plugin;
/**
 * Optimistic update plugin - apply optimistic state, rollback on failure.
 *
 * Accepts per-action `apply` functions that optimistically mutate state
 * and return a rollback closure. If the handler (or async resolution) fails,
 * the rollback is called automatically.
 *
 * @example
 * bus.use(optimistic({
 *   cartAdd: { apply: (cmd) => { addItem(cmd.target); return () => removeItem(cmd.target); } },
 * }));
 */
export declare function optimistic(handlers: Record<string, {
    apply: (cmd: Command) => (() => void) | null;
}>): Plugin;
export type OptimisticUndoOptions = {
    /**
     * Predict the optimistic result returned immediately to the caller.
     * If omitted, returns `{ ok: true, value: undefined }` as the optimistic result.
     */
    predict?: (cmd: Command) => any;
    /**
     * Called when the real handler fails and the undo handler runs.
     * Use this to notify the UI of the rollback (e.g. show a toast).
     */
    onRollback?: (cmd: Command, error: Error) => void;
    /**
     * Called when the undo handler itself throws during rollback.
     * If omitted, errors are logged to console.error.
     */
    onRollbackError?: (cmd: Command, undoError: Error, originalError: Error) => void;
};
/**
 * Optimistic dispatch plugin that auto-rollbacks using the bus's registered undo handlers.
 *
 * Unlike `optimistic()`, this plugin does **not** require separate `apply`/rollback
 * closures — it uses the undo handler already registered via `register(action, handler, { undo })`.
 *
 * **How it works on an async bus:**
 * 1. Immediately returns `{ ok: true, value: predict(cmd) }` to the caller.
 * 2. The real handler runs in the background.
 * 3. If the real handler fails, the registered undo handler is called automatically.
 *
 * **On a sync bus:** behaves like the regular `optimistic()` — runs handler synchronously,
 * rolls back via undo handler if it fails.
 *
 * **Requires** undo handlers to be registered for the targeted actions.
 * Actions without undo handlers are passed through unchanged.
 *
 * @example
 * bus.register('cartAdd', addToCart, { undo: removeFromCart });
 * bus.use(optimisticUndo(bus, ['cartAdd'], {
 *   predict: (cmd) => ({ id: cmd.target.id, qty: cmd.payload.qty }),
 *   onRollback: (cmd, err) => toast.error(`Failed to add item: ${err.message}`),
 * }));
 * // dispatch returns immediately with predicted result
 * const result = await bus.dispatch('cartAdd', { id: 5 }, { qty: 2 });
 * // result.ok === true, result.value === { id: 5, qty: 2 }
 */
export declare function optimisticUndo(bus: CommandBus, actions: string[], options?: OptimisticUndoOptions): Plugin;
//# sourceMappingURL=plugins-core.d.ts.map