sia-reactor 0.0.21 → 0.0.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +115 -89
  2. package/dist/{TimeTravelOverlay-DxqJL0Zk.d.ts → TimeTravelOverlay-Dglcwpg-.d.ts} +9 -8
  3. package/dist/{TimeTravelOverlay-CJv-S_Km.d.cts → TimeTravelOverlay-OjklzuCD.d.cts} +9 -8
  4. package/dist/adapters/react.cjs +74 -91
  5. package/dist/adapters/react.d.cts +23 -22
  6. package/dist/adapters/react.d.ts +23 -22
  7. package/dist/adapters/react.js +3 -3
  8. package/dist/adapters/vanilla.cjs +74 -91
  9. package/dist/adapters/vanilla.d.cts +4 -4
  10. package/dist/adapters/vanilla.d.ts +4 -4
  11. package/dist/adapters/vanilla.js +3 -3
  12. package/dist/{chunk-TFLYCXK4.js → chunk-5JNWC7Z4.js} +14 -13
  13. package/dist/{chunk-DP74DVRT.js → chunk-MKL3JUPO.js} +55 -15
  14. package/dist/{chunk-2WBPGSRL.js → chunk-MSTHQVNK.js} +61 -78
  15. package/dist/{index-Oie9hhE8.d.cts → index-m0aAWxhX.d.cts} +330 -218
  16. package/dist/{index-Oie9hhE8.d.ts → index-m0aAWxhX.d.ts} +330 -218
  17. package/dist/index.cjs +69 -89
  18. package/dist/index.d.cts +1 -1
  19. package/dist/index.d.ts +1 -1
  20. package/dist/index.js +2 -4
  21. package/dist/{plugins.cjs → modules.cjs} +464 -195
  22. package/dist/modules.d.cts +52 -0
  23. package/dist/modules.d.ts +52 -0
  24. package/dist/modules.js +619 -0
  25. package/dist/super.d.ts +642 -298
  26. package/dist/super.global.js +481 -210
  27. package/dist/timeTravel-DExvNb04.d.ts +352 -0
  28. package/dist/timeTravel-DctvcHVt.d.cts +352 -0
  29. package/dist/utils.cjs +59 -14
  30. package/dist/utils.d.cts +1 -1
  31. package/dist/utils.d.ts +1 -1
  32. package/dist/utils.js +7 -1
  33. package/package.json +6 -6
  34. package/dist/plugins.d.cts +0 -112
  35. package/dist/plugins.d.ts +0 -112
  36. package/dist/plugins.js +0 -370
  37. package/dist/timeTravel-B1vedDQc.d.ts +0 -76
  38. package/dist/timeTravel-WpgWmKu-.d.cts +0 -76
@@ -20,24 +20,31 @@ type NoTraverse =
20
20
  | AbortSignal
21
21
  | Inert<unknown>;
22
22
 
23
- /** Dot-path union for traversable keys in `T`. */
24
- type Paths<T, S extends string = ".", D extends number = RDepth> = [D] extends [0]
23
+ /** Dot-path union for traversable keys in `T` up to depth `D{11}`. */
24
+ type Paths<T, S extends string = ".", D extends number = MaxDepth> = [D] extends [0]
25
25
  ? never // Circuit Breaker Triggered
26
26
  : T extends NoTraverse
27
27
  ? never
28
28
  : T extends readonly (infer U)[]
29
- ? `${Extract<keyof T, number>}` | `${Extract<keyof T, number>}${S}${Paths<U, S, RPrev[D]>}`
29
+ ? `${Extract<keyof T, number>}` | `${Extract<keyof T, number>}${S}${Paths<U, S, PrevDepth[D]>}`
30
30
  : {
31
31
  [K in keyof T & (string | number)]: T[K] extends Primitive
32
32
  ? `${K}`
33
- : `${K}` | `${K}${S}${Paths<T[K], S, RPrev[D]>}`;
33
+ : `${K}` | `${K}${S}${Paths<T[K], S, PrevDepth[D]>}`;
34
34
  }[keyof T & (string | number)];
35
35
  /** Wildcard path (`*`) or concrete dot-path. */
36
36
  type WildPaths<T, S extends string = "."> = "*" | Paths<T, S>;
37
- /** Child-path expansion for a path (includes descendants). */
38
- type ChildPaths<T, P extends WildPaths<T>, S extends string = "."> = P extends "*"
37
+ /** Child-path expansion for a path up to relative depth `D{x}`. */
38
+ type ChildPaths<
39
+ T,
40
+ P extends WildPaths<T>,
41
+ S extends string = ".",
42
+ D extends number = MaxDepth
43
+ > = P extends "*"
39
44
  ? Paths<T, S>
40
- : P | Extract<Paths<T, S>, `${P}${S}${string}`>;
45
+ : [D] extends [AllDepth] // hardcoded since already at ts deep limits
46
+ ? Extract<Paths<T, S, AddDepth<PathDepth<P, S>, D>>, `${P}${S}${string}`>
47
+ : Extract<Paths<T, S, AddDepth<PathDepth<P, S>, D>>, `${P}${S}${string}`>;
41
48
 
42
49
  /** Leaf key name extracted from a path. */
43
50
  type PathKey<T, P extends string = Paths<T>, S extends string = "."> = P extends "*"
@@ -86,7 +93,16 @@ type UnflattenKey<
86
93
  ? { [P in Head]: UnflattenKey<Tail, V, S> }
87
94
  : { [P in K]: V };
88
95
 
89
- // Helpers
96
+ // --- Helpers ---
97
+
98
+ /** Calculates the depth of a dot-separated path with a max of D{11}. */
99
+ type PathDepth<P extends string, S extends string = ".", D extends number = MaxDepth> = [
100
+ D
101
+ ] extends [0]
102
+ ? 0
103
+ : P extends `${infer _}${S}${infer Rest}`
104
+ ? NextDepth[PathDepth<Rest, S, PrevDepth[D]>]
105
+ : 1;
90
106
 
91
107
  /** Last segment of a path. */
92
108
  type PathLeaf<
@@ -104,34 +120,49 @@ type PathBranch<
104
120
  : Head
105
121
  : never;
106
122
 
123
+ /** Converts a union of types into an intersection of types. */
107
124
  type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
108
125
  k: infer I
109
126
  ) => void
110
127
  ? I
111
128
  : never;
112
129
 
130
+ /** Adds two depths together, respecting the max depth{11}. */
131
+ type AddDepth<A extends number, B extends number> = [B] extends [0]
132
+ ? A
133
+ : [A] extends [MaxDepth]
134
+ ? MaxDepth
135
+ : AddDepth<NextDepth[A], PrevDepth[B]>;
136
+
137
+ /** Subtracts depth B from A, respecting the min depth{0}. */
138
+ type SubtractDepth<A extends number, B extends number> = [B] extends [0]
139
+ ? A
140
+ : [A] extends [0]
141
+ ? 0
142
+ : SubtractDepth<PrevDepth[A], PrevDepth[B]>;
143
+
113
144
  // --- "It's not that deep" WARRIORS ---
