@elizaos/agent 2.0.0-alpha.358 → 2.0.0-alpha.376

package/packages/app-core/src/hooks/useActivityEvents.js

@@ -0,0 +1,126 @@
+/**
+ * Hook that subscribes to WebSocket activity events and maintains a ring buffer
+ * of recent entries for the chat widget rail.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { client } from "../api";
+const RING_BUFFER_CAP = 200;
+let nextEventId = 0;
+function makeEventId() {
+    nextEventId += 1;
+    return `evt-${nextEventId}-${Date.now()}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function summarizeAssistantActivityEvent(data) {
+    if (data.type !== "agent_event" || data.stream !== "assistant") {
+        return null;
+    }
+    const payload = isRecord(data.payload) ? data.payload : null;
+    if (!payload) {
+        return null;
+    }
+    const source = typeof payload.source === "string" ? payload.source : "";
+    const text = typeof payload.text === "string" ? payload.text.trim().slice(0, 120) : "";
+    if (!text) {
+        return null;
+    }
+    switch (source) {
+        case "lifeops-reminder":
+            return { eventType: "reminder", summary: text };
+        case "lifeops-workflow":
+            return { eventType: "workflow", summary: text };
+        case "proactive-gm":
+        case "proactive-gn":
+            return { eventType: "check-in", summary: text };
+        case "proactive-nudge":
+            return { eventType: "nudge", summary: text };
+        default:
+            return null;
+    }
+}
+/**
+ * Subscribe to task/proactive websocket events plus assistant activity events,
+ * returning a capped list of recent activity entries.
+ */
+export function useActivityEvents() {
+    const [events, setEvents] = useState([]);
+    const bufferRef = useRef([]);
+    const pushEvent = useCallback((entry) => {
+        const event = { ...entry, id: makeEventId() };
+        const buf = bufferRef.current;
+        buf.unshift(event);
+        if (buf.length > RING_BUFFER_CAP) {
+            buf.length = RING_BUFFER_CAP;
+        }
+        setEvents([...buf]);
+    }, []);
+    useEffect(() => {
+        const unbindPty = client.onWsEvent("pty-session-event", (data) => {
+            const eventType = (data.eventType ?? data.type);
+            const sessionId = data.sessionId;
+            const d = data.data;
+            let summary = eventType;
+            if (eventType === "task_registered") {
+                summary = `Task started: ${d?.label ?? sessionId ?? "unknown"}`;
+            }
+            else if (eventType === "task_complete" || eventType === "stopped") {
+                summary = `Task ${eventType === "task_complete" ? "completed" : "stopped"}`;
+            }
+            else if (eventType === "tool_running") {
+                const tool = d?.description ?? d?.toolName ?? "tool";
+                summary = `Running ${tool}`.slice(0, 80);
+            }
+            else if (eventType === "blocked") {
+                summary = "Waiting for input";
+            }
+            else if (eventType === "blocked_auto_resolved") {
+                summary = "Decision auto-approved";
+            }
+            else if (eventType === "escalation") {
+                summary = "Escalated — needs attention";
+            }
+            else if (eventType === "error") {
+                summary = "Error occurred";
+            }
+            pushEvent({
+                timestamp: Date.now(),
+                eventType,
+                sessionId: sessionId ?? undefined,
+                summary,
+            });
+        });
+        const unbindProactive = client.onWsEvent("proactive-message", (data) => {
+            const message = typeof data.message === "string"
+                ? data.message.slice(0, 120)
+                : "Proactive message";
+            pushEvent({
+                timestamp: Date.now(),
+                eventType: "proactive-message",
+                summary: message,
+            });
+        });
+        const unbindAgent = client.onWsEvent("agent_event", (data) => {
+            const activity = summarizeAssistantActivityEvent(data);
+            if (!activity) {
+                return;
+            }
+            pushEvent({
+                timestamp: Date.now(),
+                eventType: activity.eventType,
+                summary: activity.summary,
+            });
+        });
+        return () => {
+            unbindPty();
+            unbindProactive();
+            unbindAgent();
+        };
+    }, [pushEvent]);
+    const clearEvents = useCallback(() => {
+        bufferRef.current = [];
+        setEvents([]);
+    }, []);
+    return { events, clearEvents };
+}

package/packages/app-core/src/hooks/useAuthStatus.d.ts

