@alia.onl/sdk 13.0.0 → 13.2.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @alia.onl/sdk
 
+## 13.1.1
+
+- **The avatar flights load the runtime too.** 13.1.0 mounted the character runtime provider inside
+  the chat, but the sheet's avatar-flight layer (the avatar that flies from the welcome into the
+  header) is drawn outside it, so it asked the host for its own `/bloom-character/runtime.mjs` and got
+  the app's HTML back ("Expected a JavaScript-or-Wasm module script but the server responded with
+  a MIME type of text/html"). `AliaChatSheet` and `AliaChatScreen` now wrap everything they draw in the
+  provider, once; `AliaChatContent` no longer mounts one (it is not an entry point on its own).
+
+## 13.2.0
+
+One composer for the sheet, the screen and the Alia app: the app's composer moved here and the
+app consumes it.
+
+- **`AliaComposer`** (exported) is Bloom's `ComposerPanel` plus what every Alia surface needs the
+  same way: files by paste and drop (read with real progress, retried, refused with a sentence),
+  dictation, the suggestions over the field and the questions Alia asked, docked above it. What
+  differs per surface is a prop: `addMenu` / `onAddMenuSelect`, `modes` / `mode` /
+  `onModeChange` (a power-level selector), `attachments` / `onAddAttachment` /
+  `onRemoveAttachment` (a composer given no `onAddAttachment` takes no paste or drop),
+  `attachmentKinds` (`['image']` refuses a document with a sentence), `suggestions`, `questions`,
+  `status`, `emptyAction`, `accessory`, `onKeyPress`, `speechLanguage`, `labels`, `onError`.
+  `AliaChatContent` (so the sheet and the screen) renders it with photos, voice and suggestions;
+  a host gets today's behaviour with no setup.
+- **The sheet's composer is the panel, not the pill.** The pill has no mode selector, status tab
+  or question slot, which the Alia app needs; the sheet and the app now draw the same card. The
+  agent-working light (`ComposerLoader`) is not drawn around it, as in the app: a turn in flight
+  is its stop control and the thread's thinking line.
+- **Photos are `AliaAttachment`s** (exported type): the chat's picked photos wait as the same
+  tiles a dropped or pasted image becomes, with the same remove and error states.
+- **`AliaChatLabels` gains** `composerMessage`, `composerAddMenu`, `composerModes`,
+  `composerVoice`, `composerSend`, `composerStop`, `composerRemove`, `composerRetry`,
+  `composerUntitled`, `fileReadFailed`, `fileTooLarge`, `fileEmpty`, `fileUnsupported`,
+  `dropHint`, `dropUnavailable` and `voiceError(code)`, all with English defaults. A nested
+  `AliaChatLabelsProvider` now refines the labels already in reach instead of resetting them.
+- **`usePendingQuestions(messages, isStreaming)`** (exported) is the "asked above the composer,
+  put away until she asks again" rule both the chat and the app used to keep a copy of.
+- **`classifyIntake` / `MAX_ATTACHMENT_BYTES`** (from `@alia.onl/sdk/tools`) are the rules a file
+  passes to be attached.
+- **The sheet focuses its composer once it has presented.** `AliaChatSheet` hands each sheet's
+  `animatedProgress` (Bloom's own "fully presented" signal, no timer) to its chat, whose composer
+  takes focus when it reads `1`: the person can type at once and the keyboard opens on native. It
+  focuses once per `present()` for the main sheet and for the conversation sheet over it; dragging
+  a sheet part-way and letting go does not take the focus again. `AliaChatContent` takes
+  `presentedProgress` for a host that builds its own sheet; the screen and the app's own screens
+  pass none and keep their focus. Not verified on a device.
+
+A voice call that cannot speak ends and says why, instead of listening on in silence:
+
+- **`requestSpeechClip` throws a `SpeechClipError`** (exported) with the route's HTTP `status`,
+  its typed `code` (`SPEECH_UNAVAILABLE`, `SPEECH_LIMIT_REACHED`, `SPEECH_REJECTED`,
+  `SPEECH_PROVIDER_FAILED`, `SPEECH_GENERATION_FAILED`, `INVALID_REQUEST`, `NOT_AUTHENTICATED`, or
+  `null`), `retryable` and `requestId`. An empty token is `NOT_AUTHENTICATED` without a request.
+- **`useVoiceRoom` ends the call when a clip cannot be made or played**, after the answer has
+  finished streaming into the transcript, with `errorCode` `synthesis-unavailable`,
+  `synthesis-limited`, `synthesis-rejected`, `synthesis-failed`, `not-authenticated` (no session
+  token) or `not-played`; `synthesisError` is the `SpeechClipError` behind it. A turn no longer
+  skips a sentence it could not speak, and `turnErrorCode` is no longer `not-played`.
+- `VoiceErrorCode` gains the four `synthesis-*` codes; an app that translates every code needs
+  their sentences.
+
+## 13.1.0
+
+The chat works in any app without host setup it did not document in code:
+
+- **The avatar loads.** The chat mounts Bloom's `AgentAvatarProvider` itself, pointing at Alia's
+  shared runtime (`ALIA_CHARACTER_RUNTIME_URL`, served with CORS open); a host that serves its own
+  passes `characterRuntimeUrl`. Before, an app that had not hosted the 214 MB runtime showed
+  Bloom's "unavailable" state.
+- **The empty chat greets.** With no `welcomeGreeting` it greets the signed-in person by name
+  (`labels.greeting` / `labels.greetingNamed`). Before, it drew nothing.
+
 ## 13.0.0
 
 Fixes found by driving the sheet end to end (the sheet shows plans, links citations, nests lists):

package/README.md

@@ -25,20 +25,18 @@ the default in Expo SDK 53+), because every icon import is a subpath.
 The chat is built from Bloom (`@oxy.so/bloom`, a peer dependency): mount Bloom's
 `BloomProvider` above it, with the one `KeyboardProvider` your app already has.
 
