@buoy-gg/shared-ui 7.0.32 → 7.0.34

package/lib/module/hooks/useChangeLog.js

@@ -0,0 +1,50 @@
+"use strict";
+
+/**
+ * React bindings for `ChangeLog` — what useReduxActions, useZustandStateChanges
+ * and useJotaiAtomChanges each re-derived: seed state from the log, subscribe
+ * for the lifetime of the component, hold a filter, memoize the filtered
+ * list, and expose clear / pause / lookup.
+ *
+ * Tool-specific stats and registries (stores, atoms) compose on top — see
+ * `useSubscribedValue` for the registry half.
+ */
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+export function useChangeLog(log, options = {}) {
+  const [items, setItems] = useState(() => log.getAll());
+  const [filter, setFilter] = useState(() => options.initialFilter ?? {});
+  const [isEnabled, setIsEnabled] = useState(() => log.getEnabled());
+  useEffect(() => log.subscribe(setItems), [log]);
+  const filterItems = options.filterItems;
+  const filteredItems = useMemo(() => filterItems ? filterItems(items, filter) : items, [items, filter, filterItems]);
+  const clear = useCallback(() => {
+    log.clear();
+  }, [log]);
+  const toggleCapture = useCallback(() => {
+    const next = !isEnabled;
+    log.setEnabled(next);
+    setIsEnabled(next);
+  }, [log, isEnabled]);
+  const getById = useCallback(id => log.getById(id), [log]);
+  return {
+    items,
+    filteredItems,
+    filter,
+    setFilter,
+    isEnabled,
+    toggleCapture,
+    clear,
+    getById
+  };
+}
+
+/**
+ * Hold a value that a store pushes through a `(value) => void` listener —
+ * a registry of stores, atoms, sources. Seeded synchronously from `read`.
+ */
+export function useSubscribedValue(read, subscribe) {
+  const [value, setValue] = useState(read);
+  useEffect(() => subscribe(setValue), [subscribe]);
+  return value;
+}

package/lib/module/hooks/useEventStoreEvents.js

@@ -0,0 +1,61 @@
+"use strict";
+
+/**
+ * React bindings for a `BaseEventStore` — what useRouteEvents and
+ * useStorageEvents each hand-rolled: subscribe while enabled (which
+ * auto-starts the store's capture), coalesce bursts onto one animation
+ * frame so a storm of writes is one commit instead of one per emission,
+ * select/limit the list, and report whether capture is live.
+ */
+
+import { useCallback, useEffect, useState } from "react";
+export function useEventStoreEvents(store, options = {}) {
+  const {
+    enabled = true,
+    maxEvents = 500,
+    select
+  } = options;
+  const [events, setEvents] = useState([]);
+  // Tracked locally so it updates reactively with the subscription.
+  const [isActive, setIsActive] = useState(enabled);
+  useEffect(() => {
+    if (!enabled) {
+      setIsActive(false);
+      return;
+    }
+
+    // Frame-coalesced: bursts land as ONE commit per frame instead of one
+    // per emission — the dominant live-churn cost measured on the network
+    // tool (tool-bench 2026-07-06).
+    let rafId = null;
+    let pending = null;
+    const unsubscribe = store.subscribeToEvents(all => {
+      pending = all;
+      if (rafId != null) return;
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        if (!pending) return;
+        let next = pending;
+        pending = null;
+        if (select) next = select(next);
+        if (next.length > maxEvents) next = next.slice(0, maxEvents);
+        setEvents(next);
+      });
+    });
+    setIsActive(true);
+    return () => {
+      unsubscribe();
+      if (rafId != null) cancelAnimationFrame(rafId);
+      // Not setting isActive=false here: a dependency change re-subscribes
+      // immediately, and that is not "stopped".
+    };
+  }, [store, enabled, maxEvents, select]);
+  const clearEvents = useCallback(() => {
+    store.clearEvents();
+  }, [store]);
+  return {
+    events,
+    clearEvents,
+    isActive
+  };
+}

package/lib/module/hooks/usePersistedState.js

