sia-reactor 0.0.20 → 0.0.21

package/README.md

@@ -143,8 +143,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
@@ -197,13 +197,13 @@ The engine provides native React bindings utilizing `useSyncExternalStore` and a
 
 ```javascript
 import { reactive } from 'sia-reactor';
-import { useReactor, useSelector, usePath, effect } from 'sia-reactor/react'; 
+import { useReactor, useAnyReactor, useSelector, useAnySelector, usePath, effect } from 'sia-reactor/react'; 
 
 const state = reactive({ user: { name: "Ada", 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
+  const sameState = useReactor(state); // `useReactorSnapshot()` if mutable issues arise
   useAnyReactor(); // use this when you just want to use any 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>;
@@ -211,7 +211,7 @@ function Profile() {
 
 // 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 theme = useSelector(state, (s) => s.theme); // `useSelectorSnapshot()` if mutable issues arise
   const newName = useAnySelector(() => state.user.name + spouseState.user.name); // use this when you just want to derive any state from any reactor
   return <div>Theme: {theme}</div>;
 }
@@ -223,9 +223,7 @@ 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

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

@@ -1,5 +1,5 @@
-import { R as Reactive } from './index-DCG3sacH.cjs';
-import { T as TimeTravelPlugin } from './timeTravel-L8CEhHIo.cjs';
+import { R as Reactive } from './index-Oie9hhE8.cjs';
+import { T as TimeTravelPlugin } from './timeTravel-WpgWmKu-.cjs';
 
 /** Reactive options for the TimeTravel overlay instance. */
 interface TimeTravelConfig {

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

@@ -1,5 +1,5 @@
-import { R as Reactive } from './index-DCG3sacH.js';
-import { T as TimeTravelPlugin } from './timeTravel-Bv_u5M1D.js';
+import { R as Reactive } from './index-Oie9hhE8.js';
+import { T as TimeTravelPlugin } from './timeTravel-B1vedDQc.js';
 
 /** Reactive options for the TimeTravel overlay instance. */
 interface TimeTravelConfig {

package/dist/adapters/react.cjs

@@ -26,7 +26,9 @@ __export(react_exports, {
   useISOLayoutEffect: () => useISOLayoutEffect,
   usePath: () => usePath,
   useReactor: () => useReactor,
-  useSelector: () => useSelector
+  useReactorSnapshot: () => useReactorSnapshot,
+  useSelector: () => useSelector,
+  useSelectorSnapshot: () => useSelectorSnapshot
 });
 module.exports = __toCommonJS(react_exports);
 
@@ -326,27 +328,27 @@ var Reactor = class {
   listeners;
   /**
    * Creates a new Reactor instance.
-   * @param object Initial state object.
+   * @param target Initial state target.
    * @param build Reactor bootstrap/build configuration.
    * @example
    * const rtr = new Reactor({ count: 0 });
    */
-  constructor(object = {}, build) {
+  constructor(target = {}, build) {
     this[INERTIA] = true;
     this.config = { crossRealms: false, smartCloning: false, eventBubbling: true, lineageTracing: false, preserveContext: false, equalityFunction: Object.is, batchingFunction: RTR_BATCH, ...build };
-    this.core = this.proxied(object);
+    this.core = this.proxied(target);
     if (build) this.canLog = !!build.debug;
   }
-  proxied(obj, rejectable = false, indiffable = false, parent, key, path) {
-    if (!obj || "object" !== typeof obj) return obj;
-    obj = obj[RAW] || obj;
-    if (this.config.referenceTracking && parent && key && !this.link(obj, parent, key, false)) return obj;
-    const cached = this.proxyCache.get(obj);
+  proxied(target, rejectable = false, indiffable = false, parent, key, path) {
+    if (!target || "object" !== typeof target) return target;
+    target = target[RAW] || target;
+    if (this.config.referenceTracking && parent && key && !this.link(target, parent, key, false)) return target;
+    const cached = this.proxyCache.get(target);
     if (cached) return cached;
-    if (obj[INERTIA] || !canHandle(obj, this.config, false)) return obj;
-    rejectable ||= obj[REJECTABLE];
-    indiffable ||= obj[INDIFFABLE];
-    const proxy = new Proxy(obj, {
+    if (target[INERTIA] || !canHandle(target, this.config, false)) return target;
+    rejectable ||= target[REJECTABLE];
+    indiffable ||= target[INDIFFABLE];
+    const proxy = new Proxy(target, {
       // Robust Proxy handler
       get: (object, key2, receiver) => {
         if (key2 === RAW) return this.log(`\u{1F440} [Reactor \`get\` Trap] Peeked at ${object}`), object;
@@ -359,10 +361,10 @@ var Reactor = class {
           for (let i = 0, len = this.config.lineageTracing ? paths.length : 1; i < len; i++) {
             const currPath = this.config.lineageTracing ? paths[i] : fullPath, cords = this.getters.get(currPath);
             if (!cords && !wildcords) continue;
-            const target = { path: currPath, value, key: keyStr, hadKey: true, object: receiver }, payload = { type: "get", target, currentTarget: target, root: this.core, rejectable };
+            const target2 = { path: currPath, value, key: keyStr, hadKey: true, object: receiver }, payload = { type: "get", target: target2, currentTarget: target2, root: this.core, rejectable };
             if (cords) value = this.mediate(currPath, payload, "get", cords);
             if (!wildcords) continue;
-            target.value = value;
+            target2.value = value;
             value = this.mediate("*", payload, "get", wildcords);
           }
         }
