sia-reactor 0.0.21 → 0.0.22

package/dist/{index-Oie9hhE8.d.cts → index-BgbbNXTW.d.cts}

@@ -20,24 +20,31 @@ type NoTraverse =
   | AbortSignal
   | Inert<unknown>;
 
-/** Dot-path union for traversable keys in `T`. */
-type Paths<T, S extends string = ".", D extends number = RDepth> = [D] extends [0]
+/** Dot-path union for traversable keys in `T` up to depth `D{11}`. */
+type Paths<T, S extends string = ".", D extends number = MaxDepth> = [D] extends [0]
   ? never // Circuit Breaker Triggered
   : T extends NoTraverse
   ? never
   : T extends readonly (infer U)[]
-  ? `${Extract<keyof T, number>}` | `${Extract<keyof T, number>}${S}${Paths<U, S, RPrev[D]>}`
+  ? `${Extract<keyof T, number>}` | `${Extract<keyof T, number>}${S}${Paths<U, S, PrevDepth[D]>}`
   : {
       [K in keyof T & (string | number)]: T[K] extends Primitive
         ? `${K}`
-        : `${K}` | `${K}${S}${Paths<T[K], S, RPrev[D]>}`;
+        : `${K}` | `${K}${S}${Paths<T[K], S, PrevDepth[D]>}`;
     }[keyof T & (string | number)];
 /** Wildcard path (`*`) or concrete dot-path. */
 type WildPaths<T, S extends string = "."> = "*" | Paths<T, S>;
-/** Child-path expansion for a path (includes descendants). */
-type ChildPaths<T, P extends WildPaths<T>, S extends string = "."> = P extends "*"
+/** Child-path expansion for a path up to relative depth `D{x}`. */
+type ChildPaths<
+  T,
+  P extends WildPaths<T>,
+  S extends string = ".",
+  D extends number = MaxDepth
+> = P extends "*"
   ? Paths<T, S>
-  : P | Extract<Paths<T, S>, `${P}${S}${string}`>;
+  : [D] extends [AllDepth] // hardcoded since already at ts deep limits
+  ? Extract<Paths<T, S, AddDepth<PathDepth<P, S>, D>>, `${P}${S}${string}`>
+  : Extract<Paths<T, S, AddDepth<PathDepth<P, S>, D>>, `${P}${S}${string}`>;
 
 /** Leaf key name extracted from a path. */
 type PathKey<T, P extends string = Paths<T>, S extends string = "."> = P extends "*"
@@ -86,7 +93,16 @@ type UnflattenKey<
   ? { [P in Head]: UnflattenKey<Tail, V, S> }
   : { [P in K]: V };
 
-// Helpers
+// --- Helpers ---
+
+/** Calculates the depth of a dot-separated path with a max of D{11}. */
+type PathDepth<P extends string, S extends string = ".", D extends number = MaxDepth> = [
+  D
+] extends [0]
+  ? 0
+  : P extends `${infer _}${S}${infer Rest}`
+  ? NextDepth[PathDepth<Rest, S, PrevDepth[D]>]
+  : 1;
 
 /** Last segment of a path. */
 type PathLeaf<
@@ -104,34 +120,49 @@ type PathBranch<
     : Head
   : never;
 
+/** Converts a union of types into an intersection of types. */
 type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
   k: infer I
 ) => void
   ? I
   : never;
 
+/** Adds two depths together, respecting the max depth{11}. */
+type AddDepth<A extends number, B extends number> = [B] extends [0]
+  ? A
+  : [A] extends [MaxDepth]
+  ? MaxDepth
+  : AddDepth<NextDepth[A], PrevDepth[B]>;
+
+/** Subtracts depth B from A, respecting the min depth{0}. */
+type SubtractDepth<A extends number, B extends number> = [B] extends [0]
+  ? A
+  : [A] extends [0]
+  ? 0
+  : SubtractDepth<PrevDepth[A], PrevDepth[B]>;
+
 // --- "It's not that deep" WARRIORS ---
 
-/** Deep key union of `T` up to depth `D{10}`. */
-type DeepKeys<T, D extends number = RDepth> = [D] extends [0]
+/** Deep key union of `T` up to depth `D{11}`. */
+type DeepKeys<T, D extends number = MaxDepth> = [D] extends [0]
   ? never
   : T extends NoTraverse
   ? never
   : T extends readonly any[]
-  ? DeepKeys<T[number], RPrev[D]>
+  ? DeepKeys<T[number], PrevDepth[D]>
   : {
-      [K in keyof T & (string | number)]: K | DeepKeys<T[K], RPrev[D]>;
+      [K in keyof T & (string | number)]: K | DeepKeys<T[K], PrevDepth[D]>;
     }[keyof T & (string | number)];
 
