@asaidimu/utils-artifacts 1.0.0 → 2.0.1

package/README.md

@@ -1,4 +1,4 @@
-# @asaidimu/utils-artifacts
+# `@asaidimu/utils-artifacts`
 
 A powerful, reactive dependency injection container for managing application artifacts and their lifecycles. It provides a robust framework for building modular, maintainable, and highly responsive applications by decoupling components and managing their state-driven dependencies.
 
@@ -16,8 +16,7 @@ A powerful, reactive dependency injection container for managing application art
     *   [Artifact-to-Artifact Dependencies](#artifact-to-artifact-dependencies)
     *   [Lifecycle Hooks: `onCleanup` & `onDispose`](#lifecycle-hooks-oncleanup--ondispose)
     *   [Watching Artifacts for Changes](#watching-artifacts-for-changes)
-    *   [Yielding Intermediate Values](#yielding-intermediate-values)
-    *   [Hierarchical Containers](#hierarchical-containers)
+    *   [Updating Intermediate Values with `ctx.update`](#updating-intermediate-values-with-ctxupdate)
     *   [Debugging Information](#debugging-information)
 *   [Project Architecture](#-project-architecture)
 *   [Development & Contributing](#-development--contributing)
@@ -25,7 +24,7 @@ A powerful, reactive dependency injection container for managing application art
 
 ---
 
-⚠️ **Beta Warning**  
+⚠️ **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!
 
 ## 📚 Overview & Features
@@ -38,15 +37,14 @@ This package is ideal for building complex, event-driven systems, front-end appl
 
 *   **Reactive Dependency Injection**: Automatically invalidates and rebuilds artifacts when their declared dependencies (other artifacts or global state slices) change.
 *   **Singleton & Transient Scopes**: Control whether an artifact is instantiated once and reused (`Singleton`) or created fresh on every request (`Transient`).
-*   **Hierarchical Containers**: Create child containers that can inherit and resolve artifacts from their parents, enabling scoped dependency trees.
 *   **State-Driven Invalidation with Debouncing**: Integrates with a `DataStore` to track state dependencies, triggering artifact rebuilds only when relevant state paths change, with configurable debouncing.
 *   **Fine-grained Dependency Tracking**: Explicitly declare dependencies on other artifacts using `ctx.resolve()` and on state slices using `ctx.select()`.
 *   **Robust Error Handling**: Built-in detection and specific error types for circular dependencies, missing artifacts, and illegal operations, distinguishing between `system` (structural) and `external` (runtime) errors.
 *   **Lifecycle Hooks**: Register `onCleanup` callbacks for instance-specific resource release and `onDispose` for final resource teardown.
 *   **Asynchronous Artifact Resolution**: Supports `async`/`await` in artifact factories, with configurable retries for external failures and timeouts.
-*   **`ArtifactWatcher` for Reactive Observation**: Observe changes to an artifact's resolved value over time, subscribing to updates without repeatedly resolving.
-*   **Live Updates via `yield()`**: Singleton artifacts can proactively update their value from within their factory, immediately notifying dependents and watchers.
-*   **Comprehensive Debugging Info**: `getDebugInfo()` provides a snapshot of the container's state, including artifact statuses, dependencies, and dependents.
+*   **`ArtifactObserver` for Reactive Observation**: Observe changes to an artifact's resolved value over time, subscribing to updates without repeatedly resolving.
+*   **Live Updates via `ctx.update()`**: Singleton artifacts can proactively update their value from within their factory, immediately notifying dependents and watchers.
+*   **Comprehensive Debugging Info**: `debugInfo()` provides a snapshot of the container's state, including artifact statuses, dependencies, and dependents.
 
 ---
 
@@ -80,7 +78,7 @@ To use the `ArtifactContainer`, you need to initialize it with an object that pr
 If you're using `@asaidimu/utils-store` as your `DataStore`:
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store'; // Assuming this provides DataStore interface
 
 interface AppState {
@@ -111,8 +109,8 @@ You can verify the installation by trying to import and instantiate the `Artifac
 import { ArtifactContainer } from '@asaidimu/utils-artifacts';
 // Assuming a mock or real DataStore is available
 const mockStore = {
-  get: () => ({}),
-  watch: () => () => {},
+  get: () => ({}), // Returns an empty object for state
+  watch: () => () => {}, // Returns a no-op unsubscribe function
 };
 const container = new ArtifactContainer(mockStore);
 console.log('ArtifactContainer initialized successfully!');
@@ -132,7 +130,7 @@ Artifacts can be registered with different scopes, controlling their lifecycle.
 A singleton artifact is created only once. Subsequent `resolve` calls return the same instance.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 const store = new ReactiveDataStore({});
@@ -150,7 +148,7 @@ container.register({
       version: '1.0.0'
     };
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
   lazy: false, // Build immediately on registration
 });
 
@@ -179,7 +177,7 @@ runSingletonExample();
 A transient artifact creates a new instance every time it is resolved.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 const store = new ReactiveDataStore({});
@@ -194,7 +192,7 @@ container.register({
       timestamp: Date.now()
     };
   },
-  scope: ArtifactScope.Transient,
+  scope: ArtifactScopes.Transient,
 });
 
 async function runTransientExample() {
@@ -222,7 +220,7 @@ runTransientExample();
 Artifacts can react to changes in your global `DataStore` state by using `ctx.select()` within their factory's `use` block.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 interface AppState {
@@ -247,7 +245,7 @@ container.register({
     console.log(`UI Config Build ${uiComponentBuilds}: Theme=${theme}, Notifications=${notifications}`);
     return { theme, notifications };
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
 async function runReactiveStateExample() {
@@ -271,7 +269,7 @@ async function runReactiveStateExample() {
 
   // Resolve again
   uiConfig = await container.resolve('uiConfiguration');
-  console.assert(uiConfig.instance?.notificationsEnabled === false, 'Notifications should be false');
+  console.assert(uiConfig.instance?.notifications === false, 'Notifications should be false');
   console.assert(uiComponentBuilds === 3, 'Build count should increment after another state change');
 
   // Output:
@@ -292,7 +290,7 @@ runReactiveStateExample();
 Artifacts can depend on other artifacts using `ctx.resolve()` within their factory's `use` block. Changes to a dependency will invalidate the dependent artifact.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 const store = new ReactiveDataStore({});
@@ -307,7 +305,7 @@ container.register({
     await new Promise(res => setTimeout(res, 50)); // Simulate async work
     return { client: 'PostgreSQL', status: 'connected' };
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
 let userRepositoryBuilds = 0;
@@ -322,7 +320,7 @@ container.register({
       findUser: (id: string) => `User ${id} from ${db.instance?.client}`
     };
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
 async function runArtifactDependencyExample() {
@@ -365,7 +363,7 @@ Artifacts can register cleanup functions to manage resources.
 *   `onDispose`: Executed *only* when the artifact is unregistered or the container itself is disposed. Ideal for final, permanent resource release.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 const store = new ReactiveDataStore({});
@@ -380,7 +378,7 @@ container.register({
     let count = 0;
     currentInterval = setInterval(() => {
       count++;
-      console.log(`Tick: ${count}`);
+      // console.log(`Tick: ${count}`); // Uncomment to see live ticks
     }, 1000);
 
     onCleanup(() => {
@@ -395,14 +393,14 @@ container.register({
 
     return { start: Date.now() };
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
   lazy: false, // Eagerly build
 });
 
 async function runLifecycleHooksExample() {
   await container.resolve('ticker');
-  console.log('Ticker running for 3 seconds...');
-  await new Promise(res => setTimeout(res, 3000));
+  console.log('Ticker running for 2 seconds...');
+  await new Promise(res => setTimeout(res, 2000));
 
   console.log('\n--- Invalidating Ticker (will trigger onCleanup and rebuild) ---');
   const ticker = await container.resolve('ticker'); // Get current to invalidate
@@ -426,7 +424,7 @@ runLifecycleHooksExample();
 The `watch()` method provides a reactive way to observe an artifact's value without repeatedly calling `resolve()`. This is particularly useful for UI frameworks or reactive data flows.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 interface AppState {
@@ -442,7 +440,7 @@ container.register({
     const count = await use((ctx) => ctx.select((state) => state.counter));
     return `Current count: ${count}`;
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
 async function runWatcherExample() {
@@ -450,11 +448,10 @@ async function runWatcherExample() {
   const watcher = container.watch('reactiveCounter');
 
   let unsubscribe = watcher.subscribe(() => {
-    const resolved = watcher.get();
     if (resolved.ready) {
       console.log('Watcher received update:', resolved.instance);
     } else if (resolved.error) {
-      console.error('Watcher received error:', resolved.error);
+      console.error('Watcher received error:', resolved.error.message);
     } else {
       console.log('Watcher received pending update (artifact not ready yet).');
     }
@@ -475,135 +472,97 @@ async function runWatcherExample() {
   unsubscribe(); // Unsubscribe first
   await watcher.dispose(); // Then dispose the watcher itself
 
+  // After dispose, attempts to get will yield WatcherDisposedError
+  console.log('Watcher after dispose:', watcher.get().error.message);
+
   // Output:
   // Setting up watcher...
   // Watcher received pending update (artifact not ready yet).
   // Watcher received update: Current count: 0
   //
   // --- Incrementing counter ---
+  // Watcher received pending update (artifact not ready yet).
   // Watcher received update: Current count: 1
   //
   // --- Incrementing counter again ---
+  // Watcher received pending update (artifact not ready yet).
   // Watcher received update: Current count: 2
   //
   // --- Disposing watcher ---
+  // Watcher after dispose: [ArtifactContainer] Artifact with key:reactiveCounter has already been disposed
 }
 
 runWatcherExample();
 ```
 
-### Yielding Intermediate Values
+### Updating Intermediate Values with `ctx.update`
 
-For long-running or multi-stage artifact factories, `ctx.yield()` allows a Singleton artifact to publish intermediate values. This updates the artifact's current instance and notifies dependents/watchers without fully completing the factory execution.
+For long-running or multi-stage artifact factories, `ctx.update()` allows a Singleton artifact to publish intermediate values. This updates the artifact's current instance and notifies dependents/watchers without fully completing the factory execution.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
+import { ArtifactContainer, ArtifactScopes } from "@asaidimu/utils-artifacts";
+import { ReactiveDataStore } from "@asaidimu/utils-store";
 
 const store = new ReactiveDataStore({});
 const container = new ArtifactContainer(store);
 
 container.register({
-  key: 'longProcessArtifact',
-    factory: async ({ yield: publish }) => {
-        async function process() {
-            console.log('Starting long process...');
+  key: "longProcessArtifact",
+  factory: async ({ update: publish }) => { // `update` is renamed to `publish` for clarity in this example
+    async function process() {
+      await new Promise((res) => setTimeout(res, 100));
+      console.log("Starting long process...");
 
-            publish('Step 1: Initializing...');
-            await new Promise(res => setTimeout(res, 100));
+      await publish("Step 1: Initializing...");
+      await new Promise((res) => setTimeout(res, 100));
 
-            publish('Step 2: Loading data...');
-            await new Promise(res => setTimeout(res, 100));
+      await publish("Step 2: Loading data...");
+      await new Promise((res) => setTimeout(res, 100));
 
-            publish('Step 3: Processing data...');
-            await new Promise(res => setTimeout(res, 100));
+      await publish("Step 3: Processing data...");
+      await new Promise((res) => setTimeout(res, 100));
 
-            console.log('Long process complete.');
-        }
+      console.log("Long process complete.");
+    }
 
-        process()
-        return 'Created factory...';
+    queueMicrotask(process); // Start the process in the background,
+    return "Factory Starting"; 
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
-async function runYieldExample() {
-  const watcher = container.watch('longProcessArtifact');
+async function runUpdateExample() {
+  const watcher = container.watch("longProcessArtifact");
+
   const unsubscribe = watcher.subscribe(() => {
     const resolved = watcher.get();
     if (resolved.instance) {
-      console.log('Watcher observed yield:', resolved.instance);
+      console.log("Watcher observed update:", resolved.instance);
     }
   });
 
-  await container.resolve('longProcessArtifact'); // Trigger the factory
-  console.log('Factory finished.');
+  // Resolve the artifact to trigger its factory and the background process
+  await container.resolve("longProcessArtifact");
+
+  // Give some time for the process to run and yield updates
+  await new Promise((res) => setTimeout(res, 600));
 
   unsubscribe();
   await watcher.dispose();
 
-  // Output will show intermediate values from `yield` as they occur,
+  // Output will show intermediate values from `ctx.update` as they occur,
   // then the final result once the factory completes.
 }
 
-runYieldExample();
-```
-
-### Hierarchical Containers
-
-Create child containers to manage dependencies in a nested, scoped manner. Child containers can resolve artifacts registered in their parent.
-
-```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
-import { ReactiveDataStore } from '@asaidimu/utils-store';
-
-const store = new ReactiveDataStore({});
-const parentContainer = new ArtifactContainer(store);
-
-parentContainer.register({
-  key: 'globalConfig',
-  factory: () => ({ logLevel: 'info', serverUrl: 'api.example.com' }),
-  scope: ArtifactScope.Singleton,
-});
-
-const childContainer = parentContainer.createChild();
-
-childContainer.register({
-  key: 'featureService',
-  factory: async ({ use }) => {
-    const config = await use((ctx) => ctx.resolve('globalConfig')); // Resolves from parent
-    return {
-      name: 'FeatureService',
-      apiUrl: `${config.instance?.serverUrl}/feature`
-    };
-  },
-  scope: ArtifactScope.Singleton,
-});
-
-async function runHierarchicalExample() {
-  const globalConfig = await parentContainer.resolve('globalConfig');
-  const featureService = await childContainer.resolve('featureService');
-
-  console.log('Global Config from parent:', globalConfig.instance);
-  console.log('Feature Service from child:', featureService.instance);
-
-  console.assert(globalConfig.instance?.logLevel === 'info', 'Parent artifact resolved');
-  console.assert(featureService.instance?.apiUrl === 'api.example.com/feature', 'Child resolved parent artifact');
-
-  // Output:
-  // Global Config from parent: { logLevel: 'info', serverUrl: 'api.example.com' }
-  // Feature Service from child: { name: 'FeatureService', apiUrl: 'api.example.com/feature' }
-}
-
-runHierarchicalExample();
+runUpdateExample();
 ```
 
 ### Debugging Information
 
-Use `getDebugInfo()` to inspect the current state of artifacts within a container, including their status, dependencies, and dependents.
+Use `debugInfo()` to inspect the current state of artifacts within a container, including their status, dependencies, and dependents.
 
 ```typescript
-import { ArtifactContainer, ArtifactScope } from '@asaidimu/utils-artifacts';
+import { ArtifactContainer, ArtifactScopes } from '@asaidimu/utils-artifacts';
 import { ReactiveDataStore } from '@asaidimu/utils-store';
 
 const store = new ReactiveDataStore({});
@@ -612,7 +571,7 @@ const container = new ArtifactContainer(store);
 container.register({
   key: 'serviceA',
   factory: () => 'Service A Instance',
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
 container.register({
@@ -621,13 +580,13 @@ container.register({
     await use((ctx) => ctx.resolve('serviceA'));
     return 'Service B Instance';
   },
-  scope: ArtifactScope.Singleton,
+  scope: ArtifactScopes.Singleton,
 });
 
 async function runDebugInfoExample() {
   await container.resolve('serviceB'); // Resolve to build dependencies
 
-  const debugInfo = container.getDebugInfo();
+  const debugInfo = container.debugInfo();
   console.log('--- Artifact Debug Information ---');
   debugInfo.forEach(node => {
     console.log(`ID: ${node.id}`);
@@ -659,42 +618,45 @@ The `@asaidimu/utils-artifacts` package is built around the central `ArtifactCon
 
 ### Core Components
 
-*   **`ArtifactContainer`**: The heart of the system. It manages the registration, resolution, lifecycle (Singleton/Transient), and reactive updates of all artifacts. It can also create child containers to form a hierarchy.
-*   **`ArtifactDefinition`**: An internal representation of a registered artifact, holding its configuration (scope, lazy loading, retries, etc.) and runtime state (current instance, error, cleanup functions, dependency graph links).
-*   **`ArtifactFactory`**: A function that defines how an artifact instance is created. It receives an `ArtifactFactoryContext` which is crucial for declaring dependencies and managing its lifecycle.
-*   **`DataStore` (External Dependency)**: The container relies on an external data store (e.g., `@asaidimu/utils-store`) to manage global application state. The container interacts with it via `watch` (for reactive subscriptions) and `get` (for reading current state). The `buildPaths` function is used internally to derive specific state paths for granular dependency tracking.
-*   **`ArtifactWatcher`**: An observable interface for tracking the resolved state of an artifact over time, providing `get` for current value and `subscribe` for updates.
+*   **`ArtifactContainer`**: The public-facing entry point of the system. It orchestrates the registration, resolution, lifecycle management (Singleton/Transient), and reactive updates of all artifacts. It provides methods like `register`, `resolve`, `watch`, `invalidate`, and `debugInfo`.
+*   **`ArtifactRegistry`**: Manages the definitions of all registered artifacts, storing their factory functions and configuration options (scope, lazy loading, retries, debounce, timeout).
+*   **`ArtifactCache`**: Stores the runtime state of resolved singleton artifacts, including their instances, errors, cleanup functions, state dependencies, and internal synchronization primitives (`Once`, `Serializer`). It's responsible for packaging cached data into the public `ResolvedArtifact` format.
+*   **`ArtifactDependencyGraph`**: A specialized wrapper around a generic `DependencyGraph` that tracks artifact-to-artifact dependencies and state path dependencies. It's crucial for detecting circular dependencies and determining the cascade order during invalidation.
+*   **`ArtifactManager`**: The core engine responsible for the actual building, invalidation, and disposal of artifact instances. It interacts heavily with the `Registry`, `Cache`, `DependencyGraph`, and `DataStore`. It implements retry logic, timeouts, and manages lifecycle hooks.
+*   **`ArtifactObserverManager`**: Handles the creation and management of `ArtifactObserver` instances, allowing external code to subscribe to artifact changes. It also manages reference counting for watchers and notifies them of updates.
+*   **`DataStore` (External Dependency)**: The container relies on an external data store (e.g., `@asaidimu/utils-store`) to manage global application state. The container interacts with it via `watch` (for reactive subscriptions to state changes) and `get` (for reading the current state).
+*   **Synchronization Primitives (`Mutex`, `Once`, `Serializer`)**: These internal utilities provide robust mechanisms for managing concurrency, ensuring single execution of tasks, and processing operations sequentially. They are fundamental building blocks for the `ArtifactManager` and `ArtifactCache`.
 
 ### Data Flow
 
-1.  **Registration (`container.register`)**: An `ArtifactFactory` is associated with a `key` and `ArtifactOptions` (scope, lazy, retries, etc.).
+1.  **Registration (`container.register`)**: An `ArtifactTemplate` (containing an `ArtifactFactory` and its `options`) is stored in the `ArtifactRegistry`. A corresponding node is added to the `ArtifactDependencyGraph`.
 2.  **Resolution (`container.resolve`)**:
-    *   If the artifact is a `Singleton` and already built, the cached instance is returned.
-    *   If not built, the `ArtifactFactory` is invoked within a specialized context.
-    *   **Dependency Declaration (`ctx.use`)**: Inside the factory, `ctx.use` provides:
-        *   `ctx.resolve(key)`: Declares a dependency on another artifact. This call recursively triggers resolution of the dependency.
-        *   `ctx.select(selector)`: Declares a dependency on a slice of the global `DataStore` state. Internally, `buildPaths` extracts specific state paths from the selector.
-3.  **Dependency Graph Construction**: As dependencies are declared, the `ArtifactContainer` builds a precise, bidirectional dependency graph, linking artifacts to their dependents and subscribed state paths.
+    *   If the artifact is a `Singleton` and already built, its cached instance from `ArtifactCache` is returned.
+    *   If not built (or `Transient`), the `ArtifactManager` invokes the `ArtifactFactory` within a specialized `ArtifactFactoryContext`.
+    *   **Dependency Declaration (`ctx.use`)**: Inside the factory, `ctx.use` provides methods to declare dependencies:
+        *   `ctx.resolve(key)`: Recursively triggers resolution of another artifact. The relationship is added to the `ArtifactDependencyGraph`.
+        *   `ctx.select(selector)`: Extracts specific state paths from the global `DataStore`. These paths are registered as state dependencies for the artifact.
+3.  **Dependency Graph Construction**: As dependencies are declared (via `ctx.resolve` or `ctx.select`), the `ArtifactDependencyGraph` constructs a precise, bidirectional graph, linking artifacts and their state dependencies.
 4.  **Reactive Invalidation**:
-    *   **State Changes**: When a `DataStore` value changes, its `watch` callback is invoked. If the changed path matches an `ArtifactDefinition`'s `stateDependencies`, `container.invalidate()` is called for that artifact.
-    *   **Artifact Changes**: When an artifact is rebuilt or `yield()`s a new value, its `dependents` are identified and `container.invalidate()` is called for each.
+    *   **State Changes**: When a `DataStore` value changes, `ArtifactManager` identifies affected artifacts (those subscribed to the changed state paths) and calls `container.invalidate()` for them.
+    *   **Artifact Changes**: When an artifact is rebuilt, invalidated, or proactively `update()`s its value, its direct and transitive `dependents` are identified by the `ArtifactDependencyGraph`, and `container.invalidate()` is called for each.
 5.  **Rebuild Process**: `container.invalidate()` triggers:
-    *   **Debouncing**: If configured, rebuilds are debounced to consolidate multiple rapid invalidations into a single rebuild.
-    *   **Cleanup**: `onCleanup` hooks for the old instance are run.
-    *   **New Instance**: The `ArtifactFactory` is re-executed, creating a new instance.
-    *   **Graph Update**: The dependency graph is updated based on the new factory execution.
-    *   **Notification**: `ArtifactWatcher` subscribers are notified of the new instance.
-6.  **Disposal (`container.dispose` / `container.unregister`)**: All resources (`onDispose` hooks, state subscriptions, instance cache) are released.
+    *   **Debouncing**: If configured, rebuilds are debounced (`activeDebounceMs`) to consolidate multiple rapid invalidations.
+    *   **Cleanup**: `onCleanup` hooks for the *old* instance are executed.
+    *   **New Instance**: The `ArtifactFactory` is re-executed by the `ArtifactManager`, creating a new instance.
+    *   **Graph Update**: The dependency graph is updated based on any *new* dependencies declared by the re-executed factory.
+    *   **Notification**: `ArtifactObserver` subscribers are notified of the new instance via `ArtifactObserverManager`.
+6.  **Disposal (`container.dispose` / `container.unregister`)**: All resources associated with an artifact (`onDispose` hooks, state subscriptions, cache entry, graph links) are released. Full container disposal clears everything.
 
 ### Extension Points
 
 The primary extension point is the **`ArtifactFactory` function**. By implementing custom factories, you can:
-*   Integrate with any third-party library or framework.
-*   Define complex business logic.
-*   Manage external resources like database connections, API clients, or message queues.
+*   Integrate with any third-party library or framework (e.g., database clients, API wrappers, authentication services).
+*   Define complex business logic that reacts to state or other services.
+*   Manage external resources like database connections, API clients, or message queues, ensuring they are properly initialized and cleaned up using `onCleanup` and `onDispose`.
 *   Provide custom logging, monitoring, or telemetry by injecting those services as dependencies.
 
-The `ArtifactContainer` itself is designed to be highly configurable via `ArtifactOptions`, allowing fine-tuning of scope, lazy loading, error handling, and reactive behavior.
+The `ArtifactContainer` itself is designed to be highly configurable via `ArtifactTemplate` options, allowing fine-tuning of scope, lazy loading, error handling, and reactive behavior. 
 
 ---
 
@@ -724,6 +686,8 @@ We welcome contributions! Please read the guidelines below.
 
 *   `bun install`: Installs project dependencies.
 *   `bun run test`: Runs the test suite using Vitest.
+*   `bun run test:watch`: Runs tests in watch mode for continuous feedback.
+*   `bun run test:browser`: Runs tests in a browser environment.
 *   `bun run build`: Compiles the TypeScript source code into JavaScript.
 
 ### Testing
@@ -761,14 +725,15 @@ Provide as much detail as possible, including steps to reproduce, expected behav
 
 ### Troubleshooting
 
-*   **`ArtifactNotFoundError`**: This typically means you're trying to `resolve` an artifact that hasn't been `register`ed in the current container or any of its parent containers. Double-check your `key`s and registration calls.
+*   **`ArtifactNotFoundError`**: This typically means you're trying to `resolve` or `watch` an artifact that hasn't been `register`ed in the current container. Double-check your `key`s and registration calls.
 *   **`CircularDependencyError`**: Occurs when artifact A depends on B, and B depends back on A (directly or indirectly). This indicates a structural problem in your dependency graph. Redesign your artifacts to break the cycle. The error message will show the path of the cycle.
 *   **Artifact Not Updating Reactively**:
     *   Ensure your artifact is a `Singleton` (Transient artifacts don't cache or react to invalidations).
     *   Verify you are using `ctx.use()` and `ctx.select()` (for state) or `ctx.resolve()` (for other artifacts) inside your factory to declare dependencies.
     *   Check that your `DataStore` implementation is correctly triggering its `watch` callbacks.
-*   **`IllegalScopeError`**: You might be trying to `yield` a value from a `Transient` artifact. `yield` is only meaningful for `Singleton` artifacts, which maintain a persistent instance.
-*   **Timeout Errors**: Your artifact factory took longer than `timeoutMs` to complete. Consider increasing the `timeoutMs` or optimizing your factory's logic.
+*   **`IllegalScopeError`**: You might be trying to `update` a value from a `Transient` artifact. `update` is only meaningful for `Singleton` artifacts, which maintain a persistent instance.
+*   **`TimeoutError`**: Your artifact factory took longer than its configured `timeout` to complete, or a `Mutex` lock operation exceeded its timeout. Consider increasing the `timeout` or optimizing your factory's logic.
+*   **`WatcherDisposedError`**: You are attempting to access a watcher's state (`watcher.get()`) after `watcher.dispose()` has been called. Ensure you unsubscribe and dispose of watchers when no longer needed, and avoid using them afterward.
 
 ### FAQ
 
@@ -780,7 +745,7 @@ Provide as much detail as possible, including steps to reproduce, expected behav
     *   **Singleton**: For services, database connections, configuration objects, or any resource that should be shared and consistently available throughout your application. They are efficient as they are built once and reused.
     *   **Transient**: For objects that need a fresh instance every time they are requested, such as temporary calculators, request-scoped contexts, or factory functions that produce unique outputs.
 *   **How does `debounce` work?**
-    `debounce` prevents an artifact from rebuilding too frequently. If multiple invalidations occur within the specified `debounce` time, they are consolidated, and the artifact's factory is only run once after the activity ceases. This is crucial for performance with rapid state changes.
+    `debounce` prevents an artifact from rebuilding too frequently. If multiple invalidations occur within the specified `debounce` time, they are consolidated, and the artifact's factory is only run once after the activity ceases. This is crucial for performance with rapid state changes, especially when many state changes might trigger the same artifact rebuild.
 
 ### Changelog / Roadmap
 
@@ -796,4 +761,3 @@ This project is licensed under the MIT License. See the [LICENSE](https://github
 *   Developed as part of the `@asaidimu` utilities collection.
 *   Uses [Semantic Release](https://semantic-release.gitbook.io/semantic-release/) for automated versioning and publishing.
 *   Leverages [Vitest](https://vitest.dev/) for fast and reliable testing.
-