@buoy-gg/events 7.0.4 → 7.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -24,6 +24,7 @@ import { useUnifiedEvents } from "../hooks/useUnifiedEvents";
24
24
  import { UnifiedEventFilters } from "./UnifiedEventFilters";
25
25
  import { UnifiedEventList } from "./UnifiedEventList";
26
26
  import { UnifiedEventDetail } from "./UnifiedEventDetail";
27
+ import type { OptionalDetailComponents } from "./UnifiedEventDetail";
27
28
  import { EventsCopySettingsView } from "./EventsCopySettingsView";
28
29
  import type { UnifiedEvent } from "../types";
29
30
 
@@ -45,6 +46,53 @@ interface EventsModalProps {
45
46
  onBack?: () => void;
46
47
  onMinimize?: (modalState: unknown) => void;
47
48
  enableSharedModalDimensions?: boolean;
49
+ /**
50
+ * Render as a header-bar + body stack instead of inside `JsModal`, for hosts
51
+ * that place tools in a panel rather than a modal (Buoy Desktop). Only the
52
+ * shell differs — header, screens and state are shared. See `EventsToolView`.
53
+ */
54
+ inline?: boolean;
55
+ /**
56
+ * Controlled capture toggle. Omit and the tool drives its own store, which is
57
+ * what the phone wants. The desktop passes its persisted capture store,
58
+ * because there the toggle also has to stop the DEVICE streaming.
59
+ */
60
+ capturing?: boolean;
61
+ onCapturingChange?: (capturing: boolean) => void;
62
+ /**
63
+ * Wraps the network-event detail page. The desktop dashboard uses it to
64
+ * provide the body resolver, so payloads the device stripped from the sync
65
+ * snapshot can be fetched on demand. Omit on device — bodies are already
66
+ * local there.
67
+ */
68
+ networkDetailWrapper?: ComponentType<{ children: ReactNode }>;
69
+ /**
70
+ * Overrides for the per-tool detail pages `UnifiedEventDetail` renders when
71
+ * you open a network or route event.
72
+ *
73
+ * ⚠️ NOT optional on the desktop. `UnifiedEventDetail` normally resolves these
74
+ * with a runtime `require("@buoy-gg/network")`, which does not work in a
75
+ * Vite/ESM bundle — omit them there and opening a network or route event
76
+ * silently falls back to the generic renderer instead of the real tool page.
77
+ */
78
+ NetworkEventDetailViewComponent?: ComponentType<{
79
+ event: unknown;
80
+ ignoredPatterns?: Set<string>;
81
+ onTogglePattern?: (value: string) => void;
82
+ }>;
83
+ RouteEventDetailComponent?: ComponentType<{
84
+ event: unknown;
85
+ visitNumber?: number;
86
+ onNavigate?: (pathname: string) => void;
87
+ }>;
88
+ /**
89
+ * Overrides for EVERY per-tool detail page — storage, redux, zustand, jotai
90
+ * and renders as well as network and route. Same reason as the two above: the
91
+ * runtime `require` that normally resolves them does not work in a bundled
92
+ * host, so without these, opening one of those events falls back to the
93
+ * generic renderer.
94
+ */
95
+ detailComponents?: Partial<OptionalDetailComponents>;
48
96
  }
49
97
 