114
145
 
115
- /** Deep key union of `T` up to depth `D{10}`. */
116
- type DeepKeys<T, D extends number = RDepth> = [D] extends [0]
146
+ /** Deep key union of `T` up to depth `D{11}`. */
147
+ type DeepKeys<T, D extends number = MaxDepth> = [D] extends [0]
117
148
  ? never
118
149
  : T extends NoTraverse
119
150
  ? never
120
151
  : T extends readonly any[]
121
- ? DeepKeys<T[number], RPrev[D]>
152
+ ? DeepKeys<T[number], PrevDepth[D]>
122
153
  : {
123
- [K in keyof T & (string | number)]: K | DeepKeys<T[K], RPrev[D]>;
154
+ [K in keyof T & (string | number)]: K | DeepKeys<T[K], PrevDepth[D]>;
124
155
  }[keyof T & (string | number)];
125
156
 
126
- /** Recursive merge result type for `T1` and `T2` up to depth `D{10}`. */
127
- type DeepMerge<T1, T2, D extends number = RDepth> = [D] extends [0]
157
+ /** Recursive merge result type for `T1` and `T2` up to depth `D{11}`. */
158
+ type DeepMerge<T1, T2, D extends number = MaxDepth> = [D] extends [0]
128
159
  ? never
129
160
  : T2 extends object
130
161
  ? T1 extends object
