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

package/apps/app-companion/src/components/avatar/vector-browser-utils.js

@@ -0,0 +1,245 @@
+/**
+ * Vector Browser — pure functions, constants, and type definitions.
+ *
+ * Shared companion-owned helpers for vector table projection and rendering.
+ */
+export const PAGE_SIZE = 25;
+export const MAX_THREE_PIXEL_RATIO = 2;
+/** The dimension columns in the elizaOS `embeddings` table. */
+export const DIM_COLUMNS = [
+    "dim_384",
+    "dim_512",
+    "dim_768",
+    "dim_1024",
+    "dim_1536",
+    "dim_3072",
+];
+export function hasEmbedding(memory) {
+    return memory.embedding !== null;
+}
+export const VECTOR_GRAPH_2D_PALETTE = [
+    "#6cf",
+    "#f59e0b",
+    "#10b981",
+    "#ef4444",
+    "#8b5cf6",
+    "#ec4899",
+    "#06b6d4",
+    "#84cc16",
+];
+/** Try to parse a JSON content field, returning the text content or the raw string. */
+export function parseContent(val) {
+    if (typeof val !== "string") {
+        if (val && typeof val === "object") {
+            const record = val;
+            if (typeof record.text === "string")
+                return record.text;
+            if (typeof record.content === "string")
+                return record.content;
+            try {
+                return JSON.stringify(val, null, 2);
+            }
+            catch {
+                return String(val);
+            }
+        }
+        return String(val ?? "");
+    }
+    if (val.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(val);
+            if (parsed.text)
+                return String(parsed.text);
+            if (parsed.content)
+                return String(parsed.content);
+            return val;
+        }
+        catch {
+            return val;
+        }
+    }
+    return val;
+}
+/** Parse an embedding from various storage formats (pgvector text, JSON, typed arrays). */
+export function parseEmbedding(val) {
+    if (!val)
+        return null;
+    if (Array.isArray(val))
+        return val;
+    // Handle typed arrays (Float32Array, Float64Array, Uint8Array etc.)
+    if (ArrayBuffer.isView(val)) {
+        return Array.from(val);
+    }
+    if (typeof val === "string" && val.length > 2) {
+        const trimmed = val.trim();
+        // pgvector text format: [0.1,0.2,0.3] — also valid JSON
+        // Also handle without brackets: 0.1,0.2,0.3
+        const inner = trimmed.startsWith("[") && trimmed.endsWith("]")
+            ? trimmed.slice(1, -1)
+            : trimmed;
+        if (!inner)
+            return null;
+        // Fast path: split by comma and parse floats
+        const parts = inner.split(",");
+        if (parts.length < 2)
+            return null;
+        const nums = [];
+        for (const p of parts) {
+            const n = Number.parseFloat(p);
+            if (Number.isNaN(n))
+                return null;
+            nums.push(n);
+        }
+        return nums;
+    }
+    return null;
+}
+export function rowToMemory(row) {
+    // Try explicit embedding/vector column first, then check elizaOS dim_* columns
+    let embeddingVal = row.embedding ?? row.vector ?? row.embeddings;
+    if (!embeddingVal) {
+        for (const dim of DIM_COLUMNS) {
+            if (row[dim]) {
+                embeddingVal = row[dim];
+                break;
+            }
+        }
+    }
+    return {
+        id: String(row.id ?? row.ID ?? row.memory_id ?? ""),
+        content: parseContent(row.content ?? row.body ?? row.text ?? ""),
+        roomId: String(row.roomId ?? row.room_id ?? row.roomID ?? ""),
+        entityId: String(row.entityId ??
+            row.entity_id ??
+            row.entityID ??
+            row.userId ??
+            row.user_id ??
+            ""),
+        type: String(row.type ?? row.memoryType ?? row.memory_type ?? ""),
+        createdAt: String(row.createdAt ?? row.created_at ?? row.timestamp ?? ""),
+        unique: row.unique === true || row.unique === 1 || row.isUnique === true,
+        embedding: parseEmbedding(embeddingVal),
+        raw: row,
+    };
+}
+export function buildVectorGraph2DLayout(memories) {
+    const withEmbeddings = memories.filter(hasEmbedding);
+    if (withEmbeddings.length < 2) {
+        return null;
+    }
+    const points = projectTo2D(withEmbeddings.map((memory) => memory.embedding));
+    let minX = Infinity;
+    let maxX = -Infinity;
+    let minY = Infinity;
+    let maxY = -Infinity;
+    for (const [x, y] of points) {
+        if (x < minX)
+            minX = x;
+        if (x > maxX)
+            maxX = x;
+        if (y < minY)
+            minY = y;
+        if (y > maxY)
+            maxY = y;
+    }
+    const typeColors = {};
+    const types = [...new Set(withEmbeddings.map((memory) => memory.type))];
+    for (let index = 0; index < types.length; index += 1) {
+        typeColors[types[index]] =
+            VECTOR_GRAPH_2D_PALETTE[index % VECTOR_GRAPH_2D_PALETTE.length];
+    }
+    return {
+        bounds: {
+            minX,
+            minY,
+            rangeX: maxX - minX || 1,
+            rangeY: maxY - minY || 1,
+        },
+        points,
+        typeColors,
+        withEmbeddings,
+    };
+}
+export function toVectorGraph2DScreenX(x, width, padding, bounds) {
+    return padding + ((x - bounds.minX) / bounds.rangeX) * (width - 2 * padding);
+}
+export function toVectorGraph2DScreenY(y, height, padding, bounds) {
+    return padding + ((y - bounds.minY) / bounds.rangeY) * (height - 2 * padding);
+}
+// ── PCA projection utilities ───────────────────────────────────────────
+function dot(a, b) {
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * (b[i] ?? 0);
+    return s;
+}
+function powerIteration(data, dims, iters = 30) {
+    const v = new Float64Array(dims);
+    // Random init
+    for (let d = 0; d < dims; d++)
+        v[d] = Math.random() - 0.5;
+    normalize(v);
+    for (let iter = 0; iter < iters; iter++) {
+        const w = new Float64Array(dims);
+        for (const row of data) {
+            const d = dot(row, v);
+            for (let j = 0; j < dims; j++)
+                w[j] += d * row[j];
+        }
+        normalize(w);
+        for (let d = 0; d < dims; d++)
+            v[d] = w[d];
+    }
+    return v;
+}
+function normalize(v) {
+    let len = 0;
+    for (let i = 0; i < v.length; i++)
+        len += v[i] * v[i];
+    len = Math.sqrt(len) || 1;
+    for (let i = 0; i < v.length; i++)
+        v[i] /= len;
+}
+/** Compute mean and center data for PCA. */
+function centerData(vectors) {
+    const dims = vectors[0].length;
+    const n = vectors.length;
+    const mean = new Float64Array(dims);
+    for (const v of vectors) {
+        for (let d = 0; d < dims; d++)
+            mean[d] += v[d];
+    }
+    for (let d = 0; d < dims; d++)
+        mean[d] /= n;
+    const centered = vectors.map((v) => v.map((x, d) => x - mean[d]));
+    return { centered, mean };
+}
+/** Deflate data by removing projection onto a principal component. */
+function deflate(data, pc) {
+    const proj = data.map((v) => dot(v, pc));
+    return data.map((v, i) => v.map((x, d) => x - proj[i] * pc[d]));
+}
+/** Project high-dimensional vectors to 2D using the first two principal axes. */
+export function projectTo2D(vectors) {
+    if (vectors.length === 0)
+        return [];
+    const dims = vectors[0].length;
+    const { centered } = centerData(vectors);
+    const pc1 = powerIteration(centered, dims);
+    const deflated1 = deflate(centered, pc1);
+    const pc2 = powerIteration(deflated1, dims);
+    return centered.map((v) => [dot(v, pc1), dot(v, pc2)]);
+}
+/** Project high-dimensional vectors to 3D using the first three principal axes. */
+export function projectTo3D(vectors) {
+    if (vectors.length === 0)
+        return [];
+    const dims = vectors[0].length;
+    const { centered } = centerData(vectors);
+    const pc1 = powerIteration(centered, dims);
+    const deflated1 = deflate(centered, pc1);
+    const pc2 = powerIteration(deflated1, dims);
+    const deflated2 = deflate(deflated1, pc2);
+    const pc3 = powerIteration(deflated2, dims);
+    return centered.map((v) => [dot(v, pc1), dot(v, pc2), dot(v, pc3)]);
+}

