@buoy-gg/console 4.0.2

package/src/preset.tsx

@@ -0,0 +1,35 @@
+/**
+ * Pre-configured Console tool for FloatingDevTools.
+ *
+ * @example
+ * ```tsx
+ * import { consoleToolPreset } from '@buoy-gg/console';
+ *
+ * <FloatingDevTools apps={[consoleToolPreset]} />
+ * ```
+ */
+
+import { ConsoleIcon, CONSOLE_ICON_COLOR } from "./components/ConsoleIcon";
+import { ConsoleModal } from "./components/ConsoleModal";
+
+export const consoleToolPreset = {
+  id: "console",
+  name: "CONSOLE",
+  description: "Captured console.* output",
+  slot: "both" as const,
+  icon: ({ size, color }: { size: number; color?: string }) => (
+    <ConsoleIcon size={size} color={color || CONSOLE_ICON_COLOR} />
+  ),
+  component: ConsoleModal,
+};
+
+/** Create a custom Console tool configuration. */
+export function createConsoleTool(
+  options: { name?: string; description?: string } = {}
+) {
+  return {
+    ...consoleToolPreset,
+    name: options.name ?? consoleToolPreset.name,
+    description: options.description ?? consoleToolPreset.description,
+  };
+}

package/src/store/consoleLogStore.ts