131
162
  ? {
132
163
  [K in keyof T1 | keyof T2]: K extends keyof T2
133
164
  ? K extends keyof T1
134
- ? DeepMerge<T1[K], T2[K], RPrev[D]>
165
+ ? DeepMerge<T1[K], T2[K], PrevDepth[D]>
135
166
  : T2[K]
136
167
  : K extends keyof T1
137
168
  ? T1[K]
@@ -140,39 +171,139 @@ type DeepMerge<T1, T2, D extends number = RDepth> = [D] extends [0]
140
171
  : T2
141
172
  : T2;
142
173
 
143
- /** Recursive partial type up to depth `D{10}`. */
144
- type DeepPartial<T, D extends number = RDepth> = [D] extends [0]
174
+ /** Recursive partial type up to depth `D{11}`. */
175
+ type DeepPartial<T, D extends number = MaxDepth> = [D] extends [0]
145
176
  ? never
146
177
  : T extends Function
147
178
  ? T
148
179
  : T extends Array<infer U>
149
- ? Array<DeepPartial<U, RPrev[D]>>
180
+ ? Array<DeepPartial<U, PrevDepth[D]>>
150
181
  : T extends ReadonlyArray<infer U>
151
- ? ReadonlyArray<DeepPartial<U, RPrev[D]>>
182
+ ? ReadonlyArray<DeepPartial<U, PrevDepth[D]>>
152
183
  : T extends object
153
- ? { [P in keyof T]?: DeepPartial<T[P], RPrev[D]> }
184
+ ? { [P in keyof T]?: DeepPartial<T[P], PrevDepth[D]> }
154
185
  : T;
155
186
 
156
- /** Recursive required type up to depth `D{10}`. */
157
- type DeepRequired<T, D extends number = RDepth> = [D] extends [0]
187
+ /** Recursive required type up to depth `D{11}`. */
188
+ type DeepRequired<T, D extends number = MaxDepth> = [D] extends [0]
158
189
  ? never
159
190
  : T extends Function
160
191
  ? T
161
192
  : T extends Array<infer U>
162
- ? Array<DeepRequired<U, RPrev[D]>>
193
+ ? Array<DeepRequired<U, PrevDepth[D]>>
163
194
  : T extends ReadonlyArray<infer U>
164
- ? ReadonlyArray<DeepRequired<U, RPrev[D]>>
195
+ ? ReadonlyArray<DeepRequired<U, PrevDepth[D]>>
165
196
  : T extends object
166
- ? { [P in keyof T]-?: DeepRequired<T[P], RPrev[D]> }
197
+ ? { [P in keyof T]-?: DeepRequired<T[P], PrevDepth[D]> }
167
198
  : T;
168
199
 
169
200
  // --- RECURSION LIMITERS ---
170
- type RDepth = 10; // current limit for state trees, observed ts max - 19; limit needed cuz of ts bundlers
171
- // This tuple maps a number to the number below it (Index 4 contains 3) allowing `RPrev[D]` to subtract 1 from our depth.
172
- type RPrev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
201
+
202
+ /** Config for defining recursive limits for all parts of the application */
203
+ interface DepthConfig {
204
+ max: 11;
205
+ 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
206
+ prev: [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
207
+ next: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20];
208
+ }
209
+ /** Current recursive depth limit */
210
+ type MaxDepth = DepthConfig["max"];
211
+ type AllDepth = DepthConfig["all"];
212
+ type PrevDepth = DepthConfig["prev"];
213
+ type NextDepth = DepthConfig["next"];
214
+
215
+ /**
216
+ * - Runtime event payload used by Reactor listener waves.
217
+ * - Tracks phase and current path context during propagation, mimics native `Event` API.
218
+ * Exposes intent controls (`resolve`/`reject`), propagation controls, and `composedPath()`.
219
+ * @typeParam T Root state object type.
220
+ * @typeParam P Target path type.
221
+ */
222
+ declare class ReactorEvent<T extends object, P extends WildPaths<T> = WildPaths<T>> {
223
+ /** No active propagation phase. */
224
+ static readonly NONE = 0;
225
+ /** Capture phase: root to target parent. */
226
+ static readonly CAPTURING_PHASE = 1;
227
+ /** Target phase: target listeners run. */
228
+ static readonly AT_TARGET = 2;
229
+ /** Bubble phase: target parent to root. */
230
+ static readonly BUBBLING_PHASE = 3;
231
+ /** Current propagation phase for this event instance. */
232
+ eventPhase: number;
233
+ /** Current event type for the active propagation path, clone immediately if async */
234
+ type: Payload<T, P>["type"];
235
+ /**
236
+ * Current target context for the active propagation path, clone immediately if async.
237
+ * Also use to survive future object shape changes from nesting for a path callback.
238
+ */
239
+ currentTarget: Payload<T, P>["currentTarget"];
240
+ /** Original event type before propagation remapping. */
241
+ readonly staticType: Exclude<Payload<T, P>["type"], "update">;
242
+ /** Original event target context. */
243
+ readonly target: Payload<T, P>["target"];
244
+ /** Root reactive object for this event instance wave. */
245
+ readonly root: Payload<T, P>["root"];
246
+ /** Original target path for this event instance wave. */
247
+ readonly path: Payload<T, P>["target"]["path"];
248
+ /** Current value at the event target path. */
249
+ readonly value: Payload<T, P>["target"]["value"];
250
+ /** Previous value at the event target path. */
251
+ readonly oldValue: Payload<T, P>["target"]["oldValue"];
252
+ /** Whether resolve/reject intent semantics are allowed for this event instance. */
253
+ readonly rejectable: boolean;
254
+ /** Whether this event instance wave can bubble back up to ancestors or just capture down. */
255
+ readonly bubbles: boolean;
256
+ /**
257
+ * `DOMHighResTimeStamp` for this event instance payload for native event parity and accuracy.
258
+ * Enable `eventTimeStamps` option, then use this over custom timestamps in listeners for accuracy.
259
+ * */
260
+ readonly timestamp?: number;
261
+ /** The `Reactor` instance that dispatched this event instance. */
262
+ readonly reactor: Reactor<T>;
263
+ protected _resolved: string;
264
+ protected _rejected: string;
265
+ protected _propagationStopped: boolean;
266
+ protected _immediatePropagationStopped: boolean;
267
+ /**
268
+ * @param payload Source payload for this event instance.
269
+ * @param reactor The `Reactor` instance creating this event instance.
270
+ */
271
+ constructor(payload: Payload<T, P>, reactor: Reactor<T>);
272
+ /** Whether propagation has been stopped. */
273
+ get propagationStopped(): boolean;
274
+ /** Stops propagation to remaining listeners in later nodes/phases. */
275
+ stopPropagation(): void;
276
+ /** Whether immediate propagation has been stopped. */
277
+ get immediatePropagationStopped(): boolean;
278
+ /** Stops propagation immediately, including remaining listeners on current path. */
279
+ stopImmediatePropagation(): void;
280
+ /** Resolution message for rejectable events. */
281
+ get resolved(): string;
282
+ /**
283
+ * Marks a rejectable event as resolved.
284
+ * @param message Optional resolution message or identity.
285
+ * @example e.resolve("html5Tech"); // identity
286
+ * @example e.resolve("API Load successful"); // message
287
+ */
288
+ resolve(message?: string): void;
289
+ /** Rejection reason for rejectable events. */
290
+ get rejected(): string;
291
+ /**
292
+ * Marks a rejectable event as rejected.
293
+ * @param reason Optional rejection reason or identity.
294
+ * @example e.resolve("html5Tech"); // identity
295
+ * @example e.resolve("User is not logged in"); // reason
296
+ */
297
+ reject(reason?: string): void;
298
+ /**
299
+ * Returns event path values from target to root.
300
+ * @returns Composed path values in bubbling order.
301
+ */
302
+ composedPath(): any[];
303
+ }
173
304
 
174
305
  /** Reactor method names exposed on objects returned by {@link reactive}. */
175
- 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"];
306
+ 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"];
176
307
  type Method = (typeof methods)[number];
177
308
  type Prefix<P extends ReactivePreferences | undefined> = P extends {
178
309
  prefix?: infer X extends string;
@@ -202,14 +333,14 @@ type Reactive<T extends object, P extends ReactivePreferences | undefined = unde
202
333
  __Reactor__: Reactor<T>;
203
334
  };
204
335
  /**
205
- * Attaches Reactor APIs to a state object and returns its reactive proxy.
206
- * If an existing `reactive()` return value is passed, it is re-returned ignoring change in preferences.
336
+ * Attaches `Reactor` APIs to a state object and returns its reactive proxy from the reactor's core.
337
+ * If an existing `reactive()` object is passed, it is re-returned ignoring change in preferences.
207
338
  * @param target Source state object or an existing Reactor instance.
208
339
  * @param build Reactor initial configuration.
209
340
  * @param preferences Method naming preferences for exposed APIs.
210
341
  * @returns Reactive object with mapped Reactor methods and `__Reactor__`.
211
342
  * @example
212
- * const state = reactive({ user: { name: "Ada" } });
343
+ * const state = reactive({ user: { name: "Kosi" } });
213
344
  * state.set("user.name", (v) => v);
214
345
  * @example
215
346
  * const rtr = new Reactor({ count: 0 });
@@ -233,7 +364,7 @@ declare function live<T extends object>(target: T): Live<T>;
233
364
  * @param target Object to test.
234
365
  * @returns `true` when inert.
235
366
  */
236
- declare function isInert<T extends object>(target: T): target is Inert<T>;
367
+ declare function isInert<T extends object>(target?: T): target is Inert<T>;
237
368
  /**
238
369
  * Marks an object as intent (rejectable).
239
370
  * @param target Object to mark.
@@ -251,7 +382,7 @@ declare function state<T extends object>(target: T): State<T>;
251
382
  * @param target Object to test.
252
383
  * @returns `true` when marked as intent.
253
384
  */
254
- declare function isIntent<T extends object>(target: T): target is Intent<T>;
385
+ declare function isIntent<T extends object>(target?: T): target is Intent<T>;
255
386
  /**
256
387
  * Marks an object as volatile (indiffable enabled).
257
388
  * @param target Object to mark.
@@ -269,25 +400,25 @@ declare function stable<T extends object>(target: T): Stable<T>;
269
400
  * @param target Object to test.
270
401
  * @returns `true` when marked as volatile.
271
402
  */
272
- declare function isVolatile<T extends object>(target: T): target is Volatile<T>;
403
+ declare function isVolatile<T extends object>(target?: T): target is Volatile<T>;
273
404
  /**
274
405
  * Gets the raw (unproxied) version of an object if it's proxied, otherwise returns the original object.
275
406
  * @param target Object to unwrap.
276
- * @returns Raw object if proxied, else the original object.
407
+ * @returns Raw object if proxied, else the original object. Use `Reactor.snapshot(true)` for deep unwrapping.
277
408
  */
278
- declare function getRaw<T extends object>(target: T): T;
409
+ declare function getRaw<T extends object>(target?: T): T;
279
410
  /**
280
411
  * Gets the current structural version of an object.
281
412
  * @param target Object to inspect.
282
413
  * @returns Version number.
283
414
  */
284
- declare function getVersion<T extends object>(target: T): number;
415
+ declare function getVersion<T extends object>(target?: T): number;
285
416
  /**
286
417
  * Gets the current snapshot-cache version of an object.
287
418
  * @param target Object to inspect.
288
419
  * @returns Snapshot version number.
289
420
  */
290
- declare function getSnapshotVersion<T extends object>(target: T): number;
421
+ declare function getSnapshotVersion<T extends object>(target?: T): number;
291
422
 
292
423
  // ===========================================================================
293
424
  // CORE MARKERS & STATE WRAPPERS
@@ -333,9 +464,9 @@ interface Target<T, P extends WildPaths<T> = WildPaths<T>> {
333
464
  }
334
465
 
335
466
  /** Runtime payload union for mediated operations and update waves (Creates the IDE magic). */
336
- type Payload<T, P extends WildPaths<T> = WildPaths<T>> =
467
+ type Payload<T, P extends WildPaths<T> = WildPaths<T>, D extends number = MaxDepth> =
337
468
  | DirectPayload<T, P>
338
- | UpdatePayload<T, P>;
469
+ | UpdatePayload<T, P, D>;
339
470
 
340
471
  interface BasePayload<T, P extends WildPaths<T> = WildPaths<T>> {
341
472
  /**
@@ -356,24 +487,32 @@ interface DirectPayload<T, P extends WildPaths<T> = WildPaths<T>> extends BasePa
356
487
  /** Target context for this payload. */
357
488
  target: Target<T, P>;
358
489
  }
359
- interface UpdatePayload<T, P extends WildPaths<T> = WildPaths<T>> extends BasePayload<T, P> {
490
+ interface UpdatePayload<
491
+ T,
492
+ P extends WildPaths<T> = WildPaths<T>,
493
+ D extends number = MaxDepth
494
+ > extends BasePayload<T, P> {
360
495
  /** Type of the operation that triggered this payload, i.e. "update" */
361
496
  type: "update";
362
497
  /** Target context for this payload. */
363
- target: Target<T, ChildPaths<T, P>>; // Target is strictly one of the child paths!
498
+ target: Target<T, ChildPaths<T, P, ".", D>>; // Target is strictly one of the child paths!
364
499
  }
365
500
 
366
501
  /** Event union with payload-aware overrides for `type`, `path`, and value fields (Creates the IDE magic). */
367
- type REvent<T extends object, P extends WildPaths<T> = WildPaths<T>> =
502
+ type REvent<
503
+ T extends object,
504
+ P extends WildPaths<T> = WildPaths<T>,
505
+ D extends number = MaxDepth
506
+ > =
368
507
  | (Omit<ReactorEvent<T, P>, OverrideEvtProp> &
369
508
  DirectPayload<T, P> &
370
- OverrideEvtPart<DirectPayload<T, P>>)
509
+ OverrideEvt<DirectPayload<T, P>>)
371
510
  | (Omit<ReactorEvent<T, P>, OverrideEvtProp> &
372
- UpdatePayload<T, P> &
373
- OverrideEvtPart<UpdatePayload<T, P>>);
511
+ UpdatePayload<T, P, D> &
512
+ OverrideEvt<UpdatePayload<T, P, D>>);
374
513
 