@@ -0,0 +1,44 @@
+/**
+ * useAuthStatus — monitors the current auth state via GET /api/auth/me.
+ *
+ * Returns a discriminated union that lets the shell decide whether to render
+ * the login gate or the main dashboard.
+ *
+ * Fail-closed: network errors are treated as 401 so the login gate renders
+ * rather than the dashboard leaking in an unknown auth state.
+ *
+ * Call `refetch()` after login / logout to force a fresh check.
+ */
+import { type AuthAccessInfo, type AuthIdentity, type AuthSessionInfo } from "../api/auth-client";
+export type AuthStatusState = {
+    phase: "loading";
+} | {
+    phase: "authenticated";
+    identity: AuthIdentity;
+    session: AuthSessionInfo;
+    access: AuthAccessInfo;
+} | {
+    phase: "unauthenticated";
+    reason?: "remote_auth_required" | "remote_password_not_configured";
+    access?: AuthAccessInfo;
+} | {
+    phase: "server_unavailable";
+};
+interface UseAuthStatusOptions {
+    /**
+     * How often to re-check in the background (ms).
+     * Defaults to 5 minutes. Set to 0 to disable background polling.
+     */
+    pollIntervalMs?: number;
+    /**
+     * When true the hook will NOT start its initial fetch.
+     * Useful when the app knows auth is not yet relevant (e.g. during onboarding).
+     */
+    skip?: boolean;
+}
+export declare function useAuthStatus(options?: UseAuthStatusOptions): {
+    state: AuthStatusState;
+    refetch: () => void;
+};
+export {};
+//# sourceMappingURL=useAuthStatus.d.ts.map

package/packages/app-core/src/hooks/useAuthStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAuthStatus.d.ts","sourceRoot":"","sources":["../../../../../../app-core/src/hooks/useAuthStatus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,EAErB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,MAAM,eAAe,GACvB;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,GACpB;IACE,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,eAAe,CAAC;IACzB,MAAM,EAAE,cAAc,CAAC;CACxB,GACD;IACE,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,CAAC,EAAE,sBAAsB,GAAG,gCAAgC,CAAC;IACnE,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,GACD;IAAE,KAAK,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEpC,UAAU,oBAAoB;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAID,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG;IACjE,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAsDA"}

package/packages/app-core/src/hooks/useAuthStatus.js

