@elizaos/app-core 2.0.0-alpha.10

package/src/hooks/useLifoSync.ts

@@ -0,0 +1,143 @@
+import { useCallback, useEffect, useRef } from "react";
+import {
+  getLifoSyncChannelName,
+  type LifoRuntime,
+  type LifoSyncMessage,
+  normalizeTerminalText,
+} from "../platform";
+
+interface UseLifoSyncOptions {
+  popoutMode: boolean;
+  lifoSessionId: string | null;
+  runtimeRef: React.RefObject<LifoRuntime | null>;
+  appendOutput: (line: string) => void;
+  setRunCount: React.Dispatch<React.SetStateAction<number>>;
+  setSessionKey: React.Dispatch<React.SetStateAction<number>>;
+  setControllerOnline: React.Dispatch<React.SetStateAction<boolean>>;
+  controllerHeartbeatAtRef: React.MutableRefObject<number>;
+}
+
+interface UseLifoSyncReturn {
+  broadcastSyncMessage: (message: Omit<LifoSyncMessage, "source">) => void;
+  syncChannelRef: React.RefObject<BroadcastChannel | null>;
+}
+
+export function useLifoSync({
+  popoutMode,
+  lifoSessionId,
+  runtimeRef,
+  appendOutput,
+  setRunCount,
+  setSessionKey,
+  setControllerOnline,
+  controllerHeartbeatAtRef,
+}: UseLifoSyncOptions): UseLifoSyncReturn {
+  const syncChannelRef = useRef<BroadcastChannel | null>(null);
+
+  const broadcastSyncMessage = useCallback(
+    (message: Omit<LifoSyncMessage, "source">) => {
+      if (!popoutMode) return;
+      syncChannelRef.current?.postMessage({
+        source: "controller",
+        ...message,
+      } satisfies LifoSyncMessage);
+    },
+    [popoutMode],
+  );
+
+  useEffect(() => {
+    if (typeof BroadcastChannel === "undefined") return;
+
+    const channel = new BroadcastChannel(getLifoSyncChannelName(lifoSessionId));
+    syncChannelRef.current = channel;
+
+    let heartbeatInterval: ReturnType<typeof setInterval> | null = null;
+    let heartbeatWatchInterval: ReturnType<typeof setInterval> | null = null;
+
+    if (popoutMode) {
+      setControllerOnline(true);
+      broadcastSyncMessage({ type: "heartbeat" });
+      heartbeatInterval = setInterval(() => {
+        broadcastSyncMessage({ type: "heartbeat" });
+      }, 1000);
+    } else {
+      heartbeatWatchInterval = setInterval(() => {
+        const online = Date.now() - controllerHeartbeatAtRef.current < 3500;
+        setControllerOnline(online);
+      }, 1000);
+    }
+
+    channel.onmessage = (event: MessageEvent<unknown>) => {
+      if (popoutMode) return;
+      const data = event.data as Partial<LifoSyncMessage> | null;
+      if (!data || data.source !== "controller") return;
+
+      if (data.type === "heartbeat") {
+        controllerHeartbeatAtRef.current = Date.now();
+        setControllerOnline(true);
+        return;
+      }
+
+      const runtime = runtimeRef.current;
+      if (!runtime) return;
+
+      switch (data.type) {
+        case "session-reset":
+          setSessionKey((value) => value + 1);
+          break;
+        case "command-start":
+          if (typeof data.command !== "string") return;
+          runtime.terminal.writeln(`$ ${data.command}`);
+          appendOutput(`$ ${data.command}`);
+          setRunCount((prev) => prev + 1);
+          break;
+        case "stdout":
+          if (typeof data.chunk !== "string") return;
+          runtime.terminal.write(normalizeTerminalText(data.chunk));
+          if (data.chunk.trimEnd()) appendOutput(data.chunk.trimEnd());
+          break;
+        case "stderr":
+          if (typeof data.chunk !== "string") return;
+          runtime.terminal.write(normalizeTerminalText(data.chunk));
+          if (data.chunk.trimEnd()) {
+            appendOutput(`stderr: ${data.chunk.trimEnd()}`);
+          }
+          break;
+        case "command-exit":
+          if (typeof data.exitCode !== "number") return;
+          runtime.terminal.writeln(`[exit ${data.exitCode}]`);
+          appendOutput(`[exit ${data.exitCode}]`);
+          try {
+            runtime.explorer.refresh();
+          } catch {
+            // Ignore refresh failures when mirroring popout events.
+          }
+          break;
+        case "command-error":
+          if (typeof data.message !== "string") return;
+          runtime.terminal.writeln(`error: ${data.message}`);
+          appendOutput(`error: ${data.message}`);
+          break;
+      }
+    };
+
+    return () => {
+      if (heartbeatInterval) clearInterval(heartbeatInterval);
+      if (heartbeatWatchInterval) clearInterval(heartbeatWatchInterval);
+      syncChannelRef.current = null;
+      channel.close();
+    };
+  }, [
+    appendOutput,
+    broadcastSyncMessage,
+    controllerHeartbeatAtRef,
+    lifoSessionId,
+    popoutMode,
+    runtimeRef,
+    setControllerOnline,
+    setRunCount,
+    setSessionKey,
+  ]);
+
+  return { broadcastSyncMessage, syncChannelRef };
+}