375
514
  type OverrideEvtProp = "type" | "target" | "value" | "oldValue" | "path";
376
- interface OverrideEvtPart<PL extends { target: { path: any; value: any; oldValue?: any } }> {
515
+ interface OverrideEvt<PL extends { target: { path: any; value: any; oldValue?: any } }> {
377
516
  path: PL["target"]["path"];
378
517
  value: PL["target"]["value"];
379
518
  oldValue: PL["target"]["oldValue"];
@@ -409,7 +548,9 @@ type Watcher<T, P extends WildPaths<T> = WildPaths<T>> = (
409
548
  ) => void;
410
549
 
411
550
  /** Listener callback (batched/asynchronous by default). */
412
- type Listener<T, P extends WildPaths<T> = WildPaths<T>> = (event: REvent<T, P>) => void;
551
+ type Listener<T, P extends WildPaths<T> = WildPaths<T>, D extends number = MaxDepth> = (
552
+ event: REvent<T, P, D>
553
+ ) => void;
413
554
 
414
555
  // ===========================================================================
415
556
  // ENGINE RECORDS (Internal Storage)
@@ -417,35 +558,39 @@ type Listener<T, P extends WildPaths<T> = WildPaths<T>> = (event: REvent<T, P>)
417
558
 
418
559
  type GetterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
419
560
  cb: Getter<T, P>;
420
- clup: () => ReturnType<Reactor<T>["noget"]>; // Registration Cleanup
561
+ clup: () => boolean | undefined; // Registration Cleanup
421
562
  sclup?: () => void; // AbortSignal Cleanup
422
563
  } & SyncOptionsTuple;
423
564
 
424
565
  /** Internal registry record for `set` mediators. */
425
566
  type SetterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
426
567
  cb: Setter<T, P>;
427
- clup: () => ReturnType<Reactor<T>["noset"]>;
568
+ clup: () => boolean | undefined;
428
569
  sclup?: () => void;
429
570
  } & SyncOptionsTuple;
430
571
 
431
572
  type DeleterRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
432
573
  cb: Deleter<T, P>;
433
- clup: () => ReturnType<Reactor<T>["nodelete"]>;
574
+ clup: () => boolean | undefined;
434
575
  sclup?: () => void;
435
576
  } & SyncOptionsTuple;
436
577
 
437
578
  type WatcherRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
438
579
  cb: Watcher<T, P>;
439
- clup: () => ReturnType<Reactor<T>["nowatch"]>;
580
+ clup: () => boolean | undefined;
440
581
  sclup?: () => void;
441
582
  } & SyncOptionsTuple;
442
583
 
443
- type ListenerRecord<T extends object, P extends WildPaths<T> = WildPaths<T>> = {
444
- cb: Listener<T, P>;
445
- clup: () => ReturnType<Reactor<T>["off"]>;
584
+ type ListenerRecord<
585
+ T extends object,
586
+ P extends WildPaths<T> = WildPaths<T>,
587
+ D extends number = MaxDepth
588
+ > = {
589
+ cb: Listener<T, P, D>;
590
+ clup: () => boolean | undefined;
446
591
  sclup?: () => void;
447
592
  lDepth?: number; // Listener Depth
448
- } & ListenerOptionsTuple;
593
+ } & ListenerOptionsTuple<D>;
449
594
 
450
595
  // ===========================================================================
451
596
  // CONFIGURATION OPTIONS
