@asaidimu/react-store 4.0.0 → 5.1.0

package/README.md

@@ -1,10 +1,11 @@
 # @asaidimu/react-store
 
-[![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)
+[![npm version](https://img.shields.io/npm/v/@asaidimu/react-store.svg?style=flat-square)](https://www.npmjs.com/package/@asaidimu/react-store)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/asaidimu/node-react/ci.yml?branch=main&style=flat-square)](https://github.com/asaidimu/node-react/actions)
+[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
 
-A performant, type-safe state management solution for React with built-in persistence, extensive observability, and a robust middleware system.
+A performant, type-safe state management solution for React with built-in persistence, extensive observability, and a robust middleware and artifact management system.
 
 ⚠️ **Beta Warning**  
 This package is currently in **beta**. The API is subject to rapid changes and should not be considered stable. Breaking changes may occur frequently without notice as we iterate and improve. We’ll update this warning once the package reaches a stable release. Use at your own risk and share feedback or report issues to help us improve!
@@ -20,10 +21,10 @@ This package is currently in **beta**. The API is subject to rapid changes and s
     *   [Using in Components](#using-in-components)
     *   [Handling Deletions](#handling-deletions)
     *   [Persistence](#persistence)
-    *   [Middleware](#middleware)
+    *   [Middleware (Transform & Validate)](#middleware-transform--validate)
+    *   [Artifact Management](#artifact-management)
     *   [Observability](#observability)
     *   [Remote Observability](#remote-observability)
-    *   [Transaction Support](#transaction-support)
     *   [Event System](#event-system)
     *   [Watching Action Loading States](#watching-action-loading-states)
     *   [Advanced Hook Properties](#advanced-hook-properties)
@@ -43,20 +44,20 @@ This package is currently in **beta**. The API is subject to rapid changes and s
 
 ## Overview & Features
 
-`@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.
+`@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 artifact management, 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. The library is built with TypeScript from the ground up, offering strong type safety throughout your application's state and actions.
+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, actions, and resolved artifacts.
 
 ### Key Features
 
 *   📊 **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.
+*   🛡️ **Type-Safe**: Developed entirely in TypeScript, providing strict type checking for state, actions, artifacts, and middleware.
+*   ⚙️ **Middleware Pipeline**: Implement custom logic to `transform` or `validate` state changes before they are applied.
 *   💾 **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 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.
+*   🔍 **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 `StoreObserver` instance.
+*   🚀 **Artifact Management**: Define and reactively resolve asynchronous resources, services, or derived data, enabling advanced dependency injection patterns and lazy loading of complex logic.
+*   ⚡ **Performance Optimized**: Features intelligent selector caching 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 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.
 
@@ -73,7 +74,7 @@ Designed with modern React in mind, it leverages `useSyncExternalStore` for opti
 To add `@asaidimu/react-store` to your project, run one of the following commands:
 
 ```bash
-bun install @asaidimu/react-store
+bun add @asaidimu/react-store
 # or
 npm install @asaidimu/react-store
 # or
@@ -82,7 +83,7 @@ yarn add @asaidimu/react-store
 
 ### Configuration
 
-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.
+No global configuration is required. All options are passed during store creation via the `createStore` function. Configuration includes enabling metrics, persistence, and performance thresholds.
 
 ### Verification
 
@@ -93,35 +94,45 @@ import { createStore } from '@asaidimu/react-store';
 
 interface MyState {
   value: string;
+  count: number;
 }
 
-const myStore = createStore<MyState, any>({
-  state: { value: 'hello' },
+const useMyStore = createStore<MyState, any, any>({
+  state: { value: 'hello', count: 0 },
   actions: {
     setValue: (_, newValue: string) => ({ value: newValue }),
+    increment: ({ state }) => ({ count: state.count + 1 }),
   },
 });
 
-const { select, actions } = myStore(); // Instantiate the hook
+function MyComponent() {
+  const { select, actions } = useMyStore(); // Instantiate the hook
+  const currentValue = select(s => s.value);
+  const currentCount = select(s => s.count);
 
-// Access state
-const currentValue = select(s => s.value);
-console.log(currentValue); // Expected: 'hello'
+  return (
+    <div>
+      <p>Value: {currentValue}</p>
+      <p>Count: {currentCount}</p>
+      <button onClick={() => actions.setValue('world')}>Set Value to 'world'</button>
+      <button onClick={() => actions.increment()}>Increment Count</button>
+    </div>
+  );
+}
 
-// Dispatch an action
-actions.setValue('world');
+// Render MyComponent in your React app.
+// If no errors are thrown during installation or when running this basic example,
+// the package is correctly installed and configured.
 ```
 
-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`. 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.
+Define your application state, actions, and optionally artifacts, then create a store using `createStore`. The `actions` object maps action names to functions that receive an `ActionContext` (containing the current `state` and a `resolve` function for artifacts) and any additional arguments.
 
 ```tsx
-// ui/store.tsx (Example from codebase)
+// ui/store.tsx (Example)
 import { createStore } from '@asaidimu/react-store'; // Assuming direct import or wrapper
 
 export interface Product {
@@ -149,6 +160,8 @@ export interface ECommerceState extends Record<string, any>{
   orders: Order[];
   topSellers: { id: number; name: string; sales: number }[];
   activeUsers: number;
+  // A property to demonstrate artifact dependency
+  currency: string;
 }
 
 const initialState: ECommerceState = {
@@ -169,6 +182,7 @@ const initialState: ECommerceState = {
     { id: 4, name: 'Webcam', sales: 65 },
   ],
   activeUsers: 1428,
+  currency: 'USD',
 };
 
 const actions = {
@@ -212,7 +226,6 @@ const actions = {
       }).sort((a, b) => b.sales - a.sales),
     };
   },
-
   updateStock: ({state}: {state:ECommerceState}) => ({
     products: state.products.map((p:any) => ({
       ...p,
@@ -235,12 +248,40 @@ const actions = {
       orders: [newOrder, ...state.orders],
     };
   },
+  setCurrency: ({state}, newCurrency: string) => ({ currency: newCurrency }),
 };
 
 export const useStore = createStore(
   {
     state: initialState,
     actions,
+    // Example artifact definition
+    artifacts: {
+      currencySymbol: {
+        factory: async ({ use }) => {
+          const currency = await use(({ select }) => select((s: ECommerceState) => s.currency));
+          switch (currency) {
+            case 'USD': return '$';
+            case 'EUR': return '€';
+            case 'GBP': return '£';
+            default: return currency;
+          }
+        },
+      },
+      // Another artifact example, might depend on other artifacts or state
+      exchangeRate: {
+        factory: async ({ resolve, use }) => {
+          const baseCurrency = await use(({ select }) => select((s: ECommerceState) => s.currency));
+          const targetCurrency = 'EUR'; // For demonstration
+          // In a real app, this would fetch from an API
+          await new Promise(r => setTimeout(r, 50)); // Simulate API delay
+          if (baseCurrency === 'USD' && targetCurrency === 'EUR') {
+            return 0.92; // 1 USD = 0.92 EUR
+          }
+          return 1.0;
+        },
+      },
+    }
   },
   { enableMetrics: true } // Enables metrics for observability
 );
@@ -251,16 +292,16 @@ export const useStore = createStore(
 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
-// ui/App.tsx (Excerpt from codebase)
+// ui/App.tsx (Excerpt)
 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
+import { useStore, Product, CartItem, Order, ECommerceState } from './store';
 
-// ... (ShadCN-like UI Components for brevity) ...
 
 const ProductCatalog = () => {
-  const { select, actions } = useStore();
+  const { select, actions, resolve } = useStore();
   const products = select((state) => state.products); // Granular selection
+  const { instance: currencySymbol, ready: currencyReady } = resolve('currencySymbol'); // Reactive artifact resolution
 
   return (
     <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
@@ -272,7 +313,9 @@ const ProductCatalog = () => {
           <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-lg font-semibold text-gray-700">
+                  {currencyReady ? currencySymbol : ''}{product.price.toFixed(2)}
+                </p>
                 <p className="text-sm text-gray-500">{product.stock} in stock</p>
             </div>
           </CardContent>
@@ -286,7 +329,8 @@ const ProductCatalog = () => {
 };
 
 function App() {
-  const { actions } = useStore();
+  const { actions, select } = useStore();
+  const currentCurrency = select((state) => state.currency);
 
   useEffect(() => {
     // Real-time simulations for the dashboard
@@ -299,26 +343,35 @@ function App() {
       clearInterval(usersInterval);
       clearInterval(ordersInterval);
     };
-  }, [actions]); // `actions` object is stable due to `useMemo` in createStore
+  }, [actions]);
 
   return (
     <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">
+            <div className="container mx-auto px-4 h-16 flex items-center justify-between">
                 <h1 className="text-xl font-bold">E-Commerce Dashboard</h1>
+                <select 
+                  value={currentCurrency} 
+                  onChange={(e) => actions.setCurrency(e.target.value)}
+                  className="p-2 border rounded-md"
+                >
+                  <option value="USD">USD</option>
+                  <option value="EUR">EUR</option>
+                  <option value="GBP">GBP</option>
+                </select>
             </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 />
+                    {/* <LiveInventoryChart /> */}
                 </div>
                 <div className="space-y-6">
-                    <ShoppingCart />
-                    <UserAnalytics />
-                    <TopSellingProducts />
-                    <RecentOrdersFeed />
+                    {/* <ShoppingCart /> */}
+                    {/* <UserAnalytics /> */}
+                    {/* <TopSellingProducts /> */}
+                    {/* <RecentOrdersFeed /> */}
                 </div>
             </div>
         </main>
@@ -395,12 +448,16 @@ Persist your store's state across browser sessions or synchronize it across mult
 
 ```tsx
 import { createStore } from '@asaidimu/react-store';
-import { WebStoragePersistence, IndexedDBPersistence } from '@asaidimu/utils-persistence'; 
+import { WebStoragePersistence, IndexedDBPersistence } from '@asaidimu/utils-persistence';
 import React, { useEffect } from 'react';
 
+interface LocalState { sessionCount: number; lastVisited: string; }
+interface SessionState { tabSpecificData: string; }
+interface UserProfileState { userId: string; preferences: { language: string; darkMode: boolean; }; }
+
 // 1. Using WebStoragePersistence (localStorage by default)
 // Data persists even if the browser tab is closed and reopened.
-const localStorePersistence = new WebStoragePersistence('my-app-state-key');
+const localStorePersistence = new WebStoragePersistence<LocalState>('my-app-state-key');
 const useLocalStore = createStore(
   {
     state: { sessionCount: 0, lastVisited: new Date().toISOString() },
@@ -414,12 +471,12 @@ const useLocalStore = createStore(
 
 // 2. Using WebStoragePersistence (sessionStorage)
 // Data only persists for the duration of the browser tab. Clears on tab close.
-const sessionStoragePersistence = new WebStoragePersistence('my-session-state-key', true);
+const sessionStoragePersistence = new WebStoragePersistence<SessionState>('my-session-state-key', true);
 const useSessionStore = createStore(
   {
     state: { tabSpecificData: 'initial' },
     actions: {
-      updateTabSpecificData: (state, newData: string) => ({ tabSpecificData: newData }),
+      updateTabSpecificData: (_, newData: string) => ({ tabSpecificData: newData }),
     },
   },
   { persistence: sessionStoragePersistence },
@@ -427,12 +484,12 @@ const useSessionStore = createStore(
 
 // 3. Using IndexedDBPersistence
 // Ideal for larger amounts of data, offers robust cross-tab synchronization.
-const indexedDBPersistence = new IndexedDBPersistence('user-profile-data');
+const indexedDBPersistence = new IndexedDBPersistence<UserProfileState>('user-profile-data');
 const useUserProfileStore = createStore(
   {
     state: { userId: '', preferences: { language: 'en', darkMode: false } },
     actions: {
-      setUserId: (state, id: string) => ({ userId: id }),
+      setUserId: (_, id: string) => ({ userId: id }),
       toggleDarkMode: ({state}) => ({ preferences: { darkMode: !state.preferences.darkMode } }),
     },
   },
@@ -442,9 +499,13 @@ const useUserProfileStore = createStore(
 function AppWithPersistence() {
   const { select: selectLocal, actions: actionsLocal, isReady: localReady } = useLocalStore();
   const { select: selectProfile, actions: actionsProfile, isReady: profileReady } = useUserProfileStore();
+  const { select: selectSession, actions: actionsSession } = useSessionStore();
+
 
   const sessionCount = selectLocal(s => s.sessionCount);
   const darkMode = selectProfile(s => s.preferences.darkMode);
+  const tabData = selectSession(s => s.tabSpecificData);
+
 
   useEffect(() => {
     if (localReady) {
@@ -454,7 +515,7 @@ function AppWithPersistence() {
     if (profileReady && !selectProfile(s => s.userId)) {
       actionsProfile.setUserId('user-' + Math.random().toString(36).substring(2, 9));
     }
-  }, [localReady, profileReady, actionsLocal, actionsProfile, selectProfile]); // Added dependencies for useEffect
+  }, [localReady, profileReady, actionsLocal, actionsProfile, selectProfile]);
 
   if (!localReady || !profileReady) {
     return <div>Loading persisted data...</div>;
@@ -462,9 +523,15 @@ function AppWithPersistence() {
 
   return (
     <div>
-      <h3>Local Store</h3>
+      <h3>Local Store (localStorage)</h3>
       <p>Session Count: {sessionCount}</p>
       
+      <h3>Session Store (sessionStorage)</h3>
+      <p>Tab Specific Data: {tabData}</p>
+      <button onClick={() => actionsSession.updateTabSpecificData('updated-for-this-tab')}>
+        Update Tab Data
+      </button>
+
       <h3>User Profile Store (IndexedDB)</h3>
       <p>Dark Mode: {darkMode ? 'Enabled' : 'Disabled'}</p>
       <button onClick={() => actionsProfile.toggleDarkMode()}>Toggle Dark Mode</button>
@@ -473,12 +540,15 @@ function AppWithPersistence() {
 }
 ```
 
-### Middleware
+### Middleware (Transform & Validate)
+
+Middleware functions can intercept and modify or block state updates. The `CHANGELOG.md` indicates a breaking change, moving from generic `middleware` and `blockingMiddleware` to `transform` and `validate` properties in the `StoreDefinition`. These now receive an `ActionContext` with `state` and `resolve` capabilities.
 
-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.
+*   `transform`: Functions that run *after* an action's core logic but *before* the state update is committed. They can modify the `DeepPartial<TState>` that will be merged into the state.
+*   `validate`: Functions that run *before* the state update is committed. If a validator returns `false` (or a `Promise<false>`), the state update is entirely cancelled.
 
 ```typescript
-import { createStore, type Middleware, type BlockingMiddleware } from '@asaidimu/react-store';
+import { createStore } from '@asaidimu/react-store';
 import React from 'react';
 
 interface CartState {
@@ -486,28 +556,7 @@ interface CartState {
   total: number;
 }
 
-const calculateTotalMiddleware: Middleware<CartState> = (state, update) => {
-  if (update.items) {
-    const newItems = update.items as CartState['items'];
-    const newTotal = newItems.reduce((sum, item) => sum + (item.quantity * item.price), 0);
-    return { ...update, total: newTotal };
-  }
-  return update;
-};
-
-const validateItemMiddleware: BlockingMiddleware<CartState> = (state, update) => {
-  if (update.items) {
-    for (const item of update.items as CartState['items']) {
-      if (item.quantity < 0) {
-        console.warn('Blocked: Item quantity cannot be negative.');
-        return false; // Blocks the update
-      }
-    }
-  }
-  return true; // Allows the update
-};
-
-const useCartStore = createStore({
+const useCartStore = createStore<CartState, any, any>({ // TArtifactsMap and TActions are inferred
   state: { items: [], total: 0 },
   actions: {
     addItem: ({state}, item: { id: string; name: string; price: number }) => {
@@ -527,9 +576,31 @@ const useCartStore = createStore({
       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 },
+  transform: {
+    // Calculates total based on updated items before state merge
+    calculateTotal: async ({ state, resolve }, update) => {
+      if (update.items) {
+        const newItems = update.items as CartState['items'];
+        const newTotal = newItems.reduce((sum, item) => sum + (item.quantity * item.price), 0);
+        return { ...update, total: newTotal };
+      }
+      return update;
+    },
+  },
+  validate: {
+    // Blocks update if any item quantity is negative
+    validateItemQuantity: async ({ state, resolve }, update) => {
+      if (update.items) {
+        for (const item of update.items as CartState['items']) {
+          if (item.quantity < 0) {
+            console.warn('Blocked by validator: Item quantity cannot be negative.');
+            return false; // Blocks the update
+          }
+        }
+      }
+      return true; // Allows the update
+    },
+  },
 });
 
 function CartComponent() {
@@ -557,6 +628,124 @@ function CartComponent() {
 }
 ```
 
+### Artifact Management
+
+The store supports defining and reactively resolving "artifacts," which can be any asynchronous resource, service, or derived value. Artifacts are defined in the `artifacts` property of the `StoreDefinition` and resolved using `ctx.resolve()` within actions or the `resolve()` hook in components. They can depend on other artifacts or on the store's reactive state.
+
+```tsx
+import { createStore } from '@asaidimu/react-store';
+import { ArtifactScopes } from '@asaidimu/utils-artifacts';
+import React, { useEffect } from 'react';
+
+interface AppState {
+  userId: string | null;
+  settingsLoaded: boolean;
+  theme: string;
+}
+
+// Assume this is an API service or similar
+const mockApiService = {
+  fetchUserSettings: async (userId: string) => {
+    await new Promise(r => setTimeout(r, 200)); // Simulate API delay
+    if (userId === 'user-123') {
+      return { theme: 'dark', notifications: true };
+    }
+    return { theme: 'light', notifications: false };
+  },
+};
+
+const useArtifactStore = createStore<AppState, any, any>({
+  state: { userId: null, settingsLoaded: false, theme: 'light' },
+  actions: {
+    setUserId: (_, id: string) => ({ userId: id, settingsLoaded: false }),
+    loadUserSettings: async ({ state, resolve }) => {
+      if (!state.userId) return;
+      
+      const { instance: userSettings } = await resolve('userSettings');
+      if (userSettings) {
+        return {
+          settingsLoaded: true,
+          theme: userSettings.theme,
+        };
+      }
+      return {};
+    },
+    toggleTheme: ({state}) => ({ theme: state.theme === 'light' ? 'dark' : 'light' }),
+  },
+  artifacts: {
+    // A singleton artifact that fetches user settings based on the current userId in state
+    userSettings: {
+      scope: ArtifactScopes.Singleton, // Ensure only one instance is created globally
+      factory: async ({ use }) => {
+        const userId = await use(({ select }) => select((s: AppState) => s.userId));
+        if (userId) {
+          console.log(`Fetching settings for user: ${userId}`);
+          return mockApiService.fetchUserSettings(userId);
+        }
+        return null;
+      },
+      lazy: true, // Only create/resolve when first requested
+    },
+    // An artifact that provides a simple logger instance
+    logger: {
+      factory: async () => console,
+      scope: ArtifactScopes.Singleton,
+    },
+  },
+});
+
+function ArtifactConsumer() {
+  const { actions, select, resolve, isReady } = useArtifactStore();
+  const userId = select(s => s.userId);
+  const theme = select(s => s.theme);
+  const settingsLoaded = select(s => s.settingsLoaded);
+
+  // Reactively resolve the userSettings artifact in the component
+  const { instance: userSettingsArtifact, ready: userSettingsReady } = resolve('userSettings');
+  const { instance: logger } = resolve('logger');
+
+  useEffect(() => {
+    // Simulate setting a user ID after initial load
+    if (isReady && !userId) {
+      actions.setUserId('user-123');
+    }
+  }, [isReady, userId, actions]);
+
+  useEffect(() => {
+    // Automatically load settings when userId is available and settings not loaded
+    if (userId && !settingsLoaded) {
+      actions.loadUserSettings();
+    }
+  }, [userId, settingsLoaded, actions]);
+
+  useEffect(() => {
+    if (logger && userSettingsArtifact) {
+      logger.log("User settings artifact updated:", userSettingsArtifact);
+    }
+  }, [logger, userSettingsArtifact]);
+
+  if (!isReady) {
+    return <div>Loading store...</div>;
+  }
+
+  return (
+    <div>
+      <h2>Artifact Management Example</h2>
+      <p>Current User ID: {userId || 'Not set'}</p>
+      <p>Settings Loaded: {settingsLoaded ? 'Yes' : 'No'}</p>
+      <p>Current Theme: {theme}</p>
+      {userSettingsReady && userSettingsArtifact && (
+        <p>Artifact (userSettings) Resolved Theme: {userSettingsArtifact.theme}</p>
+      )}
+      <button onClick={() => actions.setUserId(userId === 'user-123' ? 'user-456' : 'user-123')}>
+        Toggle User ID
+      </button>
+      <button onClick={() => actions.toggleTheme()}>Toggle App Theme</button>
+    </div>
+  );
+}
+```
+
 ### Observability
 
 Enable metrics and debugging via the `observer` and `actionTracker` objects. The `enableMetrics` option in `createStore` is crucial for activating these features.
@@ -567,10 +756,15 @@ import React from 'react';
 
 const useObservedStore = createStore(
   {
-    state: { task: '', completed: false },
+    state: { task: '', completed: false, count: 0 },
     actions: {
-      addTask: (state, taskName: string) => ({ task: taskName, completed: false }),
-      completeTask: (state) => ({ completed: true }),
+      addTask: (_, taskName: string) => ({ task: taskName, completed: false }),
+      completeTask: (_) => ({ completed: true }),
+      increment: ({state}) => ({ count: state.count + 1 }),
+      longRunningAction: async () => {
+        await new Promise(resolve => setTimeout(resolve, 500)); // Simulate async work
+        return { count: 100 };
+      },
     },
   },
   {
@@ -588,7 +782,8 @@ const useObservedStore = createStore(
 );
 
 function DebugPanel() {
-  const { actions, observer, actionTracker } = useObservedStore();
+  const { actions, observer, actionTracker, select, state: getStateSnapshot } = useObservedStore();
+  const count = select(s => s.count);
 
   // Access performance metrics
   const metrics = observer?.getPerformanceMetrics();
@@ -610,9 +805,12 @@ function DebugPanel() {
           <p>Largest Update Size (paths): {metrics?.largestUpdateSize}</p>
 
           <h3>Time Travel</h3>
+          <p>Current Count: {count} (via select)</p>
           <button onClick={() => timeTravel?.undo()} disabled={!timeTravel?.canUndo()}>Undo</button>
           <button onClick={() => timeTravel?.redo()} disabled={!timeTravel?.canRedo()}>Redo</button>
           <p>State History: {timeTravel?.getHistoryLength()}</p>
+          <p>Current Snapshot (non-reactive): {JSON.stringify(getStateSnapshot())}</p>
+
 
           <h3>Action History</h3>
           <ul>
@@ -626,6 +824,8 @@ function DebugPanel() {
       )}
       <button onClick={() => actions.addTask('Learn React Store')}>Add Task</button>
       <button onClick={() => actions.completeTask()}>Complete Task</button>
+      <button onClick={() => actions.increment()}>Increment</button>
+      <button onClick={() => actions.longRunningAction()}>Long Action</button>
     </div>
   );
 }
@@ -637,7 +837,8 @@ Send collected metrics and traces to external systems like OpenTelemetry, Promet
 
 ```tsx
 import { createStore } from '@asaidimu/react-store';
-import { useRemoteObservability } from '@asaidimu/utils-store';
+// Assuming useRemoteObservability is provided by @asaidimu/utils-store or a wrapper
+// import { useRemoteObservability } from '@asaidimu/utils-store';
 import React, { useEffect } from 'react';
 
 const useRemoteStore = createStore(
@@ -650,64 +851,48 @@ const useRemoteStore = createStore(
         }
         return { apiCallsMade: state.apiCallsMade + 1, lastApiError: null };
       },
-      handleApiError: ({state}, error: string) => ({ lastApiError: error })
+      handleApiError: (_, error: string) => ({ lastApiError: error })
     },
   },
   {
     enableMetrics: true, // Required for RemoteObservability
     enableConsoleLogging: false,
-    // 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
-  });
+  
+  // Placeholder for actual useRemoteObservability hook
+  // 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(() => {
-    // Add OpenTelemetry Collector as a destination
-    addOpenTelemetryDestination({
-      endpoint: 'http://localhost:4318', // Default OpenTelemetry HTTP endpoint
-      apiKey: 'your-otel-api-key',
-      resource: { 'app.version': '1.0.0', 'host.name': 'frontend-server' }
-    });
-
-    // Add Prometheus Pushgateway as a destination
-    addPrometheusDestination({
-      pushgatewayUrl: 'http://localhost:9091', // Default Prometheus Pushgateway
-      jobName: 'react-store-metrics',
-      username: 'promuser', // Optional basic auth
-      password: 'prompassword',
-    });
+    // In a real implementation, you would use the `remote` object
+    // to add destinations and configure reporting.
+    // Example:
+    // addOpenTelemetryDestination({ endpoint: 'http://localhost:4318', apiKey: 'your-otel-api-key' });
+    // addPrometheusDestination({ pushgatewayUrl: 'http://localhost:9091', jobName: 'react-store-metrics' });
+    // addGrafanaCloudDestination({ url: 'https://loki-prod-us-central1.grafana.net', apiKey: 'your-grafana-cloud-api-key' });
 
-    // Add Grafana Cloud Loki as a destination (for logs/traces)
-    addGrafanaCloudDestination({
-      url: 'https://loki-prod-us-central1.grafana.net', // Example Loki endpoint
-      apiKey: 'your-grafana-cloud-api-key',
-    });
-
-    // Report current store metrics periodically (in addition to event-driven metrics)
     const interval = setInterval(() => {
-      observer?.reportCurrentMetrics();
+      observer?.reportCurrentMetrics(); // Manually trigger a report if needed
     }, 5000); // Report every 5 seconds
 
     return () => clearInterval(interval);
-  }, [observer, addOpenTelemetryDestination, addPrometheusDestination, addGrafanaCloudDestination]); // Added dependencies
+  }, [observer]); // Removed placeholder dependencies for actual usage
 
   return null; // This component doesn't render anything visually
 }
@@ -725,85 +910,6 @@ function MonitoringIntegration() {
 // }
 ```
 
-### 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, maintaining state consistency.
-
-```typescript
-import { createStore } from '@asaidimu/react-store';
-import React from 'react';
-
-interface BankState {
-  checking: number;
-  savings: number;
-  transactions: string[];
-}
-
-const useBankStore = createStore<BankState, any>({
-  state: { checking: 1000, savings: 500, transactions: [] },
-  actions: {
-    transferFunds: async ({state}, fromAccount: 'checking' | 'savings', toAccount: 'checking' | 'savings', amount: number) => {
-      if (amount <= 0) {
-        throw new Error('Transfer amount must be positive.');
-      }
-
-      const newChecking = fromAccount === 'checking' ? state.checking - amount : state.checking + amount;
-      const newSavings = fromAccount === 'savings' ? state.savings - amount : state.savings + amount;
-
-      if ((fromAccount === 'checking' && newChecking < 0) || (fromAccount === 'savings' && newSavings < 0)) {
-        throw new Error('Insufficient funds.');
-      }
-
-      // Simulate a complex operation that might fail
-      if (amount > 700 && fromAccount === 'checking') {
-        throw new Error('Large transfers from checking require additional verification.');
-      }
-
-      const newTransactions = [...state.transactions, `Transfer ${amount} from ${fromAccount} to ${toAccount}`];
-      return {
-        checking: newChecking,
-        savings: newSavings,
-        transactions: newTransactions,
-      };
-    },
-  },
-});
-
-function BankApp() {
-  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 {
-      // 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)}`);
-      // State is automatically rolled back if an error occurs within the transaction
-    }
-  };
-
-  return (
-    <div>
-      <h2>Bank Accounts</h2>
-      <p>Checking: ${checkingBalance.toFixed(2)}</p>
-      <p>Savings: ${savingsBalance.toFixed(2)}</p>
-      <h3>Recent Transactions</h3>
-      <ul>
-        {transactions.map((t, i) => <li key={i}>{t}</li>)}
-      </ul>
-      <button onClick={() => handleTransfer('checking', 'savings', 100)}>Transfer $100 (Checking to Savings)</button>
-      <button onClick={() => handleTransfer('savings', 'checking', 200)}>Transfer $200 (Savings to Checking)</button>
-      <button onClick={() => handleTransfer('checking', 'savings', 800)}>Transfer $800 (Will Fail)</button>
-      <button onClick={() => handleTransfer('checking', 'savings', 1500)}>Transfer $1500 (Insufficient Funds)</button>
-    </div>
-  );
-}
-```
-
 ### Event System
 
 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()`.
@@ -819,8 +925,8 @@ const useEventStore = createStore(
       processData: ({state}, newData: string) => ({ data: newData, processedCount: state.processedCount + 1 }),
       triggerError: () => { throw new Error("Action failed intentionally"); }
     },
-    middleware: {
-      myLoggingMiddleware: (state, update) => {
+    transform: { // Using the new middleware API
+      myLoggingMiddleware: async ({state}, update) => {
         console.log('Middleware processing:', update);
         return update;
       }
@@ -913,7 +1019,7 @@ interface DataState {
 const useDataStore = createStore({
   state: { items: [] },
   actions: {
-    fetchItems: async (state) => {
+    fetchItems: async ({state}) => {
       // Simulate an API call
       await new Promise(resolve => setTimeout(resolve, 2000));
       return { items: ['Item A', 'Item B', 'Item C'] };
@@ -960,7 +1066,7 @@ 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
+import { useStore as useMyStore } from './store'; // Assuming this is your store definition
 
 function MyAdvancedComponent() {
   const {
@@ -968,11 +1074,11 @@ function MyAdvancedComponent() {
     actions,       // Object containing your defined actions (debounced, promise-returning)
     isReady,       // Boolean indicating if persistence is ready
     store,         // Direct access to the ReactiveDataStore instance (from @asaidimu/utils-store)
-    observer,      // StoreObservability instance (from @asaidimu/utils-store, if `enableMetrics` was true)
+    observer,      // StoreObserver 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)
+    resolve,       // Function to reactively 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)
@@ -991,14 +1097,14 @@ function MyAdvancedComponent() {
   }
 
   // Example: Watching a specific action's loading state
-  const isLoadingSomeAction = watch('checkout'); // Assuming 'checkout' is an action
+  const isLoadingSomeAction = watch('checkout'); // Assuming 'checkout' is an action from the example store
   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);
-  // }
+  // Example: Resolving an artifact (from the example store)
+  const { instance: currencySymbol, ready: isCurrencySymbolReady } = resolve('currencySymbol');
+  if (isCurrencySymbolReady) {
+    console.log("Currency Symbol artifact is ready:", currencySymbol);
+  }
 
   return (
     <div>
@@ -1017,53 +1123,50 @@ function MyAdvancedComponent() {
 
 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            # 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
-```
+*   `src/execution.ts`: Defines `ActionExecution` and `ActionTracker` classes for monitoring and maintaining a history of action dispatches, including their status and performance metrics.
+*   `src/store.ts`: Contains the main `createStore` factory function. This module orchestrates the initialization of the core `ReactiveDataStore`, `StoreObserver`, `ActionTracker`, and `ArtifactContainer`. It also binds actions, applies middleware (`transform`, `validate`), and sets up the React hook using `useSyncExternalStore` for efficient component updates.
+*   `src/types.ts`: Defines all core TypeScript interfaces and types for the store's public API, including `ActionContext`, `StoreDefinition`, `StoreHook`, middleware signatures (`Transformer`, `Validator`), and artifact-related types.
 
 ### Key External Dependencies
 
 This library leverages the following `@asaidimu` packages for its core functionalities:
 
-*   **`@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-store`**: Provides the foundational `ReactiveDataStore` for immutable state management, transactions, core event emission, and the `StoreObserver` 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.
+*   **`@asaidimu/utils-artifacts`**: Provides the `ArtifactContainer` and related types for defining and resolving asynchronous, reactive dependencies (artifacts) within the store.
 
 ### Core Components
 
 *   **`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.
+*   **`StoreObserver` (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.
+*   **`ArtifactContainer` (from `@asaidimu/utils-artifacts`)**: Manages the registration and resolution of artifacts. It handles dependencies between artifacts and reacts to state changes for artifacts that depend on store state.
+*   **`createStore` Hook (`src/store.ts`)**: The primary React-facing API. It instantiates `ReactiveDataStore`, `StoreObserver`, `ActionTracker`, and `ArtifactContainer`. It wraps user-defined actions with debouncing and tracking, and provides the `select` function (powered by `useSyncExternalStore` for efficient component updates), the `watch` function for action loading states, and the `resolve` function for artifacts.
+*   **Persistence Adapters (from `@asaidimu/utils-persistence`)**: Implement the `SimplePersistence` 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 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`.
+3.  **Action Loading State Update**: The store immediately updates the loading state for the dispatched action to `true` via an internal `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.
+5.  **State Update Request**: The action's implementation (receiving `ActionContext` with `state` and `resolve`) 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.
+7.  **Validator Middleware**: The update first passes through any registered `validate` middleware. If any validator returns `false` or throws an error, the update is halted, and the state remains unchanged (and rolled back if in a transaction).
+8.  **Transformer Middleware**: If not blocked, the update then passes through `transform` 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.
+11. **Persistence**: If changes occurred, the new state is saved via the configured `SimplePersistence` adapter (e.g., `localStorage`, `IndexedDB`). The system also subscribes to external changes from persistence for cross-tab synchronization.
+12. **Artifact Re-evaluation**: If state changes affect an artifact that depends on that part of the state, `ArtifactContainer` may re-evaluate and re-resolve that artifact.
+13. **Listener Notification**: `React.useSyncExternalStore` subscribers (used by `select` and `resolve`) whose selected paths or resolved artifacts have changed are notified, triggering efficient re-renders of only the relevant components.
+14. **Action Loading State Reset**: Once the action completes (either successfully or with an error), the loading state for that action is reset to `false`.
+15. **Observability Events**: Throughout this entire flow, `ReactiveDataStore` emits fine-grained events (`update:start`, `middleware:complete`, `transaction:error`, etc.) which `StoreObserver` captures for debugging, metrics collection, and remote reporting.
 
 ### Extension Points
 
-*   **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).
+*   **Custom Middleware**: Easily add your own `Transformer` or `Validator` functions for custom logic (e.g., advanced logging, analytics, data transformation, or complex validation logic).
+*   **Custom Persistence Adapters**: Implement the `SimplePersistence<T>` interface (from `@asaidimu/utils-persistence`) to integrate with any storage solution (e.g., a backend API, WebSockets, or a custom in-memory store).
+*   **Custom Artifact Factories**: Define factories for any external service, resource, or complex derived state, allowing for clear separation of concerns and reactive dependency injection.
 *   **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
@@ -1089,7 +1192,7 @@ We welcome contributions! Please follow the guidelines below.
 *   `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 prebuild`: Pre-build step that cleans the `dist` directory and runs an internal package synchronization script (`.sync-package.ts`).
 *   `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.
@@ -1127,9 +1230,10 @@ For bugs, feature requests, or questions, please open an issue on the [GitHub Is
 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, 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.
+4.  **Middleware**: Leverage `transform` and `validate` for cross-cutting concerns like logging, analytics, data transformation, or complex validation logic that applies to multiple actions. They now receive `ActionContext`, allowing for advanced logic including artifact resolution.
 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.
+7.  **Artifacts**: Use artifacts to manage external dependencies, services, or complex derived values that might change over time or have their own lifecycle. This promotes better separation of concerns and testability.
 
 ### API Reference
 
@@ -1141,18 +1245,18 @@ The main entry point for creating a store hook.
 // From src/types.ts
 export interface StoreDefinition<
     TState extends object,
-    TArtifactsMap extends ArtifactsMap<TState>, // Artifacts can be defined but not shown in this example
+    TArtifactsMap extends ArtifactsMap<TState>,
     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
+    transform?: Record<string, Transformer<TState, TArtifactsMap>>; // Optional transforming middleware
+    validate?: Record<string, Validator<TState, TArtifactsMap>>; // Optional blocking middleware
 }
 
 interface StoreOptions<T> extends ObserverOptions { // ObserverOptions from @asaidimu/utils-store
-    enableMetrics?: boolean; // Enable StoreObservability and ActionTracker features (default: false)
+    enableMetrics?: boolean; // Enable StoreObserver 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
@@ -1164,28 +1268,27 @@ const useStoreHook = createStore(definition, options);
 **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.
+*   `observer`: The `StoreObserver` 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 `(<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.
+*   `resolve`: A reactive artifact resolver `(<K extends keyof TArtifactsMap>(key: K) => ResolvedArtifact<ArtifactValue<TArtifactsMap[K]>>)`. If `artifacts` are defined in the store, this hook returns `ResolvedArtifact` (containing `instance` and `ready` status) for a specific artifact, reactively updating if the artifact instance changes or becomes ready.
 
 #### `ReactiveDataStore` (accessed via `useStoreHook().store` from `@asaidimu/utils-store`)
 
 *   `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.
+*   `watch(path: string | string[], callback: (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.
+*   `use(middleware: StoreMiddleware<TState>): string`: Adds a transforming middleware. Returns its ID. (Note: The `createStore` API uses `transform` and `validate` which internally map to `ReactiveDataStore.use`).
 *   `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'`, `'transaction:start'`).
 
-#### `StoreObservability` (accessed via `useStoreHook().observer` from `@asaidimu/utils-store`)
+#### `StoreObserver` (accessed via `useStoreHook().observer` from `@asaidimu/utils-store`)
 
 Available only if `enableMetrics` is `true` in `createStore` options.
 
@@ -1194,8 +1297,6 @@ Available only if `enableMetrics` is `true` in `createStore` options.
 *   `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<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.
 
@@ -1224,10 +1325,10 @@ All adapters implement `SimplePersistence<T>`:
 | **Feature**            | **@asaidimu/react-store** | **Redux**          | **Zustand**        | **MobX**           | **Recoil**         |
 | :--------------------- | :------------------------ | :----------------- | :----------------- | :----------------- | :----------------- |
 | **Dev Experience**     | Intuitive hook-based API with rich tooling. | Verbose setup with reducers and middleware. | Minimalist, hook-friendly API. | Reactive, class-based approach. | Atom-based, React-native feel. |
-| **Learning Curve**     | Moderate (middleware, observability add complexity). | Steep (boilerplate-heavy). | Low (simple API). | Moderate (reactive concepts). | Low to moderate (atom model). |
+| **Learning Curve**     | Moderate (artifacts, middleware, observability add complexity). | Steep (boilerplate-heavy). | Low (simple API). | Moderate (reactive concepts). | Low to moderate (atom model). |
 | **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). |
+| **Scalability**        | High (transactions, persistence, remote metrics, artifacts). | High (structured but verbose). | High (small but flexible). | High (reactive scaling). | High (granular atoms). |
+| **Extensibility**      | Excellent (middleware, custom persistence, observability, artifacts). | Good (middleware, enhancers). | Good (middleware-like). | Moderate (custom reactions). | Moderate (custom selectors). |
 | **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). |
@@ -1235,13 +1336,13 @@ All adapters implement `SimplePersistence<T>`:
 | **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 and their integration complexities.
+*   **All-in-One**: It aims to be a single solution for state management, persistence, observability, and artifact management, 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. 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.
+*   **Learning Curve**: The rich feature set and advanced concepts (middleware, transactions, observability, artifacts) 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
 
@@ -1257,12 +1358,18 @@ All adapters implement `SimplePersistence<T>`:
     *   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`.
+*   **Middleware (transform/validate) not working:**
+    *   Ensure `transform` and `validate` functions are correctly registered in the `createStore` definition.
     *   Check console logs (if `enableConsoleLogging` is `true`) for `middleware:start`, `middleware:complete`, or `middleware:error` events.
+    *   Verify the middleware signature matches the `Transformer` or `Validator` types, especially the `ActionContext` parameter.
+*   **Artifacts not resolving or updating:**
+    *   Check the `ready` property returned by the `resolve` hook. Artifacts are often asynchronous.
+    *   Ensure that any dependencies an artifact has (e.g., other artifacts, state values) are stable or correctly configured for reactivity.
+    *   Verify the `factory` function for your artifact is correctly defined and returns the expected value.
 *   **TypeScript errors:**
     *   Verify your state interfaces match the `initialState` structure.
     *   Ensure action return types are `DeepPartial<TState>` as expected.
+    *   Make sure `transform` and `validate` functions adhere to their new `ActionContext` signature.
     *   Update `@asaidimu/react-store` and `@types/react` to their latest compatible versions.
 
 ### FAQ
@@ -1271,16 +1378,16 @@ All adapters implement `SimplePersistence<T>`:
 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.
+A: Currently, `@asaidimu/react-store` promotes independent stores. For shared logic or derived state, consider creating an artifact that both stores can resolve, or 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.
+A: The core state management (`ReactiveDataStore`, `StoreObserver` 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.
+A: Currently, there is no dedicated browser extension. However, the built-in `StoreObserver` (`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
 
@@ -1293,4 +1400,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.
+This library leverages the robust capabilities of [@asaidimu/utils-store](https://github.com/asaidimu/utils-store), [@asaidimu/utils-persistence](https://github.com/asaidimu/utils-persistence), and [@asaidimu/utils-artifacts](https://github.com/asaidimu/utils-artifacts) for its core state management, persistence, and artifact management features.