package/src/hooks/useMemoryMonitor.ts

@@ -0,0 +1,334 @@
+/**
+ * Memory monitoring hook for detecting memory leaks.
+ *
+ * Uses the Performance API's memory metrics (Chrome/Edge only) to track
+ * heap usage over time and detect potential memory leaks by analyzing
+ * growth patterns.
+ *
+ * Usage:
+ *   const { metrics, isLeaking, trend } = useMemoryMonitor({ enabled: true });
+ *
+ * The hook samples memory at regular intervals and calculates:
+ * - Current heap usage
+ * - Heap growth trend (MB/min)
+ * - Leak detection based on sustained growth
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+// Extend Performance interface for memory info (Chrome/Edge only)
+interface PerformanceMemory {
+  usedJSHeapSize: number;
+  totalJSHeapSize: number;
+  jsHeapSizeLimit: number;
+}
+
+interface PerformanceWithMemory extends Performance {
+  memory?: PerformanceMemory;
+}
+
+export interface MemoryMetrics {
+  /** Current used JS heap size in bytes */
+  usedHeapSize: number;
+  /** Total JS heap size in bytes */
+  totalHeapSize: number;
+  /** JS heap size limit in bytes */
+  heapSizeLimit: number;
+  /** Heap usage as percentage of limit */
+  usagePercent: number;
+  /** Timestamp of measurement */
+  timestamp: number;
+}
+
+export interface MemorySample {
+  usedHeapSize: number;
+  timestamp: number;
+}
+
+export interface MemoryTrend {
+  /** Growth rate in bytes per minute (positive = growing) */
+  bytesPerMinute: number;
+  /** Growth rate in MB per minute */
+  mbPerMinute: number;
+  /** Number of samples in the analysis window */
+  sampleCount: number;
+  /** Duration of analysis window in minutes */
+  windowMinutes: number;
+}
+
+export interface UseMemoryMonitorOptions {
+  /** Enable memory monitoring (default: true in dev mode) */
+  enabled?: boolean;
+  /** Sampling interval in milliseconds (default: 5000) */
+  sampleInterval?: number;
+  /** Number of samples to keep for trend analysis (default: 60) */
+  maxSamples?: number;
+  /** Threshold in MB/min to consider a leak (default: 1.0) */
+  leakThresholdMbPerMin?: number;
+  /** Minimum samples before detecting leaks (default: 12) */
+  minSamplesForDetection?: number;
+  /** Callback when a potential leak is detected */
+  onLeakDetected?: (trend: MemoryTrend, metrics: MemoryMetrics) => void;
+}
+
+export interface UseMemoryMonitorResult {
+  /** Whether memory API is supported in this browser */
+  supported: boolean;
+  /** Current memory metrics (null if not supported) */
+  metrics: MemoryMetrics | null;
+  /** Memory growth trend analysis */
+  trend: MemoryTrend | null;
+  /** Whether a potential memory leak is detected */
+  isLeaking: boolean;
+  /** Historical samples for charting */
+  samples: MemorySample[];
+  /** Force garbage collection (if available) */
+  forceGC: () => void;
+  /** Clear sample history */
+  clearHistory: () => void;
+  /** Get formatted memory stats for display */
+  getFormattedStats: () => string;
+}
+
+const DEFAULT_OPTIONS: Required<
+  Omit<UseMemoryMonitorOptions, "onLeakDetected">
+> = {
+  enabled: Boolean(import.meta.env.DEV),
+  sampleInterval: 5000,
+  maxSamples: 60,
+  leakThresholdMbPerMin: 1.0,
+  minSamplesForDetection: 12,
+};
+
+function getMemoryInfo(): PerformanceMemory | null {
+  const perf = performance as PerformanceWithMemory;
+  return perf.memory ?? null;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  if (bytes < 1024 * 1024 * 1024)
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+function calculateTrend(samples: MemorySample[]): MemoryTrend | null {
+  if (samples.length < 2) return null;
+
+  const firstSample = samples[0];
+  const lastSample = samples[samples.length - 1];
+  const durationMs = lastSample.timestamp - firstSample.timestamp;
+
+  if (durationMs <= 0) return null;
+
+  const durationMinutes = durationMs / (1000 * 60);
+  const heapChange = lastSample.usedHeapSize - firstSample.usedHeapSize;
+  const bytesPerMinute = heapChange / durationMinutes;
+  const mbPerMinute = bytesPerMinute / (1024 * 1024);
+
+  return {
+    bytesPerMinute,
+    mbPerMinute,
+    sampleCount: samples.length,
+    windowMinutes: durationMinutes,
+  };
+}
+
+export function useMemoryMonitor(
+  options: UseMemoryMonitorOptions = {},
+): UseMemoryMonitorResult {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const {
+    enabled,
+    sampleInterval,
+    maxSamples,
+    leakThresholdMbPerMin,
+    minSamplesForDetection,
+  } = opts;
+
+  const [supported, setSupported] = useState(false);
+  const [metrics, setMetrics] = useState<MemoryMetrics | null>(null);
+  const [samples, setSamples] = useState<MemorySample[]>([]);
+  const [trend, setTrend] = useState<MemoryTrend | null>(null);
+  const [isLeaking, setIsLeaking] = useState(false);
+
+  const onLeakDetectedRef = useRef(options.onLeakDetected);
+  onLeakDetectedRef.current = options.onLeakDetected;
+  const lastLeakNotifyRef = useRef(0);
+
+  // Check browser support
+  useEffect(() => {
+    const memInfo = getMemoryInfo();
+    setSupported(memInfo !== null);
+  }, []);
+
+  // Sample memory at intervals
+  useEffect(() => {
+    if (!enabled || !supported) return;
+
+    const sample = () => {
+      const memInfo = getMemoryInfo();
+      if (!memInfo) return;
+
+      const now = Date.now();
+      const currentMetrics: MemoryMetrics = {
+        usedHeapSize: memInfo.usedJSHeapSize,
+        totalHeapSize: memInfo.totalJSHeapSize,
+        heapSizeLimit: memInfo.jsHeapSizeLimit,
+        usagePercent: (memInfo.usedJSHeapSize / memInfo.jsHeapSizeLimit) * 100,
+        timestamp: now,
+      };
+
+      setMetrics(currentMetrics);
+
+      setSamples((prev) => {
+        const newSample: MemorySample = {
+          usedHeapSize: memInfo.usedJSHeapSize,
+          timestamp: now,
+        };
+
+        const updated = [...prev, newSample];
+        if (updated.length > maxSamples) {
+          updated.splice(0, updated.length - maxSamples);
+        }
+        return updated;
+      });
+    };
+
+    // Initial sample
+    sample();
+
+    const intervalId = setInterval(sample, sampleInterval);
+    return () => clearInterval(intervalId);
+  }, [enabled, supported, sampleInterval, maxSamples]);
+
+  // Calculate trend and detect leaks
+  useEffect(() => {
+    if (samples.length < 2) {
+      setTrend(null);
+      setIsLeaking(false);
+      return;
+    }
+
+    const currentTrend = calculateTrend(samples);
+    setTrend(currentTrend);
+
+    if (!currentTrend || samples.length < minSamplesForDetection) {
+      setIsLeaking(false);
+      return;
+    }
+
+    // Detect sustained memory growth
+    const leaking = currentTrend.mbPerMinute > leakThresholdMbPerMin;
+    setIsLeaking(leaking);
+
+    // Notify callback (throttled to once per minute)
+    if (leaking && metrics && onLeakDetectedRef.current) {
+      const now = Date.now();
+      if (now - lastLeakNotifyRef.current > 60000) {
+        lastLeakNotifyRef.current = now;
+        onLeakDetectedRef.current(currentTrend, metrics);
+      }
+    }
+  }, [samples, minSamplesForDetection, leakThresholdMbPerMin, metrics]);
+
+  const forceGC = useCallback(() => {
+    // gc() is only available when Chrome is started with --js-flags="--expose-gc"
+    const win = window as Window & { gc?: () => void };
+    if (typeof win.gc === "function") {
+      win.gc();
+    }
+  }, []);
+
+  const clearHistory = useCallback(() => {
+    setSamples([]);
+    setTrend(null);
+    setIsLeaking(false);
+  }, []);
+
+  const getFormattedStats = useCallback(() => {
+    if (!metrics) return "Memory monitoring not available";
+
+    const lines = [
+      `Heap Used: ${formatBytes(metrics.usedHeapSize)}`,
+      `Heap Total: ${formatBytes(metrics.totalHeapSize)}`,
+      `Heap Limit: ${formatBytes(metrics.heapSizeLimit)}`,
+      `Usage: ${metrics.usagePercent.toFixed(1)}%`,
+    ];
+
+    if (trend) {
+      const trendSign = trend.mbPerMinute >= 0 ? "+" : "";
+      lines.push(
+        `Trend: ${trendSign}${trend.mbPerMinute.toFixed(2)} MB/min`,
+        `Samples: ${trend.sampleCount} (${trend.windowMinutes.toFixed(1)} min)`,
+      );
+    }
+
+    if (isLeaking) {
+      lines.push("WARNING: Potential memory leak detected!");
+    }
+
+    return lines.join("\n");
+  }, [metrics, trend, isLeaking]);
+
+  return {
+    supported,
+    metrics,
+    trend,
+    isLeaking,
+    samples,
+    forceGC,
+    clearHistory,
+    getFormattedStats,
+  };
+}
+
+/**
+ * Lightweight memory leak detector that logs warnings to console.
+ * Can be used as a standalone function without React.
+ */
+export function startMemoryLeakDetector(options?: {
+  intervalMs?: number;
+  thresholdMbPerMin?: number;
+  onLeak?: (info: { mbPerMinute: number; currentMb: number }) => void;
+}): () => void {
+  const intervalMs = options?.intervalMs ?? 10000;
+  const thresholdMbPerMin = options?.thresholdMbPerMin ?? 2.0;
+  const samples: MemorySample[] = [];
+  const maxSamples = 30;
+
+  const intervalId = setInterval(() => {
+    const memInfo = getMemoryInfo();
+    if (!memInfo) return;
+
+    const now = Date.now();
+    samples.push({
+      usedHeapSize: memInfo.usedJSHeapSize,
+      timestamp: now,
+    });
+
+    if (samples.length > maxSamples) {
+      samples.shift();
+    }
+
+    if (samples.length >= 6) {
+      const trend = calculateTrend(samples);
+      if (trend && trend.mbPerMinute > thresholdMbPerMin) {
+        const currentMb = memInfo.usedJSHeapSize / (1024 * 1024);
+        console.warn(
+          `[MemoryLeakDetector] Potential memory leak detected!\n` +
+            `  Growth rate: +${trend.mbPerMinute.toFixed(2)} MB/min\n` +
+            `  Current heap: ${currentMb.toFixed(1)} MB\n` +
+            `  Window: ${trend.windowMinutes.toFixed(1)} min (${trend.sampleCount} samples)`,
+        );
+        options?.onLeak?.({
+          mbPerMinute: trend.mbPerMinute,
+          currentMb,
+        });
+      }
+    }
+  }, intervalMs);
+
+  return () => clearInterval(intervalId);
+}

package/src/hooks/useRenderGuard.ts

@@ -0,0 +1,43 @@
+import { useRef } from "react";
+
+const THRESHOLD = 3;
+const WINDOW_MS = 1000;
+const IS_DEV =
+  typeof process !== "undefined" &&
+  (process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test");
+
+/**
+ * Development-only render-rate guard.
+ *
+ * Tracks render timestamps for the named component and logs a console warning
+ * when the component re-renders {@link THRESHOLD} or more times within
+ * {@link WINDOW_MS} ms.  No-op in production builds.
+ *
+ * Usage:
+ * ```ts
+ * function MyComponent() {
+ *   useRenderGuard("MyComponent");
+ *   // …
+ * }
+ * ```
+ */
+export function useRenderGuard(name: string): void {
+  // Always call the hook (preserve hook call order) but skip work in prod.
+  const timestamps = useRef<number[]>([]);
+  if (!IS_DEV) return;
+
+  const now = Date.now();
+  const ts = timestamps.current;
+  ts.push(now);
+
+  // Prune old entries outside the window
+  while (ts.length > 0 && ts[0] < now - WINDOW_MS) {
+    ts.shift();
+  }
+
+  if (ts.length >= THRESHOLD) {
+    console.warn(
+      `[RenderGuard] "${name}" rendered ${ts.length}× in the last ${WINDOW_MS}ms`,
+    );
+  }
+}

package/src/hooks/useRetakeCapture.ts

@@ -0,0 +1,67 @@
+/**
+ * Hook that controls desktop native frame capture for retake.tv streaming.
+ *
+ * Uses the native desktop capture path through the renderer bridge — this captures
+ * the full compositor output including cross-origin iframes (unlike the old canvas approach
+ * which was blocked by same-origin policy).
+ *
+ * The main process handles capture + HTTP POST to /api/stream/frame directly.
+ * This hook just sends start/stop signals.
+ */
+
+import { useEffect, useRef } from "react";
+import { invokeDesktopBridgeRequest } from "../bridge";
+
+const DEFAULT_FPS = 15;
+const JPEG_QUALITY = 70;
+
+export function useRetakeCapture(
+  _iframeRef: React.RefObject<HTMLIFrameElement | null>,
+  active: boolean,
+  fps = DEFAULT_FPS,
+) {
+  const activeRef = useRef(false);
+
+  useEffect(() => {
+    if (active && !activeRef.current) {
+      activeRef.current = true;
+      void invokeDesktopBridgeRequest({
+        rpcMethod: "screencaptureStartFrameCapture",
+        ipcChannel: "screencapture:startFrameCapture",
+        params: {
+          fps,
+          quality: JPEG_QUALITY,
+          apiBase: window.__MILADY_API_BASE__ ?? "http://localhost:2138",
+          endpoint: "/api/stream/frame",
+        },
+      })
+        .then((result) => {
+          if (result === null) {
+            activeRef.current = false;
+          }
+        })
+        .catch((err) => {
+          console.warn("[retake] Failed to start frame capture:", err);
+          activeRef.current = false;
+        });
+    } else if (!active && activeRef.current) {
+      activeRef.current = false;
+      void invokeDesktopBridgeRequest({
+        rpcMethod: "screencaptureStopFrameCapture",
+        ipcChannel: "screencapture:stopFrameCapture",
+      }).catch((err) => {
+        console.warn("[retake] Failed to stop frame capture:", err);
+      });
+    }
+
+    return () => {
+      if (activeRef.current) {
+        activeRef.current = false;
+        void invokeDesktopBridgeRequest({
+          rpcMethod: "screencaptureStopFrameCapture",
+          ipcChannel: "screencapture:stopFrameCapture",
+        }).catch(() => {});
+      }
+    };
+  }, [active, fps]);
+}

package/src/hooks/useStreamPopoutNavigation.ts

@@ -0,0 +1,27 @@
+import { useEffect } from "react";
+
+export function getNextTabForStreamPopoutEvent<TTab extends string>(
+  _detail: unknown,
+): TTab | null {
+  return null;
+}
+
+export function useStreamPopoutNavigation<TTab extends string>(
+  setTab: (tab: TTab) => void,
+): void {
+  useEffect(() => {
+    const target =
+      typeof window !== "undefined" ? window : (globalThis as EventTarget);
+    const handler = (event: Event) => {
+      const nextTab = getNextTabForStreamPopoutEvent<TTab>(
+        (event as CustomEvent).detail,
+      );
+      if (nextTab) {
+        setTab(nextTab);
+      }
+    };
+
+    target.addEventListener("stream-popout", handler);
+    return () => target.removeEventListener("stream-popout", handler);
+  }, [setTab]);
+}

package/src/hooks/useTimeout.ts

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Custom hook to safely manage `setTimeout` calls within React components.
+ * Automatically clears the timeout if the component unmounts before it fires.
+ *
+ * Returns `{ setTimeout, clearTimeout }` which mimic the global functions.
+ */
+export function useTimeout() {
+  const timeoutRefs = useRef<Set<ReturnType<typeof setTimeout>>>(new Set());
+
+  const setSafeTimeout = useCallback((callback: () => void, ms: number) => {
+    const id = setTimeout(() => {
+      timeoutRefs.current.delete(id);
+      callback();
+    }, ms);
+    timeoutRefs.current.add(id);
+    return id;
+  }, []);
+
+  const clearSafeTimeout = useCallback((id: ReturnType<typeof setTimeout>) => {
+    clearTimeout(id);
+    timeoutRefs.current.delete(id);
+  }, []);
+
+  useEffect(() => {
+    const refs = timeoutRefs;
+    return () => {
+      for (const id of refs.current) {
+        clearTimeout(id);
+      }
+      refs.current.clear();
+    };
+  }, []);
+
+  return { setTimeout: setSafeTimeout, clearTimeout: clearSafeTimeout };
+}