@@ -0,0 +1,67 @@
+/**
+ * useAuthStatus — monitors the current auth state via GET /api/auth/me.
+ *
+ * Returns a discriminated union that lets the shell decide whether to render
+ * the login gate or the main dashboard.
+ *
+ * Fail-closed: network errors are treated as 401 so the login gate renders
+ * rather than the dashboard leaking in an unknown auth state.
+ *
+ * Call `refetch()` after login / logout to force a fresh check.
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { authMe, } from "../api/auth-client";
+const DEFAULT_POLL_INTERVAL_MS = 5 * 60 * 1000;
+export function useAuthStatus(options = {}) {
+    const { pollIntervalMs = DEFAULT_POLL_INTERVAL_MS, skip = false } = options;
+    const [state, setState] = useState({ phase: "loading" });
+    const mountedRef = useRef(true);
+    const fetch = useCallback(async () => {
+        if (!mountedRef.current)
+            return;
+        setState((prev) => prev.phase === "loading" ? prev : { phase: "loading" });
+        const result = await authMe();
+        if (!mountedRef.current)
+            return;
+        if (result.ok === true) {
+            setState({
+                phase: "authenticated",
+                identity: result.identity,
+                session: result.session,
+                access: result.access,
+            });
+        }
+        else if (result.ok === false) {
+            if (result.status === 503) {
+                setState({ phase: "server_unavailable" });
+            }
+            else {
+                setState({
+                    phase: "unauthenticated",
+                    reason: result.reason === "remote_auth_required" ||
+                        result.reason === "remote_password_not_configured"
+                        ? result.reason
+                        : undefined,
+                    access: result.access,
+                });
+            }
+        }
+    }, []);
+    useEffect(() => {
+        mountedRef.current = true;
+        if (!skip)
+            void fetch();
+        return () => {
+            mountedRef.current = false;
+        };
+    }, [skip, fetch]);
+    useEffect(() => {
+        if (skip || pollIntervalMs === 0)
+            return;
+        const id = setInterval(() => {
+            void fetch();
+        }, pollIntervalMs);
+        return () => clearInterval(id);
+    }, [skip, pollIntervalMs, fetch]);
+    return { state, refetch: fetch };
+}

package/packages/app-core/src/hooks/useBugReport.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from "react";
+export interface BugReportDraft {
+    description?: string;
+    stepsToReproduce?: string;
+    expectedBehavior?: string;
+    actualBehavior?: string;
+    environment?: string;
+    nodeVersion?: string;
+    modelProvider?: string;
+    logs?: string;
+}
+interface BugReportContextValue {
+    isOpen: boolean;
+    draft: BugReportDraft | null;
+    open: (draft?: BugReportDraft) => void;
+    close: () => void;
+}
+export declare function useOptionalBugReport(): BugReportContextValue | null;
+export declare function useBugReport(): BugReportContextValue;
+export declare function useBugReportState(): BugReportContextValue;
+export declare function BugReportProvider({ children, value, }: {
+    children: ReactNode;
+    value: BugReportContextValue;
+}): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=useBugReport.d.ts.map

package/packages/app-core/src/hooks/useBugReport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBugReport.d.ts","sourceRoot":"","sources":["../../../../../../app-core/src/hooks/useBugReport.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,SAAS,EAIf,MAAM,OAAO,CAAC;AAEf,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,UAAU,qBAAqB;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACvC,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAID,wBAAgB,oBAAoB,IAAI,qBAAqB,GAAG,IAAI,CAEnE;AAED,wBAAgB,YAAY,IAAI,qBAAqB,CAKpD;AAED,wBAAgB,iBAAiB,IAAI,qBAAqB,CAYzD;AAED,wBAAgB,iBAAiB,CAAC,EAChC,QAAQ,EACR,KAAK,GACN,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,qBAAqB,CAAC;CAC9B,2CAMA"}

package/packages/app-core/src/hooks/useBugReport.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useState, } from "react";
+const BugReportContext = createContext(null);
+export function useOptionalBugReport() {
+    return useContext(BugReportContext);
+}
+export function useBugReport() {
+    const ctx = useOptionalBugReport();
+    if (!ctx)
+        throw new Error("useBugReport must be used within BugReportProvider");
+    return ctx;
+}
+export function useBugReportState() {
+    const [isOpen, setIsOpen] = useState(false);
+    const [draft, setDraft] = useState(null);
+    const open = useCallback((nextDraft) => {
+        setDraft(nextDraft ?? null);
+        setIsOpen(true);
+    }, []);
+    const close = useCallback(() => {
+        setIsOpen(false);
+        setDraft(null);
+    }, []);
+    return { isOpen, draft, open, close };
+}
+export function BugReportProvider({ children, value, }) {
+    return (_jsx(BugReportContext.Provider, { value: value, children: children }));
+}

package/packages/app-core/src/hooks/useCanvasWindow.d.ts

@@ -0,0 +1,38 @@
+/**
+ * useCanvasWindow
+ *
+ * Creates a floating BrowserWindow (via the Electrobun canvas RPC) that is
+ * positioned and sized to match a DOM placeholder div.  The BrowserWindow
+ * appears to be "embedded" because it is always kept aligned with the div.
+ *
+ * Works in:
+ *   - Electrobun — calls via the preload-exposed renderer RPC
+ *   - Legacy desktop bridge compatibility — falls back to the historical bridge
+ *
+ * Falls back gracefully (isReady=false, no window created) when neither
+ * runtime is detected (web / Capacitor / SSR).
+ */
+export interface UseCanvasWindowOptions {
+    /** URL to load inside the floating BrowserWindow. */
+    url: string;
+    /** When false the window is not created (and any existing one is destroyed). */
+    enabled: boolean;
+    /** Window title passed to canvasCreateWindow. */
+    title?: string;
+}
+export interface UseCanvasWindowResult {
+    /** Attach to the placeholder <div> that the BrowserWindow should cover. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /** The canvas window ID returned by canvasCreateWindow, or null before ready. */
+    windowId: string | null;
+    /** True once the window has been created and positioned. */
+    isReady: boolean;
+    /** Navigate the canvas window to a new URL. */
+    navigate: (url: string) => void;
+    /** Show the canvas window (if it was hidden). */
+    show: () => void;
+    /** Hide the canvas window. */
+    hide: () => void;
+}
+export declare function useCanvasWindow(options: UseCanvasWindowOptions): UseCanvasWindowResult;
+//# sourceMappingURL=useCanvasWindow.d.ts.map

