@buoy-gg/shared-ui 7.0.33 → 7.0.34

package/lib/typescript/module/hooks/usePersistedState.d.ts

@@ -1,16 +1,45 @@
+/** The two calls a backend needs. `persistentStorage` and AsyncStorage both fit. */
+export interface PersistedStateStorage {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+export interface PersistedStateOptions<T> {
+    /**
+     * Turn the stored string into a value. Return `undefined` to reject it
+     * (corrupt, or a value the UI no longer offers) and keep the default.
+     * Default: `JSON.parse`.
+     */
+    parse?: (raw: string) => T | undefined;
+    /** Turn a value into the stored string. Default: `JSON.stringify`. */
+    serialize?: (value: T) => string;
+    /**
+     * Where the value lives. Default: `persistentStorage` (FileSystem →
+     * AsyncStorage → memory). A tool whose keys were always written straight to
+     * AsyncStorage keeps reading them by passing AsyncStorage here.
+     */
+    storage?: PersistedStateStorage;
+}
 /**
  * `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 declare function usePersistedState<T>(key: string, defaultValue: T): [T, (next: T | ((prev: T) => T)) => void, boolean];
+export declare function usePersistedState<T>(key: string, defaultValue: T, options?: PersistedStateOptions<T>): [T, (next: T | ((prev: T) => T)) => void, boolean];
+/** Test seam: forget every hydrated value. */
+export declare function resetPersistedStateCache(): void;
 //# sourceMappingURL=usePersistedState.d.ts.map

package/lib/typescript/module/hooks/usePersistedState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePersistedState.d.ts","sourceRoot":"","sources":["../../../../src/hooks/usePersistedState.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,CAoDpD"}
+{"version":3,"file":"usePersistedState.d.ts","sourceRoot":"","sources":["../../../../src/hooks/usePersistedState.ts"],"names":[],"mappings":"AAUA,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,SAAS,CAAC;IACvC,sEAAsE;IACtE,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC;;;;OAIG;IACH,OAAO,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,GAAE,qBAAqB,CAAC,CAAC,CAAM,GACrC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,CA+DpD;AAED,8CAA8C;AAC9C,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/lib/typescript/module/index.d.ts

@@ -1,10 +1,15 @@
 export * from "./ui";
 export * from "./stores";
 export * from "./sync/wireBudget";
+export * from "./sync/wireForm";
+export * from "./sync/toolSyncAdapter";
+export * from "./tools/defineTool";
 export * from "./sync/toolActionRegistry";
 export * from "./sync/toolUiBridge";
 export { absoluteFill, displayValue, parseDisplayValue, getSafeAreaInsets, persistentStorage, isUsingPersistentStorage, getStorageBackendType, safeStringify, getValueType, isPrimitive, isJsonSerializable, isValidJson, getConstructorName, isEmpty, getValueSize, parseValue, formatValue, getTypeColor, truncateText, flattenObject, formatPath, loadOptionalModule, getCachedOptionalModule, setRenderCaptureProvider, getRenderCaptureProvider, type RenderCaptureProvider, type RenderCaptureSummary, type RenderCaptureTopComponent, type RenderCauseCounts, registerStateSnapshotProvider, getStateSnapshotProviders, getStateSnapshotProvider, subscribeToStateSnapshotProviders, type StateSnapshotProvider, type StateSnapshotProviderStatus, type StateSnapshotCapture, type StateSnapshotRestoreResult, type StateSnapshotPreview, type StateSnapshotPreviewItem, type StateSnapshotPreviewVerdict, superJsonSerialize, superJsonDeserialize, type SuperJSONResult, reloadApp, scheduleReloadApp, resolveReloadStrategy, REMOTE_RELOAD_DELAY_MS, type ReloadStrategy, type ResolvedReloadStrategy, getDevServerOrigin, Subscribable, type SubscribableListener, subscriberCountNotifier, subscribeToSubscriberCountChanges, notifySubscriberCountChange, useSafeRouter, useSafePathname, useSafeSegments, useSafeGlobalSearchParams, getSafeRouter, getSafeCurrentPathname, getSafeCurrentRoute, isExpoRouterAvailable, } from "./utils";
 export type { SafeRouteLocation } from "./utils";
+export { PREVIEW_ITEM_RENDER_BYTE_LIMIT, createRestoreScope, emptyRestoreResult, failedRestore, skippedRestore, classifyPreviewItem, wontApply, unionKeys, type RestoreScope, type RestoreScopeOptions, type ClassifyOptions, type ClassifyInput, } from "./utils/snapshotProviderKit";
+export { entityColor, formatValuePreview, shallowDiffSummary, type ValuePreviewOptions, type ShallowDiffSummary, } from "./utils/stateTools";
 export * from "./utils/formatting";
 export * from "./utils/time";
 export { isPlainObject as isPlainObjectUtil } from "./utils/typeHelpers";
@@ -13,7 +18,7 @@ export * from "./clipboard";
 export * from "./logger";
 export * from "./settings";
 export * from "./storage";
-export { useSafeAreaInsets, useFilterManager, usePersistedState, useDeviceInfo, getDeviceInfo, logDeviceInfo, type DeviceInfo, type PlatformInfo, type DisplayInfo, type AccessibilitySettings, type AppearanceInfo, type LocaleInfo, type StatusBarInfo, type KeyboardInfo, type AppStateInfo, type UniqueIdentifiers, type SettingsInfo, } from "./hooks";
+export { useSafeAreaInsets, useFilterManager, usePersistedState, resetPersistedStateCache, type PersistedStateOptions, type PersistedStateStorage, useChangeLog, useSubscribedValue, useEventStoreEvents, type UseChangeLogOptions, type UseChangeLogResult, type UseEventStoreEventsOptions, type UseEventStoreEventsResult, useDeviceInfo, getDeviceInfo, logDeviceInfo, type DeviceInfo, type PlatformInfo, type DisplayInfo, type AccessibilitySettings, type AppearanceInfo, type LocaleInfo, type StatusBarInfo, type KeyboardInfo, type AppStateInfo, type UniqueIdentifiers, type SettingsInfo, } from "./hooks";
 export { JsModal } from "./JsModal";
 export type { ModalMode, ModalState } from "./JsModal";
 export { night, NIGHT_LABEL_TRACKING } from "./ui/night/nightTheme";

package/lib/typescript/module/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/storage/definePersistedSetting.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+export interface PersistedSettingOptions<T> {
+    /** Merge-then-validate. Receives `{ ...defaults, ...stored }`; returns the value to use. */
+    sanitize?: (merged: T, stored: unknown) => T;
+    /** Default: `JSON.parse`. */
+    parse?: (raw: string) => unknown;
+    /** Default: `JSON.stringify`. */
+    serialize?: (value: T) => string;
+    /** Default: `persistentStorage`. */
+    storage?: {
+        getItem(key: string): Promise<string | null>;
+        setItem(key: string, value: string): Promise<void>;
+        removeItem(key: string): Promise<void>;
+    };
+}
+export interface PersistedSetting<T> {
+    readonly key: string;
+    readonly defaults: T;
+    /** The stored value merged over the defaults, or the defaults. Never throws. */
+    load(): Promise<T>;
+    /** Like `load()`, but `null` when nothing is stored (or it is unreadable). */
+    loadOrNull(): Promise<T | null>;
+    save(value: T): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function definePersistedSetting<T>(key: string, defaults: T, options?: PersistedSettingOptions<T>): PersistedSetting<T>;
+//# sourceMappingURL=definePersistedSetting.d.ts.map

package/lib/typescript/module/storage/definePersistedSetting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definePersistedSetting.d.ts","sourceRoot":"","sources":["../../../../src/storage/definePersistedSetting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,MAAM,WAAW,uBAAuB,CAAC,CAAC;IACxC,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,KAAK,CAAC,CAAC;IAC7C,6BAA6B;IAC7B,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IACjC,iCAAiC;IACjC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IACjC,oCAAoC;IACpC,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QAC7C,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACxC,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,gFAAgF;IAChF,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IACnB,8EAA8E;IAC9E,UAAU,IAAI,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAMD,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,CAAC,EACX,OAAO,GAAE,uBAAuB,CAAC,CAAC,CAAM,GACvC,gBAAgB,CAAC,CAAC,CAAC,CA6CrB"}

package/lib/typescript/module/storage/index.d.ts

@@ -1,2 +1,3 @@
 export { devToolsStorageKeys, isDevToolsStorageKey } from './devToolsStorageKeys';
+export { definePersistedSetting, type PersistedSetting, type PersistedSettingOptions, } from "./definePersistedSetting";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAElF,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC"}

package/lib/typescript/module/stores/ChangeLog.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 type ChangeLogListener<T> = (items: T[]) => void;
+export interface ChangeLogOptions {
+    /** Ring-buffer depth. Default 200 — what all four stores shipped with. */
+    max?: number;
+}
+export interface Identified {
+    id: string;
+}
+export declare class ChangeLog<T extends Identified> {
+    /** Newest first. Subclasses may read; mutate only through the helpers. */
+    protected items: T[];
+    protected max: number;
+    private readonly itemListeners;
+    private readonly clearListeners;
+    private idCounter;
+    private enabled;
+    private captureSuppressed;
+    constructor(options?: ChangeLogOptions);
+    /** True when a new item should be recorded (not paused, not a mirror). */
+    protected canRecord(): boolean;
+    /** `${Date.now()}-${n}` — unique per store instance, sorts by time. */
+    protected nextId(): string;
+    /**
+     * 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()`.
+     */
+    protected push(item: T): void;
+    /** `push()` + notify. The common case. */
+    protected record(item: T): void;
+    /** Replace the buffer wholesale (already merged/hydrated by the caller) and notify. */
+    protected setItems(next: T[]): void;
+    /** All items, newest first. Fresh array each call. */
+    getAll(): T[];
+    getById(id: string): T | undefined;
+    get size(): number;
+    /**
+     * 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(): void;
+    /**
+     * Listen for `clear()` calls. Used in remote mirror mode to forward a
+     * clear performed in the dashboard UI to the synced device.
+     */
+    onClear(listener: () => void): () => void;
+    /**
+     * 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(): void;
+    /** Whether the store is in remote mirror mode (capture suppressed). */
+    isCaptureSuppressed(): boolean;
+    /**
+     * 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: T[]): boolean;
+    /**
+     * 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: string, patch: Partial<T>): void;
+    setEnabled(enabled: boolean): void;
+    getEnabled(): boolean;
+    setMax(max: number): void;
+    getMax(): number;
+    subscribe(listener: ChangeLogListener<T>): () => void;
+    protected notifyListeners(): void;
+    protected get listenerCount(): number;
+}
+//# sourceMappingURL=ChangeLog.d.ts.map

package/lib/typescript/module/stores/ChangeLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChangeLog.d.ts","sourceRoot":"","sources":["../../../../src/stores/ChangeLog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,qBAAa,SAAS,CAAC,CAAC,SAAS,UAAU;IACzC,0EAA0E;IAC1E,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,CAAM;IAC1B,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC;IAEtB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,OAAO,GAAE,gBAAqB;IAM1C,0EAA0E;IAC1E,SAAS,CAAC,SAAS,IAAI,OAAO;IAI9B,uEAAuE;IACvE,SAAS,CAAC,MAAM,IAAI,MAAM;IAI1B;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAI7B,0CAA0C;IAC1C,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAK/B,uFAAuF;IACvF,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI;IAOnC,sDAAsD;IACtD,MAAM,IAAI,CAAC,EAAE;IAIb,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIlC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAYb;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IASzC;;;;;OAKG;IACH,cAAc,IAAI,IAAI;IAItB,uEAAuE;IACvE,mBAAmB,IAAI,OAAO;IAI9B;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,OAAO;IAM9B;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAahD,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC,UAAU,IAAI,OAAO;IAIrB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAQzB,MAAM,IAAI,MAAM;IAMhB,SAAS,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAOrD,SAAS,CAAC,eAAe,IAAI,IAAI;IAKjC,SAAS,KAAK,aAAa,IAAI,MAAM,CAEpC;CACF"}

package/lib/typescript/module/stores/createToolStore.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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. */
+export type ToolStoreListener = () => void;
+export type ToolStoreOrder = "append" | "prepend";
+export interface ToolStoreOptions {
+    /** Tool id, as the sync layer knows it (`"console"`, `"sentry"`, …). Used by
+     * `flushSync()` so the dashboard pushes THIS tool's snapshot. */
+    id: string;
+    /** Ring-buffer depth. */
+    max: number;
+    /** Where new items land. Default `"append"` (newest last). */
+    order?: ToolStoreOrder;
+    /**
+     * `"frame"`: coalesce listener notifications onto one animation frame so a
+     * burst (a log loop, a navigation's several envelopes) is one React commit.
+     * `"sync"` (default): notify immediately.
+     */
+    coalesce?: "frame" | "sync";
+    /** Floor between opportunistic (non-forced) `flushSync()` calls. Default 150 ms. */
+    flushMinIntervalMs?: number;
+    /** First id `allocId()` hands out. Default 1. */
+    firstId?: number;
+}
+export interface ToolStore<T> {
+    /** Subscribe to any change (items, or a `notify()` from companion state). */
+    subscribe(listener: ToolStoreListener): () => void;
+    /** Current items. Stable reference between mutations. */
+    getSnapshot(): T[];
+    /** Number of items. */
+    size(): number;
+    /** Add one item at the configured end, trimming from the other. No-op while paused. */
+    add(item: T): void;
+    /** Replace all items (remote mirror mode, restore-from-disk). Trims to `max`. */
+    set(next: T[]): void;
+    /** Functional replace: `update(items => items.filter(...))`. Trims to `max`. */
+    update(fn: (items: T[]) => T[]): void;
+    /** Empty the buffer. Fires `onClear` listeners FIRST, always. */
+    clear(): void;
+    /** Listen for `clear()`. The dashboard uses this to forward a clear to the device. */
+    onClear(listener: ToolStoreListener): () => void;
+    /** Notify subscribers without touching items (companion state changed). */
+    notify(): void;
+    /**
+     * Push this tool's snapshot to any connected dashboard now, via the
+     * `__buoyFlushToolSync` global (@buoy-gg/external-sync `crashFlush`).
+     * Rate-limited unless `force` — a fatal is the app's last word and always goes out.
+     */
+    flushSync(force?: boolean): void;
+    /** While paused, `add()` is dropped. `set`/`update`/`clear` still apply. */
+    setPaused(paused: boolean): void;
+    isPaused(): boolean;
+    /** Change the ring-buffer depth; trims immediately if shrinking. */
+    setMax(max: number): void;
+    getMax(): number;
+    /** Monotonic id counter for items that need one. */
+    allocId(): number;
+    /** Raise the id floor (after restoring persisted items that carry ids). */
+    bumpIdAbove(id: number): void;
+    /** How many `subscribe` listeners are attached. */
+    listenerCount(): number;
+    /** The tool id this store was created with. */
+    readonly id: string;
+}
+export declare function createToolStore<T>(options: ToolStoreOptions): ToolStore<T>;
+//# sourceMappingURL=createToolStore.d.ts.map

package/lib/typescript/module/stores/createToolStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createToolStore.d.ts","sourceRoot":"","sources":["../../../../src/stores/createToolStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,mEAAmE;AACnE,MAAM,MAAM,iBAAiB,GAAG,MAAM,IAAI,CAAC;AAE3C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,gBAAgB;IAC/B;qEACiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC5B,oFAAoF;IACpF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,6EAA6E;IAC7E,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAC;IACnD,yDAAyD;IACzD,WAAW,IAAI,CAAC,EAAE,CAAC;IACnB,uBAAuB;IACvB,IAAI,IAAI,MAAM,CAAC;IACf,uFAAuF;IACvF,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB,iFAAiF;IACjF,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;IACrB,gFAAgF;IAChF,MAAM,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC;IACtC,iEAAiE;IACjE,KAAK,IAAI,IAAI,CAAC;IACd,sFAAsF;IACtF,OAAO,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAAC;IACjD,2EAA2E;IAC3E,MAAM,IAAI,IAAI,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,4EAA4E;IAC5E,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,QAAQ,IAAI,OAAO,CAAC;IACpB,oEAAoE;IACpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,IAAI,MAAM,CAAC;IACjB,oDAAoD;IACpD,OAAO,IAAI,MAAM,CAAC;IAClB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,mDAAmD;IACnD,aAAa,IAAI,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAYD,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,CA6J1E"}

package/lib/typescript/module/stores/index.d.ts

@@ -3,4 +3,6 @@
  */
 export { BaseEventStore, type ArrayListener, type EventCallback, type BaseEventStoreOptions, } from "./BaseEventStore";
 export { ignoredPatternsStore, useIgnoredPatterns, urlMatchesIgnoredPattern, isUrlIgnored, type IgnoredPattern, type IgnoredPatternMatchMode, type UseIgnoredPatternsResult, } from "./ignoredPatternsStore";
+export { createToolStore, type ToolStore, type ToolStoreOptions, type ToolStoreOrder, type ToolStoreListener, } from "./createToolStore";
+export { ChangeLog, type ChangeLogListener, type ChangeLogOptions, type Identified, } from "./ChangeLog";
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/stores/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/stores/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/stores/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,wBAAwB,EACxB,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC9B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,eAAe,EACf,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,SAAS,EACT,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC"}

package/lib/typescript/module/sync/toolSyncAdapter.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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. */
+export type ToolAction = (params: unknown) => unknown | Promise<unknown>;
+/** Anything that can tell the bridge "something changed". */
+export type ChangeSource = (onChange: () => void) => () => void;
+/**
+ * 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.
+ */
+export interface ToolSyncAdapter {
+    /** Version of this tool's payload shape. Bump on breaking changes. */
+    version: number;
+    /** Current full state — sent when a dashboard starts watching or requests state. */
+    getSnapshot: () => unknown;
+    /**
+     * Fires on state changes. Only called while at least one dashboard is
+     * watching this tool; the bridge subscribes/unsubscribes on demand so
+     * stores with auto start/stop lifecycles stay idle when unwatched.
+     */
+    subscribe: ChangeSource;
+    /** Remote-invocable actions, keyed by action name. */
+    actions?: Record<string, ToolAction>;
+}
+export interface SyncAdapterDefinition<TSnapshot, TActions extends Record<string, ToolAction> | undefined> {
+    version: number;
+    getSnapshot: () => TSnapshot;
+    /** One source, or several that are merged into a single subscription. */
+    subscribe: ChangeSource | ChangeSource[];
+    actions?: TActions;
+}
+export type SyncAdapter<TSnapshot, TActions extends Record<string, ToolAction> | undefined> = {
+    version: number;
+    getSnapshot: () => TSnapshot;
+    subscribe: ChangeSource;
+} & (TActions extends undefined ? {
+    actions?: undefined;
+} : {
+    actions: TActions;
+});
+/** Subscribe to every source; the returned function unsubscribes from all. */
+export declare function mergeChangeSources(sources: ChangeSource[]): ChangeSource;
+export declare function createSyncAdapter<TSnapshot, TActions extends Record<string, ToolAction> | undefined = undefined>(definition: SyncAdapterDefinition<TSnapshot, TActions>): SyncAdapter<TSnapshot, TActions>;
+//# sourceMappingURL=toolSyncAdapter.d.ts.map

package/lib/typescript/module/sync/toolSyncAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolSyncAdapter.d.ts","sourceRoot":"","sources":["../../../../src/sync/toolSyncAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,mFAAmF;AACnF,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEzE,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,WAAW,EAAE,MAAM,OAAO,CAAC;IAC3B;;;;OAIG;IACH,SAAS,EAAE,YAAY,CAAC;IACxB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,qBAAqB,CACpC,SAAS,EACT,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS;IAEvD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,SAAS,CAAC;IAC7B,yEAAyE;IACzE,SAAS,EAAE,YAAY,GAAG,YAAY,EAAE,CAAC;IACzC,OAAO,CAAC,EAAE,QAAQ,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,CACrB,SAAS,EACT,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,IACrD;IACF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,SAAS,CAAC;IAC7B,SAAS,EAAE,YAAY,CAAC;CACzB,GAAG,CAAC,QAAQ,SAAS,SAAS,GAAG;IAAE,OAAO,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC;AAEnF,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,YAAY,CAQxE;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EACT,QAAQ,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,GAAG,SAAS,EACnE,UAAU,EAAE,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG,WAAW,CAAC,SAAS,EAAE,QAAQ,CAAC,CAW1F"}

package/lib/typescript/module/sync/wireForm.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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. */
+export declare const WIRE_INLINE_LIMIT_BYTES: number;
+/**
+ * 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.
+ */
+export declare const WIRE_DETAIL_LIMIT_BYTES: number;
+/** A frozen `{ __buoy<Kind>OnDevice: true, note }` marker. */
+export type OnDeviceMarker<K extends string> = Readonly<{
+    [P in `__buoy${K}OnDevice`]: true;
+} & {
+    note: string;
+}>;
+/**
+ * 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.
+ */
+export declare function onDeviceMarker<K extends string>(kind: K, note: string): OnDeviceMarker<K>;
+/** True when `value` is the on-device marker for `kind`. */
+export declare function isOnDeviceMarker(value: unknown, kind: string): boolean;
+/** The note a detail fetch returns when a single field exceeds the detail cap. */
+export declare function truncatedNote(limitBytes?: number): {
+    __buoyTruncated: true;
+    note: string;
+};
+/**
+ * The value itself if it fits `limit` (and is serializable), else `marker`.
+ * `undefined` passes through untouched: an absent field must stay absent.
+ */
+export declare function toWire<T>(value: unknown, marker: T, limit?: number): unknown;
+/** Detail-fetch cap: the value, or a truncation note when it is too big. */
+export declare function capDetail(value: unknown, limit?: number): unknown;
+/**
+ * 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.
+ */
+export declare function memoByIdentity<T extends object, R>(convert: (item: T) => R): (item: T) => R;
+export interface WireSized<T> {
+    value: T;
+    bytes: number;
+}
+export interface NewestFittingOptions<T, W> {
+    /** Convert one item to its wire form and its byte cost. Memoize with `memoByIdentity`. */
+    toWire: (item: T) => WireSized<W>;
+    /** Snapshot byte budget. */
+    budget: number;
+    /** Bytes the envelope around the list costs (`{"entries":[]}` ≈ 16). */
+    baseBytes?: number;
+}
+/**
+ * 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.
+ */
+export declare function newestFitting<T, W>(items: T[], options: NewestFittingOptions<T, W>): W[];
+/**
+ * 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".
+ */
+export declare function sizeOrStub<W>(wired: W, limit: number, stub: () => W): WireSized<W>;
+/** `(params as T | undefined) ?? {}` — the first line of every action. */
+export declare function readParams<T extends object>(params: unknown): Partial<T>;
+export type DetailResult<R extends object> = {
+    found: false;
+    reason: "missing id" | "unknown id";
+} | ({
+    found: true;
+    id: string;
+} & R);
+/**
+ * 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.
+ */
+export declare function detailByIdAction<T, R extends object>(lookup: (id: string) => T | undefined, detail: (item: T, cap: (value: unknown) => unknown) => R, limit?: number): (params?: unknown) => DetailResult<R>;
+//# sourceMappingURL=wireForm.d.ts.map

package/lib/typescript/module/sync/wireForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wireForm.d.ts","sourceRoot":"","sources":["../../../../src/sync/wireForm.ts"],"names":[],"mappings":"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"}