50
98
  export function EventsModal({
@@ -53,6 +101,13 @@ export function EventsModal({
53
101
  onBack,
54
102
  onMinimize,
55
103
  enableSharedModalDimensions = false,
104
+ inline = false,
105
+ capturing: capturingProp,
106
+ onCapturingChange,
107
+ networkDetailWrapper,
108
+ NetworkEventDetailViewComponent,
109
+ RouteEventDetailComponent,
110
+ detailComponents,
56
111
  }: EventsModalProps) {
57
112
  const router = useSafeRouter();
58
113
  const {
@@ -62,11 +117,19 @@ export function EventsModal({
62
117
  clearEvents,
63
118
  totalCount,
64
119
  filteredCount,
65
- isCapturing,
66
- toggleCapturing,
120
+ isCapturing: isCapturingLocal,
121
+ toggleCapturing: toggleCapturingLocal,
67
122
  hiddenEventsCount,
68
123
  } = useUnifiedEvents();
69
124
 
125
+ // Controlled when the host supplies both halves; otherwise the tool's own
126
+ // store is the source of truth.
127
+ const controlledCapture = capturingProp != null && onCapturingChange != null;
128
+ const isCapturing = controlledCapture ? capturingProp : isCapturingLocal;
129
+ const toggleCapturing = controlledCapture
130
+ ? () => onCapturingChange(!capturingProp)
131
+ : toggleCapturingLocal;
132
+
70
133
  const [currentView, setCurrentView] = useState<ModalView>("list");
71
134
  const [selectedEvent, setSelectedEvent] = useState<UnifiedEvent | null>(null);
72
135
  const [showUpgradeModal, setShowUpgradeModal] = useState(false);
@@ -211,6 +274,10 @@ export function EventsModal({
211
274
  event={selectedEvent}
212
275
  onBack={handleBack}
213
276
  onNavigate={handleNavigate}
277
+ networkDetailWrapper={networkDetailWrapper}
278
+ NetworkEventDetailViewComponent={NetworkEventDetailViewComponent}
279
+ RouteEventDetailComponent={RouteEventDetailComponent}
280
+ detailComponents={detailComponents}
214
281
  />
215
282
  ) : (
216
283
  <>
@@ -235,6 +302,39 @@ export function EventsModal({
235
302
  </View>
236
303
  );
237
304
 
305
+ const body = TickProvider ? <TickProvider>{content}</TickProvider> : content;
306
+
307
+ const upgradeModal = (<>
308
+ <UpgradeModal
309
+ visible={showUpgradeModal}
310
+ onClose={() => setShowUpgradeModal(false)}
311
+ featureName="Unlimited Events"
312
+ description="View your complete event history to debug complex flows and track down issues."
313
+ benefits={[
314
+ "Unlimited event history (vs 25 events)",
315
+ "Export events to Markdown, JSON, or plain text",
316
+ "Share event flows with teammates",
317
+ "Feed event context directly to AI assistants",
318
+ ]}
319
+ />
320
+ </>);
321
+
322
+ // The ONLY difference between the phone and the desktop dashboard is which
323
+ // shell the header and body go in. Everything above this line is shared.
324
+ if (inline) {
325
+ return (
326
+ <>
327
+ <View style={styles.inlineRoot}>
328
+ {/* Flex-less wrapper — `ModalHeader` is `flex: 1` for JsModal's
329
+ ROW-direction header slot and would grow vertically here. */}
330
+ <View style={styles.inlineHeader}>{renderHeaderContent()}</View>
331
+ {body}
332
+ </View>
333
+ {upgradeModal}
334
+ </>
335
+ );
336
+ }
337
+
238
338
  return (
239
339
  <>
240
340
  <JsModal
@@ -253,26 +353,26 @@ export function EventsModal({
253
353
  styles={{}}
254
354
  disableScrollWrapper={true}
255
355
  >
256
- {TickProvider ? <TickProvider>{content}</TickProvider> : content}
356
+ {body}
257
357
  </JsModal>
258
-
259
- <UpgradeModal
260
- visible={showUpgradeModal}
261
- onClose={() => setShowUpgradeModal(false)}
262
- featureName="Unlimited Events"
263
- description="View your complete event history to debug complex flows and track down issues."
264
- benefits={[
265
- "Unlimited event history (vs 25 events)",
266
- "Export events to Markdown, JSON, or plain text",
267
- "Share event flows with teammates",
268
- "Feed event context directly to AI assistants",
269
- ]}
270
- />
358
+ {upgradeModal}
271
359
  </>
272
360
  );
273
361
  }
274
362
 
275
363
  const styles = StyleSheet.create({
364
+ inlineRoot: {
365
+ flex: 1,
366
+ minHeight: 0,
367
+ backgroundColor: buoyColors.base,
368
+ },
369
+ inlineHeader: {
370
+ paddingHorizontal: 12,
371
+ paddingVertical: 8,
372
+ borderBottomWidth: 1,
373
+ borderBottomColor: buoyColors.border,
374
+ backgroundColor: buoyColors.card,
375
+ },
276
376
  container: {
277
377
  flex: 1,
278
378
  backgroundColor: buoyColors.base,
@@ -313,3 +413,15 @@ const styles = StyleSheet.create({
313
413
  borderColor: buoyColors.error + "40",
314
414
  },
315
415
  });
416
+
417
+ /**
418
+ * The same events tool as `EventsModal`, rendered INLINE for hosts that place
419
+ * tools in a panel rather than a modal. Exists so there is exactly one
420
+ * implementation — the desktop dashboard used to ship its own copy of this
421
+ * component's header and screen router.
422
+ */
423
+ export function EventsToolView(
424
+ props: Omit<EventsModalProps, "visible" | "onClose" | "inline"> = {}
425
+ ) {
426
+ return <EventsModal {...props} inline visible onClose={() => {}} />;
427
+ }
@@ -29,7 +29,7 @@ import type {
29
29
  // Optional Component Loading
30
30
  // ============================================================================
31
31
 
32
- interface OptionalDetailComponents {
32
+ export interface OptionalDetailComponents {
33
33
  StorageEventDetailContent: ComponentType<{
34
34
  conversation: unknown;
35
35
  selectedEventIndex: number;
@@ -236,6 +236,20 @@ interface UnifiedEventDetailProps {
236
236
  visitNumber?: number;
237
237
  onNavigate?: (pathname: string) => void;
238
238
  }>;
239
+ /**
240
+ * Overrides for the per-tool detail pages this component renders.
241
+ *
242
+ * ⚠️ REQUIRED IN A BUNDLED HOST. They are normally resolved with a runtime
243
+ * `require("@buoy-gg/storage")` and friends, which works under Metro but NOT
244
+ * in a Vite/ESM bundle — there every one of them silently resolves to null and
245
+ * opening an event falls back to the generic key/value renderer instead of
246
+ * that tool's real detail page. Buoy Desktop passes all of them.
247
+ *
248
+ * `NetworkEventDetailViewComponent` / `RouteEventDetailComponent` above are
249
+ * the older single-component form of the same thing and still win if both are
250
+ * supplied.
251
+ */
252
+ detailComponents?: Partial<OptionalDetailComponents>;
239
253
  /** Navigate the host app to a route (route detail "Go to route" action). */
240
254
  onNavigate?: (pathname: string) => void;
241
255
  }
@@ -246,8 +260,17 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
246
260
  NetworkEventDetailViewComponent,
247
261
  networkDetailWrapper,
248
262
  RouteEventDetailComponent,
263
+ detailComponents,
249
264
  onNavigate,
250
265
  }: UnifiedEventDetailProps) {
266
+ /**
267
+ * One resolution point for every per-tool detail page: the `require`-loaded
268
+ * set, overridden by whatever the host injected.
269
+ */
270
+ const resolved = useMemo<OptionalDetailComponents>(
271
+ () => ({ ...optionalComponents, ...detailComponents }),
272
+ [detailComponents]
273
+ );
251
274
  const sourceConfig = SOURCE_CONFIG[event.source];
252
275
  const timestamp = new Date(event.timestamp);
253
276
  // Shared ignored-domain/URL patterns — drives the "Ignore Domain / Ignore URL
@@ -259,12 +282,24 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
259
282
  // For storage events, create a conversation object to use with StorageEventDetailContent
260
283
  const storageConversation = useMemo(() => {
261
284
  if (!isStorageEvent(event.source)) return null;
262
- if (!optionalComponents.StorageEventDetailContent) return null;
285
+ if (!resolved.StorageEventDetailContent) return null;
263
286
 
264
- const originalEvent = event.originalEvent as AsyncStorageEvent & {
287
+ const raw = event.originalEvent as AsyncStorageEvent & {
265
288
  storageType?: "async" | "mmkv";
266
289
  };
267
290
 
291
+ /**
292
+ * `timestamp` is a real `Date` in-process but an ISO STRING once the event
293
+ * has crossed a sync transport, and `StorageEventDetailContent` calls
294
+ * `date.getHours()` on it. `new Date(...)` is idempotent for a Date, so
295
+ * normalising unconditionally costs nothing and covers both. The same
296
+ * reasoning is why `event.timestamp` above is wrapped.
297
+ */
298
+ const originalEvent = {
299
+ ...raw,
300
+ timestamp: new Date(raw.timestamp),
301
+ };
302
+
268
303
  // Create a conversation with a single event for the detail view
269
304
  return {
270
305
  key: originalEvent.data?.key || "unknown",
@@ -275,11 +310,11 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
275
310
  valueType: getValueType(originalEvent.data?.value),
276
311
  storageTypes: new Set([originalEvent.storageType || "async"]) as Set<"async" | "mmkv">,
277
312
  };
278
- }, [event]);
313
+ }, [event, resolved]);
279
314
 
280
315
  // For storage events, use the shared StorageEventDetailContent if available
281
- if (storageConversation && optionalComponents.StorageEventDetailContent) {
282
- const { StorageEventDetailContent } = optionalComponents;
316
+ if (storageConversation && resolved.StorageEventDetailContent) {
317
+ const { StorageEventDetailContent } = resolved;
283
318
  return (
284
319
  <View style={styles.container}>
285
320
  <StorageEventDetailContent
@@ -293,8 +328,8 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
293
328
  }
294
329
 
295
330
  // For Redux events, use the shared ReduxActionDetailContent if available
296
- if (event.source === "redux" && optionalComponents.ReduxActionDetailContent) {
297
- const { ReduxActionDetailContent } = optionalComponents;
331
+ if (event.source === "redux" && resolved.ReduxActionDetailContent) {
332
+ const { ReduxActionDetailContent } = resolved;
298
333
  const reduxAction = event.originalEvent as ReduxAction;
299
334
 
300
335
  return (
@@ -316,7 +351,7 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
316
351
  // "Ignore Domain / Ignore URL Pattern" toggles work, and wrap in the optional
317
352
  // body-resolver provider so large bodies can be fetched on demand.
318
353
  const NetworkDetailView =
319
- NetworkEventDetailViewComponent ?? optionalComponents.NetworkEventDetailView;
354
+ NetworkEventDetailViewComponent ?? resolved.NetworkEventDetailView;
320
355
  if (event.source === "network" && NetworkDetailView) {
321
356
  const networkEvent = event.originalEvent as NetworkEvent;
322
357
  const NetworkWrapper = networkDetailWrapper ?? PassThrough;
@@ -346,8 +381,8 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
346
381
  }
347
382
 
348
383
  // For Zustand events, use the shared ZustandStateDetailContent if available
349
- if (event.source === "zustand" && optionalComponents.ZustandStateDetailContent) {
350
- const { ZustandStateDetailContent } = optionalComponents;
384
+ if (event.source === "zustand" && resolved.ZustandStateDetailContent) {
385
+ const { ZustandStateDetailContent } = resolved;
351
386
  const zustandChange = event.originalEvent;
352
387
 
353
388
  return (
@@ -364,8 +399,8 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
364
399
  }
365
400
 
366
401
  // For Jotai events, use the shared JotaiAtomDetailContent if available
367
- if (event.source === "jotai" && optionalComponents.JotaiAtomDetailContent) {
368
- const { JotaiAtomDetailContent } = optionalComponents;
402
+ if (event.source === "jotai" && resolved.JotaiAtomDetailContent) {
403
+ const { JotaiAtomDetailContent } = resolved;
369
404
  const jotaiChange = event.originalEvent;
370
405
 
371
406
  return (
@@ -382,8 +417,8 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
382
417
  }
383
418
 
384
419
  // For render events, use the RenderDetailView if available
385
- if (event.source === "render" && optionalComponents.RenderDetailView) {
386
- const { RenderDetailView } = optionalComponents;
420
+ if (event.source === "render" && resolved.RenderDetailView) {
421
+ const { RenderDetailView } = resolved;
387
422
  const renderData = event.originalEvent as { render: unknown };
388
423
 
389
424
  return (
@@ -399,7 +434,7 @@ export const UnifiedEventDetail = memo(function UnifiedEventDetail({
399
434
  // Prefer an injected component (desktop), fall back to the dynamically required
400
435
  // one (mobile). onNavigate powers the "Go to route" action.
401
436
  const RouteDetail =
402
- RouteEventDetailComponent ?? optionalComponents.RouteEventDetail;
437
+ RouteEventDetailComponent ?? resolved.RouteEventDetail;
403
438
  if (event.source === "route" && RouteDetail) {
404
439
  return (
405
440
  <View style={styles.container}>
package/src/index.tsx CHANGED
@@ -19,7 +19,11 @@ export { eventsToolPreset, createEventsTool } from "./preset";
19
19
  // MAIN COMPONENT
20
20
  // =============================================================================
21
21
  export { UnifiedEventViewer } from "./components/UnifiedEventViewer";
22
- export { EventsModal } from "./components/EventsModal";
22
+ // `EventsToolView` is the same tool rendered inline (header bar + body)
23
+ // instead of inside a JsModal — for hosts that show tools in a panel.
24
+ export { EventsModal, EventsToolView } from "./components/EventsModal";
25
+ // The per-tool detail pages a bundled host must inject — see UnifiedEventDetail.
26
+ export type { OptionalDetailComponents } from "./components/UnifiedEventDetail";
23
27
 
24
28
  // =============================================================================
25
29
  // EXTERNAL SYNC (Adapter for @buoy-gg/external-sync's useExternalSync)
@@ -17,6 +17,63 @@ interface ExportEventsParams {
17
17
  limit?: number;
18
18
  }
19
19
 
20
+ // ==========================================================================
21
+ // Snapshot compaction — keep the device→broker socket healthy.
22
+ //
23
+ // Each UnifiedEvent carries `originalEvent` (full network bodies, query
24
+ // payloads, redux prev/next state trees) for the on-device detail view. The
25
+ // sync snapshot re-sends ALL events on every change (throttled to 200ms), and
26
+ // measured sessions hit 4–6MB per push — a socket firehose that starves the
27
+ // broker and the device's JS thread. Cap the per-event payload for the WIRE
28
+ // only; the on-device modal reads the store directly and keeps full detail.
29
+ // ==========================================================================
30
+
31
+ /** Max serialized bytes of one event's originalEvent on the wire. */
32
+ const MAX_SYNC_ORIGINAL_EVENT_BYTES = 16 * 1024;
33
+
34
+ interface TruncatedOriginalEvent {
35
+ __buoyTruncated: true;
36
+ approxBytes: number;
37
+ note: string;
38
+ }
39
+
40
+ // Events are immutable once created, so compaction is computed once per event
41
+ // object and drops out of the cache when the store evicts the event.
42
+ const compactionCache = new WeakMap<object, unknown>();
43
+
44
+ function compactEventForSync<T extends { originalEvent: unknown }>(event: T): T {
45
+ const original = event.originalEvent;
46
+ if (typeof original !== "object" || original === null) return event;
47
+
48
+ const cached = compactionCache.get(event as object);
49
+ if (cached !== undefined) return cached as T;
50
+
51
+ let result: T = event;
52
+ try {
53
+ const size = JSON.stringify(original)?.length ?? 0;
54
+ if (size > MAX_SYNC_ORIGINAL_EVENT_BYTES) {
55
+ const truncated: TruncatedOriginalEvent = {
56
+ __buoyTruncated: true,
57
+ approxBytes: size,
58
+ note: `Payload (${(size / 1024).toFixed(0)}KB) exceeds the ${MAX_SYNC_ORIGINAL_EVENT_BYTES / 1024}KB sync limit and stayed on the device. Open the tool on-device (or use the source tool's detail action) for the full payload.`,
59
+ };
60
+ result = { ...event, originalEvent: truncated };
61
+ }
62
+ } catch {
63
+ // Unserializable payloads would break the socket emit anyway — replace.
64
+ result = {
65
+ ...event,
66
+ originalEvent: {
67
+ __buoyTruncated: true,
68
+ approxBytes: -1,
69
+ note: "Payload is not JSON-serializable and stayed on the device.",
70
+ } satisfies TruncatedOriginalEvent,
71
+ };
72
+ }
73
+ compactionCache.set(event as object, result);
74
+ return result;
75
+ }
76
+
20
77
  /**
21
78
  * Sync adapter for the events tool, consumed by @buoy-gg/external-sync's
22
79
  * `useExternalSync` (structurally matches its ToolSyncAdapter interface so
@@ -36,7 +93,7 @@ interface ExportEventsParams {
36
93
  export const eventsSyncAdapter = {
37
94
  version: 2,
38
95
  getSnapshot: () => ({
39
- events: unifiedEventStore.getEvents(),
96
+ events: unifiedEventStore.getEvents().map(compactEventForSync),
40
97
  availableSources: Array.from(unifiedEventStore.getAvailableEventSources()),
41
98
  }),
42
99
  subscribe: (onChange: () => void) => {