package/apps/app-companion/src/components/avatar/vrm-desktop-energy.d.ts

@@ -0,0 +1,40 @@
+import { type CompanionHalfFramerateMode, type CompanionVrmPowerMode } from "@elizaos/app-core";
+/** How often to re-read AC vs battery in the Electrobun shell (ms). */
+export declare const VRM_DESKTOP_BATTERY_POLL_MS = 60000;
+/**
+ * localStorage: set to **`"0"`** to keep full Retina VRM resolution on battery.
+ *
+ * **WHY:** some users prefer visual fidelity over the default **1×** pixel cap
+ * when unplugged.
+ */
+export declare const VRM_BATTERY_PIXEL_CAP_STORAGE_KEY = "eliza.vrmBatteryPixelCap";
+export declare function isVrmBatteryPixelCapEnabled(): boolean;
+export type VrmEngineBatteryPolicyTarget = {
+    isInitialized(): boolean;
+    /** DPR cap + shadow + Spark tuning — independent of frame cadence. */
+    setLowPowerRenderMode(enabled: boolean): void;
+    /** ~Half display refresh: skip alternate ticks; uses `Clock` accumulation. */
+    setHalfFramerateMode(enabled: boolean): void;
+};
+export type RefreshVrmDesktopBatteryPixelPolicyOptions = {
+    /** User Settings: quality / balanced / efficiency (default `balanced`). */
+    companionVrmPowerMode?: CompanionVrmPowerMode;
+    /**
+     * When to apply half-FPS: never, whenever pixel low-power is active, or always.
+     * Default `when_saving_power` matches historic “bundled” behavior.
+     */
+    companionHalfFramerateMode?: CompanionHalfFramerateMode;
+};
+/**
+ * Syncs **`VrmEngine`** **pixel / shadow / Spark** policy and **half-FPS** from
+ * **`desktop:getPowerState`** (Electrobun) and **`companionVrmPowerMode`**.
+ *
+ * - **`quality`:** never low-power visuals.
+ * - **`efficiency`:** always low-power visuals.
+ * - **`balanced`:** low-power visuals only when on battery and the battery pixel cap path is active.
+ *
+ * Half-FPS follows **`companionHalfFramerateMode`**: default ties it to the same
+ * moments as low-power visuals (`when_saving_power`).
+ */
+export declare function refreshVrmDesktopBatteryPixelPolicy(engine: VrmEngineBatteryPolicyTarget | null, options?: RefreshVrmDesktopBatteryPixelPolicyOptions): Promise<void>;
+//# sourceMappingURL=vrm-desktop-energy.d.ts.map

