@elizaos/agent 2.0.0-alpha.520 → 2.0.0-alpha.521

package/apps/app-companion/src/components/avatar/VrmEngine.js

@@ -1,2003 +0,0 @@
-import { resolveAppAssetUrl } from "@elizaos/app-core";
-import { MToonMaterialLoaderPlugin, VRMLoaderPlugin, VRMUtils, } from "@pixiv/three-vrm";
-import * as THREE from "three";
-import { MathEnvironment } from "./MathEnvironment";
-import { SceneOverlayManager } from "./SceneOverlayManager";
-import { OrbitControls } from "three/examples/jsm/controls/OrbitControls.js";
-import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
-import { DRACOLoader } from "three/examples/jsm/loaders/DRACOLoader.js";
-import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
-import { loadEmoteClip, loadIdleClip, } from "./VrmAnimationLoader";
-import { VrmBlinkController } from "./VrmBlinkController";
-import { VrmCameraManager, } from "./VrmCameraManager";
-const DEFAULT_CAMERA_ANIMATION = {
-    enabled: false,
-    swayAmplitude: 0.06,
-    bobAmplitude: 0.03,
-    rotationAmplitude: 0.01,
-    speed: 0.8,
-};
-const CAMERA_PROFILE_TRANSITION_DURATION_SECONDS = 0.8;
-const AVATAR_SWITCH_CAMERA_TRANSITION_DURATION_SECONDS = 3;
-const TELEPORT_DISSOLVE_START_Y = -1.2;
-const TELEPORT_DISSOLVE_END_Y = 1.0;
-const COMPANION_ZOOM_NEAR_FACTOR = 0.25;
-const COMPANION_ZOOM_MIN_RADIUS = 1.2;
-const MAX_RENDERER_PIXEL_RATIO = 2;
-const AVATAR_RENDERER_OVERRIDE_KEY = "eliza.avatarRenderer";
-const KNOWN_VRM_WEBGPU_WARNING = 'TSL: "transformedNormalView" is deprecated. Use "normalView" instead.';
-let knownVrmWebGpuWarningFilterRefs = 0;
-let releaseKnownVrmWebGpuWarningFilterGlobal = null;
-let sharedDracoLoader = null;
-let teleportSparkleTexture = null;
-let _cachedDracoDecoderPath = null;
-/** Lazy + cached: module-load resolution can be wrong in bundled/desktop init order. */
-function getDracoDecoderPath() {
-    _cachedDracoDecoderPath ??= resolveAppAssetUrl("vrm-decoders/draco/");
-    return _cachedDracoDecoderPath;
-}
-function getRendererPixelRatio() {
-    if (typeof window === "undefined")
-        return 1;
-    return Math.min(Math.max(window.devicePixelRatio || 1, 1), MAX_RENDERER_PIXEL_RATIO);
-}
-function isElectrobunAvatarRuntime() {
-    if (typeof window === "undefined")
-        return false;
-    const runtimeWindow = window;
-    return (typeof runtimeWindow.__electrobunWindowId === "number" ||
-        typeof runtimeWindow.__electrobunWebviewId === "number");
-}
-function getPreferredAvatarRendererBackend() {
-    if (typeof window === "undefined")
-        return "webgl";
-    const override = (() => {
-        try {
-            return window.localStorage.getItem(AVATAR_RENDERER_OVERRIDE_KEY);
-        }
-        catch {
-            return null;
-        }
-    })();
-    const normalizedOverride = override?.trim().toLowerCase();
-    if (normalizedOverride === "webgpu" || normalizedOverride === "webgl") {
-        return normalizedOverride;
-    }
-    return isElectrobunAvatarRuntime() ? "webgpu" : "webgl";
-}
-function installKnownVrmWebGpuWarningFilter() {
-    knownVrmWebGpuWarningFilterRefs += 1;
-    if (!releaseKnownVrmWebGpuWarningFilterGlobal) {
-        const originalWarn = console.warn.bind(console);
-        console.warn = (...args) => {
-            if (typeof args[0] === "string" &&
-                args[0].includes(KNOWN_VRM_WEBGPU_WARNING)) {
-                return;
-            }
-            originalWarn(...args);
-        };
-        releaseKnownVrmWebGpuWarningFilterGlobal = () => {
-            knownVrmWebGpuWarningFilterRefs = Math.max(0, knownVrmWebGpuWarningFilterRefs - 1);
-            if (knownVrmWebGpuWarningFilterRefs === 0) {
-                console.warn = originalWarn;
-                releaseKnownVrmWebGpuWarningFilterGlobal = null;
-            }
-        };
-    }
-    return () => {
-        releaseKnownVrmWebGpuWarningFilterGlobal?.();
-    };
-}
-function getSharedDracoLoader() {
-    if (!sharedDracoLoader) {
-        sharedDracoLoader = new DRACOLoader();
-        sharedDracoLoader.setDecoderConfig({ type: "wasm" });
-        sharedDracoLoader.setDecoderPath(getDracoDecoderPath());
-        sharedDracoLoader.preload();
-    }
-    // three/examples and the current GLTF loader declarations diverge on the
-    // decoder surface, but this runtime instance is the loader we use in app.
-    return sharedDracoLoader;
-}
-function configureVrmGltfLoader(loader) {
-    // three/examples and the current GLTF loader declarations diverge on the
-    // meshopt decoder surface, but this runtime instance is the decoder we ship.
-    loader.setMeshoptDecoder(MeshoptDecoder);
-    loader.setDRACOLoader(getSharedDracoLoader());
-}
-function getTeleportSparkleTexture() {
-    if (teleportSparkleTexture)
-        return teleportSparkleTexture;
-    const canvas = document.createElement("canvas");
-    canvas.width = 128;
-    canvas.height = 128;
-    const context = canvas.getContext("2d");
-    if (!context) {
-        teleportSparkleTexture = new THREE.CanvasTexture(canvas);
-        return teleportSparkleTexture;
-    }
-    const gradient = context.createRadialGradient(64, 64, 6, 64, 64, 64);
-    gradient.addColorStop(0.0, "rgba(255,255,255,1)");
-    gradient.addColorStop(0.2, "rgba(190,245,255,0.95)");
-    gradient.addColorStop(0.55, "rgba(112,214,255,0.48)");
-    gradient.addColorStop(1.0, "rgba(112,214,255,0)");
-    context.fillStyle = gradient;
-    context.fillRect(0, 0, 128, 128);
-    teleportSparkleTexture = new THREE.CanvasTexture(canvas);
-    teleportSparkleTexture.needsUpdate = true;
-    return teleportSparkleTexture;
-}
-function isGzipBuffer(buffer) {
-    if (buffer.byteLength < 2)
-        return false;
-    const bytes = new Uint8Array(buffer, 0, 2);
-    return bytes[0] === 0x1f && bytes[1] === 0x8b;
-}
-async function decompressGzipBuffer(buffer) {
-    if (typeof DecompressionStream !== "function") {
-        throw new Error("This runtime does not support gzip-compressed VRM assets.");
-    }
-    const stream = new Blob([buffer])
-        .stream()
-        .pipeThrough(new DecompressionStream("gzip"));
-    return await new Response(stream).arrayBuffer();
-}
-const vrmBufferCache = new Map();
-const VRM_BUFFER_CACHE_MAX = 8;
-/**
- * In-flight prefetch promises keyed by URL. Prevents duplicate concurrent
- * downloads when `loadGltfAsset` runs while a prefetch for the same URL is
- * still in progress.
- */
-const vrmPrefetchInflight = new Map();
-function touchVrmCacheEntry(url, buffer) {
-    vrmBufferCache.set(url, { buffer, lastUsed: performance.now() });
-    // Evict oldest entries when over capacity.
-    while (vrmBufferCache.size > VRM_BUFFER_CACHE_MAX) {
-        let oldestKey = null;
-        let oldestTime = Infinity;
-        for (const [key, entry] of vrmBufferCache) {
-            if (entry.lastUsed < oldestTime) {
-                oldestTime = entry.lastUsed;
-                oldestKey = key;
-            }
-        }
-        if (oldestKey)
-            vrmBufferCache.delete(oldestKey);
-        else
-            break;
-    }
-}
-/**
- * Prefetch a VRM file into the in-memory buffer cache without parsing it.
- * Fire-and-forget: silently swallows errors since prefetch is best-effort.
- * Calling this when the character tab opens means the buffer is ready before
- * the user clicks a character, turning a ~3-8 s cold fetch into a <200 ms
- * re-parse from cache.
- */
-export async function prefetchVrmToCache(url) {
-    if (vrmBufferCache.has(url))
-        return; // already warm
-    // If a prefetch for this URL is already in flight, join it instead of
-    // starting a duplicate download.
-    const existing = vrmPrefetchInflight.get(url);
-    if (existing)
-        return existing;
-    const work = (async () => {
-        try {
-            const response = await fetch(url, { cache: "force-cache" });
-            if (!response.ok)
-                return;
-            let buffer = await response.arrayBuffer();
-            if (isGzipBuffer(buffer))
-                buffer = await decompressGzipBuffer(buffer);
-            touchVrmCacheEntry(url, buffer);
-        }
-        catch {
-            // Prefetch is best-effort — network errors are silently ignored.
-        }
-        finally {
-            vrmPrefetchInflight.delete(url);
-        }
-    })();
-    vrmPrefetchInflight.set(url, work);
-    return work;
-}
-async function loadGltfAsset(loader, url, onProgress) {
-    let buffer;
-    // If a prefetch for this URL is in flight, await it so we hit the
-    // in-memory cache instead of starting a duplicate network request.
-    const inflight = vrmPrefetchInflight.get(url);
-    if (inflight) {
-        await inflight;
-    }
-    const cached = vrmBufferCache.get(url);
-    if (cached) {
-        // Cache hit — skip network entirely, copy the buffer so the cache stays
-        // valid even if GLTFLoader transfers/neuters the original.
-        buffer = cached.buffer.slice(0);
-        touchVrmCacheEntry(url, cached.buffer);
-        onProgress?.(1);
-    }
-    else {
-        // Cache miss — fetch from network/browser cache.
-        const response = await fetch(url, { cache: "force-cache" });
-        if (!response.ok) {
-            throw new Error(`Failed to fetch VRM asset: ${response.status}`);
-        }
-        const contentLength = Number(response.headers.get("content-length") || 0);
-        if (!contentLength || !response.body || !onProgress) {
-            buffer = await response.arrayBuffer();
-            onProgress?.(1);
-        }
-        else {
-            const reader = response.body.getReader();
-            let received = 0;
-            const chunks = [];
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                if (value) {
-                    chunks.push(value);
-                    received += value.length;
-                    onProgress(Math.min(received / contentLength, 1));
-                }
-            }
-            const combined = new Uint8Array(received);
-            let offset = 0;
-            for (const chunk of chunks) {
-                combined.set(chunk, offset);
-                offset += chunk.length;
-            }
-            buffer = combined.buffer;
-        }
-        // Decompress gzip if needed, then store the decompressed bytes.
-        if (isGzipBuffer(buffer)) {
-            buffer = await decompressGzipBuffer(buffer);
-        }
-        // Store a copy in the cache (keep the original for parsing below).
-        touchVrmCacheEntry(url, buffer.slice(0));
-    }
-    const objectUrl = URL.createObjectURL(new Blob([buffer], { type: "model/gltf-binary" }));
-    try {
-        return await loader.loadAsync(objectUrl);
-    }
-    finally {
-        URL.revokeObjectURL(objectUrl);
-    }
-}
-/**
- * Create the best available renderer for the canvas.
- * Tries WebGPURenderer only when preference allows, Electrobun defaults prefer
- * webgpu, and `navigator.gpu` exists; otherwise uses WebGL (also on WebGPU init failure).
- * Non-Electrobun (e.g. browser dev) defaults preference to WebGL to reduce TSL noise.
- * `localStorage` can force `webgpu` or `webgl`. WebGPURenderer is async; await `init()` when present.
- */
-async function createRenderer(canvas, preference = "auto") {
-    if (preference !== "webgl" &&
-        getPreferredAvatarRendererBackend() === "webgpu" &&
-        typeof navigator !== "undefined" &&
-        navigator.gpu) {
-        try {
-            const { WebGPURenderer } = await import("three/webgpu");
-            const renderer = new WebGPURenderer({
-                canvas,
-                alpha: true,
-                antialias: true,
-            });
-            await renderer.init?.();
-            console.info("[VrmEngine] Using WebGPURenderer");
-            return { backend: "webgpu", renderer };
-        }
-        catch (err) {
-            console.warn("[VrmEngine] WebGPURenderer failed, falling back to WebGL:", err);
-        }
-    }
-    const renderer = new THREE.WebGLRenderer({
-        canvas,
-        alpha: true,
-        antialias: true,
-    });
-    console.info("[VrmEngine] Using WebGLRenderer");
-    return { backend: "webgl", renderer };
-}
-export class VrmEngine {
-    renderer = null;
-    rendererBackend = "webgl";
-    rendererPreference = "auto";
-    scene = null;
-    mathEnvironment = null;
-    overlayManager = null;
-    avatarRoot = null;
-    camera = null;
-    clock = new THREE.Clock();
-    vrm = null;
-    mixer = null;
-    idleAction = null;
-    idleLoadPromise = null;
-    animationFrameId = null;
-    onUpdate = null;
-    initialized = false;
-    loadingAborted = false;
-    vrmLoadRequestId = 0;
-    vrmReady = false;
-    lastLoadError = null;
-    teleportProgress = 1.0;
-    loadingProgress = 0;
-    /** Timestamp (from elapsedTime) when the teleport dissolve finished. */
-    teleportCompleteTime = -Infinity;
-    teleportProgressUniform = null;
-    teleportDissolvedMaterials = [];
-    teleportFallbackShaders = [];
-    teleportSparkles = null;
-    revealStarted = false;
-    mouthValue = 0;
-    mouthSmoothed = 0;
-    vrmName = null;
-    lookAtTarget = new THREE.Vector3(0, 0.5, 0);
-    idleGlbUrl = resolveAppAssetUrl("animations/idle.glb.gz");
-    outgoingVrm = null;
-    outgoingMixer = null;
-    cameraAnimation = {
-        ...DEFAULT_CAMERA_ANIMATION,
-    };
-    baseCameraPosition = new THREE.Vector3();
-    elapsedTime = 0;
-    speaking = false;
-    speakingStartTime = 0;
-    blinkController = new VrmBlinkController();
-    cameraManager = new VrmCameraManager();
-    emoteAction = null;
-    emoteTimeout = null;
-    emoteCompletionCleanup = null;
-    emoteClipCache = new Map();
-    emoteRequestId = 0;
-    controls = null;
-    /** Key light used for avatar shadows — toggled in low-power mode. */
-    keyDirectionalLight = null;
-    /** When true, cap effective `devicePixelRatio` at 1 (fewer shaded pixels on Retina). */
-    lowPowerRenderMode = false;
-    /**
-     * When true, skip every other animation tick (~half display rate). Independent
-     * of {@link lowPowerRenderMode}; `Clock.getDelta()` on active ticks absorbs skips.
-     */
-    halfFramerateMode = false;
-    halfFramerateSkipNext = false;
-    paused = false;
-    /**
-     * When true, only VRM idle/physics keep running (document hidden + user opt-in).
-     */
-    minimalBackgroundMode = false;
-    interactionEnabled = false;
-    interactionMode = "free";
-    cameraProfile = "chat";
-    pointerParallaxEnabled = false;
-    pointerParallaxTarget = new THREE.Vector2();
-    pointerParallaxCurrent = new THREE.Vector2();
-    pointerParallaxPosition = new THREE.Vector3();
-    pointerParallaxLookAt = new THREE.Vector3();
-    dragOrbitTarget = new THREE.Vector2();
-    dragOrbitCurrent = new THREE.Vector2();
-    companionZoomTarget = 0;
-    companionZoomCurrent = 0;
-    cameraXOffsetTarget = 0;
-    cameraXOffsetCurrent = 0;
-    /** Orbital yaw offset applied by the editor camera shift. */
-    cameraYawOffsetTarget = 0;
-    cameraYawOffsetCurrent = 0;
-    avatarLookTarget = null;
-    headLookTarget = new THREE.Vector2();
-    headLookCurrent = new THREE.Vector2();
-    clearEmoteTimeout() {
-        if (this.emoteTimeout !== null) {
-            clearTimeout(this.emoteTimeout);
-            this.emoteTimeout = null;
-        }
-    }
-    clearEmoteCompletionCleanup() {
-        this.emoteCompletionCleanup?.();
-        this.emoteCompletionCleanup = null;
-    }
-    clearPendingEmoteCompletion() {
-        this.clearEmoteTimeout();
-        this.clearEmoteCompletionCleanup();
-    }
-    watchOneShotEmoteCompletion(mixer, action, requestId, fallbackDurationSeconds) {
-        const handleFinished = (event) => {
-            if (event.action !== action)
-                return;
-            if (this.emoteRequestId !== requestId || this.emoteAction !== action) {
-                return;
-            }
-            this.stopEmote();
-        };
-        mixer.addEventListener("finished", handleFinished);
-        this.emoteCompletionCleanup = () => {
-            mixer.removeEventListener("finished", handleFinished);
-        };
-        const safeDuration = Number.isFinite(fallbackDurationSeconds) && fallbackDurationSeconds > 0
-            ? fallbackDurationSeconds
-            : 3;
-        // Keep a timer fallback in case the mixer completion event is missed.
-        this.emoteTimeout = setTimeout(() => {
-            if (this.emoteRequestId !== requestId || this.emoteAction !== action) {
-                return;
-            }
-            this.stopEmote();
-        }, Math.max(0.25, safeDuration + 0.1) * 1000);
-    }
-    activateAction(action) {
-        action.enabled = true;
-        action.paused = false;
-        action.setEffectiveTimeScale(1);
-        action.setEffectiveWeight(1);
-        action.play();
-    }
-    async ensureIdleAction(vrm, mixer) {
-        if (this.idleAction)
-            return this.idleAction;
-        if (this.idleLoadPromise)
-            return this.idleLoadPromise;
-        this.idleLoadPromise = (async () => {
-            const clip = await loadIdleClip(vrm, this.idleGlbUrl, this.animationLoaderContext);
-            if (!clip || this.loadingAborted || this.vrm !== vrm) {
-                return null;
-            }
-            const activeMixer = this.mixer ?? mixer;
-            if (!activeMixer || this.vrm !== vrm) {
-                return null;
-            }
-            const action = activeMixer.clipAction(clip);
-            action.reset();
-            action.setLoop(THREE.LoopRepeat, Infinity);
-            action.timeScale = 1.0;
-            this.idleAction = action;
-            activeMixer.update(1 / 60);
-            return action;
-        })().finally(() => {
-            this.idleLoadPromise = null;
-        });
-        return this.idleLoadPromise;
-    }
-    restoreIdleAfterEmote(activeEmote, fadeDuration, vrm, mixer) {
-        void this.ensureIdleAction(vrm, mixer).then((idleAction) => {
-            if (!idleAction || this.loadingAborted || this.vrm !== vrm) {
-                activeEmote?.fadeOut(fadeDuration);
-                return;
-            }
-            this.activateAction(idleAction);
-            if (activeEmote && activeEmote !== idleAction) {
-                idleAction.crossFadeFrom(activeEmote, fadeDuration, false);
-            }
-            else {
-                idleAction.fadeIn(fadeDuration);
-            }
-        });
-    }
-    avatarLookRig = {
-        headBone: null,
-        neckBone: null,
-        spineBone: null,
-    };
-    tempCameraOrbitOffset = new THREE.Vector3();
-    tempCameraSpherical = new THREE.Spherical();
-    tempAvatarLookTarget = new THREE.Vector3();
-    tempAvatarLocalTarget = new THREE.Vector3();
-    tempAvatarLocalAnchor = new THREE.Vector3();
-    tempAvatarHeadWorld = new THREE.Vector3();
-    readyPromise = Promise.resolve();
-    resolveReady = null;
-    rejectReady = null;
-    releaseKnownWebGpuWarningFilter = null;
-    // Transition state
-    isCameraTransitioning = false;
-    transitionStartFov = 0;
-    transitionTargetFov = 0;
-    transitionStartPos = new THREE.Vector3();
-    transitionTargetPos = new THREE.Vector3();
-    transitionStartLookAt = new THREE.Vector3();
-    transitionTargetLookAt = new THREE.Vector3();
-    transitionProgress = 0;
-    transitionDuration = CAMERA_PROFILE_TRANSITION_DURATION_SECONDS;
-    handleControlStart = () => {
-        if (!this.interactionEnabled)
-            return;
-    };
-    handleControlEnd = () => {
-        if (!this.interactionEnabled)
-            return;
-        if (this.controls) {
-            this.lookAtTarget.copy(this.controls.target);
-        }
-    };
-    scheduleNextFrame() {
-        if (!this.initialized || this.paused || this.animationFrameId !== null) {
-            return;
-        }
-        if (this.renderer?.setAnimationLoop) {
-            this.animationFrameId = 1;
-            this.renderer.setAnimationLoop(() => {
-                this.loop();
-            });
-        }
-        else {
-            this.animationFrameId = requestAnimationFrame(() => {
-                this.animationFrameId = null;
-                this.loop();
-            });
-        }
-    }
-    stopLoop() {
-        if (this.animationFrameId !== null) {
-            if (this.renderer?.setAnimationLoop) {
-                this.renderer.setAnimationLoop(null);
-            }
-            else {
-                cancelAnimationFrame(this.animationFrameId);
-            }
-            this.animationFrameId = null;
-        }
-        this.clock.stop();
-    }
-    /**
-     * Re-applies `setPixelRatio` from DPR and battery policy, then
-     * resizes the drawing buffer to match the canvas CSS size.
-     *
-     * **WHY:** `setPixelRatio` alone does not always refit the buffer after
-     * snapshot capture or when toggling low-power mode mid-session.
-     */
-    applyRendererPixelRatio() {
-        if (!this.renderer || !this.camera)
-            return;
-        const base = getRendererPixelRatio();
-        const ratio = this.lowPowerRenderMode ? Math.min(base, 1) : base;
-        this.renderer.setPixelRatio(ratio);
-        const canvas = this.renderer.domElement;
-        if (!canvas)
-            return;
-        const w = canvas.clientWidth;
-        const h = canvas.clientHeight;
-        if (w > 0 && h > 0) {
-            this.resize(w, h);
-        }
-    }
-    /** Disable expensive directional shadow maps on battery — big GPU savings. */
-    applyLowPowerShadowPolicy() {
-        const light = this.keyDirectionalLight;
-        if (!light)
-            return;
-        if (this.lowPowerRenderMode) {
-            light.castShadow = false;
-        }
-        else {
-            light.castShadow = true;
-            light.shadow.mapSize.setScalar(1024);
-        }
-        const r = this.renderer;
-        if (r?.shadowMap) {
-            r.shadowMap.needsUpdate = true;
-        }
-    }
-    resumeLoop() {
-        if (!this.initialized || this.paused)
-            return;
-        this.clock.start();
-        this.scheduleNextFrame();
-    }
-    applyCompanionZoom(camera, stableDelta) {
-        const isCompanionProfile = this.cameraProfile === "companion";
-        const follow = Math.min(1, stableDelta * 10);
-        const targetZoom = isCompanionProfile ? this.companionZoomTarget : 0;
-        this.companionZoomCurrent = THREE.MathUtils.lerp(this.companionZoomCurrent, targetZoom, follow);
-        if (this.companionZoomCurrent < 1e-4)
-            return;
-        const baseRadius = this.baseCameraPosition.distanceTo(this.lookAtTarget);
-        if (!Number.isFinite(baseRadius) || baseRadius < 1e-4)
-            return;
-        const orbitOffset = this.tempCameraOrbitOffset
-            .copy(camera.position)
-            .sub(this.lookAtTarget);
-        if (orbitOffset.lengthSq() < 1e-6)
-            return;
-        const spherical = this.tempCameraSpherical.setFromVector3(orbitOffset);
-        const nearRadius = Math.max(COMPANION_ZOOM_MIN_RADIUS, baseRadius * COMPANION_ZOOM_NEAR_FACTOR);
-        spherical.radius = THREE.MathUtils.lerp(baseRadius, nearRadius, this.companionZoomCurrent);
-        camera.position
-            .copy(this.lookAtTarget)
-            .add(orbitOffset.setFromSpherical(spherical));
-    }
-    configureAvatarLookTracking(vrm) {
-        const target = this.avatarLookTarget;
-        if (target) {
-            target.position.set(0, 1.5, 2);
-            target.updateMatrixWorld(true);
-        }
-        if (vrm.lookAt && target) {
-            vrm.lookAt.autoUpdate = true;
-            vrm.lookAt.target = target;
-        }
-        const headBone = vrm.humanoid?.getRawBoneNode("head") ?? null;
-        const neckBone = vrm.humanoid?.getRawBoneNode("neck") ?? null;
-        const spineBone = vrm.humanoid?.getRawBoneNode("upperChest") ??
-            vrm.humanoid?.getRawBoneNode("chest") ??
-            vrm.humanoid?.getRawBoneNode("spine") ??
-            null;
-        this.avatarLookRig = {
-            headBone,
-            neckBone,
-            spineBone,
-        };
-        this.headLookTarget.set(0, 0);
-        this.headLookCurrent.set(0, 0);
-    }
-    updateAvatarLookTarget(camera, stableDelta) {
-        const target = this.avatarLookTarget;
-        if (!target)
-            return;
-        this.tempAvatarLookTarget.copy(camera.position);
-        const follow = Math.min(1, stableDelta * 24);
-        target.position.lerp(this.tempAvatarLookTarget, follow);
-        target.updateMatrixWorld(true);
-    }
-    refreshAvatarEyeTracking() {
-        const vrm = this.vrm;
-        if (!vrm?.lookAt || !this.avatarLookTarget)
-            return;
-        vrm.lookAt.update(0);
-        vrm.expressionManager?.update();
-    }
-    applyAvatarHeadTracking(camera, stableDelta) {
-        const vrm = this.vrm;
-        const { headBone, neckBone, spineBone } = this.avatarLookRig;
-        if (!vrm || !headBone)
-            return;
-        const headParent = headBone.parent;
-        if (!headParent || typeof headParent.worldToLocal !== "function")
-            return;
-        if (typeof THREE.Euler !== "function" ||
-            typeof THREE.Quaternion !== "function" ||
-            typeof headBone.quaternion.clone !== "function") {
-            return;
-        }
-        const lookAtState = vrm.lookAt;
-        const lookAtYawDegrees = lookAtState?._yaw;
-        const lookAtPitchDegrees = lookAtState?._pitch;
-        if (Number.isFinite(lookAtYawDegrees) &&
-            Number.isFinite(lookAtPitchDegrees)) {
-            this.headLookTarget.set(THREE.MathUtils.clamp(THREE.MathUtils.degToRad(lookAtYawDegrees || 0), -0.55, 0.55), THREE.MathUtils.clamp(THREE.MathUtils.degToRad(lookAtPitchDegrees || 0), -0.3, 0.24));
-        }
-        else {
-            headBone.getWorldPosition(this.tempAvatarHeadWorld);
-            this.tempAvatarLocalTarget.copy(camera.position);
-            this.tempAvatarLocalTarget.y -= 0.04;
-            headParent.worldToLocal(this.tempAvatarLocalTarget);
-            headParent.worldToLocal(this.tempAvatarLocalAnchor.copy(this.tempAvatarHeadWorld));
-            this.tempAvatarLocalTarget.sub(this.tempAvatarLocalAnchor);
-            const planarDistance = Math.max(1e-4, Math.hypot(this.tempAvatarLocalTarget.x, this.tempAvatarLocalTarget.z));
-            this.headLookTarget.set(THREE.MathUtils.clamp(Math.atan2(-this.tempAvatarLocalTarget.x, Math.max(-this.tempAvatarLocalTarget.z, 1e-4)), -0.55, 0.55), THREE.MathUtils.clamp(Math.atan2(this.tempAvatarLocalTarget.y, planarDistance), -0.3, 0.24));
-        }
-        this.headLookCurrent.lerp(this.headLookTarget, Math.min(1, stableDelta * 4.5));
-        const applyTrackedBone = (bone, yawWeight, pitchWeight) => {
-            if (!bone?.quaternion || typeof bone.quaternion.clone !== "function") {
-                return;
-            }
-            const offsetEuler = new THREE.Euler(this.headLookCurrent.y * pitchWeight, this.headLookCurrent.x * yawWeight, 0, "YXZ");
-            const offsetQuaternion = new THREE.Quaternion().setFromEuler(offsetEuler);
-            const animatedPose = bone.quaternion.clone();
-            bone.quaternion.copy(animatedPose).multiply(offsetQuaternion);
-        };
-        applyTrackedBone(spineBone, 0.12, 0.06);
-        applyTrackedBone(neckBone, 0.3, 0.18);
-        applyTrackedBone(headBone, 0.52, 0.28);
-    }
-    toDebugVector3(vector) {
-        if (!vector)
-            return null;
-        return {
-            x: Number(vector.x.toFixed(4)),
-            y: Number(vector.y.toFixed(4)),
-            z: Number(vector.z.toFixed(4)),
-        };
-    }
-    toDebugBounds(object) {
-        if (!object)
-            return null;
-        const bounds = new THREE.Box3().setFromObject(object);
-        if (bounds.isEmpty())
-            return null;
-        return this.toDebugBoundsFromBox(bounds);
-    }
-    toDebugBoundsFromBox(bounds) {
-        if (!bounds || bounds.isEmpty())
-            return null;
-        const center = bounds.getCenter(new THREE.Vector3());
-        const size = bounds.getSize(new THREE.Vector3());
-        const min = this.toDebugVector3(bounds.min.clone());
-        const max = this.toDebugVector3(bounds.max.clone());
-        const centerVector = this.toDebugVector3(center);
-        const sizeVector = this.toDebugVector3(size);
-        if (!min || !max || !centerVector || !sizeVector)
-            return null;
-        return {
-            min,
-            max,
-            center: centerVector,
-            size: sizeVector,
-        };
-    }
-    getDebugInfo() {
-        this.scene?.updateMatrixWorld(true);
-        this.vrm?.scene.updateMatrixWorld(true);
-        const cameraRotation = this.camera
-            ? new THREE.Vector3(this.camera.rotation.x, this.camera.rotation.y, this.camera.rotation.z)
-            : null;
-        const lookAtTarget = this.toDebugVector3(this.lookAtTarget) ??
-            { x: 0, y: 0, z: 0 };
-        return {
-            initialized: this.initialized,
-            rendererBackend: this.rendererBackend,
-            cameraProfile: this.cameraProfile,
-            sceneChildren: this.scene?.children.map((child) => child.name || child.type) ?? [],
-            camera: {
-                parentName: this.camera?.parent?.name ?? null,
-                position: this.toDebugVector3(this.camera?.position ?? null),
-                rotation: this.toDebugVector3(cameraRotation),
-                fov: this.camera?.fov ?? null,
-                lookAtTarget,
-            },
-            avatar: {
-                loaded: this.vrm !== null,
-                ready: this.vrmReady,
-                parentName: this.vrm?.scene.parent?.name ?? null,
-                position: this.toDebugVector3(this.vrm?.scene.position ?? null),
-                scale: this.toDebugVector3(this.vrm?.scene.scale ?? null),
-                bounds: this.toDebugBounds(this.vrm?.scene ?? null),
-            },
-        };
-    }
-    setDebugAvatarVisible(visible) {
-        if (!this.vrm)
-            return;
-        this.vrm.scene.visible = visible;
-    }
-    setDebugCamera(position, target) {
-        if (!this.camera)
-            return;
-        this.isCameraTransitioning = false;
-        this.camera.position.copy(position);
-        this.baseCameraPosition.copy(position);
-        this.lookAtTarget.copy(target);
-        this.controls?.target.copy(target);
-        this.controls?.update();
-        this.camera.lookAt(target);
-    }
-    startCameraTransition(startPos, startLookAt, startFov, targetPos, targetLookAt, targetFov, durationSeconds) {
-        if (!this.camera)
-            return;
-        this.transitionStartFov = startFov;
-        this.transitionTargetFov = targetFov;
-        this.transitionStartPos.copy(startPos);
-        this.transitionTargetPos.copy(targetPos);
-        this.transitionStartLookAt.copy(startLookAt);
-        this.transitionTargetLookAt.copy(targetLookAt);
-        this.transitionDuration = Math.max(0.01, durationSeconds);
-        this.camera.fov = startFov;
-        this.camera.position.copy(startPos);
-        this.camera.updateProjectionMatrix();
-        this.baseCameraPosition.copy(startPos);
-        this.lookAtTarget.copy(startLookAt);
-        if (this.controls) {
-            this.controls.target.copy(startLookAt);
-            this.controls.update();
-        }
-        this.camera.lookAt(startLookAt);
-        this.isCameraTransitioning = true;
-        this.transitionProgress = 0;
-    }
-    transitionCameraToFramedAvatar(vrm, durationSeconds) {
-        if (!this.camera)
-            return;
-        const startPos = new THREE.Vector3().copy(this.baseCameraPosition);
-        const startLookAt = new THREE.Vector3().copy(this.lookAtTarget);
-        const startFov = this.camera.fov;
-        const targetLookAt = new THREE.Vector3();
-        const defaultProfileTargetPos = new THREE.Vector3();
-        const dummyCamera = this.camera.clone();
-        this.cameraManager.centerAndFrame(vrm, dummyCamera, this.controls, this.cameraProfile, targetLookAt, defaultProfileTargetPos, (c) => this.cameraManager.applyInteractionMode(c, this.interactionMode), true);
-        // To prevent frame-based dynamic offsets (yaw, sway, zoom) from accumulating and causing camera spin,
-        // compute the pristine tracking offset from baseCameraPosition, which is unaffected by post-process
-        // modifiers in applyCameraMotion. We do NOT use OrbitControls' getDistance/getAzimuthalAngle because
-        // OrbitControls reads from `camera.position` which has the temporary view shifts applied to it every frame.
-        const currentOffset = new THREE.Vector3();
-        currentOffset.copy(this.baseCameraPosition).sub(startLookAt);
-        const targetPos = new THREE.Vector3().copy(targetLookAt).add(currentOffset);
-        this.startCameraTransition(startPos, startLookAt, startFov, targetPos, targetLookAt, dummyCamera.fov, durationSeconds);
-    }
-    whenReady() {
-        return this.readyPromise;
-    }
-    resetReadyPromise() {
-        this.readyPromise = new Promise((resolve, reject) => {
-            this.resolveReady = resolve;
-            this.rejectReady = reject;
-        });
-    }
-    settleReady(error) {
-        if (error) {
-            this.rejectReady?.(error);
-        }
-        else {
-            this.resolveReady?.();
-        }
-        this.resolveReady = null;
-        this.rejectReady = null;
-    }
-    setup(canvas, onUpdate, options) {
-        if (this.initialized && this.renderer?.domElement === canvas) {
-            this.onUpdate = onUpdate;
-            return;
-        }
-        if (this.initialized)
-            this.dispose();
-        this.onUpdate = onUpdate;
-        this.loadingAborted = false;
-        this.rendererPreference = options?.rendererPreference ?? "auto";
-        this.resetReadyPromise();
-        // Async renderer creation: tries WebGPU, falls back to WebGL.
-        // setup() remains synchronous for callers; the loop starts after init resolves.
-        void (async () => {
-            try {
-                const { backend, renderer } = await createRenderer(canvas, this.rendererPreference);
-                const releaseKnownWebGpuWarningFilter = backend === "webgpu" ? installKnownVrmWebGpuWarningFilter() : null;
-                // Guard: if dispose() was called while we were awaiting, abort.
-                if (this.loadingAborted) {
-                    releaseKnownWebGpuWarningFilter?.();
-                    renderer.dispose();
-                    this.settleReady();
-                    return;
-                }
-                this.releaseKnownWebGpuWarningFilter = releaseKnownWebGpuWarningFilter;
-                this.renderer = renderer;
-                renderer.setClearColor(0x000000, 0);
-                if (backend === "webgl") {
-                    const webglRenderer = renderer;
-                    webglRenderer.shadowMap.enabled = true;
-                    webglRenderer.shadowMap.type = THREE.PCFSoftShadowMap;
-                    webglRenderer.toneMapping = THREE.NoToneMapping;
-                    webglRenderer.toneMappingExposure = 1.0;
-                    webglRenderer.outputColorSpace = THREE.SRGBColorSpace;
-                }
-                this.rendererBackend = backend;
-                const scene = new THREE.Scene();
-                this.scene = scene;
-                // Build construct environment (white void, floating screens, fog)
-                this.mathEnvironment = new MathEnvironment();
-                this.mathEnvironment.build(scene, "light");
-                const avatarRoot = new THREE.Group();
-                avatarRoot.name = "AvatarRoot";
-                scene.add(avatarRoot);
-                this.avatarRoot = avatarRoot;
-                const avatarLookTarget = new THREE.Group();
-                avatarLookTarget.name = "AvatarLookTarget";
-                scene.add(avatarLookTarget);
-                this.avatarLookTarget = avatarLookTarget;
-                const cameraRig = new THREE.Group();
-                cameraRig.name = "AvatarCameraRig";
-                scene.add(cameraRig);
-                const camera = new THREE.PerspectiveCamera(30, 1, 0.1, 20);
-                camera.position.set(0, 1.2, 5.0);
-                cameraRig.add(camera);
-                this.camera = camera;
-                const controls = new OrbitControls(camera, renderer.domElement);
-                controls.enableDamping = false;
-                controls.target.copy(this.lookAtTarget);
-                controls.addEventListener("start", this.handleControlStart);
-                controls.addEventListener("end", this.handleControlEnd);
-                this.cameraManager.applyInteractionMode(controls, this.interactionMode);
-                controls.update();
-                this.controls = controls;
-                this.setInteractionEnabled(this.interactionEnabled);
-                // Apply deferred camera profile (setCameraProfile may have been called
-                // before the camera existed) and initialize baseCameraPosition so that
-                // drag-orbit and companion-zoom have a valid reference point from the
-                // very first frame.
-                this.cameraManager.applyCameraProfileToCamera(camera, controls, this.cameraProfile);
-                this.baseCameraPosition.copy(camera.position);
-                this.lookAtTarget.copy(controls.target);
-                const ambient = new THREE.AmbientLight(0xffffff, 1.2);
-                scene.add(ambient);
-                const keyLight = new THREE.DirectionalLight(0xffffff, 1.0);
-                keyLight.position.set(1, 1.5, 1).normalize();
-                keyLight.castShadow = true;
-                keyLight.shadow.mapSize.setScalar(1024);
-                scene.add(keyLight);
-                this.keyDirectionalLight = keyLight;
-                const fillLight = new THREE.DirectionalLight(0xffffff, 0.6);
-                fillLight.position.set(-1, 0.5, -1).normalize();
-                scene.add(fillLight);
-                this.applyRendererPixelRatio();
-                if (this.lowPowerRenderMode) {
-                    this.applyLowPowerShadowPolicy();
-                }
-                // Auto-create the scene overlay manager for floating HUD panels.
-                if (!this.overlayManager && this.scene) {
-                    try {
-                        this.overlayManager = new SceneOverlayManager();
-                        this.overlayManager.attach(this.scene);
-                    }
-                    catch {
-                        // Overlay panels require a full 2D canvas context; gracefully
-                        // skip when running in headless / test environments.
-                    }
-                }
-                this.initialized = true;
-                this.resumeLoop();
-                this.settleReady();
-            }
-            catch (error) {
-                this.initialized = false;
-                this.releaseKnownWebGpuWarningFilter?.();
-                this.releaseKnownWebGpuWarningFilter = null;
-                this.renderer = null;
-                this.rendererBackend = "webgl";
-                this.scene = null;
-                this.camera = null;
-                this.controls = null;
-                this.keyDirectionalLight = null;
-                console.error("[VrmEngine] Failed to initialize renderer:", error);
-                this.settleReady(error);
-            }
-        })();
-    }
-    isInitialized() {
-        return this.initialized && this.renderer !== null;
-    }
-    dispose() {
-        this.mathEnvironment?.dispose();
-        this.mathEnvironment = null;
-        this.overlayManager?.dispose();
-        this.overlayManager = null;
-        this.loadingAborted = true;
-        this.initialized = false;
-        this.settleReady();
-        this.releaseKnownWebGpuWarningFilter?.();
-        this.releaseKnownWebGpuWarningFilter = null;
-        if (this.animationFrameId !== null) {
-            cancelAnimationFrame(this.animationFrameId);
-            this.animationFrameId = null;
-        }
-        if (this.vrm?.scene.parent) {
-            this.vrm.scene.parent.remove(this.vrm.scene);
-            VRMUtils.deepDispose(this.vrm.scene);
-        }
-        if (this.controls) {
-            this.controls.removeEventListener("start", this.handleControlStart);
-            this.controls.removeEventListener("end", this.handleControlEnd);
-            this.controls.dispose();
-            this.controls = null;
-        }
-        this.vrm = null;
-        this.vrmReady = false;
-        this.vrmName = null;
-        this.lastLoadError = null;
-        this.mixer = null;
-        this.idleAction = null;
-        this.idleLoadPromise = null;
-        this.clearPendingEmoteCompletion();
-        this.emoteAction = null;
-        this.emoteClipCache.clear();
-        this.teleportProgress = 1.0;
-        this.cleanupTeleportDissolve();
-        this.cleanupTeleportSparkles();
-        this.avatarLookTarget?.parent?.remove(this.avatarLookTarget);
-        this.avatarLookTarget = null;
-        this.avatarLookRig = {
-            headBone: null,
-            neckBone: null,
-            spineBone: null,
-        };
-        this.headLookTarget.set(0, 0);
-        this.headLookCurrent.set(0, 0);
-        if (this.renderer) {
-            this.renderer.dispose();
-        }
-        this.renderer = null;
-        this.rendererBackend = "webgl";
-        this.keyDirectionalLight = null;
-        this.scene = null;
-        this.avatarRoot = null;
-        this.camera = null;
-        this.onUpdate = null;
-        this.paused = false;
-    }
-    setPaused(paused) {
-        if (this.paused === paused)
-            return;
-        this.paused = paused;
-        if (paused) {
-            this.stopLoop();
-            return;
-        }
-        this.resumeLoop();
-    }
-    /**
-     * Keeps the animation/render loop alive so the avatar keeps idling while
-     * background is hidden. Restores prior state when disabled.
-     */
-    setMinimalBackgroundMode(enabled) {
-        if (this.minimalBackgroundMode === enabled)
-            return;
-        this.minimalBackgroundMode = enabled;
-    }
-    /**
-     * When true, caps the WebGL/WebGPU pixel ratio at **1** on top of the usual
-     * DPR clamp and applies cheaper shadows — primarily for
-     * **battery** on Retina. Does **not** change frame cadence; use
-     * {@link setHalfFramerateMode} for ~half refresh rate.
-     *
-     * **WHY:** shader cost scales with physical pixels; `desktopGetPowerState`
-     * → `onBattery` toggles this from the Electrobun shell without a full reload.
-     */
-    setLowPowerRenderMode(enabled) {
-        if (this.lowPowerRenderMode === enabled)
-            return;
-        this.lowPowerRenderMode = enabled;
-        this.applyRendererPixelRatio();
-        this.applyLowPowerShadowPolicy();
-    }
-    /**
-     * When true, the main loop skips every other tick so `renderer.render` runs at
-     * roughly half the display refresh rate; skipped ticks do not call
-     * `clock.getDelta()`, so the next tick’s delta spans two intervals.
-     */
-    setHalfFramerateMode(enabled) {
-        if (this.halfFramerateMode === enabled)
-            return;
-        this.halfFramerateMode = enabled;
-        this.halfFramerateSkipNext = false;
-    }
-    setInteractionEnabled(enabled) {
-        this.interactionEnabled = enabled;
-        if (this.controls) {
-            this.controls.enabled = enabled;
-        }
-    }
-    setInteractionMode(mode) {
-        this.interactionMode = mode;
-        if (this.controls) {
-            this.cameraManager.applyInteractionMode(this.controls, mode);
-            this.controls.update();
-        }
-    }
-    setCameraProfile(profile) {
-        if (this.cameraProfile === profile)
-            return;
-        if (this.camera) {
-            const startFov = this.camera.fov;
-            const startPos = new THREE.Vector3().copy(this.camera.position);
-            const startLookAt = new THREE.Vector3().copy(this.lookAtTarget);
-            this.cameraProfile = profile;
-            const targetLookAt = new THREE.Vector3().copy(this.lookAtTarget);
-            const targetPos = new THREE.Vector3().copy(this.camera.position);
-            let targetFov = this.camera.fov;
-            if (this.vrm) {
-                const dummyCamera = this.camera.clone();
-                this.cameraManager.centerAndFrame(this.vrm, dummyCamera, this.controls, this.cameraProfile, targetLookAt, targetPos, (c) => this.cameraManager.applyInteractionMode(c, this.interactionMode), true);
-                targetFov = dummyCamera.fov;
-            }
-            else {
-                const dummyCamera = this.camera.clone();
-                this.cameraManager.applyCameraProfileToCamera(dummyCamera, this.controls, this.cameraProfile);
-                targetPos.copy(dummyCamera.position);
-                targetFov = dummyCamera.fov;
-                // controls.target handles lookAt internally or we just leap
-                if (this.controls) {
-                    // Skipping instant snap of controls.target, we let transition handle it
-                    targetLookAt.copy(this.controls.target);
-                }
-            }
-            this.startCameraTransition(startPos, startLookAt, startFov, targetPos, targetLookAt, targetFov, CAMERA_PROFILE_TRANSITION_DURATION_SECONDS);
-        }
-        else {
-            this.cameraProfile = profile;
-        }
-    }
-    resize(width, height) {
-        if (!this.renderer || !this.camera)
-            return;
-        if (width <= 0 || height <= 0)
-            return;
-        const aspect = width / height;
-        if (!Number.isFinite(aspect) || aspect <= 0)
-            return;
-        this.renderer.setSize(width, height, false);
-        this.camera.aspect = aspect;
-        this.camera.updateProjectionMatrix();
-    }
-    getState() {
-        const idlePlaying = this.idleAction?.isRunning() ?? false;
-        return {
-            vrmLoaded: this.vrm !== null && this.vrmReady,
-            vrmName: this.vrmName,
-            loadError: this.lastLoadError,
-            idlePlaying,
-            idleTime: this.idleAction?.time ?? 0,
-            idleTracks: this.idleAction?.getClip()?.tracks.length ?? 0,
-            revealStarted: this.revealStarted,
-            loadingProgress: this.loadingProgress,
-        };
-    }
-    setMouthOpen(value) {
-        this.mouthValue = Math.max(0, Math.min(1, value));
-    }
-    setSpeaking(speaking) {
-        if (speaking && !this.speaking) {
-            this.speakingStartTime = this.elapsedTime;
-        }
-        this.speaking = speaking;
-    }
-    attachOverlayManager(manager) {
-        this.overlayManager = manager;
-        if (this.scene)
-            manager.attach(this.scene);
-    }
-    getOverlayManager() {
-        return this.overlayManager;
-    }
-    setCameraAnimation(config) {
-        this.cameraAnimation = { ...this.cameraAnimation, ...config };
-    }
-    setPointerParallaxEnabled(enabled) {
-        this.pointerParallaxEnabled = enabled;
-        if (!enabled) {
-            this.pointerParallaxTarget.set(0, 0);
-        }
-    }
-    setPointerParallaxTarget(x, y) {
-        this.pointerParallaxTarget.set(THREE.MathUtils.clamp(x, -1, 1), THREE.MathUtils.clamp(y, -1, 1));
-    }
-    resetPointerParallax() {
-        this.pointerParallaxTarget.set(0, 0);
-    }
-    setDragOrbitTarget(yaw, pitch) {
-        this.dragOrbitTarget.set(THREE.MathUtils.clamp(yaw, -0.6, 0.6), THREE.MathUtils.clamp(pitch, -0.35, 0.35));
-    }
-    resetDragOrbit() {
-        this.dragOrbitTarget.set(0, 0);
-    }
-    setCompanionZoomNormalized(value) {
-        this.companionZoomTarget = THREE.MathUtils.clamp(value, 0, 1);
-    }
-    setCameraXOffset(offset) {
-        this.cameraXOffsetTarget = THREE.MathUtils.clamp(offset, -3, 3);
-        // Map the X offset to an orbital yaw offset (radians).
-        // Positive X offset → negative theta (orbit camera to the right so
-        // character appears on the left).
-        this.cameraYawOffsetTarget = -offset * 0.7;
-    }
-    async setWorldUrl(_url) {
-        // World backgrounds removed — math environment managed separately.
-    }
-    /** Switch the mathematical environment theme. */
-    setEnvironmentTheme(theme) {
-        this.mathEnvironment?.setTheme(theme);
-    }
-    async playEmote(path, duration, loop) {
-        const vrm = this.vrm;
-        const mixer = this.mixer;
-        if (!vrm || !mixer)
-            return;
-        // Don't start emotes while the teleport dissolve is still running or
-        // within a short cooldown afterwards — the idle animation needs time
-        // to settle into a stable pose before we can cross-fade from it.
-        const POST_TELEPORT_COOLDOWN = 0.3; // seconds
-        if (this.teleportProgress < 1.0 ||
-            this.elapsedTime - this.teleportCompleteTime < POST_TELEPORT_COOLDOWN) {
-            return;
-        }
-        this.clearPendingEmoteCompletion();
-        this.emoteRequestId++;
-        const requestId = this.emoteRequestId;
-        const currentEmote = this.emoteAction;
-        const clip = await this.loadEmoteClipCached(path, vrm);
-        if (!clip || this.vrm !== vrm || this.mixer !== mixer)
-            return;
-        if (this.emoteRequestId !== requestId)
-            return;
-        const action = mixer.clipAction(clip);
-        action.setLoop(loop ? THREE.LoopRepeat : THREE.LoopOnce, loop ? Infinity : 1);
-        action.clampWhenFinished = !loop;
-        const fadeDuration = 0.4;
-        // Use explicit fadeOut + fadeIn instead of crossFadeFrom. crossFadeFrom
-        // only blends tracks that exist in BOTH clips — emotes exported with
-        // non-uniform keyframes (sparse Mixamo optimization) leave body/leg
-        // bones without tracks, so idle's tracks for those bones continue at
-        // full weight, creating visible overlap. Fading out the source
-        // explicitly ensures ALL its tracks fade away cleanly.
-        if (currentEmote && currentEmote !== action) {
-            currentEmote.fadeOut(fadeDuration);
-        }
-        if (this.idleAction && this.idleAction !== action) {
-            this.idleAction.fadeOut(fadeDuration);
-        }
-        action.reset();
-        this.activateAction(action);
-        action.fadeIn(fadeDuration);
-        this.emoteAction = action;
-        if (!loop) {
-            const clipDuration = Number.isFinite(duration) && duration > 0 ? duration : clip.duration;
-            this.watchOneShotEmoteCompletion(mixer, action, requestId, clipDuration);
-        }
-    }
-    stopEmote() {
-        this.clearPendingEmoteCompletion();
-        const fadeDuration = 0.4;
-        const activeEmote = this.emoteAction;
-        this.emoteAction = null;
-        if (this.idleAction) {
-            this.activateAction(this.idleAction);
-            if (activeEmote && activeEmote !== this.idleAction) {
-                this.idleAction.crossFadeFrom(activeEmote, fadeDuration, false);
-            }
-            else {
-                this.idleAction.fadeIn(fadeDuration);
-            }
-            return;
-        }
-        if (this.vrm && this.mixer) {
-            this.restoreIdleAfterEmote(activeEmote, fadeDuration, this.vrm, this.mixer);
-            return;
-        }
-        activeEmote?.fadeOut(fadeDuration);
-    }
-    /** Play a one-shot wave greeting after the VRM becomes visible. */
-    playWaveGreeting() {
-        this.playEmote(resolveAppAssetUrl("animations/emotes/greeting.fbx"), 3, false);
-    }
-    async loadVrmFromUrl(url, name) {
-        await this.whenReady();
-        if (!this.scene)
-            throw new Error("VrmEngine not initialized");
-        if (!this.camera)
-            throw new Error("VrmEngine not initialized");
-        if (this.loadingAborted)
-            return;
-        const requestId = ++this.vrmLoadRequestId;
-        const hadPreviousVrm = this.vrm !== null;
-        if (this.vrm) {
-            if (this.outgoingVrm) {
-                this.outgoingVrm.scene.parent?.remove(this.outgoingVrm.scene);
-                VRMUtils.deepDispose(this.outgoingVrm.scene);
-            }
-            this.outgoingVrm = this.vrm;
-            this.outgoingMixer = this.mixer;
-            this.vrm = null;
-            this.vrmReady = false;
-            this.vrmName = null;
-            this.mixer = null;
-            this.idleAction = null;
-            this.idleLoadPromise = null;
-            this.revealStarted = false;
-            this.clearPendingEmoteCompletion();
-            this.emoteAction = null;
-            this.emoteClipCache.clear();
-        }
-        this.lastLoadError = null;
-        this.loadingProgress = 0;
-        this.onUpdate?.();
-        const loader = new GLTFLoader();
-        configureVrmGltfLoader(loader);
-        const webGpuNodes = this.rendererBackend === "webgpu"
-            ? await import("@pixiv/three-vrm/nodes")
-            : null;
-        loader.register((parser) => {
-            if (webGpuNodes) {
-                const mtoonMaterialPlugin = new MToonMaterialLoaderPlugin(parser, {
-                    materialType: webGpuNodes.MToonNodeMaterial,
-                });
-                return new VRMLoaderPlugin(parser, { mtoonMaterialPlugin });
-            }
-            return new VRMLoaderPlugin(parser);
-        });
-        let gltf;
-        try {
-            gltf = await loadGltfAsset(loader, url, (progress) => {
-                if (this.vrmLoadRequestId === requestId && !this.loadingAborted) {
-                    this.loadingProgress = progress;
-                    this.onUpdate?.();
-                }
-            });
-        }
-        catch (error) {
-            if (!this.loadingAborted && requestId === this.vrmLoadRequestId) {
-                this.lastLoadError =
-                    error instanceof Error ? error.message : String(error);
-                this.onUpdate?.();
-            }
-            throw error;
-        }
-        if (this.loadingAborted ||
-            !this.scene ||
-            requestId !== this.vrmLoadRequestId) {
-            const staleVrm = gltf.userData.vrm;
-            if (staleVrm)
-                VRMUtils.deepDispose(staleVrm.scene);
-            return;
-        }
-        const vrm = gltf.userData.vrm;
-        if (!vrm)
-            throw new Error("Loaded asset is not a VRM");
-        VRMUtils.removeUnnecessaryVertices(vrm.scene);
-        if (this.camera) {
-            if (!hadPreviousVrm) {
-                this.cameraManager.centerAndFrame(vrm, this.camera, this.controls, this.cameraProfile, this.lookAtTarget, this.baseCameraPosition, (c) => this.cameraManager.applyInteractionMode(c, this.interactionMode));
-            }
-        }
-        try {
-            VRMUtils.rotateVRM0(vrm);
-        }
-        catch {
-            /* optional in some versions */
-        }
-        this.cameraManager.ensureFacingCamera(vrm, this.camera);
-        this.configureAvatarLookTracking(vrm);
-        if (this.loadingAborted ||
-            !this.scene ||
-            requestId !== this.vrmLoadRequestId) {
-            VRMUtils.deepDispose(vrm.scene);
-            return;
-        }
-        vrm.scene.visible = false;
-        vrm.scene.traverse((obj) => {
-            obj.frustumCulled = false;
-        });
-        const avatarParent = this.avatarRoot ?? this.scene;
-        avatarParent.add(vrm.scene);
-        this.vrm = vrm;
-        this.vrmName = name ?? null;
-        this.lastLoadError = null;
-        vrm.springBoneManager?.reset?.();
-        this.blinkController.reset();
-        try {
-            await this.loadAndPlayIdle(vrm);
-            if (!this.loadingAborted && this.vrm === vrm) {
-                this.vrmReady = true;
-                // Let the idle animation settle into a natural pose before revealing
-                await new Promise((resolve) => setTimeout(resolve, 300));
-                if (this.loadingAborted || this.vrm !== vrm)
-                    return;
-                await this.playTeleportReveal(vrm);
-                vrm.scene.visible = true;
-                // Greeting animation is handled by CharacterEditor via vrm-teleport-complete event
-            }
-        }
-        catch {
-            if (!this.loadingAborted && this.vrm === vrm) {
-                this.vrmReady = true;
-                vrm.scene.visible = true;
-                // Teleport animation failed (e.g. WebGPU unavailable) — still notify
-                // the app so companion UI (header, chat) becomes visible.
-                if (typeof window !== "undefined") {
-                    window.dispatchEvent(new CustomEvent("eliza:vrm-teleport-complete"));
-                }
-            }
-        }
-    }
-    async playTeleportReveal(vrm) {
-        if (this.outgoingVrm && this.camera) {
-            this.transitionCameraToFramedAvatar(vrm, AVATAR_SWITCH_CAMERA_TRANSITION_DURATION_SECONDS);
-        }
-        this.teleportProgress = 0.0;
-        this.cleanupTeleportDissolve();
-        let appliedNodeDissolve = false;
-        try {
-            const tsl = await import("three/tsl");
-            const uProgress = tsl.uniform(0.0);
-            this.teleportProgressUniform = uProgress;
-            const applyTslDissolve = (targetVrm, isOutgoing) => {
-                targetVrm.scene.traverse((obj) => {
-                    if (!(obj instanceof THREE.Mesh))
-                        return;
-                    const mats = Array.isArray(obj.material)
-                        ? obj.material
-                        : [obj.material];
-                    for (const mat of mats) {
-                        if (!mat.isNodeMaterial || mat.userData._dissolveApplied)
-                            continue;
-                        appliedNodeDissolve = true;
-                        mat.userData._dissolveApplied = true;
-                        mat.userData._origOpacityNode = mat.opacityNode ?? null;
-                        mat.userData._origEmissiveNode =
-                            mat.emissiveNode ?? null;
-                        mat.userData._origAlphaTest = mat.alphaTest;
-                        const worldY = tsl.positionWorld.y;
-                        const threshold = uProgress
-                            .mul(TELEPORT_DISSOLVE_END_Y - TELEPORT_DISSOLVE_START_Y)
-                            .add(TELEPORT_DISSOLVE_START_Y);
-                        const diff = worldY.sub(threshold);
-                        const nx = tsl.sin(tsl.positionWorld.x.mul(18.0).add(worldY.mul(12.0)));
-                        const ny = tsl.cos(worldY.mul(15.0).add(tsl.positionWorld.z.mul(10.0)));
-                        const nz = tsl.sin(tsl.positionWorld.z.mul(18.0).add(tsl.positionWorld.x.mul(10.0)));
-                        const noise = nx.add(ny).add(nz).div(3.0).add(1.0).mul(0.5);
-                        const ratio = diff.div(0.3).clamp(0.0, 1.0);
-                        const baseAlpha = tsl.step(ratio, noise);
-                        const dissolveAlpha = isOutgoing
-                            ? tsl.float(1.0).sub(baseAlpha)
-                            : baseAlpha;
-                        const edgeDist = diff.abs();
-                        const glowWidth = tsl.float(0.08);
-                        const glowIntensity = tsl
-                            .float(1.0)
-                            .sub(edgeDist.div(glowWidth).clamp(0.0, 1.0));
-                        const hueShift = tsl.fract(worldY.mul(3.0).add(uProgress.mul(2.0)));
-                        const holoR = tsl
-                            .smoothstep(tsl.float(0.3), tsl.float(0.7), hueShift)
-                            .mul(0.8)
-                            .add(0.2);
-                        const holoG = tsl.float(0.9);
-                        const holoB = tsl
-                            .smoothstep(tsl.float(0.7), tsl.float(0.3), hueShift)
-                            .mul(0.8)
-                            .add(0.2);
-                        const holoColor = tsl.vec3(holoR, holoG, holoB);
-                        const glowActive = tsl
-                            .step(tsl.float(0.001), uProgress)
-                            .mul(tsl.float(1.0).sub(tsl.step(tsl.float(0.999), uProgress)));
-                        const emissiveBoost = holoColor.mul(glowIntensity.mul(10.0).mul(glowActive).mul(dissolveAlpha));
-                        const origOpacity = mat.opacityNode;
-                        mat.opacityNode = origOpacity
-                            ? (origOpacity.mul(dissolveAlpha) ?? dissolveAlpha)
-                            : dissolveAlpha;
-                        const matWithEmissive = mat;
-                        const origEmissive = matWithEmissive.emissiveNode;
-                        matWithEmissive.emissiveNode = origEmissive
-                            ? origEmissive.add(emissiveBoost)
-                            : emissiveBoost;
-                        mat.alphaTest = 0.01;
-                        mat.needsUpdate = true;
-                        this.teleportDissolvedMaterials.push(mat);
-                    }
-                });
-            };
-            applyTslDissolve(vrm, false);
-            if (this.outgoingVrm) {
-                applyTslDissolve(this.outgoingVrm, true);
-            }
-        }
-        catch (err) {
-            console.warn("[VrmEngine] TSL dissolve unavailable, showing instantly:", err);
-        }
-        if (!appliedNodeDissolve) {
-            this.applyTeleportFallbackDissolve(vrm, false);
-            if (this.outgoingVrm) {
-                this.applyTeleportFallbackDissolve(this.outgoingVrm, true);
-            }
-        }
-        // Force shader compilation by rendering invisible frames before displaying particles
-        await new Promise((resolve) => setTimeout(resolve, 0));
-        if (typeof window !== "undefined") {
-            await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
-        }
-        if (this.loadingAborted || this.vrm !== vrm)
-            return;
-        this.revealStarted = true;
-        this.startTeleportSparkles(vrm);
-    }
-    applyTeleportFallbackDissolve(vrm, isOutgoing) {
-        vrm.scene.traverse((obj) => {
-            if (!(obj instanceof THREE.Mesh))
-                return;
-            const mats = Array.isArray(obj.material) ? obj.material : [obj.material];
-            for (const mat of mats) {
-                if (mat.userData._dissolveApplied)
-                    continue;
-                mat.userData._dissolveApplied = true;
-                mat.userData._origAlphaTest = mat.alphaTest;
-                mat.userData._origOnBeforeCompile = mat.onBeforeCompile;
-                mat.userData._origCustomProgramCacheKey = mat.customProgramCacheKey;
-                const shaderRef = {
-                    uniforms: { uTeleportProgress: { value: this.teleportProgress } },
-                    isOutgoing,
-                };
-                this.teleportFallbackShaders.push(shaderRef);
-                mat.alphaTest = Math.max(mat.alphaTest ?? 0, 0.01);
-                mat.onBeforeCompile = (shader) => {
-                    shader.uniforms.uTeleportProgress =
-                        shaderRef.uniforms.uTeleportProgress;
-                    shader.vertexShader = `
-varying vec3 vTeleportWorldPosition;
-${shader.vertexShader}
-`.replace("#include <project_vertex>", `vec4 teleportWorldPosTemp = vec4( transformed, 1.0 );
-#ifdef USE_INSTANCING
-teleportWorldPosTemp = instanceMatrix * teleportWorldPosTemp;
-#endif
-teleportWorldPosTemp = modelMatrix * teleportWorldPosTemp;
-vTeleportWorldPosition = teleportWorldPosTemp.xyz;
-#include <project_vertex>`);
-                    shader.fragmentShader = `
-uniform float uTeleportProgress;
-varying vec3 vTeleportWorldPosition;
-float teleportSmoothNoise(vec3 p) {
-  float nx = sin(p.x * 18.0 + p.y * 12.0);
-  float ny = cos(p.y * 15.0 + p.z * 10.0);
-  float nz = sin(p.z * 18.0 + p.x * 10.0);
-  return (nx + ny + nz) / 3.0 * 0.5 + 0.5;
-}
-${shader.fragmentShader}
-`
-                        .replace("#include <alphatest_fragment>", `float teleportThreshold = mix(${TELEPORT_DISSOLVE_START_Y.toFixed(1)}, ${TELEPORT_DISSOLVE_END_Y.toFixed(1)}, uTeleportProgress);
-float teleportDiff = vTeleportWorldPosition.y - teleportThreshold;
-float teleportRatio = clamp(teleportDiff / 0.3, 0.0, 1.0);
-float teleportNoise = teleportSmoothNoise(vTeleportWorldPosition);
-${isOutgoing ? "if (teleportNoise >= teleportRatio) discard;" : "if (teleportNoise < teleportRatio) discard;"}
-#include <alphatest_fragment>`)
-                        .replace("#include <emissivemap_fragment>", `#include <emissivemap_fragment>
-            float teleportGlowDist = abs(teleportDiff);
-            float teleportGlowIntensity = 1.0 - clamp(teleportGlowDist / 0.08, 0.0, 1.0);
-            vec3 teleportHoloColor = vec3(0.3, 0.9, 0.8);
-            float teleportGlowActive = step(0.001, uTeleportProgress) * (1.0 - step(0.999, uTeleportProgress));
-            float teleportDissolveAlpha = ${isOutgoing ? "1.0 - step(teleportRatio, teleportNoise)" : "step(teleportRatio, teleportNoise)"};
-            totalEmissiveRadiance += teleportHoloColor * (teleportGlowIntensity * 10.0 * teleportGlowActive * teleportDissolveAlpha);`);
-                    const originalOnBeforeCompile = mat.userData._origOnBeforeCompile;
-                    if (typeof originalOnBeforeCompile === "function") {
-                        originalOnBeforeCompile(shader, this.renderer);
-                    }
-                };
-                const origCacheKey = mat.userData._origCustomProgramCacheKey;
-                mat.customProgramCacheKey = () => {
-                    const baseKey = typeof origCacheKey === "function" ? origCacheKey.call(mat) : "";
-                    return `${baseKey}:${mat.type}:teleport-dissolve-fallback:${isOutgoing ? "out" : "in"}`;
-                };
-                mat.needsUpdate = true;
-                this.teleportDissolvedMaterials.push(mat);
-            }
-        });
-    }
-    startTeleportSparkles(vrm) {
-        const parent = this.avatarRoot ?? this.scene;
-        if (!parent)
-            return;
-        this.cleanupTeleportSparkles();
-        const bounds = new THREE.Box3().setFromObject(vrm.scene);
-        const center = bounds.getCenter(new THREE.Vector3());
-        const size = bounds.getSize(new THREE.Vector3());
-        const sparkleGroup = new THREE.Group();
-        sparkleGroup.position.set(center.x, bounds.min.y + 0.06, center.z);
-        parent.add(sparkleGroup);
-        const texture = getTeleportSparkleTexture();
-        const particleHeight = THREE.MathUtils.clamp(size.y * 0.82, 0.95, 1.75);
-        const particles = [];
-        // Central high-energy flash
-        const flashMaterial = new THREE.SpriteMaterial({
-            map: texture,
-            color: new THREE.Color().setHSL(0.55, 0.95, 0.65),
-            transparent: true,
-            opacity: 0,
-            depthWrite: false,
-            depthTest: false,
-            blending: THREE.AdditiveBlending,
-        });
-        const flashSprite = new THREE.Sprite(flashMaterial);
-        flashSprite.visible = false;
-        flashSprite.renderOrder = 9999;
-        sparkleGroup.add(flashSprite);
-        particles.push({
-            sprite: flashSprite,
-            material: flashMaterial,
-            baseAngle: 0,
-            baseRadius: 0,
-            height: size.y * 0.5,
-            start: 0,
-            duration: 0.3,
-            spin: 0,
-            wobble: 0,
-            wobbleSpeed: 0,
-            baseSize: 1.8, // Massive size marks it as the central flash
-        });
-        // Vertical streaks
-        for (let index = 0; index < 60; index += 1) {
-            const hue = 0.52 + Math.random() * 0.08;
-            const material = new THREE.SpriteMaterial({
-                map: texture,
-                color: new THREE.Color().setHSL(hue, 0.95, 0.8),
-                transparent: true,
-                opacity: 0,
-                depthWrite: false,
-                depthTest: false,
-                blending: THREE.AdditiveBlending,
-            });
-            const sprite = new THREE.Sprite(material);
-            sprite.visible = false;
-            sprite.renderOrder = 9999;
-            sparkleGroup.add(sprite);
-            particles.push({
-                sprite,
-                material,
-                baseAngle: Math.random() * Math.PI * 2,
-                baseRadius: Math.random() * 0.4 + 0.05,
-                height: particleHeight * (1.1 + Math.random() * 0.5),
-                start: Math.random() * 0.3, // Fast start
-                duration: 0.2 + Math.random() * 0.25, // Snappy duration
-                spin: (Math.random() - 0.5) * 0.5,
-                wobble: 0,
-                wobbleSpeed: 0,
-                baseSize: 0.02 + Math.random() * 0.05, // Thin width
-            });
-        }
-        this.teleportSparkles = {
-            group: sparkleGroup,
-            particles,
-        };
-        this.updateTeleportSparkles();
-    }
-    updateTeleportSparkles() {
-        const system = this.teleportSparkles;
-        if (!system)
-            return;
-        const progress = THREE.MathUtils.clamp(this.teleportProgress, 0, 1);
-        let anyVisible = false;
-        for (const particle of system.particles) {
-            const localProgress = THREE.MathUtils.clamp((progress - particle.start) / particle.duration, 0, 1);
-            if (localProgress <= 0 || localProgress >= 1) {
-                particle.material.opacity = 0;
-                particle.sprite.visible = false;
-                continue;
-            }
-            anyVisible = true;
-            const opacity = Math.sin(localProgress * Math.PI) * 1.5;
-            if (particle.baseSize > 1.0) {
-                // Central flash
-                const scale = particle.baseSize * (1.0 + localProgress * 2.0);
-                particle.sprite.position.set(0, particle.height, 0);
-                particle.sprite.scale.setScalar(scale);
-                particle.sprite.visible = opacity > 0.01;
-                particle.material.opacity = Math.min(opacity, 1.0) * 0.45;
-            }
-            else {
-                // Vertical streaks
-                const rise = localProgress ** 1.5;
-                const angle = particle.baseAngle + progress * particle.spin;
-                const radial = particle.baseRadius * (1.0 + rise * 0.6);
-                const x = Math.cos(angle) * radial;
-                const z = Math.sin(angle) * radial;
-                const y = particle.height * rise;
-                const width = particle.baseSize * 0.6;
-                const height = particle.baseSize * (8.0 + localProgress * 6.0);
-                particle.sprite.position.set(x, y, z);
-                particle.sprite.scale.set(width, height, 1);
-                particle.sprite.visible = opacity > 0.01;
-                particle.material.opacity = Math.min(opacity, 1.0);
-            }
-        }
-        if (!anyVisible && progress >= 1) {
-            this.cleanupTeleportSparkles();
-        }
-    }
-    cleanupTeleportDissolve() {
-        for (const mat of this.teleportDissolvedMaterials) {
-            if (mat.userData._dissolveApplied) {
-                if (mat.userData._origOpacityNode !== undefined) {
-                    mat.opacityNode =
-                        mat.userData._origOpacityNode ?? null;
-                }
-                if (mat.userData._origEmissiveNode !== undefined) {
-                    mat.emissiveNode =
-                        mat.userData._origEmissiveNode ?? null;
-                }
-                mat.alphaTest = mat.userData._origAlphaTest ?? 0;
-                mat.onBeforeCompile =
-                    mat.userData._origOnBeforeCompile ?? mat.onBeforeCompile;
-                mat.customProgramCacheKey =
-                    mat.userData._origCustomProgramCacheKey ?? mat.customProgramCacheKey;
-                delete mat.userData._dissolveApplied;
-                delete mat.userData._origOpacityNode;
-                delete mat.userData._origEmissiveNode;
-                delete mat.userData._origAlphaTest;
-                delete mat.userData._origOnBeforeCompile;
-                delete mat.userData._origCustomProgramCacheKey;
-                mat.needsUpdate = true;
-            }
-        }
-        this.teleportDissolvedMaterials = [];
-        this.teleportProgressUniform = null;
-        this.teleportFallbackShaders = [];
-    }
-    cleanupTeleportSparkles() {
-        if (!this.teleportSparkles)
-            return;
-        for (const particle of this.teleportSparkles.particles) {
-            particle.sprite.parent?.remove(particle.sprite);
-            particle.material.dispose();
-        }
-        this.teleportSparkles.group.parent?.remove(this.teleportSparkles.group);
-        this.teleportSparkles = null;
-    }
-    get animationLoaderContext() {
-        return {
-            isAborted: () => this.loadingAborted,
-            isCurrentVrm: (vrm) => this.vrm === vrm,
-        };
-    }
-    loop() {
-        if (this.paused)
-            return;
-        this.scheduleNextFrame();
-        const renderer = this.renderer;
-        const scene = this.scene;
-        const camera = this.camera;
-        if (!renderer || !scene || !camera)
-            return;
-        if (this.halfFramerateMode) {
-            if (this.halfFramerateSkipNext) {
-                this.halfFramerateSkipNext = false;
-                return;
-            }
-            this.halfFramerateSkipNext = true;
-        }
-        else {
-            this.halfFramerateSkipNext = false;
-        }
-        // Reset camera to the pristine tracking base before processing this frame's
-        // motion and offsets. This ensures OrbitControls and transitions never see
-        // the temporary frame-based dynamic offsets (zoom, yaw, parallax),
-        // which prevents them from being doubled or accumulated into the state.
-        if (this.baseCameraPosition.lengthSq() > 1e-6) {
-            camera.position.copy(this.baseCameraPosition);
-        }
-        const rawDelta = this.clock.getDelta();
-        const stableDelta = Math.min(rawDelta, 1 / 30);
-        this.elapsedTime += rawDelta;
-        this.mixer?.update(rawDelta);
-        this.outgoingMixer?.update(rawDelta);
-        if (this.outgoingVrm) {
-            this.applyMouthToVrm(this.outgoingVrm);
-            this.outgoingVrm.update(stableDelta);
-        }
-        if (this.vrm) {
-            if (this.teleportProgress < 1.0) {
-                this.teleportProgress += stableDelta * 2.8; // ~0.35 seconds duration
-                if (this.teleportProgress > 1.0)
-                    this.teleportProgress = 1.0;
-                if (this.teleportProgressUniform) {
-                    this.teleportProgressUniform.value = this.teleportProgress;
-                }
-                for (const shader of this.teleportFallbackShaders) {
-                    shader.uniforms.uTeleportProgress.value = this.teleportProgress;
-                }
-                if (this.teleportProgress >= 1.0) {
-                    if (this.outgoingVrm) {
-                        this.outgoingVrm.scene.parent?.remove(this.outgoingVrm.scene);
-                        VRMUtils.deepDispose(this.outgoingVrm.scene);
-                        this.outgoingVrm = null;
-                        this.outgoingMixer = null;
-                    }
-                    this.cleanupTeleportDissolve();
-                    this.cleanupTeleportSparkles();
-                    this.teleportCompleteTime = this.elapsedTime;
-                    // Notify the app that the teleport-in animation has finished
-                    if (typeof window !== "undefined") {
-                        window.dispatchEvent(new CustomEvent("eliza:vrm-teleport-complete"));
-                    }
-                }
-            }
-            this.updateTeleportSparkles();
-            this.applyMouthToVrm(this.vrm);
-            const blinkValue = this.blinkController.update(rawDelta);
-            this.vrm.expressionManager?.setValue("blink", blinkValue);
-        }
-        // Process camera transition
-        if (this.isCameraTransitioning) {
-            this.transitionProgress += stableDelta / this.transitionDuration;
-            let finished = false;
-            if (this.transitionProgress >= 1.0) {
-                this.transitionProgress = 1.0;
-                this.isCameraTransitioning = false;
-                finished = true;
-            }
-            // Smooth step easing
-            const t = this.transitionProgress;
-            const ease = t * t * (3.0 - 2.0 * t);
-            camera.position.lerpVectors(this.transitionStartPos, this.transitionTargetPos, ease);
-            this.baseCameraPosition.copy(camera.position);
-            this.lookAtTarget.lerpVectors(this.transitionStartLookAt, this.transitionTargetLookAt, ease);
-            camera.fov = THREE.MathUtils.lerp(this.transitionStartFov, this.transitionTargetFov, ease);
-            camera.updateProjectionMatrix();
-            if (this.controls) {
-                this.controls.target.copy(this.lookAtTarget);
-                if (finished) {
-                    this.controls.update(); // Sync once at the very end when bounds match
-                }
-            }
-        }
-        const manualCameraActive = this.interactionEnabled;
-        if (!manualCameraActive &&
-            this.cameraAnimation.enabled &&
-            this.baseCameraPosition.length() > 0) {
-            this.cameraManager.applyCameraMotion(camera, this.baseCameraPosition, this.lookAtTarget, this.cameraAnimation, this.elapsedTime);
-        }
-        const dragOrbitFollow = Math.min(1, stableDelta * 9);
-        this.dragOrbitCurrent.lerp(this.dragOrbitTarget, dragOrbitFollow);
-        if (this.dragOrbitCurrent.lengthSq() > 1e-6 &&
-            this.baseCameraPosition.lengthSq() > 1e-6) {
-            const orbitOffset = this.tempCameraOrbitOffset
-                .copy(camera.position)
-                .sub(this.lookAtTarget);
-            if (orbitOffset.lengthSq() > 1e-6) {
-                const spherical = this.tempCameraSpherical.setFromVector3(orbitOffset);
-                spherical.theta += this.dragOrbitCurrent.x;
-                spherical.phi = THREE.MathUtils.clamp(spherical.phi + this.dragOrbitCurrent.y, 0.2, Math.PI - 0.2);
-                orbitOffset.setFromSpherical(spherical);
-                camera.position.copy(this.lookAtTarget).add(orbitOffset);
-            }
-        }
-        this.applyCompanionZoom(camera, stableDelta);
-        // Smoothly lerp camera orbital yaw offset (used by CharacterEditor to
-        // rotate around the character so she appears on the left side).
-        const editorFollow = Math.min(1, stableDelta * 5);
-        this.cameraXOffsetCurrent = THREE.MathUtils.lerp(this.cameraXOffsetCurrent, this.cameraXOffsetTarget, editorFollow);
-        this.cameraYawOffsetCurrent = THREE.MathUtils.lerp(this.cameraYawOffsetCurrent, this.cameraYawOffsetTarget, editorFollow);
-        // Scale offset by inverse zoom: more shift when zoomed out, less when in
-        const zoomScale = 1 - this.companionZoomCurrent * 0.8;
-        if (Math.abs(this.cameraYawOffsetCurrent) > 1e-5) {
-            const orbitVec = this.tempCameraOrbitOffset
-                .copy(camera.position)
-                .sub(this.lookAtTarget);
-            if (orbitVec.lengthSq() > 1e-6) {
-                const sph = this.tempCameraSpherical.setFromVector3(orbitVec);
-                sph.theta += this.cameraYawOffsetCurrent * zoomScale;
-                orbitVec.setFromSpherical(sph);
-                camera.position.copy(this.lookAtTarget).add(orbitVec);
-            }
-        }
-        // Also translate camera on X for the positional shift
-        const scaledXOffset = this.cameraXOffsetCurrent * zoomScale;
-        if (Math.abs(scaledXOffset) > 1e-4) {
-            camera.position.x += scaledXOffset;
-        }
-        if (this.pointerParallaxEnabled) {
-            const follow = Math.min(1, stableDelta * 7.5);
-            this.pointerParallaxCurrent.lerp(this.pointerParallaxTarget, follow);
-            this.pointerParallaxPosition.set(this.pointerParallaxCurrent.x * 0.18, this.pointerParallaxCurrent.y * 0.12, 0);
-            camera.position.add(this.pointerParallaxPosition);
-            this.pointerParallaxLookAt
-                .copy(this.lookAtTarget)
-                .add(new THREE.Vector3(this.pointerParallaxCurrent.x * 0.08 + scaledXOffset, this.pointerParallaxCurrent.y * 0.05, 0));
-        }
-        else {
-            this.pointerParallaxCurrent.lerp(this.pointerParallaxTarget, 0.12);
-            this.pointerParallaxLookAt.copy(this.lookAtTarget);
-            if (Math.abs(scaledXOffset) > 1e-4) {
-                this.pointerParallaxLookAt.x += scaledXOffset;
-            }
-        }
-        if (this.controls) {
-            if (manualCameraActive && !this.isCameraTransitioning) {
-                this.controls.update();
-                this.lookAtTarget.copy(this.controls.target);
-                // Track the manual move in our clean base position
-                this.baseCameraPosition.copy(camera.position);
-            }
-            else if (!this.isCameraTransitioning) {
-                this.controls.target.copy(this.lookAtTarget);
-            }
-        }
-        if (!manualCameraActive || this.isCameraTransitioning) {
-            camera.lookAt(this.pointerParallaxLookAt);
-        }
-        if (this.vrm) {
-            this.updateAvatarLookTarget(camera, stableDelta);
-            this.vrm.update(stableDelta);
-            this.applyAvatarHeadTracking(camera, stableDelta);
-            this.refreshAvatarEyeTracking();
-        }
-        this.mathEnvironment?.update(stableDelta, camera);
-        this.overlayManager?.update(camera, stableDelta);
-        renderer.render(scene, camera);
-        this.onUpdate?.();
-    }
-    async loadAndPlayIdle(vrm) {
-        if (this.loadingAborted)
-            return;
-        const mixer = this.mixer ?? new THREE.AnimationMixer(vrm.scene);
-        this.mixer = mixer;
-        const action = await this.ensureIdleAction(vrm, mixer);
-        if (!action)
-            return;
-        action.fadeIn(0.25);
-        action.play();
-        mixer.update(1 / 60);
-    }
-    async loadEmoteClipCached(path, vrm) {
-        const cached = this.emoteClipCache.get(path);
-        if (cached)
-            return cached;
-        const clip = await loadEmoteClip(path, vrm, this.animationLoaderContext);
-        if (clip) {
-            this.emoteClipCache.set(path, clip);
-        }
-        return clip;
-    }
-    applyMouthToVrm(vrm) {
-        const manager = vrm.expressionManager;
-        if (!manager)
-            return;
-        let target;
-        if (this.speaking) {
-            const elapsed = this.elapsedTime - this.speakingStartTime;
-            const base = Math.sin(elapsed * 12) * 0.3 + 0.4;
-            const detail = Math.sin(elapsed * 18.7) * 0.15;
-            const slow = Math.sin(elapsed * 4.2) * 0.1;
-            target = Math.max(0, Math.min(1, base + detail + slow));
-        }
-        else {
-            target = this.mouthValue;
-        }
-        const next = Math.max(0, Math.min(1, target));
-        const alpha = next > this.mouthSmoothed ? 0.3 : 0.2;
-        this.mouthSmoothed = this.mouthSmoothed * (1 - alpha) + next * alpha;
-        manager.setValue("aa", this.mouthSmoothed);
-    }
-    /**
-     * Capture a single-frame snapshot of the current VRM as a PNG Blob.
-     *
-     * When `disablePhysics` is true (the default), spring bone simulation is
-     * frozen for the capture frame so hair and cloth render in their rest pose,
-     * then restored afterwards. The render loop is paused during capture to
-     * prevent physics from re-running between reset and canvas capture.
-     */
-    async snapshot(options) {
-        const renderer = this.renderer;
-        const scene = this.scene;
-        const camera = this.camera;
-        if (!renderer || !scene || !camera)
-            return null;
-        const canvas = renderer.domElement;
-        if (!canvas)
-            return null;
-        const disablePhysics = options?.disablePhysics ?? true;
-        const width = options?.width ?? canvas.width;
-        const height = options?.height ?? canvas.height;
-        // Pause the render loop so physics doesn't re-run between reset and capture
-        const wasPaused = this.paused;
-        this.setPaused(true);
-        // Cancel any pending animation frame to ensure the loop truly stops
-        if (this.animationFrameId !== null) {
-            cancelAnimationFrame(this.animationFrameId);
-            this.animationFrameId = null;
-        }
-        // Reset spring bones to rest pose (hair/cloth at initial position)
-        const springBoneManager = this.vrm?.springBoneManager ?? null;
-        if (disablePhysics && springBoneManager) {
-            springBoneManager.reset?.();
-        }
-        // Resize renderer for the capture resolution
-        renderer.setPixelRatio(1);
-        renderer.setSize(width, height);
-        camera.aspect = width / height;
-        camera.updateProjectionMatrix();
-        // Update VRM transforms without physics
-        if (this.vrm) {
-            if (disablePhysics && springBoneManager) {
-                // Update only the humanoid/expression without spring bones
-                this.vrm.humanoid?.update?.();
-                this.vrm.expressionManager?.update?.();
-            }
-            else {
-                this.vrm.update(0);
-            }
-        }
-        // Render the frame (synchronous — captures immediately to canvas)
-        renderer.render(scene, camera);
-        // Capture the canvas
-        const blob = await new Promise((resolve) => {
-            canvas.toBlob((b) => resolve(b), "image/png");
-        });
-        // Restore drawing buffer + DPR policy (matches normal display, including
-        // low-power cap) instead of raw `devicePixelRatio` alone.
-        this.applyRendererPixelRatio();
-        // Restore paused state — resume the render loop
-        this.setPaused(wasPaused);
-        return blob;
-    }
-}