orchestore 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -1,6 +1,183 @@
-import React from 'react';
+import { ConfigureStoreOptions } from '@reduxjs/toolkit';
 import { ProviderProps } from 'react-redux';
 
+type NodePrototype<N, A extends any[] = []> = {
+    /**
+     * Creates a new detached instance within the same lineage.
+     *
+     * The cloned instance is fully independent at runtime, but still
+     * linked to the original definition family.
+     */
+    readonly clone: (...args: A) => N;
+    /**
+     * Returns all instances that belong to the same lineage family,
+     * including the current instance.
+     */
+    readonly getLineage: () => N[];
+    /**
+     * Returns all other instances in the same lineage,
+     * excluding the current instance.
+     */
+    readonly getClones: () => N[];
+    /**
+     * Checks whether another instance belongs to the same lineage.
+     *
+     * Useful for verifying whether two slices originate from the same definition,
+     * even if they are different runtime instances.
+     */
+    readonly isTypeOf: (other?: any) => other is N;
+};
+
+declare global {
+    namespace OrcheStore {
+        /** User-defined framework type slots. */
+        interface Slots {
+        }
+    }
+}
+/** Resolves a type slot with validation and fallback support. */
+type Definition<T, Rule, Default> = T extends keyof OrcheStore.Slots ? Exclude<OrcheStore.Slots[T], undefined | null> extends Rule ? Exclude<OrcheStore.Slots[T], undefined | null> : Default : Default;
+/** Resolved type for application-wide utilities. */
+type Utils = {
+    /**
+     * Application-wide utilities shared across all slices and the store.
+     *
+     * Utilities provide a global place to register and access runtime services such as:
+     * navigation, notifications, API clients, analytics, and other shared helpers.
+     *
+     * Once registered, utilities are available everywhere in the application:
+     * - inside slices via `this.utils`
+     * - from the root store via `store.utils`
+     * - directly via `getUtils()`
+     *
+     * Utilities can be updated at runtime using `setUtils`, and all updates are
+     * immediately reflected across the entire store tree.
+     *
+     * @example
+     * ```ts
+     * // Register utilities
+     * setUtils({
+     *   notify(type, message) {
+     *     console.log(type, message);
+     *   },
+     * });
+     *
+     * // Inside a slice
+     * const userSlice = createSlice({
+     *   name: "user",
+     *   state: { loading: false },
+     *
+     *   methods: {
+     *     login() {
+     *       this.utils.notify("success", "Login successful");
+     *     },
+     *   },
+     * });
+     *
+     * // From the store
+     * store.utils.notify("info", "App started");
+     *
+     * // Direct access
+     * const utils = getUtils();
+     * utils.notify("success", "Hello");
+     * ```
+     */
+    utils: Definition<"utils", Dict, any>;
+};
+
+/**
+ * Runtime API returned by `createStore()`.
+ *
+ * The store represents the root of the OrcheStore runtime tree and provides
+ * access to all mounted slices, global state, and shared utilities.
+ */
+type store<C> = OmitNever<Utils & {
+    /** Unique name of the store. */
+    readonly name: string;
+    /**
+     * Returns the current immutable state snapshot of the entire store tree.
+     *
+     * Includes all mounted slices and nested state.
+     */
+    readonly getState: () => StoreState<C>;
+    /**
+     * Subscribes to store state changes inside React components.
+     *
+     * The selector receives the full store state along with a context
+     * containing shared utilities.
+     *
+     * This hook is bound to the store instance and requires `StoreProvider`
+     * to be mounted in the React tree.
+     */
+    readonly useSelect: <T>(selector: (this: Utils, state: StoreState<C>, context: Utils) => T) => T;
+} & {
+    /** Root mounted slice instances. */
+    readonly [K in Exclude<keyof C, ReservedStoreKeys>]: C[K] extends slice<infer S, infer R, infer M, infer C> ? slice<S, R, M, C> : never;
+}>;
+/**
+ * Configuration used to create a store instance.
+ *
+ * A store is composed of multiple slices that are mounted into a single
+ * runtime tree. Each slice becomes accessible directly through the store API.
+ */
+type storeOptions<C> = Omit<ConfigureStoreOptions, "reducer" | "middleware" | "duplicateMiddlewareCheck" | "preloadedState" | "enhancers"> & {
+    /** Unique name of the store. */
+    readonly name?: string;
+    /**
+     * Collection of slices registered in this store.
+     *
+     * Each slice is mounted and becomes available as:
+     * `store.<sliceKey>`
+     *
+     * @example
+     * ```ts
+     * const store = createStore({
+     *   slices: {
+     *     counter,
+     *     user,
+     *   },
+     * });
+     *
+     * // Exposed slices access
+     * store.user.getState();
+     * store.counter.increment();
+     * store.counter.useSelect((state) => state.value);
+     *
+     * // State tree access
+     * store.getState().counter.value;
+     * store.useSelect((state) => state.counter.value);
+     * ```
+     */
+    slices: C;
+};
+/**
+ * Derived immutable state shape of the store.
+ *
+ * Represents the full read-only state tree including all mounted slices.
+ */
+type StoreState<C> = ReadOnly<OmitNever<{
+    readonly [K in Exclude<keyof C, ReservedStoreKeys>]: C[K] extends slice<infer S, infer _, infer __, infer C> ? SliceState.State<S, C> : never;
+}>>;
+/**
+ * Props for the OrcheStore React provider.
+ *
+ * Wraps the application and injects the store into React-Redux context.
+ */
+type StoreProviderProps<T = any> = Omit<ProviderProps, "store" | "serverState" | "context"> & {
+    /**
+     * Root store instance created with `createStore()`.
+     *
+     * This store will be injected into the React component tree.
+     */
+    store: store<T>;
+};
+/**
+ * Property names reserved by the framework.
+ *
+ * These names cannot be used for child slices.
+ */
+type ReservedStoreKeys<R = {}, M = {}> = ("name" | "computed" | "utils" | "getState" | "useSelect") | (keyof R | keyof M);
+
 /** `Record` with string keys, requiring only the value type. */
 type Dict<Value = any> = Record<string, Value>;
 /** `Record` with default property keys, requiring only the value type. */