package/apps/app-companion/src/components/avatar/vrm-desktop-energy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vrm-desktop-energy.d.ts","sourceRoot":"","sources":["../../../../../../../../apps/app-companion/src/components/avatar/vrm-desktop-energy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAI3B,MAAM,mBAAmB,CAAC;AAE3B,uEAAuE;AACvE,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,6BAA6B,CAAC;AAE5E,wBAAgB,2BAA2B,IAAI,OAAO,CASrD;AAED,MAAM,MAAM,4BAA4B,GAAG;IACzC,aAAa,IAAI,OAAO,CAAC;IACzB,sEAAsE;IACtE,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9C,8EAA8E;IAC9E,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9C,CAAC;AAEF,MAAM,MAAM,0CAA0C,GAAG;IACvD,2EAA2E;IAC3E,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C;;;OAGG;IACH,0BAA0B,CAAC,EAAE,0BAA0B,CAAC;CACzD,CAAC;AAWF;;;;;;;;;;GAUG;AACH,wBAAsB,mCAAmC,CACvD,MAAM,EAAE,4BAA4B,GAAG,IAAI,EAC3C,OAAO,CAAC,EAAE,0CAA0C,GACnD,OAAO,CAAC,IAAI,CAAC,CAuCf"}

package/apps/app-companion/src/components/avatar/vrm-desktop-energy.js