package/packages/app-core/src/hooks/useCanvasWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasWindow.d.ts","sourceRoot":"","sources":["../../../../../../app-core/src/hooks/useCanvasWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AASH,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAC;IACjB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,2EAA2E;IAC3E,YAAY,EAAE,KAAK,CAAC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,iDAAiD;IACjD,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAsTvB"}

package/packages/app-core/src/hooks/useCanvasWindow.js

@@ -0,0 +1,277 @@
+/**
+ * useCanvasWindow
+ *
+ * Creates a floating BrowserWindow (via the Electrobun canvas RPC) that is
+ * positioned and sized to match a DOM placeholder div.  The BrowserWindow
+ * appears to be "embedded" because it is always kept aligned with the div.
+ *
+ * Works in:
+ *   - Electrobun — calls via the preload-exposed renderer RPC
+ *   - Legacy desktop bridge compatibility — falls back to the historical bridge
+ *
+ * Falls back gracefully (isReady=false, no window created) when neither
+ * runtime is detected (web / Capacitor / SSR).
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { invokeDesktopBridgeRequest } from "../bridge";
+// ---------------------------------------------------------------------------
+// Geometry helpers
+// ---------------------------------------------------------------------------
+function getScreenRect(el) {
+    const rect = el.getBoundingClientRect();
+    return {
+        x: Math.round(rect.left + window.scrollX),
+        y: Math.round(rect.top + window.scrollY),
+        width: Math.round(rect.width),
+        height: Math.round(rect.height),
+    };
+}
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+export function useCanvasWindow(options) {
+    const { url, enabled, title } = options;
+    const containerRef = useRef(null);
+    const windowIdRef = useRef(null);
+    const [windowId, setWindowId] = useState(null);
+    const [isReady, setIsReady] = useState(false);
+    // Stable refs so callbacks don't need to re-bind.
+    const urlRef = useRef(url);
+    urlRef.current = url;
+    const titleRef = useRef(title);
+    titleRef.current = title;
+    // Track last-synced bounds to avoid redundant bridge calls.
+    const lastBoundsRef = useRef(null);
+    const syncFrameRef = useRef(null);
+    const trackingFrameRef = useRef(null);
+    const animationTrackerCountRef = useRef(0);
+    // ---------------------------------------------------------------------------
+    // Sync position/size to the placeholder div
+    // ---------------------------------------------------------------------------
+    const syncBounds = useCallback(() => {
+        const el = containerRef.current;
+        const id = windowIdRef.current;
+        if (!el || !id)
+            return;
+        const bounds = getScreenRect(el);
+        const last = lastBoundsRef.current;
+        if (last &&
+            last.x === bounds.x &&
+            last.y === bounds.y &&
+            last.width === bounds.width &&
+            last.height === bounds.height) {
+            return; // Nothing changed — skip the bridge call.
+        }
+        lastBoundsRef.current = bounds;
+        void invokeDesktopBridgeRequest({
+            rpcMethod: "canvasSetBounds",
+            ipcChannel: "canvas:setBounds",
+            params: { id, ...bounds },
+        }).catch((err) => {
+            console.warn("[useCanvasWindow] canvas:setBounds failed", err);
+        });
+    }, []);
+    const scheduleSyncBounds = useCallback(() => {
+        if (trackingFrameRef.current !== null || syncFrameRef.current !== null) {
+            return;
+        }
+        syncFrameRef.current = requestAnimationFrame(() => {
+            syncFrameRef.current = null;
+            syncBounds();
+        });
+    }, [syncBounds]);
+    const startTrackingBounds = useCallback(() => {
+        if (trackingFrameRef.current !== null) {
+            return;
+        }
+        const loop = () => {
+            syncBounds();
+            trackingFrameRef.current = requestAnimationFrame(loop);
+        };
+        trackingFrameRef.current = requestAnimationFrame(loop);
+    }, [syncBounds]);
+    const stopTrackingBounds = useCallback(() => {
+        if (trackingFrameRef.current !== null) {
+            cancelAnimationFrame(trackingFrameRef.current);
+            trackingFrameRef.current = null;
+        }
+        if (syncFrameRef.current !== null) {
+            cancelAnimationFrame(syncFrameRef.current);
+            syncFrameRef.current = null;
+        }
+    }, []);
+    // ---------------------------------------------------------------------------
+    // Lifecycle: create / destroy window
+    // ---------------------------------------------------------------------------
+    useEffect(() => {
+        if (!enabled)
+            return;
+        let destroyed = false;
+        let createdId = null;
+        // Determine initial position from the container div (if already mounted).
+        const el = containerRef.current;
+        const initial = el
+            ? getScreenRect(el)
+            : { x: 100, y: 100, width: 800, height: 600 };
+        void invokeDesktopBridgeRequest({
+            rpcMethod: "canvasCreateWindow",
+            ipcChannel: "canvas:createWindow",
+            params: {
+                url: urlRef.current,
+                title: titleRef.current ?? "Canvas",
+                x: initial.x,
+                y: initial.y,
+                width: initial.width,
+                height: initial.height,
+            },
+        })
+            .then((result) => {
+            if (!result) {
+                return;
+            }
+            if (destroyed) {
+                // Component unmounted before the promise resolved — clean up.
+                const id = result.id;
+                if (id) {
+                    void invokeDesktopBridgeRequest({
+                        rpcMethod: "canvasDestroyWindow",
+                        ipcChannel: "canvas:destroyWindow",
+                        params: { id },
+                    }).catch((err) => {
+                        console.warn("[useCanvasWindow] canvas:destroyWindow cleanup failed", err);
+                    });
+                }
+                return;
+            }
+            const id = result.id;
+            if (!id) {
+                console.warn("[useCanvasWindow] canvasCreateWindow returned no id");
+                return;
+            }
+            createdId = id;
+            windowIdRef.current = id;
+            setWindowId(id);
+            lastBoundsRef.current = null; // Force a setBounds on next sync.
+            setIsReady(true);
+            scheduleSyncBounds();
+        })
+            .catch((err) => {
+            console.warn("[useCanvasWindow] canvas:createWindow failed", err);
+        });
+        const isTrackedTarget = (target) => {
+            const trackedElement = containerRef.current;
+            return (trackedElement !== null &&
+                target instanceof Node &&
+                trackedElement.contains(target));
+        };
+        const handleViewportChange = () => {
+            scheduleSyncBounds();
+        };
+        const startAnimationTracking = (event) => {
+            if (!isTrackedTarget(event.target)) {
+                return;
+            }
+            animationTrackerCountRef.current += 1;
+            startTrackingBounds();
+        };
+        const stopAnimationTracking = (event) => {
+            if (!isTrackedTarget(event.target)) {
+                return;
+            }
+            animationTrackerCountRef.current = Math.max(0, animationTrackerCountRef.current - 1);
+            if (animationTrackerCountRef.current === 0) {
+                stopTrackingBounds();
+                scheduleSyncBounds();
+            }
+        };
+        window.addEventListener("resize", handleViewportChange);
+        window.addEventListener("scroll", handleViewportChange, true);
+        window.addEventListener("transitionstart", startAnimationTracking, true);
+        window.addEventListener("transitionend", stopAnimationTracking, true);
+        window.addEventListener("transitioncancel", stopAnimationTracking, true);
+        window.addEventListener("animationstart", startAnimationTracking, true);
+        window.addEventListener("animationend", stopAnimationTracking, true);
+        window.addEventListener("animationcancel", stopAnimationTracking, true);
+        window.visualViewport?.addEventListener("resize", handleViewportChange);
+        window.visualViewport?.addEventListener("scroll", handleViewportChange);
+        // ResizeObserver: pick up size changes from layout shifts.
+        let ro = null;
+        if (el && typeof ResizeObserver !== "undefined") {
+            ro = new ResizeObserver(() => {
+                scheduleSyncBounds();
+            });
+            ro.observe(el);
+        }
+        return () => {
+            destroyed = true;
+            animationTrackerCountRef.current = 0;
+            stopTrackingBounds();
+            ro?.disconnect();
+            window.removeEventListener("resize", handleViewportChange);
+            window.removeEventListener("scroll", handleViewportChange, true);
+            window.removeEventListener("transitionstart", startAnimationTracking, true);
+            window.removeEventListener("transitionend", stopAnimationTracking, true);
+            window.removeEventListener("transitioncancel", stopAnimationTracking, true);
+            window.removeEventListener("animationstart", startAnimationTracking, true);
+            window.removeEventListener("animationend", stopAnimationTracking, true);
+            window.removeEventListener("animationcancel", stopAnimationTracking, true);
+            window.visualViewport?.removeEventListener("resize", handleViewportChange);
+            window.visualViewport?.removeEventListener("scroll", handleViewportChange);
+            const id = createdId ?? windowIdRef.current;
+            if (id) {
+                windowIdRef.current = null;
+                setWindowId(null);
+                setIsReady(false);
+                lastBoundsRef.current = null;
+                void invokeDesktopBridgeRequest({
+                    rpcMethod: "canvasDestroyWindow",
+                    ipcChannel: "canvas:destroyWindow",
+                    params: { id },
+                }).catch((err) => {
+                    console.warn("[useCanvasWindow] canvas:destroyWindow teardown failed", err);
+                });
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [enabled, scheduleSyncBounds, startTrackingBounds, stopTrackingBounds]);
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    const navigate = useCallback((newUrl) => {
+        const id = windowIdRef.current;
+        if (!id)
+            return;
+        void invokeDesktopBridgeRequest({
+            rpcMethod: "canvasNavigate",
+            ipcChannel: "canvas:navigate",
+            params: { id, url: newUrl },
+        }).catch((err) => {
+            console.warn("[useCanvasWindow] canvas:navigate failed", err);
+        });
+    }, []);
+    const show = useCallback(() => {
+        const id = windowIdRef.current;
+        if (!id)
+            return;
+        void invokeDesktopBridgeRequest({
+            rpcMethod: "canvasShow",
+            ipcChannel: "canvas:show",
+            params: { id },
+        }).catch((err) => {
+            console.warn("[useCanvasWindow] canvas:show failed", err);
+        });
+    }, []);
+    const hide = useCallback(() => {
+        const id = windowIdRef.current;
+        if (!id)
+            return;
+        void invokeDesktopBridgeRequest({
+            rpcMethod: "canvasHide",
+            ipcChannel: "canvas:hide",
+            params: { id },
+        }).catch((err) => {
+            console.warn("[useCanvasWindow] canvas:hide failed", err);
+        });
+    }, []);
+    return { containerRef, windowId, isReady, navigate, show, hide };
+}

package/packages/app-core/src/hooks/useChatAvatarVoiceBridge.d.ts

@@ -0,0 +1,12 @@
+export interface UseChatAvatarVoiceBridgeOptions {
+    mouthOpen: number;
+    isSpeaking: boolean;
+    usingAudioAnalysis: boolean;
+    onSpeakingChange: (isSpeaking: boolean) => void;
+}
+/**
+ * Pushes voice analysis from {@link useVoiceChat} to the companion avatar via
+ * {@link CHAT_AVATAR_VOICE_EVENT} and syncs speaking state into chat shell state.
+ */
+export declare function useChatAvatarVoiceBridge({ mouthOpen, isSpeaking, onSpeakingChange, }: UseChatAvatarVoiceBridgeOptions): void;
+//# sourceMappingURL=useChatAvatarVoiceBridge.d.ts.map