-/** Recursive merge result type for `T1` and `T2` up to depth `D{10}`. */
-type DeepMerge<T1, T2, D extends number = RDepth> = [D] extends [0]
+/** Recursive merge result type for `T1` and `T2` up to depth `D{11}`. */
+type DeepMerge<T1, T2, D extends number = MaxDepth> = [D] extends [0]
   ? never
   : T2 extends object
   ? T1 extends object
     ? {
         [K in keyof T1 | keyof T2]: K extends keyof T2
           ? K extends keyof T1
-            ? DeepMerge<T1[K], T2[K], RPrev[D]>
+            ? DeepMerge<T1[K], T2[K], PrevDepth[D]>
             : T2[K]
           : K extends keyof T1
           ? T1[K]
@@ -140,39 +171,139 @@ type DeepMerge<T1, T2, D extends number = RDepth> = [D] extends [0]
     : T2
   : T2;
 
-/** Recursive partial type up to depth `D{10}`. */
-type DeepPartial<T, D extends number = RDepth> = [D] extends [0]
+/** Recursive partial type up to depth `D{11}`. */
+type DeepPartial<T, D extends number = MaxDepth> = [D] extends [0]
   ? never
   : T extends Function
   ? T
   : T extends Array<infer U>
-  ? Array<DeepPartial<U, RPrev[D]>>
+  ? Array<DeepPartial<U, PrevDepth[D]>>
   : T extends ReadonlyArray<infer U>
-  ? ReadonlyArray<DeepPartial<U, RPrev[D]>>
+  ? ReadonlyArray<DeepPartial<U, PrevDepth[D]>>
   : T extends object
-  ? { [P in keyof T]?: DeepPartial<T[P], RPrev[D]> }
+  ? { [P in keyof T]?: DeepPartial<T[P], PrevDepth[D]> }
   : T;
 
-/** Recursive required type up to depth `D{10}`. */
-type DeepRequired<T, D extends number = RDepth> = [D] extends [0]
+/** Recursive required type up to depth `D{11}`. */
+type DeepRequired<T, D extends number = MaxDepth> = [D] extends [0]
   ? never
   : T extends Function
   ? T
   : T extends Array<infer U>
-  ? Array<DeepRequired<U, RPrev[D]>>
+  ? Array<DeepRequired<U, PrevDepth[D]>>
   : T extends ReadonlyArray<infer U>
-  ? ReadonlyArray<DeepRequired<U, RPrev[D]>>
+  ? ReadonlyArray<DeepRequired<U, PrevDepth[D]>>
   : T extends object
-  ? { [P in keyof T]-?: DeepRequired<T[P], RPrev[D]> }
+  ? { [P in keyof T]-?: DeepRequired<T[P], PrevDepth[D]> }
   : T;
 
 // --- RECURSION LIMITERS ---
-type RDepth = 10; // current limit for state trees, observed ts max - 19; limit needed cuz of ts bundlers
-// This tuple maps a number to the number below it (Index 4 contains 3) allowing `RPrev[D]` to subtract 1 from our depth.
-type RPrev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
+
+/** Config for defining recursive limits for all parts of the application */
+interface DepthConfig {
+  max: 11;
+  all: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19; // observed bundler recursive limit for state trees
+  prev: [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
+  next: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20];
+}
+/** Current recursive depth limit */
+type MaxDepth = DepthConfig["max"];
+type AllDepth = DepthConfig["all"];
+type PrevDepth = DepthConfig["prev"];
+type NextDepth = DepthConfig["next"];
+
+/**
+ * - Runtime event payload used by Reactor listener waves.
+ * - Tracks phase and current path context during propagation, mimics native `Event` API.
+ * Exposes intent controls (`resolve`/`reject`), propagation controls, and `composedPath()`.
+ * @typeParam T Root state object type.
+ * @typeParam P Target path type.
+ */
+declare class ReactorEvent<T extends object, P extends WildPaths<T> = WildPaths<T>> {
+    /** No active propagation phase. */
+    static readonly NONE = 0;
+    /** Capture phase: root to target parent. */
+    static readonly CAPTURING_PHASE = 1;
+    /** Target phase: target listeners run. */
+    static readonly AT_TARGET = 2;
+    /** Bubble phase: target parent to root. */
+    static readonly BUBBLING_PHASE = 3;
+    /** Current propagation phase for this event instance. */
+    eventPhase: number;
+    /** Current event type for the active propagation path, clone immediately if async */
+    type: Payload<T, P>["type"];
+    /**
+     * Current target context for the active propagation path, clone immediately if async.
+     * Also use to survive future object shape changes from nesting for a path callback.
+     */
+    currentTarget: Payload<T, P>["currentTarget"];
+    /** Original event type before propagation remapping. */
+    readonly staticType: Exclude<Payload<T, P>["type"], "update">;
+    /** Original event target context. */
+    readonly target: Payload<T, P>["target"];
+    /** Root reactive object for this event instance wave. */
+    readonly root: Payload<T, P>["root"];
+    /** Original target path for this event instance wave. */
+    readonly path: Payload<T, P>["target"]["path"];
+    /** Current value at the event target path. */
+    readonly value: Payload<T, P>["target"]["value"];
+    /** Previous value at the event target path. */
+    readonly oldValue: Payload<T, P>["target"]["oldValue"];
+    /** Whether resolve/reject intent semantics are allowed for this event instance. */
+    readonly rejectable: boolean;
+    /** Whether this event instance wave can bubble back up to ancestors or just capture down. */
+    readonly bubbles: boolean;
+    /**
+     * `DOMHighResTimeStamp` for this event instance payload for native event parity and accuracy.
+     * Enable `eventTimeStamps` option, then use this over custom timestamps in listeners for accuracy.
+     * */
+    readonly timestamp?: number;
+    /** The `Reactor` instance that dispatched this event instance. */
+    readonly reactor: Reactor<T>;
+    protected _resolved: string;
+    protected _rejected: string;
+    protected _propagationStopped: boolean;
+    protected _immediatePropagationStopped: boolean;
+    /**
+     * @param payload Source payload for this event instance.
+     * @param reactor The `Reactor` instance creating this event instance.
+     */
+    constructor(payload: Payload<T, P>, reactor: Reactor<T>);
+    /** Whether propagation has been stopped. */
+    get propagationStopped(): boolean;
+    /** Stops propagation to remaining listeners in later nodes/phases. */
+    stopPropagation(): void;
+    /** Whether immediate propagation has been stopped. */
+    get immediatePropagationStopped(): boolean;
+    /** Stops propagation immediately, including remaining listeners on current path. */
+    stopImmediatePropagation(): void;
+    /** Resolution message for rejectable events. */
+    get resolved(): string;
+    /**
+     * Marks a rejectable event as resolved.
+     * @param message Optional resolution message or identity.
+     * @example e.resolve("html5Tech"); // identity
+     * @example e.resolve("API Load successful"); // message
+     */
+    resolve(message?: string): void;
+    /** Rejection reason for rejectable events. */
+    get rejected(): string;
+    /**
+     * Marks a rejectable event as rejected.
+     * @param reason Optional rejection reason or identity.
+     * @example e.resolve("html5Tech"); // identity
+     * @example e.resolve("User is not logged in"); // reason
+     */
+    reject(reason?: string): void;
+    /**
+     * Returns event path values from target to root.
+     * @returns Composed path values in bubbling order.
+     */
+    composedPath(): any[];
+}
 
 /** Reactor method names exposed on objects returned by {@link reactive}. */
-declare const methods: readonly ["tick", "stall", "nostall", "get", "gonce", "noget", "set", "sonce", "noset", "delete", "donce", "nodelete", "watch", "wonce", "nowatch", "on", "once", "off", "snapshot", "cascade", "plugIn", "reset", "destroy"];
+declare const methods: readonly ["tick", "stall", "nostall", "get", "gonce", "noget", "set", "sonce", "noset", "delete", "donce", "nodelete", "watch", "wonce", "nowatch", "on", "once", "off", "snapshot", "use", "reset", "destroy"];
 type Method = (typeof methods)[number];
 type Prefix<P extends ReactivePreferences | undefined> = P extends {
     prefix?: infer X extends string;
@@ -202,14 +333,14 @@ type Reactive<T extends object, P extends ReactivePreferences | undefined = unde
     __Reactor__: Reactor<T>;
 };
 /**
- * Attaches Reactor APIs to a state object and returns its reactive proxy.
- * If an existing `reactive()` return value is passed, it is re-returned ignoring change in preferences.
+ * Attaches `Reactor` APIs to a state object and returns its reactive proxy from the reactor's core.
+ * If an existing `reactive()` object is passed, it is re-returned ignoring change in preferences.
  * @param target Source state object or an existing Reactor instance.
  * @param build Reactor initial configuration.
  * @param preferences Method naming preferences for exposed APIs.
  * @returns Reactive object with mapped Reactor methods and `__Reactor__`.
  * @example
- * const state = reactive({ user: { name: "Ada" } });
+ * const state = reactive({ user: { name: "Kosi" } });
  * state.set("user.name", (v) => v);
  * @example
  * const rtr = new Reactor({ count: 0 });
@@ -273,7 +404,7 @@ declare function isVolatile<T extends object>(target: T): target is Volatile<T>;
 /**
  * Gets the raw (unproxied) version of an object if it's proxied, otherwise returns the original object.
  * @param target Object to unwrap.
- * @returns Raw object if proxied, else the original object.
+ * @returns Raw object if proxied, else the original object. Use `Reactor.snapshot(true)` for deep unwrapping.
  */
 declare function getRaw<T extends object>(target: T): T;
 /**
@@ -333,9 +464,9 @@ interface Target<T, P extends WildPaths<T> = WildPaths<T>> {
 }
 
 /** Runtime payload union for mediated operations and update waves (Creates the IDE magic). */
-type Payload<T, P extends WildPaths<T> = WildPaths<T>> =
+type Payload<T, P extends WildPaths<T> = WildPaths<T>, D extends number = MaxDepth> =
   | DirectPayload<T, P>
-  | UpdatePayload<T, P>;
+  | UpdatePayload<T, P, D>;
 
 interface BasePayload<T, P extends WildPaths<T> = WildPaths<T>> {
   /**
@@ -356,24 +487,32 @@ interface DirectPayload<T, P extends WildPaths<T> = WildPaths<T>> extends BasePa
   /** Target context for this payload. */
   target: Target<T, P>;
 }
-interface UpdatePayload<T, P extends WildPaths<T> = WildPaths<T>> extends BasePayload<T, P> {
+interface UpdatePayload<
+  T,
+  P extends WildPaths<T> = WildPaths<T>,
+  D extends number = MaxDepth
+> extends BasePayload<T, P> {
   /** Type of the operation that triggered this payload, i.e. "update" */
   type: "update";
   /** Target context for this payload. */
-  target: Target<T, ChildPaths<T, P>>; // Target is strictly one of the child paths!
+  target: Target<T, ChildPaths<T, P, ".", D>>; // Target is strictly one of the child paths!
 }
 
 /** Event union with payload-aware overrides for `type`, `path`, and value fields (Creates the IDE magic). */
-type REvent<T extends object, P extends WildPaths<T> = WildPaths<T>> =
+type REvent<
+  T extends object,
+  P extends WildPaths<T> = WildPaths<T>,
+  D extends number = MaxDepth
+> =
   | (Omit<ReactorEvent<T, P>, OverrideEvtProp> &
       DirectPayload<T, P> &
-      OverrideEvtPart<DirectPayload<T, P>>)
+      OverrideEvt<DirectPayload<T, P>>)
   | (Omit<ReactorEvent<T, P>, OverrideEvtProp> &
-      UpdatePayload<T, P> &
-      OverrideEvtPart<UpdatePayload<T, P>>);
+      UpdatePayload<T, P, D> &
+      OverrideEvt<UpdatePayload<T, P, D>>);
 
 type OverrideEvtProp = "type" | "target" | "value" | "oldValue" | "path";