@@ -0,0 +1,74 @@
+import { invokeDesktopBridgeRequest, isElectrobunRuntime, } from "@elizaos/app-core";
+/** How often to re-read AC vs battery in the Electrobun shell (ms). */
+export const VRM_DESKTOP_BATTERY_POLL_MS = 60_000;
+/**
+ * localStorage: set to **`"0"`** to keep full Retina VRM resolution on battery.
+ *
+ * **WHY:** some users prefer visual fidelity over the default **1×** pixel cap
+ * when unplugged.
+ */
+export const VRM_BATTERY_PIXEL_CAP_STORAGE_KEY = "eliza.vrmBatteryPixelCap";
+export function isVrmBatteryPixelCapEnabled() {
+    if (typeof window === "undefined")
+        return true;
+    try {
+        return (window.localStorage.getItem(VRM_BATTERY_PIXEL_CAP_STORAGE_KEY) !== "0");
+    }
+    catch {
+        return true;
+    }
+}
+function resolveHalfFramerateEnabled(halfMode, lowPowerVisual) {
+    if (halfMode === "off")
+        return false;
+    if (halfMode === "always")
+        return true;
+    return lowPowerVisual;
+}
+/**
+ * Syncs **`VrmEngine`** **pixel / shadow / Spark** policy and **half-FPS** from
+ * **`desktop:getPowerState`** (Electrobun) and **`companionVrmPowerMode`**.
+ *
+ * - **`quality`:** never low-power visuals.
+ * - **`efficiency`:** always low-power visuals.
+ * - **`balanced`:** low-power visuals only when on battery and the battery pixel cap path is active.
+ *
+ * Half-FPS follows **`companionHalfFramerateMode`**: default ties it to the same
+ * moments as low-power visuals (`when_saving_power`).
+ */
+export async function refreshVrmDesktopBatteryPixelPolicy(engine, options) {
+    const mode = options?.companionVrmPowerMode ?? "balanced";
+    const halfMode = options?.companionHalfFramerateMode ?? "when_saving_power";
+    if (!engine?.isInitialized())
+        return;
+    let lowPowerVisual;
+    if (!isElectrobunRuntime()) {
+        lowPowerVisual = mode === "efficiency";
+        engine.setLowPowerRenderMode(lowPowerVisual);
+        engine.setHalfFramerateMode(resolveHalfFramerateEnabled(halfMode, lowPowerVisual));
+        return;
+    }
+    if (!isVrmBatteryPixelCapEnabled()) {
+        lowPowerVisual = mode === "efficiency";
+        engine.setLowPowerRenderMode(lowPowerVisual);
+        engine.setHalfFramerateMode(resolveHalfFramerateEnabled(halfMode, lowPowerVisual));
+        return;
+    }
+    const power = await invokeDesktopBridgeRequest({
+        rpcMethod: "desktopGetPowerState",
+        ipcChannel: "desktop:getPowerState",
+    });
+    if (!power)
+        return;
+    if (mode === "quality") {
+        lowPowerVisual = false;
+    }
+    else if (mode === "efficiency") {
+        lowPowerVisual = true;
+    }
+    else {
+        lowPowerVisual = power.onBattery === true;
+    }
+    engine.setLowPowerRenderMode(lowPowerVisual);
+    engine.setHalfFramerateMode(resolveHalfFramerateEnabled(halfMode, lowPowerVisual));
+}

package/apps/app-companion/src/components/chat/ChatAvatar.d.ts

