@veams/status-quo 1.6.0 → 1.8.0

package/dist/store/signal-state-handler.js

@@ -1,41 +1,76 @@
+/**
+ * Import signal-based state primitives from @preact/signals-core.
+ */
 import { signal } from '@preact/signals-core';
+/**
+ * Import internal configuration and the abstract base state handler.
+ */
 import { resolveDistinctOptions } from '../config/status-quo-config.js';
 import { BaseStateHandler } from './base-state-handler.js';
+/**
+ * SignalStateHandler: A state handler built on top of Preact Signals.
+ * Provides fine-grained reactivity and efficient state updates.
+ */
 export class SignalStateHandler extends BaseStateHandler {
+    // Internal Signal to manage the state with high performance.
     state;
+    // Configuration to determine if and how state changes should trigger notifications.
     distinctOptions;
+    /**
+     * Initializes the signal state handler with given state and configuration.
+     */
     constructor({ initialState, options }) {
+        // Pass the initial state to the base handler.
         super(initialState);
+        // Initialize the internal Signal with the initial state.
         this.state = signal(initialState);
+        // Resolve the final distinct options based on provided configuration.
         this.distinctOptions = resolveDistinctOptions(options?.distinct, options?.useDistinctUntilChanged);
+        // Initialize Redux DevTools integration.
         this.initDevTools(options?.devTools);
     }
+    /**
+     * Returns the underlying signal for external use (e.g., in reactive templates).
+     */
     getSignal() {
         return this.state;
     }
     subscribe(listener) {
+        // Track whether the listener has been initialized during the first emission.
         let initialized = false;
+        // Keep track of the previous state snapshot for comparison.
         let previousSnapshot = this.state.value;
+        // Use the Signal's subscription method.
         return this.state.subscribe((nextState) => {
+            // If this is the initial emission, notify the listener and mark as initialized.
             if (!initialized) {
                 initialized = true;
                 previousSnapshot = nextState;
                 listener(nextState);
                 return;
             }
+            // If distinct mode is enabled and the state hasn't effectively changed, stop here.
             if (this.distinctOptions.enabled &&
                 this.distinctOptions.comparator(previousSnapshot, nextState)) {
                 previousSnapshot = nextState;
                 return;
             }
+            // Update the previous snapshot and notify the listener.
             previousSnapshot = nextState;
             listener(nextState);
         });
     }
+    /**
+     * Internal implementation of getting the state value via the Signal's value property.
+     */
     getStateValue() {
         return this.state.value;
     }
+    /**
+     * Internal implementation of updating the state value via the Signal's value property.
+     */
     setStateValue(nextState) {
+        // Update the Signal's value, which automatically notifies its subscribers.
         this.state.value = nextState;
     }
 }