package/packages/app-core/src/hooks/useChatAvatarVoiceBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatAvatarVoiceBridge.d.ts","sourceRoot":"","sources":["../../../../../../app-core/src/hooks/useChatAvatarVoiceBridge.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,gBAAgB,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,SAAS,EACT,UAAU,EACV,gBAAgB,GACjB,EAAE,+BAA+B,GAAG,IAAI,CAkBxC"}

package/packages/app-core/src/hooks/useChatAvatarVoiceBridge.js

@@ -0,0 +1,21 @@
+import { useEffect, useRef } from "react";
+import { CHAT_AVATAR_VOICE_EVENT, } from "../events";
+/**
+ * Pushes voice analysis from {@link useVoiceChat} to the companion avatar via
+ * {@link CHAT_AVATAR_VOICE_EVENT} and syncs speaking state into chat shell state.
+ */
+export function useChatAvatarVoiceBridge({ mouthOpen, isSpeaking, onSpeakingChange, }) {
+    const prevSpeakingRef = useRef(isSpeaking);
+    useEffect(() => {
+        if (prevSpeakingRef.current !== isSpeaking) {
+            prevSpeakingRef.current = isSpeaking;
+            onSpeakingChange(isSpeaking);
+        }
+    }, [isSpeaking, onSpeakingChange]);
+    useEffect(() => {
+        const detail = { mouthOpen, isSpeaking };
+        window.dispatchEvent(new CustomEvent(CHAT_AVATAR_VOICE_EVENT, {
+            detail,
+        }));
+    }, [mouthOpen, isSpeaking]);
+}