@@ -0,0 +1,3 @@
+export type ChatAvatarProps = Record<string, never>;
+export declare function ChatAvatar(_props: ChatAvatarProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ChatAvatar.d.ts.map

package/apps/app-companion/src/components/chat/ChatAvatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatAvatar.d.ts","sourceRoot":"","sources":["../../../../../../../../apps/app-companion/src/components/chat/ChatAvatar.tsx"],"names":[],"mappings":"AAcA,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEpD,wBAAgB,UAAU,CAAC,MAAM,EAAE,eAAe,2CAiIjD"}

package/apps/app-companion/src/components/chat/ChatAvatar.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { APP_EMOTE_EVENT, getVrmPreviewUrl, getVrmUrl, resolveAppAssetUrl, STOP_EMOTE_EVENT, useApp, } from "@elizaos/app-core";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { VrmViewer } from "../avatar/VrmViewer";
+export function ChatAvatar(_props) {
+    const { selectedVrmIndex, customVrmUrl, companionVrmPowerMode, companionHalfFramerateMode, companionAnimateWhenHidden, } = useApp();
+    // Resolve VRM path from selected index or custom upload
+    const vrmPath = selectedVrmIndex === 0 && customVrmUrl
+        ? customVrmUrl
+        : getVrmUrl(selectedVrmIndex || 1);
+    const fallbackPreviewUrl = selectedVrmIndex > 0
+        ? getVrmPreviewUrl(selectedVrmIndex)
+        : getVrmPreviewUrl(1);
+    const vrmEngineRef = useRef(null);
+    const [engineReady, setEngineReady] = useState(false);
+    const [vrmLoaded, setVrmLoaded] = useState(false);
+    const [showFallback, setShowFallback] = useState(false);
+    const avatarVisible = engineReady || vrmLoaded || showFallback;
+    const handleEngineReady = useCallback((engine) => {
+        vrmEngineRef.current = engine;
+        setEngineReady(true);
+    }, []);
+    const handleEngineState = useCallback((state) => {
+        if (state.vrmLoaded) {
+            setVrmLoaded(true);
+            setShowFallback(false);
+            return;
+        }
+        if (state.loadError) {
+            setVrmLoaded(false);
+            setShowFallback(true);
+        }
+    }, []);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: reset the loading UI when the requested VRM changes.
+    useEffect(() => {
+        setVrmLoaded(false);
+        setShowFallback(false);
+    }, [vrmPath]);
+    useEffect(() => {
+        if (!engineReady)
+            return;
+        const handler = (event) => {
+            const engine = vrmEngineRef.current;
+            if (!engine)
+                return;
+            const detail = event.detail;
+            if (!detail?.path)
+                return;
+            const resolvedPath = resolveAppAssetUrl(detail.path);
+            const duration = typeof detail.duration === "number" && Number.isFinite(detail.duration)
+                ? detail.duration
+                : 3;
+            const isLoop = detail.loop === true;
+            void engine.playEmote(resolvedPath, duration, isLoop);
+        };
+        window.addEventListener(APP_EMOTE_EVENT, handler);
+        return () => window.removeEventListener(APP_EMOTE_EVENT, handler);
+    }, [engineReady]);
+    // Listen for stop-emote events from the EmotePicker control panel.
+    useEffect(() => {
+        if (!engineReady)
+            return;
+        const handler = () => {
+            vrmEngineRef.current?.stopEmote();
+        };
+        document.addEventListener(STOP_EMOTE_EVENT, handler);
+        return () => document.removeEventListener(STOP_EMOTE_EVENT, handler);
+    }, [engineReady]);
+    return (_jsx("div", { className: "relative h-full w-full", children: _jsx("div", { className: "absolute inset-0", style: {
+                opacity: avatarVisible ? 0.95 : 0,
+                transition: "opacity 0.45s ease-in-out",
+                background: "radial-gradient(circle at 50% 100%, rgba(255,255,255,0.08), transparent 60%)",
+            }, children: _jsxs("div", { className: "absolute inset-0 overflow-hidden", children: [_jsx("div", { className: "absolute inset-0", style: {
+                            opacity: vrmLoaded ? 1 : 0,
+                            transition: "opacity 0.45s ease",
+                            // Keep a stable full-body framing in the narrow chat sidebar.
+                            transform: "scale(1.02) translateY(1%)",
+                            transformOrigin: "50% 42%",
+                        }, children: _jsx(VrmViewer, { vrmPath: vrmPath, interactive: true, interactiveMode: "orbitZoom", companionVrmPowerMode: companionVrmPowerMode, companionHalfFramerateMode: companionHalfFramerateMode, companionAnimateWhenHidden: companionAnimateWhenHidden, onEngineReady: handleEngineReady, onEngineState: handleEngineState }) }), showFallback && !vrmLoaded && (_jsx("img", { src: fallbackPreviewUrl, alt: "avatar preview", className: "absolute left-1/2 -translate-x-1/2 bottom-[-2%] h-[122%] object-contain opacity-90" })), !vrmLoaded && !showFallback && (_jsx("div", { className: "flex h-full w-full items-center justify-center", children: _jsx("div", { className: "h-8 w-8 animate-spin rounded-full border-2 border-current border-t-transparent opacity-40" }) }))] }) }) }));
+}

package/apps/app-companion/src/components/companion/CompanionAppView.d.ts

@@ -0,0 +1,9 @@
+import { type OverlayAppContext } from "@elizaos/app-core";
+/**
+ * CompanionAppView — top-level overlay app component.
+ *
+ * Mounts CompanionSceneHost (which owns VrmStage → VrmViewer → VrmEngine).
+ * Everything loads on mount, everything disposes on unmount.
+ */
+export declare function CompanionAppView(_props: OverlayAppContext): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=CompanionAppView.d.ts.map

package/apps/app-companion/src/components/companion/CompanionAppView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompanionAppView.d.ts","sourceRoot":"","sources":["../../../../../../../../apps/app-companion/src/components/companion/CompanionAppView.tsx"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,iBAAiB,EAIvB,MAAM,mBAAmB,CAAC;AAiQ3B;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,2CAQzD"}

