@asaidimu/react-store 2.1.0 → 4.0.0

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@asaidimu/react-store.svg)](https://www.npmjs.com/package/@asaidimu/react-store)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/asaidimu/node-react/actions)
 
 A performant, type-safe state management solution for React with built-in persistence, extensive observability, and a robust middleware system.
 
@@ -21,6 +22,7 @@ This package is currently in **beta**. The API is subject to rapid changes and s
     *   [Persistence](#persistence)
     *   [Middleware](#middleware)
     *   [Observability](#observability)
+    *   [Remote Observability](#remote-observability)
     *   [Transaction Support](#transaction-support)
     *   [Event System](#event-system)
     *   [Watching Action Loading States](#watching-action-loading-states)
@@ -31,6 +33,8 @@ This package is currently in **beta**. The API is subject to rapid changes and s
     *   [Best Practices](#best-practices)
     *   [API Reference](#api-reference)
     *   [Comparison with Other State Management Solutions](#comparison-with-other-state-management-solutions)
+    *   [Troubleshooting](#troubleshooting)
+    *   [FAQ](#faq)
     *   [Changelog](#changelog)
     *   [License](#license)
     *   [Acknowledgments](#acknowledgments)
@@ -41,19 +45,19 @@ This package is currently in **beta**. The API is subject to rapid changes and s
 
 `@asaidimu/react-store` provides an efficient and predictable way to manage complex application state in React applications. It goes beyond basic state management by integrating features typically found in separate libraries, such as data persistence and comprehensive observability tools, directly into its core. This allows developers to build robust, high-performance applications with deep insights into state changes and application behavior.
 
-Designed with modern React in mind, it leverages `useSyncExternalStore` for optimal performance and reactivity, ensuring components re-render only when relevant parts of the state change. Its flexible design supports a variety of use cases, from simple counter applications to complex data flows requiring atomic updates and cross-tab synchronization.
+Designed with modern React in mind, it leverages `useSyncExternalStore` for optimal performance and reactivity, ensuring components re-render only when relevant parts of the state change. Its flexible design supports a variety of use cases, from simple counter applications to complex data flows requiring atomic updates and cross-tab synchronization. The library is built with TypeScript from the ground up, offering strong type safety throughout your application's state and actions.
 
 ### Key Features
 
-*   📊 **Reactive State Management**: Automatically tracks dependencies to optimize component renders and ensure efficient updates.
-*   🛡️ **Type-Safe**: Built with TypeScript from the ground up, providing strict type checking and a safer development experience.
+*   📊 **Reactive State Management**: Automatically tracks dependencies to optimize component renders and ensure efficient updates using `useSyncExternalStore`.
+*   🛡️ **Type-Safe**: Developed entirely in TypeScript, providing strict type checking for state, actions, and middleware.
 *   ⚙️ **Middleware Pipeline**: Implement custom logic to transform, validate, or log state changes before they are applied. Supports both transforming and blocking middleware.
 *   📦 **Transaction Support**: Group multiple state updates into a single atomic operation, with automatic rollback if any part of the transaction fails.
 *   💾 **Built-in Persistence**: Seamlessly integrate with web storage mechanisms like `IndexedDB` and `WebStorage` (localStorage/sessionStorage), including cross-tab synchronization.
-*   🔍 **Deep Observability**: Gain profound insights into your application's state with built-in metrics, detailed event logging, state history, and time-travel debugging capabilities.
+*   🔍 **Deep Observability**: Gain profound insights into your application's state with built-in metrics, detailed event logging, state history, and time-travel debugging capabilities via the `StoreObservability` instance.
 *   ⚡ **Performance Optimized**: Features intelligent selector caching (now using `WeakMap` for enhanced efficiency) and debounced actions with configurable immediate execution to prevent rapid successive calls and ensure smooth application performance.
 *   🚀 **Action Loading States**: Track the real-time loading status of individual actions, providing immediate feedback on asynchronous operations.
-*   ⚛️ **React 18+ Ready**: Fully compatible with the latest React versions, leveraging modern APIs for enhanced performance and development ergonomics.
+*   ⚛️ **React 19+ Ready**: Fully compatible with the latest React versions, leveraging modern APIs for enhanced performance and development ergonomics.
 *   🗑️ **Explicit Deletions**: Use `Symbol.for("delete")` to explicitly remove properties from nested state objects.
 
 ## Installation & Setup
@@ -61,8 +65,8 @@ Designed with modern React in mind, it leverages `useSyncExternalStore` for opti
 ### Prerequisites
 
 *   Node.js (v18 or higher recommended)
-*   React (v18 or higher recommended)
-*   A package manager like `bun`, `npm`, or `yarn`.
+*   React (v19 or higher recommended)
+*   A package manager like `bun`, `npm`, or `yarn`. This project explicitly uses `bun`.
 
 ### Installation Steps
 
@@ -78,7 +82,7 @@ yarn add @asaidimu/react-store
 
 ### Configuration
 
-No global configuration is required. All options are passed during store creation.
+No global configuration is required. All options are passed during store creation via the `createStore` function. Configuration includes enabling metrics, logging, persistence, and performance thresholds.
 
 ### Verification
 
@@ -87,98 +91,242 @@ You can verify the installation by importing `createStore` and setting up a basi
 ```typescript
 import { createStore } from '@asaidimu/react-store';
 
-const myStore = createStore({
+interface MyState {
+  value: string;
+}
+
+const myStore = createStore<MyState, any>({
   state: { value: 'hello' },
   actions: {
-    setValue: (state, newValue: string) => ({ value: newValue }),
+    setValue: (_, newValue: string) => ({ value: newValue }),
   },
 });
 
+const { select, actions } = myStore(); // Instantiate the hook
+
+// Access state
+const currentValue = select(s => s.value);
+console.log(currentValue); // Expected: 'hello'
+
+// Dispatch an action
+actions.setValue('world');
 ```
 
-If no errors are thrown, the package is correctly installed.
+If no errors are thrown during installation or when running this basic example, the package is correctly installed and configured.
 
 ## Usage Documentation
 
 ### Creating a Store
 
-Define your application state and actions, then create a store using `createStore`.
+Define your application state and actions, then create a store using `createStore`. The `actions` object maps action names to functions that receive an `ActionContext` (containing the current `state` and an `resolve` function for artifacts) and any additional arguments.
 
 ```tsx
-// src/stores/myStore.ts
-import { createStore } from '@asaidimu/react-store';
+// ui/store.tsx (Example from codebase)
+import { createStore } from '@asaidimu/react-store'; // Assuming direct import or wrapper
+
+export interface Product {
+  id: number;
+  name: string;
+  price: number;
+  stock: number;
+  image: string;
+}
+
+export interface CartItem extends Product {
+  quantity: number;
+}
+
+export interface Order {
+  id: string;
+  items: CartItem[];
+  total: number;
+  date: Date;
+}
 
-interface AppState {
-  count: number;
-  user: { name: string; loggedIn: boolean; email?: string };
-  settings: { theme: 'light' | 'dark'; notifications: boolean };
+export interface ECommerceState extends Record<string, any>{
+  products: Product[];
+  cart: CartItem[];
+  orders: Order[];
+  topSellers: { id: number; name: string; sales: number }[];
+  activeUsers: number;
 }
 
-const initialState: AppState = {
-  count: 0,
-  user: { name: 'Guest', loggedIn: false },
-  settings: { theme: 'light', notifications: true },
+const initialState: ECommerceState = {
+  products: [
+    { id: 1, name: 'Wireless Mouse', price: 25.99, stock: 150, image: 'https://placehold.co/600x400/white/black?text=Mouse' },
+    { id: 2, name: 'Mechanical Keyboard', price: 79.99, stock: 100, image: 'https://placehold.co/600x400/white/black?text=Keyboard' },
+    { id: 3, name: '4K Monitor', price: 349.99, stock: 75, image: 'https://placehold.co/600x400/white/black?text=Monitor' },
+    { id: 4, name: 'Webcam', price: 45.50, stock: 120, image: 'https://placehold.co/600x400/white/black?text=Webcam' },
+    { id: 5, name: 'USB-C Hub', price: 39.99, stock: 200, image: 'https://placehold.co/600x400/white/black?text=Hub' },
+  ],
+  cart: [],
+  orders: [],
+  topSellers: [
+    { id: 2, name: 'Mechanical Keyboard', sales: 120 },
+    { id: 3, name: '4K Monitor', sales: 85 },
+    { id: 1, name: 'Wireless Mouse', sales: 80 },
+    { id: 5, name: 'USB-C Hub', sales: 70 },
+    { id: 4, name: 'Webcam', sales: 65 },
+  ],
+  activeUsers: 1428,
 };
 
-const myStore = createStore({
-  state: initialState,
-  actions: {
-    increment: (state, amount: number) => ({ count: state.count + amount }),
-    login: async (state, username: string, email: string) => {
-      // Simulate an asynchronous API call
-      await new Promise(resolve => setTimeout(resolve, 500));
-      return { user: { name: username, loggedIn: true, email } };
-    },
-    toggleTheme: (state) => ({
-      settings: { theme: state.settings.theme === 'light' ? 'dark' : 'light' },
-    }),
+const actions = {
+  addToCart: ({ state }: any, product: Product) => {
+    const existingItem = state.cart.find((item:any) => item.id === product.id);
+    if (existingItem) {
+      return {
+        cart: state.cart.map((item:any) =>
+          item.id === product.id ? { ...item, quantity: item.quantity + 1 } : item
+        ),
+      };
+    }
+    return { cart: [...state.cart, { ...product, quantity: 1 }] };
   },
-}, {
-  debounceTime: 0, // Actions execute immediately by default
-  enableConsoleLogging: true, // Enable console logs for store events
-  logEvents: { updates: true, transactions: true, middleware: true },
-  performanceThresholds: { updateTime: 20, middlewareTime: 5 }, // Warn for slow operations
-});
+  removeFromCart: ({state}: {state:ECommerceState}, productId: number) => ({
+    cart: state.cart.filter((item) => item.id !== productId),
+  }),
+  updateQuantity: ({state}: {state:ECommerceState}, { productId, quantity }: { productId: number; quantity: number }) => ({
+    cart: state.cart.map((item) =>
+      item.id === productId ? { ...item, quantity } : item
+    ).filter(item => item.quantity > 0),
+  }),
+  checkout: ({state}: {state:ECommerceState}) => {
+    const total = state.cart.reduce((sum, item) => sum + item.price * item.quantity, 0);
+    const newOrder: Order = {
+      id: crypto.randomUUID(),
+      items: state.cart,
+      total,
+      date: new Date(),
+    };
+    return {
+      cart: [],
+      orders: [newOrder, ...state.orders],
+      products: state.products.map(p => {
+        const cartItem = state.cart.find(item => item.id === p.id);
+        return cartItem ? { ...p, stock: p.stock - cartItem.quantity } : p;
+      }),
+      topSellers: state.topSellers.map(s => {
+        const cartItem = state.cart.find(item => item.id === s.id);
+        return cartItem ? { ...s, sales: s.sales + cartItem.quantity } : s;
+      }).sort((a, b) => b.sales - a.sales),
+    };
+  },
+
+  updateStock: ({state}: {state:ECommerceState}) => ({
+    products: state.products.map((p:any) => ({
+      ...p,
+      stock: Math.max(0, p.stock + Math.floor(Math.random() * 10) - 5)
+    }))
+  }),
+  updateActiveUsers: ({state}: {state:ECommerceState}) => ({
+    activeUsers: state.activeUsers + Math.floor(Math.random() * 20) - 10,
+  }),
+  addRandomOrder: ({state}: {state:ECommerceState}) => {
+    const randomProduct = state.products[Math.floor(Math.random() * state.products.length)];
+    const quantity = Math.floor(Math.random() * 3) + 1;
+    const newOrder: Order = {
+      id: crypto.randomUUID(),
+      items: [{ ...randomProduct, quantity }],
+      total: randomProduct.price * quantity,
+      date: new Date(),
+    };
+    return {
+      orders: [newOrder, ...state.orders],
+    };
+  },
+};
 
-// Export the hook for use in components
-export const useMyStore = myStore;
+export const useStore = createStore(
+  {
+    state: initialState,
+    actions,
+  },
+  { enableMetrics: true } // Enables metrics for observability
+);
 ```
 
 ### Using in Components
 
-Consume your store's state and actions within your React components using the exported hook.
+Consume your store's state and actions within your React components using the exported hook. The `select` function allows you to subscribe to specific parts of the state, ensuring that your components only re-render when the selected data changes.
 
 ```tsx
-// src/components/MyComponent.tsx
-import React from 'react';
-import { useMyStore } from '../stores/myStore';
+// ui/App.tsx (Excerpt from codebase)
+import { useEffect, useMemo } from 'react';
+import { BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip, Legend, ResponsiveContainer } from 'recharts';
+import { useStore, Product, CartItem, Order } from './store'; // Assuming these imports resolve correctly
 
-function MyComponent() {
-  const { select, actions, isReady } = useMyStore();
+// ... (ShadCN-like UI Components for brevity) ...
 
-  // Select specific parts of the state for granular re-renders
-  const count = select((state) => state.count);
-  const userName = select((state) => state.user.name);
-  const theme = select((state) => state.settings.theme);
+const ProductCatalog = () => {
+  const { select, actions } = useStore();
+  const products = select((state) => state.products); // Granular selection
 
-  // isReady indicates if persistence has loaded initial state
-  if (!isReady) {
-    return <div>Loading store data...</div>;
-  }
+  return (
+    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
+      {products.map((product: Product) => (
+        <Card key={product.id}>
+          <CardHeader>
+            <CardTitle>{product.name}</CardTitle>
+          </CardHeader>
+          <CardContent className="flex-grow">
+            <img src={product.image} alt={product.name} className="w-full h-40 object-cover rounded-lg mb-4" />
+            <div className="flex justify-between items-center">
+                <p className="text-lg font-semibold text-gray-700">${product.price.toFixed(2)}</p>
+                <p className="text-sm text-gray-500">{product.stock} in stock</p>
+            </div>
+          </CardContent>
+          <CardFooter>
+            <Button onClick={() => actions.addToCart(product)} className="w-full">Add to Cart</Button>
+          </CardFooter>
+        </Card>
+      ))}
+    </div>
+  );
+};
+
+function App() {
+  const { actions } = useStore();
+
+  useEffect(() => {
+    // Real-time simulations for the dashboard
+    const stockInterval = setInterval(() => actions.updateStock(), 2000);
+    const usersInterval = setInterval(() => actions.updateActiveUsers(), 3000);
+    const ordersInterval = setInterval(() => actions.addRandomOrder(), 5000);
+
+    return () => {
+      clearInterval(stockInterval);
+      clearInterval(usersInterval);
+      clearInterval(ordersInterval);
+    };
+  }, [actions]); // `actions` object is stable due to `useMemo` in createStore
 
   return (
-    <div style={{ background: theme === 'dark' ? '#333' : '#FFF', color: theme === 'dark' ? '#FFF' : '#333' }}>
-      <h1>Welcome, {userName}!</h1>
-      <p>Current Count: {count}</p>
-      <button onClick={() => actions.increment(1)}>Increment</button>
-      <button onClick={() => actions.increment(5)}>Increment by 5 (debounced)</button>
-      <button onClick={() => actions.login('Alice', 'alice@example.com')}>Login as Alice</button>
-      <button onClick={() => actions.toggleTheme()}>Toggle Theme</button>
+    <div className="bg-gray-50 text-gray-900 min-h-screen">
+        <header className="border-b">
+            <div className="container mx-auto px-4 h-16 flex items-center">
+                <h1 className="text-xl font-bold">E-Commerce Dashboard</h1>
+            </div>
+        </header>
+        <main className="container mx-auto p-4 sm:p-6 lg:p-8">
+            <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+                <div className="lg:col-span-2 space-y-6">
+                    <ProductCatalog />
+                    <LiveInventoryChart />
+                </div>
+                <div className="space-y-6">
+                    <ShoppingCart />
+                    <UserAnalytics />
+                    <TopSellingProducts />
+                    <RecentOrdersFeed />
+                </div>
+            </div>
+        </main>
     </div>
   );
 }
 
-export default MyComponent;
+export default App;
 ```
 
 ### Handling Deletions
@@ -202,12 +350,12 @@ const deleteStore = createStore({
     tags: ['electronics', 'new']
   },
   actions: {
-    removeDetails: (state) => ({ details: Symbol.for("delete") }),
-    removeDimensions: (state) => ({ details: { dimensions: Symbol.for("delete") } }),
-    removeTag: (state, tagToRemove: string) => ({
+    removeDetails: (ctx) => ({ details: Symbol.for("delete") }),
+    removeDimensions: (ctx) => ({ details: { dimensions: Symbol.for("delete") } }),
+    removeTag: ({state}, tagToRemove: string) => ({
       tags: state.tags.filter(tag => tag !== tagToRemove)
     }),
-    clearAllExceptId: (state) => ({
+    clearAllExceptId: (ctx) => ({
       name: Symbol.for("delete"),
       details: Symbol.for("delete"),
       tags: Symbol.for("delete")
@@ -243,10 +391,12 @@ runDeleteExample();
 
 ### Persistence
 
-Persist your store's state across browser sessions or synchronize it across multiple tabs.
+Persist your store's state across browser sessions or synchronize it across multiple tabs using persistence adapters from `@asaidimu/utils-persistence`. You can choose between `WebStoragePersistence` (for `localStorage` or `sessionStorage`) and `IndexedDBPersistence` for more robust storage.
 
 ```tsx
-import { createStore, WebStoragePersistence, IndexedDBPersistence } from '@asaidimu/react-store';
+import { createStore } from '@asaidimu/react-store';
+import { WebStoragePersistence, IndexedDBPersistence } from '@asaidimu/utils-persistence'; 
+import React, { useEffect } from 'react';
 
 // 1. Using WebStoragePersistence (localStorage by default)
 // Data persists even if the browser tab is closed and reopened.
@@ -255,7 +405,7 @@ const useLocalStore = createStore(
   {
     state: { sessionCount: 0, lastVisited: new Date().toISOString() },
     actions: {
-      incrementSessionCount: (state) => ({ sessionCount: state.sessionCount + 1 }),
+      incrementSessionCount: ({state}) => ({ sessionCount: state.sessionCount + 1 }),
       updateLastVisited: () => ({ lastVisited: new Date().toISOString() }),
     },
   },
@@ -283,7 +433,7 @@ const useUserProfileStore = createStore(
     state: { userId: '', preferences: { language: 'en', darkMode: false } },
     actions: {
       setUserId: (state, id: string) => ({ userId: id }),
-      toggleDarkMode: (state) => ({ preferences: { darkMode: !state.preferences.darkMode } }),
+      toggleDarkMode: ({state}) => ({ preferences: { darkMode: !state.preferences.darkMode } }),
     },
   },
   { persistence: indexedDBPersistence },
@@ -296,7 +446,7 @@ function AppWithPersistence() {
   const sessionCount = selectLocal(s => s.sessionCount);
   const darkMode = selectProfile(s => s.preferences.darkMode);
 
-  React.useEffect(() => {
+  useEffect(() => {
     if (localReady) {
       actionsLocal.incrementSessionCount();
       actionsLocal.updateLastVisited();
@@ -304,7 +454,7 @@ function AppWithPersistence() {
     if (profileReady && !selectProfile(s => s.userId)) {
       actionsProfile.setUserId('user-' + Math.random().toString(36).substring(2, 9));
     }
-  }, [localReady, profileReady]);
+  }, [localReady, profileReady, actionsLocal, actionsProfile, selectProfile]); // Added dependencies for useEffect
 
   if (!localReady || !profileReady) {
     return <div>Loading persisted data...</div>;
@@ -325,10 +475,11 @@ function AppWithPersistence() {
 
 ### Middleware
 
-Middleware functions can intercept and modify or block state updates. They are executed in the order they are added.
+Middleware functions can intercept and modify or block state updates. They are executed in the order they are added. Transforming middleware can alter the state update payload, while blocking middleware can prevent an update from proceeding.
 
 ```typescript
-import { createStore, Middleware, BlockingMiddleware } from '@asaidimu/react-store';
+import { createStore, type Middleware, type BlockingMiddleware } from '@asaidimu/react-store';
+import React from 'react';
 
 interface CartState {
   items: Array<{ id: string; name: string; quantity: number; price: number }>;
@@ -359,7 +510,7 @@ const validateItemMiddleware: BlockingMiddleware<CartState> = (state, update) =>
 const useCartStore = createStore({
   state: { items: [], total: 0 },
   actions: {
-    addItem: (state, item: { id: string; name: string; price: number }) => {
+    addItem: ({state}, item: { id: string; name: string; price: number }) => {
       const existingItem = state.items.find(i => i.id === item.id);
       if (existingItem) {
         return {
@@ -372,10 +523,11 @@ const useCartStore = createStore({
         items: [...state.items, { ...item, quantity: 1 }],
       };
     },
-    updateQuantity: (state, id: string, quantity: number) => ({
+    updateQuantity: ({state}, id: string, quantity: number) => ({
       items: state.items.map(item => (item.id === id ? { ...item, quantity } : item)),
     }),
   },
+  // Middleware now accepts an object mapping names to middleware functions
   middleware: { calculateTotal: calculateTotalMiddleware },
   blockingMiddleware: { validateItem: validateItemMiddleware },
 });
@@ -407,10 +559,11 @@ function CartComponent() {
 
 ### Observability
 
-Enable metrics and debugging via the `store` and `observer` objects:
+Enable metrics and debugging via the `observer` and `actionTracker` objects. The `enableMetrics` option in `createStore` is crucial for activating these features.
 
 ```tsx
 import { createStore } from '@asaidimu/react-store';
+import React from 'react';
 
 const useObservedStore = createStore(
   {
@@ -421,7 +574,7 @@ const useObservedStore = createStore(
     },
   },
   {
-    enableMetrics: true, // Crucial for enabling the 'observer' object
+    enableMetrics: true, // Crucial for enabling the 'observer' and 'actionTracker' objects
     enableConsoleLogging: true, // Log events directly to browser console
     logEvents: { updates: true, middleware: true, transactions: true }, // Which event types to log
     performanceThresholds: {
@@ -440,16 +593,16 @@ function DebugPanel() {
   // Access performance metrics
   const metrics = observer?.getPerformanceMetrics();
 
-  // Access state history for time travel
+  // Access state history for time travel (if maxStateHistory > 0)
   const timeTravel = observer?.createTimeTravel();
 
   // Access action execution history
-  const actionHistory = actionTracker.getExecutions();
+  const actionHistory = actionTracker?.getExecutions() || []; // actionTracker is only available if enableMetrics is true
 
   return (
     <div>
       <h2>Debug Panel</h2>
-      {observer && (
+      {observer && ( // Check if observer is enabled
         <>
           <h3>Performance Metrics</h3>
           <p>Update Count: {metrics?.updateCount}</p>
@@ -480,47 +633,50 @@ function DebugPanel() {
 
 ### Remote Observability
 
-Send collected metrics and traces to external systems like OpenTelemetry, Prometheus, or Grafana Cloud for centralized monitoring.
+Send collected metrics and traces to external systems like OpenTelemetry, Prometheus, or Grafana Cloud for centralized monitoring. This functionality typically resides in the `@asaidimu/utils-store` ecosystem.
 
 ```tsx
-import { createStore, useRemoteObservability } from '@asaidimu/react-store';
+import { createStore } from '@asaidimu/react-store';
+import { useRemoteObservability } from '@asaidimu/utils-store';
 import React, { useEffect } from 'react';
 
 const useRemoteStore = createStore(
   {
     state: { apiCallsMade: 0, lastApiError: null },
     actions: {
-      simulateApiCall: async (state) => {
-        // Simulate an error 10% of the time
+      simulateApiCall: async ({state}) => {
         if (Math.random() < 0.1) {
           throw new Error('API request failed');
         }
         return { apiCallsMade: state.apiCallsMade + 1, lastApiError: null };
       },
-      handleApiError: (state, error: string) => ({ lastApiError: error })
+      handleApiError: ({state}, error: string) => ({ lastApiError: error })
     },
   },
   {
     enableMetrics: true, // Required for RemoteObservability
     enableConsoleLogging: false,
-    collectCategories: {
-      performance: true,
-      errors: true,
-      stateChanges: true,
-      middleware: true,
-    },
-    reportingInterval: 10000, // Send metrics every 10 seconds
-    batchSize: 10, // Send after 10 metrics or interval, whichever comes first
-    immediateReporting: false, // Don't send immediately after each metric
+    // collectCategories configuration would typically be passed to useRemoteObservability
+    // reportingInterval, batchSize, immediateReporting would also be part of useRemoteObservability options
   }
 );
 
 function MonitoringIntegration() {
   const { store, observer } = useRemoteStore();
+  // useRemoteObservability is assumed to be part of utils-store or a separate utility
   const { remote, addOpenTelemetryDestination, addPrometheusDestination, addGrafanaCloudDestination } = useRemoteObservability(store, {
     serviceName: 'my-react-app',
     environment: 'development',
     instanceId: `web-client-${Math.random().toString(36).substring(2, 9)}`,
+    collectCategories: {
+      performance: true,
+      errors: true,
+      stateChanges: true,
+      middleware: true,
+    },
+    reportingInterval: 10000, // Send metrics every 10 seconds
+    batchSize: 10, // Send after 10 metrics or interval, whichever comes first
+    immediateReporting: false, // Don't send immediately after each metric
   });
 
   useEffect(() => {
@@ -551,24 +707,31 @@ function MonitoringIntegration() {
     }, 5000); // Report every 5 seconds
 
     return () => clearInterval(interval);
-  }, []);
+  }, [observer, addOpenTelemetryDestination, addPrometheusDestination, addGrafanaCloudDestination]); // Added dependencies
 
   return null; // This component doesn't render anything visually
 }
 
-// In your App component:
-// <MonitoringIntegration />
-// <button onClick={() => useRemoteStore().actions.simulateApiCall().catch(e => useRemoteStore().actions.handleApiError(e.message))}>
-//   Simulate API Call
-// </button>
+// In your App component, you would use it like:
+// function MyApp() {
+//   return (
+//     <>
+//       <MonitoringIntegration />
+//       <button onClick={() => useRemoteStore().actions.simulateApiCall().catch(e => useRemoteStore().actions.handleApiError(e.message))}>
+//         Simulate API Call
+//       </button>
+//     </>
+//   );
+// }
 ```
 
 ### Transaction Support
 
-Group related updates that should succeed or fail together. If an error occurs within the transaction, all changes made during that transaction are automatically rolled back.
+Group related updates that should succeed or fail together. If an error occurs within the transaction, all changes made during that transaction are automatically rolled back, maintaining state consistency.
 
 ```typescript
 import { createStore } from '@asaidimu/react-store';
+import React from 'react';
 
 interface BankState {
   checking: number;
@@ -579,7 +742,7 @@ interface BankState {
 const useBankStore = createStore<BankState, any>({
   state: { checking: 1000, savings: 500, transactions: [] },
   actions: {
-    transferFunds: async (state, fromAccount: 'checking' | 'savings', toAccount: 'checking' | 'savings', amount: number) => {
+    transferFunds: async ({state}, fromAccount: 'checking' | 'savings', toAccount: 'checking' | 'savings', amount: number) => {
       if (amount <= 0) {
         throw new Error('Transfer amount must be positive.');
       }
@@ -607,14 +770,15 @@ const useBankStore = createStore<BankState, any>({
 });
 
 function BankApp() {
-  const { select, actions } = useBankStore();
+  const { select, actions, store } = useBankStore();
   const checkingBalance = select(s => s.checking);
   const savingsBalance = select(s => s.savings);
   const transactions = select(s => s.transactions);
 
   const handleTransfer = async (from: 'checking' | 'savings', to: 'checking' | 'savings', amount: number) => {
     try {
-      await actions.transferFunds(from, to, amount);
+      // Wrap the action call in a store transaction
+      await store.transaction(() => actions.transferFunds(from, to, amount));
       alert(`Successfully transferred ${amount} from ${from} to ${to}.`);
     } catch (error) {
       alert(`Transfer failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -642,7 +806,7 @@ function BankApp() {
 
 ### Event System
 
-The store emits various events during its lifecycle, which you can subscribe to for logging, analytics, or custom side effects.
+The store emits various events during its lifecycle, which you can subscribe to for logging, analytics, or custom side effects. This is done via `store.onStoreEvent()`.
 
 ```typescript
 import { createStore } from '@asaidimu/react-store';
@@ -652,7 +816,7 @@ const useEventStore = createStore(
   {
     state: { data: 'initial', processedCount: 0 },
     actions: {
-      processData: (state, newData: string) => ({ data: newData, processedCount: state.processedCount + 1 }),
+      processData: ({state}, newData: string) => ({ data: newData, processedCount: state.processedCount + 1 }),
       triggerError: () => { throw new Error("Action failed intentionally"); }
     },
     middleware: {
@@ -665,7 +829,7 @@ const useEventStore = createStore(
 );
 
 function EventMonitor() {
-  const { store } = useEventStore();
+  const { store, actions } = useEventStore();
   const [eventLogs, setEventLogs] = React.useState<string[]>([]);
 
   useEffect(() => {
@@ -718,8 +882,6 @@ function EventMonitor() {
     };
   }, [store]); // Re-subscribe if store instance changes (unlikely)
 
-  const { actions } = useEventStore();
-
   return (
     <div>
       <h3>Store Event Log</h3>
@@ -756,7 +918,7 @@ const useDataStore = createStore({
       await new Promise(resolve => setTimeout(resolve, 2000));
       return { items: ['Item A', 'Item B', 'Item C'] };
     },
-    addItem: async (state, item: string) => {
+    addItem: async ({state}, item: string) => {
       // Simulate a quick add operation
       await new Promise(resolve => setTimeout(resolve, 500));
       return { items: [...state.items, item] };
@@ -798,19 +960,22 @@ function DataLoader() {
 The hook returned by `createStore` provides several properties for advanced usage and debugging, beyond the commonly used `select`, `actions`, and `isReady`:
 
 ```tsx
+import { useStore as useMyStore } from '../ui/store'; // Assuming this is your store definition
+
 function MyAdvancedComponent() {
   const {
-    select,        // Function to select state parts (memoized)
-    actions,       // Object containing your defined actions (debounced)
+    select,        // Function to select state parts (memoized, reactive)
+    actions,       // Object containing your defined actions (debounced, promise-returning)
     isReady,       // Boolean indicating if persistence is ready
-    store,         // Direct access to the ReactiveDataStore instance
-    observer,      // StoreObservability instance (if `enableMetrics` was true)
-    actionTracker, // Instance of ActionTracker for monitoring action executions
-    state,         // A hook `() => T` to get the entire reactive state object
+    store,         // Direct access to the ReactiveDataStore instance (from @asaidimu/utils-store)
+    observer,      // StoreObservability instance (from @asaidimu/utils-store, if `enableMetrics` was true)
+    actionTracker, // Instance of ActionTracker for monitoring action executions (if `enableMetrics` was true)
+    state,         // A getter function `() => TState` to get the entire current state object (reactive)
     watch,         // Function to watch the loading status of actions
+    resolve,       // Function to resolve an artifact (if artifacts are defined)
   } = useMyStore(); // Assuming useMyStore is defined from createStore
 
-  // Example: Accessing the full state (use with caution for performance, `select` is preferred)
+  // Example: Accessing the full state (use with caution for performance; `select` is preferred)
   const fullCurrentState = state();
   console.log("Full reactive state:", fullCurrentState);
 
@@ -821,15 +986,24 @@ function MyAdvancedComponent() {
   }
 
   // Example: Accessing action history
-  console.log("Action executions:", actionTracker.getExecutions());
+  if (actionTracker) { // actionTracker is only available if enableMetrics is true
+    console.log("Action executions:", actionTracker.getExecutions());
+  }
 
   // Example: Watching a specific action's loading state
-  const isLoadingSomeAction = watch('someActionName');
-  console.log("Is 'someActionName' loading?", isLoadingSomeAction);
+  const isLoadingSomeAction = watch('checkout'); // Assuming 'checkout' is an action
+  console.log("Is 'checkout' action loading?", isLoadingSomeAction);
+
+  // Example: Resolving an artifact (if defined in your store)
+  // const [myArtifact, isArtifactReady] = resolve('myArtifactKey');
+  // if (isArtifactReady) {
+  //   console.log("My artifact is ready:", myArtifact);
+  // }
 
   return (
     <div>
       {/* ... your component content ... */}
+      <p>Store Ready: {isReady ? 'Yes' : 'No'}</p>
     </div>
   );
 }
@@ -837,22 +1011,19 @@ function MyAdvancedComponent() {
 
 ## Project Architecture
 
-`@asaidimu/react-store` is structured to provide a modular yet integrated state management solution.
+`@asaidimu/react-store` is structured to provide a modular yet integrated state management solution. It separates core state logic into reusable utilities while offering a streamlined React-specific API.
 
 ### Internal Structure
 
-The core logic of this package resides directly within the `src/` directory:
+The core logic of this package integrates and extends external utility packages, with `src/store.ts` serving as the main entry point for the React hook.
 
 ```
 .
 ├── src/
-│   ├── execution.ts            # Action tracking interface and class
-│   ├── hash.ts                 # Utilities for hashing objects (e.g., for selectors)
-│   ├── paths.ts                # Utility for building selector paths
-│   ├── selector.ts             # Selector memoization manager
-│   ├── store.ts                # Main `createStore` React hook implementation
-│   └── types.ts                # Core TypeScript types for the library
-├── index.ts                    # Main entry point for the library (re-exports `createStore` and other public APIs)
+│   ├── execution.ts            # Manages tracking and history of action executions.
+│   ├── store.ts                # The main `createStore` function, integrating `ReactiveDataStore` and `StoreObservability` from `@asaidimu/utils-store` with React's `useSyncExternalStore`.
+│   └── types.ts                # Defines core TypeScript interfaces for store definitions, actions, middleware, and the store hook.
+├── index.ts                    # Main library entry point, re-exporting `createStore` and core types.
 ├── package.json
 └── tsconfig.json
 ```
@@ -861,37 +1032,39 @@ The core logic of this package resides directly within the `src/` directory:
 
 This library leverages the following `@asaidimu` packages for its core functionalities:
 
-*   **`@asaidimu/utils-store`**: Provides the foundational `ReactiveDataStore` for state management, including immutable updates, transactions, and core event emission. It also includes `StoreObservability` for deep insights into state changes.
-*   **`@asaidimu/utils-persistence`**: Offers persistence adapters like `WebStoragePersistence` and `IndexedDBPersistence` for saving and loading state.
+*   **`@asaidimu/utils-store`**: Provides the foundational `ReactiveDataStore` for immutable state management, transactions, core event emission, and the `StoreObservability` instance for deep insights into state changes.
+*   **`@asaidimu/utils-persistence`**: Offers various persistence adapters like `WebStoragePersistence` and `IndexedDBPersistence` for saving and loading state, including cross-tab synchronization.
 
 ### Core Components
 
-*   **`ReactiveDataStore` (from `@asaidimu/utils-store`)**: The foundational state management layer. This external library manages the immutable state, processes updates, handles middleware, transactions, and interacts with persistence adapters. It also emits detailed internal events for observability.
-*   **`StoreObservability` (from `@asaidimu/utils-store`)**: An extension built on top of the external `ReactiveDataStore`'s event system. It provides debugging features like event history, state snapshots for time-travel, performance metrics, and utilities to create logging/validation middleware.
-*   **`createStore` Hook (`src/store.ts`)**: The primary React-facing API. It instantiates the external `ReactiveDataStore` and `StoreObservability`, wraps actions with debouncing and tracking, and provides the `select` hook powered by `useSyncExternalStore` for efficient component updates, and the `watch` function for action loading states.
-*   **Persistence Adapters (from `@asaidimu/utils-persistence`)**: Implement the `DataStorePersistence` interface. `WebStoragePersistence` and `IndexedDBPersistence` provide concrete storage solutions with cross-tab synchronization.
+*   **`ReactiveDataStore` (from `@asaidimu/utils-store`)**: The heart of the state management. It handles immutable state updates, middleware processing, transaction management, and emits detailed internal events about state changes.
+*   **`StoreObservability` (from `@asaidimu/utils-store`)**: Built on top of `ReactiveDataStore`'s event system, this component provides comprehensive debugging and monitoring features. This includes event history, state snapshots for time-travel, performance metrics, and utilities for logging or validation middleware.
+*   **`ActionTracker` (`src/execution.ts`)**: A dedicated class for tracking the lifecycle and performance of individual action executions, capturing details like start/end times, duration, parameters, and outcomes (success/error).
+*   **`createStore` Hook (`src/store.ts`)**: The primary React-facing API. It instantiates `ReactiveDataStore`, `StoreObservability`, and `ActionTracker`. It wraps user-defined actions with debouncing and tracking, and provides the `select` function (powered by `useSyncExternalStore` for efficient component updates) and the `watch` function for action loading states.
+*   **Persistence Adapters (from `@asaidimu/utils-persistence`)**: Implement the `DataStorePersistence` interface. `WebStoragePersistence` (for `localStorage`/`sessionStorage`) and `IndexedDBPersistence` provide concrete, ready-to-use storage solutions with cross-tab synchronization capabilities.
 
 ### Data Flow
 
-1.  **Action Dispatch**: A React component calls an action (e.g., `actions.increment(1)`). Actions are debounced by default.
-2.  **Action Loading State Update**: The store immediately updates the loading state for the dispatched action to `true`.
-3.  **Action Execution Tracking**: The `ActionTracker` records the action's details (name, params, start time).
-4.  **State Update Request**: The action, after potential debouncing, initiates a `store.set()` call with a partial state update or a function returning a partial object.
-5.  **Transaction Context**: If within a `store.transaction()`, the state is snapshotted for potential rollback.
-6.  **Blocking Middleware**: Updates first pass through `blockingMiddleware`. If any middleware returns `false` or throws, the update is halted, and the state is not modified.
-7.  **Transform Middleware**: If not blocked, updates then pass through transforming `middleware`. These functions can modify the partial update.
-8.  **State Merging**: The final transformed update is immutably merged into the current state using `ReactiveDataStore`'s internal merge utility.
-9.  **Change Detection**: `ReactiveDataStore`'s internal diffing mechanism identifies which paths in the state have truly changed.
-10. **Persistence**: If changes occurred, the new state is saved via the configured `DataStorePersistence` adapter (e.g., `localStorage`, `IndexedDB`). External changes from persistence are also subscribed to and applied.
-11. **Listener Notification**: Only `React.useSyncExternalStore` subscribers whose selected paths have changed are notified, triggering re-renders of relevant components.
-12. **Action Loading State Reset**: Once the action completes (success or error), the loading state for that action is reset to `false`.
-13. **Observability Events**: Throughout this flow, the `ReactiveDataStore` emits fine-grained events (`update:start`, `middleware:complete`, `transaction:error`, etc.) that `StoreObservability` captures for debugging, metrics, and remote reporting.
+1.  **Action Dispatch**: A React component calls a bound action (e.g., `actions.addItem()`).
+2.  **Action Debouncing**: Actions are debounced by default (configurable), preventing rapid successive calls.
+3.  **Action Loading State Update**: The store immediately updates the loading state for the dispatched action to `true` via `ReactiveDataStore`.
+4.  **Action Execution Tracking**: The `ActionTracker` records the action's details (name, parameters, start time).
+5.  **State Update Request**: The action's implementation returns a partial state update or a promise resolving to one.
+6.  **Transaction Context**: If the action is wrapped within `store.transaction()`, the current state is snapshotted to enable potential rollback.
+7.  **Blocking Middleware**: The update first passes through any registered `blockingMiddleware`. If any middleware returns `false` or throws an error, the update is halted, and the state remains unchanged (and rolled back if in a transaction).
+8.  **Transform Middleware**: If not blocked, the update then passes through transforming `middleware`. These functions can modify the partial update payload.
+9.  **State Merging**: The final, possibly transformed, update is immutably merged into the current state using `ReactiveDataStore`'s internal utility.
+10. **Change Detection**: `ReactiveDataStore` performs a deep diff to identify precisely which paths in the state have changed.
+11. **Persistence**: If changes occurred, the new state is saved via the configured `DataStorePersistence` adapter (e.g., `localStorage`, `IndexedDB`). The system also subscribes to external changes from persistence for cross-tab synchronization.
+12. **Listener Notification**: `React.useSyncExternalStore` subscribers (used by `select`) whose selected paths have changed are notified, triggering efficient re-renders of only the relevant components.
+13. **Action Loading State Reset**: Once the action completes (either successfully or with an error), the loading state for that action is reset to `false`.
+14. **Observability Events**: Throughout this entire flow, `ReactiveDataStore` emits fine-grained events (`update:start`, `middleware:complete`, `transaction:error`, etc.) which `StoreObservability` captures for debugging, metrics collection, and remote reporting.
 
 ### Extension Points
 
-*   **Custom Middleware**: Easily add your own `Middleware` or `BlockingMiddleware` functions for custom logic.
-*   **Custom Persistence Adapters**: Implement the `DataStorePersistence<T>` interface to integrate with any storage solution (e.g., a backend API, WebSockets, or a custom in-memory store).
-*   **Remote Observability Destinations**: Create new `RemoteDestination` implementations to send metrics and traces to any external observability platform not already supported.
+*   **Custom Middleware**: Easily add your own `Middleware` or `BlockingMiddleware` functions for custom logic (e.g., advanced logging, validation, side effects).
+*   **Custom Persistence Adapters**: Implement the `DataStorePersistence<T>` interface (from `@asaidimu/utils-persistence`) to integrate with any storage solution (e.g., a backend API, WebSockets, or a custom in-memory store).
+*   **Remote Observability Destinations**: Create new `RemoteDestination` implementations (part of `@asaidimu/utils-store`) to send metrics and traces to any external observability platform not already supported by default.
 
 ## Development & Contributing
 
@@ -901,7 +1074,7 @@ We welcome contributions! Please follow the guidelines below.
 
 1.  **Clone the repository:**
     ```bash
-    git clone https://github.com/asaidimu/react-store.git
+    git clone https://github.com/asaidimu/node-react.git
     cd react-store
     ```
 2.  **Install dependencies:**
@@ -912,18 +1085,18 @@ We welcome contributions! Please follow the guidelines below.
 
 ### Scripts
 
-*   `bun ci`: Installs dependencies (for CI/CD environments).
-*   `bun test`: Runs all unit tests using `Vitest`.
-*   `bun test:ci`: Runs tests in CI mode (single run).
-*   `bun clean`: Removes the `dist` directory.
-*   `bun prebuild`: Cleans `dist` and runs a sync script (internal).
-*   `bun build`: Compiles the TypeScript source into `dist/` for CJS and ESM formats, generates type definitions, and minifies.
-*   `bun dev`: Starts the e-commerce dashboard demonstration.
-*   `bun postbuild`: Copies `README.md`, `LICENSE.md`, and `dist.package.json` into the `dist` folder.
+*   `bun ci`: Installs dependencies, typically used in CI/CD environments to ensure a clean install.
+*   `bun test`: Runs all unit tests using `Vitest` in interactive watch mode.
+*   `bun test:ci`: Runs all unit tests once, suitable for CI/CD pipelines.
+*   `bun clean`: Removes the `dist` directory, cleaning up previous build artifacts.
+*   `bun prebuild`: Pre-build step that cleans the `dist` directory and runs an internal package synchronization script.
+*   `bun build`: Compiles the TypeScript source into `dist/` for CJS and ESM formats, generates type definitions, and minifies the code using `Terser`.
+*   `bun dev`: Starts the e-commerce dashboard demonstration application using `Vite`.
+*   `bun postbuild`: Post-build step that copies `README.md`, `LICENSE.md`, and the specialized `dist.package.json` into the `dist` folder, preparing the package for publishing.
 
 ### Testing
 
-Tests are written using `Vitest` and `React Testing Library`.
+Tests are written using `Vitest` and `React Testing Library` for component and hook testing.
 
 To run tests:
 
@@ -937,103 +1110,103 @@ bun test --watch
 
 1.  **Fork** the repository and create your branch from `main`.
 2.  **Code Standards**: Ensure your code adheres to existing coding styles (TypeScript, ESLint, Prettier are configured).
-3.  **Tests**: Add unit and integration tests for new features or bug fixes. Ensure all tests pass.
-4.  **Commits**: Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.
-5.  **Pull Requests**: Submit a pull request to the `main` branch. Provide a clear description of your changes.
+3.  **Tests**: Add unit and integration tests for new features or bug fixes. Ensure all tests pass (`bun test`).
+4.  **Commits**: Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages. This project uses `semantic-release` for automated versioning and changelog generation.
+5.  **Pull Requests**: Submit a pull request to the `main` branch. Provide a clear description of your changes, referencing any relevant issues.
 
 ### Issue Reporting
 
-For bugs, feature requests, or questions, please open an issue on the [GitHub Issues page](https://github.com/asaidimu/react-store/issues).
+For bugs, feature requests, or questions, please open an issue on the [GitHub Issues page](https://github.com/asaidimu/node-react/issues).
 
 ## Additional Information
 
 ### Best Practices
 
-1.  **Granular Selectors**: Always use `select((state) => state.path.to.value)` instead of `select((state) => state)` to prevent unnecessary re-renders of components.
-2.  **Action Design**: Keep actions focused on a single responsibility. Use `async` actions for asynchronous operations and return partial updates upon completion.
+1.  **Granular Selectors**: Always use `select((state) => state.path.to.value)` instead of `select((state) => state)` to prevent unnecessary re-renders of components. The more specific your selector, the more optimized your component updates will be.
+2.  **Action Design**: Keep actions focused on a single responsibility. Use `async` actions for asynchronous operations (e.g., API calls) and return partial updates or promises resolving to partial updates upon completion. Actions should describe *what* happened, not *how*.
 3.  **Persistence**:
     *   Use unique `storeId` or `storageKey` for each distinct store to avoid data conflicts.
-    *   Always check the `isReady` flag for UI elements that depend on the initial state loaded from persistence.
-4.  **Middleware**: Leverage middleware for cross-cutting concerns like logging, analytics, or complex validation logic.
-5.  **`Symbol.for("delete")`**: Use this explicit symbol for property removal to maintain clarity and avoid accidental data mutations.
+    *   Always check the `isReady` flag for UI elements that depend on the initial state loaded from persistence, to prevent rendering incomplete data.
+4.  **Middleware**: Leverage middleware for cross-cutting concerns like logging, analytics, data transformation, or complex validation logic that applies to multiple actions.
+5.  **`Symbol.for("delete")`**: Use this explicit symbol for property removal to maintain clarity and avoid accidental data mutations or unexpected behavior when merging partial updates.
+6.  **Debounce Time**: Adjust the `debounceTime` in `createStore` options for actions that might be called rapidly (e.g., search input, scroll events) to optimize performance. A `debounceTime` of `0` means actions execute immediately.
 
 ### API Reference
 
 #### `createStore(definition, options)`
 
-The main entry point for creating a store.
+The main entry point for creating a store hook.
 
 ```typescript
-type StoreDefinition<T, R extends Actions<T>> = {
-  state: T; // Initial state object
-  actions: R; // Object mapping action names to action functions
-  middleware?: Record<string, Middleware<T>>; // Optional transforming middleware
-  blockingMiddleware?: Record<string, BlockingMiddleware<T>>; // Optional blocking middleware
-};
+// From src/types.ts
+export interface StoreDefinition<
+    TState extends object,
+    TArtifactsMap extends ArtifactsMap<TState>, // Artifacts can be defined but not shown in this example
+    TActions extends ActionMap<TState, TArtifactsMap>,
+> {
+    state: TState;
+    actions: TActions;
+    artifacts?: TArtifactsMap; // Optional artifact definitions
+    blockingMiddleware?: Record<string, BlockingMiddleware<TState>>; // Optional blocking middleware
+    middleware?: Record<string, Middleware<TState>>; // Optional transforming middleware
+}
 
-interface StoreOptions<T> {
-  enableMetrics?: boolean; // Enable StoreObservability features (default: false)
-  enableConsoleLogging?: boolean; // Log store events to console (default: false)
-  maxEvents?: number; // Maximum number of events to keep in history (default: 500)
-  maxStateHistory?: number; // Maximum number of state snapshots for time travel (default: 20)
-  logEvents?: { // Which event categories to log (defaults to all true if enableConsoleLogging is true)
-    updates?: boolean;
-    middleware?: boolean;
-    transactions?: boolean;
-  };
-  performanceThresholds?: { // Thresholds for logging slow operations (in ms)
-    updateTime?: number; // default: 50ms
-    middlewareTime?: number; // default: 20ms
-  };
-  persistence?: DataStorePersistence<T>; // Optional persistence adapter instance
-  debounceTime?: number; // Time in milliseconds to debounce actions (default: 0ms)
+interface StoreOptions<T> extends ObserverOptions { // ObserverOptions from @asaidimu/utils-store
+    enableMetrics?: boolean; // Enable StoreObservability and ActionTracker features (default: false)
+    persistence?: SimplePersistence<T>; // Optional persistence adapter instance (from @asaidimu/utils-persistence)
+    debounceTime?: number; // Time in milliseconds to debounce actions (default: 0ms)
+    // Other ObserverOptions for logging, performanceThresholds, maxEvents, maxStateHistory are inherited
 }
 
-const useStore = createStore(definition, options);
+const useStoreHook = createStore(definition, options);
 ```
 
-**Returns**: A `useStore` hook which, when called in a component, returns an object with:
-*   `store`: Direct access to the `ReactiveDataStore` instance.
-*   `observer`: The `StoreObservability` instance (available if `enableMetrics` is `true`). Provides debug and monitoring utilities.
-*   `select`: A memoized selector function to extract specific state slices. Re-renders components only when selected data changes.
-*   `actions`: An object containing your defined actions. These actions are debounced and tracked.
-*   `actionTracker`: An instance of `ActionTracker` for monitoring the execution history of your actions.
-*   `state`: A hook `() => T` that returns the entire current state object. Use sparingly as it will cause re-renders on *any* state change.
+**Returns**: A React hook (`useStoreHook`) which, when called in a component, returns an object with the following properties:
+
+*   `store`: Direct access to the underlying `ReactiveDataStore` instance (from `@asaidimu/utils-store`). This provides low-level control and event subscription.
+*   `observer`: The `StoreObservability` instance (from `@asaidimu/utils-store`). Available only if `enableMetrics` is `true`. Provides debug, time-travel, and monitoring utilities.
+*   `select`: A memoized selector function `(<S>(selector: (state: TState) => S) => S)`. Extracts specific state slices. Re-renders components only when selected data changes.
+*   `actions`: An object containing your defined actions, fully typed and bound to the store. These actions are debounced (if `debounceTime` > 0) and their loading states are tracked. Each action returns a `Promise<TState>` resolving to the new state after the action completes.
+*   `actionTracker`: An instance of `ActionTracker` (from `src/execution.ts`). Available only if `enableMetrics` is `true`. Provides methods for monitoring the execution history of your actions.
+*   `state`: A getter function `(() => TState)` that returns the entire current state object. Use sparingly, as components relying on this will re-render on *any* state change. `select` is generally preferred for performance.
 *   `isReady`: A boolean indicating whether the store's persistence layer (if configured) has finished loading its initial state.
-*   `watch`: A function to watch the loading status of actions.
+*   `watch`: A function `(<K extends keyof TActions>(action: K) => boolean)` to watch the loading status of individual actions. Returns `true` if the action is currently executing.
+*   `resolve`: A reactive artifact resolver `(<K extends keyof TArtifactsMap>(key: K) => readonly [ExtractInstanceFromMap<TArtifactsMap, K>, true] | readonly [ExtractInstanceFromMap<TArtifactsMap, K> | undefined, false])`. If `artifacts` are defined in the store, this hook returns `[instance, isReady]` for a specific artifact, reactively updating if the artifact instance changes or becomes ready.
 
-#### `ReactiveDataStore` (accessed via `useStore().store`)
+#### `ReactiveDataStore` (accessed via `useStoreHook().store` from `@asaidimu/utils-store`)
 
-*   `get(clone?: boolean): T`: Retrieves the current state. Pass `true` to get a deep clone (recommended for mutations outside of actions).
-*   `set(update: StateUpdater<T>): Promise<void>`: Updates the state with a partial object or a function returning a partial object.
-*   `subscribe(path: string | string[], listener: (state: T) => void): () => void`: Subscribes a listener to changes at a specific path or array of paths. Returns an unsubscribe function.
-*   `transaction<R>(operation: () => R | Promise<R>): Promise<R}`: Executes a function as an atomic transaction. Rolls back all changes if an error occurs.
-*   `use(middleware: Middleware<T>, name?: string): string`: Adds a transforming middleware. Returns its ID.
-*   `useBlockingMiddleware(middleware: BlockingMiddleware<T>, name?: string): string`: Adds a blocking middleware. Returns its ID.
+*   `get(clone?: boolean): TState`: Retrieves the current state. Pass `true` to get a deep clone (recommended for mutations outside of actions).
+*   `set(update: StateUpdater<TState>): Promise<void>`: Updates the state with a partial object or a function returning a partial object.
+*   `subscribe(path: string | string[], listener: (state: TState) => void): () => void`: Subscribes a listener to changes at a specific path or array of paths. Returns an unsubscribe function.
+*   `transaction<R>(operation: () => R | Promise<R>): Promise<R>`: Executes a function as an atomic transaction. Rolls back all changes if an error occurs if the operation throws.
+*   `use(middleware: Middleware<TState>, name?: string): string`: Adds a transforming middleware. Returns its ID.
+*   `useBlockingMiddleware(middleware: BlockingMiddleware<TState>, name?: string): string`: Adds a blocking middleware. Returns its ID.
 *   `removeMiddleware(id: string): boolean`: Removes a middleware by its ID.
 *   `isReady(): boolean`: Checks if the persistence layer has loaded its initial state.
-*   `onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void`: Subscribes to internal store events (e.g., `'update:complete'`, `'middleware:error'`).
+*   `onStoreEvent(event: StoreEvent, listener: (data: any) => void): () => void`: Subscribes to internal store events (e.g., `'update:complete'`, `'middleware:error'`, `'transaction:start'`).
+
+#### `StoreObservability` (accessed via `useStoreHook().observer` from `@asaidimu/utils-store`)
 
-#### `StoreObservability` (accessed via `useStore().observer`)
+Available only if `enableMetrics` is `true` in `createStore` options.
 
 *   `getEventHistory(): DebugEvent[]`: Retrieves a history of all captured store events.
-*   `getStateHistory(): T[]`: Returns a history of state snapshots, enabling time-travel.
-*   `getRecentChanges(limit?: number): Array<{ timestamp: number; changedPaths: string[]; from: Partial<T>; to: Partial<T>; }>`: Provides a simplified view of recent state changes.
+*   `getStateHistory(): TState[]`: Returns a history of state snapshots, enabling time-travel debugging (if `maxStateHistory` > 0).
+*   `getRecentChanges(limit?: number): Array<{ timestamp: number; changedPaths: string[]; from: DeepPartial<TState>; to: DeepPartial<TState>; }>`: Provides a simplified view of recent state changes.
 *   `getPerformanceMetrics(): StoreMetrics`: Returns an object containing performance statistics (e.g., `updateCount`, `averageUpdateTime`).
 *   `createTimeTravel(): { canUndo: () => boolean; canRedo: () => boolean; undo: () => Promise<void>; redo: () => Promise<void>; getHistoryLength: () => number; clear: () => void; }`: Returns controls for time-travel debugging.
-*   `createLoggingMiddleware(options?: object): Middleware<T>`: A factory for a simple logging middleware.
-*   `createValidationMiddleware(validator: (state: T, update: DeepPartial<T>) => boolean | { valid: boolean; reason?: string }): BlockingMiddleware<T>`: A factory for a schema validation middleware.
+*   `createLoggingMiddleware(options?: object): Middleware<TState>`: A factory for a simple logging middleware.
+*   `createValidationMiddleware(validator: (state: TState, update: DeepPartial<TState>) => boolean | { valid: boolean; reason?: string }): BlockingMiddleware<TState>`: A factory for a schema validation middleware.
 *   `clearHistory(): void`: Clears the event and state history.
 *   `disconnect(): void`: Cleans up all listeners and resources.
 
-#### Persistence Adapters
+#### Persistence Adapters (from `@asaidimu/utils-persistence`)
 
-All adapters implement `DataStorePersistence<T>`:
+All adapters implement `SimplePersistence<T>`:
 
 *   `set(id:string, state: T): boolean | Promise<boolean>`: Persists data.
-*   `get(): T | null | Promise<T | null>`: Retrieves data.
-*   `subscribe(id:string, callback: (state:T) => void): () => void`: Subscribes to external changes.
-*   `clear(): boolean | Promise<boolean>`: Clears persisted data.
+*   `get(id:string): T | null | Promise<T | null>`: Retrieves data.
+*   `subscribe(id:string, callback: (state:T) => void): () => void`: Subscribes to external changes (e.g., from other tabs).
+*   `clear(id:string): boolean | Promise<boolean>`: Clears persisted data.
 
 ##### `IndexedDBPersistence(storeId: string)`
 
@@ -1044,13 +1217,9 @@ All adapters implement `DataStorePersistence<T>`:
 *   **`storageKey`**: The key under which data is stored (e.g., `'app-config'`).
 *   **`session`**: Optional. If `true`, uses `sessionStorage`; otherwise, uses `localStorage` (default: `false`).
 
-##### `LocalStoragePersistence(storageKey: string)` (Deprecated)
-
-*   This is an alias for `WebStoragePersistence`. Use `WebStoragePersistence` instead.
-
 ### Comparison with Other State Management Solutions
 
-`@asaidimu/react-store` aims to be a comprehensive, all-in-one solution for React state management. Here's a comparison to popular alternatives:
+`@asaidimu/react-store` aims to be a comprehensive, all-in-one solution for React state management, integrating features that often require multiple libraries in other ecosystems. Here's a comparison to popular alternatives:
 
 | **Feature**            | **@asaidimu/react-store** | **Redux**          | **Zustand**        | **MobX**           | **Recoil**         |
 | :--------------------- | :------------------------ | :----------------- | :----------------- | :----------------- | :----------------- |
@@ -1059,20 +1228,59 @@ All adapters implement `DataStorePersistence<T>`:
 | **API Complexity**     | Medium (rich feature set balanced with simplicity). | High (many concepts: actions, reducers, etc.). | Low (straightforward). | Medium (proxies, decorators). | Medium (atom/selectors). |
 | **Scalability**        | High (transactions, persistence, remote metrics). | High (structured but verbose). | High (small but flexible). | High (reactive scaling). | High (granular atoms). |
 | **Extensibility**      | Excellent (middleware, custom persistence, observability). | Good (middleware, enhancers). | Good (middleware-like). | Moderate (custom reactions). | Moderate (custom selectors). |
-| **Performance**        | Optimized (selectors, reactive updates). | Good (predictable but manual optimization). | Excellent (minimal overhead). | Good (reactive overhead). | Good (granular updates). |
-| **Bundle Size**        | Moderate (includes observability, persistence, remote observability). | Large (core + toolkit). | Tiny (~1KB). | Moderate (~20KB). | Moderate (~10KB). |
+| **Performance**        | Optimized (selectors, reactive updates via `useSyncExternalStore`). | Good (predictable but manual optimization). | Excellent (minimal overhead). | Good (reactive overhead). | Good (granular updates). |
+| **Bundle Size**        | Moderate (includes observability, persistence, remote observability framework). | Large (core + toolkit). | Tiny (~1KB). | Moderate (~20KB). | Moderate (~10KB). |
 | **Persistence**        | Built-in (IndexedDB, WebStorage, cross-tab). | Manual (via middleware). | Manual (via middleware). | Manual (custom). | Manual (custom). |
-| **Observability**      | Excellent (metrics, time-travel, remote). | Good (dev tools). | Basic (via plugins). | Good (reactive logs). | Basic (via plugins). |
-| **React Integration**  | Native (hooks, `useSyncExternalStore`) | Manual (React-Redux). | Native (hooks). | Native (observers). | Native (atoms). |
+| **Observability**      | Excellent (metrics, time-travel, event logging, remote). | Good (dev tools). | Basic (via plugins). | Good (reactive logs). | Basic (via plugins). |
+| **React Integration**  | Native (hooks, `useSyncExternalStore`). | Manual (React-Redux). | Native (hooks). | Native (observers). | Native (atoms). |
 
 #### Where `@asaidimu/react-store` Shines
-*   **All-in-One**: It aims to be a single solution for state management, persistence, and observability, reducing the need for multiple external dependencies.
-*   **Flexibility**: The robust middleware system and transaction support make it highly adaptable to complex business logic and data flows.
-*   **Modern React**: It leverages `useSyncExternalStore` for direct integration with React's concurrency model, ensuring efficient and up-to-date component renders.
+*   **All-in-One**: It aims to be a single solution for state management, persistence, and observability, reducing the need for multiple external dependencies and their integration complexities.
+*   **Flexibility**: The robust middleware system, transaction support, and artifact management make it highly adaptable to complex business logic, asynchronous data flows, and dependency injection patterns.
+*   **Modern React**: It leverages `useSyncExternalStore` for direct integration with React's concurrency model, ensuring efficient and up-to-date component renders with minimal overhead.
 
 #### Trade-Offs
-*   **Bundle Size**: While comprehensive, it naturally has a larger bundle size compared to minimalist alternatives like Zustand, as it includes a wider range of features out-of-the-box.
-*   **Learning Curve**: The rich feature set might present a slightly steeper learning curve for developers new to advanced state management concepts, though the API strives for simplicity.
+*   **Bundle Size**: While comprehensive, it naturally has a larger bundle size compared to minimalist alternatives like Zustand, as it includes a wider range of features out-of-the-box. Tree-shaking is applied, but the rich feature set contributes to the baseline.
+*   **Learning Curve**: The rich feature set and advanced concepts (middleware, transactions, observability) might present a slightly steeper initial learning curve for developers new to advanced state management, though the API strives for simplicity and clear documentation.
+
+### Troubleshooting
+
+*   **Components not re-rendering:**
+    *   Ensure you are using `select` with a specific path (e.g., `select(s => s.user.name)`) instead of the entire state object.
+    *   Verify that the data at the selected path is actually changing (reference equality matters for objects/arrays).
+*   **Persistence not loading/saving:**
+    *   Check if `isReady` is `true` before interacting with state dependent on persistence.
+    *   Ensure your `persistence` instance is correctly passed to `createStore`.
+    *   Check browser developer tools for `localStorage`, `sessionStorage`, or `IndexedDB` to see if data is being stored/retrieved.
+    *   Look for console errors related to persistence.
+*   **Actions not executing or seem delayed:**
+    *   Check the `debounceTime` option in your `createStore` configuration. If set, actions will be delayed.
+    *   If actions are `async`, ensure you `await` them where necessary in your components.
+    *   Use the `watch` function to check if an action is in a loading state.
+*   **Middleware not working:**
+    *   Ensure middleware functions are correctly registered in the `middleware` or `blockingMiddleware` objects in `createStore`.
+    *   Check console logs (if `enableConsoleLogging` is `true`) for `middleware:start`, `middleware:complete`, or `middleware:error` events.
+*   **TypeScript errors:**
+    *   Verify your state interfaces match the `initialState` structure.
+    *   Ensure action return types are `DeepPartial<TState>` as expected.
+    *   Update `@asaidimu/react-store` and `@types/react` to their latest compatible versions.
+
+### FAQ
+
+**Q: Does it support React Server Components (RSC)?**
+A: `useSyncExternalStore` is generally a client-side hook. While the underlying `ReactiveDataStore` is framework-agnostic, the `createStore` hook is designed for client-side React components and is not directly compatible with RSCs for reactive state consumption. You can, however, hydrate the client-side store with initial state from RSCs.
+
+**Q: How do I share state between multiple stores?**
+A: Currently, `@asaidimu/react-store` promotes independent stores. For shared logic or derived state, consider creating a utility function that both stores can call, or a parent component that manages shared data and passes it down. Direct cross-store subscription or merging is not a primary pattern.
+
+**Q: Can I use it without React?**
+A: The core state management (`ReactiveDataStore`, `StoreObservability` from `@asaidimu/utils-store`) is framework-agnostic. The `createStore` function is React-specific, but you can use the underlying `ReactiveDataStore` directly in non-React environments.
+
+**Q: What about immutability?**
+A: All state updates are handled immutably. The library ensures that direct state mutations within actions are prevented and that new state objects are created for changed paths, preserving reference equality for unchanged parts of the state.
+
+**Q: Is there a dev tools extension?**
+A: Currently, there is no dedicated browser extension. However, the built-in `StoreObservability` (`observer` object) and `ActionTracker` provide extensive programmatic debugging capabilities, including event history, state snapshots, and performance metrics, which can be integrated into your application's dev panel. Console logging can also be enabled for quick insights.
 
 ### Changelog
 
@@ -1085,3 +1293,4 @@ This project is licensed under the MIT License. See the [LICENSE.md](./LICENSE.m
 ### Acknowledgments
 
 Developed by [Saidimu](https://github.com/asaidimu).
+This library leverages the robust capabilities of [@asaidimu/utils-store](https://github.com/asaidimu/utils-store) and [@asaidimu/utils-persistence](https://github.com/asaidimu/utils-persistence) for its core state management and persistence features.