@@ -384,13 +386,13 @@ var Reactor = class {
           for (let i = 0; i < loopLen; i++) {
             const currPath = this.config.lineageTracing ? paths[i] : fullPath, cords = this.setters.get(currPath);
             if (!cords && !wildcords) continue;
-            const target = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver }, payload = { type: "set", target, currentTarget: target, root: this.core, terminated, rejectable };
+            const target2 = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver }, payload = { type: "set", target: target2, currentTarget: target2, root: this.core, terminated, rejectable };
             if (cords) {
               const result2 = this.mediate(currPath, payload, "set", cords);
               if (!(terminated ||= payload.terminated)) value = result2;
             }
             if (!wildcords) continue;
-            target.value = value;
+            target2.value = value;
             const result = this.mediate("*", payload, "set", wildcords);
             if (!(terminated ||= payload.terminated)) value = result;
           }
@@ -401,8 +403,8 @@ var Reactor = class {
         if (this.config.referenceTracking && !unchanged) this.config.smartCloning && this.stamp(object), this.unlink(safeOldValue, object, keyStr), this.link(safeValue, object, keyStr);
         if (this.watchers || this.listeners)
           for (let i = 0; i < loopLen; i++) {
-            const currPath = this.config.lineageTracing ? paths[i] : fullPath, target = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver };
-            this.notify(currPath, { type: "set", target, currentTarget: target, root: this.core, terminated, rejectable });
+            const currPath = this.config.lineageTracing ? paths[i] : fullPath, target2 = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver };
+            this.notify(currPath, { type: "set", target: target2, currentTarget: target2, root: this.core, terminated, rejectable });
           }
         return true;
       },
@@ -416,7 +418,7 @@ var Reactor = class {
           for (let i = 0; i < loopLen; i++) {
             const currPath = this.config.lineageTracing ? paths[i] : fullPath, cords = this.deleters.get(currPath);
             if (!cords && !wildcords) continue;
-            const target = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver }, payload = { type: "delete", target, currentTarget: target, root: this.core, rejectable };
+            const target2 = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver }, payload = { type: "delete", target: target2, currentTarget: target2, root: this.core, rejectable };
             if (cords) {
               const result2 = this.mediate(currPath, payload, "delete", cords);
               if (!(terminated ||= payload.terminated)) value = result2;
@@ -432,8 +434,8 @@ var Reactor = class {
         if (this.config.referenceTracking) this.config.smartCloning && this.stamp(object), this.unlink(oldValue?.[RAW] || oldValue, object, keyStr);
         if (this.watchers || this.listeners)
           for (let i = 0; i < loopLen; i++) {
-            const currPath = this.config.lineageTracing ? paths[i] : fullPath, target = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver };
-            this.notify(currPath, { type: "delete", target, currentTarget: target, root: this.core, rejectable });
+            const currPath = this.config.lineageTracing ? paths[i] : fullPath, target2 = { path: currPath, value, oldValue, key: keyStr, hadKey, object: receiver };
+            this.notify(currPath, { type: "delete", target: target2, currentTarget: target2, root: this.core, rejectable });
           }
         return true;
       },
@@ -459,7 +461,7 @@ var Reactor = class {
         return ownKeys;
       }
     });