package/apps/app-companion/src/components/companion/CompanionAppView.js

@@ -0,0 +1,114 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChatModalView, useApp, usePtySessions, useRenderGuard, } from "@elizaos/app-core";
+import { PtyConsoleSidePanel } from "@elizaos/app-task-coordinator";
+import { lazy, memo, Suspense, useCallback, useEffect, useMemo, useState, } from "react";
+import { CompanionHeader } from "./CompanionHeader";
+import { CompanionSceneHost } from "./CompanionSceneHost";
+import { useCompanionSceneStatus } from "./companion-scene-status-context";
+import { EmotePicker } from "./EmotePicker";
+import { InferenceCloudAlertButton } from "./InferenceCloudAlertButton";
+import { resolveCompanionInferenceNotice } from "./resolve-companion-inference-notice";
+const CharacterEditor = lazy(() => import("@elizaos/app-core/components/character/CharacterEditor").then((m) => ({
+    default: m.CharacterEditor,
+})));
+const COMPANION_UI_REVEAL_FALLBACK_MS = 1400;
+const COMPANION_DOCK_HEIGHT = "min(42vh, 24rem)";
+/** Isolated PTY panel — avoids polling ptySessions in the main overlay. */
+const CompanionPtyPanel = memo(function CompanionPtyPanel({ sessionId, onClose, }) {
+    const { ptySessions } = usePtySessions();
+    if (ptySessions.length === 0)
+        return null;
+    return (_jsx(PtyConsoleSidePanel, { activeSessionId: sessionId, sessions: ptySessions, onClose: onClose }));
+});
+/**
+ * Inner overlay — subscribes to useApp() for chat state.
+ * Extracted so CompanionSceneHost receives stable children.
+ */
+const CompanionOverlay = memo(function CompanionOverlay() {
+    useRenderGuard("CompanionAppView");
+    const { uiLanguage, setUiLanguage, uiTheme, setUiTheme, chatAgentVoiceMuted, chatLastUsage, conversationMessages, elizaCloudAuthRejected, elizaCloudConnected, elizaCloudCreditsError, elizaCloudEnabled, handleNewConversation, navigation, setState, setTab, t, } = useApp();
+    const [companionView, setCompanionView] = useState("companion");
+    const [ptySidePanelSessionId, setPtySidePanelSessionId] = useState(null);
+    const [historyOpen, setHistoryOpen] = useState(false);
+    const handleSidebarClose = useCallback(() => setHistoryOpen(false), []);
+    const handlePtySessionClick = useCallback((id) => setPtySidePanelSessionId((prev) => prev === id ? null : id), []);
+    const handlePtyPanelClose = useCallback(() => setPtySidePanelSessionId(null), []);
+    const { avatarReady: sceneAvatarReady } = useCompanionSceneStatus();
+    const [avatarReadyFallback, setAvatarReadyFallback] = useState(false);
+    useEffect(() => {
+        if (sceneAvatarReady) {
+            setAvatarReadyFallback(false);
+            return;
+        }
+        setAvatarReadyFallback(false);
+        const fallbackTimer = window.setTimeout(() => {
+            setAvatarReadyFallback(true);
+        }, COMPANION_UI_REVEAL_FALLBACK_MS);
+        return () => {
+            window.clearTimeout(fallbackTimer);
+        };
+    }, [sceneAvatarReady]);
+    const avatarReady = sceneAvatarReady || avatarReadyFallback;
+    useEffect(() => {
+        setState("chatMode", elizaCloudEnabled || elizaCloudConnected ? "power" : "simple");
+    }, [elizaCloudConnected, elizaCloudEnabled, setState]);
+    const hasInterruptedAssistant = useMemo(() => conversationMessages.some((m) => m.role === "assistant" && m.interrupted), [conversationMessages]);
+    const inferenceNotice = useMemo(() => resolveCompanionInferenceNotice({
+        elizaCloudConnected,
+        elizaCloudAuthRejected,
+        elizaCloudCreditsError,
+        elizaCloudEnabled,
+        chatLastUsageModel: chatLastUsage?.model,
+        hasInterruptedAssistant,
+        t,
+    }), [
+        chatLastUsage?.model,
+        elizaCloudAuthRejected,
+        elizaCloudConnected,
+        elizaCloudCreditsError,
+        elizaCloudEnabled,
+        hasInterruptedAssistant,
+        t,
+    ]);
+    // Exit companion overlay → navigate to chat / desktop mode
+    const handleExitToDesktop = useCallback(() => {
+        setState("activeOverlayApp", null);
+        setTab("chat");
+    }, [setState, setTab]);
+    // Switch to character editor within the companion overlay
+    const handleSwitchToCharacter = useCallback(() => {
+        setCompanionView("character");
+    }, []);
+    // Switch back to companion chat within the overlay
+    const handleSwitchToCompanion = useCallback(() => {
+        setCompanionView("companion");
+    }, []);
+    const handleInferenceAlertClick = useCallback(() => {
+        if (!inferenceNotice)
+            return;
+        setState("activeOverlayApp", null);
+        navigation.scheduleAfterTabCommit(() => {
+            setTab("settings");
+            if (inferenceNotice.kind === "cloud") {
+                setState("cloudDashboardView", "billing");
+            }
+        });
+    }, [inferenceNotice, navigation, setState, setTab]);
+    const companionHeaderRightExtras = (_jsx(_Fragment, { children: inferenceNotice ? (_jsx(InferenceCloudAlertButton, { notice: inferenceNotice, onPointerDown: (e) => e.stopPropagation(), onClick: handleInferenceAlertClick })) : null }));
+    return (_jsxs("div", { className: "absolute inset-0 z-10 flex flex-col pointer-events-none", children: [_jsx("div", { style: {
+                    opacity: avatarReady ? 1 : 0,
+                    transition: "opacity 0.35s ease-out",
+                    pointerEvents: avatarReady ? "auto" : "none",
+                }, children: _jsx(CompanionHeader, { activeView: companionView, onExitToDesktop: handleExitToDesktop, onExitToCharacter: handleSwitchToCharacter, onSwitchToCompanion: handleSwitchToCompanion, uiLanguage: uiLanguage, setUiLanguage: setUiLanguage, uiTheme: uiTheme, setUiTheme: setUiTheme, t: t, chatAgentVoiceMuted: chatAgentVoiceMuted, onToggleVoiceMute: () => setState("chatAgentVoiceMuted", !chatAgentVoiceMuted), onNewChat: () => void handleNewConversation(), rightExtras: companionHeaderRightExtras }) }), avatarReady && companionView === "companion" && (_jsx("div", { className: "pointer-events-auto absolute inset-x-0 bottom-0 z-20 flex justify-center px-1.5 sm:px-4", style: {
+                    paddingBottom: "calc(var(--safe-area-bottom, 0px) + 0.75rem)",
+                }, children: _jsx("div", { className: "relative w-full max-w-5xl min-w-0", style: { height: COMPANION_DOCK_HEIGHT, minHeight: "17rem" }, children: _jsx(ChatModalView, { variant: "companion-dock", showSidebar: historyOpen, onSidebarClose: handleSidebarClose, onPtySessionClick: handlePtySessionClick }) }) })), avatarReady && companionView === "character" && (_jsx(Suspense, { fallback: null, children: _jsx(CharacterEditor, { sceneOverlay: true }) })), ptySidePanelSessionId && companionView === "companion" && (_jsx("div", { className: "pointer-events-auto", children: _jsx(CompanionPtyPanel, { sessionId: ptySidePanelSessionId, onClose: handlePtyPanelClose }) })), _jsx(EmotePicker, {}), _jsx("div", { className: "flex-1 grid grid-cols-[1fr_auto] gap-6 min-h-0 relative", children: _jsx("div", { className: "w-full h-full" }) })] }));
+});
+/**
+ * CompanionAppView — top-level overlay app component.
+ *
+ * Mounts CompanionSceneHost (which owns VrmStage → VrmViewer → VrmEngine).
+ * Everything loads on mount, everything disposes on unmount.
+ */
+export function CompanionAppView(_props) {
+    return (_jsx("div", { className: "fixed inset-0 z-50 h-[100vh] w-full min-h-0 overflow-hidden supports-[height:100dvh]:h-[100dvh]", children: _jsx(CompanionSceneHost, { active: true, children: _jsx(CompanionOverlay, {}) }) }));
+}

