@buoy-gg/shared-ui 7.0.33 → 7.0.35

package/lib/commonjs/stores/createToolStore.js

@@ -0,0 +1,175 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createToolStore = createToolStore;
+/**
+ * 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);
+  }
+}
+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;
+}

package/lib/commonjs/stores/index.js

@@ -9,6 +9,18 @@ Object.defineProperty(exports, "BaseEventStore", {
     return _BaseEventStore.BaseEventStore;
   }
 });
+Object.defineProperty(exports, "ChangeLog", {
+  enumerable: true,
+  get: function () {
+    return _ChangeLog.ChangeLog;
+  }
+});
+Object.defineProperty(exports, "createToolStore", {
+  enumerable: true,
+  get: function () {
+    return _createToolStore.createToolStore;
+  }
+});
 Object.defineProperty(exports, "ignoredPatternsStore", {
   enumerable: true,
   get: function () {
@@ -34,4 +46,6 @@ Object.defineProperty(exports, "useIgnoredPatterns", {
   }
 });
 var _BaseEventStore = require("./BaseEventStore.js");
-var _ignoredPatternsStore = require("./ignoredPatternsStore");
+var _ignoredPatternsStore = require("./ignoredPatternsStore");
+var _createToolStore = require("./createToolStore.js");
+var _ChangeLog = require("./ChangeLog.js");

package/lib/commonjs/sync/toolSyncAdapter.js

@@ -0,0 +1,63 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createSyncAdapter = createSyncAdapter;
+exports.mergeChangeSources = mergeChangeSources;
+/**
+ * ToolSyncAdapter — the contract a tool implements to sync to Buoy Desktop /
+ * the MCP server, plus `createSyncAdapter`, the one way to build one.
+ *
+ * Every tool package used to declare its adapter as a bare object literal
+ * with the comment "structurally matches external-sync's ToolSyncAdapter so
+ * this package doesn't need a dependency on it". That kept the packages
+ * decoupled but left the contract unchecked: storage shipped `version: 3`
+ * while every sibling was on 2 and nothing noticed. The type now lives here,
+ * in shared (which every tool already depends on), and external-sync
+ * re-exports it — one definition, checked everywhere.
+ *
+ * `createSyncAdapter` is deliberately thin. It:
+ *  - type-checks the literal against the contract (a wrong `subscribe`
+ *    signature or a non-function action fails at compile time),
+ *  - keeps the CONCRETE `actions` type, so `adapter.actions.getChangeDetail()`
+ *    stays typed for tests and callers,
+ *  - merges several change sources into one `subscribe` (a store plus its
+ *    registry, envelopes plus drops) — the second most-copied block.
+ */
+
+/** A remote-invocable action. Thrown errors are reported back to the dashboard. */
+
+/** Anything that can tell the bridge "something changed". */
+
+/**
+ * The contract each dev tool implements to become remotely syncable.
+ * Works with BaseEventStore, ChangeLog, createToolStore, or any pattern
+ * exposing subscribe + getSnapshot.
+ *
+ * Payloads (snapshots and action results) must be JSON-serializable —
+ * no functions, circular references, or class instances.
+ */
+
+/** Subscribe to every source; the returned function unsubscribes from all. */
+function mergeChangeSources(sources) {
+  if (sources.length === 1) return sources[0];
+  return onChange => {
+    const offs = sources.map(source => source(onChange));
+    return () => {
+      for (const off of offs) off();
+    };
+  };
+}
+function createSyncAdapter(definition) {
+  const subscribe = Array.isArray(definition.subscribe) ? mergeChangeSources(definition.subscribe) : definition.subscribe;
+  const adapter = {
+    version: definition.version,
+    getSnapshot: definition.getSnapshot,
+    subscribe,
+    ...(definition.actions ? {
+      actions: definition.actions
+    } : {})
+  };
+  return adapter;
+}

package/lib/commonjs/sync/wireForm.js