-Alia's avatar is Bloom's 3D character (`AgentAvatar`), which draws through a
-runtime Bloom ships as static files (about 11 MB). Serve the package's
-`assets/character-runtime/` directory unchanged and give the URL of `runtime.mjs`
-to Bloom's provider, once, near the root:
-
-```tsx
-import { AgentAvatarProvider } from '@oxy.so/bloom/agent-avatar';
-
-<AgentAvatarProvider runtimeUrl="/bloom-character/runtime.mjs">…</AgentAvatarProvider>
-```
-
-Without it the avatar shows Bloom's "unavailable" state. Native avatars run in a
+Alia's avatar is Bloom's 3D character (`AgentAvatar`). It draws through a runtime of
+static files (about 214 MB), which the chat loads from Alia's own origin
+(`ALIA_CHARACTER_RUNTIME_URL`, served with CORS open), so the app hosts nothing and mounts
+no avatar provider. An app with a strict CSP allows `https://alia.onl` in `script-src` and
+`connect-src` (and `'wasm-unsafe-eval'`). To serve your own copy instead, serve the Bloom
+package's `assets/character-runtime/` directory unchanged and pass the URL of `runtime.mjs`
+as `characterRuntimeUrl` to `AliaChatSheet` or `AliaChatScreen`; native avatars run in a
 WebView, so there the URL must be absolute and reachable from the device.
 
+The empty chat greets the signed-in person by name ("Hi Nate, what's on your mind?"); pass
+`welcomeGreeting` to say something else, or `labels.greeting` / `labels.greetingNamed` to translate it.
+
 Failures (a voice call that cannot start, a dictation error) are shown with Bloom's `toast`,
 so the app needs a `ToastOutlet` (`OxyProvider` mounts one), or pass `onError` to handle them.
 
@@ -114,6 +112,37 @@ components render. Those events are the product runtime's, not part of the Oxy
 generic inference contract, and this package is written against them on
 purpose: it is a **product** client.
 
+## The composer
+
+The sheet, the screen and the Alia app share one composer, `AliaComposer`: Bloom's
+`ComposerPanel` with files by paste and drop (read with real progress, retried, refused with a
+sentence), dictation, suggestions over the field and Alia's questions docked above it.
+`AliaChatSheet` and `AliaChatScreen` render it with photos, voice and suggestions, and
+`AliaChatSheet` focuses it once the sheet has presented. To build your own surface, mount it and
+pass what the surface has:
+
+```tsx
+import { AliaComposer } from '@alia.onl/sdk';
+
+<AliaComposer
+  value={draft}
+  onValueChange={setDraft}
+  onSubmit={send}
+  busy={isStreaming}
+  onStop={stop}
+  modes={powerLevels} // the mode selector; omit to hide it
+  mode={level}
+  onModeChange={setLevel}
+  addMenu={groups} // the add menu's rows, and what pressing one does
+  onAddMenuSelect={onAdd}
+  attachments={files} // omit `onAddAttachment` and the composer takes no paste or drop
+  onAddAttachment={addFile}
+  onRemoveAttachment={removeFile}
+  attachmentKinds={['image']} // what your send carries; others are refused with a sentence
+  labels={{ composerSend: 'Enviar' }} // anything omitted is English
+/>;
+```
+
 ## Which endpoint the SDK calls, and why
 
 The hook sends its turns to `POST {apiUrl}/v1/chat/completions`, with `apiUrl`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "13.0.0",
+  "version": "13.2.0",
   "description": "Alia AI chat SDK — reusable chat UI, voice, and streaming components for Oxy apps",
   "main": "src/index.ts",
   "react-native": "src/index.ts",
@@ -32,7 +32,7 @@
   "dependencies": {
     "clsx": "^2.1.1",
     "react-native-markdown-display": "^7.0.2",
-    "tailwind-merge": "^3.6.0",
+    "tailwind-merge": "^3.7.0",
     "zustand": "^5.0.15"
   },
   "peerDependencies": {

package/src/components/AliaChatContent.tsx

@@ -8,29 +8,30 @@
  */
 
 import React, { Suspense, useState, useCallback, useEffect, useMemo, useRef } from 'react';
-import { View } from 'react-native';
+import { View, type TextInput } from 'react-native';
+import type { SharedValue } from 'react-native-reanimated';
 import { useAliaChat, type UseAliaChatOptions } from '../hooks/useAliaChat';
 import { useTTS } from '../hooks/useTTS';
-import { useSpeechToText } from '../hooks/useSpeechToText';
+import { useFocusWhenPresented } from '../hooks/useFocusWhenPresented';
+import { usePendingQuestions } from '../hooks/usePendingQuestions';
 import { useImagePicker } from '../hooks/useImagePicker';
 import { imageUriToDataUrl } from '../lib/image-data-url';
 import { useAmbientWave } from '../hooks/useAmbientWave';
 import { AmbientField } from './AmbientField';
-import { QuestionCard } from './QuestionCard';
-import { pendingQuestions } from '../lib/questions';
+import { getAccountDisplayName } from '@oxy.so/core';
+import { useOxy } from '@oxy.so/services/ui/client';
 import { AliaChatMessageList } from './AliaChatMessageList';
 import { AliaFlightsProvider, ALIA_TO_PROFILE } from '../lib/flights';
 import { AliaWelcomeMessage } from './AliaWelcomeMessage';
-import { ComposerSuggestions } from './ComposerSuggestions';
+import { AliaComposer } from './AliaComposer';
 import { useComposerSuggestions, useSuggestionQuery } from '../hooks/useComposerSuggestions';
-import { ComposerLoader } from '@oxy.so/bloom/composer-loader';
 import { AiChatContainer } from '@oxy.so/bloom/ai-chat';
 import {
   AvatarFlightLayer,
   useAvatarFlights,
   type AvatarFlights,
 } from '@oxy.so/bloom/avatar-flight';
-import { ComposerPill, type ComposerPanelAddMenuGroup } from '@oxy.so/bloom/composer-panel';
+import type { ComposerPanelAddMenuGroup } from '@oxy.so/bloom/composer-panel';
 import { RiImageLine } from '@oxy.so/bloom/icons';
 import { toast } from '@oxy.so/bloom/toast';
 import { Button } from '@oxy.so/bloom/button';
@@ -38,6 +39,7 @@ import { type AliaChatLabels, AliaChatLabelsProvider, useLabels } from '../lib/l
 import type { AliaAvatarState } from './AliaAvatar';
 import { VoiceModeIcon } from './VoiceModeIcon';
 import type {
+  AliaAttachment,
   AliaSuggestion,
   ChatMessage,
   VoiceMessage,
@@ -84,7 +86,7 @@ export interface AliaChatContentProps {
   apiUrl?: string;
   /** Error handler (e.g. toast) */
   onError?: (message: string) => void;
-  // Welcome message
+  /** The empty chat's greeting; omitted, Alia greets the signed-in person by name (`labels`). */
   welcomeGreeting?: string;
   welcomeSubtitle?: string;
   /** The lines offered over the composer on an empty chat. */
@@ -133,12 +135,21 @@ export interface AliaChatContentProps {
   flights?: AvatarFlights;
   /** A turn sent once as this chat mounts: the conversation a sheet was opened for. */
   initialTurn?: AliaTurn;
+  /**
+   * The `animatedProgress` of the Bloom sheet this chat is in. The composer takes focus (and on
+   * native opens the keyboard) once it reads `1`, so the person can type as soon as the sheet is
+   * up. Omitted, the chat is not in a sheet and focus is left alone.
+   */
+  presentedProgress?: SharedValue<number>;
   /** Internal sheet lifecycle bridge: receives the live request canceller. */
   onStopReady?: (stop: (() => void) | null) => void;
   /** Overrides for the chat's own copy; anything omitted is English. */
   labels?: Partial<AliaChatLabels>;
 }
 
+/** The chat API carries photos (`image_url` parts) and nothing else. */
+const PHOTOS_ONLY = ['image'] as const;
+
 /** The add menu: photos are the one attachment the chat API carries (`image_url` parts). */
 function addMenu(labels: AliaChatLabels): ComposerPanelAddMenuGroup[] {
   return [
@@ -186,6 +197,7 @@ function AliaChatContentBody({
   agents: knownAgents,
   flights: sharedFlights,
   initialTurn,
+  presentedProgress,
   onStopReady,
 }: AliaChatContentProps) {
   const ownFlights = useAvatarFlights();
@@ -206,15 +218,7 @@ function AliaChatContentBody({
   const { messages, setMessages, send, isStreaming, stop, clear, approvePlan, rejectPlan } =
     useAliaChat(chatOptions);
   const agents = useMemo(() => participatingAgents(messages), [messages]);
-  // What Alia asked in her last turn and the person has not answered: asked above the composer,
-  // not in the thread. Any later message, typed or sent from the card, is the answer.
-  const lastMessage = messages.at(-1);
-  const questionsAsked = useMemo(
-    () => pendingQuestions(messages, isStreaming),
-    [messages, isStreaming],
-  );
-  const [dismissedQuestionsOf, setDismissedQuestionsOf] = useState<string | null>(null);
-  const asking = questionsAsked.length > 0 && dismissedQuestionsOf !== lastMessage?.id;
+  const asked = usePendingQuestions(messages, isStreaming);
 
   // The first turn of an empty chat goes to the host when it asked for it; every other turn is sent here.
   const startsElsewhere = onStart !== undefined && messages.length === 0;
@@ -252,9 +256,7 @@ function AliaChatContentBody({
   const [inputValue, setInputValue] = useState('');
 
   // Picked photos wait here, as tiles above the field, until the turn is sent.
-  const [photos, setPhotos] = useState<
-    Array<{ id: string; name: string; uri: string; mimeType?: string }>
-  >([]);
+  const [photos, setPhotos] = useState<AliaAttachment[]>([]);
   const { pickImage } = useImagePicker();
 
   const handleAddMenuSelect = useCallback(
@@ -266,8 +268,10 @@ function AliaChatContentBody({
         ...prev,
         ...assets.map((asset) => ({
           id: `img-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+          type: 'image' as const,
           name: asset.name,
           uri: asset.uri,
+          size: asset.size,
           mimeType: asset.mimeType,
         })),
       ]);
@@ -317,24 +321,6 @@ function AliaChatContentBody({
     [submitTurn, photos, reportError],
   );
 
-  // ── Dictation: the pill's mic toggles it, the transcript lands in the field ──
-  const stt = useSpeechToText();
-  useEffect(() => {
-    if (stt.error) reportError(stt.error);
-  }, [stt.error, reportError]);
-  const sttRef = useRef(stt);
-  sttRef.current = stt;
-  const handleListeningChange = useCallback(async (listening: boolean) => {
-    const current = sttRef.current;
-    if (listening) {
-      if (!current.isRecording && !current.isTranscribing) current.startRecording();
-      return;
-    }
-    if (!current.isRecording) return;
-    const text = await current.stopAndTranscribe();
-    if (text) setInputValue((prev) => (prev ? `${prev} ${text}` : text));
-  }, []);
-
   // ── TTS ──
   const tts = useTTS({ apiUrl });
 
@@ -399,14 +385,17 @@ function AliaChatContentBody({
     return 'writing';
   }, [messages, isStreaming, isVoiceActive, voiceAgentState]);
 
+  const { user } = useOxy();
+  const greeting =
+    welcomeGreeting ?? (user ? labels.greetingNamed(getAccountDisplayName(user)) : labels.greeting);
   const welcomeComponent = useMemo(() => {
-    if (!welcomeGreeting || messages.length > 0) return undefined;
+    if (messages.length > 0) return undefined;
     return (
       <View className="flex-1 items-center justify-center px-4 py-10">
-        <AliaWelcomeMessage greeting={welcomeGreeting} subtitle={welcomeSubtitle} />
+        <AliaWelcomeMessage greeting={greeting} subtitle={welcomeSubtitle} />
       </View>
     );
-  }, [welcomeGreeting, welcomeSubtitle, messages.length]);
+  }, [greeting, welcomeSubtitle, messages.length]);
 
   // ── Ambient wave — one persistent overlay across idle/voice/TTS/STT ──
   const wave = useAmbientWave({
@@ -443,16 +432,8 @@ function AliaChatContentBody({
     [VoiceSession, activateVoice, labels.startVoice],
   );
 
-  const pillAttachments = useMemo(
-    () =>
-      photos.map((photo) => ({
-        id: photo.id,
-        name: photo.name,
-        kind: 'image' as const,
-        src: photo.uri,
-      })),
-    [photos],
-  );
+  const composerRef = useRef<TextInput | null>(null);
+  useFocusWhenPresented(presentedProgress, () => composerRef.current?.focus());
 
   const composer =
     VoiceSession && isVoiceActive ? (
@@ -461,45 +442,32 @@ function AliaChatContentBody({
         <VoiceSession apiUrl={apiUrl} onStateChange={setVoiceState} onEnd={deactivateVoice} />
       </Suspense>
     ) : (
-      <>
-        <ComposerSuggestions
-          completions={suggestions.completions}
-          selected={suggestions.selected}
-          onPick={handlePickSuggestion}
-        />
-        {/* Beside the loader, not inside the pill: its light traces the box it wraps. */}
-        {asking ? (
-          <View className="mb-2">
-            <QuestionCard
-              questions={questionsAsked}
-              onSubmit={(message) => send(message)}
-              onDismiss={() => setDismissedQuestionsOf(lastMessage?.id ?? null)}
-            />
-          </View>
-        ) : null}
-        <ComposerLoader active={isStreaming}>
-          <ComposerPill
-            onKeyPress={suggestions.onKeyPress}
-            surface={false}
-            frosted={isStreaming}
-            value={inputValue}
-            onValueChange={setInputValue}
-            onSubmit={handleSubmit}
-            busy={isStreaming}
-            onStop={stop}
-            emptyAction={voiceActivateButton}
-            placeholder={labels.placeholder}
-            addMenu={addMenuGroups}
-            onAddMenuSelect={handleAddMenuSelect}
-            attachments={pillAttachments}
-            onRemoveAttachment={(id) => setPhotos((prev) => prev.filter((p) => p.id !== id))}
-            voiceState={
-              stt.isTranscribing ? 'transcribing' : stt.isRecording ? 'recording' : 'idle'
-            }
-            onVoiceStateChange={(next) => void handleListeningChange(next === 'recording')}
-          />
-        </ComposerLoader>
-      </>
+      <AliaComposer
+        inputRef={composerRef}
+        disableKeyboardAvoidance
+        onKeyPress={suggestions.onKeyPress}
+        suggestions={{ ...suggestions, onPick: handlePickSuggestion }}
+        // Asked beside the field, not in the thread: the card docks above the composer.
+        questions={{
+          items: asked.questions,
+          onSubmit: (message) => send(message),
+          onDismiss: asked.dismiss,
+        }}
+        value={inputValue}
+        onValueChange={setInputValue}
+        onSubmit={() => void handleSubmit(inputValue)}
+        busy={isStreaming}
+        onStop={stop}
+        emptyAction={voiceActivateButton}
+        placeholder={labels.placeholder}
+        addMenu={addMenuGroups}
+        onAddMenuSelect={handleAddMenuSelect}
+        attachments={photos}
+        onAddAttachment={(photo) => setPhotos((prev) => [...prev, photo])}
+        onRemoveAttachment={(id) => setPhotos((prev) => prev.filter((p) => p.id !== id))}
+        attachmentKinds={PHOTOS_ONLY}
+        onError={onError}
+      />
     );
 
   const hasMessages = messages.length > 0;

package/src/components/AliaChatScreen.tsx

@@ -20,6 +20,8 @@
 import React, { useCallback } from 'react';
 import { View } from 'react-native';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { AgentAvatarProvider } from '@oxy.so/bloom/agent-avatar';
+import { ALIA_CHARACTER_RUNTIME_URL } from '../lib/character-runtime';
 import { KeyboardAvoidingView } from '../lib/keyboard';
 import { AliaChatContent, type AliaChatContentProps } from './AliaChatContent';
 import { AliaChatHeader } from './AliaChatHeader';
@@ -62,6 +64,8 @@ export interface AliaChatScreenProps {
   voiceSession?: VoiceSessionComponent;
   /** Overrides for the chat's own copy (header, composer, plan, research…); omitted, English. */
   labels?: Partial<AliaChatLabels>;
+  /** Where the 3D avatar's runtime is served from; omitted, Alia's shared copy (`ALIA_CHARACTER_RUNTIME_URL`). */
+  characterRuntimeUrl?: string;
 }
 
 export function AliaChatScreen({
@@ -82,6 +86,7 @@ export function AliaChatScreen({
   isDarkMode,
   voiceSession,
   labels,
+  characterRuntimeUrl = ALIA_CHARACTER_RUNTIME_URL,
 }: AliaChatScreenProps) {
   const insets = useSafeAreaInsets();
   // The screen owns the whole window, so it keeps its composer out of both
@@ -111,27 +116,29 @@ export function AliaChatScreen({
   );
 
   return (
-    <View
-      className="flex-1 bg-background-full"
-      style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}
-    >
-      <KeyboardAvoidingView behavior="padding" automaticOffset style={{ flex: 1 }}>
-        <AliaChatContent
-          clientContext={clientContext}
-          model={model}
-          apiUrl={apiUrl}
-          welcomeGreeting={welcomeGreeting}
-          welcomeSubtitle={welcomeSubtitle}
-          welcomeSuggestions={welcomeSuggestions}
-          agents={agents}
-          suggestionMatches={suggestionMatches}
-          onSuggestionQuery={onSuggestionQuery}
-          isDarkMode={isDarkMode}
-          voiceSession={voiceSession}
-          labels={labels}
-          header={header}
-        />
-      </KeyboardAvoidingView>
-    </View>
+    <AgentAvatarProvider runtimeUrl={characterRuntimeUrl}>
+      <View
+        className="flex-1 bg-background-full"
+        style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}
+      >
+        <KeyboardAvoidingView behavior="padding" automaticOffset style={{ flex: 1 }}>
+          <AliaChatContent
+            clientContext={clientContext}
+            model={model}
+            apiUrl={apiUrl}
+            welcomeGreeting={welcomeGreeting}
+            welcomeSubtitle={welcomeSubtitle}
+            welcomeSuggestions={welcomeSuggestions}
+            agents={agents}
+            suggestionMatches={suggestionMatches}
+            onSuggestionQuery={onSuggestionQuery}
+            isDarkMode={isDarkMode}
+            voiceSession={voiceSession}
+            labels={labels}
+            header={header}
+          />
+        </KeyboardAvoidingView>
+      </View>
+    </AgentAvatarProvider>
   );
 }

package/src/components/AliaChatSheet.tsx

@@ -1,10 +1,13 @@
+import { AgentAvatarProvider } from '@oxy.so/bloom/agent-avatar';
 import { AvatarFlightLayer, useAvatarFlights } from '@oxy.so/bloom/avatar-flight';
 import { BottomSheet, type BottomSheetRef } from '@oxy.so/bloom/bottom-sheet';
 import { forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { useTheme } from '@oxy.so/bloom/theme';
 import { useWindowDimensions, View } from 'react-native';
+import { useSharedValue } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { BREAKPOINTS } from '@oxy.so/bloom/styles';
+import { ALIA_CHARACTER_RUNTIME_URL } from '../lib/character-runtime';
 import type { AliaChatLabels } from '../lib/labels';
 import type { VoiceSessionComponent } from '../types';
 import { AliaChatContent, type AliaChatContentProps, type AliaTurn } from './AliaChatContent';
@@ -52,6 +55,8 @@ export interface AliaChatSheetProps {
   voiceSession?: VoiceSessionComponent;
   /** Overrides for the chat's own copy (header, composer, plan, research…); omitted, English. */
   labels?: Partial<AliaChatLabels>;
+  /** Where the 3D avatar's runtime is served from; omitted, Alia's shared copy (`ALIA_CHARACTER_RUNTIME_URL`). */
+  characterRuntimeUrl?: string;
   /** Draws the header's share button once there is a conversation; omitted, no share button. */
   onShare?: () => void;
   /** More rows for the header's menu (`DropdownMenuItem`s from `@oxy.so/bloom/dropdown-menu`). */
@@ -78,6 +83,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
       isDarkMode,
       voiceSession,
       labels,
+      characterRuntimeUrl = ALIA_CHARACTER_RUNTIME_URL,
       onShare,
       headerMenu,
     },
@@ -85,6 +91,9 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
   ) => {
     // Bloom's resolved mode, not the system's scheme.
     const { isDark } = useTheme();
+    // How far each sheet is presented (0 closed, 1 up): its chat takes the composer's focus at 1.
+    const mainProgress = useSharedValue(0);
+    const conversationProgress = useSharedValue(0);
     const mainRef = useRef<BottomSheetRef>(null);
     const conversationRef = useRef<BottomSheetRef>(null);
     // Each sheet's chat registers its own canceller; closing a sheet stops its own turn.
@@ -161,13 +170,16 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
       labels,
     };
 
+    // The provider wraps the sheets AND the flight layer: both draw avatars, and an avatar drawn
+    // outside it would fall back to the host's own `/bloom-character/runtime.mjs`.
     return (
-      <>
+      <AgentAvatarProvider runtimeUrl={characterRuntimeUrl}>
         <BottomSheet
           ref={mainRef}
           detached={detached}
           scrollable={false}
           manualActivation
+          animatedProgress={mainProgress}
           onDismissAttempt={onMainDismissAttempt}
           onDismiss={() => setConversation(null)}
           style={sheetStyle}
@@ -182,6 +194,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
             agents={agents}
             suggestionMatches={suggestionMatches}
             onSuggestionQuery={onSuggestionQuery}
+            presentedProgress={mainProgress}
             onStopReady={registerMainStop}
             onStart={startConversation}
           />
@@ -194,6 +207,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
             detached={detached}
             scrollable={false}
             manualActivation
+            animatedProgress={conversationProgress}
             onDismissAttempt={onConversationDismissAttempt}
             onDismiss={() => setConversation(null)}
             style={sheetStyle}
@@ -201,6 +215,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
             <AliaChatContent
               {...shared}
               initialTurn={conversation.turn}
+              presentedProgress={conversationProgress}
               agents={agents}
               onStopReady={registerConversationStop}
               // The bar is the conversation's: back to the main screen, the profile, share and
@@ -221,7 +236,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
           </BottomSheet>
         ) : null}
         <AvatarFlightLayer flights={flights} />
-      </>
+      </AgentAvatarProvider>
     );
   },
 );