@buoy-gg/shared-ui 7.0.16 → 7.0.18

package/lib/commonjs/dataViewer/objectDiff.js

@@ -0,0 +1,304 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.boundedDeepEqual = boundedDeepEqual;
+exports.jsonLikelyLargerThan = jsonLikelyLargerThan;
+exports.objectDiff = objectDiff;
+exports.toDiffable = toDiffable;
+/**
+ * objectDiff — the bounded, cycle-safe diff KERNEL the dataViewer never had.
+ *
+ * Every diff consumer so far either hand-rolled a private summary helper or
+ * fed whole values into the render-layer viewers (which compute eagerly, have
+ * no cycle guards, and mis-compare rich types — TreeDiffViewer treats two
+ * different Dates/Maps/Sets as EQUAL because they have zero own keys).
+ *
+ * This kernel is for VERDICTS and BADGES, not rendering:
+ * - correct equality for Date / RegExp / Map / Set / BigInt / NaN /
+ *   TypedArray / URL / Error, and `undefined`-value vs absent-key
+ * - WeakSet cycle guard (a revisited pair reports unequal-safe truncation,
+ *   never a stack overflow)
+ * - hard depth + node budgets with an explicit `truncated` flag; when the
+ *   budget runs out a subtree is reported as CHANGED (a false "changed" is
+ *   recoverable — a false "unchanged" hides a real difference, the worst
+ *   failure mode for a restore preview)
+ *
+ * `toDiffable` is the companion RENDER normalizer: it converts rich types to
+ * plain-JSON stand-ins so the existing viewers (which only handle plain JSON
+ * faithfully) never see a Date/Map/Set/BigInt/cycle at all.
+ */
+
+function isPlainObjectLike(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function isTypedArray(v) {
+  return ArrayBuffer.isView(v) && !(v instanceof DataView);
+}
+
+/**
+ * Bounded deep equality. Returns false on budget exhaustion (conservative:
+ * report changed rather than hide a change) and marks the budget truncated.
+ */
+function boundedDeepEqual(a, b, options) {
+  const budget = {
+    nodes: options?.maxNodes ?? 2000,
+    truncated: false
+  };
+  return deepEqual(a, b, options?.maxDepth ?? 8, budget, new WeakSet());
+}
+function deepEqual(a, b, depth, budget, seen) {
+  if (budget.nodes-- <= 0) {
+    budget.truncated = true;
+    return false;
+  }
+  // NaN-equal, -0-distinct — Object.is has the right scalar semantics.
+  if (Object.is(a, b)) return true;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object" || a === null || b === null) {
+    // Distinct functions: treated as EQUAL — providers strip/preserve them
+    // and reference inequality across a serialization boundary is pure noise.
+    return typeof a === "function" && typeof b === "function";
+  }
+
+  // Rich types the render-layer viewers get wrong:
+  if (a instanceof Date || b instanceof Date) {
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  }
+  if (a instanceof RegExp || b instanceof RegExp) {
+    return a instanceof RegExp && b instanceof RegExp && a.source === b.source && a.flags === b.flags;
+  }
+  if (a instanceof Error || b instanceof Error) {
+    return a instanceof Error && b instanceof Error && a.name === b.name && a.message === b.message;
+  }
+  if (typeof URL !== "undefined" && (a instanceof URL || b instanceof URL)) {
+    return a instanceof URL && b instanceof URL && a.href === b.href;
+  }
+  if (isTypedArray(a) || isTypedArray(b)) {
+    if (!isTypedArray(a) || !isTypedArray(b)) return false;
+    if (a.constructor !== b.constructor || a.byteLength !== b.byteLength) {
+      return false;
+    }
+    const ua = new Uint8Array(a.buffer, a.byteOffset, a.byteLength);
+    const ub = new Uint8Array(b.buffer, b.byteOffset, b.byteLength);
+    for (let i = 0; i < ua.length; i++) if (ua[i] !== ub[i]) return false;
+    return true;
+  }
+  if (depth <= 0) {
+    budget.truncated = true;
+    return false;
+  }
+  // Cycle guard: a revisited left-side object ends the walk for this branch.
+  // Reporting unequal here is the conservative direction.
+  if (seen.has(a)) {
+    budget.truncated = true;
+    return false;
+  }
+  seen.add(a);
+  if (a instanceof Map || b instanceof Map) {
+    if (!(a instanceof Map) || !(b instanceof Map) || a.size !== b.size) {
+      return false;
+    }
+    // Insertion-order comparison — superjson round-trips preserve it, and
+    // order-insensitive matching with object keys is quadratic.
+    const ea = Array.from(a.entries());
+    const eb = Array.from(b.entries());
+    for (let i = 0; i < ea.length; i++) {
+      if (!deepEqual(ea[i][0], eb[i][0], depth - 1, budget, seen)) return false;
+      if (!deepEqual(ea[i][1], eb[i][1], depth - 1, budget, seen)) return false;
+    }
+    return true;
+  }
+  if (a instanceof Set || b instanceof Set) {
+    if (!(a instanceof Set) || !(b instanceof Set) || a.size !== b.size) {
+      return false;
+    }
+    const va = Array.from(a.values());
+    const vb = Array.from(b.values());
+    for (let i = 0; i < va.length; i++) {
+      if (!deepEqual(va[i], vb[i], depth - 1, budget, seen)) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+      return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i], depth - 1, budget, seen)) return false;
+    }
+    return true;
+  }
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  for (const k of ka) {
+    if (!Object.prototype.hasOwnProperty.call(b, k)) return false;
+    if (!deepEqual(a[k], b[k], depth - 1, budget, seen)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Top-level key diff of two values with bounded deep equality per key.
+ * Non-object inputs degrade to a single implicit "value" comparison.
+ */
+function objectDiff(oldValue, newValue, options) {
+  const maxDepth = options?.maxDepth ?? 8;
+  const budget = {
+    nodes: options?.maxNodes ?? 2000,
+    truncated: false
+  };
+  const oldIsObj = isPlainObjectLike(oldValue);
+  const newIsObj = isPlainObjectLike(newValue);
+  if (!oldIsObj || !newIsObj) {
+    const equal = deepEqual(oldValue, newValue, maxDepth, budget, new WeakSet());
+    return {
+      equal,
+      addedKeys: [],
+      removedKeys: [],
+      changedKeys: equal ? [] : ["value"],
+      truncated: budget.truncated
+    };
+  }
+  const addedKeys = [];
+  const removedKeys = [];
+  const changedKeys = [];
+  const oldObj = oldValue;
+  const newObj = newValue;
+  for (const k of Object.keys(oldObj)) {
+    if (!Object.prototype.hasOwnProperty.call(newObj, k)) {
+      removedKeys.push(k);
+    } else if (!deepEqual(oldObj[k], newObj[k], maxDepth - 1, budget, new WeakSet())) {
+      changedKeys.push(k);
+    }
+  }
+  for (const k of Object.keys(newObj)) {
+    if (!Object.prototype.hasOwnProperty.call(oldObj, k)) addedKeys.push(k);
+  }
+  return {
+    equal: addedKeys.length === 0 && removedKeys.length === 0 && changedKeys.length === 0,
+    addedKeys,
+    removedKeys,
+    changedKeys,
+    truncated: budget.truncated
+  };
+}
+
+// ============================================================================
+// toDiffable — render normalizer
+// ============================================================================
+
+const TO_DIFFABLE_MAX_DEPTH = 12;
+
+/**
+ * Convert a value tree into plain JSON the render-layer diff viewers handle
+ * faithfully. Dates → ISO strings, Maps → objects, Sets → arrays,
+ * BigInt → "123n", TypedArrays/cycles/depth-overflow → placeholder strings.
+ * Functions become "[Function]" (providers have already recorded real ones).
+ */
+function toDiffable(value) {
+  return normalizeForDiff(value, TO_DIFFABLE_MAX_DEPTH, new WeakSet());
+}
+function normalizeForDiff(value, depth, seen) {
+  if (value === null || value === undefined) return value;
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return value;
+  if (t === "number") {
+    return Number.isFinite(value) ? value : String(value);
+  }
+  if (t === "bigint") return `${String(value)}n`;
+  if (t === "function") return "[Function]";
+  if (t === "symbol") return String(value);
+  if (t !== "object") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof RegExp) return String(value);
+  if (value instanceof Error) return `[${value.name}: ${value.message}]`;
+  if (typeof URL !== "undefined" && value instanceof URL) return value.href;
+  if (isTypedArray(value)) {
+    return `<${value.constructor.name} ${value.byteLength} bytes>`;
+  }
+  if (depth <= 0) return "[Max depth]";
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (value instanceof Map) {
+    const out = {};
+    for (const [k, v] of value.entries()) {
+      const key = typeof k === "string" ? k : JSON.stringify(toDiffable(k));
+      out[key] = normalizeForDiff(v, depth - 1, seen);
+    }
+    return out;
+  }
+  if (value instanceof Set) {
+    return Array.from(value.values()).map(v => normalizeForDiff(v, depth - 1, seen));
+  }
+  if (Array.isArray(value)) {
+    return value.map(v => normalizeForDiff(v, depth - 1, seen));
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = normalizeForDiff(v, depth - 1, seen);
+  }
+  return out;
+}
+
+// ============================================================================
+// Size probe — O(limit) early-bail, cycle-safe
+// ============================================================================
+
+/**
+ * True when `value`'s JSON form is likely larger than `limitBytes`. Iterative
+ * walk that bails the moment the running estimate crosses the limit, so cost
+ * is O(limit) regardless of payload size (the redux store's `jsonLongerThan`
+ * lesson: a full stringify per check froze enterprise-scale apps).
+ */
+function jsonLikelyLargerThan(value, limitBytes) {
+  let size = 0;
+  const stack = [value];
+  const seenObjects = new Set();
+  while (stack.length > 0) {
+    const v = stack.pop();
+    if (v === null || v === undefined) {
+      size += 4;
+    } else if (typeof v === "string") {
+      size += v.length + 2;
+    } else if (typeof v === "number" || typeof v === "boolean") {
+      size += 8;
+    } else if (typeof v === "bigint") {
+      size += String(v).length + 1;
+    } else if (typeof v === "object") {
+      if (seenObjects.has(v)) continue;
+      seenObjects.add(v);
+      if (v instanceof Date || v instanceof RegExp) {
+        size += 32;
+      } else if (isTypedArray(v)) {
+        size += v.byteLength;
+      } else if (v instanceof Map) {
+        for (const [k, val] of v.entries()) {
+          stack.push(k, val);
+          size += 4;
+        }
+      } else if (v instanceof Set) {
+        for (const val of v.values()) {
+          stack.push(val);
+          size += 2;
+        }
+      } else if (Array.isArray(v)) {
+        for (const item of v) stack.push(item);
+        size += 2 * v.length + 2;
+      } else {
+        for (const [k, val] of Object.entries(v)) {
+          size += k.length + 4;
+          stack.push(val);
+        }
+      }
+    }
+    if (size > limitBytes) return true;
+  }
+  return false;
+}

package/lib/commonjs/hooks/index.js

@@ -33,6 +33,12 @@ Object.defineProperty(exports, "useFilterManager", {
     return _useFilterManager.useFilterManager;
   }
 });
