sia-reactor 0.0.20 → 0.0.22

package/README.md

@@ -16,7 +16,7 @@
 
 - [sia-reactor](#sia-reactor)
   - [Table of contents](#table-of-contents)
-  - [Reading Paths](#reading-paths)
+  - [Why sia-reactor?](#why-sia-reactor)
   - [Getting Started](#getting-started)
   - [Usage](#usage)
   - [API Reference](#api-reference)
@@ -30,41 +30,45 @@
 
 ---
 
-## Reading Paths
+## Why sia-reactor?
 
-Choose your reading mode:
+Most state libraries react to changes.
 
-- **I want to understand the architecture shift first**:
-Read [Chronicles](https://github.com/Tobi007-del/tmg-media-player/blob/main/CHRONICLES.md) and [Interaction Folklore](https://github.com/Tobi007-del/tmg-media-player/blob/main/FOLKLORE.md), then continue here.
-- **I just need to use this fast**:
-Jump directly to [Getting Started](#getting-started) and [API Reference](#api-reference).
+`sia-reactor` lets you:
 
-### Quick Overview
+- intercept changes BEFORE they happen
+- approve or reject user intent
+- observe changes AFTER they settle
+- treat your state like a programmable event system
 
-`sia-reactor` treats nested data like a programmable evented tree.
-
-- **State** = factual reality.
-- **Intent** = requested reality.
-- **Mediators** (`get|set|delete`) = synchronous gatekeepers.
-- **Watchers** (`watch`) = synchronous post-mutation observers.
-- **Listeners** (`on`) = microtask-batched event observers.
-
-Semantic split recommendation:
-- `intent`: async/delayed requests.
-- `state`: granted facts.
-- `settings/config (custom)`: immediate user prefs.
-- `status (custom)`: read-only system facts.
+```js
+const player = reactive({
+  intent: intent({ playing: false }),
+  state: { playing: false }
+});
 
-```javascript
-import { reactive, intent } from 'sia-reactor';
+// Logic layer (capture phase)
+player.on("intent.playing", (e) => {
+  if (!ready) return e.reject();
+  player.state.playing = true;
+}, { capture: true });
 
-const player = reactive({
-  intent: intent({ playing: false, fullscreen: false }),
-  state: { playing: false, fullscreen: false },
-  settings: { theme: "dark", defaultPlaybackRate: 1 },
-  status: { buffering: false, duration: 120 }
+// UI layer
+player.on("state.playing", (e) => {
+  console.log("Now playing:", e.value);
 });
+
+// User action
+player.intent.playing = true;
 ```
+***"This is the entire system."***
+
+Choose your reading mode:
+
+- **I want to understand the architecture shift first**:
+Read [Chronicles](https://github.com/Tobi007-del/tmg-media-player/blob/main/CHRONICLES.md) and [Interaction Folklore](https://github.com/Tobi007-del/tmg-media-player/blob/main/FOLKLORE.md), then continue here.
+- **I just need to use this fast**:
+Jump directly to [Getting Started](#getting-started) and [API Reference](#api-reference).
 
 ---
 
@@ -84,10 +88,10 @@ pnpm add sia-reactor
 
 ```javascript
 // 1. Core Engine
-import { reactive, Reactor, TERMINATOR } from 'sia-reactor';
+import { reactive, Reactor, TERMINATOR } from "sia-reactor";
 
 // 2. Deep Object Utilities
-import { setAny, getAny, mergeObjs } from 'sia-reactor/utils';
+import { setAny, getAny, mergeObjs } from "sia-reactor/utils";
 ```
 
 ---
@@ -97,12 +101,12 @@ import { setAny, getAny, mergeObjs } from 'sia-reactor/utils';
 ### Modern Bundlers (ESM)
 
 ```javascript
-import { reactive, Reactor } from 'sia-reactor';
-import 'sia-reactor/utils'; // deep object helpers (setAny/getAny/mergeObjs/...)
-import 'sia-reactor/plugins'; // built-in plugins + storage adapters
-import 'sia-reactor/adapters/vanilla'; // Autotracker + effect API + TimeTravelOverlay class
-import 'sia-reactor/adapters/vanilla/time-travel-overlay.css'; // TimeTravelOverlay CSS
-import 'sia-reactor/adapters/react'; // useReactor/useSelector/usePath hooks
+import { reactive, Reactor } from "sia-reactor";
+import "sia-reactor/utils"; // deep object helpers (setAny/getAny/deleteAny/inAny/parseAnyObj/fanout/mergeObjs/deepClone/nuke...)
+import "sia-reactor/modules"; // built-in modules + storage adapters
+import "sia-reactor/adapters/vanilla"; // Autotracker + effect API + TimeTravelOverlay class
+import "sia-reactor/adapters/react"; // useReactor/useSelector/usePath hooks
+import "sia-reactor/styles/time-travel-overlay.css"; // TimeTravelOverlay CSS
 ```
 
 ### CDN / Browser (Global)
@@ -115,7 +119,7 @@ import 'sia-reactor/adapters/react'; // useReactor/useSelector/usePath hooks
   <script>
     const { reactive, Reactor } = window.sia;
     window.sia.utils;
-    window.sia.plugins;
+    window.sia.modules;
     window.sia.adapters.vanilla;    
   </script>
 </body>
@@ -143,8 +147,8 @@ getReactor(state); state.__Reactor__; // Reference to the underlying reactor
 
 Alternatively, you can instantiate the `Reactor` class directly to keep the API from interfering with your data or [try this](#reactive-preferences-method-naming):
 ```javascript
-const reactor = new Reactor({ player: { volume: 50 } }, { debug: true, referenceTracking: true });
-reactor.core.player.volume = 100;
+const reactor = new Reactor({ player: { volume: 50 } }, { debug: true });
+reactor.core.player.volume = 100; // re-assign core if desired
 ```
 
 ### Core Methods
@@ -157,10 +161,10 @@ All methods are available on `Reactor` instances or objects wrapped in `reactive
 - **`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.
+- **`watch(path, callback, options)`**: Fires instantly after a mutation. Use strictly for critical internal engine syncing on leaf paths preferably, sees only direct operations.
 
 #### **Listeners (Asynchronous/Batched UI Observers)**
-- **`on(path, callback, options)`**: Attach DOM-style event listeners. Supports `{ capture: true, depth: 1, once: true, immediate: true }`.
+- **`on(path, callback, options)`**: Attach DOM-style event listeners that respect `depth`. 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.
 
@@ -168,8 +172,7 @@ All methods are available on `Reactor` instances or objects wrapped in `reactive
 - **`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.
 - **`snapshot(raw)`**: Generates a strict, structurally-shared, un-proxied clone of the current state tree.
-- **`cascade(eventOrPayload, objectSafe)`**: Manually trigger direct object values event waves, bypassing strict unchanged-proxy traps, `objectSafe` merges `value` with `oldValue`.
-- **`plugIn(new ReactorPlugin(config))`**: Allows extended behaviour with external logic.
+- **`use(new ReactorModule(config), id)`**: 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, lives on every class.
 
@@ -182,7 +185,7 @@ You can wrap properties in special flags *before* initializing the reactor to di
 - **`volatile(obj)` / `stable(obj)`**: Forces the reactor to fire event waves even if the new value is identical to the old value (bypassing the Proxy's unchanged performance check).
 
 ```javascript
-import { reactive, intent, volatile, inert } from 'sia-reactor';
+import { reactive, intent, volatile, inert } from "sia-reactor";
 
 const data = reactive({
   apiResponse: inert({ heavy: "data" }), // Proxy won't traverse this
@@ -193,26 +196,26 @@ const data = reactive({
 
 ### React Hooks & Effects
 
-The engine provides native React bindings utilizing `useSyncExternalStore` and an internal `Autotracker` for concurrent-safe, surgically precise component re-renders. All hooks natively accept a `Reactor` instance, a `reactive()` proxy, or a plain object (which will be auto-wrapped on the fly).
+The engine provides native React bindings utilizing `useSyncExternalStore` and an internal `Autotracker` for concurrent-safe, surgically precise component re-renders. All hooks natively accept a `Reactor` instance, a `reactive()` proxy, or a plain object (which will be auto-wrapped on the fly). Just import, your editor will reveal more details.
 
 ```javascript
-import { reactive } from 'sia-reactor';
-import { useReactor, useSelector, usePath, effect } from 'sia-reactor/react'; 
+import { reactive } from "sia-reactor";
+import { useReactor, useAnyReactor, useSelector, useAnySelector, usePath, effect } from "sia-reactor/adapters/react"; 
 
-const state = reactive({ user: { name: "Ada", age: 25 }, theme: "dark" });
+const state = reactive({ user: { name: "Kosi", age: 25 }, theme: "dark" });
 
 // 1. The Tracked State (Valtio-style)
 function Profile() {
-  const sameState = useReactor(state); // pass in a normal object for an auto-scoped instance
-  useAnyReactor(); // use this when you just want to use any state from any reactor
+  const sameState = useReactor(state); // `useReactorSnapshot()` if mutable issues arise
+  useAnyReactor(); // when you just want state from any reactor
   // Only re-renders if state.user.name mutates. Completely ignores age and theme!
   return <div>{sameState.user.name + otherState.user.name}</div>;
 } // no snapshots like Valtio, you can read or write to anything
 
 // 2. The Slice Selector (Zustand-style)
 function Theme() {
-  const theme = useSelector(state, (s) => s.theme); // pass in a normal object for an auto-scoped instance
-  const newName = useAnySelector(() => state.user.name + spouseState.user.name); // use this when you just want to derive any state from any reactor
+  const theme = useSelector(state, (s) => s.theme); // `useSelectorSnapshot()` if mutable issues arise
+  const newName = useAnySelector(() => state.user.name + spouseState.user.name); // when you just want to derive any state from any reactor
   return <div>Theme: {theme}</div>;
 }
 
@@ -223,56 +226,59 @@ function AgeObserver() {
 }
 
 // 4. Vanilla Side Effects (Runs anywhere, framework agnostic)
-const stopTracking = effect(() => {
-  console.log("User name changed to:", state.user.name);
-});
+const stopTracking = effect(() => console.log("User name changed to:", state.user.name)); // read or write as you wish
 ```
 
-### Plugins: The Extension Port
+### Modules: 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.
+The `Reactor` is designed to be a lightweight core. Extended capabilities are attached via Modules. It ships with a suite of powerful modules for common architectural needs.
 
-#### The Persistence Plugin
-Automatically syncs your State to LocalStorage, SessionStorage, Memory or IndexedDB. It respects the async nature of any adapter while keeping your app synchronous.
+#### The Persistence Module
+Automatically syncs your State to LocalStorage, SessionStorage, Memory or IndexedDB. Always use this module first to avoid re-initialization issues.
 
 ```javascript
-import { reactive, Reactor, getReactor } from 'sia-reactor';
-import { PersistPlugin, LocalStorageAdapter, IndexedDBAdapter } from 'sia-reactor/plugins';
+import { reactive, Reactor, getReactor } from "sia-reactor";
+import { PersistModule, LocalStorageAdapter, IndexedDBAdapter, SessionStorageAdapter, CookieAdapter, MemoryAdapter } from "sia-reactor/modules";
 
 const state = reactive({ theme: "dark", settings: { volume: 50, brightness: 30 } });
-state.plugIn(new PersistPlugin({ // Plug it in. State is now automatically hydrated and throttled-saved.
+const persist = new PersistModule({ // Plug it in. State is now automatically hydrated and throttled-saved.
   key: "APP_PREFS",
   paths: ["theme", "settings.brightness"],
   throttle: 5000, 
-  adapter: new IndexedDBAdapter({ dbName: "Session", version: 1, onversionchange: () => location.reload() }) // or `LocalStorageAdapter` (instance or signature)
-}, getReactor(state)));  // Put Reactor as second arg if you want type inference, e.g. for the paths in the array.
+  fanout: true, // async hydration should use leaf writes incase UI listeners already initialized.
+  adapter: new IndexedDBAdapter({ dbName: "Session", version: 1, onversionchange: () => location.reload(), useSnapshot: true }) // or `LocalStorageAdapter` (instance or signature)
+};
+state.use(persist, getReactor(state)));  // Put `Reactor` as second constructor arg if you want type inference, e.g. for the paths in the array.
 ```
 
-#### The Time Travel Plugin
+#### The Time Travel Module
 Record state frames, step through history, and optionally attach a ready-to-use vanilla debug overlay.
 
 ```javascript
-import { reactive } from 'sia-reactor';
-import { TimeTravelPlugin } from 'sia-reactor/plugins';
-import { TimeTravelOverlay } from 'sia-reactor/adapters/vanilla';
-import 'sia-reactor/css/time-travel-overlay.css';
-
-const state = reactive({ count: 0, filter: "all" });
-const time = new TimeTravelPlugin({ maxHistory: 300, loop: false, rate: 150 });
-state.plugIn(time);
+import { TimeTravelModule } from "sia-reactor/modules";
+import { effect, TimeTravelOverlay } from "sia-reactor/adapters/vanilla";
+import "sia-reactor/css/time-travel-overlay.css";
+
+const time = new TimeTravelModule({ maxHistory: 300, loop: false, rate: 150 });
+state.use(time);
+
+// If persist uses an async adapter (e.g. IndexedDB), wait till after hydration:
+persist.state.once("hydrated", () => state.use(time)); // starts `false`, one-time stall until it flips
+effect(() => persist.state.hydrated && state.use(time), { once: true }) // same logic, different look :)
+
 const overlay = new TimeTravelOverlay(time, { color: "#e26e02", startOpen: false, devOnly: true, container: document.body }); // optional debug interface for visulazation
 ```
 ```jsx
-import { TimeTravelOverlay } from 'sia-reactor/adapters/react';
+import { TimeTravelOverlay } from "sia-reactor/adapters/react";
 
 <TimeTravelOverlay time={time} color="#e26e02" startOpen devOnly /> // react-safe instance lifecycle management, e.g. for HMR predictability.
 ```
 
-Useful plugin methods: `play()`, `pause()`, `rewind()`, `clear()`, `undo()`, `redo()`, `step(n, forward)`, `jumpTo(frame)`, `export()`, `import(serialized)`.
+Useful methods: `play()`, `pause()`, `rewind()`, `clear()`, `undo()`, `redo()`, `step(n, forward)`, `jumpTo(frame)`, `export(replacer)`, `import(json, reviver)`.
 
 ### Reactor Build Options
 
-These are some core build options accepted by `new Reactor(core, build)` and `reactive(core, build, preferences)`.
+These are some core build options accepted by `new Reactor(core, build)` and `reactive(core, build, preferences)` configurable via `Reactor.config`.
 
 - **`debug?`**: 1-time set. Enables debug logging and diagnostics of core operations. (default: `false`)
 - **`crossRealms?`**: Enables cross-realm object detection support by using slower but safer type checks. (e.g. iframes) (default: `false`).
@@ -283,8 +289,6 @@ These are some core build options accepted by `new Reactor(core, build)` and `re
 - **`equalityFunction?`**: Custom equality used by setters and adapter comparisons (default: `Object.is`).
 - **`batchingFunction?`**: Custom batching scheduler for listener notification flushes (default: `queueMicrotask`)
 - **`referenceTracking?`**: Enables identity/reference tracking features in the runtime. (default: `false`).
- 
-*NOTE: those not marked as 1-time set are configurable via `Reactor.config`. Also, plugs and hooks turn on whatever they need automatically.*
 
 ### Reactive Preferences (Method Naming)
 
@@ -295,7 +299,7 @@ These are some core build options accepted by `new Reactor(core, build)` and `re
 - **`whitelist?`**: Keeps specific methods on their original names while others get affixed.
 
 ```javascript
-import { reactive } from 'sia-reactor';
+import { reactive } from "sia-reactor";
 
 const state = reactive(
   { count: 0 },
@@ -341,9 +345,10 @@ player.on("intent.playing", (e) => {
 
 ### Troubleshooting
 
-- Listener timing feels late: `on` is microtask-batched by design; use `watch` only for strict immediate engine sync.
-- `reject()` appears ignored: call it in capture phase and ensure branch is wrapped in `intent(...)`, remember it's the listener's choice to listen also.
-- Snapshot behavior feels stale: enable `referenceTracking: true` with `smartCloning: true`.
+- Listener timing feels late: `on(path, ...)` is microtask-batched by design; use `watch(path, ...)` only for strict immediate engine sync on leaf paths preferably.
+- Listeners don't react to changes: use `fanout(state, path, object, { depth: n })` instead of direct object sets to keep immutable semantics.
+- `reject()` appears ignored: call it in capture phase and ensure branch is wrapped in `intent(...)`, also remember it's the listener's choice to comply.
+- Snapshot behavior feels stale: enable `referenceTracking: true` with `smartCloning: true`, also use these when persisting to environments that don't take proxies, e.g. IndexedDB.
 - Cross-frame data is skipped: enable `crossRealms: true` for iframe/other realm objects.
 - Class/prototype behavior is odd: enable `preserveContext: true` (tradeoff: slower hot paths).
 - Working with symbol keys and you want blind writes/reads: unwrap first with `getRaw` or `RAW` and operate on the raw object.
@@ -355,9 +360,9 @@ player.on("intent.playing", (e) => {
 The S.I.A. Reactor operates in two distinct dimensions: **The Synchronous Dimension** (Gatekeepers & Watchers) and **The Asynchronous Dimension** (Listeners). Because they intercept data at entirely different points in time, they receive different objects and possess different capabilities.
 
 ### 1. The Synchronous Dimension: The `Payload`
-When you use `get`, `set`, `delete`, or `watch`, you are sitting *directly inside the Javascript Proxy Trap*. The memory has not been written yet (or is being written right at that exact millisecond). 
+When you use `.get()`, `.set()`, `.delete()`, or `.watch()`, you are sitting *directly inside the Javascript Proxy Trap*. The memory has not been written yet (or is being written right at that exact millisecond). 
 
-Because there is no "bubbling" or "event wave" yet, these methods do not receive a complex event object. They receive a lightweight, factual `Payload`.
+Because there is no "bubbling" or "event wave" yet, these methods do not receive an event object. They receive a lightweight, factual `Payload`.
 
 #### The `Payload` Anatomy
 ```javascript
@@ -390,7 +395,7 @@ The `target` and `currentTarget` objects give you absolute surgical awareness of
 Because `set` and `delete` mediators execute *before* the memory is written, you have the power to alter reality or stop it entirely using the `TERMINATOR` symbol.
 
 ```javascript
-import { TERMINATOR } from 'sia-reactor';
+import { TERMINATOR } from "sia-reactor";
 
 // Example: Data Sanitization & Blocking
 rtr.set("user.age", (value) => {
@@ -400,14 +405,14 @@ rtr.set("user.age", (value) => {
 ```
 
 ### 2. The Asynchronous Dimension: The S.I.A. Event Loop
-When you use `on` or `once` (Listeners), you are sitting in the **Microtask Queue**. The memory has already been safely written, the Proxy traps have closed, and the engine is now broadcasting a DOM-Style "Mutation Wave" across the state tree.
+When you use `.on()` or `.once()` (Listeners), you are sitting in the **Microtask Queue**. The memory has already been safely written, the Proxy traps have closed, and the engine is now broadcasting a DOM-Style "Mutation Wave" across the state tree.
 
-If you mutate `state.user.profile.name = "Ada"`, the event wave travels like this:
+If you mutate `state.user.profile.name = "Kosi"`, the event wave travels like this:
 1. **Capture Phase:** `*` (Root) ➔ `user` ➔ `user.profile`
 2. **Target Phase:** `user.profile.name`
 3. **Bubble Phase:** `user.profile` ➔ `user` ➔ `*` (Root)
 
-*NOTE: Only `on` does this since it is batched tree walking to stay within recursive limits.*
+*NOTE: Only `on` does this since it is batched to stay within recursive limits.*
 
 #### The Event Anatomy (`REvent` type)
 Listeners receive a `ReactorEvent` (`REvent`). This object *inherits* everything from the `Payload`, but adds **Political Event Routing**, providing absolute surgical awareness of what is happening in the tree.
@@ -419,13 +424,13 @@ rtr.on("user.profile", (e) => {
   console.log(e.staticType);    // "set" (The original action)
   console.log(e.path);          // "user.profile.name" (The actual property changed)
   console.log(e.currentTarget); // { path: "user.profile", value: {...} } (Where we are listening)
-  console.log(e.value);         // "Ada" (The new value)
+  console.log(e.value);         // "Kosi" (The new value)
   console.log(e.oldValue);      // "John" (The previous value)
   // 2. Political Routing
   console.log(e.eventPhase);    // 3 (Bubbling Phase)
   console.log(e.bubbles);       // true/false 
   // 3. Misc
-  console.log(e.composedPath()); // ["Ada", { name: "Ada", age: 26 }, { profile: { name: "Ada", age: 26 } }, { user: { profile: { name: "Ada", age: 26 } } }] (refs, target -> root)
+  console.log(e.composedPath()); // ["Kosi", { name: "Kosi", age: 26 }, { profile: { name: "Kosi", age: 26 } }, { user: { profile: { name: "Kosi", age: 26 } } }] (refs, target -> root)
 }); // you could use external callbacks but typed with `REvent<T, "user.age">`
 ```
 
@@ -454,9 +459,29 @@ When you listen to a parent object (like `"user.profile"`), you will naturally c
 
 To help you instantly differentiate between the object *itself* being replaced, versus a *child* property mutating deep inside of it, the Reactor intelligently morphs the `e.type`:
 * If `state.user.profile = {}` happens, the listener receives `e.type === "set"`.
-* If `state.user.profile.name = "Ada"` happens, the parent listener receives `e.type === "update"`.
+* If `state.user.profile.name = "Kosi"` happens, the parent listener receives `e.type === "update"`.
 
-This allows for highly fine-grained syncing bridges across your application without writing heavy, manual for-loop diffing algorithms!
+This allows for highly fine-grained syncing bridges across your application without writing heavy for-loop diffing algorithms! Use `{ depth: n }` to control how deep the path bubbles you see are, i.e. 
+
+```javascript
+rtr.on("todos", (e) => console.log(e), { depth : 1 }); // only sees updates on direct children
+```
+
+Typing tip (for depth-aware `update` narrowing): `depth` mainly affects inferred `target.key` unions. To preserve type narrowing where desired, avoid destructuring in the callback signature. Types can be too accurate thereby causing issues, cast where necessary. e.g. `e.value as any`.
+
+```javascript
+// Less reliable inference for depth-aware unions
+rtr.on("todos", ({ type, target: { path, key } }) => {
+  if (type === "update") console.log(path, key);
+}, { depth: 1 });
+// Better: narrow first, then destructure inside
+rtr.on("todos", (e: REvent<user, "todos", 1>) => {
+  if (e.type === "update") {
+    const { path, key } = e.target;
+    console.log(path, key); // or e.target.path, e.target.key
+  }
+}, { depth: 1 }); // you need the generic for external callbacks only
+```
 
 ---
 
@@ -464,7 +489,7 @@ This allows for highly fine-grained syncing bridges across your application with
 
 ### The CSS Black Box
 
-Imagine you have 50 different CSS variables in your state (`settings.css.containerWidth`, `settings.css.themeColor`, etc.). Registering 50 individual `watch()` or `on()` listeners would need manual css crawling that will be blind dynamically added variables.
+Imagine you have 50 different CSS variables in your state (`settings.css.containerWidth`, `settings.css.themeColor`, etc.). Registering 50 individual `watch()` or `on()` listeners would need manual css crawling that will be blind to dynamically added variables.
 
 Instead, we use the **Root Wildcard** (`"*"`) for both Reading (`get`) and Writing (`watch`).
 
@@ -486,8 +511,8 @@ this.ctlr.config.get("*", (val, { target: { key, path } }) => {
 });
 ```
 #### Why this pattern is elite:
-1. **Synchronous Execution (`watch`):** CSSOM needs immediate updates. If you used an asynchronous `.on()` listener, the browser might paint the old frame before the microtask resolves, causing UI flicker. `.watch()` executes synchronously during the proxy trap.
-2. **The Wildcard Tradeoff:** By listening to `*`, this callback runs synchronously on *every single mutation* in the entire reactor. 
+1. **Synchronous Execution (`watch`):** CSSOM needs immediate updates. If you used an `.on()` listener, a slow browser might paint the old frame before the microtask resolves, causing UI flicker. `.watch()` executes synchronously during the proxy trap.
+2. **The Wildcard Tradeoff:** By listening to `*`, this callback runs synchronously on *every single mutation* in the entire reactor. This is the only synchronous way to catch deep nested updates.
 3. **The Ultimate Illusion:** A developer writes `console.log(state.settings.css.themeColor)`. To them, it looks like a standard plain object property access. In reality, the Reactor just executed a surgical DOM read. It is a true black box.
 
 ---
@@ -499,7 +524,6 @@ S.I.A. Reactor synthesizes core concepts from the heavyweights of web and media
 * **The Native JavaScript Proxy API:** Arguably the most powerful, slept-on feature in the ECMAScript specification. The Reactor is essentially a love letter to the Proxy API, packaging its raw, interception-level power into a structured and safe Data DOM so the community can finally use what it's truly capable of.
 * **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 & Valtio:** Leveraging native ES6 Proxies for instant, deep reactivity without forcing clunky `get()` or `set()` wrapper functions.
  
 ---

package/dist/{TimeTravelOverlay-BYSnHBXx.d.cts → TimeTravelOverlay-DiXUgbUU.d.cts}

@@ -1,5 +1,5 @@
-import { R as Reactive } from './index-DCG3sacH.cjs';
-import { T as TimeTravelPlugin } from './timeTravel-L8CEhHIo.cjs';
+import { d as Reactive } from './index-BgbbNXTW.cjs';
+import { m as TimeTravelModule } from './timeTravel-CraHdbXZ.cjs';
 
 /** Reactive options for the TimeTravel overlay instance. */
 interface TimeTravelConfig {
@@ -14,8 +14,9 @@ interface TimeTravelConfig {
     /** Container element that owns the overlay layer and dock. */
     container: HTMLElement;
 }
-/** Vanilla overlay controller for visual time-travel controls and timeline I/O.
- * Mounts a docked HUD into the configured container, syncs its UI with plugin state, and forwards keyboard/button actions to the TimeTravelPlugin.
+/**
+ * - Vanilla overlay controller for visual time-travel controls and timeline I/O.
+ * - Mounts a docked HUD into the configured container, syncs its UI with module state, and forwards keyboard/button actions to the TimeTravelModule.
  * Supports reactive `config` updates (title/color/container/devOnly) and maintains local overlay UI state (`open` and `import` payload text).
  */
 declare class TimeTravelOverlay {
@@ -26,15 +27,15 @@ declare class TimeTravelOverlay {
         open: boolean;
         import: string;
     }, undefined>;
-    readonly time: TimeTravelPlugin;
+    readonly time: TimeTravelModule;
     readonly els: Record<string, HTMLElement>;
     private clups;
     private keyup?;
-    /** Creates a docked TimeTravel overlay bound to a plugin instance.
-     * @param time TimeTravel plugin instance that owns timeline operations.
+    /** Creates a docked TimeTravel overlay bound to a module instance.
+     * @param time TimeTravel module instance that owns timeline operations.
      * @param build Optional initial overlay config overrides.
      */
-    constructor(time: TimeTravelPlugin, build?: Partial<TimeTravelConfig>);
+    constructor(time: TimeTravelModule, build?: Partial<TimeTravelConfig>);
     destroy(): void;
 }
 

package/dist/{TimeTravelOverlay-DoNrZwvX.d.ts → TimeTravelOverlay-eWjAy0yr.d.ts}

@@ -1,5 +1,5 @@
-import { R as Reactive } from './index-DCG3sacH.js';
-import { T as TimeTravelPlugin } from './timeTravel-Bv_u5M1D.js';
+import { d as Reactive } from './index-BgbbNXTW.js';
+import { m as TimeTravelModule } from './timeTravel-YUxRHRgh.js';
 
 /** Reactive options for the TimeTravel overlay instance. */
 interface TimeTravelConfig {
@@ -14,8 +14,9 @@ interface TimeTravelConfig {
     /** Container element that owns the overlay layer and dock. */
     container: HTMLElement;
 }
-/** Vanilla overlay controller for visual time-travel controls and timeline I/O.
- * Mounts a docked HUD into the configured container, syncs its UI with plugin state, and forwards keyboard/button actions to the TimeTravelPlugin.
+/**
+ * - Vanilla overlay controller for visual time-travel controls and timeline I/O.
+ * - Mounts a docked HUD into the configured container, syncs its UI with module state, and forwards keyboard/button actions to the TimeTravelModule.
  * Supports reactive `config` updates (title/color/container/devOnly) and maintains local overlay UI state (`open` and `import` payload text).
  */
 declare class TimeTravelOverlay {
@@ -26,15 +27,15 @@ declare class TimeTravelOverlay {
         open: boolean;
         import: string;
     }, undefined>;
-    readonly time: TimeTravelPlugin;
+    readonly time: TimeTravelModule;
     readonly els: Record<string, HTMLElement>;
     private clups;
     private keyup?;
-    /** Creates a docked TimeTravel overlay bound to a plugin instance.
-     * @param time TimeTravel plugin instance that owns timeline operations.
+    /** Creates a docked TimeTravel overlay bound to a module instance.
+     * @param time TimeTravel module instance that owns timeline operations.
      * @param build Optional initial overlay config overrides.
      */
-    constructor(time: TimeTravelPlugin, build?: Partial<TimeTravelConfig>);
+    constructor(time: TimeTravelModule, build?: Partial<TimeTravelConfig>);
     destroy(): void;
 }