-    return this.proxyCache.set(obj, proxy), proxy;
+    return this.proxyCache.set(target, proxy), proxy;
   }
   trace(target, path, paths = [], seen = /* @__PURE__ */ new WeakSet()) {
     if (Object.is(target, this.core[RAW] || this.core)) return paths.push(path), paths;
@@ -612,15 +614,14 @@ var Reactor = class {
     if (sig) sig.aborted ? cord.clup() : sig.addEventListener("abort", cord.clup, { once: true });
     return cord.sclup = !sig || sig.aborted ? NOOP : () => sig.removeEventListener("abort", cord.clup), cord.clup;
   }
-  cloned(obj, raw, seen = /* @__PURE__ */ new WeakMap()) {
-    if (!obj || "object" !== typeof obj) return obj;
-    obj = obj[RAW] || obj;
-    const cloned = seen.get(obj);
+  cloned(target, raw, seen = /* @__PURE__ */ new WeakMap()) {
+    if (!target || "object" !== typeof target) return target;
+    const obj = target[RAW] || target, cloned = seen.get(obj);
     if (cloned) return cloned;
     if (!canHandle(obj, this.config, false)) return obj;
     const version = obj[VERSION] || 0, cached = !raw && this.config.smartCloning && (this.snapCache ??= /* @__PURE__ */ new WeakMap()).get(obj);
     if (cached && obj[SSVERSION] === version) return cached;
-    const clone = !raw ? this.config.preserveContext ? Object.create(Object.getPrototypeOf(obj)) : Array.isArray(obj) ? [] : {} : obj[RAW] || obj;
+    const clone = !raw ? this.config.preserveContext ? Object.create(Object.getPrototypeOf(obj)) : Array.isArray(obj) ? [] : {} : obj;
     seen.set(obj, clone);
     const keys2 = this.config.preserveContext ? Reflect.ownKeys(obj) : Object.keys(obj);
     for (let i = 0, len = keys2.length; i < len; i++) clone[keys2[i]] = this.cloned(obj[keys2[i]], raw, seen);
@@ -804,19 +805,8 @@ var Reactor = class {
     for (let i = 0, len = cords.length; i < len; i++) if (Object.is(cords[i].cb, callback) && cords[i].capture === capture) return cords[i].sclup(), cords.splice((len--, i--), 1), !cords.length && this.listeners.delete(path), true;
     return false;
   }
-  /**
-   * Creates a snapshot; possibly clone of state (or a state branch).
-   * You could alternatively use or serialize your proxied state "as is" except the environment demands no proxies or new references.
-   * @param raw Use raw (deep unproxied & uncloned) version of branch.
-   * @param branch Branch to clone.
-   * @returns Snapshot deep or smart (structurally shared) clone.
-   * @example
-   * const snap = rtr.snapshot();
-   * @example
-   * const snap = rtr.snapshot(false, rtr.core.history.past);
-   */
-  snapshot(raw = !this.config.smartCloning, branch = this.core) {
-    return this.cloned(branch, raw);
+  snapshot(raw = !this.config.smartCloning, branch) {
+    return this.cloned(arguments.length < 2 ? this.core : branch, raw);
   }
   /**
    * Cascades object updates into direct child paths.
@@ -1032,7 +1022,7 @@ function useReactor(target, options = NIL, build) {
   const versionRef = (0, import_react2.useRef)(0), tgtRef = (0, import_react2.useRef)(), rtrRef = (0, import_react2.useRef)(), rtr = tgtRef.current !== target || !rtrRef.current ? (tgtRef.current = target, rtrRef.current = getReactor(target, true, build)) : rtrRef.current, atrkrRef = (0, import_react2.useRef)(), prevTrkr = CTX.autotracker, atrkr = CTX.autotracker = atrkrRef.current ||= new Autotracker(), optsRef = (0, import_react2.useRef)(options), notifyRef = (0, import_react2.useRef)(NOOP);
   optsRef.current = options;
   atrkr.unblock(rtr), queueMicrotask(() => CTX.autotracker === atrkr && (CTX.autotracker = prevTrkr));
-  const subscribe = (0, import_react2.useCallback)((notify) => atrkr.callback(notifyRef.current = () => (versionRef.current++, notify())), []);
+  const subscribe = (0, import_react2.useCallback)((notify) => atrkr.callback(notifyRef.current = () => (versionRef.current++, notify())), [atrkr]);
   const getSnapshot = (0, import_react2.useCallback)(() => versionRef.current, []);
   (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return useISOLayoutEffect(() => (CTX.autotracker = prevTrkr, atrkr.callback(notifyRef.current, optsRef.current)), [atrkr]), rtr.core;
@@ -1041,11 +1031,21 @@ function useAnyReactor(options = NIL) {
   const versionRef = (0, import_react2.useRef)(0), atrkrRef = (0, import_react2.useRef)(), prevTrkr = CTX.autotracker, atrkr = CTX.autotracker = atrkrRef.current ||= new Autotracker(), optsRef = (0, import_react2.useRef)(options), notifyRef = (0, import_react2.useRef)(NOOP);
   optsRef.current = options;
   atrkr.unblock(), queueMicrotask(() => CTX.autotracker === atrkr && (CTX.autotracker = prevTrkr));
-  const subscribe = (0, import_react2.useCallback)((notify) => atrkr.callback(notifyRef.current = () => (versionRef.current++, notify())), []);
+  const subscribe = (0, import_react2.useCallback)((notify) => atrkr.callback(notifyRef.current = () => (versionRef.current++, notify())), [atrkr]);
   const getSnapshot = (0, import_react2.useCallback)(() => versionRef.current, []);
   (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   useISOLayoutEffect(() => (CTX.autotracker = prevTrkr, atrkr.callback(notifyRef.current, optsRef.current)), [atrkr]);
 }
+function useReactorSnapshot(target, options, build = { referenceTracking: true, smartCloning: true }) {
+  const tgtRef = (0, import_react2.useRef)(), rtrRef = (0, import_react2.useRef)(), rtr = tgtRef.current !== target || !rtrRef.current ? (tgtRef.current = target, rtrRef.current = getReactor(target, true, build)) : rtrRef.current, atrkrRef = (0, import_react2.useRef)(), atrkrRtrRef = (0, import_react2.useRef)(), atrkr = atrkrRtrRef.current !== rtr || !atrkrRef.current ? (atrkrRtrRef.current = rtr, atrkrRef.current = new Autotracker(rtr)) : atrkrRef.current, notifyRef = (0, import_react2.useRef)(NOOP), optsRef = (0, import_react2.useRef)(options);
+  rtr.config.referenceTracking = rtr.config.smartCloning = true;
+  optsRef.current = options;
+  const subscribe = (0, import_react2.useCallback)((notify) => (atrkr.callback(notifyRef.current = notify, optsRef.current), () => atrkr.cleanup()), [atrkr]);
+  const getSnapshot = () => rtr.snapshot();
+  const snapshot = (0, import_react2.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  const proxy = (0, import_react2.useMemo)(() => atrkr.tracked(snapshot), [atrkr, snapshot]);
+  return useISOLayoutEffect(() => atrkr.callback(notifyRef.current, optsRef.current), [atrkr, proxy]), proxy;
+}
 
 // src/ts/adapters/react/hooks/useSelector.ts
 var import_react3 = require("react");
@@ -1071,6 +1071,18 @@ function useAnySelector(sel, eq = Object.is, options = NIL) {
   const slice = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
   return useISOLayoutEffect(() => atrkr.callback(notifyRef.current, optsRef.current), [atrkr, slice]), slice;
 }
+function useSelectorSnapshot(target, sel, eq = Object.is, options, build = { referenceTracking: true, smartCloning: true }) {
+  const tgtRef = (0, import_react3.useRef)(), rtrRef = (0, import_react3.useRef)(), rtr = tgtRef.current !== target || !rtrRef.current ? (tgtRef.current = target, rtrRef.current = getReactor(target, true, build)) : rtrRef.current, atrkrRef = (0, import_react3.useRef)(), atrkrRtrRef = (0, import_react3.useRef)(), atrkr = atrkrRtrRef.current !== rtr || !atrkrRef.current ? (atrkrRtrRef.current = rtr, atrkrRef.current = new Autotracker(rtr)) : atrkrRef.current, notifyRef = (0, import_react3.useRef)(NOOP), sliceRef = (0, import_react3.useRef)(), selRef = (0, import_react3.useRef)(sel), eqRef = (0, import_react3.useRef)(eq), optsRef = (0, import_react3.useRef)(options);
+  rtr.config.referenceTracking = rtr.config.smartCloning = true;
+  optsRef.current = options, selRef.current = sel, eqRef.current = eq;
+  const subscribe = (0, import_react3.useCallback)((notify) => (atrkr.callback(notifyRef.current = notify, optsRef.current), () => atrkr.cleanup()), [atrkr]);
+  const getSnapshot = (0, import_react3.useCallback)(() => {
+    const next = selRef.current(atrkr.tracked(rtr.snapshot()));
+    return eqRef.current(sliceRef.current, next) ? sliceRef.current : sliceRef.current = next;
+  }, [atrkr]);
+  const slice = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+  return useISOLayoutEffect(() => atrkr.callback(notifyRef.current, optsRef.current), [atrkr, slice]), slice;
+}
 
 // src/ts/adapters/react/hooks/usePath.ts
 var import_react4 = require("react");
@@ -1187,41 +1199,16 @@ var TimeTravelOverlay = class _TimeTravelOverlay {
    */
   constructor(time, build = {}) {
     this.time = time;
-    this.config = reactive({ container: document.body, color: "", startOpen: false, devOnly: true, title: `Time Travel Overlay ${this.index = ++_TimeTravelOverlay.count}`, ...build });
+    this.config = reactive({ title: `Time Travel Overlay ${this.index = ++_TimeTravelOverlay.count}`, ...build });
     this.state.open = !!this.config.startOpen;
-    const host = createEl("div", { className: "tt-overlay-host" });
-    const toggle = createEl("button", { className: "tt-overlay-toggle", type: "button", onclick: () => this.state.open = !this.state.open });
-    const panel = createEl("aside", { className: "tt-overlay", ariaLabel: "time travel overlay" });
-    const title = createEl("div", { className: "title" });
-    const frame = createEl("span", { className: "muted" });
-    const history = createEl("span", { className: "muted" });
-    const paused = createEl("span", { className: "muted" });
-    const clrHistory = createEl("button", { textContent: `Clear History${formatKeyForDisplay(keys.shortcuts.clrHistory)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.clrHistory, false), onclick: () => (this.time.clear(), this.state.import = "") });
-    const undo = createEl("button", { textContent: `Undo${formatKeyForDisplay(keys.shortcuts.undo[0])}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.undo, false), onclick: this.time.undo });
-    const redo = createEl("button", { textContent: `Redo${formatKeyForDisplay(keys.shortcuts.redo[0])}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.redo, false), onclick: this.time.redo });
-    const genesis = createEl("button", { textContent: `Genesis${formatKeyForDisplay(keys.shortcuts.genesis[0])}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.genesis, false), onclick: () => this.time.jumpTo(0) });
-    const playPause = createEl("button", { onclick: () => this.time[this.time.state.paused ? "play" : "pause"](), ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.playPause, false) });
-    const rewind = createEl("button", { textContent: `Rewind${formatKeyForDisplay(keys.shortcuts.rewind)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.rewind, false), onclick: this.time.rewind });
-    const range = createEl("input", { type: "range", min: "0", max: "0", value: "0", title: "time travel frame", ariaLabel: "time travel frame", oninput: () => this.time.jumpTo(Number(range.value)) });
-    const exp = createEl("button", { textContent: `Export${formatKeyForDisplay(keys.shortcuts.export)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.export, false), onclick: () => this.state.import = this.time.export() });
-    const imp = createEl("button", { textContent: `Import${formatKeyForDisplay(keys.shortcuts.import)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.import, false), onclick: () => this.state.import.trim().length && this.time.import(this.state.import) });
-    const clr = createEl("button", { textContent: `Clear${formatKeyForDisplay(keys.shortcuts.clear)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.clear, false), onclick: () => this.state.import = "" });
-    const io = createEl("textarea", { className: "tt-io", placeholder: "timeline payload json", oninput: () => this.state.import = io.value });
-    const foot = createEl("p", { className: "tt-footnote", textContent: "Want this in your app? " });
-    const link = createEl("a", { target: "_blank", rel: "noreferrer noopener", textContent: "sia-reactor", href: "https://www.npmjs.com/package/sia-reactor" });
-    const box = createEl("div", { className: "tt-status-box" });
-    const status = createEl("div", { className: "tt-status-row" });
-    const row1 = createEl("div", { className: "tt-row" });
-    const row2 = createEl("div", { className: "tt-row" });
-    const row3 = createEl("div", { className: "tt-row" });
-    status.append((box.append(frame, history, paused), box), clrHistory);
-    panel.append(title, status, (row1.append(undo, redo, genesis), row1), (row2.append(playPause, rewind), row2), range, (row3.append(exp, imp, clr), row3), io, (foot.appendChild(link), foot));
+    const s = this.time.state, host = createEl("div", { className: "tt-overlay-host" }), toggle = createEl("button", { className: "tt-overlay-toggle", type: "button", onclick: () => this.state.open = !this.state.open }), panel = createEl("aside", { className: "tt-overlay", ariaLabel: "time travel overlay" }), title = createEl("div", { className: "title" }), frame = createEl("span", { className: "muted" }), clrHistory = createEl("button", { textContent: `Clear History${formatKeyForDisplay(keys.shortcuts.clrHistory)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.clrHistory, false), onclick: () => (this.time.clear(), this.state.import = "") }), undo = createEl("button", { textContent: `Undo${formatKeyForDisplay(keys.shortcuts.undo[0])}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.undo, false), onclick: this.time.undo }), redo = createEl("button", { textContent: `Redo${formatKeyForDisplay(keys.shortcuts.redo[0])}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.redo, false), onclick: this.time.redo }), genesis = createEl("button", { textContent: `Genesis${formatKeyForDisplay(keys.shortcuts.genesis[0])}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.genesis, false), onclick: () => this.time.jumpTo(0) }), playPause = createEl("button", { onclick: () => this.time[s.paused ? "play" : "pause"](), ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.playPause, false) }), rewind = createEl("button", { textContent: `Rewind${formatKeyForDisplay(keys.shortcuts.rewind)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.rewind, false), onclick: this.time.rewind }), range = createEl("input", { type: "range", min: "0", max: "0", value: "0", title: "time travel frame", ariaLabel: "time travel frame", oninput: () => this.time.jumpTo(Number(range.value)) }), exp = createEl("button", { textContent: `Export${formatKeyForDisplay(keys.shortcuts.export)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.export, false), onclick: () => this.state.import = this.time.export(null, 2) }), imp = createEl("button", { textContent: `Import${formatKeyForDisplay(keys.shortcuts.import)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.import, false), onclick: () => this.state.import.trim().length && this.time.import(this.state.import) }), clr = createEl("button", { textContent: `Clear${formatKeyForDisplay(keys.shortcuts.clear)}`, ariaKeyShortcuts: parseForARIAKS(keys.shortcuts.clear, false), onclick: () => this.state.import = "" }), payload = createEl("textarea", { className: "tt-io", readOnly: true, placeholder: "current payload json", title: "current payload" }), io = createEl("textarea", { className: "tt-io", placeholder: "timeline payload json", oninput: () => this.state.import = io.value }), foot = createEl("p", { className: "tt-footnote", textContent: "Want this in your app? " }), link = createEl("a", { target: "_blank", rel: "noreferrer noopener", textContent: "sia-reactor", href: "https://www.npmjs.com/package/sia-reactor" }), box = createEl("div", { className: "tt-status-box" }), status = createEl("div", { className: "tt-status-row" }), row1 = createEl("div", { className: "tt-row" }), row2 = createEl("div", { className: "tt-row" }), row3 = createEl("div", { className: "tt-row" });
+    status.append((box.append(frame), box), clrHistory);
+    panel.append(title, status, (row1.append(undo, redo, genesis), row1), (row2.append(playPause, rewind), row2), payload, range, (row3.append(exp, imp, clr), row3), io, (foot.appendChild(link), foot));
     host.append(toggle, panel);
-    this.els = { host, toggle, panel, title, frame, history, paused, clrHistory, undo, redo, genesis, playPause, rewind, range, exp, imp, clr, io };
+    this.els = { host, toggle, panel, title, frame, clrHistory, undo, redo, genesis, playPause, rewind, range, exp, imp, clr, payload, io };
     this.keyup = (e) => {
-      if (!this.state.open) return;
-      const a = keyEventAllowed(e, keys);
-      a === "undo" ? this.time.undo() : a === "redo" ? this.time.redo() : a === "genesis" ? this.time.jumpTo(0) : a === "prevFrame" ? this.time.step(1, false) : a === "nextFrame" ? this.time.step(1, true) : a === "skipBwd" ? this.time.step(5, false) : a === "skipFwd" ? this.time.step(5, true) : a === "rewind" ? this.time.rewind() : a === "playPause" ? this.time[this.time.state.paused ? "play" : "pause"]() : a === "clrHistory" ? this.time.clear() : a === "closeOverlay" ? this.state.open = false : a === "export" ? this.state.import = this.time.export() : a === "import" ? this.state.import.trim().length && this.time.import(this.state.import) : a === "clear" && (this.state.import = "");
+      const a = this.state.open && keyEventAllowed(e, keys);
+      a === "undo" ? this.time.undo() : a === "redo" ? this.time.redo() : a === "genesis" ? this.time.jumpTo(0) : a === "prevFrame" ? this.time.step(1, false) : a === "nextFrame" ? this.time.step(1, true) : a === "skipBwd" ? this.time.step(5, false) : a === "skipFwd" ? this.time.step(5, true) : a === "rewind" ? this.time.rewind() : a === "playPause" ? this.time[s.paused ? "play" : "pause"]() : a === "clrHistory" ? this.time.clear() : a === "closeOverlay" ? this.state.open = false : a === "export" ? this.state.import = this.time.export() : a === "import" ? this.state.import.trim().length && this.time.import(this.state.import) : a === "clear" && (this.state.import = "");
     };
     window.addEventListener("keydown", this.keyup);
     const sync = [
@@ -1231,26 +1218,19 @@ var TimeTravelOverlay = class _TimeTravelOverlay {
         const dock = getDock(this.config.container);
         if (host.parentNode !== dock) dock.appendChild(host);
       }),
-      effect(() => (toggle.textContent = `${this.state.open ? "Hide" : "Show"} ${this.config.title ?? ""}`, panel.hidden = !this.state.open)),
+      effect(() => toggle.textContent = `${(panel.hidden = !this.state.open) ? "Show" : "Hide"} ${title.textContent = this.config.title ?? ""}`),
+      effect(() => playPause.textContent = `${s.paused ? "Play" : "Pause"}${formatKeyForDisplay(keys.shortcuts.playPause)}`),
       effect(() => {
-        title.textContent = this.config.title ?? "";
-        frame.textContent = `Frame: ${this.time.state.currentFrame} / ${this.time.state.history.length}`;
-        history.textContent = `History: ${this.time.state.history.length}`;
-        paused.textContent = `Paused: ${this.time.state.paused ? "Yes" : "No"}`;
-        playPause.textContent = `${this.time.state.paused ? "Play" : "Pause"}${formatKeyForDisplay(keys.shortcuts.playPause)}`;
+        frame.textContent = `Frame: ${s.currentFrame} / ${s.history.length}`;
+        range.disabled = clrHistory.disabled = !s.history.length;
+        genesis.disabled = rewind.disabled = undo.disabled = !s.currentFrame;
+        playPause.disabled = redo.disabled = s.currentFrame >= s.history.length;
+        range.max = String(s.history.length);
+        range.value = String(Math.min(s.currentFrame, s.history.length));
+        payload.value = JSON.stringify(s.currentFrame ? s.history[s.currentFrame - 1] : { type: "genesis", value: s.initialState }, null, 2);
       }),
       effect(() => {
-        clrHistory.disabled = !this.time.state.history.length;
-        undo.disabled = this.time.state.currentFrame <= 0;
-        redo.disabled = this.time.state.currentFrame >= this.time.state.history.length;
-        genesis.disabled = this.time.state.currentFrame <= 0;
-        playPause.disabled = this.time.state.currentFrame === this.time.state.history.length;
-        rewind.disabled = !this.time.state.currentFrame;
-        range.max = String(this.time.state.history.length);
-        range.value = String(Math.min(this.time.state.currentFrame, this.time.state.history.length));
-        range.disabled = !this.time.state.history.length;
-        imp.disabled = !this.state.import.trim().length;
-        clr.disabled = !this.state.import.trim().length;
+        clr.disabled = imp.disabled = !this.state.import.trim().length;
         io.value !== this.state.import && (io.value = this.state.import);
       })
     ];
@@ -1277,12 +1257,12 @@ function getDock(container) {
 
 // src/ts/adapters/react/TimeTravelOverlay.tsx
 function TimeTravelOverlay2(props) {
-  const vRef = (0, import_react5.useRef)(null), { time, title, color = "", devOnly = true, startOpen = false, container = document.body } = props;
-  (0, import_react5.useEffect)(() => {
+  const vRef = (0, import_react5.useRef)(null), { time, title, color, devOnly, startOpen, container } = props;
+  useISOLayoutEffect(() => {
     vRef.current = new TimeTravelOverlay(time, props);
     return () => void (vRef.current?.destroy(), vRef.current = null);
   }, [time]);
-  useISOLayoutEffect(() => void (vRef.current && (title !== void 0 && (vRef.current.config.title = title), vRef.current.config.color = color, vRef.current.config.devOnly = devOnly, vRef.current.config.container = container ?? document.body, vRef.current.state.open = startOpen)), [title, color, devOnly, container, startOpen]);
+  useISOLayoutEffect(() => void (vRef.current && (title !== void 0 && (vRef.current.config.title = title), vRef.current.config.color = color, vRef.current.config.devOnly = devOnly, vRef.current.config.container = container, vRef.current.state.open = startOpen)), [title, color, devOnly, container, startOpen]);
   return null;
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1293,5 +1273,7 @@ function TimeTravelOverlay2(props) {
   useISOLayoutEffect,
   usePath,
   useReactor,
-  useSelector
+  useReactorSnapshot,
+  useSelector,
+  useSelectorSnapshot
 });

package/dist/adapters/react.d.cts

@@ -1,7 +1,7 @@
-import { E as EffectOptions, b as Reactor, R as Reactive, o as ReactorBuild, W as WildPaths, q as PathValue } from '../index-DCG3sacH.cjs';
+import { E as EffectOptions, b as Reactor, R as Reactive, o as ReactorBuild, W as WildPaths, q as PathValue } from '../index-Oie9hhE8.cjs';
 import { useLayoutEffect } from 'react';
-import { T as TimeTravelPlugin } from '../timeTravel-L8CEhHIo.cjs';
-import { T as TimeTravelConfig } from '../TimeTravelOverlay-BYSnHBXx.cjs';
+import { T as TimeTravelPlugin } from '../timeTravel-WpgWmKu-.cjs';
+import { T as TimeTravelConfig } from '../TimeTravelOverlay-CJv-S_Km.cjs';
 
 /**
  * Subscribes a component to desired Reactor state and returns it.
@@ -12,7 +12,7 @@ import { T as TimeTravelConfig } from '../TimeTravelOverlay-BYSnHBXx.cjs';
  * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
  * @returns State for render usage if state is scoped locally or just desired.
  * @example
- * const a = useReactor({ user: { name: "Ada" } });
+ * const a = useReactor({ user: { name: "Ada" } }); // per-component scoped
  * @example
  * const state = reactive({ user: { name: "Ada" } });
  * const b = useReactor(state);
@@ -29,6 +29,25 @@ declare function useReactor<T extends object>(target: T | Reactor<T> | Reactive<
  * useAnyReactor();
  */
 declare function useAnyReactor(options?: EffectOptions): void;
+/**
+ * Subscribes a component to Reactor state and returns a tracked snapshot.
+ * Rule of thumb: read from snapshots, mutate the source.
+ * The hook uses access tracking so re-renders occur only when accessed fields change.
+ * @typeParam T Root state object type.
+ * @param target Reactive object, Reactor instance, or plain object.
+ * @param options Watcher options if `options.sync: false` else Listener options.
+ * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
+ * @returns Tracked snapshot snap for render usage.
+ * @example
+ * const a = useReactorSnapshot({ user: { name: "Ada" } }); // per-component scoped
+ * @example
+ * const state = reactive({ user: { name: "Ada" } });
+ * const b = useReactorSnapshot(state);
+ * @example
+ * const rtr = new Reactor({ user: { name: "Ada" } });
+ * const c = useReactorSnapshot(rtr);
+ */
+declare function useReactorSnapshot<T extends object>(target: T | Reactor<T> | Reactive<T>, options?: EffectOptions, build?: ReactorBuild<T>): T;
 
 /**
  * Subscribes to a derived slice of Reactor state.
@@ -43,7 +62,7 @@ declare function useAnyReactor(options?: EffectOptions): void;
  * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
  * @returns The selected slice.
  * @example
- * const a = useSelector({ user: { name: "Ada" } }, (s) => s.user.name);
+ * const a = useSelector({ user: { name: "Ada" } }, (s) => s.user.name); // per-component scoped
  * @example
  * const state = reactive({ user: { name: "Ada" } });
  * const b = useSelector(state, (s) => s.user.name);
@@ -63,6 +82,28 @@ declare function useSelector<T extends object, R>(target: T | Reactor<T> | React
  * @returns The selected slice.
  */
 declare function useAnySelector<R>(sel: () => R, eq?: (value1: any, value2: any) => boolean, options?: EffectOptions): R;
+/**
+ * Subscribes to a derived slice of Reactor state.
+ * The selector runs against a tracked snapshot and uses the provided equality function
+ * to suppress unchanged results.
+ * @typeParam T Root state object type.
+ * @typeParam R Selector return type.
+ * @param target Reactive object, Reactor instance, or plain object.
+ * @param sel Slice selector.
+ * @param eq Equality function used to compare consecutive selector results.
+ * @param options Watcher options if `options.sync: false` else Listener options.
+ * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
+ * @returns The selected slice.
+ * @example
+ * const a = useSelectorSnapshot({ user: { name: "Ada" } }, (s) => s.user.name); // per-component scoped
+ * @example
+ * const state = reactive({ user: { name: "Ada" } });
+ * const b = useSelectorSnapshot(state, (s) => s.user.name);
+ * @example
+ * const rtr = new Reactor({ user: { name: "Ada" } });
+ * const c = useSelectorSnapshot(rtr, (s) => s.user.name);
+ */
+declare function useSelectorSnapshot<T extends object, R>(target: T | Reactor<T> | Reactive<T>, sel: (state: T) => R, eq?: (value1: any, value2: any) => boolean, options?: EffectOptions, build?: ReactorBuild<T>): R;
 
 /**
  * Subscribes to a single path in Reactor state.
@@ -102,4 +143,4 @@ interface TimeTravelOverlayProps extends Partial<TimeTravelConfig> {
  */
 declare function TimeTravelOverlay(props: TimeTravelOverlayProps): null;
 
-export { TimeTravelOverlay, type TimeTravelOverlayProps, useAnyReactor, useAnySelector, useISOLayoutEffect, usePath, useReactor, useSelector };
+export { TimeTravelOverlay, type TimeTravelOverlayProps, useAnyReactor, useAnySelector, useISOLayoutEffect, usePath, useReactor, useReactorSnapshot, useSelector, useSelectorSnapshot };

package/dist/adapters/react.d.ts

@@ -1,7 +1,7 @@
-import { E as EffectOptions, b as Reactor, R as Reactive, o as ReactorBuild, W as WildPaths, q as PathValue } from '../index-DCG3sacH.js';
+import { E as EffectOptions, b as Reactor, R as Reactive, o as ReactorBuild, W as WildPaths, q as PathValue } from '../index-Oie9hhE8.js';
 import { useLayoutEffect } from 'react';
-import { T as TimeTravelPlugin } from '../timeTravel-Bv_u5M1D.js';
-import { T as TimeTravelConfig } from '../TimeTravelOverlay-DoNrZwvX.js';
+import { T as TimeTravelPlugin } from '../timeTravel-B1vedDQc.js';
+import { T as TimeTravelConfig } from '../TimeTravelOverlay-DxqJL0Zk.js';
 
 /**
  * Subscribes a component to desired Reactor state and returns it.
@@ -12,7 +12,7 @@ import { T as TimeTravelConfig } from '../TimeTravelOverlay-DoNrZwvX.js';
  * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
  * @returns State for render usage if state is scoped locally or just desired.
  * @example
- * const a = useReactor({ user: { name: "Ada" } });
+ * const a = useReactor({ user: { name: "Ada" } }); // per-component scoped
  * @example
  * const state = reactive({ user: { name: "Ada" } });
  * const b = useReactor(state);
@@ -29,6 +29,25 @@ declare function useReactor<T extends object>(target: T | Reactor<T> | Reactive<
  * useAnyReactor();
  */
 declare function useAnyReactor(options?: EffectOptions): void;
+/**
+ * Subscribes a component to Reactor state and returns a tracked snapshot.
+ * Rule of thumb: read from snapshots, mutate the source.
+ * The hook uses access tracking so re-renders occur only when accessed fields change.
+ * @typeParam T Root state object type.
+ * @param target Reactive object, Reactor instance, or plain object.
+ * @param options Watcher options if `options.sync: false` else Listener options.
+ * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
+ * @returns Tracked snapshot snap for render usage.
+ * @example
+ * const a = useReactorSnapshot({ user: { name: "Ada" } }); // per-component scoped
+ * @example
+ * const state = reactive({ user: { name: "Ada" } });
+ * const b = useReactorSnapshot(state);
+ * @example
+ * const rtr = new Reactor({ user: { name: "Ada" } });
+ * const c = useReactorSnapshot(rtr);
+ */
+declare function useReactorSnapshot<T extends object>(target: T | Reactor<T> | Reactive<T>, options?: EffectOptions, build?: ReactorBuild<T>): T;
 
 /**
  * Subscribes to a derived slice of Reactor state.
@@ -43,7 +62,7 @@ declare function useAnyReactor(options?: EffectOptions): void;
  * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
  * @returns The selected slice.
  * @example
- * const a = useSelector({ user: { name: "Ada" } }, (s) => s.user.name);
+ * const a = useSelector({ user: { name: "Ada" } }, (s) => s.user.name); // per-component scoped
  * @example
  * const state = reactive({ user: { name: "Ada" } });
  * const b = useSelector(state, (s) => s.user.name);
@@ -63,6 +82,28 @@ declare function useSelector<T extends object, R>(target: T | Reactor<T> | React
  * @returns The selected slice.
  */
 declare function useAnySelector<R>(sel: () => R, eq?: (value1: any, value2: any) => boolean, options?: EffectOptions): R;
+/**
+ * Subscribes to a derived slice of Reactor state.
+ * The selector runs against a tracked snapshot and uses the provided equality function
+ * to suppress unchanged results.
+ * @typeParam T Root state object type.
+ * @typeParam R Selector return type.
+ * @param target Reactive object, Reactor instance, or plain object.
+ * @param sel Slice selector.
+ * @param eq Equality function used to compare consecutive selector results.
+ * @param options Watcher options if `options.sync: false` else Listener options.
+ * @param build Optional Reactor build options used when creating a scoped Reactor for plain objects.
+ * @returns The selected slice.
+ * @example
+ * const a = useSelectorSnapshot({ user: { name: "Ada" } }, (s) => s.user.name); // per-component scoped
+ * @example
+ * const state = reactive({ user: { name: "Ada" } });
+ * const b = useSelectorSnapshot(state, (s) => s.user.name);
+ * @example
+ * const rtr = new Reactor({ user: { name: "Ada" } });
+ * const c = useSelectorSnapshot(rtr, (s) => s.user.name);
+ */
+declare function useSelectorSnapshot<T extends object, R>(target: T | Reactor<T> | Reactive<T>, sel: (state: T) => R, eq?: (value1: any, value2: any) => boolean, options?: EffectOptions, build?: ReactorBuild<T>): R;
 
 /**
  * Subscribes to a single path in Reactor state.
@@ -102,4 +143,4 @@ interface TimeTravelOverlayProps extends Partial<TimeTravelConfig> {
  */
 declare function TimeTravelOverlay(props: TimeTravelOverlayProps): null;
 
-export { TimeTravelOverlay, type TimeTravelOverlayProps, useAnyReactor, useAnySelector, useISOLayoutEffect, usePath, useReactor, useSelector };
+export { TimeTravelOverlay, type TimeTravelOverlayProps, useAnyReactor, useAnySelector, useISOLayoutEffect, usePath, useReactor, useReactorSnapshot, useSelector, useSelectorSnapshot };