package/dist/store/signal-state-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"signal-state-handler.js","sourceRoot":"","sources":["../../src/store/signal-state-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAc3D,MAAM,OAAgB,kBAAyB,SAAQ,gBAAsB;IAC1D,KAAK,CAAY;IACjB,eAAe,CAA+C;IAE/E,YAAsB,EAAE,YAAY,EAAE,OAAO,EAA8B;QACzE,KAAK,CAAC,YAAY,CAAC,CAAC;QAEpB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAI,YAAY,CAAC,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,sBAAsB,CAC3C,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,uBAAuB,CACjC,CAAC;QACF,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAID,SAAS,CAAC,QAA4B;QACpC,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,IAAI,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAExC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE;YACxC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,WAAW,GAAG,IAAI,CAAC;gBACnB,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACpB,OAAO;YACT,CAAC;YAED,IACE,IAAI,CAAC,eAAe,CAAC,OAAO;gBAC5B,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,gBAAgB,EAAE,SAAS,CAAC,EAC5D,CAAC;gBACD,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,OAAO;YACT,CAAC;YAED,gBAAgB,GAAG,SAAS,CAAC;YAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAES,aAAa;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAES,aAAa,CAAC,SAAY;QAClC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"signal-state-handler.js","sourceRoot":"","sources":["../../src/store/signal-state-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAsB3D;;;GAGG;AACH,MAAM,OAAgB,kBAAyB,SAAQ,gBAAsB;IAC3E,6DAA6D;IAC5C,KAAK,CAAY;IAClC,oFAAoF;IACnE,eAAe,CAA+C;IAE/E;;OAEG;IACH,YAAsB,EAAE,YAAY,EAAE,OAAO,EAA8B;QACzE,8CAA8C;QAC9C,KAAK,CAAC,YAAY,CAAC,CAAC;QACpB,yDAAyD;QACzD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAI,YAAY,CAAC,CAAC;QACrC,sEAAsE;QACtE,IAAI,CAAC,eAAe,GAAG,sBAAsB,CAC3C,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,uBAAuB,CACjC,CAAC;QACF,yCAAyC;QACzC,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAQD,SAAS,CAAC,QAA4B;QACpC,6EAA6E;QAC7E,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,4DAA4D;QAC5D,IAAI,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAExC,wCAAwC;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE;YACxC,gFAAgF;YAChF,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,WAAW,GAAG,IAAI,CAAC;gBACnB,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACpB,OAAO;YACT,CAAC;YAED,mFAAmF;YACnF,IACE,IAAI,CAAC,eAAe,CAAC,OAAO;gBAC5B,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,gBAAgB,EAAE,SAAS,CAAC,EAC5D,CAAC;gBACD,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,OAAO;YACT,CAAC;YAED,wDAAwD;YACxD,gBAAgB,GAAG,SAAS,CAAC;YAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACO,aAAa;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;OAEG;IACO,aAAa,CAAC,SAAY;QAClC,2EAA2E;QAC3E,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAC/B,CAAC;CACF"}

package/dist/store/state-singleton.d.ts

@@ -1,8 +1,22 @@
+/**
+ * Import necessary type for state subscription management.
+ */
 import type { StateSubscriptionHandler } from '../types/types.js';
+/**
+ * Interface representing a singleton state handler.
+ * Provides a method to get the single instance of a state handler.
+ */
 export interface StateSingleton<V, A> {
     getInstance: () => StateSubscriptionHandler<V, A>;
 }
+/**
+ * Options for configuring the behavior of a state singleton.
+ */
 export interface StateSingletonOptions {
     destroyOnNoConsumers?: boolean;
 }
+/**
+ * Factory function to create a singleton state handler.
+ * Ensures only one instance of the state handler exists throughout the application.
+ */
 export declare function makeStateSingleton<S, A>(stateHandlerFactory: () => StateSubscriptionHandler<S, A>, { destroyOnNoConsumers }?: StateSingletonOptions): StateSingleton<S, A>;

package/dist/store/state-singleton.js

@@ -1,21 +1,40 @@
-export function makeStateSingleton(stateHandlerFactory, { destroyOnNoConsumers = false } = {}) {
+/**
+ * Factory function to create a singleton state handler.
+ * Ensures only one instance of the state handler exists throughout the application.
+ */
+export function makeStateSingleton(
+// Function responsible for creating the state handler instance when needed.
+stateHandlerFactory, 
+// Optional configuration for the singleton.
+{ destroyOnNoConsumers = false } = {}) {
+    // Internal variable to store the shared instance of the state handler.
     let instance = null;
+    // The singleton object with an added internal destroy method.
     const singleton = {
+        // Expose whether this singleton should be destroyed when not in use.
         destroyOnNoConsumers,
+        // Method to get or create the singleton instance.
         getInstance() {
+            // If no instance exists, create it using the factory function.
             if (!instance) {
                 instance = stateHandlerFactory();
             }
+            // Return the current instance.
             return instance;
         },
+        // Method to manually destroy the singleton instance and its resources.
         destroyInstance() {
+            // If no instance exists, there's nothing to destroy.
             if (!instance) {
                 return;
             }
+            // Call the destroy method on the instance to clean up its resources.
             instance.destroy();
+            // Clear the internal reference to the instance.
             instance = null;
         },
     };
+    // Return the created singleton object.
     return singleton;
 }
 //# sourceMappingURL=state-singleton.js.map

package/dist/store/state-singleton.js.map

@@ -1 +1 @@
-{"version":3,"file":"state-singleton.js","sourceRoot":"","sources":["../../src/store/state-singleton.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,kBAAkB,CAChC,mBAAyD,EACzD,EAAE,oBAAoB,GAAG,KAAK,KAA4B,EAAE;IAE5D,IAAI,QAAQ,GAA0C,IAAI,CAAC;IAC3D,MAAM,SAAS,GAGX;QACF,oBAAoB;QACpB,WAAW;YACT,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,mBAAmB,EAAE,CAAC;YACnC,CAAC;YAED,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,eAAe;YACb,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YAED,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;KACF,CAAC;IAEF,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"state-singleton.js","sourceRoot":"","sources":["../../src/store/state-singleton.ts"],"names":[],"mappings":"AAsBA;;;GAGG;AACH,MAAM,UAAU,kBAAkB;AAChC,4EAA4E;AAC5E,mBAAyD;AACzD,4CAA4C;AAC5C,EAAE,oBAAoB,GAAG,KAAK,KAA4B,EAAE;IAE5D,uEAAuE;IACvE,IAAI,QAAQ,GAA0C,IAAI,CAAC;IAE3D,8DAA8D;IAC9D,MAAM,SAAS,GAGX;QACF,qEAAqE;QACrE,oBAAoB;QACpB,kDAAkD;QAClD,WAAW;YACT,+DAA+D;YAC/D,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,QAAQ,GAAG,mBAAmB,EAAE,CAAC;YACnC,CAAC;YAED,+BAA+B;YAC/B,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,uEAAuE;QACvE,eAAe;YACb,qDAAqD;YACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YAED,qEAAqE;YACrE,QAAQ,CAAC,OAAO,EAAE,CAAC;YACnB,gDAAgD;YAChD,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;KACF,CAAC;IAEF,uCAAuC;IACvC,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/types/types.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Common types and interfaces for state management.
+ */
+/**
+ * Interface representing a standard state handler with subscription support.
+ * Used by React hooks and other components to interact with the state store.
+ * V: The type of the state value.
+ * A: The type of the available actions.
+ */
 export interface StateSubscriptionHandler<V, A> {
     subscribe(listener: () => void): () => void;
     subscribe(listener: (value: V) => void): () => void;

package/dist/types/types.js

@@ -1,2 +1,5 @@
+/**
+ * Common types and interfaces for state management.
+ */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/types/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/utils/selector-cache.d.ts

@@ -1,13 +1,30 @@
+/**
+ * Utility functions for caching selector results to optimize state updates.
+ */
 export type Selector<Value, Selected> = (value: Value) => Selected;
 export type EqualityFn<Selected> = (current: Selected, next: Selected) => boolean;
+/**
+ * Interface for internal selector cache storage.
+ */
 type SelectorCache<Selected> = {
     hasValue: boolean;
     value: Selected | undefined;
 };
+/**
+ * Interface for the result of a selection operation.
+ */
 type SelectionResult<Selected> = {
     value: Selected;
     hasChanged: boolean;
 };
+/**
+ * Creates a new, empty selector cache.
+ * Provides a simple container to track state and values across selections.
+ */
 export declare function createSelectorCache<Selected>(): SelectorCache<Selected>;
+/**
+ * Executes a selector and returns the cached value if the result is considered equal.
+ * This optimization avoids unnecessary re-renders or updates when the derived state is the same.
+ */
 export declare function selectWithCache<Value, Selected>(selectorCache: SelectorCache<Selected>, value: Value, selector: Selector<Value, Selected>, isEqual?: EqualityFn<Selected>): SelectionResult<Selected>;
 export {};

package/dist/utils/selector-cache.js

@@ -1,21 +1,48 @@
+/**
+ * Utility functions for caching selector results to optimize state updates.
+ */
+/**
+ * Creates a new, empty selector cache.
+ * Provides a simple container to track state and values across selections.
+ */
 export function createSelectorCache() {
     return {
+        // Initially, no value is stored in the cache.
         hasValue: false,
         value: undefined,
     };
 }
-export function selectWithCache(selectorCache, value, selector, isEqual = Object.is) {
+/**
+ * Executes a selector and returns the cached value if the result is considered equal.
+ * This optimization avoids unnecessary re-renders or updates when the derived state is the same.
+ */
+export function selectWithCache(
+// The cache object to store and compare values.
+selectorCache, 
+// The source value from which to select.
+value, 
+// The selector function to transform the source value.
+selector, 
+// Optional equality function to compare selected values (defaults to Object.is).
+isEqual = Object.is) {
+    // Execute the selector to derive the current selection value.
     const nextSelection = selector(value);
+    // If the cache has a value and the new selection is equal to it, return the cached version.
     if (selectorCache.hasValue && isEqual(selectorCache.value, nextSelection)) {
         return {
+            // Return the previously cached value to maintain referential stability.
             value: selectorCache.value,
+            // Signal that no effective change has occurred.
             hasChanged: false,
         };
     }
+    // Update the cache with the newly computed selection.
     selectorCache.hasValue = true;
     selectorCache.value = nextSelection;
     return {
+        // Return the fresh selection result.
         value: nextSelection,
+        // Signal that the selected value has changed.
         hasChanged: true,
     };
 }

package/dist/utils/selector-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"selector-cache.js","sourceRoot":"","sources":["../../src/utils/selector-cache.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,SAAS;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,aAAsC,EACtC,KAAY,EACZ,QAAmC,EACnC,UAAgC,MAAM,CAAC,EAAE;IAEzC,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEtC,IAAI,aAAa,CAAC,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,KAAiB,EAAE,aAAa,CAAC,EAAE,CAAC;QACtF,OAAO;YACL,KAAK,EAAE,aAAa,CAAC,KAAiB;YACtC,UAAU,EAAE,KAAK;SAClB,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC;IAEpC,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"selector-cache.js","sourceRoot":"","sources":["../../src/utils/selector-cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AA4BH;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,8CAA8C;QAC9C,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,SAAS;KACjB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe;AAC7B,gDAAgD;AAChD,aAAsC;AACtC,yCAAyC;AACzC,KAAY;AACZ,uDAAuD;AACvD,QAAmC;AACnC,iFAAiF;AACjF,UAAgC,MAAM,CAAC,EAAE;IAEzC,8DAA8D;IAC9D,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEtC,4FAA4F;IAC5F,IAAI,aAAa,CAAC,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,KAAiB,EAAE,aAAa,CAAC,EAAE,CAAC;QACtF,OAAO;YACL,wEAAwE;YACxE,KAAK,EAAE,aAAa,CAAC,KAAiB;YACtC,gDAAgD;YAChD,UAAU,EAAE,KAAK;SAClB,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,aAAa,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC;IAEpC,OAAO;QACL,qCAAqC;QACrC,KAAK,EAAE,aAAa;QACpB,8CAA8C;QAC9C,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "The manager to rule states in frontend.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -51,6 +51,17 @@
     "react": ">=18.0.0",
     "rxjs": ">=7.5.4"
   },
+  "peerDependenciesMeta": {
+    "@preact/signals-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "rxjs": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@preact/signals-core": "^1.13.0",
     "@types/react-dom": "^19.0.0",

package/src/config/status-quo-config.ts

@@ -1,55 +1,91 @@
+/**
+ * Global configuration and utility functions for Status Quo state management.
+ */
+
+// Function signature for comparing state objects to determine if they are distinct.
 export type DistinctComparator<T = unknown> = (previous: T, next: T) => boolean;
 
+// Options for configuring distinct emission behavior in state handlers.
 export type DistinctOptions<T = unknown> = {
+  // Whether distinct updates are enabled.
   enabled?: boolean;
+  // Custom function to compare states for equality.
   comparator?: DistinctComparator<T>;
 };
 
+// Options for configuring Redux DevTools integration for a specific state handler.
 export type DevToolsOptions = {
+  // Whether DevTools integration is enabled for this handler.
   enabled?: boolean;
+  // Namespace for the store in the DevTools window.
   namespace?: string;
 };
 
+// Global options for Redux DevTools integration across all handlers.
 export type GlobalDevToolsOptions = {
+  // Whether DevTools integration is enabled globally.
   enabled?: boolean;
 };
 
+// Main configuration object for the Status Quo system.
 export type StatusQuoConfig<T = unknown> = {
+  // Global DevTools configuration.
   devTools?: GlobalDevToolsOptions;
+  // Global distinct emission configuration.
   distinct?: DistinctOptions<T>;
 };
 
+// Internal representation of resolved distinct options.
 type ResolvedDistinctOptions<T = unknown> = {
+  // Final enabled status for distinct updates.
   enabled: boolean;
+  // Final comparator function to use for equality checks.
   comparator: DistinctComparator<T>;
 };
 
+// Internal representation of resolved DevTools options.
 type ResolvedDevToolsOptions = {
+  // Final enabled status for DevTools.
   enabled: boolean;
 };
 
+// Internal representation of the full resolved configuration.
 type ResolvedStatusQuoConfig = {
+  // Resolved global DevTools configuration.
   devTools: ResolvedDevToolsOptions;
+  // Resolved global distinct emission configuration.
   distinct: ResolvedDistinctOptions;
 };
 
+/**
+ * Default comparator function that uses referential equality (Object.is)
+ * and falls back to JSON stringification for structural equality.
+ */
 function distinctAsJson(previous: unknown, next: unknown) {
+  // Fast path for referential equality.
   if (Object.is(previous, next)) {
     return true;
   }
 
+  // Structural comparison using JSON stringification as a fallback.
   try {
     return JSON.stringify(previous) === JSON.stringify(next);
   } catch {
+    // If stringification fails, assume they are not equal.
     return false;
   }
 }
 
+/**
+ * Creates the default Status Quo configuration.
+ */
 function createDefaultStatusQuoConfig(): ResolvedStatusQuoConfig {
   return {
+    // DevTools integration is disabled by default.
     devTools: {
       enabled: false,
     },
+    // Distinct emission is enabled by default with JSON-based structural equality.
     distinct: {
       enabled: true,
       comparator: distinctAsJson,
@@ -57,13 +93,20 @@ function createDefaultStatusQuoConfig(): ResolvedStatusQuoConfig {
   };
 }
 
+// Global configuration instance, initialized with defaults.
 let statusQuoConfig = createDefaultStatusQuoConfig();
 
+/**
+ * Global setup function to configure Status Quo.
+ */
 export function setupStatusQuo<T = unknown>(config: StatusQuoConfig<T> = {}) {
+  // Merge the provided configuration with the current global config.
   statusQuoConfig = {
+    // Update global DevTools status.
     devTools: {
       enabled: config.devTools?.enabled ?? false,
     },
+    // Update global distinct emission status and comparator.
     distinct: {
       enabled: config.distinct?.enabled ?? true,
       comparator: (config.distinct?.comparator ?? distinctAsJson) as DistinctComparator,
@@ -71,23 +114,39 @@ export function setupStatusQuo<T = unknown>(config: StatusQuoConfig<T> = {}) {
   };
 }
 
+/**
+ * Resolves the final distinct options for a specific state handler.
+ * Combines global configuration with handler-specific overrides.
+ */
 export function resolveDistinctOptions<T>(
+  // Handler-specific distinct options.
   options?: DistinctOptions<T>,
+  // Boolean flag often used to override or determine enabled status.
   useDistinctUntilChanged?: boolean
 ): ResolvedDistinctOptions<T> {
   return {
+    // Determine the enabled status for distinct emissions.
     enabled: options?.enabled ?? useDistinctUntilChanged ?? statusQuoConfig.distinct.enabled,
+    // Determine the comparator function to use.
     comparator: (options?.comparator ??
       statusQuoConfig.distinct.comparator),
   };
 }
 
+/**
+ * Resolves the final DevTools options for a specific state handler.
+ * Combines global configuration with handler-specific overrides.
+ */
 export function resolveDevToolsOptions(options?: DevToolsOptions): ResolvedDevToolsOptions {
   return {
+    // Determine the enabled status for DevTools integration.
     enabled: options?.enabled ?? statusQuoConfig.devTools.enabled,
   };
 }
 
+/**
+ * Returns a copy of the current global configuration.
+ */
 export function getStatusQuoConfig() {
   return {
     devTools: {
@@ -100,7 +159,11 @@ export function getStatusQuoConfig() {
   } as ResolvedStatusQuoConfig;
 }
 
-/** @internal testing helper */
+/**
+ * Resets the Status Quo configuration to its default values.
+ * Useful for ensuring test isolation in unit tests.
+ * @internal testing helper
+ */
 export function resetStatusQuoForTests() {
   statusQuoConfig = createDefaultStatusQuoConfig();
 }

package/src/index.ts

@@ -1,11 +1,19 @@
+/**
+ * Main entry point for the Status Quo state management library.
+ * Exports core functionality for both store and React integration.
+ */
+
+// Import internal setup functions and core state handlers.
 import { setupStatusQuo } from './config/status-quo-config.js';
 import {
   BaseStateHandler,
   makeStateSingleton,
+  NativeStateHandler,
   ObservableStateHandler,
   SignalStateHandler,
 } from './store';
 
+// Import necessary types for external use.
 import type {
   DevToolsOptions,
   GlobalDevToolsOptions,
@@ -16,21 +24,42 @@ import type {
 import type { StateSingleton, StateSingletonOptions } from './store';
 import type { StateSubscriptionHandler } from './types/types.js';
 
+/**
+ * Core state management functions and classes.
+ */
 export {
+  // Abstract base class for all state handlers.
   BaseStateHandler,
+  // Factory function for creating singleton state handlers.
   makeStateSingleton,
+  // Lightweight state handler using plain JavaScript.
+  NativeStateHandler,
+  // State handler powered by RxJS BehaviorSubjects.
   ObservableStateHandler,
+  // Global configuration function for Status Quo.
   setupStatusQuo,
+  // State handler powered by Preact Signals.
   SignalStateHandler,
 };
 
+/**
+ * Type definitions for public API.
+ */
 export type {
+  // Options for Redux DevTools integration.
   DevToolsOptions,
+  // Global options for Redux DevTools.
   GlobalDevToolsOptions,
+  // Function signature for state equality comparisons.
   DistinctComparator,
+  // Options for configuring distinct updates.
   DistinctOptions,
+  // Interface representing a singleton state handler.
   StateSingleton,
+  // Options for configuring state singleton instances.
   StateSingletonOptions,
+  // Interface representing a standard state subscription handler.
   StateSubscriptionHandler,
+  // Main configuration object for the Status Quo system.
   StatusQuoConfig,
 };

package/src/react/hooks/__tests__/state-provider.spec.tsx

@@ -6,7 +6,7 @@ import {
   useProvidedStateActions,
   useProvidedStateHandler,
   useProvidedStateSubscription,
-} from '../state-provider.js';
+} from '../index.js';
 
 import type { StateSubscriptionHandler } from '../../../types/types.js';
 
@@ -279,7 +279,7 @@ describe('StateProvider', () => {
       act(() => {
         root.render(<MissingProviderConsumer />);
       });
-    }).toThrow('No StateProvider instance found in the current React tree.');
+    }).toThrow('useProvidedStateHandler must be used within a StateProvider');
 
     consoleErrorSpy.mockRestore();
   });

package/src/react/hooks/__tests__/state-selector.spec.tsx

@@ -331,6 +331,23 @@ const FullSubscriptionConsumer = ({
   return <span>{state.user.name}</span>;
 };
 
+type ObjectSelectorConsumerProps = {
+  createStateHandler: () => StateSubscriptionHandler<TestState, TestActions>;
+  onRender: (value: { counter: number; userName: string }) => void;
+};
+
+const ObjectSelectorConsumer = ({ createStateHandler, onRender }: ObjectSelectorConsumerProps) => {
+  const stateHandler = useStateHandler(createStateHandler, []);
+  const [summary] = useStateSubscription(stateHandler, (state) => ({
+    counter: state.counter,
+    userName: state.user.name,
+  }));
+
+  onRender(summary);
+
+  return <span>{summary.userName}</span>;
+};
+
 type StrictModeMirrorFactoryConsumerProps = {
   createStateHandler: () => StateSubscriptionHandler<CounterMirrorState, CounterMirrorActions>;
   onRender: (count: number) => void;
@@ -569,6 +586,55 @@ describe('Selector hooks', () => {
     expect(renderSpy).toHaveBeenCalledTimes(2);
   });
 
+  it('useStateSubscription should cache object selector snapshots within one store version', () => {
+    let stateHandler: TestStateHandler | null = null;
+    const createStateHandler = jest.fn(() => {
+      if (!stateHandler) {
+        stateHandler = new TestStateHandler({
+          user: { name: 'Ada' },
+          counter: 0,
+        });
+      }
+
+      return stateHandler;
+    });
+    const renderSpy = jest.fn();
+
+    expect(() => {
+      act(() => {
+        root.render(
+          <ObjectSelectorConsumer createStateHandler={createStateHandler} onRender={renderSpy} />
+        );
+      });
+    }).not.toThrow();
+
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+    expect(renderSpy).toHaveBeenLastCalledWith({
+      counter: 0,
+      userName: 'Ada',
+    });
+
+    act(() => {
+      stateHandler!.getActions().increment();
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(2);
+    expect(renderSpy).toHaveBeenLastCalledWith({
+      counter: 1,
+      userName: 'Ada',
+    });
+
+    act(() => {
+      stateHandler!.getActions().setName('Grace');
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(3);
+    expect(renderSpy).toHaveBeenLastCalledWith({
+      counter: 1,
+      userName: 'Grace',
+    });
+  });
+
   it('useStateSubscription should return full snapshot when no selector is provided', () => {
     let stateHandler: TestStateHandler | null = null;
     const createStateHandler = jest.fn(() => {

package/src/react/hooks/index.ts

@@ -1,11 +1,16 @@
-export { useStateActions } from './state-actions.js';
+/**
+ * Export available hooks for React components.
+ */
+
+// Export hook to access the actions of a state handler.
+export { useProvidedStateActions, useStateActions } from './state-actions.js';
+// Export hook to create and manage a state handler within a component.
 export { useStateFactory } from './state-factory.js';
+// Export hook to manage a state handler's lifecycle within a component's reference.
 export { useStateHandler } from './state-handler.js';
-export {
-  StateProvider,
-  useProvidedStateActions,
-  useProvidedStateHandler,
-  useProvidedStateSubscription,
-} from './state-provider.js';
+// Export hook and component to use a state handler through React Context.
+export { StateProvider, useProvidedStateHandler } from './state-provider.js';
+// Export hook to use a singleton state handler.
 export { useStateSingleton } from './state-singleton.js';
-export { useStateSubscription } from './state-subscription.js';
+// Export hook to subscribe to a state handler and receive its state updates.
+export { useProvidedStateSubscription, useStateSubscription } from './state-subscription.js';