@@ -0,0 +1,346 @@
+/**
+ * consoleLogStore
+ *
+ * Intercepts the global `console` methods and keeps a bounded ring buffer of
+ * captured entries, modeled after Chrome DevTools' ConsoleMessage. Direct
+ * console patching is the capture path (works identically on Expo, RN CLI, and
+ * web). The DevTools-style view layer (filtering, formatting, grouping) is built
+ * on top of these raw entries.
+ *
+ * By default the buffer is in-memory only, so a JS reload starts fresh — just
+ * like the Metro/Chrome console. A "Preserve log" toggle persists the buffer to
+ * storage and restores it on the next launch (Chrome's "Preserve log").
+ */
+
+import * as React from "react";
+import { persistentStorage } from "@buoy-gg/shared-ui";
+import { sanitizeArgs } from "./sanitize";
+import { parseOrigin, type LogOrigin } from "../devtools/origin";
+
+/** The console method that produced an entry. */
+export type ConsoleMethod =
+  | "log"
+  | "info"
+  | "warn"
+  | "error"
+  | "debug"
+  | "trace"
+  | "dir"
+  | "table"
+  | "assert"
+  | "group"
+  | "groupCollapsed"
+  | "groupEnd";
+
+/** DevTools log levels (Protocol.Log.LogEntryLevel). */
+export type ConsoleLevel = "verbose" | "info" | "warning" | "error";
+
+export interface ConsoleLogEntry {
+  /** Monotonic id, unique per captured entry. */
+  id: number;
+  /** The console method that produced this entry. */
+  method: ConsoleMethod;
+  /** DevTools level, derived from the method. */
+  level: ConsoleLevel;
+  /** The raw arguments passed to the console method. */
+  args: unknown[];
+  /** Pre-rendered single-line text (used for filtering + the simple list). */
+  message: string;
+  /** Capture time in ms since epoch. */
+  timestamp: number;
+  /** Captured JS stack (error/warn/trace only), newest frame first. */
+  stack?: string;
+  /** Where the log came from (component / function / call site). */
+  origin?: LogOrigin;
+}
+
+/** Methods we intercept, in the order we install them. */
+const METHODS: ConsoleMethod[] = [
+  "log",
+  "info",
+  "warn",
+  "error",
+  "debug",
+  "trace",
+  "dir",
+  "table",
+  "assert",
+  "group",
+  "groupCollapsed",
+  "groupEnd",
+];
+
+/** Methods whose call site we capture a stack for. */
+const STACK_METHODS = new Set<ConsoleMethod>(["error", "warn", "trace", "assert"]);
+
+/** method → DevTools level. */
+const METHOD_LEVEL: Record<ConsoleMethod, ConsoleLevel> = {
+  error: "error",
+  assert: "error",
+  warn: "warning",
+  debug: "verbose",
+  log: "info",
+  info: "info",
+  trace: "info",
+  dir: "info",
+  table: "info",
+  group: "info",
+  groupCollapsed: "info",
+  groupEnd: "info",
+};
+
+/** Max entries retained before the oldest are dropped. */
+const MAX_ENTRIES = 1000;
+
+type Listener = () => void;
+
+let entries: ConsoleLogEntry[] = [];
+let nextId = 1;
+let installed = false;
+
+const listeners = new Set<Listener>();
+const clearListeners = new Set<Listener>();
+
+/** Saved originals so we can restore on uninstall and still print through. */
+const originals: Partial<Record<ConsoleMethod, (...args: unknown[]) => void>> = {};
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+/** Best-effort, single-line serialization of a single console argument. */
+function formatArg(arg: unknown): string {
+  if (typeof arg === "string") return arg;
+  if (arg instanceof Error) return arg.stack ?? `${arg.name}: ${arg.message}`;
+  if (arg === undefined) return "undefined";
+  if (arg === null) return "null";
+  if (typeof arg === "function") return `ƒ ${arg.name || "(anonymous)"}`;
+  try {
+    return JSON.stringify(arg);
+  } catch {
+    return String(arg);
+  }
+}
+
+function formatArgs(args: unknown[]): string {
+  return args.map(formatArg).join(" ");
+}
+
+/** Drop the "Error" header + the interceptor's own frames from a raw stack. */
+function cleanStack(raw?: string): string | undefined {
+  if (!raw) return undefined;
+  return raw.split("\n").slice(3).join("\n") || undefined;
+}
+
+/** Nearest owning React component stack (dev only; empty off-render). */
+function captureOwnerStack(): string | undefined {
+  try {
+    const fn = (React as unknown as { captureOwnerStack?: () => string | null })
+      .captureOwnerStack;
+    return typeof fn === "function" ? fn() ?? undefined : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function record(method: ConsoleMethod, args: unknown[]): void {
+  // Capture the call site for every log so we can attribute its origin.
+  const rawStack = new Error().stack;
+  const origin = parseOrigin(rawStack, captureOwnerStack());
+  const entry: ConsoleLogEntry = {
+    id: nextId++,
+    method,
+    level: METHOD_LEVEL[method],
+    args,
+    message: formatArgs(args),
+    timestamp: Date.now(),
+    stack: STACK_METHODS.has(method) ? cleanStack(rawStack) : undefined,
+    origin,
+  };
+  entries =
+    entries.length >= MAX_ENTRIES
+      ? [...entries.slice(entries.length - MAX_ENTRIES + 1), entry]
+      : [...entries, entry];
+  emit();
+  scheduleSave();
+}
+
+/**
+ * Patch the global console methods. Idempotent — safe to call more than once.
+ * Each patched method still forwards to the original so normal logging keeps
+ * working (Metro terminal, Chrome, native logcat/Xcode).
+ */
+export function installConsoleCapture(): void {
+  if (installed) return;
+  installed = true;
+
+  for (const method of METHODS) {
+    const original = console[method] as ((...args: unknown[]) => void) | undefined;
+    if (typeof original !== "function") continue;
+    originals[method] = original;
+    // Named so origin parsing can identify (and skip) this frame by function
+    // name — in a Metro bundle every frame shares one bundle URL, so filename
+    // filtering can't distinguish our wrapper from the real caller.
+    console[method] = function buoyConsoleProxy(...args: unknown[]) {
+      record(method, args);
+      original.apply(console, args);
+    };
+  }
+}
+
+/** Restore the original console methods. */
+export function uninstallConsoleCapture(): void {
+  if (!installed) return;
+  installed = false;
+  for (const method of METHODS) {
+    const original = originals[method];
+    if (original) console[method] = original;
+    delete originals[method];
+  }
+}
+
+/** Subscribe to changes. Returns an unsubscribe function. */
+export function subscribe(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Current snapshot (stable reference between mutations for useSyncExternalStore). */
+export function getEntries(): ConsoleLogEntry[] {
+  return entries;
+}
+
+/** Clear all captured entries. Fires onClear listeners (e.g. to forward the
+ * clear to a remote device when running in mirror mode). */
+export function clearEntries(): void {
+  for (const listener of clearListeners) listener();
+  void clearSavedBuffer();
+  if (entries.length === 0) return;
+  entries = [];
+  emit();
+}
+
+// ─── Remote-mirror mode (desktop dashboard) ──────────────────────────────────
+// The desktop imports this same store but, instead of patching its own console,
+// drives it from device snapshots via replaceEntries(). Capture is never
+// installed there, so local and remote modes never mix.
+
+/** Replace the whole entry list from a remote snapshot. */
+export function replaceEntries(next: ConsoleLogEntry[]): void {
+  entries = next.length > MAX_ENTRIES ? next.slice(next.length - MAX_ENTRIES) : next;
+  emit();
+}
+
+/** Register a listener fired when clearEntries() is called. Returns an
+ * unsubscribe function. Used by the dashboard to forward clears to the device. */
+export function onClear(listener: Listener): () => void {
+  clearListeners.add(listener);
+  return () => {
+    clearListeners.delete(listener);
+  };
+}
+
+// ─── Preserve log (persist across reload) ────────────────────────────────────
+// Default OFF: the buffer is in-memory only, so a reload starts fresh. When ON,
+// the buffer is saved to storage (debounced) and restored on the next launch.
+
+const PRESERVE_KEY = "@react_buoy_console_preserve";
+const BUFFER_KEY = "@react_buoy_console_buffer";
+const SAVE_DEBOUNCE_MS = 600;
+
+let preserveLog = false;
+let persistenceReady = false;
+const preserveListeners = new Set<Listener>();
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+
+function emitPreserve(): void {
+  for (const listener of preserveListeners) listener();
+}
+
+function scheduleSave(): void {
+  if (!preserveLog) return;
+  if (saveTimer) clearTimeout(saveTimer);
+  saveTimer = setTimeout(saveBuffer, SAVE_DEBOUNCE_MS);
+}
+
+async function saveBuffer(): Promise<void> {
+  saveTimer = null;
+  if (!preserveLog) return;
+  try {
+    const serializable = entries.map((entry) => ({
+      ...entry,
+      args: sanitizeArgs(entry.args),
+    }));
+    await persistentStorage.setItem(BUFFER_KEY, JSON.stringify(serializable));
+  } catch {
+    // Storage unavailable — preserve is best-effort.
+  }
+}
+
+async function clearSavedBuffer(): Promise<void> {
+  try {
+    await persistentStorage.removeItem(BUFFER_KEY);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Load the persisted preserve-log flag and, if enabled, restore the saved
+ * buffer. If disabled, drop any saved buffer so the session starts fresh.
+ * Idempotent — safe to call from ConsoleRoot on every mount.
+ */
+export async function initConsolePersistence(): Promise<void> {
+  if (persistenceReady) return;
+  persistenceReady = true;
+  try {
+    preserveLog = (await persistentStorage.getItem(PRESERVE_KEY)) === "true";
+  } catch {
+    preserveLog = false;
+  }
+  emitPreserve();
+
+  if (!preserveLog) {
+    await clearSavedBuffer();
+    return;
+  }
+  try {
+    const raw = await persistentStorage.getItem(BUFFER_KEY);
+    if (raw) {
+      const saved = JSON.parse(raw) as ConsoleLogEntry[];
+      if (Array.isArray(saved) && saved.length) {
+        // Prepend restored entries before anything captured this session.
+        entries = [...saved, ...entries].slice(-MAX_ENTRIES);
+        nextId = Math.max(nextId, ...saved.map((e) => e.id + 1));
+        emit();
+      }
+    }
+  } catch {
+    // Corrupt/absent buffer — ignore.
+  }
+}
+
+/** Whether logs persist across reload. */
+export function getPreserveLog(): boolean {
+  return preserveLog;
+}
+
+/** Toggle preserve-log. Persists the flag; saves or drops the buffer. */
+export function setPreserveLog(next: boolean): void {
+  if (preserveLog === next) return;
+  preserveLog = next;
+  emitPreserve();
+  persistentStorage.setItem(PRESERVE_KEY, String(next)).catch(() => {});
+  if (next) saveBuffer();
+  else clearSavedBuffer();
+}
+
+/** Subscribe to preserve-log changes. Returns an unsubscribe function. */
+export function subscribePreserveLog(listener: Listener): () => void {
+  preserveListeners.add(listener);
+  return () => {
+    preserveListeners.delete(listener);
+  };
+}

package/src/store/sanitize.ts

@@ -0,0 +1,58 @@
+/**
+ * sanitizeArgs — deep-convert captured console arguments into JSON-safe values.
+ *
+ * Captured `args` can hold Errors, functions, bigints, symbols, and circular
+ * references. Both the external-sync snapshot (device → desktop) and the
+ * preserve-log persistence need plain JSON, so this produces a structural copy
+ * (objects/arrays preserved so they stay expandable) with cycles broken.
+ */
+
+const MAX_DEPTH = 6;
+const MAX_ARRAY = 100;
+const MAX_KEYS = 100;
+
+function sanitizeValue(value: unknown, depth: number, seen: WeakSet<object>): unknown {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return value;
+  if (t === "number") return Number.isFinite(value as number) ? value : String(value);
+  if (t === "undefined") return "undefined";
+  if (t === "bigint") return `${String(value)}n`;
+  if (t === "function") return `ƒ ${(value as { name?: string }).name || "(anonymous)"}`;
+  if (t === "symbol") return (value as symbol).toString();
+
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack };
+  }
+
+  if (depth >= MAX_DEPTH) return Array.isArray(value) ? "[Array]" : "{…}";
+
+  const obj = value as object;
+  if (seen.has(obj)) return "[Circular]";
+  seen.add(obj);
+
+  try {
+    if (Array.isArray(value)) {
+      const out = value.slice(0, MAX_ARRAY).map((v) => sanitizeValue(v, depth + 1, seen));
+      if (value.length > MAX_ARRAY) out.push(`… ${value.length - MAX_ARRAY} more`);
+      return out;
+    }
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).slice(0, MAX_KEYS)) {
+      try {
+        out[key] = sanitizeValue((obj as Record<string, unknown>)[key], depth + 1, seen);
+      } catch {
+        out[key] = "[Unserializable]";
+      }
+    }
+    return out;
+  } finally {
+    seen.delete(obj);
+  }
+}
+
+/** Deep-sanitize an array of console arguments into JSON-safe values. */
+export function sanitizeArgs(args: unknown[]): unknown[] {
+  const seen = new WeakSet<object>();
+  return args.map((arg) => sanitizeValue(arg, 0, seen));
+}

package/src/sync/consoleSyncAdapter.ts

@@ -0,0 +1,49 @@
+/**
+ * consoleSyncAdapter — streams captured console entries from the device to the
+ * desktop dashboard via @buoy-gg/external-sync.
+ *
+ * Structurally matches external-sync's `ToolSyncAdapter` WITHOUT importing the
+ * package (so console has no hard dependency on external-sync, matching how the
+ * other tools' adapters are written). Auto-discovery in @buoy-gg/core picks it
+ * up by the export name and announces the "console" capability.
+ *
+ * Snapshots MUST be JSON-serializable. Captured `args` can hold Errors,
+ * functions, bigints, and circular references, so we deep-sanitize them into
+ * plain JSON values (objects/arrays preserved so they stay expandable on the
+ * dashboard).
+ */
+
+import {
+  subscribe,
+  getEntries,
+  clearEntries,
+  type ConsoleLogEntry,
+} from "../store/consoleLogStore";
+import { sanitizeArgs } from "../store/sanitize";
+
+interface ConsoleSnapshot {
+  entries: ConsoleLogEntry[];
+}
+
+export const consoleSyncAdapter = {
+  version: 1,
+
+  getSnapshot(): ConsoleSnapshot {
+    const entries = getEntries().map((entry) => ({
+      ...entry,
+      args: sanitizeArgs(entry.args),
+    }));
+    return { entries };
+  },
+
+  subscribe(onChange: () => void): () => void {
+    return subscribe(onChange);
+  },
+
+  actions: {
+    clearEntries(): { cleared: true } {
+      clearEntries();
+      return { cleared: true };
+    },
+  },
+};