@okyrychenko-dev/react-action-guard 1.0.5 → 2.0.0

package/dist/index.d.cts

@@ -1,8 +1,9 @@
 import { ReactNode } from 'react';
 import * as zustand from 'zustand';
 import { StoreApi } from 'zustand';
+import { Optional } from '@okyrychenko-dev/type-utils';
 
-type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
+type AnalyticsEventData = Record<string, Optional<string | number | ReadonlyArray<string>>>;
 type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
 interface GoogleAnalyticsConfig {
     provider: "ga";
@@ -18,39 +19,32 @@ interface CustomAnalyticsConfig {
 }
 type AnalyticsConfig = GoogleAnalyticsConfig | MixpanelConfig | AmplitudeConfig | CustomAnalyticsConfig;
 
+/** An immutable point-in-time blocker projection. */
+type BlockingLifecycleSnapshot = ReadonlyArray<Readonly<BlockerInfo>>;
+/** Read snapshots and observe lifecycle changes without transition authority. */
+interface BlockingLifecycleObservation {
+    getSnapshot: () => BlockingLifecycleSnapshot;
+    subscribe: (listener: (snapshot: BlockingLifecycleSnapshot) => void) => VoidFunction;
+    observe: (observer: Middleware) => VoidFunction;
+}
+interface BlockingLifecycle extends BlockingLifecycleObservation {
+    add: (id: string, config?: BlockerConfig) => void;
+    update: (id: string, config?: Partial<BlockerConfig>) => void;
+    replace: (id: string, config: BlockerConfig) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+    clearScope: (scope: string) => void;
+    isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
+    getBlockingInfo: (scope: string) => BlockingLifecycleSnapshot;
+}
+type BlockingEvent = MiddlewareContext;
+
+/** Owns one independent store's blockers, timers, snapshots, and transition events. */
+declare function createBlockingLifecycle(): BlockingLifecycle;
+
 /**
  * Configuration options for creating or updating a blocker.
  *
- * All fields are optional. Defaults will be applied for any missing values:
- * - `scope`: "global"
- * - `reason`: "Blocking UI"
- * - `priority`: 50
- * - `timestamp`: Current time
- *
- * @example
- * Basic configuration
- * ```ts
- * const config: BlockerConfig = {
- *   scope: 'form',
- *   reason: 'Submitting data...',
- *   priority: 70
- * };
- * ```
- *
- * @example
- * With timeout and callback
- * ```ts
- * const config: BlockerConfig = {
- *   scope: ['form', 'navigation'],
- *   reason: 'Critical operation in progress',
- *   priority: 90,
- *   timeout: 30000, // 30 seconds
- *   onTimeout: (id) => {
- *     console.warn(`Blocker ${id} timed out`);
- *   }
- * };
- * ```
- *
  * @public
  * @since 0.6.0
  */
@@ -60,153 +54,65 @@ interface BlockerConfig {
     /** Priority level (negative values are normalized to 0) */
     priority?: number;
     timestamp?: number;
-    /** Automatically remove the blocker after N milliseconds */
-    timeout?: number;
-    /** Callback invoked when the blocker is automatically removed due to timeout */
-    onTimeout?: (blockerId: string) => void;
-}
-/**
- * Internal representation of a blocker with all fields populated.
- *
- * This is the stored format in the Map. All optional fields from {@link BlockerConfig}
- * are converted to required fields with default values applied.
- *
- * @internal This type is primarily for internal use. Users should work with
- *           {@link BlockerConfig} for configuration and {@link BlockerInfo} for
- *           reading blocker data.
- *
- * @since 0.6.0
- */
-interface StoredBlocker {
-    scope: string | ReadonlyArray<string>;
-    reason: string;
-    priority: number;
-    timestamp: number;
-    /** Timeout duration in milliseconds (if set) */
+    /**
+     * Remove after a positive finite delay in milliseconds, using bounded timer chunks.
+     * Omitted, zero and finite negative values disable expiration. Invalid/nonfinite values
+     * or a deadline beyond Number.MAX_SAFE_INTEGER throw RangeError before mutation.
+     */
     timeout?: number;
-    /** Internal timeout ID for cleanup */
-    timeoutId?: ReturnType<typeof setTimeout>;
     /** Callback invoked when the blocker is automatically removed due to timeout */
     onTimeout?: (blockerId: string) => void;
 }
 /**
  * Complete blocker information including its unique identifier.
  *
- * This type extends {@link StoredBlocker} with the blocker's ID, making it
- * suitable for reading and displaying blocker information. Returned by
- * {@link UIBlockingStoreActions.getBlockingInfo} and used by {@link useBlockingInfo}.
- *
- * @example
- * Accessing blocker info
- * ```ts
- * const blockers: BlockerInfo[] = store.getState().getBlockingInfo('form');
- * blockers.forEach(blocker => {
- *   console.log(`${blocker.id}: ${blocker.reason} (priority: ${blocker.priority})`);
- * });
- * ```
- *
  * @public
  * @since 0.6.0
  */
-interface BlockerInfo extends Omit<StoredBlocker, "timeoutId"> {
-    id: string;
+interface BlockerInfo {
+    readonly id: string;
+    readonly scope: string | ReadonlyArray<string>;
+    readonly reason: string;
+    readonly priority: number;
+    readonly timestamp: number;
+    readonly timeout?: number;
+    readonly onTimeout?: (blockerId: string) => void;
 }
-/**
- * Internal state structure of the UI blocking store.
- *
- * Contains the core data structures for managing blockers and middleware.
- * This state is combined with {@link UIBlockingStoreActions} to create the
- * complete {@link UIBlockingStore} type.
- *
- * @internal
- * @since 0.6.0
- */
+/** Immutable projection published by the Zustand adapter. */
 interface UIBlockingStoreState {
-    activeBlockers: Map<string, StoredBlocker>;
-    middlewares: Map<string, Middleware>;
+    readonly blockingSnapshot: BlockingLifecycleSnapshot;
 }
 /**
  * All available actions for managing UI blocking state.
  *
- * These methods allow adding, removing, updating blockers, checking blocking status,
- * and managing middleware. Combined with {@link UIBlockingStoreState} to form
- * the complete {@link UIBlockingStore} type.
- *
- * All actions are safe to call multiple times and handle edge cases gracefully.
- *
- * @example
- * Using store actions directly
- * ```ts
- * import { uiBlockingStoreApi } from '@okyrychenko-dev/react-action-guard';
- *
- * // Add a blocker
- * uiBlockingStoreApi.getState().addBlocker('my-blocker', {
- *   scope: 'form',
- *   reason: 'Processing...'
- * });
- *
- * // Check if blocked
- * const isBlocked = uiBlockingStoreApi.getState().isBlocked('form');
- *
- * // Remove blocker
- * uiBlockingStoreApi.getState().removeBlocker('my-blocker');
- * ```
- *
  * @public
  * @since 0.6.0
  */
 interface UIBlockingStoreActions {
     addBlocker: (id: string, config?: BlockerConfig) => void;
     updateBlocker: (id: string, config?: Partial<BlockerConfig>) => void;
+    /** @internal Apply current reactive configuration, clearing omitted optional fields. */
+    replaceBlocker: (id: string, config: BlockerConfig) => void;
     removeBlocker: (id: string) => void;
     isBlocked: (scope?: string | ReadonlyArray<string>) => boolean;
-    getBlockingInfo: (scope: string) => ReadonlyArray<BlockerInfo>;
+    getBlockingInfo: (scope: string) => ReadonlyArray<Readonly<BlockerInfo>>;
     clearAllBlockers: VoidFunction;
     clearBlockersForScope: (scope: string) => void;
-    registerMiddleware: (name: string, middleware: Middleware) => void;
-    unregisterMiddleware: (name: string) => void;
-    runMiddlewares: (context: MiddlewareContext) => Promise<void>;
+    /** Observe lifecycle transitions through an anonymous, ownership-safe lease. */
+    observeBlockingEvents: (observer: Middleware) => VoidFunction;
 }
 /**
  * Complete UI blocking store type combining state and actions.
  *
- * This is the full store interface used by hooks like {@link useUIBlockingStore}
- * and accessible via {@link uiBlockingStoreApi}. It combines all state properties
- * from {@link UIBlockingStoreState} with all action methods from {@link UIBlockingStoreActions}.
- *
- * @example
- * Using the complete store
- * ```ts
- * import { useUIBlockingStore } from '@okyrychenko-dev/react-action-guard';
- *
- * function MyComponent() {
- *   const store = useUIBlockingStore();
- *
- *   // Access state
- *   console.log(store.activeBlockers.size);
- *
- *   // Call actions
- *   store.addBlocker('my-blocker', { scope: 'form' });
- *
- *   return <div>...</div>;
- * }
- * ```
- *
  * @public
  * @since 0.6.0
  */
 type UIBlockingStore = UIBlockingStoreState & UIBlockingStoreActions;
-interface ShallowStoreBindings<StoreState> {
-    useStore: {
-        (): StoreState;
-        <T>(selector: (state: StoreState) => T): T;
-    };
-    useStoreApi: StoreApi<StoreState>;
-}
 
 type BlockingAction = "add" | "update" | "remove" | "timeout" | "clear" | "clear_scope";
 type MiddlewareBlockerConfig = BlockerConfig;
 interface MiddlewareContext {
+    registration?: object;
     action: BlockingAction;
     blockerId: string;
     config?: MiddlewareBlockerConfig;
@@ -220,281 +126,68 @@ type Middleware = (context: MiddlewareContext) => void | Promise<void>;
 /**
  * Creates middleware for tracking blocker events to analytics platforms.
  *
- * Automatically tracks all blocker actions (add, remove, update, timeout, clear)
- * to your analytics platform. Supports Google Analytics, Mixpanel, Amplitude,
- * and custom analytics providers.
- *
- * Event data includes: blockerId, action, scope, reason, priority, timestamp,
- * and duration (for remove events).
- *
- * @param config - Analytics configuration specifying provider and credentials
- *
- * @example
- * Google Analytics integration
- * ```ts
- * import { configureMiddleware, createAnalyticsMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * const analyticsMiddleware = createAnalyticsMiddleware({
- *   provider: 'ga',
- *   trackingId: 'GA-XXXXX-Y'
- * });
- *
- * configureMiddleware([analyticsMiddleware]);
- * ```
- *
- * @example
- * Mixpanel integration
- * ```ts
- * const analyticsMiddleware = createAnalyticsMiddleware({
- *   provider: 'mixpanel',
- *   token: 'your_mixpanel_token',
- *   options: {
- *     debug: true
- *   }
- * });
- *
- * configureMiddleware([analyticsMiddleware]);
- * ```
- *
- * @example
- * Custom analytics provider
- * ```ts
- * const analyticsMiddleware = createAnalyticsMiddleware({
- *   track: (eventName, eventData) => {
- *     // Send to your custom analytics
- *     myAnalytics.track(eventName, {
- *       ...eventData,
- *       userId: getCurrentUserId()
- *     });
- *   }
- * });
- * ```
- *
- * @example
- * Amplitude with user properties
- * ```ts
- * const analyticsMiddleware = createAnalyticsMiddleware({
- *   provider: 'amplitude',
- *   apiKey: 'your_amplitude_key',
- *   userId: 'user-123',
- *   userProperties: {
- *     plan: 'premium',
- *     role: 'admin'
- *   }
- * });
- * ```
- *
- * @see {@link AnalyticsConfig} for configuration options
- * @see {@link configureMiddleware} for registering middleware
- *
  * @public
  * @since 0.6.0
+ * @see {@link AnalyticsConfig} for configuration options
+ * @see {@link configureMiddleware} for registering middleware
  */
 declare function createAnalyticsMiddleware(config: AnalyticsConfig): Middleware;
 
-/**
- * Configures and registers multiple middleware functions for the UI blocking store.
- *
- * Convenience function that registers an array of middleware at once. Each middleware
- * is automatically assigned a unique name based on its array index ("middleware-0",
- * "middleware-1", etc.). Middleware are executed in the order they are registered.
- *
- * All middleware receive {@link MiddlewareContext} containing action type, blocker ID,
- * configuration, and timestamp for each blocking event.
- *
- * @param middlewares - Array of middleware functions to register. Functions are called
- *                      in order for each blocking action (add, remove, update, etc.)
- *
- * @example
- * Basic usage with built-in middleware
- * ```ts
- * import { configureMiddleware, loggerMiddleware, createPerformanceMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * configureMiddleware([
- *   loggerMiddleware,
- *   createPerformanceMiddleware({ threshold: 1000 })
- * ]);
- * ```
- *
- * @example
- * With custom middleware
- * ```ts
- * const customMiddleware: Middleware = (context) => {
- *   if (context.action === 'add') {
- *     console.log(`Blocker added: ${context.blockerId}`);
- *   }
- * };
- *
- * configureMiddleware([
- *   loggerMiddleware,
- *   customMiddleware
- * ]);
- * ```
- *
- * @example
- * Analytics integration
- * ```ts
- * import { configureMiddleware, createAnalyticsMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * configureMiddleware([
- *   createAnalyticsMiddleware({
- *     provider: 'google-analytics',
- *     trackingId: 'GA-XXXXX'
- *   })
- * ]);
- * ```
- *
- * @see {@link Middleware} for middleware function signature
- * @see {@link loggerMiddleware} for built-in logging middleware
- * @see {@link createAnalyticsMiddleware} for analytics tracking
- * @see {@link createPerformanceMiddleware} for performance monitoring
- *
- * @public
- * @since 0.6.0
- */
+/** Replace configured global observations without releasing independently owned observations. */
 declare function configureMiddleware(middlewares: ReadonlyArray<Middleware>): void;
 
 /**
  * Built-in middleware for logging all blocking actions to the console.
  *
- * Logs every blocker action (add, remove, update, timeout, clear) with emoji
- * indicators and formatted data. Useful for debugging blocking behavior during
- * development. Register it conditionally when production logging is not desired.
- *
- * Output format: `[UIBlocking] 🔒 blocker-id {scope: "form", reason: "..."}`
- *
- * Emoji indicators:
- * - 🔒 Add
- * - 🔓 Remove
- * - 🔄 Update
- * - ⏰ Timeout
- * - 🧹 Clear/ClearScope
- *
- * @example
- * Register logger middleware
- * ```ts
- * import { configureMiddleware, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * // Enable logging for all blocking actions
- * configureMiddleware([loggerMiddleware]);
- * ```
- *
- * @example
- * Console output examples
- * ```
- * [UIBlocking] 🔒 save-form {scope: "form", reason: "Saving...", priority: 50}
- * [UIBlocking] 🔄 save-form {scope: "form", reason: "Almost done..."}
- * [UIBlocking] 🔓 save-form {reason: "Saving..."}
- * [UIBlocking] ⏰ api-timeout {timeout: 30000}
- * ```
- *
- * @example
- * Production check pattern
- * ```ts
- * import { configureMiddleware, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
- * const middlewares = [];
- * if (process.env.NODE_ENV !== 'production') {
- *   middlewares.push(loggerMiddleware);
- * }
- * configureMiddleware(middlewares);
- * ```
- *
+ * @public
+ * @since 0.6.0
  * @see {@link configureMiddleware} for registering middleware
  * @see {@link Middleware} for middleware function signature
  * @see {@link MiddlewareContext} for available context data
- *
- * @public
- * @since 0.6.0
  */
 declare function loggerMiddleware(context: MiddlewareContext): void;
 
+declare const DEFAULT_SCOPE: "global";
+
+/**
+ * A blocking scope is either one name or a list of names.
+ *
+ * Lists are interpreted as a set: order and duplicate entries have no semantic meaning.
+ * An empty list observes no scope. Guarded controls additionally treat an empty explicit list as
+ * an instruction to inherit their provider scope through {@link resolveScope}.
+ */
+type Scope = string | ReadonlyArray<string>;
+
+/**
+ * Returns a frozen, stable, deduplicated, sorted scope list.
+ * An omitted scope means global; an empty list remains empty.
+ */
+declare function normalizeScope(scope?: Scope): ReadonlyArray<string>;
+/**
+ * Resolves guarded-control inheritance.
+ * An omitted or empty explicit scope inherits; any non-empty explicit scope wins.
+ */
+declare function resolveScope(explicitScope?: Scope, inheritedScope?: Scope): Optional<Scope>;
+/**
+ * Checks ordinary observation semantics.
+ * A global blocker affects every observed scope and otherwise any shared scope is a match.
+ */
+declare function scopeAffectsObservation(blockerScope: Scope, observedScope: Scope): boolean;
+/**
+ * Checks targeted-clear semantics.
+ * Global blockers never match a target, including the global target; otherwise any shared scope
+ * is a match.
+ */
+declare function scopeMatchesTarget(blockerScope: Scope, targetScope: Scope): boolean;
+
 interface PerformanceConfig {
     slowBlockThreshold?: number;
     onSlowBlock?: (blockerId: string, duration: number) => void;
 }
 
 /**
- * Creates middleware for monitoring blocker performance and detecting slow blocks.
- *
- * Tracks the duration of each blocker (from add to remove) and invokes an optional
- * callback when a blocker exceeds the configured threshold. Useful for identifying
- * performance issues, stuck blockers, or operations that take too long.
- *
- * The middleware is side-effect free by default; use `onSlowBlock` for custom
- * reporting, logging, or analytics integration.
- *
- * @param config - Performance monitoring configuration
- * @param config.slowBlockThreshold - Duration in ms before considering a block "slow".
- *                                     Defaults to 3000ms (3 seconds).
- * @param config.onSlowBlock - Optional callback invoked when a slow block is detected.
- *                             Receives blockerId and duration in milliseconds.
- *
- * @returns Middleware function for performance monitoring
- *
- * @example
- * Basic usage with default threshold
- * ```ts
- * import { configureMiddleware, createPerformanceMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * const performanceMiddleware = createPerformanceMiddleware();
- *
- * configureMiddleware([performanceMiddleware]);
- * // Track slow blocks via onSlowBlock if any blocker lasts > 3 seconds
- * ```
- *
- * @example
- * Custom threshold and callback
- * ```ts
- * const performanceMiddleware = createPerformanceMiddleware({
- *   slowBlockThreshold: 5000, // 5 seconds
- *   onSlowBlock: (blockerId, duration) => {
- *     console.error(`Blocker ${blockerId} took ${duration}ms`);
- *
- *     // Report to error tracking
- *     Sentry.captureMessage('Slow UI Blocker', {
- *       extra: { blockerId, duration }
- *     });
- *   }
- * });
- * ```
- *
- * @example
- * With analytics integration
- * ```ts
- * const performanceMiddleware = createPerformanceMiddleware({
- *   slowBlockThreshold: 2000,
- *   onSlowBlock: (blockerId, duration) => {
- *     // Track slow blocks in analytics
- *     analytics.track('slow_blocker_detected', {
- *       blocker_id: blockerId,
- *       duration_ms: duration,
- *       threshold_ms: 2000
- *     });
- *   }
- * });
- * ```
- *
- * @example
- * Development vs Production
- * ```ts
- * const performanceMiddleware = createPerformanceMiddleware({
- *   // Strict threshold in development
- *   slowBlockThreshold: process.env.NODE_ENV === 'production' ? 5000 : 1000,
- *   onSlowBlock: (blockerId, duration) => {
- *     if (process.env.NODE_ENV === 'production') {
- *       // Report to error service in production
- *       errorService.log({ blockerId, duration });
- *     } else {
- *       // Detailed logging in development
- *       console.table({ blockerId, duration });
- *     }
- *   }
- * });
- * ```
- *
- * @see {@link PerformanceConfig} for configuration options
- * @see {@link configureMiddleware} for registering middleware
- *
+ * Measures registration lifetimes from add until removal, timeout or bulk clear.
+ * Updates preserve the start; replacement adds restart it. Callback failures are isolated.
  * @public
  * @since 0.6.0
  */
@@ -527,94 +220,11 @@ declare function useUIBlockingStoreFromContext<T>(selector: (state: UIBlockingSt
 /**
  * Provider component for isolated UI blocking state management.
  *
- * Creates an independent store instance for a subtree of your application.
- * Each provider has its own isolated blocking state, separate from the global
- * store and other provider instances.
- *
- * **Use cases:**
- * - Server-Side Rendering (SSR) - Avoid state sharing between requests
- * - Testing - Isolated state for each test
- * - Micro-frontends - Independent blocking state per micro-app
- * - Modals/Dialogs - Scoped blocking within a dialog
- *
- * Uses `createStoreProvider` from `@okyrychenko-dev/react-zustand-toolkit` with
- * provider-scoped store creation and middleware registration.
- *
- * @param props - Provider configuration
- * @param props.children - React children to wrap with the provider
- * @param props.middlewares - Array of middleware functions to register on store creation
- *
- * @example
- * Basic SSR setup
- * ```tsx
- * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
- *
- * function App() {
- *   return (
- *     <UIBlockingProvider>
- *       <MyApplication />
- *     </UIBlockingProvider>
- *   );
- * }
- * ```
- *
- * @example
- * With middleware
- * ```tsx
- * import { UIBlockingProvider, loggerMiddleware } from '@okyrychenko-dev/react-action-guard';
- *
- * function App() {
- *   return (
- *     <UIBlockingProvider
- *       middlewares={[loggerMiddleware]}
- *     >
- *       <MyApplication />
- *     </UIBlockingProvider>
- *   );
- * }
- * ```
- *
- * @example
- * Multiple providers for micro-frontends
- * ```tsx
- * function MicroFrontendApp() {
- *   return (
- *     <div>
- *       <UIBlockingProvider>
- *         <MicroApp1 />
- *       </UIBlockingProvider>
- *
- *       <UIBlockingProvider>
- *         <MicroApp2 />
- *       </UIBlockingProvider>
- *     </div>
- *   );
- * }
- * ```
- *
- * @example
- * Testing with isolated state
- * ```tsx
- * // In your test file
- * import { render } from '@testing-library/react';
- * import { UIBlockingProvider } from '@okyrychenko-dev/react-action-guard';
- *
- * test('blocker behavior', () => {
- *   render(
- *     <UIBlockingProvider>
- *       <ComponentUnderTest />
- *     </UIBlockingProvider>
- *   );
- *   // Each test gets isolated state
- * });
- * ```
- *
+ * @public
+ * @since 0.6.0
  * @see {@link useUIBlockingContext} to access the store from context
  * @see {@link useIsInsideUIBlockingProvider} to check if inside a provider
  * @see {@link UIBlockingProviderProps} for prop details
- *
- * @public
- * @since 0.6.0
  */
 declare function UIBlockingProvider({ children, middlewares, }: UIBlockingProviderProps): ReactNode;
 
@@ -633,148 +243,46 @@ declare function useResolvedStoreApi(): StoreApi<UIBlockingStore>;
 /**
  * Hook to use the resolved store with a selector
  *
- * Automatically applies shallow comparison to prevent unnecessary re-renders.
+ * Uses toolkit shallow comparison by default, or the supplied domain equality.
  *
  * @param selector - Selector function to pick state from the store
+ * @param equalityFn - Optional comparison retaining equivalent selected values
  * @returns Selected state value
  */
-declare function useResolvedValue<T>(selector: (state: UIBlockingStore) => T): T;
+declare function useResolvedValue<T>(selector: (state: UIBlockingStore) => T, equalityFn?: (left: T, right: T) => boolean): T;
+
+/**
+ * @deprecated Use `useOptionalUIBlockingContext`.
+ */
+declare function useOptionalContext(): ReturnType<typeof useOptionalUIBlockingContext>;
+/**
+ * @deprecated Use `useResolvedStoreApi`.
+ */
+declare function useResolvedStore(): StoreApi<UIBlockingStore>;
+/**
+ * @deprecated Use `useResolvedValue`.
+ */
+declare function useResolvedStoreWithSelector<T>(selector: (state: UIBlockingStore) => T): T;
 
 /**
  * Options for useAsyncAction hook
  */
 interface UseAsyncActionOptions {
-    /** Timeout in milliseconds after which the blocker will be automatically removed */
+    /** Blocker lifetime in milliseconds; does not cancel or settle the operation */
     timeout?: number;
     /** Callback invoked when the blocker is automatically removed due to timeout */
     onTimeout?: (blockerId: string) => void;
 }
 /**
- * Wraps async functions with automatic UI blocking during execution.
- *
- * Creates a wrapper function that automatically:
- * 1. Adds a blocker before executing the async function
- * 2. Executes the async function
- * 3. Removes the blocker after completion (success or failure)
- *
- * Each invocation generates a unique blocker ID (actionId-counter), allowing
- * multiple concurrent executions of the same action without ID conflicts.
- * The blocker is removed even if the async function throws an error.
- *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
- *
- * @template T - The return type of the async function being wrapped
- * @param actionId - Base identifier for the action. Used in blocker ID and default reason.
- *                   Example: "saveForm", "fetchData", "submitOrder"
- * @param scope - Scope(s) to block during execution. Can be a single scope or array.
- *                Defaults to "global" if not specified.
- * @param options - Optional configuration
- * @param options.timeout - Timeout in milliseconds. Blocker auto-removes after this duration.
- * @param options.onTimeout - Callback invoked when blocker times out before async completes
- *
- * @returns Wrapper function that accepts an async function and returns a Promise with the same type
- *
- * @example
- * Basic form submission
- * ```tsx
- * function MyForm() {
- *   const executeWithBlocking = useAsyncAction('saveForm', 'form');
- *
- *   const handleSubmit = async (e) => {
- *     e.preventDefault();
- *
- *     await executeWithBlocking(async () => {
- *       const response = await fetch('/api/save', {
- *         method: 'POST',
- *         body: JSON.stringify(formData)
- *       });
- *       return response.json();
- *     });
- *
- *     alert('Form saved!');
- *   };
- *
- *   return <form onSubmit={handleSubmit}>...</form>;
- * }
- * ```
- *
- * @example
- * With timeout and error handling
- * ```tsx
- * const executeWithBlocking = useAsyncAction(
- *   'fetchData',
- *   ['global', 'data'],
- *   {
- *     timeout: 30000, // 30 seconds
- *     onTimeout: (blockerId) => {
- *       console.warn(`Operation ${blockerId} timed out`);
- *     }
- *   }
- * );
- *
- * const loadData = async () => {
- *   try {
- *     const data = await executeWithBlocking(async () => {
- *       return await fetchDataFromAPI();
- *     });
- *     setData(data);
- *   } catch (error) {
- *     console.error('Failed to load data:', error);
- *     // Blocker is automatically removed even on error
- *   }
- * };
- * ```
- *
- * @example
- * Multiple concurrent actions
- * ```tsx
- * function FileUploader() {
- *   const uploadWithBlocking = useAsyncAction('upload', 'uploads');
- *
- *   const uploadFiles = async (files) => {
- *     // Each upload gets unique blocker ID (upload-1, upload-2, etc.)
- *     const promises = files.map(file =>
- *       uploadWithBlocking(() => uploadFile(file))
- *     );
- *
- *     await Promise.all(promises);
- *   };
- *
- *   return <...>;
- * }
- * ```
- *
- * @example
- * Type-safe return value
- * ```tsx
- * interface UserData {
- *   id: string;
- *   name: string;
- * }
- *
- * function UserProfile() {
- *   const executeWithBlocking = useAsyncAction<UserData>('fetchUser', 'user');
- *
- *   const loadUser = async (userId: string) => {
- *     const userData = await executeWithBlocking(async () => {
- *       const response = await fetch(`/api/users/${userId}`);
- *       return response.json(); // TypeScript knows this is UserData
- *     });
- *
- *     // userData is typed as UserData
- *     console.log(userData.name);
- *   };
- *
- *   return <...>;
- * }
- * ```
- *
- * @see {@link useBlocker} for manual blocker management
- * @see {@link useIsBlocked} to check blocking state
- * @see {@link UseAsyncActionOptions} for available options
+ * Wraps async functions with UI blocking. Concurrent calls get unique blocker IDs;
+ * each blocker is removed in finally on success or failure, even after caller unmount.
+ * Tracking does not exclude concurrent execution. Timeout releases only the blocker.
  *
  * @public
  * @since 0.6.0
+ * @see {@link useActionBlocker} for manual blocker management
+ * @see {@link useIsBlocked} to check blocking state
+ * @see {@link UseAsyncActionOptions} for available options
  */
 declare function useAsyncAction<T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>, options?: UseAsyncActionOptions): (asyncFn: () => Promise<T>) => Promise<T>;
 
@@ -801,157 +309,30 @@ declare function useUIBlockingStore<T>(selector: (state: UIBlockingStore) => T,
 /**
  * Automatically manages a UI blocker based on component lifecycle.
  *
- * Creates a blocker that is automatically added when the condition is true
- * and removed when the component unmounts or condition becomes false.
- * Supports scoped blocking, priorities, timeouts, and works with both
- * global store and isolated provider instances.
- *
- * @param blockerId - Unique identifier for this blocker. Must be unique within the scope.
- * @param config - Configuration object for the blocker
- * @param config.scope - Scope(s) to block. Can be a single scope string (e.g., "form", "navigation")
- *                       or an array of scopes (e.g., ["form", "navigation"]). Defaults to "global".
- * @param config.reason - Human-readable reason for blocking, displayed in DevTools and UI
- * @param config.priority - Priority level (0-100). Higher priority blockers take precedence.
- *                          Use 0-30 for low priority, 31-70 for medium, 71-100 for high priority.
- * @param config.timeout - Auto-removal timeout in milliseconds. Blocker will be automatically
- *                         removed after this duration. Use 0 or undefined for no timeout.
- * @param config.onTimeout - Callback function invoked when the blocker times out
- * @param isActive - When true, blocker is active; when false, blocker is removed.
- *                   Defaults to true. Use this for conditional blocking.
- *
- * @example
- * Basic form submission blocking
- * ```tsx
- * function MyForm() {
- *   const [isSubmitting, setIsSubmitting] = useState(false);
- *
- *   useBlocker('form-submit', {
- *     scope: 'form',
- *     reason: 'Submitting form...',
- *     priority: 50,
- *     timeout: 30000, // Auto-remove after 30 seconds
- *     onTimeout: () => {
- *       console.warn('Form submission timed out');
- *       setIsSubmitting(false);
- *     }
- *   }, isSubmitting);
- *
- *   return <form onSubmit={handleSubmit}>...</form>;
- * }
- * ```
- *
- * @example
- * Multiple scopes with high priority
- * ```tsx
- * useBlocker('critical-save', {
- *   scope: ['form', 'navigation', 'actions'],
- *   reason: 'Saving critical data...',
- *   priority: 90,
- * }, isSaving);
- * ```
- *
- * @example
- * Conditional blocking based on unsaved changes
- * ```tsx
- * function Editor() {
- *   const [hasUnsavedChanges, setHasUnsavedChanges] = useState(false);
- *
- *   useBlocker('unsaved-changes', {
- *     scope: 'navigation',
- *     reason: 'You have unsaved changes',
- *     priority: 80,
- *   }, hasUnsavedChanges);
- *
- *   return <div>...</div>;
- * }
- * ```
- *
+ * @public
+ * @since 0.6.0
  * @see {@link useIsBlocked} to check if a scope is currently blocked
  * @see {@link useBlockingInfo} to get detailed blocker information
  * @see {@link useAsyncAction} for async operation wrapping with automatic blocking
  * @see {@link useConfirmableBlocker} for blockers that require user confirmation
- *
- * @public
- * @since 0.6.0
  */
-declare function useBlocker(blockerId: string, config: BlockerConfig, isActive?: boolean): void;
+declare function useActionBlocker(blockerId: string, config: BlockerConfig, isActive?: boolean): void;
+/**
+ * @deprecated Use {@link useActionBlocker} to avoid confusion with React Router's `useBlocker`.
+ */
+declare const useBlocker: typeof useActionBlocker;
 
 /**
- * Gets detailed information about all active blockers for a specific scope.
- *
- * Returns an array of blocker information objects, sorted by priority (highest first).
- * Each blocker object contains id, reason, priority, and scope information.
- * The hook automatically re-renders when blockers are added, removed, or updated.
- *
- * Uses memoization to provide a stable reference - only re-renders when the actual
- * blocker list changes, not on every store update. This makes it efficient for
- * rendering lists of blockers.
- *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
- *
- * @param scope - Scope to get blocking information for. Defaults to "global" if not specified.
- * @returns Array of {@link BlockerInfo} objects, sorted by priority (highest to lowest)
- *
- * @example
- * Display list of active blockers
- * ```tsx
- * function BlockerList() {
- *   const blockers = useBlockingInfo('form');
- *
- *   if (blockers.length === 0) {
- *     return <div>No active blockers</div>;
- *   }
- *
- *   return (
- *     <ul>
- *       {blockers.map((blocker) => (
- *         <li key={blocker.id}>
- *           {blocker.reason} (Priority: {blocker.priority})
- *         </li>
- *       ))}
- *     </ul>
- *   );
- * }
- * ```
- *
- * @example
- * Show highest priority blocker reason
- * ```tsx
- * function BlockingBanner() {
- *   const blockers = useBlockingInfo('global');
- *
- *   // blockers are already sorted by priority (highest first)
- *   const topBlocker = blockers[0];
- *
- *   if (!topBlocker) {
- *     return null;
- *   }
- *
- *   return <div className="banner">{topBlocker.reason}</div>;
- * }
- * ```
- *
- * @example
- * Count active blockers
- * ```tsx
- * function BlockerCount() {
- *   const formBlockers = useBlockingInfo('form');
- *   const navBlockers = useBlockingInfo('navigation');
- *
- *   const total = formBlockers.length + navBlockers.length;
- *
- *   return <div>{total} active blockers</div>;
- * }
- * ```
- *
- * @see {@link useIsBlocked} for a simple boolean check
- * @see {@link useBlocker} to create blockers
- * @see {@link BlockerInfo} for the structure of blocker information objects
+ * Gets immutable, priority-ordered information about blockers affecting the observed scopes.
+ * Unrelated lifecycle changes preserve the result and do not trigger a render.
  *
  * @public
  * @since 0.6.0
+ * @see {@link useIsBlocked} for a simple boolean check
+ * @see {@link useActionBlocker} to create blockers
+ * @see {@link BlockerInfo} for the structure of blocker information objects
  */
-declare function useBlockingInfo(scope?: string): ReadonlyArray<BlockerInfo>;
+declare function useBlockingInfo(scope?: Scope): ReadonlyArray<Readonly<BlockerInfo>>;
 
 /**
  * Configuration for conditional blocker hook.
@@ -973,142 +354,11 @@ interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig,
 /**
  * Blocks UI based on a dynamic condition that is periodically evaluated.
  *
- * Periodically checks a condition function and automatically adds or removes
- * a blocker based on the result. Useful for blocking based on application state,
- * network status, feature flags, or any other dynamic condition.
- *
- * The condition function receives optional state and returns a boolean.
- * It's evaluated immediately on mount and then at the specified interval.
- * The blocker is added/removed automatically as the condition changes.
- *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
- *
- * @template TState - Type of the state object passed to the condition function
- * @param blockerId - Unique identifier for this conditional blocker
- * @param config - Configuration for conditional blocking
- * @param config.condition - Function that returns true to block, false to unblock.
- *                           Receives the `state` object as parameter.
- * @param config.state - Optional state object passed to the condition function
- * @param config.checkInterval - How often to check the condition in milliseconds.
- *                               Defaults to 1000ms (1 second). Lower values mean
- *                               more responsive blocking but higher CPU usage.
- * @param config.scope - Scope(s) to block when condition is true
- * @param config.reason - Reason for blocking (displayed to users)
- * @param config.priority - Optional blocker priority (0-100)
- *
- * @example
- * Block based on network status
- * ```tsx
- * function OfflineBlocker() {
- *   const [isOnline, setIsOnline] = useState(navigator.onLine);
- *
- *   useEffect(() => {
- *     const handleOnline = () => setIsOnline(true);
- *     const handleOffline = () => setIsOnline(false);
- *
- *     window.addEventListener('online', handleOnline);
- *     window.addEventListener('offline', handleOffline);
- *
- *     return () => {
- *       window.removeEventListener('online', handleOnline);
- *       window.removeEventListener('offline', handleOffline);
- *     };
- *   }, []);
- *
- *   useConditionalBlocker('offline', {
- *     condition: () => !isOnline,
- *     state: { isOnline },
- *     checkInterval: 500, // Check every 500ms
- *     scope: 'global',
- *     reason: 'No internet connection. Please check your network.',
- *     priority: 95
- *   });
- *
- *   return <App />;
- * }
- * ```
- *
- * @example
- * Block based on feature flag
- * ```tsx
- * function FeatureFlagBlocker() {
- *   const featureFlags = useFeatureFlags();
- *
- *   useConditionalBlocker('feature-disabled', {
- *     condition: (state) => !state.featureFlags.newFeatureEnabled,
- *     state: { featureFlags },
- *     checkInterval: 5000, // Check every 5 seconds
- *     scope: 'new-feature',
- *     reason: 'This feature is currently disabled',
- *     priority: 70
- *   });
- *
- *   return <NewFeature />;
- * }
- * ```
- *
- * @example
- * Block during API rate limit
- * ```tsx
- * function RateLimitBlocker() {
- *   const [requestCount, setRequestCount] = useState(0);
- *   const [resetTime, setResetTime] = useState<number | null>(null);
- *
- *   useConditionalBlocker('rate-limit', {
- *     condition: (state) => {
- *       if (!state.resetTime) {
- *         return false;
- *       }
- *       return Date.now() < state.resetTime && state.requestCount >= 100;
- *     },
- *     state: { requestCount, resetTime },
- *     checkInterval: 1000,
- *     scope: 'api',
- *     reason: 'API rate limit reached. Please wait.',
- *     priority: 90
- *   });
- *
- *   return <Dashboard />;
- * }
- * ```
- *
- * @example
- * Block based on form validation
- * ```tsx
- * function FormValidationBlocker() {
- *   const { formState } = useFormContext();
- *
- *   useConditionalBlocker('invalid-form', {
- *     condition: (state) => !state.isValid && state.isDirty,
- *     state: formState,
- *     checkInterval: 500,
- *     scope: 'form-submit',
- *     reason: 'Please fix form errors before submitting',
- *     priority: 60
- *   });
- *
- *   return <Form />;
- * }
- * ```
- *
- * @example
- * Without state parameter (simple condition)
- * ```tsx
- * useConditionalBlocker('low-battery', {
- *   condition: () => !navigator.onLine,
- *   checkInterval: 30000, // Check every 30 seconds
- *   scope: 'heavy-operations',
- *   reason: 'Internet connection is required for this operation',
- *   priority: 80
- * });
- * ```
- *
- * @see {@link useBlocker} for simple conditional blocking with boolean
- * @see {@link useScheduledBlocker} for time-based blocking
- * @see {@link ConditionalBlockerConfig} for configuration options
- *
  * @public
  * @since 0.6.0
+ * @see {@link useActionBlocker} for simple conditional blocking with boolean
+ * @see {@link useScheduledBlocker} for time-based blocking
+ * @see {@link ConditionalBlockerConfig} for configuration options
  */
 declare function useConditionalBlocker<TState = unknown>(blockerId: string, config: ConditionalBlockerConfig<TState>): void;
 
@@ -1156,209 +406,21 @@ interface UseConfirmableBlockerReturn {
 /**
  * Creates a blocker that requires user confirmation before executing an action.
  *
- * Manages a confirmation dialog and blocking state for actions that need user approval.
- * The blocker is active during both the confirmation dialog display and action execution.
- *
- * Workflow:
- * 1. Call `execute()` to show confirmation dialog (blocker activated)
- * 2. User confirms → `onConfirm` callback runs (blocker remains active)
- * 3. Action completes → blocker removed
- * 4. User cancels → blocker removed, optional `onCancel` callback runs
- *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
- *
- * @param blockerId - Unique identifier for this confirmable blocker
- * @param config - Configuration for the confirmable action
- * @param config.confirmMessage - Message to display in the confirmation dialog
- * @param config.confirmTitle - Optional dialog title (defaults to "Confirm Action")
- * @param config.confirmButtonText - Optional confirm button text (defaults to "Confirm")
- * @param config.cancelButtonText - Optional cancel button text (defaults to "Cancel")
- * @param config.onConfirm - Async function to execute after user confirms
- * @param config.onCancel - Optional callback when user cancels
- * @param config.scope - Scope(s) to block during confirmation and execution
- * @param config.reason - Optional custom blocking reason (defaults to confirmMessage)
- * @param config.priority - Optional blocker priority (0-100)
- *
- * @returns Object containing:
- * - `execute`: Function to trigger the confirmation dialog
- * - `isDialogOpen`: Boolean indicating if confirmation dialog is visible
- * - `isExecuting`: Boolean indicating if the confirmed action is executing
- * - `confirmConfig`: Dialog configuration (title, message, button texts)
- * - `onConfirm`: Function to call when user confirms
- * - `onCancel`: Function to call when user cancels
- *
- * @example
- * Delete confirmation with custom dialog
- * ```tsx
- * function DeleteButton({ itemId, itemName }) {
- *   const confirmableDelete = useConfirmableBlocker('delete-item', {
- *     confirmMessage: `Are you sure you want to delete "${itemName}"?`,
- *     confirmTitle: 'Delete Item',
- *     confirmButtonText: 'Delete',
- *     cancelButtonText: 'Keep',
- *     scope: ['form', 'navigation'],
- *     priority: 80,
- *     onConfirm: async () => {
- *       await deleteItem(itemId);
- *       showToast('Item deleted successfully');
- *     },
- *     onCancel: () => {
- *       console.log('Delete cancelled');
- *     }
- *   });
- *
- *   return (
- *     <>
- *       <button onClick={confirmableDelete.execute}>
- *         Delete
- *       </button>
- *
- *       {confirmableDelete.isDialogOpen && (
- *         <ConfirmDialog
- *           {...confirmableDelete.confirmConfig}
- *           onConfirm={confirmableDelete.onConfirm}
- *           onCancel={confirmableDelete.onCancel}
- *           isLoading={confirmableDelete.isExecuting}
- *         />
- *       )}
- *     </>
- *   );
- * }
- * ```
- *
- * @example
- * Simple confirmation with default dialog
- * ```tsx
- * function LogoutButton() {
- *   const confirmLogout = useConfirmableBlocker('logout', {
- *     confirmMessage: 'Are you sure you want to log out?',
- *     scope: 'global',
- *     onConfirm: async () => {
- *       await api.logout();
- *       navigate('/login');
- *     }
- *   });
- *
- *   return (
- *     <>
- *       <button onClick={confirmLogout.execute}>Logout</button>
- *
- *       {confirmLogout.isDialogOpen && (
- *         <Dialog
- *           title={confirmLogout.confirmConfig.title}
- *           message={confirmLogout.confirmConfig.message}
- *           onConfirm={confirmLogout.onConfirm}
- *           onCancel={confirmLogout.onCancel}
- *         />
- *       )}
- *     </>
- *   );
- * }
- * ```
- *
- * @example
- * With loading state during execution
- * ```tsx
- * function SaveButton() {
- *   const confirmSave = useConfirmableBlocker('save-changes', {
- *     confirmMessage: 'Save all changes?',
- *     scope: 'form',
- *     onConfirm: async () => {
- *       await saveAllChanges();
- *     }
- *   });
- *
- *   return (
- *     <button
- *       onClick={confirmSave.execute}
- *       disabled={confirmSave.isExecuting}
- *     >
- *       {confirmSave.isExecuting ? 'Saving...' : 'Save All'}
- *     </button>
- *   );
- * }
- * ```
- *
- * @see {@link useBlocker} for simple blocking without confirmation
- * @see {@link ConfirmableBlockerConfig} for configuration options
- * @see {@link UseConfirmableBlockerReturn} for return value structure
- *
  * @public
  * @since 0.6.0
+ * @see {@link useActionBlocker} for simple blocking without confirmation
+ * @see {@link ConfirmableBlockerConfig} for configuration options
+ * @see {@link UseConfirmableBlockerReturn} for return value structure
  */
 declare function useConfirmableBlocker(blockerId: string, config: ConfirmableBlockerConfig): UseConfirmableBlockerReturn;
 
 /**
  * Checks if one or more scopes are currently blocked.
  *
- * Returns a boolean indicating whether any of the specified scopes have active blockers.
- * The hook automatically re-renders the component when the blocking state changes,
- * ensuring your UI always reflects the current blocking state.
- *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
- *
- * @param scope - Scope(s) to check for blocking. Can be:
- *                - A single scope string (e.g., "form", "navigation", "global")
- *                - An array of scopes (e.g., ["form", "navigation"])
- *                - undefined to check the "global" scope
- * @returns true if ANY of the specified scopes are blocked, false otherwise
- *
- * @example
- * Basic single scope check
- * ```tsx
- * function SubmitButton() {
- *   const isFormBlocked = useIsBlocked('form');
- *
- *   return (
- *     <button disabled={isFormBlocked}>
- *       {isFormBlocked ? 'Processing...' : 'Submit'}
- *     </button>
- *   );
- * }
- * ```
- *
- * @example
- * Multiple scopes check
- * ```tsx
- * function NavigationLink({ href, children }) {
- *   const isBlocked = useIsBlocked(['navigation', 'global']);
- *
- *   return (
- *     <a
- *       href={href}
- *       onClick={(e) => {
- *         if (isBlocked) {
- *           e.preventDefault();
- *           alert('Navigation is currently blocked');
- *         }
- *       }}
- *       style={{ opacity: isBlocked ? 0.5 : 1 }}
- *     >
- *       {children}
- *     </a>
- *   );
- * }
- * ```
- *
- * @example
- * Conditional rendering based on blocking state
- * ```tsx
- * function SaveIndicator() {
- *   const isSaving = useIsBlocked('save');
- *
- *   if (!isSaving) {
- *     return null;
- *   }
- *
- *   return <div className="spinner">Saving...</div>;
- * }
- * ```
- *
- * @see {@link useBlocker} to create a blocker
- * @see {@link useBlockingInfo} to get detailed information about active blockers
- *
  * @public
  * @since 0.6.0
+ * @see {@link useActionBlocker} to create a blocker
+ * @see {@link useBlockingInfo} to get detailed information about active blockers
  */
 declare function useIsBlocked(scope?: string | ReadonlyArray<string>): boolean;
 
@@ -1369,7 +431,11 @@ declare function useIsBlocked(scope?: string | ReadonlyArray<string>): boolean;
  * 1. start + duration: Block for a specific duration after start time
  * 2. start + end: Block between start and end times
  *
- * Note: If both duration and end are provided, duration takes precedence.
+ * Windows are half-open [start, end). Omit both duration and end for indefinite blocking.
+ * Zero duration or equal bounds are empty and emit no schedule notifications.
+ * Every supplied bound must be valid, even when duration takes precedence over end.
+ * Negative/nonfinite duration, invalid dates, end before start and calculated end
+ * outside the JavaScript Date range cancel the schedule with a development warning.
  */
 interface BlockingSchedule {
     /** Start time as ISO string, Date object, or timestamp */
@@ -1394,123 +460,12 @@ interface ScheduledBlockerConfig extends BlockerConfig {
 /**
  * Schedules UI blocking for a specific time period (e.g., maintenance windows).
  *
- * Automatically blocks UI between specified start and end times. Useful for
- * scheduled maintenance, planned downtime, or time-based feature restrictions.
- * Supports callbacks when the blocking period starts and ends.
- *
- * Time specifications support:
- * - Date objects
- * - ISO 8601 strings (e.g., "2024-01-15T10:00:00Z")
- * - Unix timestamps (milliseconds since epoch)
- *
- * You can specify the end time either as an absolute time or as a duration
- * from the start time. If both are provided, duration takes precedence.
- *
- * Works with both the global store and isolated provider instances (via UIBlockingProvider).
- *
- * @param blockerId - Unique identifier for this scheduled blocker
- * @param config - Schedule configuration
- * @param config.schedule - Schedule timing configuration
- * @param config.schedule.start - When to start blocking (Date, ISO string, or timestamp)
- * @param config.schedule.end - Optional absolute end time (Date, ISO string, or timestamp)
- * @param config.schedule.duration - Optional duration in milliseconds from start time
- * @param config.scope - Scope(s) to block during the scheduled period
- * @param config.reason - Reason for blocking (displayed to users)
- * @param config.priority - Optional blocker priority (0-100)
- * @param config.onScheduleStart - Optional callback when blocking period starts
- * @param config.onScheduleEnd - Optional callback when blocking period ends
- *
- * @example
- * Maintenance window with absolute times
- * ```tsx
- * function MaintenanceWarning() {
- *   useScheduledBlocker('maintenance', {
- *     schedule: {
- *       start: new Date('2024-01-15T02:00:00Z'),
- *       end: new Date('2024-01-15T04:00:00Z'),
- *     },
- *     scope: 'global',
- *     reason: 'System maintenance in progress',
- *     priority: 95,
- *     onScheduleStart: () => {
- *       console.log('Maintenance started');
- *       showNotification('System is now in maintenance mode');
- *     },
- *     onScheduleEnd: () => {
- *       console.log('Maintenance completed');
- *       showNotification('System is back online');
- *     }
- *   });
- *
- *   return <div>...</div>;
- * }
- * ```
- *
- * @example
- * Short maintenance with duration
- * ```tsx
- * useScheduledBlocker('quick-maintenance', {
- *   schedule: {
- *     start: new Date('2024-01-15T03:00:00'),
- *     duration: 15 * 60 * 1000, // 15 minutes
- *   },
- *   scope: ['api', 'forms'],
- *   reason: 'Brief system update',
- *   priority: 90
- * });
- * ```
- *
- * @example
- * Business hours enforcement
- * ```tsx
- * function BusinessHoursBlocker() {
- *   const now = new Date();
- *   const tomorrow9AM = new Date(now);
- *   tomorrow9AM.setDate(now.getDate() + 1);
- *   tomorrow9AM.setHours(9, 0, 0, 0);
- *
- *   useScheduledBlocker('after-hours', {
- *     schedule: {
- *       start: new Date(now.getTime() + 1000), // Start immediately
- *       end: tomorrow9AM,
- *     },
- *     scope: 'trading',
- *     reason: 'Trading is only available during business hours (9 AM - 5 PM)',
- *     priority: 85
- *   });
- *
- *   return <TradingDashboard />;
- * }
- * ```
- *
- * @example
- * Using ISO strings for scheduling
- * ```tsx
- * useScheduledBlocker('deployment', {
- *   schedule: {
- *     start: '2024-01-20T00:00:00Z',
- *     duration: 2 * 60 * 60 * 1000, // 2 hours
- *   },
- *   scope: 'global',
- *   reason: 'Deploying new version',
- *   priority: 100,
- *   onScheduleStart: () => {
- *     analytics.track('deployment_started');
- *   },
- *   onScheduleEnd: () => {
- *     analytics.track('deployment_completed');
- *     window.location.reload(); // Reload to get new version
- *   }
- * });
- * ```
- *
- * @see {@link useBlocker} for immediate blocking without scheduling
+ * @public
+ * @since 0.6.0
+ * @see {@link useActionBlocker} for immediate blocking without scheduling
  * @see {@link useConditionalBlocker} for condition-based blocking
  * @see {@link ScheduledBlockerConfig} for configuration options
  * @see {@link BlockingSchedule} for schedule specification details
- *
- * @public
- * @since 0.6.0
  */
 declare function useScheduledBlocker(blockerId: string, config: ScheduledBlockerConfig): void;
 
@@ -1530,7 +485,7 @@ interface BlockerConfigTyped<TScope extends string> {
     scope?: ScopeValue<TScope>;
     /** Human-readable reason for blocking */
     reason?: string;
-    /** Priority level (higher priority blockers take precedence, minimum value is 0) */
+    /** Reason ordering priority (minimum 0). Every matching active blocker retains protection, including lower-priority ones. */
     priority?: number;
     /** Timestamp when the blocker was created */
     timestamp?: number;
@@ -1545,7 +500,12 @@ interface BlockerConfigTyped<TScope extends string> {
  */
 interface TypedHooks<TScope extends string> {
     /**
-     * Type-safe version of useBlocker hook
+     * Type-safe action blocker hook
+     */
+    useActionBlocker: (blockerId: string, config: BlockerConfigTyped<TScope>, isActive?: boolean) => void;
+    /**
+     * Backward-compatible name for useActionBlocker
+     * @deprecated Use `useActionBlocker`.
      */
     useBlocker: (blockerId: string, config: BlockerConfigTyped<TScope>, isActive?: boolean) => void;
     /**
@@ -1559,7 +519,7 @@ interface TypedHooks<TScope extends string> {
     /**
      * Type-safe version of useBlockingInfo hook
      */
-    useBlockingInfo: (scope: TScope) => ReturnType<typeof useBlockingInfo>;
+    useBlockingInfo: (scope: ScopeValue<TScope>) => ReturnType<typeof useBlockingInfo>;
 }
 /**
  * Creates type-safe versions of all blocking hooks with your custom scope types
@@ -1573,26 +533,13 @@ interface TypedHooks<TScope extends string> {
  * type AppScopes = "global" | "form" | "navigation" | "checkout";
  *
  * // Create typed hooks
- * const { useBlocker, useIsBlocked, useAsyncAction } = createTypedHooks<AppScopes>();
+ * const { useActionBlocker, useIsBlocked, useAsyncAction } = createTypedHooks<AppScopes>();
  *
  * // Now TypeScript will catch typos
- * useBlocker("id", { scope: "form" }); // ✓ OK
- * useBlocker("id", { scope: "typo" }); // ✗ Type error!
+ * useActionBlocker("id", { scope: "form" }); // ✓ OK
+ * useActionBlocker("id", { scope: "typo" }); // ✗ Type error!
  * ```
  */
 declare function createTypedHooks<TScope extends string>(): TypedHooks<TScope>;
 
-/**
- * @deprecated Use `useOptionalUIBlockingContext`.
- */
-declare function useOptionalContext(): ReturnType<typeof useOptionalUIBlockingContext>;
-/**
- * @deprecated Use `useResolvedStoreApi`.
- */
-declare function useResolvedStore(): StoreApi<UIBlockingStore>;
-/**
- * @deprecated Use `useResolvedValue`.
- */
-declare function useResolvedStoreWithSelector<T>(selector: (state: UIBlockingStore) => T): T;
-
-export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerConfigTyped, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type DefaultScopes, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type ScopeValue, type ShallowStoreBindings, type StoredBlocker, type TypedHooks, UIBlockingProvider, type UIBlockingProviderProps, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseAsyncActionOptions, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useOptionalContext, useOptionalUIBlockingContext, useResolvedStore, useResolvedStoreApi, useResolvedStoreWithSelector, useResolvedValue, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };
+export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerConfigTyped, type BlockerInfo, type BlockingAction, type BlockingEvent, type BlockingLifecycle, type BlockingLifecycleObservation, type BlockingLifecycleSnapshot, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, DEFAULT_SCOPE, type DefaultScopes, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type Scope, type ScopeValue, type TypedHooks, UIBlockingProvider, type UIBlockingProviderProps, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseAsyncActionOptions, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createBlockingLifecycle, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, normalizeScope, resolveScope, scopeAffectsObservation, scopeMatchesTarget, uiBlockingStoreApi, useActionBlocker, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useOptionalContext, useOptionalUIBlockingContext, useResolvedStore, useResolvedStoreApi, useResolvedStoreWithSelector, useResolvedValue, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };