@elizaos/ui 2.0.3-beta.2 → 2.0.3-beta.3

package/hooks/useLayoutShiftMonitor.js

@@ -0,0 +1,128 @@
+// Runtime reflow (layout-shift) telemetry (issue #9141).
+//
+// useRenderGuard catches runaway *re-renders*; useFrameBudgetMonitor catches
+// dropped *frames*. Neither catches a *reflow*: content jumping after paint (a
+// ranked widget list reordering, a card popping in and pushing siblings down,
+// an avatar loading with no reserved box). That visible "blip" is exactly a
+// `layout-shift` PerformanceEntry, the same signal Chrome sums into CLS.
+//
+// This module is the missing runtime glue: a passive PerformanceObserver that
+// windows the shifts and emits a LayoutShiftTelemetryEvent on the SAME
+// `eliza:render-telemetry` channel the render-guard and frame-budget monitor
+// use (one channel, by design). The pure CLS math lives in
+// ../testing/layout-stability (shared with the unit tests + the e2e observer),
+// so this file is only the browser glue and stays thin.
+//
+// A layout-shift observer is passive: it fires only when the layout actually
+// shifts, with no rAF/poll, so unlike the frame-budget sampler it is cheap
+// enough to run always-on in dev. It therefore gates on the same
+// isRenderTelemetryEnabled() switch as useRenderGuard (on in dev/test, off in
+// production, killable via __ELIZA_RENDER_TELEMETRY_DISABLED__ or the env), not
+// the opt-in perf-HUD flag.
+import { useEffect } from "react";
+import { cumulativeLayoutShift, } from "../testing/layout-stability.js";
+import { currentRoute, isRenderTelemetryEnabled, nextRenderTelemetrySequence, RENDER_TELEMETRY_EVENT, } from "./useRenderGuard.js";
+/** Web Vitals "good" CLS budget: above this, a window of shifts is flagged. */
+export const DEFAULT_CLS_BUDGET = 0.1;
+function emitLayoutShift(event) {
+    const globalObject = globalThis;
+    if (Array.isArray(globalObject.__ELIZA_RENDER_TELEMETRY__)) {
+        globalObject.__ELIZA_RENDER_TELEMETRY__.push(event);
+    }
+    if (typeof window !== "undefined" && typeof CustomEvent !== "undefined") {
+        window.dispatchEvent(new CustomEvent(RENDER_TELEMETRY_EVENT, { detail: event }));
+    }
+    const message = `[RenderTelemetry] layout shifted ${event.shiftCount}x (CLS ${event.cls.toFixed(3)}) within ${event.windowMs}ms`;
+    if (event.severity === "error") {
+        console.error(message, event);
+    }
+    else {
+        console.info(message, event);
+    }
+}
+/**
+ * Start observing layout shifts. Returns a stop function. No-op (returns a no-op
+ * stop) when render telemetry is disabled or the engine lacks the layout-shift
+ * PerformanceObserver (notably Safari/WebKit).
+ */
+export function startLayoutShiftMonitor(options = {}) {
+    if (!isRenderTelemetryEnabled() ||
+        typeof PerformanceObserver !== "function" ||
+        typeof window === "undefined") {
+        return () => { };
+    }
+    const windowMs = options.windowMs ?? 1000;
+    const clsBudget = options.clsBudget ?? DEFAULT_CLS_BUDGET;
+    const emitHealthy = options.emitHealthy ?? false;
+    let pending = [];
+    let largest = 0;
+    let flushTimer = null;
+    const flush = () => {
+        flushTimer = null;
+        const samples = pending;
+        const largestShift = largest;
+        pending = [];
+        largest = 0;
+        const cls = cumulativeLayoutShift(samples);
+        const shiftCount = samples.filter((s) => !s.hadRecentInput && s.value > 0).length;
+        if (shiftCount === 0)
+            return;
+        const flagged = cls > clsBudget;
+        if (!flagged && !emitHealthy)
+            return;
+        emitLayoutShift({
+            source: "layoutShift",
+            severity: flagged ? "error" : "info",
+            cls,
+            shiftCount,
+            largestShift,
+            windowMs,
+            at: Date.now(),
+            sequence: nextRenderTelemetrySequence(),
+            route: currentRoute(),
+        });
+    };
+    let observer = null;
+    try {
+        observer = new PerformanceObserver((list) => {
+            for (const entry of list.getEntries()) {
+                if (!Number.isFinite(entry.value) || entry.value <= 0)
+                    continue;
+                pending.push({
+                    value: entry.value,
+                    hadRecentInput: entry.hadRecentInput === true,
+                });
+                if (!entry.hadRecentInput && entry.value > largest) {
+                    largest = entry.value;
+                }
+            }
+            // Coalesce a reflow burst into one window: only the first shift arms the
+            // timer; nothing runs while the layout is stable (no rAF, no poll).
+            if (flushTimer === null && pending.length > 0) {
+                flushTimer = setTimeout(flush, windowMs);
+            }
+        });
+        observer.observe({ type: "layout-shift", buffered: true });
+    }
+    catch {
+        // `layout-shift` unsupported: nothing to observe; treat as 0 reflow.
+        observer = null;
+    }
+    return () => {
+        if (flushTimer !== null)
+            clearTimeout(flushTimer);
+        flushTimer = null;
+        observer?.disconnect();
+        observer = null;
+        pending = [];
+    };
+}
+/**
+ * React hook: observe layout shifts while mounted. A no-op in production. Reacts
+ * to nothing at runtime (always-on in dev), so callers mount it once near the
+ * shell root.
+ */
+export function useLayoutShiftMonitor(options = {}) {
+    // biome-ignore lint/correctness/useExhaustiveDependencies: options read once at start
+    useEffect(() => startLayoutShiftMonitor(options), []);
+}

package/hooks/useNow.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A coarse "current time" (epoch-ms) that updates on an interval, for recency /
+ * decay math that must re-render as time passes (e.g. home-widget attention
+ * decay). Returns `0` on the first render so that render path stays
+ * deterministic — `Date.now()` is never called during render (see the UI
+ * determinism convention); the real clock is installed in an effect and then
+ * ticks every `intervalMs`.
+ */
+export declare function useNow(intervalMs?: number): number;
+//# sourceMappingURL=useNow.d.ts.map

package/hooks/useNow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNow.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/useNow.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,GAAG,MAAM,CAQlD"}

package/hooks/useNow.js

@@ -0,0 +1,18 @@
+import { useEffect, useState } from "react";
+/**
+ * A coarse "current time" (epoch-ms) that updates on an interval, for recency /
+ * decay math that must re-render as time passes (e.g. home-widget attention
+ * decay). Returns `0` on the first render so that render path stays
+ * deterministic — `Date.now()` is never called during render (see the UI
+ * determinism convention); the real clock is installed in an effect and then
+ * ticks every `intervalMs`.
+ */
+export function useNow(intervalMs = 60_000) {
+    const [now, setNow] = useState(0);
+    useEffect(() => {
+        setNow(Date.now());
+        const id = setInterval(() => setNow(Date.now()), intervalMs);
+        return () => clearInterval(id);
+    }, [intervalMs]);
+    return now;
+}

package/hooks/useRuntimeMode.d.ts

@@ -17,7 +17,7 @@
  * build), the hook returns `phase: "unavailable"` and callers fall back to
  * local heuristics. The snapshot is advisory; it never gates security.
  */
-import { type RuntimeMode, type RuntimeModeSnapshot } from "../api/runtime-mode-client";
+import { type RuntimeMode, type RuntimeModeSnapshot } from "../api/runtime-mode-client.js";
 export type UseRuntimeModeState = {
     phase: "loading";
 } | {

package/hooks/useSignalPairing.d.ts

@@ -1,5 +1,5 @@
-export type { SignalPairingStatus } from "../api/client-types-core";
-import type { SignalPairingStatus } from "../api/client-types-core";
+export type { SignalPairingStatus } from "../api/client-types-core.js";
+import type { SignalPairingStatus } from "../api/client-types-core.js";
 export declare function useSignalPairing(accountId?: string): {
     startPairing: () => Promise<void>;
     stopPairing: () => Promise<void>;

package/hooks/useViewCatalog.d.ts

@@ -1,5 +1,5 @@
 /**
- * useViewCatalog — data source for the unified `/views` launcher.
+ * useViewCatalog — data source for the unified Springboard launcher.
  *
  * Merges three sources into one {@link ViewEntry} list:
  *  - loaded views (`GET /api/views`, via {@link useAvailableViews}),
@@ -12,7 +12,7 @@
  * hot-registers the plugin's views, so a refetch flips the card to "Open" with
  * no restart.
  */
-import { type ViewEntry } from "./view-catalog";
+import { type ViewEntry } from "./view-catalog.js";
 export interface UseViewCatalogResult {
     entries: ViewEntry[];
     loading: boolean;

package/hooks/useViewCatalog.js

@@ -1,5 +1,5 @@
 /**
- * useViewCatalog — data source for the unified `/views` launcher.
+ * useViewCatalog — data source for the unified Springboard launcher.
  *
  * Merges three sources into one {@link ViewEntry} list:
  *  - loaded views (`GET /api/views`, via {@link useAvailableViews}),
@@ -16,7 +16,7 @@ import { useCallback, useMemo, useState } from "react";
 import { client } from "../api/index.js";
 import { loadAppsCatalog } from "../components/apps/load-apps-catalog.js";
 import { getActiveViewModality } from "../platform/platform-guards.js";
-import { useIsDeveloperMode } from "../state/useDeveloperMode.js";
+import { useEnabledViewKinds } from "../state/useViewKinds.js";
 import { useAvailableViews } from "./useAvailableViews.js";
 import { useCachedResource } from "./useCachedResource.js";
 import { mergeViewCatalog } from "./view-catalog.js";
@@ -25,7 +25,7 @@ const INSTALLED_CACHE_KEY = "view-catalog:installed";
 const CATALOG_STALE_MS = 60_000;
 export function useViewCatalog() {
     const { views, loading: viewsLoading, error: viewsError, refresh: refreshViews, } = useAvailableViews();
-    const isDeveloperMode = useIsDeveloperMode();
+    const enabledKinds = useEnabledViewKinds();
     const activeModality = useMemo(() => getActiveViewModality(), []);
     const catalogRes = useCachedResource(CATALOG_CACHE_KEY, () => loadAppsCatalog(), {
         staleTime: CATALOG_STALE_MS,
@@ -41,12 +41,12 @@ export function useViewCatalog() {
             catalog,
             installed,
             activeModality,
-            isDeveloperMode,
+            enabledKinds,
         });
         if (Object.keys(pending).length === 0)
             return merged;
         return merged.map((e) => pending[e.key] ? { ...e, state: pending[e.key] } : e);
-    }, [views, catalog, installed, activeModality, isDeveloperMode, pending]);
+    }, [views, catalog, installed, activeModality, enabledKinds, pending]);
     const refresh = useCallback(() => {
         refreshViews();
         catalogRes.refetch();

package/hooks/useViewEvent.d.ts

@@ -6,7 +6,7 @@
  * and give components a stable emit function.
  */
 import { type DependencyList } from "react";
-import { type ViewEvent, type ViewEventPayload } from "../views/view-event-bus";
+import { type ViewEvent, type ViewEventPayload } from "../views/view-event-bus.js";
 /**
  * Subscribe to a view event type inside a React component.
  *

package/hooks/useVoiceChat.d.ts

@@ -9,12 +9,23 @@
  * STT: local-inference ASR on local desktop, then native TalkMode or browser
  * SpeechRecognition fallback.
  */
-import type { VoiceConfig } from "../api/client";
-import { queueableSpeechPrefix, remainderAfter, splitFirstSentence, toSpeakableText } from "../voice/voice-chat-playback";
-import { mergeTranscriptWindows } from "../voice/voice-chat-recording";
-import { resolveEffectiveVoiceConfig, resolveVoiceMode, resolveVoiceProxyEndpoint, type VoiceChatOptions, type VoiceChatState, webSpeechVoiceDebugFields } from "../voice/voice-chat-types";
-export { nextIdleMouthOpen } from "../voice/voice-chat-playback";
-export type { QueueAssistantSpeechOptions, VoiceAssistantSpeechTelemetry, VoiceCaptureMode, VoiceChatOptions, VoiceChatState, VoicePlaybackStartEvent, VoiceSessionMode, VoiceSpeakerMetadata, VoiceTranscriptEvent, VoiceTranscriptPreviewEvent, VoiceTurn, } from "../voice/voice-chat-types";
+import type { VoiceConfig } from "../api/client.js";
+import { queueableSpeechPrefix, remainderAfter, splitFirstSentence, toSpeakableText } from "../voice/voice-chat-playback.js";
+import { mergeTranscriptWindows } from "../voice/voice-chat-recording.js";
+import { resolveEffectiveVoiceConfig, resolveVoiceMode, resolveVoiceProxyEndpoint, type VoiceChatOptions, type VoiceChatState, webSpeechVoiceDebugFields } from "../voice/voice-chat-types.js";
+export { nextIdleMouthOpen } from "../voice/voice-chat-playback.js";
+export type { QueueAssistantSpeechOptions, VoiceAssistantSpeechTelemetry, VoiceCaptureMode, VoiceChatOptions, VoiceChatState, VoicePlaybackStartEvent, VoiceSessionMode, VoiceSpeakerMetadata, VoiceTranscriptEvent, VoiceTranscriptPreviewEvent, VoiceTurn, } from "../voice/voice-chat-types.js";
+declare global {
+    interface Window {
+        /**
+         * Headless-test observability flag — set true the first time a real TTS
+         * playback starts. The voice self-test + real-audio e2e poll this to prove
+         * audio flowed (the only honest "reply was spoken" signal in a headless
+         * browser).
+         */
+        __voicePlaybackStarted?: boolean;
+    }
+}
 declare function resumeAudioContextForPlayback(ctx: AudioContext, timeoutMs?: number): Promise<boolean>;
 declare function shouldPreferNativeTalkMode(): boolean;
 declare function isWindowsElectrobunRenderer(): boolean;

package/hooks/useVoiceChat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useVoiceChat.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/useVoiceChat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AA6BjD,OAAO,EAKL,qBAAqB,EACrB,cAAc,EAEd,kBAAkB,EAClB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAiBL,2BAA2B,EAC3B,gBAAgB,EAChB,yBAAyB,EAOzB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAOnB,yBAAyB,EAC1B,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,SAAS,GACV,MAAM,2BAA2B,CAAC;AAYnC,iBAAe,6BAA6B,CAC1C,GAAG,EAAE,YAAY,EACjB,SAAS,SAAkC,GAC1C,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED,iBAAS,0BAA0B,IAAI,OAAO,CAG7C;AAED,iBAAS,2BAA2B,IAAI,OAAO,CAO9C;AAED,iBAAS,mCAAmC,IAAI,OAAO,CAMtD;AAED,iBAAS,0BAA0B,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAEvE;AA6BD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;CAkBhC,CAAC;AAIF,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAmgEtE"}
+{"version":3,"file":"useVoiceChat.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/useVoiceChat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAiCjD,OAAO,EAKL,qBAAqB,EACrB,cAAc,EAEd,kBAAkB,EAClB,eAAe,EAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAiBL,2BAA2B,EAC3B,gBAAgB,EAChB,yBAAyB,EAOzB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAOnB,yBAAyB,EAC1B,MAAM,2BAA2B,CAAC;AAInC,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EACV,2BAA2B,EAC3B,6BAA6B,EAC7B,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,SAAS,GACV,MAAM,2BAA2B,CAAC;AAEnC,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd;;;;;WAKG;QACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;KAClC;CACF;AAYD,iBAAe,6BAA6B,CAC1C,GAAG,EAAE,YAAY,EACjB,SAAS,SAAkC,GAC1C,OAAO,CAAC,OAAO,CAAC,CAkBlB;AAED,iBAAS,0BAA0B,IAAI,OAAO,CAG7C;AAED,iBAAS,2BAA2B,IAAI,OAAO,CAO9C;AAED,iBAAS,mCAAmC,IAAI,OAAO,CAMtD;AAED,iBAAS,0BAA0B,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,OAAO,CAEvE;AA6BD,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;CAkBhC,CAAC;AAIF,wBAAgB,YAAY,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAmjEtE"}

package/hooks/useVoiceChat.js

@@ -20,6 +20,7 @@ import { isTtsDebugEnabled, ttsDebug, ttsDebugTextPreview, } from "../utils/tts-
 import { hasConfiguredApiKey } from "../voice/index.js";
 import { isLocalAsrCaptureSupported, startLocalAsrRecorder, } from "../voice/local-asr-capture.js";
 import { isLocalInferenceAsrReady, transcribeLocalInferenceWav, } from "../voice/local-asr-transcribe.js";
+import { PlaybackFramePump, } from "../voice/playback-frame-pump.js";
 import { collapseWhitespace, nextIdleMouthOpen, normalizeCacheText, normalizeMouthOpen, queueableSpeechPrefix, remainderAfter, shouldCacheGeneratedSpeech, splitFirstSentence, toSpeakableText, } from "../voice/voice-chat-playback.js";
 import { mergeTranscriptWindows } from "../voice/voice-chat-recording.js";
 import { ASSISTANT_TTS_DEBOUNCE_MS, ASSISTANT_TTS_FINAL_ONLY, ASSISTANT_TTS_FIRST_FLUSH_CHARS, ASSISTANT_TTS_MIN_CHUNK_CHARS, DEFAULT_ELEVEN_MODEL, DEFAULT_ELEVEN_VOICE, describeTtsCloudFetchTargetForDebug, getSpeechRecognitionCtor, globalAudioCache, isAbortError, localePrefix, MAX_CACHED_SEGMENTS, matchesVoiceLocale, normalizeSpeechLocale, resolveEffectiveVoiceConfig, resolveVoiceMode, resolveVoiceProxyEndpoint, TALKMODE_STOP_SETTLE_MS, toArrayBuffer, webSpeechVoiceDebugFields, } from "../voice/voice-chat-types.js";
@@ -130,6 +131,7 @@ export function useVoiceChat(options) {
     const talkModeHandlesRef = useRef([]);
     const synthRef = useRef(null);
     const utteranceRef = useRef(null);
+    const playbackFrameTapRef = useRef(null);
     const animFrameRef = useRef(0);
     const speakingStartRef = useRef(0);
     const speechTimeoutRef = useRef(null);
@@ -193,6 +195,22 @@ export function useVoiceChat(options) {
     const interruptOnSpeechRef = useRef(options.interruptOnSpeech ?? true);
     interruptOnSpeechRef.current = options.interruptOnSpeech ?? true;
     const interruptSpeechRef = useRef(() => { });
+    const playbackFramePumpRef = useRef(null);
+    const getPlaybackFramePump = useCallback(() => {
+        if (!playbackFramePumpRef.current) {
+            playbackFramePumpRef.current = new PlaybackFramePump();
+        }
+        return playbackFramePumpRef.current;
+    }, []);
+    const stopPlaybackFrameTap = useCallback((options = {}) => {
+        const tap = playbackFrameTapRef.current;
+        playbackFrameTapRef.current = null;
+        if (!tap)
+            return;
+        void tap.stop(options).catch(() => {
+            /* best effort only */
+        });
+    }, []);
     // ── ElevenLabs Web Audio refs ──────────────────────────────────────
     const analyserRef = useRef(null);
     const audioSourceRef = useRef(null);
@@ -501,7 +519,7 @@ export function useVoiceChat(options) {
         }
         // Defer to the next backend (talk-mode / browser) when the server can't
         // transcribe right now — capturing here would only 502 at stop() with no
-        // recoverable fallback (no whisper model / native adapter installed).
+        // recoverable fallback (no local ASR assets / native adapter installed).
         if (!(await isLocalInferenceAsrReady())) {
             return false;
         }
@@ -750,6 +768,7 @@ export function useVoiceChat(options) {
         activeFetchAbortRef.current = null;
         activeTaskFinishRef.current?.();
         activeTaskFinishRef.current = null;
+        stopPlaybackFrameTap({ reset: true, drain: false });
         // Browser TTS
         synthRef.current?.cancel();
         utteranceRef.current = null;
@@ -780,7 +799,7 @@ export function useVoiceChat(options) {
         clearSpeechTimers();
         usingAudioAnalysisRef.current = false;
         setUsingAudioAnalysis(false);
-    }, [clearSpeechTimers]);
+    }, [clearSpeechTimers, stopPlaybackFrameTap]);
     const stopSpeaking = useCallback(() => {
         if (assistantTtsDebounceRef.current != null) {
             clearTimeout(assistantTtsDebounceRef.current);
@@ -967,6 +986,9 @@ export function useVoiceChat(options) {
         source.connect(analyser);
         analyser.connect(ctx.destination);
         audioSourceRef.current = source;
+        const playbackTap = await getPlaybackFramePump()
+            .tapSource(ctx, source, audioBuffer)
+            .catch(() => null);
         await new Promise((resolve) => {
             let finished = false;
             const playStartMs = performance.now();
@@ -981,6 +1003,12 @@ export function useVoiceChat(options) {
                 if (audioSourceRef.current === source) {
                     audioSourceRef.current = null;
                 }
+                if (playbackFrameTapRef.current === playbackTap) {
+                    playbackFrameTapRef.current = null;
+                }
+                void playbackTap?.stop({ reset: true }).catch(() => {
+                    /* best effort only */
+                });
                 source.onended = null;
                 try {
                     source.disconnect();
@@ -1014,6 +1042,10 @@ export function useVoiceChat(options) {
             });
             activeTaskFinishRef.current = wrappedFinish;
             source.onended = wrappedFinish;
+            if (playbackTap) {
+                playbackFrameTapRef.current = playbackTap;
+                playbackTap.start(playStartMs);
+            }
             speechTimeoutRef.current = setTimeout(wrappedFinish, Math.max(2500, Math.ceil(audioBuffer.duration * 1000) + 1200));
             source.start(0);
             emitPlaybackStart({
@@ -1027,6 +1059,7 @@ export function useVoiceChat(options) {
         });
     }, [
         clearSpeechTimers,
+        getPlaybackFramePump,
         makeElevenCacheKey,
         markAudioBlocked,
         markAudioPlaying,
@@ -1111,6 +1144,9 @@ export function useVoiceChat(options) {
         source.connect(analyser);
         analyser.connect(ctx.destination);
         audioSourceRef.current = source;
+        const playbackTap = await getPlaybackFramePump()
+            .tapSource(ctx, source, audioBuffer)
+            .catch(() => null);
         await new Promise((resolve) => {
             let finished = false;
             const playStartMs = performance.now();
@@ -1125,6 +1161,12 @@ export function useVoiceChat(options) {
                 if (audioSourceRef.current === source) {
                     audioSourceRef.current = null;
                 }
+                if (playbackFrameTapRef.current === playbackTap) {
+                    playbackFrameTapRef.current = null;
+                }
+                void playbackTap?.stop({ reset: true }).catch(() => {
+                    /* best effort only */
+                });
                 source.onended = null;
                 try {
                     source.disconnect();
@@ -1144,6 +1186,10 @@ export function useVoiceChat(options) {
             wrappedFinish = finish;
             activeTaskFinishRef.current = wrappedFinish;
             source.onended = wrappedFinish;
+            if (playbackTap) {
+                playbackFrameTapRef.current = playbackTap;
+                playbackTap.start(playStartMs);
+            }
             speechTimeoutRef.current = setTimeout(wrappedFinish, Math.max(2500, Math.ceil(audioBuffer.duration * 1000) + 1200));
             source.start(0);
             emitPlaybackStart({
@@ -1157,6 +1203,7 @@ export function useVoiceChat(options) {
         });
     }, [
         clearSpeechTimers,
+        getPlaybackFramePump,
         makeLocalInferenceCacheKey,
         markAudioBlocked,
         markAudioPlaying,

package/hooks/useWhatsAppPairing.d.ts

@@ -1,5 +1,5 @@
-export type { WhatsAppPairingStatus } from "../api/client-types-core";
-import type { WhatsAppPairingStatus } from "../api/client-types-core";
+export type { WhatsAppPairingStatus } from "../api/client-types-core.js";
+import type { WhatsAppPairingStatus } from "../api/client-types-core.js";
 export declare function useWhatsAppPairing(accountId?: string): {
     startPairing: () => Promise<void>;
     stopPairing: () => Promise<void>;

package/hooks/view-catalog.d.ts

@@ -14,10 +14,11 @@
  *
  * This module is the pure merge/dedupe so it can be unit-tested without React.
  */
-import type { RegistryAppInfo } from "../api";
-import type { ViewModality } from "../platform/platform-guards";
-import type { ViewRegistryEntry } from "./useAvailableViews";
-export type { ViewModality } from "../platform/platform-guards";
+import { type EnabledViewKinds, type ViewKind } from "@elizaos/core";
+import type { RegistryAppInfo } from "../api/index.js";
+import type { ViewModality } from "../platform/platform-guards.js";
+import type { ViewRegistryEntry } from "./useAvailableViews.js";
+export type { ViewModality } from "../platform/platform-guards.js";
 export type ViewEntryState = "loaded" | "available" | "installing" | "error";
 export type ViewEntryKind = "view" | "app";
 export interface ViewEntry {
@@ -31,10 +32,26 @@ export interface ViewEntry {
     icon?: string;
     /** Real preview image URL, or undefined when only a generated fallback exists. */
     heroUrl?: string;
+    /**
+     * Always-available preview image URL. Real plugin art wins when present;
+     * otherwise this is a deterministic branded SVG data URI. Use this (not
+     * {@link heroUrl}) when every entry must show an image, e.g. Springboard
+     * tiles.
+     */
+    imageUrl?: string;
+    /** Deterministic branded image used when a real preview image fails to load. */
+    fallbackImageUrl?: string;
     hasHero: boolean;
     category?: string;
     /** Presentation modality (`gui` for catalog apps until loaded). */
     modality: ViewModality;
+    /**
+     * Every surface this logical view renders on. A single-declaration entry has
+     * `[modality]`; after {@link collapseViewEntries} it carries the union of all
+     * same-id declarations (e.g. `["gui", "xr", "tui"]`) so the view lists once
+     * with modality badges instead of one duplicate row per surface.
+     */
+    modalities?: ViewModality[];
     state: ViewEntryState;
     kind: ViewEntryKind;
     /** Catalog/plugin package name — used to launch and to dedupe vs loaded. */
@@ -47,6 +64,8 @@ export interface ViewEntry {
     launchUrl?: string | null;
     builtin?: boolean;
     developerOnly?: boolean;
+    /** Four-tier visibility category resolved from the source declaration. */
+    viewKind?: ViewKind;
     /** Source records (one is set depending on `kind`). */
     view?: ViewRegistryEntry;
     app?: RegistryAppInfo;
@@ -55,6 +74,7 @@ export interface ViewEntry {
 export interface InstalledAppLike {
     name: string;
 }
+export declare function viewToEntry(view: ViewRegistryEntry): ViewEntry;
 /**
  * Merge loaded views + the app catalog into one deduped launcher list.
  *
@@ -69,6 +89,18 @@ export declare function mergeViewCatalog(input: {
     catalog: RegistryAppInfo[];
     installed: readonly InstalledAppLike[];
     activeModality: ViewModality;
-    isDeveloperMode: boolean;
+    /** Which view kinds the user/​build has enabled (system+release always on). */
+    enabledKinds: EnabledViewKinds;
 }): ViewEntry[];
+/**
+ * Collapse entries that share an `id` into one logical entry carrying the union
+ * of every surface they render on. The GUI entry is preferred as the base (its
+ * label has no "XR"/"TUI" suffix); its `modalities` becomes the deduped union of
+ * all same-id entries. First-seen order is preserved. App entries (`kind:"app"`)
+ * have unique package-name ids, so they collapse to themselves.
+ *
+ * This is what makes a view appear ONCE with modality badges instead of one
+ * duplicate row per surface ("Phone" / "Phone XR" / "Phone TUI").
+ */
+export declare function collapseViewEntries(entries: ViewEntry[]): ViewEntry[];
 //# sourceMappingURL=view-catalog.d.ts.map

package/hooks/view-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-catalog.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/view-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAC7E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,EAAE,YAAY,CAAC;IACvB,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAgDD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvC,cAAc,EAAE,YAAY,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;CAC1B,GAAG,SAAS,EAAE,CAgCd"}
+{"version":3,"file":"view-catalog.d.ts","sourceRoot":"","sources":["../../../../../src/hooks/view-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAoB7D,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEhE,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,WAAW,GAAG,YAAY,GAAG,OAAO,CAAC;AAC7E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,KAAK,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,uDAAuD;IACvD,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,SAAS,CAiC9D;AAoCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE;IACtC,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,SAAS,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACvC,cAAc,EAAE,YAAY,CAAC;IAC7B,+EAA+E;IAC/E,YAAY,EAAE,gBAAgB,CAAC;CAChC,GAAG,SAAS,EAAE,CAgCd;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAwBrE"}