sia-reactor 0.0.16 → 0.0.18

package/README.md

@@ -39,7 +39,7 @@ Read [Chronicles](https://github.com/Tobi007-del/tmg-media-player/blob/main/CHRO
 - **I just need to use this fast**:
 Jump directly to [Getting Started](#getting-started) and [API Reference](#api-reference).
 
-### Concept Snapshot 
+### Quick Overview
 
 `sia-reactor` treats nested data like a programmable evented tree.
 
@@ -52,8 +52,8 @@ Jump directly to [Getting Started](#getting-started) and [API Reference](#api-re
 Semantic split recommendation:
 - `intent`: async/delayed requests.
 - `state`: granted facts.
-- `settings/config`: immediate user prefs.
-- `status`: read-only system facts.
+- `settings/config (custom)`: immediate user prefs.
+- `status (custom)`: read-only system facts.
 
 ```javascript
 import { reactive, intent } from 'sia-reactor';
@@ -137,16 +137,41 @@ state.set("player.volume", (val) => Math.min(val, 100));
 state.on("player.volume", (e) => console.log(e.value));
 
 state.player.volume = 150; // Triggers mediation, clamps to 100, fires listener.
+state.__Reactor__ // Reference to the underlying reactor
 ```
 
 Alternatively, you can instantiate the `Reactor` class directly to keep the API separate from your data:
 ```javascript
 const reactor = new Reactor({ player: { volume: 50 } }, { debug: true, referenceTracking: true });
 reactor.core.player.volume = 100;
-const state = reactive(reactor); // Methods are now attached to the core and returned.
-state.__Reactor__ // Reference to the underlying reactor
 ```
 
+### Core Methods
+
+All methods are available on `Reactor` instances or objects wrapped in `reactive()`.
+
+#### **Mediators (Synchronous Gatekeepers)**
+- **`set(path, callback, options)`**: Intercept memory writes. Return a value to modify it, or return `TERMINATOR` to block the write entirely.
+- **`get(path, callback, options)`**: Intercept and format data during retrieval.
+- **`delete(path, callback, options)`**: Intercept property deletion.
+
+#### **Watchers (Synchronous Observers)**
+- **`watch(path, callback, options)`**: Fires instantly after a mutation. Use strictly for critical internal engine syncing.
+
+#### **Listeners (Asynchronous/Batched UI Observers)**
+- **`on(path, callback, options)`**: Attach DOM-style event listeners. Supports `{ capture: true, depth: 1, once: true, immediate: true }`.
+- **`once(path, callback, options)`**: Fires once and self-destructs.
+- **`off(path, callback, options)`**: Removes a listener.
+
+#### **Lifecycle & Utilities**
+- **`tick(path)`**: Forces a synchronous flush of the batch queue for a specific path.
+- **`stall(task)` / `nostall(task)`**: Manually stall the queue to wait for calculations before rendering.
+- **`cascade(eventOrPayload, objectSafe)`**: Manually trigger deep-object event waves, bypassing strict unchanged-proxy traps. Perfect for dumping massive API payloads into the tree, `objectSafe` merges `value` with `oldValue`.
+- **`snapshot(raw)`**: Generates a strict, structurally-shared, un-proxied clone of the current state tree.
+- **`plugIn(new ReactorPlugin(config))`**: Allows extended behaviour with external logic.
+- **`reset()`**: Clears all records bringing everything back to a clean slate.
+- **`destroy()`**: Last resort destruction, nukes everything by nullifying it's properties for full disposal.
+
 ### Reactor Build Options
 
 These are some core build options accepted by `new Reactor(core, build)` and `reactive(core, build)`.
@@ -181,32 +206,6 @@ const data = reactive({
 });
 ```
 
-### Core Methods
-
-All methods are available on `Reactor` instances or objects wrapped in `reactive()`.
-
-#### **Mediators (Synchronous Gatekeepers)**
-- **`set(path, callback, options)`**: Intercept memory writes. Return a value to modify it, or return `TERMINATOR` to block the write entirely.
-- **`get(path, callback, options)`**: Intercept and format data during retrieval.
-- **`delete(path, callback, options)`**: Intercept property deletion.
-
-#### **Watchers (Synchronous Observers)**
-- **`watch(path, callback, options)`**: Fires instantly after a mutation. Use strictly for critical internal engine syncing.
-
-#### **Listeners (Asynchronous/Batched UI Observers)**
-- **`on(path, callback, options)`**: Attach DOM-style event listeners. Supports `{ capture: true, depth: 1, once: true, immediate: true }`.
-- **`once(path, callback, options)`**: Fires once and self-destructs.
-- **`off(path, callback, options)`**: Removes a listener.
-
-#### **Lifecycle & Utilities**
-- **`tick(path)`**: Forces a synchronous flush of the batch queue for a specific path.
-- **`stall(task)` / `nostall(task)`**: Manually stall the queue to wait for calculations before rendering.
-- **`cascade(eventOrPayload, objectSafe)`**: Manually trigger deep-object event waves, bypassing strict unchanged-proxy traps. Perfect for dumping massive API payloads into the tree, `objectSafe` merges `value` with `oldValue`.
-- **`snapshot(raw)`**: Generates a strict, structurally-shared, un-proxied clone of the current state tree.
-- **`plugIn(new ReactorPlugin(config))`**: Allows extended behaviour with external logic.
-- **`reset()`**: Clears all records bringing everything back to a clean slate.
-- **`destroy()`**: Last resort destruction, nukes everything by nullifying it's properties for full disposal.
-
 ### Plugins: The Extension Port
 
 The `Reactor` is designed to be a lightweight core. Extended capabilities are attached via Plugins. It ships with a suite of built-in plugins for common architectural needs. like a Persist and TimeTravel plugin.
@@ -455,7 +454,7 @@ S.I.A. Reactor synthesizes core concepts from the heavyweights of web and media
 * **Video.js (VJS):** The philosophy of "Intent vs. State" MEDIATION, ensuring UI actions only commit when the underlying engine allows it.
 * **The Browser DOM:** Treating a raw JSON state tree like HTML nodes, complete with deep, path-based event bubbling.
 * **The JavaScript Event Loop:** Utilizing `queueMicrotask` to batch thousands of synchronous state mutations into a single, noiseless render tick.
-* **Vue & MobX:** Leveraging native ES6 Proxies for instant, deep reactivity without forcing clunky `get()` or `set()` wrapper functions.
+* **Vue, MobX & Valtio:** Leveraging native ES6 Proxies for instant, deep reactivity without forcing clunky `get()` or `set()` wrapper functions.
  
 ---
 

package/dist/adapters/react.d.cts

@@ -1,5 +1,5 @@
 import { useLayoutEffect } from 'react';
-import { E as EffectOptions, R as Reactor, l as Reactive, W as WildPaths, o as PathValue } from '../index-jlxXiocy.cjs';
+import { E as EffectOptions, R as Reactor, l as Reactive, W as WildPaths, o as PathValue } from '../index-JdV5I0R3.cjs';
 
 /** Isomorphic layout effect alias (`useLayoutEffect` in browser, `useEffect` otherwise). */
 declare const useISOLayoutEffect: typeof useLayoutEffect;

package/dist/adapters/react.d.ts

@@ -1,5 +1,5 @@
 import { useLayoutEffect } from 'react';
-import { E as EffectOptions, R as Reactor, l as Reactive, W as WildPaths, o as PathValue } from '../index-jlxXiocy.js';
+import { E as EffectOptions, R as Reactor, l as Reactive, W as WildPaths, o as PathValue } from '../index-JdV5I0R3.js';
 
 /** Isomorphic layout effect alias (`useLayoutEffect` in browser, `useEffect` otherwise). */
 declare const useISOLayoutEffect: typeof useLayoutEffect;

package/dist/adapters/vanilla.d.cts

@@ -1,5 +1,5 @@
-import { E as EffectOptions } from '../index-jlxXiocy.cjs';
-export { A as Autotracker, w as withTracker } from '../index-jlxXiocy.cjs';
+import { E as EffectOptions } from '../index-JdV5I0R3.cjs';
+export { A as Autotracker, w as withTracker } from '../index-JdV5I0R3.cjs';
 
 /**
  * Runs a reactive side effect in vanilla JavaScript.

package/dist/adapters/vanilla.d.ts

@@ -1,5 +1,5 @@
-import { E as EffectOptions } from '../index-jlxXiocy.js';
-export { A as Autotracker, w as withTracker } from '../index-jlxXiocy.js';
+import { E as EffectOptions } from '../index-JdV5I0R3.js';
+export { A as Autotracker, w as withTracker } from '../index-JdV5I0R3.js';
 
 /**
  * Runs a reactive side effect in vanilla JavaScript.

package/dist/{index-jlxXiocy.d.cts → index-JdV5I0R3.d.cts}

@@ -21,16 +21,22 @@ type NoTraverse =
   | Inert<unknown>;
 
 /** Dot-path union for traversable keys in `T`. */
-type Paths<T, S extends string = ".", D extends number = RDepth> = [D] extends [0]
+type Paths<T, S extends string = ".", D extends number = RDepth, Seen = never> = [
+  D
+] extends [0]
   ? never // Circuit Breaker Triggered
+  : T extends Seen
+  ? never // Cycle Guard 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, RPrev[D], Seen | T>}`
   : {
       [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, RPrev[D], Seen | T>}`;
     }[keyof T & (string | number)];
 /** Wildcard path (`*`) or concrete dot-path. */
 type WildPaths<T, S extends string = "."> = "*" | Paths<T, S>;
@@ -113,14 +119,16 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
 // --- "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]
+type DeepKeys<T, D extends number = RDepth, Seen = never> = [D] extends [0]
   ? never
+  : T extends Seen
+  ? never // Cycle Guard Triggered
   : T extends NoTraverse
   ? never
   : T extends readonly any[]
-  ? DeepKeys<T[number], RPrev[D]>
+  ? DeepKeys<T[number], RPrev[D], Seen | T>
   : {
-      [K in keyof T & (string | number)]: K | DeepKeys<T[K], RPrev[D]>;
+      [K in keyof T & (string | number)]: K | DeepKeys<T[K], RPrev[D], Seen | T>;
     }[keyof T & (string | number)];
 
 /** Recursive merge result type for `T1` and `T2` up to depth `D{10}`. */
@@ -724,8 +732,8 @@ declare abstract class BaseReactorPlugin<T extends object = any, Config = any, S
     get name(): string;
     protected ac: AbortController;
     readonly signal: AbortSignal;
-    protected rtr: Reactor<T>;
-    protected config: Config extends object ? Reactive<Config> : Config;
+    rtr: Reactor<T>;
+    config: Config extends object ? Reactive<Config> : Config;
     state: State extends object ? Reactive<State> : State;
     constructor(config?: Config, rtr?: Reactor<T>, state?: State);
     /** Entry point called to initialize plugin wiring. */

package/dist/{index-jlxXiocy.d.ts → index-JdV5I0R3.d.ts}

@@ -21,16 +21,22 @@ type NoTraverse =
   | Inert<unknown>;
 
 /** Dot-path union for traversable keys in `T`. */
-type Paths<T, S extends string = ".", D extends number = RDepth> = [D] extends [0]
+type Paths<T, S extends string = ".", D extends number = RDepth, Seen = never> = [
+  D
+] extends [0]
   ? never // Circuit Breaker Triggered
+  : T extends Seen
+  ? never // Cycle Guard 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, RPrev[D], Seen | T>}`
   : {
       [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, RPrev[D], Seen | T>}`;
     }[keyof T & (string | number)];
 /** Wildcard path (`*`) or concrete dot-path. */
 type WildPaths<T, S extends string = "."> = "*" | Paths<T, S>;
@@ -113,14 +119,16 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
 // --- "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]
+type DeepKeys<T, D extends number = RDepth, Seen = never> = [D] extends [0]
   ? never
+  : T extends Seen
+  ? never // Cycle Guard Triggered
   : T extends NoTraverse
   ? never
   : T extends readonly any[]
-  ? DeepKeys<T[number], RPrev[D]>
+  ? DeepKeys<T[number], RPrev[D], Seen | T>
   : {
-      [K in keyof T & (string | number)]: K | DeepKeys<T[K], RPrev[D]>;
+      [K in keyof T & (string | number)]: K | DeepKeys<T[K], RPrev[D], Seen | T>;
     }[keyof T & (string | number)];
 
 /** Recursive merge result type for `T1` and `T2` up to depth `D{10}`. */
@@ -724,8 +732,8 @@ declare abstract class BaseReactorPlugin<T extends object = any, Config = any, S
     get name(): string;
     protected ac: AbortController;
     readonly signal: AbortSignal;
-    protected rtr: Reactor<T>;
-    protected config: Config extends object ? Reactive<Config> : Config;
+    rtr: Reactor<T>;
+    config: Config extends object ? Reactive<Config> : Config;
     state: State extends object ? Reactive<State> : State;
     constructor(config?: Config, rtr?: Reactor<T>, state?: State);
     /** Entry point called to initialize plugin wiring. */

package/dist/index.d.cts

@@ -1 +1 @@
-export { C as CTX, q as ChildPaths, D as DeepKeys, r as DeepMerge, t as DeepPartial, u as DeepRequired, v as Deleter, x as DeleterRecord, y as DirectPayload, z as EVT_OPTS, F as EVT_WARN, E as EffectOptions, G as Getter, H as GetterRecord, I as INDIFFABLE, J as INERTIA, K as Inert, L as Intent, M as Listener, N as ListenerOptions, O as ListenerOptionsTuple, Q as ListenerRecord, S as Live, T as NIL, U as NOOP, V as PathBranch, X as PathBranchValue, Y as PathKey, Z as PathLeaf, o as PathValue, P as Paths, _ as Payload, $ as RAW, a0 as REJECTABLE, a as REvent, a1 as RTR_BATCH, a2 as RTR_LOG, l as Reactive, a3 as ReactivePreferences, R as Reactor, a4 as ReactorBuild, a5 as ReactorEvent, a6 as SSVERSION, a7 as Setter, a8 as SetterRecord, a9 as Stable, aa as State, ab as StrictPathKey, ac as SyncOptions, ad as SyncOptionsTuple, ae as TERMINATOR, af as Target, ag as Unflatten, ah as UnionToIntersection, ai as UpdatePayload, aj as VERSION, ak as Volatile, al as Watcher, am as WatcherRecord, W as WildPaths, an as getRaw, ao as getSnapshotVersion, ap as getVersion, aq as inert, ar as intent, as as isInert, at as isIntent, au as isVolatile, av as live, aw as methods, ax as reactive, ay as stable, az as state, aA as volatile } from './index-jlxXiocy.cjs';
+export { C as CTX, q as ChildPaths, D as DeepKeys, r as DeepMerge, t as DeepPartial, u as DeepRequired, v as Deleter, x as DeleterRecord, y as DirectPayload, z as EVT_OPTS, F as EVT_WARN, E as EffectOptions, G as Getter, H as GetterRecord, I as INDIFFABLE, J as INERTIA, K as Inert, L as Intent, M as Listener, N as ListenerOptions, O as ListenerOptionsTuple, Q as ListenerRecord, S as Live, T as NIL, U as NOOP, V as PathBranch, X as PathBranchValue, Y as PathKey, Z as PathLeaf, o as PathValue, P as Paths, _ as Payload, $ as RAW, a0 as REJECTABLE, a as REvent, a1 as RTR_BATCH, a2 as RTR_LOG, l as Reactive, a3 as ReactivePreferences, R as Reactor, a4 as ReactorBuild, a5 as ReactorEvent, a6 as SSVERSION, a7 as Setter, a8 as SetterRecord, a9 as Stable, aa as State, ab as StrictPathKey, ac as SyncOptions, ad as SyncOptionsTuple, ae as TERMINATOR, af as Target, ag as Unflatten, ah as UnionToIntersection, ai as UpdatePayload, aj as VERSION, ak as Volatile, al as Watcher, am as WatcherRecord, W as WildPaths, an as getRaw, ao as getSnapshotVersion, ap as getVersion, aq as inert, ar as intent, as as isInert, at as isIntent, au as isVolatile, av as live, aw as methods, ax as reactive, ay as stable, az as state, aA as volatile } from './index-JdV5I0R3.cjs';

package/dist/index.d.ts

@@ -1 +1 @@
-export { C as CTX, q as ChildPaths, D as DeepKeys, r as DeepMerge, t as DeepPartial, u as DeepRequired, v as Deleter, x as DeleterRecord, y as DirectPayload, z as EVT_OPTS, F as EVT_WARN, E as EffectOptions, G as Getter, H as GetterRecord, I as INDIFFABLE, J as INERTIA, K as Inert, L as Intent, M as Listener, N as ListenerOptions, O as ListenerOptionsTuple, Q as ListenerRecord, S as Live, T as NIL, U as NOOP, V as PathBranch, X as PathBranchValue, Y as PathKey, Z as PathLeaf, o as PathValue, P as Paths, _ as Payload, $ as RAW, a0 as REJECTABLE, a as REvent, a1 as RTR_BATCH, a2 as RTR_LOG, l as Reactive, a3 as ReactivePreferences, R as Reactor, a4 as ReactorBuild, a5 as ReactorEvent, a6 as SSVERSION, a7 as Setter, a8 as SetterRecord, a9 as Stable, aa as State, ab as StrictPathKey, ac as SyncOptions, ad as SyncOptionsTuple, ae as TERMINATOR, af as Target, ag as Unflatten, ah as UnionToIntersection, ai as UpdatePayload, aj as VERSION, ak as Volatile, al as Watcher, am as WatcherRecord, W as WildPaths, an as getRaw, ao as getSnapshotVersion, ap as getVersion, aq as inert, ar as intent, as as isInert, at as isIntent, au as isVolatile, av as live, aw as methods, ax as reactive, ay as stable, az as state, aA as volatile } from './index-jlxXiocy.js';
+export { C as CTX, q as ChildPaths, D as DeepKeys, r as DeepMerge, t as DeepPartial, u as DeepRequired, v as Deleter, x as DeleterRecord, y as DirectPayload, z as EVT_OPTS, F as EVT_WARN, E as EffectOptions, G as Getter, H as GetterRecord, I as INDIFFABLE, J as INERTIA, K as Inert, L as Intent, M as Listener, N as ListenerOptions, O as ListenerOptionsTuple, Q as ListenerRecord, S as Live, T as NIL, U as NOOP, V as PathBranch, X as PathBranchValue, Y as PathKey, Z as PathLeaf, o as PathValue, P as Paths, _ as Payload, $ as RAW, a0 as REJECTABLE, a as REvent, a1 as RTR_BATCH, a2 as RTR_LOG, l as Reactive, a3 as ReactivePreferences, R as Reactor, a4 as ReactorBuild, a5 as ReactorEvent, a6 as SSVERSION, a7 as Setter, a8 as SetterRecord, a9 as Stable, aa as State, ab as StrictPathKey, ac as SyncOptions, ad as SyncOptionsTuple, ae as TERMINATOR, af as Target, ag as Unflatten, ah as UnionToIntersection, ai as UpdatePayload, aj as VERSION, ak as Volatile, al as Watcher, am as WatcherRecord, W as WildPaths, an as getRaw, ao as getSnapshotVersion, ap as getVersion, aq as inert, ar as intent, as as isInert, at as isIntent, au as isVolatile, av as live, aw as methods, ax as reactive, ay as stable, az as state, aA as volatile } from './index-JdV5I0R3.js';

package/dist/plugins.d.cts

@@ -1,5 +1,5 @@
-import { P as Paths, B as BaseReactorPlugin, R as Reactor, a as REvent } from './index-jlxXiocy.cjs';
-export { b as ReactorPluginConstructor } from './index-jlxXiocy.cjs';
+import { P as Paths, B as BaseReactorPlugin, R as Reactor, a as REvent } from './index-JdV5I0R3.cjs';
+export { b as ReactorPluginConstructor } from './index-JdV5I0R3.cjs';
 
 interface StorageAdapterConfig {
     debug: boolean;

package/dist/plugins.d.ts

@@ -1,5 +1,5 @@
-import { P as Paths, B as BaseReactorPlugin, R as Reactor, a as REvent } from './index-jlxXiocy.js';
-export { b as ReactorPluginConstructor } from './index-jlxXiocy.js';
+import { P as Paths, B as BaseReactorPlugin, R as Reactor, a as REvent } from './index-JdV5I0R3.js';
+export { b as ReactorPluginConstructor } from './index-JdV5I0R3.js';
 
 interface StorageAdapterConfig {
     debug: boolean;

package/dist/utils.d.cts

@@ -1,4 +1,4 @@
-export { c as canHandle, d as deepClone, e as deleteAny, g as getAny, f as getTrailRecords, i as inAny, h as isObj, j as isPOJO, m as mergeObjs, n as nuke, p as parseAnyObj, k as parseEvtOpts, s as setAny } from './index-jlxXiocy.cjs';
+export { c as canHandle, d as deepClone, e as deleteAny, g as getAny, f as getTrailRecords, i as inAny, h as isObj, j as isPOJO, m as mergeObjs, n as nuke, p as parseAnyObj, k as parseEvtOpts, s as setAny } from './index-JdV5I0R3.cjs';
 
 declare function clamp(min: number | undefined, val: number, max?: number): number;
 

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-export { c as canHandle, d as deepClone, e as deleteAny, g as getAny, f as getTrailRecords, i as inAny, h as isObj, j as isPOJO, m as mergeObjs, n as nuke, p as parseAnyObj, k as parseEvtOpts, s as setAny } from './index-jlxXiocy.js';
+export { c as canHandle, d as deepClone, e as deleteAny, g as getAny, f as getTrailRecords, i as inAny, h as isObj, j as isPOJO, m as mergeObjs, n as nuke, p as parseAnyObj, k as parseEvtOpts, s as setAny } from './index-JdV5I0R3.js';
 
 declare function clamp(min: number | undefined, val: number, max?: number): number;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sia-reactor",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "The Programmable Data DOM. A high-performance State Intent Architecture (S.I.A.) Engine with zero-allocation loops, event propagation, and structural sharing.",
   "author": "Oketade Oluwatobiloba <tobioketade007@gmail.com>",
   "license": "MIT",