@@ -464,19 +609,20 @@ interface SyncOptionsTuple {
464
609
  /** Tuple-form and shorthand boolean for mediator/watch registrations. */
465
610
  type SyncOptions = boolean | SyncOptionsTuple;
466
611
 
467
- interface ListenerOptionsTuple extends Omit<SyncOptionsTuple, "lazy"> {
612
+ interface ListenerOptionsTuple<D extends number = MaxDepth>
613
+ extends Omit<SyncOptionsTuple, "lazy"> {
468
614
  /** Whether to listen on the capture phase against bubble. */
469
615
  capture?: boolean;
470
616
  /** Maximum path nested depth for event propagation, try `1` if listening to an array with nested objects. */
471
- depth?: number;
617
+ depth?: D;
472
618
  }
473
619
  /** Tuple-form and shorthand boolean for listener registrations. */
474
- type ListenerOptions = boolean | ListenerOptionsTuple;
620
+ type ListenerOptions<D extends number = MaxDepth> = boolean | ListenerOptionsTuple<D>;
475
621
 
476
622
  /** Options accepted by adapter effects (`sync: true` -> watch mode else listener mode). */
477
623
  type EffectOptions =
478
- | (SyncOptionsTuple & { sync: true })
479
- | (ListenerOptionsTuple & { sync?: false });
624
+ | (Omit<SyncOptionsTuple, "immediate"> & { sync: true })
625
+ | (Omit<ListenerOptionsTuple, "immediate"> & { sync?: false });
480
626
 
481
627
  /** Reactor bootstrap/build configuration. */
482
628
  interface ReactorBuild<T extends object, P extends Paths<T> = Paths<T>> {
@@ -550,99 +696,7 @@ interface ReactorBuild<T extends object, P extends Paths<T> = Paths<T>> {
550
696
  ) => (string | symbol)[]; // "almighty" mediation
551
697
  } // debating keeping use of the Reflect API opt-in
552
698
 
553
- /**
554
- * Runtime event payload used by Reactor listener waves.
555
- *
556
- * Tracks phase and current path context during propagation, mimics native `Event` API.
557
- * Exposes intent controls (`resolve`/`reject`), propagation controls, and `composedPath()`.
558
- * @typeParam T Root state object type.
559
- * @typeParam P Target path type.
560
- */
561
- declare class ReactorEvent<T extends object, P extends WildPaths<T> = WildPaths<T>> {
562
- /** No active propagation phase. */
563
- static readonly NONE = 0;
564
- /** Capture phase: root to target parent. */
565
- static readonly CAPTURING_PHASE = 1;
566
- /** Target phase: target listeners run. */
567
- static readonly AT_TARGET = 2;
568
- /** Bubble phase: target parent to root. */
569
- static readonly BUBBLING_PHASE = 3;
570
- /** Current propagation phase for this event instance. */
571
- eventPhase: number;
572
- /** Current event type for the active propagation path, clone immediately if async */
573
- type: Payload<T, P>["type"];
574
- /**
575
- * Current target context for the active propagation path, clone immediately if async.
576
- * Also use to survive future object shape changes from nesting for a path callback.
577
- */
578
- currentTarget: Payload<T, P>["currentTarget"];
579
- /** Original event type before propagation remapping. */
580
- readonly staticType: Exclude<Payload<T, P>["type"], "update">;
581
- /** Original event target context. */
582
- readonly target: Payload<T, P>["target"];
583
- /** Root reactive object for this event wave. */
584
- readonly root: Payload<T, P>["root"];
585
- /** Original target path for this event wave. */
586
- readonly path: Payload<T, P>["target"]["path"];
587
- /** Current value at the event target path. */
588
- readonly value: Payload<T, P>["target"]["value"];
589
- /** Previous value at the event target path. */
590
- readonly oldValue: Payload<T, P>["target"]["oldValue"];
591
- /** Whether resolve/reject intent semantics are allowed for this event. */
592
- readonly rejectable: boolean;
593
- /** Whether this event wave can bubble back up to ancestors or just capture down. */
594
- readonly bubbles: boolean;
595
- /**
596
- * `DOMHighResTimeStamp` for this event payload for native event parity and accuracy.
597
- * Enable `eventTimeStamps` option, then use this over custom timestamps in listeners for accuracy.
598
- * */
599
- readonly timestamp?: number;
600
- protected _warn: (...args: any[]) => void;
601
- protected _resolved: string;
602
- protected _rejected: string;
603
- protected _propagationStopped: boolean;
604
- protected _immediatePropagationStopped: boolean;
605
- /**
606
- * @param payload Source payload for this event instance.
607
- * @param bubbles Whether bubbling is enabled for this wave.
608
- * @param canWarn Whether warning output is enabled.
609
- * @param canStamp Whether timestamping is enabled.
610
- */
611
- constructor(payload: Payload<T, P>, bubbles?: boolean, canStamp?: boolean, canWarn?: boolean);
612
- /** Whether propagation has been stopped. */
613
- get propagationStopped(): boolean;
614
- /** Stops propagation to remaining listeners in later nodes/phases. */
615
- stopPropagation(): void;
616
- /** Whether immediate propagation has been stopped. */
617
- get immediatePropagationStopped(): boolean;
618
- /** Stops propagation immediately, including remaining listeners on current path. */
619
- stopImmediatePropagation(): void;
620
- /** Resolution message for rejectable events. */
621
- get resolved(): string;
622
- /**
623
- * Marks a rejectable event as resolved.
624
- * @param message Optional resolution message or identity.
625
- * @example e.resolve("html5Tech"); // identity
626
- * @example e.resolve("API Load successful"); // message
627
- */
628
- resolve(message?: string): void;
629
- /** Rejection reason for rejectable events. */
630
- get rejected(): string;
631
- /**
632
- * Marks a rejectable event as rejected.
633
- * @param reason Optional rejection reason or identity.
634
- * @example e.resolve("html5Tech"); // identity
635
- * @example e.resolve("User is not logged in"); // reason
636
- */
637
- reject(reason?: string): void;
638
- /**
639
- * Returns event path values from target to root.
640
- * @returns Composed path values in bubbling order.
641
- */
642
- composedPath(): any[];
643
- get canWarn(): boolean;
644
- }
645
-
699
+ declare const arrRegex: RegExp;
646
700
  /** Checks if a value type is an object for common use cases. */
647
701
  declare function isObj<T extends object = object>(obj: any, arraycheck?: boolean): obj is T;
648
702
  /** Checks if a value is a "Plain Old Javascript Object". */
@@ -657,57 +711,90 @@ declare function canHandle(obj: any, config?: {
657
711
  /**
658
712
  * Gets a value by path.
659
713
  * @example
660
- * const state = { user: { profile: { name: "Ada" } } };
714
+ * const state = { user: { profile: { name: "Kosi" } } };
661
715
  * const name = getAny(state, "user.profile.name");
662
716
  */
663
717
  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>;
664
718
  /**
665
719
  * Sets a value by path.
666
720
  * @example
667
- * const state = { user: { profile: { name: "Ada" } } };
721
+ * const state = { user: { profile: { name: "Kosi" } } };
668
722
  * setAny(state, "user.profile.name", "Grace");
669
723
  * @example
670
724
  * const state = { users: [] as Array<{ name?: string }> };
671
- * setAny(state, "users[0].name" as any, "Ada");
725
+ * setAny(state, "users[0].name" as any, "Kosi");
672
726
  */
673
727
  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;
674
728
  /**
675
729
  * Deletes a value by path.
676
730
  * @example
677
- * const state = { user: { profile: { name: "Ada" } } };
731
+ * const state = { user: { profile: { name: "Kosi" } } };
678
732
  * deleteAny(state, "user.profile.name");
679
733
  */
680
- declare function deleteAny<T extends object, const S extends string = ".">(target: T, key: WildPaths<T, S>, separator?: S, keyFunc?: (p: string) => string): void;
734
+ 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;
681
735
  /**
682
736
  * Checks whether a path exists.
683
737
  * @example
684
- * const state = { user: { profile: { name: "Ada" } } };
685
- * const ok = inAny(state, "user.profile.name");
738
+ * const state = { user: { profile: { name: "Kosi" } } };
739
+ * const ok = inAny(state, "user.profile.name"); // default loose typing due to it's usecase
686
740
  */
687
- declare function inAny<T extends object, const S extends string = ".">(source: T, key: string | WildPaths<T, S>, separator?: S, keyFunc?: (p: string) => string): boolean;
741
+ 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;
688
742
  /**
689
743
  * Converts flattened keys into nested object structure.
690
744
  * @example
691
- * const flat = { "user.name": "Ada", "user.role": "admin" };
745
+ * const flat = { "user.name": "Kosi", "user.role": "admin" };
692
746
  * const obj = parseAnyObj(flat);
693
747
  */
694
748
  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>;
695
749
  /** Normalizes boolean/object event options into a single options object. */
696
- declare function parseEvtOpts<T extends object>(options: T | boolean | undefined, opts: (keyof T)[] | readonly (keyof T)[], boolOpt?: keyof T, result?: T): T;
750
+ declare function parseEvtOpts<T extends object, const K extends (keyof T)[] | readonly (keyof T)[], const O extends K[number] = K[0]>(options: T | boolean | undefined, opts: K, boolOpt?: O, result?: T): T & {
751
+ [P in O]-?: T[P];
752
+ };
753
+ interface FanoutTuple extends Partial<Record<(typeof fanoutOptsArr)[number], any>> {
754
+ /** Whether to merge values before fanout, useful for patching usecases. */
755
+ merge?: boolean;
756
+ /** How many levels to fan out, set based on your listener paths max dots. `true` is `Infinity`, defaults to `1` for event cascading otherwise `Infinity`. */
757
+ depth?: number | boolean;
758
+ /** Whether to assign arrays as a whole and only touch `.length` for common cases. Only works with the `path` parameter overload or in nested levels.
759
+ * Arrays can lead to unnecessary work as more often than not, you won't be watching index paths but waiting on the parent bubble instead.
760
+ * If you happen to be watching, it might be more optimal to re-set it yourself if it's only a few indexes or just turn set this to `false`. */
761
+ atomic?: boolean;
762
+ }
697
763
  /**
698
- * Deep-merges object-like values.
764
+ * Unified expansion utility.
765
+ * Bridges Coarse (Immutable replacement) writes into Fine-grained (Reactive) writes by surgically
766
+ * expanding a single object write into multiple granular child operations for deep optimal xbubbling.
767
+ * @example
768
+ * // Event Mode (Cascading after-write)
769
+ * rtr.on("user", (e) => fanout(e, { depth: 1 })); // defaults to 1 level deep for events
699
770
  * @example
700
- * const next = mergeObjs({ user: { name: "Ada" } }, { user: { role: "admin" } });
771
+ * // Direct Mode (Patching before-write)
772
+ * fanout(state.user, { session: { id: 1, name: "Kosi", role: "admin" } }, { depth: Infinity }); // default to `Infinity` here
701
773
  */
702
- declare function mergeObjs<T1 extends object, T2 extends object>(o1: T1, o2: T2): DeepMerge<T1, T2>;
703
- declare function mergeObjs<T1 extends object>(o1: T1): T1;
704
- declare function mergeObjs<T2 extends object>(o1: undefined | null, o2: T2): T2;
774
+ declare function fanout<T extends object>(event: ReactorEvent<T> | Payload<T>, options?: {
775
+ crossRealms?: boolean;
776
+ } & FanoutTuple): void;
777
+ declare function fanout<T extends object>(target: T, value: Partial<T>, options?: {
778
+ crossRealms?: boolean;
779
+ } & FanoutTuple): void;
780
+ declare function fanout<T extends object, P extends WildPaths<T> = WildPaths<T>>(state: T, path: P, value: Partial<PathValue<T, P>>, options?: {
781
+ crossRealms?: boolean;
782
+ } & FanoutTuple): void;
783
+ declare const fanoutOptsArr: readonly ["merge", "depth", "atomic"];
784
+ /**
785
+ * Deep-merges object-like values, does necessary checks so use without doubts.
786
+ * @example
787
+ * const next = mergeObjs({ user: { name: "Kosi" } }, { user: { role: "admin" } }); // { ...o1, ...o2 } // o2 over o1 and deep!
788
+ */
789
+ declare function mergeObjs<T1 extends object, T2 extends object>(o1?: T1 | null, o2?: T2 | null, config?: {
790
+ crossRealms?: boolean;
791
+ }, pojocheck?: boolean): DeepMerge<T1, T2>;
705
792
  /** Returns [path, parent, value] records from root to the target path. */
706
793
  declare function getTrailRecords<T extends object>(obj: T, path: WildPaths<T>, reverse?: boolean): [WildPaths<T>, PathBranchValue<T, WildPaths<T>>, PathValue<T, WildPaths<T>>][];
707
794
  /**
708
795
  * Deep-clones supported object structures.
709
796
  * @example
710
- * const cloned = deepClone({ user: { name: "Ada" } });
797
+ * const cloned = deepClone({ user: { name: "Kosi" } });
711
798
  */
712
799
  declare function deepClone<T>(obj: T, config?: {
713
800
  crossRealms?: boolean;
@@ -716,27 +803,57 @@ declare function deepClone<T>(obj: T, config?: {
716
803
  /** Nulls all non-function instance properties across the prototype chain. */
717
804
  declare function nuke(target: any): void;
718
805
 
719
- interface ReactorPluginConstructor<P extends BaseReactorPlugin = BaseReactorPlugin, T extends object = any> {
806
+ type ReactorModuleId = string | number;
807
+ interface ReactorModuleConstructor<P extends BaseReactorModule = BaseReactorModule, T extends object = any> {
720
808
  new (rtr: Reactor<T>, config: any): P;
721
- plugName: string;
809
+ moduleName: string;
722
810
  }
723
- declare abstract class BaseReactorPlugin<T extends object = any, Config = any, State = any> {
724
- static readonly plugName: string;
811
+ /**
812
+ * Base class, extend to create custom reactor modules that can be used with a `Reactor` instance
813
+ * Provides common functionalities like multi-reactor management, configuration handling, and error logging.
814
+ * @typeParam T Root state object type of the reactors this module will manage.
815
+ * @typeParam Config Configuration object type for the module.
816
+ * @typeParam State Optional local state object type for the module.
817
+ */
818
+ declare abstract class BaseReactorModule<T extends object = any, Config = any, State = any> {
819
+ static readonly moduleName: string;
725
820
  get name(): string;
726
821
  protected ac: AbortController;
727
- readonly signal: AbortSignal;
728
- rtr: Reactor<T>;
822
+ protected readonly signal: AbortSignal;
823
+ protected rtrs: Map<ReactorModuleId, Reactor<any>>;
824
+ protected rids: WeakMap<Reactor<any>, ReactorModuleId>;
825
+ protected wired: boolean;
729
826
  config: Config extends object ? Reactive<Config> : Config;
730
827
  readonly state: State extends object ? Reactive<State> : State;
731
828
  constructor(config?: Config, rtr?: Reactor<T>, state?: State);
732
- /** Entry point called to initialize plugin wiring. */
733
- setup(rtr?: Reactor<T>): void;
734
- /** set up listeners/subscriptions and plugin runtime wiring. */
829
+ /**
830
+ * Connect to a `Reactor` instance, allows managing multiple reactors if needed.
831
+ * @param target `Reactor` instance or `reactive()` object to connect to.
832
+ * @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.
833
+ * @returns Current `ReactorModule` instance for fluent chaining.
834
+ * @example
835
+ * const mod = new MyModule().attach(state1).attach(state2); // implicit index-based ids by default, add a .setup() or `Reactor.use()` when ready for init.
836
+ * @example
837
+ * const persist = new PersistModule(config).attach(sessState, "session").attach(adminState, "session.admin"); // don't use "*", causes de-serialization issues.
838
+ */
839
+ attach(target?: Reactor<any> | Reactive<any>, id?: ReactorModuleId): this;
840
+ protected onAttach(_rtr: Reactor<any>, _rid?: ReactorModuleId): void;
841
+ /**
842
+ * Entry point called to initialize module wiring, calls `.attach(target, id)` first, `Reactor.use()` calls this internally.
843
+ * Should run as last in `.attach()` chain or after all desired reactors if using multiple; so wiring is done safely after.
844
+ * @param target `Reactor` instance or `reactive()` object to connect to.
845
+ * @param id Optional id for the reactor, prefer over default implicit index id when managing multiple reactors.
846
+ * @returns Current `ReactorModule` instance for fluent chaining.
847
+ * @example
848
+ * const mod = new MyModule().attach(state1).setup(state2); // if using multiple, this should run last; with same params as `.attach()` for a shorter chain
849
+ */
850
+ setup(target?: Reactor<any> | Reactive<any>, id?: ReactorModuleId): this;
851
+ /** set up listeners/subscriptions and module runtime wiring. */
735
852
  abstract wire(): void;
736
853
  destroy(): void;
737
854
  protected onDestroy?(): void;
738
855
  /**
739
- * Wraps a function with plugin-scoped error logging.
856
+ * Wraps a function with module-scoped error logging.
740
857
  * Use this when creating functions dynamically (for example, before attaching an anonymous listener on the fly).
741
858
  * @example
742
859
  * window.addEventListener("resize", this.guard(() => this.syncLayout(true)), { signal: this.signal });
@@ -744,19 +861,23 @@ declare abstract class BaseReactorPlugin<T extends object = any, Config = any, S
744
861
  guard: <Fn extends Function>(fn: Fn) => Fn;
745
862
  }
746
863
 
747
- /** Core S.I.A runtime for path mediation, observation, and event propagation.
748
- * Provides path-level mediators (`get|set|delete`), synchronous watchers (`watch`), and batched listeners (`on`).
749
- * Supports wildcard/path-based subscriptions, optional reference tracking, and plugin-based extensions.
864
+ /**
865
+ * - Core S.I.A runtime for path mediation, observation, and event propagation.
866
+ * - Provides path-level mediators (`get|set|delete`), synchronous watchers (`watch`), and batched listeners (`on`).
867
+ * Supports wildcard/path-based subscriptions, optional reference tracking, and module-based extensions.
750
868
  * @typeParam T Root state object type.
751
869
  */
752
870
  declare class Reactor<T extends object> {
871
+ /** Logger function for this reactor instance, override if desired, `this.canLog = false` resets. */
753
872
  log: (...args: any[]) => void;
873
+ /** The core state object for this reactor instance. */
754
874
  core: T;
755
- plugins?: Map<string, BaseReactorPlugin<T>>;
875
+ /** The modules being used by this reactor. */
876
+ modules?: Set<BaseReactorModule<T>>;
877
+ /** Configuration options for this reactor instance. */
756
878
  config: Omit<ReactorBuild<T>, "debug">;
879
+ /** Whether this reactor instance is currently batching updates, a window view into the engine timing */
757
880
  isBatching: boolean;
758
- isCascading: boolean;
759
- protected isLogging: boolean;
760
881
  protected queue?: Set<() => void>;
761
882
  protected batch?: Map<Paths<T>, Payload<T>>;
762
883
  protected lineage?: WeakMap<object, (object | string)[]>;
@@ -813,7 +934,7 @@ declare class Reactor<T extends object> {
813
934
  */
814
935
  nostall(task: () => any): boolean | undefined;
815
936
  getDepth(path: string, depth?: number): number;
816
- protected getContext<P extends WildPaths<T>>(path: P): Target<T, P>;
937
+ getContext<P extends WildPaths<T>>(path: P): Target<T, P>;
817
938
  protected bindSignal<Cb>(cord: GetterRecord<T> | SetterRecord<T> | DeleterRecord<T> | WatcherRecord<T> | ListenerRecord<T>, sig?: AbortSignal): Cb;
818
939
  protected cloned<O>(target: O, raw: boolean, seen?: WeakMap<WeakKey, any>): O;
819
940
  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 +998,7 @@ declare class Reactor<T extends object> {
877
998
  nodelete<P extends WildPaths<T>>(path: P, callback: Deleter<T, P>): boolean | undefined;
878
999
  /**
879
1000
  * Registers a watcher for a path.
880
- * Watch callbacks run synchronously with the operation.
1001
+ * Watch callbacks run synchronously with the operation, use leaf paths for reliability as it sees exact sets; no bubbling here.
881
1002
  * @param path Path or wildcard path.
882
1003
  * @param callback Watch callback.
883
1004
  * @param options Sync options.
@@ -905,9 +1026,9 @@ declare class Reactor<T extends object> {
905
1026
  * @example
906
1027
  * const cleanup = rtr.on("user.name", (e) => console.log(e.type, e.path));
907
1028
  */
908
- on<P extends WildPaths<T>>(path: P, callback: Listener<T, P>, options?: ListenerOptions): ListenerRecord<T>["clup"];
1029
+ 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"];
909
1030
  /** Registers an event listener for a path that only triggers once. */
910
- once<P extends WildPaths<T>>(path: P, callback: Listener<T, P>, options?: ListenerOptions): ListenerRecord<T>["clup"];
1031
+ 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"];
911
1032
  /**
912
1033
  * Removes an event listener for a path.
913
1034
  * @param path Path or wildcard path.
@@ -919,12 +1040,12 @@ declare class Reactor<T extends object> {
919
1040
  * rtr.on("user.name", cb);
920
1041
  * rtr.off("user.name", cb);
921
1042
  */
922
- off<P extends WildPaths<T>>(path: P, callback: Listener<T, P>, options?: ListenerOptions): boolean | undefined;
1043
+ off<P extends WildPaths<T>, const D extends number = MaxDepth>(path: P, callback: Listener<T, P, D>, options?: ListenerOptions<D>): boolean | undefined;
923
1044
  /**
924
1045
  * Creates a snapshot; possibly clone of state (or a state branch).
925
1046
  * You could alternatively use or serialize your proxied state "as is" except the environment demands no proxies or new references.
926
- * @param raw Use raw (deep unproxied & uncloned) version of branch.
927
- * @param branch Branch to clone.
1047
+ * @param raw Use raw (deep unproxied & uncloned) version of branch, defaults to `true` if `config.smartCloning: false`.
1048
+ * @param branch Specific branch to clone.
928
1049
  * @returns Snapshot deep or smart (structurally shared) clone.
929
1050
  * @example
930
1051
  * const snap = rtr.snapshot();
@@ -934,33 +1055,24 @@ declare class Reactor<T extends object> {
934
1055
  snapshot(raw?: boolean): T;
935
1056
  snapshot<B>(raw?: boolean, branch?: B): B;
936
1057
  /**
937
- * Cascades object updates into direct child paths.
938
- * @param payload Event or payload source.
939
- * @param objectSafe Merge old/new object values before cascading, don't set for arrays; merger doesn't play nice
940
- * @example
941
- * rtr.on("user", (event) => rtr.cascade(event));
942
- * @example
943
- * rtr.watch("user", (_value, payload) => rtr.cascade(payload));
1058
+ * Installs a module instance.
1059
+ * @param target Module instance.
1060
+ * @param id Optional identification tag for this instance in the module.
1061
+ * @returns Current `Reactor` instance for fluent chaining.
944
1062
  */
945
- cascade({ type, currentTarget: { path, value: news, oldValue: olds } }: ReactorEvent<T> | Payload<T>, objectSafe?: boolean): void;
946
- /**
947
- * Installs a plugin instance.
948
- * @param plugin Plugin instance.
949
- * @returns Current reactor for fluent chaining.
950
- */
951
- plugIn(plugin: BaseReactorPlugin<T>): this;
952
- /** Resets the reactor to its initial state. */
1063
+ use(target: BaseReactorModule<T>, id?: ReactorModuleId): this;
1064
+ /** Resets this reactor instance to its initial state. */
953
1065
  reset(): void;
954
1066
  destroy(): void;
955
1067
  get canLog(): boolean;
956
1068
  set canLog(value: boolean);
957
- get canTraceLineage(): boolean | undefined;
1069
+ get canLineageTrace(): boolean | undefined;
958
1070
  get canSmartClone(): boolean | undefined;
959
1071
  }
960
1072
 
961
1073
  /**
962
- * Auto-dependency tracker used to subscribe only to accessed paths.
963
- * `tracked(...)` wraps a snapshot in a read-tracking proxy, and `callback(...)`
1074
+ * - Auto-dependency tracker used to subscribe only to accessed paths.
1075
+ * - `tracked(...)` wraps a snapshot in a read-tracking proxy, and `callback(...)`
964
1076
  * binds subscriptions for collected paths using `watch` (sync) or `on` (batched).
965
1077
  * @typeParam T Root state object type.
966
1078
  */
@@ -1009,9 +1121,9 @@ declare class Autotracker<T extends object> {
1009
1121
  * const stop = atrkr.callback(() => console.log("changed")); // re-run after when ".user.name" changes
1010
1122
  * @example Packaged Customization
1011
1123
  * const atrkr = new Autotracker(); // no reactor passed
1012
- * withTracker(atrkr, () => state.user.name); // import `withTracker` first
1124
+ * withTracker(atrkr, () => state.user.name); // import `withTracker` too
1013
1125
  * 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
1014
- * @example Extensive customization
1126
+ * @example Extensive Customization
1015
1127
  * atrkr.unblock();
1016
1128
  * const prev = CTX.autotracker;
1017
1129
  * CTX.autotracker = atrkr; // import CTX first
@@ -1036,7 +1148,9 @@ declare function withTracker<T>(tracker: Autotracker<any>, run: () => T, rtr?: R
1036
1148
  declare const CTX: {
1037
1149
  /** Flag indicating whether the application is running in development mode. */
1038
1150
  isDevEnv: boolean;
1039
- /** active `Autotracker` instance, override for automatic dependency collection on `Reactor` traps. */
1151
+ /** Flag indicating whether a cascade is currently ongoing so reactors can allow all writes. */
1152
+ isCascading: boolean;
1153
+ /** Active `Autotracker` instance, override for automatic dependency collection on `Reactor` traps. */
1040
1154
  autotracker: Autotracker<any> | null;
1041
1155
  };
1042
1156
  /** Marker to access underlying raw object from a proxy. */
@@ -1057,8 +1171,6 @@ declare const SSVERSION: unique symbol;
1057
1171
  declare const RTR_BATCH: (callback: Function, ...args: any[]) => void;
1058
1172
  /** Default reactor logger prefix function. */
1059
1173
  declare const RTR_LOG: (...args: any[]) => void;
1060
- /** Default event warning logger prefix function. */
1061
- declare const EVT_WARN: (...args: any[]) => void;
1062
1174
  /** Canonical option keys parsed for listener and mediator registrations. */
1063
1175
  declare const EVT_OPTS: {
1064
1176
  readonly LISTENER: readonly ["capture", "depth", "once", "signal", "immediate"];
@@ -1069,4 +1181,4 @@ declare const NIL: any;
1069
1181
  /** Shared no-operation function. */
1070
1182
  declare const NOOP: () => void;
1071
1183
 
1072
- 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 };
1184
+ export { type Live as $, Autotracker as A, BaseReactorModule as B, CTX as C, type DeepKeys as D, type EffectOptions as E, type FanoutTuple as F, type DeepMerge as G, type DeepPartial as H, type Inert as I, type DeepRequired as J, type Deleter as K, type DeleterRecord as L, type DepthConfig as M, type DirectPayload as N, EVT_OPTS as O, type Paths as P, type Getter as Q, Reactor as R, type GetterRecord as S, INDIFFABLE as T, INERTIA as U, type Intent as V, type WildPaths as W, type Listener as X, type ListenerOptions as Y, type ListenerOptionsTuple as Z, type ListenerRecord as _, type REvent as a, type MaxDepth as a0, NIL as a1, NOOP as a2, type NextDepth as a3, type NoTraverse as a4, type PathBranch as a5, type PathBranchValue as a6, type PathDepth as a7, type PathKey as a8, type PathLeaf as a9, type WatcherRecord as aA, getRaw as aB, getSnapshotVersion as aC, getVersion as aD, inert as aE, intent as aF, isInert as aG, isIntent as aH, isVolatile as aI, live as aJ, methods as aK, reactive as aL, stable as aM, state as aN, volatile as aO, type Payload as aa, type PrevDepth as ab, type Primitive as ac, RAW as ad, REJECTABLE as ae, RTR_BATCH as af, RTR_LOG as ag, type ReactivePreferences as ah, ReactorEvent as ai, SSVERSION as aj, type Setter as ak, type SetterRecord as al, type Stable as am, type State as an, type StrictPathKey as ao, type SubtractDepth as ap, type SyncOptions as aq, type SyncOptionsTuple as ar, TERMINATOR as as, type Target as at, type Unflatten as au, type UnionToIntersection as av, type UpdatePayload as aw, VERSION as ax, type Volatile as ay, type Watcher as az, type ReactorModuleConstructor as b, type ReactorModuleId as c, type Reactive as d, arrRegex as e, canHandle as f, deepClone as g, deleteAny as h, fanout as i, fanoutOptsArr as j, getAny as k, getTrailRecords as l, inAny as m, isObj as n, isPOJO as o, mergeObjs as p, nuke as q, parseAnyObj as r, parseEvtOpts as s, setAny as t, type ReactorBuild as u, type PathValue as v, withTracker as w, type AddDepth as x, type AllDepth as y, type ChildPaths as z };