package/apps/app-companion/src/components/companion/CompanionHeader.d.ts

@@ -0,0 +1,25 @@
+import { type UiLanguage, type UiTheme } from "@elizaos/app-core";
+import { type ReactNode } from "react";
+export type CompanionShellView = "companion" | "character";
+export interface CompanionHeaderProps {
+    /** Which internal view is currently active. */
+    activeView?: CompanionShellView;
+    /** Exit companion overlay and navigate to chat / desktop. */
+    onExitToDesktop: () => void;
+    /** Switch to the character editor view within the companion overlay. */
+    onExitToCharacter: () => void;
+    /** Switch back to the companion chat view within the overlay. */
+    onSwitchToCompanion?: () => void;
+    uiLanguage: UiLanguage;
+    setUiLanguage: (language: UiLanguage) => void;
+    uiTheme: UiTheme;
+    setUiTheme: (theme: UiTheme) => void;
+    t: (key: string) => string;
+    chatAgentVoiceMuted?: boolean;
+    onToggleVoiceMute?: () => void;
+    onNewChat?: () => void;
+    /** Shown in the shell header right cluster (e.g. inference / cloud alert). */
+    rightExtras?: ReactNode;
+}
+export declare const CompanionHeader: import("react").MemoExoticComponent<(props: CompanionHeaderProps) => import("react/jsx-runtime").JSX.Element>;
+//# sourceMappingURL=CompanionHeader.d.ts.map

package/apps/app-companion/src/components/companion/CompanionHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompanionHeader.d.ts","sourceRoot":"","sources":["../../../../../../../../apps/app-companion/src/components/companion/CompanionHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,UAAU,EACf,KAAK,OAAO,EAEb,MAAM,mBAAmB,CAAC;AAW3B,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAK7C,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,6DAA6D;IAC7D,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,iEAAiE;IACjE,mBAAmB,CAAC,EAAE,MAAM,IAAI,CAAC;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,aAAa,EAAE,CAAC,QAAQ,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACrC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED,eAAO,MAAM,eAAe,8CACnB,oBAAoB,6CA0M3B,CAAC"}