@@ -10,25 +10,43 @@ import { persistentStorage } from "../utils/persistentStorage.js";
  */
 const hydratedCache = new Map();
 
+/** The two calls a backend needs. `persistentStorage` and AsyncStorage both fit. */
+
+function defaultParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * `useState` persisted through `persistentStorage` (FileSystem → AsyncStorage
  * → memory). Replaces the load-then-`hasLoaded`-guard `useEffect` pattern
  * every tool used to hand-roll.
  *
- * Values are JSON-serialized; the default is returned until hydration
- * completes (subsequent mounts of the same key hydrate synchronously from an
- * in-memory cache). The third tuple element reports hydration so callers can
- * defer writes that must not clobber a not-yet-loaded value.
+ * Values are JSON-serialized by default; the default is returned until
+ * hydration completes (subsequent mounts of the same key hydrate synchronously
+ * from an in-memory cache). The third tuple element reports hydration so
+ * callers can defer writes that must not clobber a not-yet-loaded value.
  *
  * ```tsx
  * const [tab, setTab, tabHydrated] = usePersistedState("@react_buoy_custom_flags_tab", "flags");
+ *
+ * // A Set, stored as an array:
+ * const [pins, setPins] = usePersistedState(key, new Set<string>(), {
+ *   parse: (raw) => new Set(JSON.parse(raw) as string[]),
+ *   serialize: (set) => JSON.stringify([...set]),
+ * });
  * ```
  */