@@ -0,0 +1,172 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.WIRE_INLINE_LIMIT_BYTES = exports.WIRE_DETAIL_LIMIT_BYTES = void 0;
+exports.capDetail = capDetail;
+exports.detailByIdAction = detailByIdAction;
+exports.isOnDeviceMarker = isOnDeviceMarker;
+exports.memoByIdentity = memoByIdentity;
+exports.newestFitting = newestFitting;
+exports.onDeviceMarker = onDeviceMarker;
+exports.readParams = readParams;
+exports.sizeOrStub = sizeOrStub;
+exports.toWire = toWire;
+exports.truncatedNote = truncatedNote;
+var _wireBudget = require("./wireBudget.js");
+/**
+ * wireForm — how a tool turns what it holds into what it may put on the wire.
+ *
+ * Every adapter that ships large values faces the same four problems, and
+ * nine of them solved each one separately:
+ *
+ *  1. A per-item cap on the snapshot stream (16 KB), with a MARKER left in
+ *     the value's place so the dashboard knows to fetch it on demand.
+ *  2. A much larger cap on that on-demand detail fetch (8 MB), with a
+ *     TRUNCATION NOTE when even that is exceeded.
+ *  3. An identity-keyed cache for the wire form, because a snapshot is
+ *     rebuilt ~5×/sec while a dashboard watches and stores never mutate a
+ *     recorded item — so converting each item once is correct and cheap.
+ *  4. For tools whose items are individually fat (console, sentry), a
+ *     newest-first walk that keeps as many items as fit a snapshot budget.
+ *
+ * Marker KEY NAMES are part of the wire protocol — Buoy Desktop and the
+ * tool stores test for `__buoyStateOnDevice`, `__buoyPayloadOnDevice`,
+ * `__buoyValueOnDevice` — so the factory builds exactly those keys.
+ */
+
+/** Per-item budget on the snapshot stream. Anything larger stays on-device. */
+const WIRE_INLINE_LIMIT_BYTES = exports.WIRE_INLINE_LIMIT_BYTES = 16 * 1024;
+
+/**
+ * Upper bound for one on-demand detail response. Generous — this is a single
+ * explicit fetch, not a per-item stream — but still guarded so a pathological
+ * tree can't OOM the device through the reply emit.
+ */
+const WIRE_DETAIL_LIMIT_BYTES = exports.WIRE_DETAIL_LIMIT_BYTES = 8 * 1024 * 1024;
+
+/** A frozen `{ __buoy<Kind>OnDevice: true, note }` marker. */
+
+/**
+ * Build the sentinel a wire-form snapshot carries in place of a value that
+ * stays on the device. `kind` names the value ("State", "Payload", "Value",
+ * "Params", "Data", …) and becomes the key the reader tests for.
+ */
+function onDeviceMarker(kind, note) {
+  return Object.freeze({
+    [`__buoy${kind}OnDevice`]: true,
+    note
+  });
+}
+
+/** True when `value` is the on-device marker for `kind`. */
+function isOnDeviceMarker(value, kind) {
+  return typeof value === "object" && value !== null && value[`__buoy${kind}OnDevice`] === true;
+}
+
+/** The note a detail fetch returns when a single field exceeds the detail cap. */
+function truncatedNote(limitBytes = WIRE_DETAIL_LIMIT_BYTES) {
+  const mb = limitBytes / (1024 * 1024);
+  return {
+    __buoyTruncated: true,
+    note: `Exceeds the ${mb}MB detail limit — inspect it on-device.`
+  };
+}
+
+/**
+ * The value itself if it fits `limit` (and is serializable), else `marker`.
+ * `undefined` passes through untouched: an absent field must stay absent.
+ */
+function toWire(value, marker, limit = WIRE_INLINE_LIMIT_BYTES) {
+  if (value === undefined) return value;
+  return (0, _wireBudget.isOverWireBudget)(value, limit) ? marker : value;
+}
+
+/** Detail-fetch cap: the value, or a truncation note when it is too big. */
+function capDetail(value, limit = WIRE_DETAIL_LIMIT_BYTES) {
+  return (0, _wireBudget.isOverWireBudget)(value, limit) ? truncatedNote(limit) : value;
+}
+
+/**
+ * Memoize a wire-form conversion by item identity. Correct for any store
+ * that prepends and never mutates a recorded item — the cache self-invalidates
+ * when the item is dropped from the buffer.
+ */
+function memoByIdentity(convert) {
+  const cache = new WeakMap();
+  return item => {
+    const cached = cache.get(item);
+    if (cached !== undefined) return cached;
+    const converted = convert(item);
+    cache.set(item, converted);
+    return converted;
+  };
+}
+/**
+ * Walk `items` (oldest-first) from the newest end, keeping every item until
+ * the budget is spent. Always keeps at least one so an over-budget newest
+ * item still reaches the dashboard as a stub rather than an empty panel.
+ * Returns oldest-first, matching the input.
+ */
+function newestFitting(items, options) {
+  const out = [];
+  let bytes = options.baseBytes ?? 16;
+  for (let i = items.length - 1; i >= 0; i--) {
+    const wired = options.toWire(items[i]);
+    if (bytes + wired.bytes > options.budget && out.length > 0) break;
+    out.push(wired.value);
+    bytes += wired.bytes;
+  }
+  out.reverse();
+  return out;
+}
+
+/**
+ * Size one wire-form item against a per-item cap, substituting a stub when it
+ * is too fat. One walk decides both "too big?" and "what does it cost".
+ */
+function sizeOrStub(wired, limit, stub) {
+  const size = (0, _wireBudget.approxJsonSize)(wired, limit);
+  if (size.bytes <= limit) return {
+    value: wired,
+    bytes: size.bytes
+  };
+  const stubbed = stub();
+  return {
+    value: stubbed,
+    bytes: (0, _wireBudget.approxJsonSize)(stubbed, limit).bytes
+  };
+}
+
+/** `(params as T | undefined) ?? {}` — the first line of every action. */
+function readParams(params) {
+  return params ?? {};
+}
+/**
+ * The on-demand detail action every change-log tool exposes: look one item
+ * up by id, and return its detail fields size-capped. Replaces the
+ * `missing id` / `unknown id` boilerplate copied into each adapter.
+ */
+function detailByIdAction(lookup, detail, limit = WIRE_DETAIL_LIMIT_BYTES) {
+  const cap = value => capDetail(value, limit);
+  return params => {
+    const {
+      id
+    } = readParams(params);
+    if (!id) return {
+      found: false,
+      reason: "missing id"
+    };
+    const item = lookup(id);
+    if (!item) return {
+      found: false,
+      reason: "unknown id"
+    };
+    return {
+      found: true,
+      id,
+      ...detail(item, cap)
+    };
+  };
+}