-interface OverrideEvtPart<PL extends { target: { path: any; value: any; oldValue?: any } }> {
+interface OverrideEvt<PL extends { target: { path: any; value: any; oldValue?: any } }> {
   path: PL["target"]["path"];
   value: PL["target"]["value"];
   oldValue: PL["target"]["oldValue"];
@@ -409,7 +548,9 @@ type Watcher<T, P extends WildPaths<T> = WildPaths<T>> = (
 ) => void;
 
 /** Listener callback (batched/asynchronous by default). */
-type Listener<T, P extends WildPaths<T> = WildPaths<T>> = (event: REvent<T, P>) => void;
+type Listener<T, P extends WildPaths<T> = WildPaths<T>, D extends number = MaxDepth> = (
+  event: REvent<T, P, D>
+) => void;
 
 // ===========================================================================
 // ENGINE RECORDS (Internal Storage)
@@ -417,35 +558,39 @@ type Listener<T, P extends WildPaths<T> = WildPaths<T>> = (event: REvent<T, P>)
 
 type GetterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
   cb: Getter<T, P>;
-  clup: () => ReturnType<Reactor<T>["noget"]>; // Registration Cleanup
+  clup: () => boolean | undefined; // Registration Cleanup
   sclup?: () => void; // AbortSignal Cleanup
 } & SyncOptionsTuple;
 
 /** Internal registry record for `set` mediators. */
 type SetterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
   cb: Setter<T, P>;
-  clup: () => ReturnType<Reactor<T>["noset"]>;
+  clup: () => boolean | undefined;
   sclup?: () => void;
 } & SyncOptionsTuple;
 
 type DeleterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
   cb: Deleter<T, P>;