-export function usePersistedState(key, defaultValue) {
+export function usePersistedState(key, defaultValue, options = {}) {
   const [value, setValue] = useState(() => hydratedCache.has(key) ? hydratedCache.get(key) : defaultValue);
   const [hydrated, setHydrated] = useState(() => hydratedCache.has(key));
   const keyRef = useRef(key);
   keyRef.current = key;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
   useEffect(() => {
     if (hydratedCache.has(key)) {
       setValue(hydratedCache.get(key));
@@ -36,17 +54,22 @@ export function usePersistedState(key, defaultValue) {
       return;
     }
     let cancelled = false;
-    persistentStorage.getItem(key).then(raw => {
+    const storage = optionsRef.current.storage ?? persistentStorage;
+    const parse = optionsRef.current.parse ?? defaultParse;
+    storage.getItem(key).then(raw => {
       if (cancelled) return;
       if (raw != null) {
+        let parsed;
         try {
-          const parsed = JSON.parse(raw);
-          hydratedCache.set(key, parsed);
-          setValue(parsed);
+          parsed = parse(raw);
         } catch {
           // Corrupt payload — fall back to the default and let the next
           // write repair it.
         }
+        if (parsed !== undefined) {
+          hydratedCache.set(key, parsed);
+          setValue(parsed);
+        }
       }
       setHydrated(true);
     }).catch(() => {
@@ -60,9 +83,20 @@ export function usePersistedState(key, defaultValue) {
     setValue(prev => {
       const resolved = typeof next === "function" ? next(prev) : next;
       hydratedCache.set(keyRef.current, resolved);
-      persistentStorage.setItem(keyRef.current, JSON.stringify(resolved)).catch(() => {});
+      const storage = optionsRef.current.storage ?? persistentStorage;
+      const serialize = optionsRef.current.serialize ?? JSON.stringify;
+      try {
+        storage.setItem(keyRef.current, serialize(resolved)).catch(() => {});
+      } catch {
+        // Unserializable value — keep it in memory, skip the write.
+      }
       return resolved;
     });
   }, []);
   return [value, set, hydrated];
+}
+
+/** Test seam: forget every hydrated value. */
+export function resetPersistedStateCache() {
+  hydratedCache.clear();
 }

package/lib/module/index.js

@@ -6,6 +6,10 @@ export * from "./ui/index.js";
 // Store base classes
 export * from "./stores/index.js";
 export * from "./sync/wireBudget.js";
+export * from "./sync/wireForm.js";
+export * from "./sync/toolSyncAdapter.js";
+// Typed tool presets + derived createXTool factories (structurally InstalledApp)
+export * from "./tools/defineTool.js";
 export * from "./sync/toolActionRegistry.js";
 export * from "./sync/toolUiBridge.js";
 
@@ -44,6 +48,12 @@ Subscribable,
 subscriberCountNotifier, subscribeToSubscriberCountChanges, notifySubscriberCountChange,
 // Safe expo-router wrappers (falls back to no-ops on RN CLI)
 useSafeRouter, useSafePathname, useSafeSegments, useSafeGlobalSearchParams, getSafeRouter, getSafeCurrentPathname, getSafeCurrentRoute, isExpoRouterAvailable } from "./utils/index.js";
+// Time Machine snapshot-provider kit (restore scope, verdict ladder, result shapes)
+export { PREVIEW_ITEM_RENDER_BYTE_LIMIT, createRestoreScope, emptyRestoreResult, failedRestore, skippedRestore, classifyPreviewItem, wontApply, unionKeys } from "./utils/snapshotProviderKit.js";
+
+// State-tool helpers (entity colors, value previews, shallow diff summaries)
+export { entityColor, formatValuePreview, shallowDiffSummary } from "./utils/stateTools.js";
+
 // Also export formatting utils
 export * from "./utils/formatting/index.js";
 export * from "./utils/time/index.js";
@@ -59,7 +69,7 @@ export * from "./clipboard/index.js";
 export * from "./logger/index.js";
 export * from "./settings/index.js";
 export * from "./storage/index.js";
-export { useSafeAreaInsets, useFilterManager, usePersistedState, useDeviceInfo, getDeviceInfo, logDeviceInfo } from "./hooks/index.js";
+export { useSafeAreaInsets, useFilterManager, usePersistedState, resetPersistedStateCache, useChangeLog, useSubscribedValue, useEventStoreEvents, useDeviceInfo, getDeviceInfo, logDeviceInfo } from "./hooks/index.js";
 
 // JsModal
 export { JsModal } from "./JsModal";

package/lib/module/storage/definePersistedSetting.js

@@ -0,0 +1,63 @@
+"use strict";
+
+/**
+ * definePersistedSetting — the `load / save / clear` triple every tool wrote
+ * for its module-level settings (copy settings, HUD prefs, JS TOP prefs, …).
+ *
+ * Contract, the same one all of them followed:
+ *  - `load()` never throws and never returns a partial object: the stored
+ *    value is merged OVER the defaults so fields added in a later release
+ *    get their default instead of `undefined`, then `sanitize` gets the last
+ *    word (drop values the UI no longer offers, coerce types).
+ *  - `save()` and `clear()` are best-effort; persistence is optional.
+ *  - `loadOrNull()` distinguishes "nothing saved yet" from the defaults, for
+ *    callers that treat first launch differently.
+ */
+
+import { persistentStorage } from "../utils/persistentStorage.js";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function definePersistedSetting(key, defaults, options = {}) {
+  const storage = options.storage ?? persistentStorage;
+  const parse = options.parse ?? (raw => JSON.parse(raw));
+  const serialize = options.serialize ?? (value => JSON.stringify(value));
+  function resolve(stored) {
+    const merged = isPlainObject(defaults) && isPlainObject(stored) ? {
+      ...defaults,
+      ...stored
+    } : stored;
+    return options.sanitize ? options.sanitize(merged, stored) : merged;
+  }
+  async function loadOrNull() {
+    try {
+      const raw = await storage.getItem(key);
+      if (raw == null || raw === "") return null;
+      return resolve(parse(raw));
+    } catch {
+      return null;
+    }
+  }
+  return {
+    key,
+    defaults,
+    loadOrNull,
+    async load() {
+      return (await loadOrNull()) ?? defaults;
+    },
+    async save(value) {
+      try {
+        await storage.setItem(key, serialize(value));
+      } catch {
+        // Persistence is best-effort.
+      }
+    },
+    async clear() {
+      try {
+        await storage.removeItem(key);
+      } catch {
+        // Persistence is best-effort.
+      }
+    }
+  };
+}

package/lib/module/storage/devToolsStorageKeys.js

@@ -250,6 +250,18 @@ export const devToolsStorageKeys = {
     pausedAt: () => `${devToolsStorageKeys.events.root()}_paused_at`,
     /** Copy/export settings */
     copySettings: () => `${devToolsStorageKeys.events.root()}_copy_settings`
+  },
+  /**
+   * Desktop/MCP sync identity
+   */
+  sync: {
+    root: () => `${devToolsStorageKeys.base}_sync`,
+    /**
+     * The per-install id minted the first time this app dials the broker.
+     * It is what makes two devices on the same build register as two
+     * devices — see core's deviceIdentity.ts.
+     */
+    deviceId: () => `${devToolsStorageKeys.sync.root()}_device_id`
   }
 };
 

package/lib/module/storage/index.js

@@ -1,3 +1,4 @@
 "use strict";
 
-export { devToolsStorageKeys, isDevToolsStorageKey } from "./devToolsStorageKeys.js";
+export { devToolsStorageKeys, isDevToolsStorageKey } from "./devToolsStorageKeys.js";
+export { definePersistedSetting } from "./definePersistedSetting.js";

package/lib/module/stores/ChangeLog.js

@@ -0,0 +1,192 @@
+"use strict";
+
+/**
+ * ChangeLog — the class-shaped event log the state tools share.
+ *
+ * redux (`ReduxActionStore`), zustand (`ZustandStateStore`), jotai
+ * (`JotaiStateStore`) and react-query (`ReactQueryEventStore`) each carried
+ * the same ~120 lines: a newest-first ring buffer, a `Set` of array listeners
+ * (`(items) => void`), a `Set` of clear listeners for the desktop's mirror
+ * mode, an `enabled` flag (the UI's pause button), a `captureSuppressed` flag
+ * (the dashboard must never record its own traffic), a monotonic id counter,
+ * `getById`, and hydrate-by-id for lazily fetched detail payloads.
+ *
+ * This is that core. Tool stores `extend` it and keep their public method
+ * names (`addStateChange`, `getActions`, `clearAtomChanges`, …) as thin
+ * wrappers, so no call site — including Buoy Desktop — has to change.
+ *
+ * Semantics preserved from the originals, deliberately:
+ * - `getAll()` returns a COPY (`[...items]`) — consumers seed React state
+ *   from it and rely on a fresh identity per notification.
+ * - `clear()` always notifies, even when already empty, then fires the clear
+ *   listeners (the dashboard forwards the clear to the device either way).
+ * - `replaceAll()` respects `enabled`: the pause button freezes a mirror.
+ * - `disableCapture()` is permanent for the store's lifetime.
+ */
+
+export class ChangeLog {
+  /** Newest first. Subclasses may read; mutate only through the helpers. */
+  items = [];
+  itemListeners = new Set();
+  clearListeners = new Set();
+  idCounter = 0;
+  enabled = true;
+  captureSuppressed = false;
+  constructor(options = {}) {
+    this.max = options.max ?? 200;
+  }
+
+  // ---- Recording ----
+
+  /** True when a new item should be recorded (not paused, not a mirror). */
+  canRecord() {
+    return this.enabled && !this.captureSuppressed;
+  }
+
+  /** `${Date.now()}-${n}` — unique per store instance, sorts by time. */
+  nextId() {
+    return `${Date.now()}-${++this.idCounter}`;
+  }
+
+  /**
+   * Prepend one item and trim to `max`. Does NOT notify — subclasses often
+   * touch companion state (per-entity counters, raw-state eviction) before
+   * they notify. Call `notifyListeners()` when done, or use `record()`.
+   */
+  push(item) {
+    this.items = [item, ...this.items].slice(0, this.max);
+  }
+
+  /** `push()` + notify. The common case. */
+  record(item) {
+    this.push(item);
+    this.notifyListeners();
+  }
+
+  /** Replace the buffer wholesale (already merged/hydrated by the caller) and notify. */
+  setItems(next) {
+    this.items = next.slice(0, this.max);
+    this.notifyListeners();
+  }
+
+  // ---- Reading ----
+
+  /** All items, newest first. Fresh array each call. */
+  getAll() {
+    return [...this.items];
+  }
+  getById(id) {
+    return this.items.find(item => item.id === id);
+  }
+  get size() {
+    return this.items.length;
+  }
+
+  // ---- Clearing ----
+
+  /**
+   * Empty the buffer, notify, then fire clear listeners. Always notifies —
+   * a clear is a user action and the list must repaint even if nothing was
+   * in it. Subclasses that keep companion counters reset them first.
+   */
+  clear() {
+    this.items = [];
+    this.notifyListeners();
+    this.clearListeners.forEach(listener => {
+      try {
+        listener();
+      } catch {
+        // Ignore listener errors
+      }
+    });
+  }
+
+  /**
+   * Listen for `clear()` calls. Used in remote mirror mode to forward a
+   * clear performed in the dashboard UI to the synced device.
+   */
+  onClear(listener) {
+    this.clearListeners.add(listener);
+    return () => {
+      this.clearListeners.delete(listener);
+    };
+  }
+
+  // ---- Remote mirror mode ----
+
+  /**
+   * Permanently suppress local capture. Use when this store acts as a mirror
+   * of a remote device (the desktop dashboard): data arrives via
+   * `replaceAll()` / a subclass snapshot method and local instrumentation
+   * must never record.
+   */
+  disableCapture() {
+    this.captureSuppressed = true;
+  }
+
+  /** Whether the store is in remote mirror mode (capture suppressed). */
+  isCaptureSuppressed() {
+    return this.captureSuppressed;
+  }
+
+  /**
+   * Replace the whole list from a remote snapshot and notify. Respects the
+   * enabled flag so the UI's pause button freezes the mirror. Returns false
+   * when skipped. Subclasses with hydration-preserving merges compute the
+   * merged list themselves and call `setItems()`.
+   */
+  replaceAll(next) {
+    if (!this.enabled) return false;
+    this.setItems(next);
+    return true;
+  }
+
+  /**
+   * Patch one item in place (by id) and notify. Used to hydrate a mirrored
+   * item with detail payloads fetched on demand from the device.
+   */
+  hydrateById(id, patch) {
+    const index = this.items.findIndex(item => item.id === id);
+    if (index === -1) return;
+    this.items = [...this.items.slice(0, index), {
+      ...this.items[index],
+      ...patch
+    }, ...this.items.slice(index + 1)];
+    this.notifyListeners();
+  }
+
+  // ---- Enable / disable ----
+
+  setEnabled(enabled) {
+    this.enabled = enabled;
+  }
+  getEnabled() {
+    return this.enabled;
+  }
+  setMax(max) {
+    this.max = max;
+    if (this.items.length > max) {
+      this.items = this.items.slice(0, max);
+      this.notifyListeners();
+    }
+  }
+  getMax() {
+    return this.max;
+  }
+
+  // ---- Subscriptions ----
+
+  subscribe(listener) {
+    this.itemListeners.add(listener);
+    return () => {
+      this.itemListeners.delete(listener);
+    };
+  }
+  notifyListeners() {
+    const items = this.getAll();
+    this.itemListeners.forEach(listener => listener(items));
+  }
+  get listenerCount() {
+    return this.itemListeners.size;
+  }
+}

package/lib/module/stores/createToolStore.js

@@ -0,0 +1,171 @@
+"use strict";
+
+/**
+ * createToolStore — the one bounded, subscribable buffer every tool used to
+ * hand-roll.
+ *
+ * Before this existed, console, sentry, images, assets, focus-inspector,
+ * tv-remote, redux, zustand, jotai and react-query each carried their own copy
+ * of the same ~100 lines: a `Set` of listeners, a `Set` of clear listeners
+ * (so the desktop dashboard can forward a clear to the device in mirror
+ * mode), a ring buffer with a max, an optional frame-coalesced emit, and the
+ * `__buoyFlushToolSync` escape hatch that pushes a tool's snapshot to the
+ * dashboard NOW (a crash's last words must not wait on the sync throttle).
+ *
+ * This is a plain function, not a class, on purpose: every consumer exposes a
+ * module-level functional API (`subscribe`, `getSnapshot`, `clearX`) and
+ * feeds `useSyncExternalStore`, so the store is a value the module wraps
+ * rather than something it extends. `BaseEventStore` stays for the
+ * class-based, auto-start/stop capture stores (network, storage, routes).
+ *
+ * Contract:
+ * - `getSnapshot()` returns the SAME array reference until the next
+ *   mutation, so `useSyncExternalStore` never re-renders for nothing.
+ * - `order: "append"` keeps the newest item LAST (console-style scrollback);
+ *   `order: "prepend"` keeps it FIRST (event-log style). Trimming drops from
+ *   the opposite end. Consumers never have to `.reverse()`.
+ * - `clear()` fires `onClear` listeners even when the buffer is already
+ *   empty — the dashboard's forwarded clear must reach the device regardless.
+ * - `set()` (mirror mode) never fires clear listeners; it is a replacement.
+ */
+
+/** Listener signature: change-only, read the snapshot yourself. */
+
+function scheduleFrame(cb) {
+  if (typeof requestAnimationFrame === "function") {
+    requestAnimationFrame(() => cb());
+  } else {
+    setTimeout(cb, 0);
+  }
+}
+export function createToolStore(options) {
+  const id = options.id;
+  const order = options.order ?? "append";
+  const coalesce = options.coalesce ?? "sync";
+  const flushMinIntervalMs = options.flushMinIntervalMs ?? 150;
+  let max = options.max;
+  let items = [];
+  let paused = false;
+  let nextId = options.firstId ?? 1;
+  let lastFlushAt = 0;
+  let emitScheduled = false;
+  const listeners = new Set();
+  const clearListeners = new Set();
+  function fire() {
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        // A broken subscriber must not take the store (or a crash path) down.
+      }
+    }
+  }
+  function emit() {
+    if (coalesce === "sync") {
+      fire();
+      return;
+    }
+    if (emitScheduled) return;
+    emitScheduled = true;
+    scheduleFrame(() => {
+      emitScheduled = false;
+      fire();
+    });
+  }
+  function trim(list) {
+    if (list.length <= max) return list;
+    return order === "append" ? list.slice(list.length - max) : list.slice(0, max);
+  }
+  const store = {
+    id,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot() {
+      return items;
+    },
+    size() {
+      return items.length;
+    },
+    add(item) {
+      if (paused) return;
+      if (order === "append") {
+        items = items.length >= max ? [...items.slice(items.length - max + 1), item] : [...items, item];
+      } else {
+        items = items.length >= max ? [item, ...items.slice(0, max - 1)] : [item, ...items];
+      }
+      emit();
+    },
+    set(next) {
+      items = trim(next);
+      emit();
+    },
+    update(fn) {
+      items = trim(fn(items));
+      emit();
+    },
+    clear() {
+      for (const listener of clearListeners) {
+        try {
+          listener();
+        } catch {
+          // ignore
+        }
+      }
+      if (items.length === 0) return;
+      items = [];
+      emit();
+    },
+    onClear(listener) {
+      clearListeners.add(listener);
+      return () => {
+        clearListeners.delete(listener);
+      };
+    },
+    notify() {
+      emit();
+    },
+    flushSync(force = false) {
+      const now = Date.now();
+      if (!force && now - lastFlushAt < flushMinIntervalMs) return;
+      lastFlushAt = now;
+      try {
+        const set = globalThis.__buoyFlushToolSync;
+        if (!set) return;
+        for (const flush of set) flush(id);
+      } catch {
+        // Best-effort: a crash path must never crash.
+      }
+    },
+    setPaused(next) {
+      paused = next;
+    },
+    isPaused() {
+      return paused;
+    },
+    setMax(next) {
+      max = next;
+      const trimmed = trim(items);
+      if (trimmed !== items) {
+        items = trimmed;
+        emit();
+      }
+    },
+    getMax() {
+      return max;
+    },
+    allocId() {
+      return nextId++;
+    },
+    bumpIdAbove(idFloor) {
+      if (idFloor + 1 > nextId) nextId = idFloor + 1;
+    },
+    listenerCount() {
+      return listeners.size;
+    }
+  };
+  return store;
+}