+Object.defineProperty(exports, "usePersistedState", {
+  enumerable: true,
+  get: function () {
+    return _usePersistedState.usePersistedState;
+  }
+});
 Object.defineProperty(exports, "useSafeAreaInsets", {
   enumerable: true,
   get: function () {
@@ -40,5 +46,6 @@ Object.defineProperty(exports, "useSafeAreaInsets", {
   }
 });
 var _useFilterManager = require("./useFilterManager.js");
+var _usePersistedState = require("./usePersistedState.js");
 var _useSafeAreaInsets = require("./useSafeAreaInsets.js");
 var _useDeviceInfo = require("./useDeviceInfo.js");

package/lib/commonjs/hooks/safe-area-impl.js

@@ -7,7 +7,7 @@ exports.useNativeSafeAreaInsets = exports.safeAreaType = exports.hasSafeAreaPack
 /**
  * Auto-generated safe area implementation
  * Detected: none
- * Generated at: 2026-08-06T20:33:57.771Z
+ * Generated at: 2026-08-14T00:03:32.153Z
  *
  * DO NOT EDIT - This file is generated by scripts/detect-safe-area.js
  *

package/lib/commonjs/hooks/usePersistedState.js

@@ -0,0 +1,71 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePersistedState = usePersistedState;
+var _react = require("react");
+var _persistentStorage = require("../utils/persistentStorage.js");
+/**
+ * Per-key cache so remounts (and multiple consumers of the same key) render
+ * the last-known value immediately instead of flashing the default while the
+ * async backend loads again.
+ */
+const hydratedCache = new Map();
+
+/**
+ * `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.
+ *
+ * ```tsx
+ * const [tab, setTab, tabHydrated] = usePersistedState("@react_buoy_custom_flags_tab", "flags");
+ * ```
+ */
+function usePersistedState(key, defaultValue) {
+  const [value, setValue] = (0, _react.useState)(() => hydratedCache.has(key) ? hydratedCache.get(key) : defaultValue);
+  const [hydrated, setHydrated] = (0, _react.useState)(() => hydratedCache.has(key));
+  const keyRef = (0, _react.useRef)(key);
+  keyRef.current = key;
+  (0, _react.useEffect)(() => {
+    if (hydratedCache.has(key)) {
+      setValue(hydratedCache.get(key));
+      setHydrated(true);
+      return;
+    }
+    let cancelled = false;
+    _persistentStorage.persistentStorage.getItem(key).then(raw => {
+      if (cancelled) return;
+      if (raw != null) {
+        try {
+          const parsed = JSON.parse(raw);
+          hydratedCache.set(key, parsed);
+          setValue(parsed);
+        } catch {
+          // Corrupt payload — fall back to the default and let the next
+          // write repair it.
+        }
+      }
+      setHydrated(true);
+    }).catch(() => {
+      if (!cancelled) setHydrated(true);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [key]);
+  const set = (0, _react.useCallback)(next => {
+    setValue(prev => {
+      const resolved = typeof next === "function" ? next(prev) : next;
+      hydratedCache.set(keyRef.current, resolved);
+      _persistentStorage.persistentStorage.setItem(keyRef.current, JSON.stringify(resolved)).catch(() => {});
+      return resolved;
+    });
+  }, []);
+  return [value, set, hydrated];
+}

package/lib/commonjs/icons/index.js

@@ -10,6 +10,8 @@ var _exportNames = {
   ENV_ICON_COLOR: true,
   ConsoleIcon: true,
   CONSOLE_ICON_COLOR: true,
+  TimeMachineIcon: true,
+  TIME_MACHINE_ICON_COLOR: true,
   ImagesIcon: true,
   IMAGES_ICON_COLOR: true,
   AssetsIcon: true,
@@ -218,6 +220,18 @@ Object.defineProperty(exports, "StorageStackIcon", {
     return _StorageStackIcon.StorageStackIcon;
   }
 });
+Object.defineProperty(exports, "TIME_MACHINE_ICON_COLOR", {
+  enumerable: true,
+  get: function () {
+    return _floatingToolsCore.TIME_MACHINE_ICON_COLOR;
+  }
+});
+Object.defineProperty(exports, "TimeMachineIcon", {
+  enumerable: true,
+  get: function () {
+    return _floatingToolsCore.TimeMachineIcon;
+  }
+});
 Object.defineProperty(exports, "WifiCircuitIcon", {
   enumerable: true,
   get: function () {

package/lib/commonjs/index.js

@@ -29,6 +29,12 @@ var _exportNames = {
   getCachedOptionalModule: true,
   setRenderCaptureProvider: true,
   getRenderCaptureProvider: true,
+  registerStateSnapshotProvider: true,
+  getStateSnapshotProviders: true,
+  getStateSnapshotProvider: true,
+  subscribeToStateSnapshotProviders: true,
+  superJsonSerialize: true,
+  superJsonDeserialize: true,
   reloadApp: true,
   scheduleReloadApp: true,
   resolveReloadStrategy: true,
@@ -47,6 +53,7 @@ var _exportNames = {
   isPlainObjectUtil: true,
   useSafeAreaInsets: true,
   useFilterManager: true,
+  usePersistedState: true,
   useDeviceInfo: true,
   getDeviceInfo: true,
   logDeviceInfo: true,
@@ -248,6 +255,18 @@ Object.defineProperty(exports, "getSafeRouter", {
     return _index3.getSafeRouter;
   }
 });
+Object.defineProperty(exports, "getStateSnapshotProvider", {
+  enumerable: true,
+  get: function () {
+    return _index3.getStateSnapshotProvider;
+  }
+});
+Object.defineProperty(exports, "getStateSnapshotProviders", {
+  enumerable: true,
+  get: function () {
+    return _index3.getStateSnapshotProviders;
+  }
+});
 Object.defineProperty(exports, "getStorageBackendType", {
   enumerable: true,
   get: function () {
@@ -380,6 +399,12 @@ Object.defineProperty(exports, "refreshGameUIColors", {
     return _gameUIColors.refreshGameUIColors;
   }
 });
+Object.defineProperty(exports, "registerStateSnapshotProvider", {
+  enumerable: true,
+  get: function () {
+    return _index3.registerStateSnapshotProvider;
+  }
+});
 Object.defineProperty(exports, "reloadApp", {
   enumerable: true,
   get: function () {
@@ -410,6 +435,12 @@ Object.defineProperty(exports, "setRenderCaptureProvider", {
     return _index3.setRenderCaptureProvider;
   }
 });
+Object.defineProperty(exports, "subscribeToStateSnapshotProviders", {
+  enumerable: true,
+  get: function () {
+    return _index3.subscribeToStateSnapshotProviders;
+  }
+});
 Object.defineProperty(exports, "subscribeToSubscriberCountChanges", {
   enumerable: true,
   get: function () {
@@ -422,6 +453,18 @@ Object.defineProperty(exports, "subscriberCountNotifier", {
     return _index3.subscriberCountNotifier;
   }
 });
+Object.defineProperty(exports, "superJsonDeserialize", {
+  enumerable: true,
+  get: function () {
+    return _index3.superJsonDeserialize;
+  }
+});
+Object.defineProperty(exports, "superJsonSerialize", {
+  enumerable: true,
+  get: function () {
+    return _index3.superJsonSerialize;
+  }
+});
 Object.defineProperty(exports, "truncateText", {
   enumerable: true,
   get: function () {
@@ -458,6 +501,12 @@ Object.defineProperty(exports, "useHintsDisabled", {
     return _index10.useHintsDisabled;
   }
 });
+Object.defineProperty(exports, "usePersistedState", {
+  enumerable: true,
+  get: function () {
+    return _index1.usePersistedState;
+  }
+});
 Object.defineProperty(exports, "useSafeAreaInsets", {
   enumerable: true,
   get: function () {
@@ -512,6 +561,18 @@ Object.keys(_index2).forEach(function (key) {
     }
   });
 });
+var _wireBudget = require("./sync/wireBudget.js");
+Object.keys(_wireBudget).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _wireBudget[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _wireBudget[key];
+    }
+  });
+});
 var _index3 = require("./utils/index.js");
 var _index4 = require("./utils/formatting/index.js");
 Object.keys(_index4).forEach(function (key) {

package/lib/commonjs/storage/devToolsStorageKeys.js

@@ -38,6 +38,28 @@ const devToolsStorageKeys = exports.devToolsStorageKeys = {
     dimensions: () => `${devToolsStorageKeys.modal.root()}_dimensions`,
     hintAcknowledged: () => `${devToolsStorageKeys.modal.root()}_hint_acknowledged`
   },
+  /**
+   * Namespace factory for third-party custom tools. Keys share the
+   * `@react_buoy` prefix, so `isDevToolsStorageKey` filtering (and the Storage
+   * tool's internal-key handling) covers custom-tool persistence for free.
+   *
+   * ```ts
+   * const keys = devToolsStorageKeys.custom("feature-flags");
+   * keys.modal();          // "@react_buoy_custom_feature-flags_modal"
+   * keys.key("overrides"); // "@react_buoy_custom_feature-flags_overrides"
+   * ```
+   */
+  custom: toolId => {
+    const root = `${devToolsStorageKeys.base}_custom_${toolId}`;
+    return {
+      root: () => root,
+      /** JsModal `persistenceKey` for this tool's window dimensions. */
+      modal: () => `${root}_modal`,
+      settings: () => `${root}_settings`,
+      /** Arbitrary tool-scoped key. */
+      key: suffix => `${root}_${suffix}`
+    };
+  },
   /**
    * Settings-related storage keys
    */
@@ -104,6 +126,15 @@ const devToolsStorageKeys = exports.devToolsStorageKeys = {
     isMonitoring: () => `${devToolsStorageKeys.storage.root()}_is_monitoring`,
     diffViewerMode: () => `${devToolsStorageKeys.storage.root()}_diff_viewer_mode` // 'split' | 'tree'
   },
+  /**
+   * Time Machine storage keys. NOTE: the snapshot VAULT keys
+   * (`@react_buoy_time_machine:index` / `:snap:*`) predate this namespace and
+   * stay as-is — only preferences live here.
+   */
+  timeMachine: {
+    root: () => `${devToolsStorageKeys.base}_time_machine`,
+    diffViewerMode: () => `${devToolsStorageKeys.timeMachine.root()}_diff_viewer_mode` // 'split' | 'tree'
+  },
   /**
    * React Query-related storage keys
    */

package/lib/commonjs/sync/wireBudget.js

@@ -0,0 +1,97 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.approxJsonSize = approxJsonSize;
+exports.isOverWireBudget = isOverWireBudget;
+var _typeHelpers = require("../utils/typeHelpers.js");
+/**
+ * Size guards for anything a tool puts on the sync wire.
+ *
+ * Every adapter faces the same problem: a snapshot is rebuilt and serialized
+ * on the device's JS thread ~5x/sec while a dashboard watches, and one fat or
+ * unserializable field can either freeze that thread or blow the emit layer's
+ * budget — which drops the WHOLE snapshot and leaves the panel stale.
+ *
+ * Two rules make that safe, and both are easy to get subtly wrong, which is
+ * why they live here instead of being copied per adapter:
+ *
+ *  1. NEVER measure by serializing. `JSON.stringify(value).length` is
+ *     O(payload) and allocates the whole string — an unbounded cost to
+ *     enforce a 16KB cap, i.e. the protection becomes the freeze. Walk with
+ *     an early abort instead: the cost is O(limit) no matter how big the
+ *     value, and a string costs a length read rather than a scan.
+ *
+ *  2. Only reach for `JSON.stringify` when the walk saw something that could
+ *     actually make it throw. A value straight out of `JSON.parse` — which is
+ *     what a network body or a stored string is — is a finite tree of plain
+ *     values and can never throw, so the check is pure waste on the common
+ *     path.
+ */
+
+/**
+ * Approximate JSON size, aborting as soon as `limit` is passed — O(limit),
+ * never O(payload). Returns the bytes counted so far, so one walk can both
+ * threshold ("over the per-field cap?") and accumulate ("how much of the
+ * snapshot budget is left?").
+ */
+function approxJsonSize(value, limit) {
+  let bytes = 0;
+  let sawRepeat = false;
+  let sawBigInt = false;
+  const stack = [value];
+  const seen = new Set();
+  while (stack.length > 0) {
+    if (bytes > limit) return {
+      bytes,
+      sawRepeat,
+      sawBigInt
+    };
+    const v = stack.pop();
+    if (v === null || v === undefined) bytes += 4;else if (typeof v === "string") bytes += v.length + 2; // O(1), no scan
+    else if (typeof v === "number") bytes += 8;else if (typeof v === "boolean") bytes += 5;else if (typeof v === "object") {
+      if (seen.has(v)) {
+        sawRepeat = true;
+        continue;
+      }
+      seen.add(v);
+      if (Array.isArray(v)) {
+        bytes += 2 + v.length;
+        for (let i = 0; i < v.length; i++) stack.push(v[i]);
+      } else {
+        bytes += 2;
+        for (const k in v) {
+          bytes += k.length + 4;
+          stack.push(v[k]);
+        }
+      }
+    } else {
+      if (typeof v === "bigint") sawBigInt = true;
+      bytes += 4;
+    }
+  }
+  return {
+    bytes,
+    sawRepeat,
+    sawBigInt
+  };
+}
+
+/**
+ * Should this value be withheld from the wire — too big, or unserializable?
+ *
+ * The ordering is the point: measure with the early-abort walk, and only pay
+ * for `JSON.stringify` when the walk found a reason it might throw.
+ */
+function isOverWireBudget(value, limit) {
+  const walk = approxJsonSize(value, limit);
+  if (walk.bytes > limit) return true;
+  // A finished walk with no repeated reference and no bigint cannot throw.
+  //
+  // Not exhaustive even then: a `toJSON`/getter that throws is invisible to
+  // the walk, so callers handling hostile payloads should still guard their
+  // own conversion. `safeEmit` is the last backstop.
+  if (!walk.sawRepeat && !walk.sawBigInt) return false;
+  return !(0, _typeHelpers.isJsonSerializable)(value);
+}