@@ -16,63 +193,181 @@ type ReadOnly<T> = T extends (...args: any[]) => any ? T : T extends readonly (i
     readonly [K in keyof T]: ReadOnly<T[K]>;
 } : T;
 
-/** Runtime slice API exposed by createSlice(...). */
-type slice<S extends Obj, R extends Mutations<S, C>, M, C> = GlobalUtils & {
-    /** Unique slice identifier. */
+/** Runtime API returned by `createSlice()`. */
+type slice<S extends Obj, R extends Mutations<S, C>, M, C> = Utils & {
+    /** Unique name of the slice. */
     readonly name: string;
-    /** Fully qualified runtime path of the slice. */
+    /** Dot-separated path of this slice within the mounted store tree. */
     readonly path: string;
-    /** Returns the latest immutable state snapshot. */
-    readonly getState: () => SliceState.State<S, C>;
-    /** Subscribes to state changes within React components. Runs with a context-bound `this` containing `root` store, `rootState` and `global` utilities. */
-    readonly useSelect: <T>(selector: (this: GlobalUtils, state: SliceState.State<S, C>, context: GlobalUtils) => T) => T;
-    /** Root store that owns this slice instance. */
+    /** Root store instance that owns this slice. */
     root: store<any>;
-    /** Parent slice in the hierarchy, if mounted under another slice. */
+    /** Parent slice in the runtime tree, or `undefined` if this is a root slice. */
     parent: slice<any, Mutations<any, any>, any, any> | undefined;
-    /** Runtime lineage and cloning utilities for this slice instance. */
-    readonly prototype: {
-        /** Creates a new detached clone within the same lineage. */
-        readonly clone: () => slice<S, R, M, C>;
-        /** Returns all slice instances in the same lineage, including this one. */
-        readonly getLineage: () => slice<S, R, M, C>[];
-        /** Returns all sibling instances in the same lineage, excluding this one. */
-        readonly getClones: () => slice<S, R, M, C>[];
-        /** Returns true if both slices belong to the same lineage. */
-        readonly isTypeOf: (other: any) => boolean;
+    /**
+     * Subscribes to this slice's state changes inside React components.
+     *
+     * The selector receives:
+     * - full store state
+     * - runtime utilities context
+     *
+     * The hook is context-bound to the store instance.
+     *
+     * The hook rely on utilizing StoreProvider being present in the component tree.
+     */
+    readonly useSelect: <T>(selector: (this: Utils, state: SliceState.State<S, C>, context: Utils) => T) => T;
+    /**
+     * Returns the current immutable state snapshot of the slice.
+     *
+     * Includes all mounted child slices and nested state.
+     */
+    readonly getState: () => SliceState.State<S, C>;
+    /**
+     * Returns the slice's original initial state.
+     *
+     * Does not include runtime updates or mutations.
+     */
+    readonly getInitialState: {
+        /**
+         * Returns the slice's original initial state.
+         *
+         * Does not include runtime updates or mutations.
+         */
+        (): SliceState.State<S, {}>;
+        /**
+         * Returns the complete initial state.
+         *
+         * Includes all mounted child slices and nested state.
+         */
+        readonly deep: () => SliceState.State<S, C>;
     };
+    /**
+     * Runtime utilities for cloning, lineage inspection,
+     * and instance identity.
+     */
+    readonly prototype: NodePrototype<slice<S, R, M, C>, [CloneArgs<S, C>["transform"]]>;
     /** Collection of derived state functions. */
     readonly computed: undefined;
 } & OmitNever<{
-    /** Exposed mutation functions. */
+    /** Directly callable state mutation functions. */
     readonly [K in Exclude<keyof R, ReservedSliceKeys>]: R[K] extends (...args: any[]) => void ? (...args: Tail<Parameters<R[K]>>) => void : never;
 }> & OmitNever<{
-    /** Exposed method functions. */
+    /** User-defined instance methods. */
     readonly [K in Exclude<keyof M, ReservedSliceKeys<R>>]: M[K] extends (...args: any[]) => void ? M[K] : never;
 }> & OmitNever<{
-    /** Exposed children. */
+    /** Nested child slice instances. */
     readonly [K in Exclude<keyof C, ReservedSliceKeys<R, M>>]: C[K] extends slice<infer S, infer R, infer M, infer C> ? slice<S, R, M, C> : never;
 }>;
-/** Configuration object used to create a slice. */
+/** Configuration used to create a slice definition. */
 type sliceOptions<S extends Obj, R extends Mutations<S, C>, M, C> = {
-    /** Unique slice identifier. */
+    /** Unique name of the slice. */
     name: string;
-    /** Initial state object or lazy state initializer. */
-    state: S | (() => S);
-    /** Collection of synchronous state transition functions. */
-    mutations?: R & ThisType<GlobalUtils>;
-    /** Collection of slice methods and orchestration logic. */
-    methods?: M & ThisType<slice<S, R, M, C> & {
-        root: RootStore;
-    }>;
-    /** Collection of derived state functions. */ /** Collection of nested child slices. */
+    /**
+     * Initial state of the slice.
+     *
+     * May be an object or a lazy initializer returning the initial state.
+     *
+     * @example
+     * ```ts
+     * const counter = createSlice({
+     *   name: "counter",
+     *
+     *   state: {
+     *     value: 0,
+     *     loading: false,
+     *   },
+     * });
+     * ```
+     *
+     * @example
+     * ```ts
+     * const counter = createSlice({
+     *   name: "counter",
+     *
+     *   state: () => ({
+     *     value: computeInitialValue(),
+     *     loading: false,
+     *   }),
+     * });
+     * ```
+     *
+     * @example
+     * Runtime usage
+     * ```ts
+     * counter.getState(); // current reactive snapshot
+     * counter.useSelect((state) => state.value); // React subscription
+     * counter.getInitialState(); // initial state only
+     * counter.getInitialState.deep(); // full tree initial state (including children)
+     * ```
+     */
+    state?: S | (() => S);
+    /**
+     * Collection of state mutation functions.
+     *
+     * Each mutation receives an Immer draft of the slice state and is exposed
+     * as a directly callable method on the created slice instance.
+     *
+     * @example
+     * ```ts
+     * mutations: {
+     *   increment(state, amount: number) {
+     *     state.value += amount;
+     *   }
+     * }
+     *
+     * // usage: without dispatch
+     * slice.increment(1);
+     * ```
+     */
+    mutations?: R & ThisType<Utils>;
+    /**
+     * Collection of user-defined instance methods.
+     *
+     * Methods are bound to the slice instance and can access:
+     * state, mutations, children, parent, root, and utils via `this`.
+     *
+     * @example
+     * ```ts
+     * methods: {
+     *   log() {
+     *     console.log(this.getState());
+     *   }
+     * }
+     *
+     * // usage:
+     * slice.log();
+     * ```
+     */
+    methods?: M & ThisType<slice<S, R, M, C>>;
+    /** Collection of derived state functions. */
+    /**
+     * Collection of child slices.
+     *
+     * Each child becomes a mounted runtime node under this slice.
+     *
+     * @example
+     * ```ts
+     * children: {
+     *   products: productsSlice,
+     *   categories: categoriesSlice,
+     * }
+     *
+     * // usage:
+     * shop.products.getState(); // access slice instance
+     * shop.getState().products; // access state subtree
+     * ```
+     */
     children?: C;
 };
-/** Defines the mutations available on a slice. */
-type Mutations<S extends Obj, C> = Dict<(state: SliceState.Draft<S, C>, ...args: any[]) => void | S>;
-/** Derived state shape exposed by a slice, excluding internal framework fields. */
+/**
+ * Collection of functions that update slice state.
+ *
+ * Mutations receive an Immer draft and may either mutate it
+ * directly or return a replacement state.
+ */
+type Mutations<S extends Obj, C> = Dict<(state: SliceState.Draft<S, C>, ...args: any[]) => void | SliceState.Draft<S, C>>;
+/** Utilities for deriving the public and mutable state types associated with a slice. */
 declare namespace SliceState {
-    type InferState<C> = C extends Obj ? (C["getState"] extends () => infer S ? S extends Obj ? S : never : never) : never;
+    type InferState<C> = C extends Obj ? C["getState"] extends () => infer S ? S extends Obj ? S : never : never : never;
     export type State<S extends Obj, C> = ReadOnly<Omit<S, "computed" | keyof OmitNever<{
         [K in keyof C]: InferState<C[K]>;
     }>> & OmitNever<{
@@ -85,58 +380,22 @@ declare namespace SliceState {
     }>;
     export {  };
 }
-/** Reserved slice member names that cannot be overridden by user-defined APIs. */
-type ReservedSliceKeys<R = {}, M = {}> = ("name" | "path" | "computed" | "root" | "parent" | "prototype" | "global" | "getState" | "useSelect") | (keyof R | keyof M);
+/**
+ * Property names reserved by the framework.
+ *
+ * These names cannot be used for mutations,
+ * methods, or child slices.
+ */
+type ReservedSliceKeys<R = {}, M = {}> = ("name" | "path" | "computed" | "root" | "parent" | "prototype" | "utils" | "getState" | "getInitialState" | "useSelect") | (keyof R | keyof M);
 type AnySlice = slice<any, Mutations<any, any>, any, any>;
-
-/** Runtime store API exposed by createStore(...). */
-type store<C> = OmitNever<GlobalUtils & {
-    /** Unique store identifier. Currently this is set to "default" and is nt configurable */
-    readonly name: "default";
-    /** Returns the latest immutable state snapshot. */
-    readonly getState: () => StoreState<C>;
-    /** Subscribes to state changes within React components. Runs with a context-bound `this` containing `global` utilities. */
-    readonly useSelect: <T>(selector: (this: GlobalUtils, state: StoreState<C>, context: GlobalUtils) => T) => T;
-} & {
-    /** Exposed slices. */
-    readonly [K in Exclude<keyof C, ReservedStoreKeys>]: C[K] extends slice<infer S, infer R, infer M, infer C> ? slice<S, R, M, C> : never;
-}>;
-/** Configuration object used to create a store. */
-type storeOptions<C> = {
-    /** Collection of slices. */
-    slices: C;
+type CloneArgs<S extends Obj = any, C = any> = {
+    /** Optional name used when reporting clone validation errors. */
+    name?: string;
+    /** Explicit state to assign to the cloned slice. */
+    object?: Obj;
+    /** Receives the cloned state before initialization, allowing it to be customized. */
+    transform?: (state: SliceState.Draft<S, C>) => void | SliceState.Draft<S, C>;
 };
-/** Derived immutable state shape of the store. */
-type StoreState<C> = ReadOnly<OmitNever<{
-    readonly [K in Exclude<keyof C, ReservedStoreKeys>]: C[K] extends slice<infer S, infer _, infer __, infer C> ? SliceState.State<S, C> : never;
-}>>;
-/** Props accepted by the store provider component. */
-type StoreProviderProps<T = any> = Omit<ProviderProps, "store" | "serverState" | "context"> & {
-    /** The root store instance created with `createStore(...)`. */
-    store: store<T>;
-};
-/** Reserved store member names that cannot be overridden by user-defined APIs. */
-type ReservedStoreKeys<R = {}, M = {}> = ("name" | "computed" | "global" | "getState" | "useSelect") | (keyof R | keyof M);
-
-declare global {
-    namespace OrcheStore {
-        /** User-defined framework type slots. */
-        interface Slots {
-        }
-    }
-}
-/** Resolves a type slot with validation and fallback support. */
-type Definition<T, Rule, Default> = T extends keyof OrcheStore.Slots ? Exclude<OrcheStore.Slots[T], undefined | null> extends Rule ? Exclude<OrcheStore.Slots[T], undefined | null> : Default : Default;
-/** Resolved type for application-wide global utilities. */
-type GlobalUtils = {
-    /** Application-wide global utilities. */
-    global: Definition<"global", Dict, any>;
-};
-/** Resolved type for the application root store. */
-type RootStore = Definition<"root", store<unknown>, any>;
-
-/** Provides an OrcheStore instance to the React component tree. */
-declare function StoreProvider<T>(props: StoreProviderProps<T>): React.JSX.Element;
 
 declare global {
     namespace OrcheStore {
@@ -151,31 +410,404 @@ declare global {
     }
 }
 
-/** Returns the current global utilities object. */
-declare function getGlobalUtils(): GlobalUtils["global"];
-/** Registers or updates application-wide global utilities. */
-declare function provideGlobalUtils(value: Partial<GlobalUtils["global"]>): GlobalUtils["global"];
+/**
+ * Provides an OrcheStore instance to the React component tree.
+ *
+ * The slice hook (`useSelect`) rely on this provider being
+ * present in the component tree.
+ *
+ * @example
+ * ```tsx
+ * import { StoreProvider, createStore } from "orchestore";
+ *
+ * const store = createStore(...);
+ *
+ * export function AppWrapper() {
+ *   return (
+ *     <StoreProvider store={store}>
+ *       <App />
+ *     </StoreProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @internal
+ * Uses React-Redux Provider internally to bind the underlying Redux store
+ * into React context.
+ */
+declare function StoreProvider<T>(props: StoreProviderProps<T>): React.JSX.Element;
+
+/**
+ * Returns the global utilities registry.
+ *
+ * The returned object acts as a shared runtime container for application-wide utilities
+ * such as navigation, notifications, API clients, and other injected services.
+ *
+ * Accessing an unregistered utility will trigger a development warning.
+ */
+declare function getUtils(): Utils["utils"];
+/**
+ * Registers or updates application-wide utilities.
+ *
+ * Utilities are merged into the existing runtime registry and become immediately
+ * available across all slices and store instances.
+ *
+ * This is the core mechanism behind OrcheStore’s global runtime utility system shared across all slices.
+ */
+declare function setUtils(value: Partial<Utils["utils"]>): Utils["utils"];
 
-/** Configures diagnostics output level ("off" | "errors" | "all"). */
-declare function configureDiagnostics(level: "off" | "errors" | "all"): void;
+/**
+ * Configures runtime diagnostic reporting behavior.
+ *
+ * Supports enabling/disabling logs, warnings, and errors globally or individually.
+ */
+declare function setReporting(enabled: boolean): void;
+declare function setReporting(config: {
+    all?: boolean;
+    logs?: boolean;
+    warnings?: boolean;
+    errors?: boolean;
+}): void;
+declare function setReporting(level: "logs" | "warnings" | "errors" | "all", enabled: boolean): void;
 
-/** Creates and initializes an OrcheStore slice. */
+/**
+ * Creates and initializes a slice runtime instance.
+ *
+ * This function constructs a fully functional OrcheStore slice,
+ * including state, mutations, methods, and nested children.
+ *
+ * @example
+ * ```tsx
+ * import { createStore, createSlice } from "orchestore";
+ *
+ * const counterSlice = createSlice({
+ *   name: "counter",
+ *
+ *   state: { value: 0 },
+ *
+ *   mutations: {
+ *     increment(state, amount: number = 1) {
+ *       state.value += amount;
+ *     },
+ *   },
+ *
+ *   methods: {
+ *     async incrementAfter(amount: number, delay: number) {
+ *       await new Promise((resolve) => setTimeout(resolve, delay));
+ *       this.increment(amount);
+ *     },
+ *   },
+ * });
+ *
+ * // Create store tree
+ * const store = createStore({
+ *   slices: {
+ *     counter: counterSlice,
+ *   },
+ * });
+ *
+ * // Direct usage
+ * counterSlice.increment(12);
+ * store.counter.increment(1);
+ * store.counter.getState(); // { value: 13 }
+ *
+ * // React usage
+ * function App() {
+ *   const count = store.counter.useSelect((state) => state.value);
+ *
+ *   return (
+ *     <>
+ *       <div>Counter {count}</div>
+ *
+ *       <button onClick={() => store.counter.increment(1)}>
+ *         Increment
+ *       </button>
+ *
+ *       <button onClick={() => store.counter.incrementAfter(1, 1000)}>
+ *         Increment after 1 second
+ *       </button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @internal
+ * Integrates Redux Toolkit, builds reducers, and wires runtime context.
+ *
+ * @prerelease
+ * Calling this function will print a pre-release message in the console.
+ * This behavior will be removed in the first stable release.
+ */
 declare const createSliceWrapper: <S extends Obj, R extends Mutations<S, C>, M, C>(props: sliceOptions<S, R, M, C>) => slice<S, R, M, C>;
-/** Creates and initializes an OrcheStore instance. */
+/**
+ * Creates and initializes an OrcheStore root instance.
+ *
+ * This function sets up the application-wide store tree,
+ * mounts all slices, and connects the runtime to Redux Toolkit.
+ *
+ * The resulting store becomes the central access point for:
+ * - slice instances and their mutations
+ * - global state inspection
+ * - React subscriptions via `useSelect`
+ * - runtime utilities via `utils`
+ *
+ * @example
+ * ```tsx
+ * import { createStore, createSlice } from "orchestore";
+ *
+ * const counterSlice = createSlice({
+ *   name: "counter",
+ *
+ *   state: { value: 0 },
+ *
+ *   mutations: {
+ *     increment(state, amount: number = 1) {
+ *       state.value += amount;
+ *     },
+ *   },
+ *
+ *   methods: {
+ *     async incrementAfter(amount: number, delay: number) {
+ *       await new Promise((r) => setTimeout(r, delay));
+ *       this.increment(amount);
+ *     },
+ *   },
+ * });
+ *
+ * const store = createStore({
+ *   slices: {
+ *     counter: counterSlice,
+ *   },
+ * });
+ *
+ * // Direct access
+ * counterSlice.increment(12);
+ * store.counter.increment(1);
+ * store.counter.getState(); // { value: 13 }
+ *
+ * // React usage
+ * function App() {
+ *   const value = store.counter.useSelect((state) => state.value);
+ *
+ *   return (
+ *     <>
+ *       <div>{value}</div>
+ *
+ *       <button onClick={() => store.counter.increment(1)}>
+ *         Increment
+ *       </button>
+ *
+ *       <button onClick={() => store.counter.incrementAfter(1, 1000)}>
+ *         Increment later
+ *       </button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @internal
+ * Bootstraps Redux Toolkit, mounts slice tree, and initializes runtime store graph.
+ *
+ * @prerelease
+ * Calling this function will print a pre-release message in the console.
+ * This behavior will be removed in the first stable release.
+ */
 declare const createStoreWrapper: <T>(props: storeOptions<T>) => store<T>;
+
 declare const defaultExport: {
-    /** Creates and initializes an OrcheStore instance. */
+    /**
+     * Creates and initializes an OrcheStore root instance.
+     *
+     * This function sets up the application-wide store tree,
+     * mounts all slices, and connects the runtime to Redux Toolkit.
+     *
+     * The resulting store becomes the central access point for:
+     * - slice instances and their mutations
+     * - global state inspection
+     * - React subscriptions via `useSelect`
+     * - runtime utilities via `utils`
+     *
+     * @example
+     * ```tsx
+     * import { createStore, createSlice } from "orchestore";
+     *
+     * const counterSlice = createSlice({
+     *   name: "counter",
+     *
+     *   state: { value: 0 },
+     *
+     *   mutations: {
+     *     increment(state, amount: number = 1) {
+     *       state.value += amount;
+     *     },
+     *   },
+     *
+     *   methods: {
+     *     async incrementAfter(amount: number, delay: number) {
+     *       await new Promise((r) => setTimeout(r, delay));
+     *       this.increment(amount);
+     *     },
+     *   },
+     * });
+     *
+     * const store = createStore({
+     *   slices: {
+     *     counter: counterSlice,
+     *   },
+     * });
+     *
+     * // Direct access
+     * counterSlice.increment(12);
+     * store.counter.increment(1);
+     * store.counter.getState(); // { value: 13 }
+     *
+     * // React usage
+     * function App() {
+     *   const value = store.counter.useSelect((state) => state.value);
+     *
+     *   return (
+     *     <>
+     *       <div>{value}</div>
+     *
+     *       <button onClick={() => store.counter.increment(1)}>
+     *         Increment
+     *       </button>
+     *
+     *       <button onClick={() => store.counter.incrementAfter(1, 1000)}>
+     *         Increment later
+     *       </button>
+     *     </>
+     *   );
+     * }
+     * ```
+     *
+     * @internal
+     * Bootstraps Redux Toolkit, mounts slice tree, and initializes runtime store graph.
+     *
+     * @prerelease
+     * Calling this function will print a pre-release message in the console.
+     * This behavior will be removed in the first stable release.
+     */
     createStore: <T>(props: storeOptions<T>) => store<T>;
-    /** Creates and initializes an OrcheStore slice. */
+    /**
+     * Creates and initializes a slice runtime instance.
+     *
+     * This function constructs a fully functional OrcheStore slice,
+     * including state, mutations, methods, and nested children.
+     *
+     * @example
+     * ```tsx
+     * import { createStore, createSlice } from "orchestore";
+     *
+     * const counterSlice = createSlice({
+     *   name: "counter",
+     *
+     *   state: { value: 0 },
+     *
+     *   mutations: {
+     *     increment(state, amount: number = 1) {
+     *       state.value += amount;
+     *     },
+     *   },
+     *
+     *   methods: {
+     *     async incrementAfter(amount: number, delay: number) {
+     *       await new Promise((resolve) => setTimeout(resolve, delay));
+     *       this.increment(amount);
+     *     },
+     *   },
+     * });
+     *
+     * // Create store tree
+     * const store = createStore({
+     *   slices: {
+     *     counter: counterSlice,
+     *   },
+     * });
+     *
+     * // Direct usage
+     * counterSlice.increment(12);
+     * store.counter.increment(1);
+     * store.counter.getState(); // { value: 13 }
+     *
+     * // React usage
+     * function App() {
+     *   const count = store.counter.useSelect((state) => state.value);
+     *
+     *   return (
+     *     <>
+     *       <div>Counter {count}</div>
+     *
+     *       <button onClick={() => store.counter.increment(1)}>
+     *         Increment
+     *       </button>
+     *
+     *       <button onClick={() => store.counter.incrementAfter(1, 1000)}>
+     *         Increment after 1 second
+     *       </button>
+     *     </>
+     *   );
+     * }
+     * ```
+     *
+     * @internal
+     * Integrates Redux Toolkit, builds reducers, and wires runtime context.
+     *
+     * @prerelease
+     * Calling this function will print a pre-release message in the console.
+     * This behavior will be removed in the first stable release.
+     */
     createSlice: <S extends Obj, R extends Mutations<S, C>, M, C>(props: sliceOptions<S, R, M, C>) => slice<S, R, M, C>;
-    /** Provides an OrcheStore instance to the React component tree. */
+    /**
+     * Provides an OrcheStore instance to the React component tree.
+     *
+     * The slice hook (`useSelect`) rely on this provider being
+     * present in the component tree.
+     *
+     * @example
+     * ```tsx
+     * import { StoreProvider, createStore } from "orchestore";
+     *
+     * const store = createStore(...);
+     *
+     * export function AppWrapper() {
+     *   return (
+     *     <StoreProvider store={store}>
+     *       <App />
+     *     </StoreProvider>
+     *   );
+     * }
+     * ```
+     *
+     * @internal
+     * Uses React-Redux Provider internally to bind the underlying Redux store
+     * into React context.
+     */
     StoreProvider: typeof StoreProvider;
-    /** Registers or updates application-wide global utilities. */
-    provideGlobalUtils: typeof provideGlobalUtils;
-    /** Returns the current global utilities object. */
-    getGlobalUtils: typeof getGlobalUtils;
-    /** Configures diagnostics output level ("off" | "errors" | "all"). */
-    configureDiagnostics: typeof configureDiagnostics;
+    /**
+     * Returns the global utilities registry.
+     *
+     * The returned object acts as a shared runtime container for application-wide utilities
+     * such as navigation, notifications, API clients, and other injected services.
+     *
+     * Accessing an unregistered utility will trigger a development warning.
+     */
+    getUtils: typeof getUtils;
+    /**
+     * Registers or updates application-wide utilities.
+     *
+     * Utilities are merged into the existing runtime registry and become immediately
+     * available across all slices and store instances.
+     *
+     * This is the core mechanism behind OrcheStore’s global runtime utility system shared across all slices.
+     */
+    setUtils: typeof setUtils;
+    /**
+     * Configures runtime diagnostic reporting behavior.
+     *
+     * Supports enabling/disabling logs, warnings, and errors globally or individually.
+     */
+    setReporting: typeof setReporting;
 };
 
-export { type GlobalUtils, type RootStore, type slice as Slice, type sliceOptions as SliceOptions, type store as Store, type storeOptions as StoreOptions, StoreProvider, configureDiagnostics, createSliceWrapper as createSlice, createStoreWrapper as createStore, defaultExport as default, getGlobalUtils, provideGlobalUtils };
+export { type slice as Slice, type sliceOptions as SliceOptions, type store as Store, type storeOptions as StoreOptions, StoreProvider, type Utils, createSliceWrapper as createSlice, createStoreWrapper as createStore, defaultExport as default, getUtils, setReporting, setUtils };