-  clup: () => ReturnType<Reactor<T>["nodelete"]>;
+  clup: () => boolean | undefined;
   sclup?: () => void;
 } & SyncOptionsTuple;
 
 type WatcherRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
   cb: Watcher<T, P>;
-  clup: () => ReturnType<Reactor<T>["nowatch"]>;
+  clup: () => boolean | undefined;
   sclup?: () => void;
 } & SyncOptionsTuple;
 
-type ListenerRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
-  cb: Listener<T, P>;
-  clup: () => ReturnType<Reactor<T>["off"]>;
+type ListenerRecord<
+  T extends object,
+  P extends WildPaths<T> = WildPaths<T>,
+  D extends number = MaxDepth
+> = {
+  cb: Listener<T, P, D>;
+  clup: () => boolean | undefined;
   sclup?: () => void;
   lDepth?: number; // Listener Depth
-} & ListenerOptionsTuple;
+} & ListenerOptionsTuple<D>;
 
 // ===========================================================================
 // CONFIGURATION OPTIONS
@@ -464,19 +609,20 @@ interface SyncOptionsTuple {
 /** Tuple-form and shorthand boolean for mediator/watch registrations. */
 type SyncOptions = boolean | SyncOptionsTuple;
 
-interface ListenerOptionsTuple extends Omit<SyncOptionsTuple, "lazy"> {
+interface ListenerOptionsTuple<D extends number = MaxDepth>
+  extends Omit<SyncOptionsTuple, "lazy"> {
   /** Whether to listen on the capture phase against bubble. */
   capture?: boolean;
   /** Maximum path nested depth for event propagation, try `1` if listening to an array with nested objects. */
-  depth?: number;
+  depth?: D;
 }
 /** Tuple-form and shorthand boolean for listener registrations. */
-type ListenerOptions = boolean | ListenerOptionsTuple;
+type ListenerOptions<D extends number = MaxDepth> = boolean | ListenerOptionsTuple<D>;
 
 /** Options accepted by adapter effects (`sync: true` -> watch mode else listener mode). */
 type EffectOptions =
-  | (SyncOptionsTuple & { sync: true })
-  | (ListenerOptionsTuple & { sync?: false });
+  | (Omit<SyncOptionsTuple, "immediate"> & { sync: true })
+  | (Omit<ListenerOptionsTuple, "immediate"> & { sync?: false });
 
 /** Reactor bootstrap/build configuration. */
 interface ReactorBuild<T extends object, P extends Paths<T> = Paths<T>> {
@@ -550,99 +696,6 @@ interface ReactorBuild<T extends object, P extends Paths<T> = Paths<T>> {
   ) => (string | symbol)[]; // "almighty" mediation
 } // debating keeping use of the Reflect API opt-in
 
-/**
- * Runtime event payload used by Reactor listener waves.
- *
- * Tracks phase and current path context during propagation, mimics native `Event` API.
- * Exposes intent controls (`resolve`/`reject`), propagation controls, and `composedPath()`.
- * @typeParam T Root state object type.
- * @typeParam P Target path type.
- */
-declare class ReactorEvent<T extends object, P extends WildPaths<T> = WildPaths<T>> {
-    /** No active propagation phase. */
-    static readonly NONE = 0;
-    /** Capture phase: root to target parent. */
-    static readonly CAPTURING_PHASE = 1;
-    /** Target phase: target listeners run. */
-    static readonly AT_TARGET = 2;
-    /** Bubble phase: target parent to root. */
-    static readonly BUBBLING_PHASE = 3;
-    /** Current propagation phase for this event instance. */
-    eventPhase: number;
-    /** Current event type for the active propagation path, clone immediately if async */
-    type: Payload<T, P>["type"];
-    /**
-     * Current target context for the active propagation path, clone immediately if async.
-     * Also use to survive future object shape changes from nesting for a path callback.
-     */
-    currentTarget: Payload<T, P>["currentTarget"];
-    /** Original event type before propagation remapping. */
-    readonly staticType: Exclude<Payload<T, P>["type"], "update">;
-    /** Original event target context. */
-    readonly target: Payload<T, P>["target"];
-    /** Root reactive object for this event wave. */
-    readonly root: Payload<T, P>["root"];
-    /** Original target path for this event wave. */
-    readonly path: Payload<T, P>["target"]["path"];
-    /** Current value at the event target path. */
-    readonly value: Payload<T, P>["target"]["value"];
-    /** Previous value at the event target path. */
-    readonly oldValue: Payload<T, P>["target"]["oldValue"];
-    /** Whether resolve/reject intent semantics are allowed for this event. */
-    readonly rejectable: boolean;
-    /** Whether this event wave can bubble back up to ancestors or just capture down. */
-    readonly bubbles: boolean;
-    /**
-     * `DOMHighResTimeStamp` for this event payload for native event parity and accuracy.
-     * Enable `eventTimeStamps` option, then use this over custom timestamps in listeners for accuracy.
-     * */
-    readonly timestamp?: number;
-    protected _warn: (...args: any[]) => void;
-    protected _resolved: string;
-    protected _rejected: string;
-    protected _propagationStopped: boolean;
-    protected _immediatePropagationStopped: boolean;
-    /**
-     * @param payload Source payload for this event instance.
-     * @param bubbles Whether bubbling is enabled for this wave.
-     * @param canWarn Whether warning output is enabled.
-     * @param canStamp Whether timestamping is enabled.
-     */
-    constructor(payload: Payload<T, P>, bubbles?: boolean, canStamp?: boolean, canWarn?: boolean);
-    /** Whether propagation has been stopped. */
-    get propagationStopped(): boolean;
-    /** Stops propagation to remaining listeners in later nodes/phases. */
-    stopPropagation(): void;
-    /** Whether immediate propagation has been stopped. */
-    get immediatePropagationStopped(): boolean;
-    /** Stops propagation immediately, including remaining listeners on current path. */
-    stopImmediatePropagation(): void;
-    /** Resolution message for rejectable events. */
-    get resolved(): string;
-    /**
-     * Marks a rejectable event as resolved.
-     * @param message Optional resolution message or identity.
-     * @example e.resolve("html5Tech"); // identity
-     * @example e.resolve("API Load successful"); // message
-     */
-    resolve(message?: string): void;
-    /** Rejection reason for rejectable events. */
-    get rejected(): string;
-    /**
-     * Marks a rejectable event as rejected.
-     * @param reason Optional rejection reason or identity.
-     * @example e.resolve("html5Tech"); // identity
-     * @example e.resolve("User is not logged in"); // reason
-     */
-    reject(reason?: string): void;
-    /**
-     * Returns event path values from target to root.
-     * @returns Composed path values in bubbling order.
-     */
-    composedPath(): any[];
-    get canWarn(): boolean;
-}
-
 /** Checks if a value type is an object for common use cases. */
 declare function isObj<T extends object = object>(obj: any, arraycheck?: boolean): obj is T;
 /** Checks if a value is a "Plain Old Javascript Object". */
@@ -657,47 +710,68 @@ declare function canHandle(obj: any, config?: {
 /**
  * Gets a value by path.
  * @example
- * const state = { user: { profile: { name: "Ada" } } };
+ * const state = { user: { profile: { name: "Kosi" } } };
  * const name = getAny(state, "user.profile.name");
  */
 declare function getAny<T extends object, const S extends string = ".", P extends WildPaths<T, S> = WildPaths<T, S>>(source: T, key: P, separator?: S, keyFunc?: (p: string) => string): PathValue<T, P, S>;
 /**
  * Sets a value by path.
  * @example
- * const state = { user: { profile: { name: "Ada" } } };
+ * const state = { user: { profile: { name: "Kosi" } } };
  * setAny(state, "user.profile.name", "Grace");
  * @example
  * const state = { users: [] as Array<{ name?: string }> };
- * setAny(state, "users[0].name" as any, "Ada");
+ * setAny(state, "users[0].name" as any, "Kosi");
  */
 declare function setAny<T extends object, const S extends string = ".", P extends WildPaths<T, S> = WildPaths<T, S>>(target: T, key: P, value: PathValue<T, P, S>, separator?: S, keyFunc?: (p: string) => string): void;
 /**
  * Deletes a value by path.
  * @example
- * const state = { user: { profile: { name: "Ada" } } };
+ * const state = { user: { profile: { name: "Kosi" } } };
  * deleteAny(state, "user.profile.name");
  */
-declare function deleteAny<T extends object, const S extends string = ".">(target: T, key: WildPaths<T, S>, separator?: S, keyFunc?: (p: string) => string): void;
+declare function deleteAny<T extends object, const S extends string = ".", P extends WildPaths<T, S> = WildPaths<T, S>>(target: T, key: P, separator?: S, keyFunc?: (p: string) => string): void;
 /**
  * Checks whether a path exists.
  * @example
- * const state = { user: { profile: { name: "Ada" } } };
- * const ok = inAny(state, "user.profile.name");
+ * const state = { user: { profile: { name: "Kosi" } } };
+ * const ok = inAny(state, "user.profile.name"); // default loose typing due to it's usecase
  */
-declare function inAny<T extends object, const S extends string = ".">(source: T, key: string | WildPaths<T, S>, separator?: S, keyFunc?: (p: string) => string): boolean;
+declare function inAny<T extends object, const S extends string = ".", P extends string = string>(source: T, key: P, separator?: S, keyFunc?: (p: string) => string): boolean;
 /**
  * Converts flattened keys into nested object structure.
  * @example
- * const flat = { "user.name": "Ada", "user.role": "admin" };
+ * const flat = { "user.name": "Kosi", "user.role": "admin" };
  * const obj = parseAnyObj(flat);
  */
 declare function parseAnyObj<T extends Record<string, any>, const S extends string = ".">(obj: T, separator?: S, keyFunc?: (p: string) => string, seen?: WeakSet<WeakKey>): Unflatten<T, S>;
 /** Normalizes boolean/object event options into a single options object. */
 declare function parseEvtOpts<T extends object>(options: T | boolean | undefined, opts: (keyof T)[] | readonly (keyof T)[], boolOpt?: keyof T, result?: T): T;
+/**
+ * Unified expansion utility.
+ * Bridges Coarse (Immutable replacement) writes into Fine-grained (Reactive) writes by
+ * surgically expanding a single object write into multiple granular child operations.
+ * @example
+ * // Event Mode (Cascading after-write)
+ * rtr.on("user", (e) => fanout(e, { depth: 1 })); // defaults to 1 level deep
+ * @example
+ * // Direct Mode (Patching before-write)
+ * fanout(state, "user", { session: { id: 1, name: "Kosi", role: "admin" } }, { depth: Infinity }); // use this or `true` to fanout all nested keys
+ */
+declare function fanout<T extends object>(event: ReactorEvent<T> | Payload<T>, options?: {
+    merge?: boolean;
+    depth?: number | boolean;
+    crossRealms?: boolean;
+}): void;
+declare function fanout<T extends object>(state: T, path: WildPaths<T>, value: any, options?: {
+    merge?: boolean;
+    depth?: number | boolean;
+    crossRealms?: boolean;
+}): void;
 /**
  * Deep-merges object-like values.
  * @example
- * const next = mergeObjs({ user: { name: "Ada" } }, { user: { role: "admin" } });
+ * const next = mergeObjs({ user: { name: "Kosi" } }, { user: { role: "admin" } });
  */
 declare function mergeObjs<T1 extends object, T2 extends object>(o1: T1, o2: T2): DeepMerge<T1, T2>;
 declare function mergeObjs<T1 extends object>(o1: T1): T1;
@@ -707,7 +781,7 @@ declare function getTrailRecords<T extends object>(obj: T, path: WildPaths<T>, r
 /**
  * Deep-clones supported object structures.
  * @example
- * const cloned = deepClone({ user: { name: "Ada" } });
+ * const cloned = deepClone({ user: { name: "Kosi" } });
  */
 declare function deepClone<T>(obj: T, config?: {
     crossRealms?: boolean;
@@ -716,27 +790,57 @@ declare function deepClone<T>(obj: T, config?: {
 /** Nulls all non-function instance properties across the prototype chain. */
 declare function nuke(target: any): void;
 
-interface ReactorPluginConstructor<P extends BaseReactorPlugin = BaseReactorPlugin, T extends object = any> {
+type ReactorModuleId = string | number;
+interface ReactorModuleConstructor<P extends BaseReactorModule = BaseReactorModule, T extends object = any> {
     new (rtr: Reactor<T>, config: any): P;
-    plugName: string;
+    moduleName: string;
 }
-declare abstract class BaseReactorPlugin<T extends object = any, Config = any, State = any> {
-    static readonly plugName: string;
+/**
+ * Base class, extend to create custom reactor modules that can be used with a `Reactor` instance
+ * Provides common functionalities like multi-reactor management, configuration handling, and error logging.
+ * @typeParam T Root state object type of the reactors this module will manage.
+ * @typeParam Config Configuration object type for the module.
+ * @typeParam State Optional local state object type for the module.
+ */
+declare abstract class BaseReactorModule<T extends object = any, Config = any, State = any> {
+    static readonly moduleName: string;
     get name(): string;
     protected ac: AbortController;
-    readonly signal: AbortSignal;
-    rtr: Reactor<T>;
+    protected readonly signal: AbortSignal;
+    protected rtrs: Map<ReactorModuleId, Reactor<any>>;
+    protected rids: WeakMap<Reactor<any>, ReactorModuleId>;
+    protected wired: boolean;
     config: Config extends object ? Reactive<Config> : Config;
     readonly state: State extends object ? Reactive<State> : State;
     constructor(config?: Config, rtr?: Reactor<T>, state?: State);
-    /** Entry point called to initialize plugin wiring. */
-    setup(rtr?: Reactor<T>): void;
-    /** set up listeners/subscriptions and plugin runtime wiring. */
+    /**
+     * Connect to a `Reactor` instance, allows managing multiple reactors if needed.
+     * @param target `Reactor` instance or `reactive()` object to connect to.
+     * @param id Optional custom id for the reactor, prefer over default implicit index id when managing multiple reactors, supports paths to merge into a single tree.
+     * @returns Current `ReactorModule` instance for fluent chaining.
+     * @example
+     * const mod = new MyModule().attach(state1).attach(state2); // implicit index-based ids by default, add a .setup() or `Reactor.use()` when ready for init.
+     * @example
+     * const persist = new PersistModule(config).attach(sessState, "session").attach(adminState, "session.admin"); // don't use "*", causes de-serialization issues.
+     */
+    attach(target?: Reactor<any> | Reactive<any>, id?: ReactorModuleId): this;
+    protected onAttach(_rtr: Reactor<any>, _rid?: ReactorModuleId): void;
+    /**
+     * Entry point called to initialize module wiring, calls `.attach(target, id)` first, `Reactor.use()` calls this internally.
+     * Should run as last in `.attach()` chain or after all desired reactors if using multiple; so wiring is done safely after.
+     * @param target `Reactor` instance or `reactive()` object to connect to.
+     * @param id Optional id for the reactor, prefer over default implicit index id when managing multiple reactors.
+     * @returns Current `ReactorModule` instance for fluent chaining.
+     * @example
+     * const mod = new MyModule().attach(state1).setup(state2); // if using multiple, this should run last; with same params as `.attach()` for a shorter chain
+     */
+    setup(target?: Reactor<any> | Reactive<any>, id?: ReactorModuleId): this;
+    /** set up listeners/subscriptions and module runtime wiring. */
     abstract wire(): void;
     destroy(): void;
     protected onDestroy?(): void;
     /**
-     * Wraps a function with plugin-scoped error logging.
+     * Wraps a function with module-scoped error logging.
      * Use this when creating functions dynamically (for example, before attaching an anonymous listener on the fly).
      * @example
      * window.addEventListener("resize", this.guard(() => this.syncLayout(true)), { signal: this.signal });
@@ -744,19 +848,23 @@ declare abstract class BaseReactorPlugin<T extends object = any, Config = any, S
     guard: <Fn extends Function>(fn: Fn) => Fn;
 }
 
-/** Core S.I.A runtime for path mediation, observation, and event propagation.
- * Provides path-level mediators (`get|set|delete`), synchronous watchers (`watch`), and batched listeners (`on`).
- * Supports wildcard/path-based subscriptions, optional reference tracking, and plugin-based extensions.
+/**
+ * - Core S.I.A runtime for path mediation, observation, and event propagation.
+ * - Provides path-level mediators (`get|set|delete`), synchronous watchers (`watch`), and batched listeners (`on`).
+ * Supports wildcard/path-based subscriptions, optional reference tracking, and module-based extensions.
  * @typeParam T Root state object type.
  */
 declare class Reactor<T extends object> {
+    /** Logger function for this reactor instance, override if desired, `this.canLog = false` resets. */
     log: (...args: any[]) => void;
+    /** The core state object for this reactor instance. */
     core: T;
-    plugins?: Map<string, BaseReactorPlugin<T>>;
+    /** The modules being used by this reactor. */
+    modules?: Set<BaseReactorModule<T>>;
+    /** Configuration options for this reactor instance. */
     config: Omit<ReactorBuild<T>, "debug">;
+    /** Whether this reactor instance is currently batching updates, a window view into the engine timing */
     isBatching: boolean;
-    isCascading: boolean;
-    protected isLogging: boolean;
     protected queue?: Set<() => void>;
     protected batch?: Map<Paths<T>, Payload<T>>;
     protected lineage?: WeakMap<object, (object | string)[]>;
@@ -813,7 +921,7 @@ declare class Reactor<T extends object> {
      */
     nostall(task: () => any): boolean | undefined;
     getDepth(path: string, depth?: number): number;
-    protected getContext<P extends WildPaths<T>>(path: P): Target<T, P>;
+    getContext<P extends WildPaths<T>>(path: P): Target<T, P>;
     protected bindSignal<Cb>(cord: GetterRecord<T> | SetterRecord<T> | DeleterRecord<T> | WatcherRecord<T> | ListenerRecord<T>, sig?: AbortSignal): Cb;
     protected cloned<O>(target: O, raw: boolean, seen?: WeakMap<WeakKey, any>): O;
     protected syncAdd<P extends WildPaths<T>>(key: "get" | "set" | "delete" | "watch", path: P, cb: any, opts: SyncOptions | undefined, onImmediate?: (immediate: boolean | "auto") => void): () => boolean | undefined;
@@ -877,7 +985,7 @@ declare class Reactor<T extends object> {
     nodelete<P extends WildPaths<T>>(path: P, callback: Deleter<T, P>): boolean | undefined;
     /**
      * Registers a watcher for a path.
-     * Watch callbacks run synchronously with the operation.
+     * Watch callbacks run synchronously with the operation, use leaf paths for reliability as it sees exact sets; no bubbling here.
      * @param path Path or wildcard path.
      * @param callback Watch callback.
      * @param options Sync options.
@@ -905,9 +1013,9 @@ declare class Reactor<T extends object> {
      * @example
      * const cleanup = rtr.on("user.name", (e) => console.log(e.type, e.path));
      */
-    on<P extends WildPaths<T>>(path: P, callback: Listener<T, P>, options?: ListenerOptions): ListenerRecord<T>["clup"];
+    on<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): ListenerRecord<T, P, D>["clup"];
     /** Registers an event listener for a path that only triggers once. */
-    once<P extends WildPaths<T>>(path: P, callback: Listener<T, P>, options?: ListenerOptions): ListenerRecord<T>["clup"];
+    once<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): ListenerRecord<T, P, D>["clup"];
     /**
      * Removes an event listener for a path.
      * @param path Path or wildcard path.
@@ -919,12 +1027,12 @@ declare class Reactor<T extends object> {
      * rtr.on("user.name", cb);
      * rtr.off("user.name", cb);
      */
-    off<P extends WildPaths<T>>(path: P, callback: Listener<T, P>, options?: ListenerOptions): boolean | undefined;
+    off<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): boolean | undefined;
     /**
      * Creates a snapshot; possibly clone of state (or a state branch).
      * You could alternatively use or serialize your proxied state "as is" except the environment demands no proxies or new references.
-     * @param raw Use raw (deep unproxied & uncloned) version of branch.
-     * @param branch Branch to clone.
+     * @param raw Use raw (deep unproxied & uncloned) version of branch, defaults to `true` if `config.smartCloning: false`.
+     * @param branch Specific branch to clone.
      * @returns Snapshot deep or smart (structurally shared) clone.
      * @example
      * const snap = rtr.snapshot();
@@ -934,33 +1042,24 @@ declare class Reactor<T extends object> {
     snapshot(raw?: boolean): T;
     snapshot<B>(raw?: boolean, branch?: B): B;
     /**
-     * Cascades object updates into direct child paths.
-     * @param payload Event or payload source.
-     * @param objectSafe Merge old/new object values before cascading, don't set for arrays; merger doesn't play nice
-     * @example
-     * rtr.on("user", (event) => rtr.cascade(event));
-     * @example
-     * rtr.watch("user", (_value, payload) => rtr.cascade(payload));
+     * Installs a module instance.
+     * @param target Module instance.
+     * @param id Optional identification tag for this instance in the module.
+     * @returns Current `Reactor` instance for fluent chaining.
      */
-    cascade({ type, currentTarget: { path, value: news, oldValue: olds } }: ReactorEvent<T> | Payload<T>, objectSafe?: boolean): void;
-    /**
-     * Installs a plugin instance.
-     * @param plugin Plugin instance.
-     * @returns Current reactor for fluent chaining.
-     */
-    plugIn(plugin: BaseReactorPlugin<T>): this;
-    /** Resets the reactor to its initial state. */
+    use(target: BaseReactorModule<T>, id?: ReactorModuleId): this;
+    /** Resets this reactor instance to its initial state. */
     reset(): void;
     destroy(): void;
     get canLog(): boolean;
     set canLog(value: boolean);
-    get canTraceLineage(): boolean | undefined;
+    get canLineageTrace(): boolean | undefined;
     get canSmartClone(): boolean | undefined;
 }
 
 /**
- * Auto-dependency tracker used to subscribe only to accessed paths.
- * `tracked(...)` wraps a snapshot in a read-tracking proxy, and `callback(...)`
+ * - Auto-dependency tracker used to subscribe only to accessed paths.
+ * - `tracked(...)` wraps a snapshot in a read-tracking proxy, and `callback(...)`
  * binds subscriptions for collected paths using `watch` (sync) or `on` (batched).
  * @typeParam T Root state object type.
  */
@@ -1009,9 +1108,9 @@ declare class Autotracker<T extends object> {
      * const stop = atrkr.callback(() => console.log("changed")); // re-run after when ".user.name" changes
      * @example Packaged Customization
      * const atrkr = new Autotracker(); // no reactor passed
-     * withTracker(atrkr, () => state.user.name); // import `withTracker` first
+     * withTracker(atrkr, () => state.user.name); // import `withTracker` too
      * const stop = atrkr.callback(() => console.log("sync"), { sync: true }); // re-run immediately when ".user.name" changes, works on any path used from any reactor state
-     * @example Extensive customization
+     * @example Extensive Customization
      * atrkr.unblock();
      * const prev = CTX.autotracker;
      * CTX.autotracker = atrkr; // import CTX first
@@ -1036,7 +1135,9 @@ declare function withTracker<T>(tracker: Autotracker<any>, run: () => T, rtr?: R
 declare const CTX: {
     /** Flag indicating whether the application is running in development mode. */
     isDevEnv: boolean;
-    /** active `Autotracker` instance, override for automatic dependency collection on `Reactor` traps. */
+    /** Flag indicating whether a cascade is currently ongoing so reactors can allow all writes. */
+    isCascading: boolean;
+    /** Active `Autotracker` instance, override for automatic dependency collection on `Reactor` traps. */
     autotracker: Autotracker<any> | null;
 };
 /** Marker to access underlying raw object from a proxy. */
@@ -1057,8 +1158,6 @@ declare const SSVERSION: unique symbol;
 declare const RTR_BATCH: (callback: Function, ...args: any[]) => void;
 /** Default reactor logger prefix function. */
 declare const RTR_LOG: (...args: any[]) => void;
-/** Default event warning logger prefix function. */
-declare const EVT_WARN: (...args: any[]) => void;
 /** Canonical option keys parsed for listener and mediator registrations. */
 declare const EVT_OPTS: {
     readonly LISTENER: readonly ["capture", "depth", "once", "signal", "immediate"];
@@ -1069,4 +1168,4 @@ declare const NIL: any;
 /** Shared no-operation function. */
 declare const NOOP: () => void;
 
-export { type PathLeaf as $, Autotracker as A, BaseReactorPlugin as B, CTX as C, type DeepKeys as D, type EffectOptions as E, EVT_OPTS as F, EVT_WARN as G, type Getter as H, type Inert as I, type GetterRecord as J, INDIFFABLE as K, INERTIA as L, type Intent as M, type Listener as N, type ListenerOptions as O, type Paths as P, type ListenerOptionsTuple as Q, type Reactive as R, type ListenerRecord as S, type Live as T, NIL as U, NOOP as V, type WildPaths as W, type NoTraverse as X, type PathBranch as Y, type PathBranchValue as Z, type PathKey as _, type REvent as a, type Payload as a0, type Primitive as a1, RAW as a2, REJECTABLE as a3, RTR_BATCH as a4, RTR_LOG as a5, type ReactivePreferences as a6, ReactorEvent as a7, SSVERSION as a8, type Setter as a9, stable as aA, state as aB, volatile as aC, type SetterRecord as aa, type Stable as ab, type State as ac, type StrictPathKey as ad, type SyncOptions as ae, type SyncOptionsTuple as af, TERMINATOR as ag, type Target as ah, type Unflatten as ai, type UnionToIntersection as aj, type UpdatePayload as ak, VERSION as al, type Volatile as am, type Watcher as an, type WatcherRecord as ao, getRaw as ap, getSnapshotVersion as aq, getVersion as ar, inert as as, intent as at, isInert as au, isIntent as av, isVolatile as aw, live as ax, methods as ay, reactive as az, Reactor as b, type ReactorPluginConstructor as c, canHandle as d, deepClone as e, deleteAny as f, getAny as g, getTrailRecords as h, inAny as i, isObj as j, isPOJO as k, parseEvtOpts as l, mergeObjs as m, nuke as n, type ReactorBuild as o, parseAnyObj as p, type PathValue as q, type ChildPaths as r, setAny as s, type DeepMerge as t, type DeepPartial as u, type DeepRequired as v, withTracker as w, type Deleter as x, type DeleterRecord as y, type DirectPayload as z };
+export { NOOP as $, Autotracker as A, BaseReactorModule as B, CTX as C, type DeepKeys as D, type EffectOptions as E, type DeepRequired as F, type Deleter as G, type DeleterRecord as H, type Inert as I, type DepthConfig as J, type DirectPayload as K, EVT_OPTS as L, type Getter as M, type GetterRecord as N, INDIFFABLE as O, type Paths as P, INERTIA as Q, Reactor as R, type Intent as S, type Listener as T, type ListenerOptions as U, type ListenerOptionsTuple as V, type WildPaths as W, type ListenerRecord as X, type Live as Y, type MaxDepth as Z, NIL as _, type REvent as a, type NextDepth as a0, type NoTraverse as a1, type PathBranch as a2, type PathBranchValue as a3, type PathDepth as a4, type PathKey as a5, type PathLeaf as a6, type Payload as a7, type PrevDepth as a8, type Primitive as a9, getVersion as aA, inert as aB, intent as aC, isInert as aD, isIntent as aE, isVolatile as aF, live as aG, methods as aH, reactive as aI, stable as aJ, state as aK, volatile as aL, RAW as aa, REJECTABLE as ab, RTR_BATCH as ac, RTR_LOG as ad, type ReactivePreferences as ae, ReactorEvent as af, SSVERSION as ag, type Setter as ah, type SetterRecord as ai, type Stable as aj, type State as ak, type StrictPathKey as al, type SubtractDepth as am, type SyncOptions as an, type SyncOptionsTuple as ao, TERMINATOR as ap, type Target as aq, type Unflatten as ar, type UnionToIntersection as as, type UpdatePayload as at, VERSION as au, type Volatile as av, type Watcher as aw, type WatcherRecord as ax, getRaw as ay, getSnapshotVersion as az, type ReactorModuleConstructor as b, type ReactorModuleId as c, type Reactive as d, canHandle as e, deepClone as f, deleteAny as g, fanout as h, getAny as i, getTrailRecords as j, inAny as k, isObj as l, isPOJO as m, mergeObjs as n, nuke as o, parseAnyObj as p, parseEvtOpts as q, type ReactorBuild as r, setAny as s, type PathValue as t, type AddDepth as u, type AllDepth as v, withTracker as w, type ChildPaths as x, type DeepMerge as y, type DeepPartial as z };