package/lib/commonjs/tools/defineTool.js

@@ -0,0 +1,79 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createToolFactory = createToolFactory;
+exports.defineToolPreset = defineToolPreset;
+/**
+ * defineToolPreset / createToolFactory — the typed way to declare a tool.
+ *
+ * Every tool package exports a `xToolPreset` object literal and a
+ * `createXTool(options)` factory that restates the same literal with
+ * `options?.name || default` on each field. None of the 23 presets was
+ * annotated with core's `InstalledApp`, so a preset that drifted from the
+ * contract (a bad `slot`, a missing `component`) failed at runtime in the
+ * dial, not at compile time.
+ *
+ * `ToolPreset` is that contract, declared here in shared (which every tool
+ * already depends on) and structurally identical to core's `InstalledApp`.
+ * `defineToolPreset` is an identity function that type-checks the literal;
+ * `createToolFactory` derives the `createXTool` function from the preset so
+ * the defaults live in exactly one place.
+ *
+ * Auto-discovery (core's `autoDiscoverPresets` / `autoExternalSync`) stays
+ * as hand-written `require()` blocks on purpose: Metro needs each package
+ * name as a static string lexically inside its own try, so a manifest can't
+ * replace them.
+ */
+
+/** Where a tool should render within the floating menu surface. */
+
+/** What an icon renderer receives. Mirrors core's `FloatingMenuRenderCtx`. */
+
+/** Declarative modal chrome for a body-only tool. Mirrors core's `ToolModalConfig`. */
+
+/**
+ * The shape the floating menu installs. Structurally identical to core's
+ * `InstalledApp`; declared here so tool packages can type their presets
+ * without depending on core.
+ */
+
+/** Identity with a type check: the literal must satisfy `ToolPreset`. */
+function defineToolPreset(preset) {
+  return preset;
+}
+
+/** The overrides every `createXTool` accepted. */
+
+/**
+ * Derive `createXTool(options)` from a preset: id/name/description overrides
+ * apply on top, and `mapProps` turns tool-specific options into `props`
+ * (merged over the preset's defaults).
+ *
+ * ```ts
+ * export const createNetworkTool = createToolFactory(networkToolPreset, (o: { enableSharedModalDimensions?: boolean }) => ({
+ *   enableSharedModalDimensions: o.enableSharedModalDimensions ?? false,
+ * }));
+ * ```
+ */
+function createToolFactory(preset, mapProps, /** Last word on any other preset field (a recolored icon, say). */
+extend) {
+  return options => {
+    const overrides = options ?? {};
+    const props = preset.props === undefined && !mapProps ? undefined : {
+      ...(preset.props ?? {}),
+      ...(mapProps ? mapProps(overrides) : {})
+    };
+    return {
+      ...preset,
+      id: overrides.id || preset.id,
+      name: overrides.name || preset.name,
+      description: overrides.description || preset.description,
+      ...(props !== undefined ? {
+        props
+      } : {}),
+      ...(extend ? extend(overrides, preset) : {})
+    };
+  };
+}

package/lib/commonjs/ui/components/ChangeRow.js

@@ -0,0 +1,111 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ChangeRow = ChangeRow;
+var _react = _interopRequireDefault(require("react"));
+var _reactNative = require("react-native");
+var _gameUIColors = require("../gameUI/constants/gameUIColors.js");
+var _CompactRow = require("./CompactRow.js");
+var _index = require("../../icons/index.js");
+var _RelativeTime = require("../../utils/time/RelativeTime.js");
+var _fonts = require("../fonts.js");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * ChangeRow — one recorded change in a state tool's history list.
+ *
+ * redux, zustand and jotai each drew the same row on top of `CompactRow`:
+ * a colored status word (the slice / store / atom), a sublabel ("1.2ms ·
+ * 3 keys changed"), the primary line (changed keys or a value preview), a
+ * relative timestamp, and a right-hand badge made of a mono verb (SET,
+ * WRITE, ADDITEM) plus an icon — a lightning bolt when state actually
+ * changed, a clock when the update was slow. The three copies differed
+ * only in how they computed those strings. This component owns the drawing;
+ * tools own the strings.
+ *
+ * testID convention (unchanged from the originals): `${testID}-badge`,
+ * `${testID}-change`, `${testID}-slow`, `${testID}-status`,
+ * `${testID}-sublabel`, `${testID}-keys`.
+ */
+
+function ChangeRow({
+  statusColor,
+  statusLabel,
+  sublabel,
+  primaryText,
+  timestamp,
+  badgeText,
+  changed = false,
+  slow = false,
+  badgePrefix,
+  customBadge,
+  plainBadgeText,
+  onPress,
+  testID,
+  accessibilityLabel
+}) {
+  // Always a custom badge, even when there is no icon to hang off it. The
+  // alternative — letting CompactRow draw `badgeText` itself — leaves the one
+  // row whose badge matters most (a write that changed NOTHING) as the only
+  // row in the list with no handle on its badge.
+  const badge = customBadge ?? (badgeText !== undefined || badgePrefix || changed || slow ? /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+    style: styles.badgeContainer,
+    children: [badgePrefix, badgeText !== undefined ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+      style: [styles.badgeText, {
+        color: statusColor
+      }],
+      testID: testID ? `${testID}-badge` : undefined,
+      children: badgeText
+    }) : null, slow ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: styles.iconBadge,
+      testID: testID ? `${testID}-slow` : undefined,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_index.Clock, {
+        size: 12,
+        color: _gameUIColors.buoyColors.error
+      })
+    }) : changed ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      style: styles.iconBadge,
+      testID: testID ? `${testID}-change` : undefined,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_index.Zap, {
+        size: 12,
+        color: _gameUIColors.buoyColors.warning
+      })
+    }) : null]
+  }) : undefined);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_CompactRow.CompactRow, {
+    statusDotColor: statusColor,
+    statusLabel: statusLabel,
+    statusSublabel: sublabel,
+    primaryText: primaryText,
+    bottomRightText: /*#__PURE__*/(0, _jsxRuntime.jsx)(_RelativeTime.RelativeTime, {
+      timestamp: timestamp
+    }),
+    customBadge: badge,
+    badgeText: badge ? undefined : plainBadgeText,
+    badgeColor: statusColor,
+    showChevron: true,
+    onPress: onPress,
+    testID: testID,
+    statusTestID: testID ? `${testID}-status` : undefined,
+    statusSublabelTestID: testID ? `${testID}-sublabel` : undefined,
+    primaryTestID: testID ? `${testID}-keys` : undefined,
+    accessibilityLabel: accessibilityLabel
+  });
+}
+const styles = _reactNative.StyleSheet.create({
+  badgeContainer: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 4
+  },
+  badgeText: {
+    fontSize: 11,
+    fontWeight: "600",
+    fontFamily: _fonts.monoFont
+  },
+  iconBadge: {
+    paddingHorizontal: 4
+  }
+});