@robono/messaging-react-native 0.0.0-stage → 0.1.0

package/app.plugin.cjs

@@ -0,0 +1,5 @@
+const {withDangerousMod,createRunOncePlugin} = require('expo/config-plugins');
+module.exports=createRunOncePlugin(config=>withDangerousMod(config,['ios',async value=>{
+  require('./plugin/preserve-call-audio.cjs').install(value.modRequest.projectRoot);
+  return value;
+}]),'@robono/messaging-react-native',require('./package.json').version);

package/dist/call-message.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+/** A new, reviewed message after no answer. Never records or sends a call automatically. */
+export declare function UnansweredCallMessage({ callId, onDismiss }: {
+    callId: string;
+    onDismiss: () => void;
+}): React.JSX.Element | null;

package/dist/call-message.js

@@ -0,0 +1,109 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Pressable, Text, View } from 'react-native';
+import { useMessagingUI } from './index.js';
+/** A new, reviewed message after no answer. Never records or sends a call automatically. */
+export function UnansweredCallMessage({ callId, onDismiss }) {
+    const { client, design, state, pickAttachment, releaseAttachment, components } = useMessagingUI();
+    const [option, setOption] = useState(null);
+    const [draft, setDraft] = useState(null);
+    const [busy, setBusy] = useState(false), [error, setError] = useState(''), [attempt, setAttempt] = useState(0);
+    const generation = useRef(0), inFlight = useRef(false), prepared = useRef(null);
+    const release = useRef(releaseAttachment);
+    release.current = releaseAttachment;
+    function clearDraft() {
+        const media = prepared.current;
+        prepared.current = null;
+        setDraft(null);
+        if (media)
+            void release.current?.(media);
+    }
+    useEffect(() => {
+        const id = ++generation.current;
+        clearDraft();
+        setOption(null);
+        setError('');
+        setBusy(false);
+        void client.unansweredCall(callId).then(o => { if (id === generation.current)
+            setOption(o); })
+            .catch(() => { if (id === generation.current)
+            setError('Could not check message availability.'); });
+        return () => { generation.current++; const media = prepared.current; prepared.current = null; if (media)
+            void release.current?.(media); };
+    }, [client, callId, state.conversationId, attempt]);
+    async function record() {
+        if (inFlight.current || !option || !pickAttachment)
+            return;
+        const id = generation.current, conversation = state.conversationId;
+        inFlight.current = true;
+        setBusy(true);
+        setError('');
+        try {
+            const current = await client.unansweredCall(callId);
+            if (id !== generation.current)
+                return;
+            if (!current || current.kind !== option.kind) {
+                clearDraft();
+                setOption(current);
+                return;
+            }
+            const media = await pickAttachment(current.kind, { maxDurationMs: current.maxDurationMs, ...(current.kind === 'video' ? { source: 'call-video' } : {}), intent: 'attach' });
+            if (!media)
+                return;
+            if (id !== generation.current || client.getSnapshot().conversationId !== conversation) {
+                void release.current?.(media);
+                return;
+            }
+            clearDraft();
+            prepared.current = media;
+            setDraft({ kind: current.kind, media });
+        }
+        catch {
+            if (id === generation.current)
+                setError('Could not prepare your message. Try again.');
+        }
+        finally {
+            inFlight.current = false;
+            if (id === generation.current)
+                setBusy(false);
+        }
+    }
+    async function send() {
+        if (inFlight.current || !draft)
+            return;
+        inFlight.current = true;
+        setBusy(true);
+        setError('');
+        const id = generation.current;
+        try {
+            const current = await client.unansweredCall(callId);
+            if (id !== generation.current)
+                return;
+            if (!current || current.kind !== draft.kind) {
+                clearDraft();
+                setOption(current);
+                return;
+            }
+            // The client now owns the stable retry identity. Unmounting only releases
+            // local preview resources, never the uploaded asset needed by a retry.
+            const work = client.send({ kind: draft.kind, media: draft.media, unansweredCallId: callId });
+            clearDraft();
+            onDismiss();
+            await work;
+        }
+        catch {
+            if (id === generation.current)
+                setError('The message could not be sent. Check the conversation for a retry.');
+        }
+        finally {
+            inFlight.current = false;
+            if (id === generation.current)
+                setBusy(false);
+        }
+    }
+    if (!pickAttachment || !state.settings?.enabled || state.conversation?.canSend === false || (!option && !error))
+        return null;
+    const c = design.colors, VoiceAttachment = components?.VoiceAttachment;
+    const action = (label, onPress) => _jsx(Pressable, { accessibilityRole: "button", disabled: busy, onPress: onPress, style: { paddingVertical: 12, paddingHorizontal: 4, minHeight: 44 }, children: _jsx(Text, { style: { color: c.incomingText, fontWeight: '600' }, children: label }) });
+    return _jsxs(View, { style: { backgroundColor: c.incoming, padding: 16, borderTopWidth: 1, borderTopColor: c.secondary + '30', gap: 6 }, children: [_jsx(Text, { style: { color: c.incomingText, fontSize: 16, fontWeight: '600' }, children: "No answer" }), option && _jsx(Text, { style: { color: c.incomingText, fontSize: 14 }, children: draft ? 'Review your message, then send it.' : `Leave a ${option.kind === 'voice' ? 'voice' : 'video'} message in this chat.` }), draft && _jsx(View, { children: draft.kind === 'voice' && VoiceAttachment ? _jsx(VoiceAttachment, { media: draft.media, appearance: design, disabled: busy, onRemove: clearDraft }) : _jsxs(Text, { style: { color: c.incomingText }, children: [draft.kind === 'voice' ? 'Voice' : 'Video', " message ready"] }) }), _jsxs(View, { style: { flexDirection: 'row', gap: 16, flexWrap: 'wrap' }, children: [option && (draft ? action('Send message', () => void send()) : action(`Record ${option.kind === 'voice' ? 'voice' : 'video'} message`, () => void record())), !option && error && action('Try again', () => setAttempt(value => value + 1)), action('Not now', () => { clearDraft(); onDismiss(); })] }), !!error && _jsx(Text, { accessibilityRole: "alert", style: { color: c.incomingText }, children: error })] });
+}

package/dist/calling.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import { type MessagingScreenProps } from './index.js';
+export { UnansweredCallMessage } from './call-message.js';
+/** Optional call entry in the standard message header. The host controls eligibility and admission. */
+export declare function MessagingCallHeader(): React.JSX.Element;
+export interface MessagingCallingScreenProps extends MessagingScreenProps {
+    /** Supply only when this contact is eligible. Never bypass server-side permissions. */
+    onCall?: () => void;
+    callLabel?: string;
+    onVideoCall?: () => void;
+    videoCallLabel?: string;
+    unansweredCallId?: string;
+    onDismissCallMessage?: () => void;
+}
+export declare function MessagingCallingScreen({ onCall, onVideoCall, videoCallLabel, callLabel, components, unansweredCallId, onDismissCallMessage, ...props }: MessagingCallingScreenProps): React.JSX.Element;

package/dist/calling.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useSyncExternalStore } from 'react';
+import { Pressable, View, Text } from 'react-native';
+import { RobonoIcon } from './visual/RobonoIcon.js';
+import { MessagingScreen, MessagingProvider, MessagingHeader, MessagingComposer, useMessagingUI } from './index.js';
+import { UnansweredCallMessage } from './call-message.js';
+export { UnansweredCallMessage } from './call-message.js';
+const Action = createContext(null);
+const FollowUp = createContext(null);
+function CallingMessageComposer() { const follow = useContext(FollowUp); return _jsxs(_Fragment, { children: [follow && _jsx(UnansweredCallMessage, { callId: follow.callId, onDismiss: follow.dismiss }), _jsx(MessagingComposer, {})] }); }
+/** Optional call entry in the standard message header. The host controls eligibility and admission. */
+export function MessagingCallHeader() {
+    const action = useContext(Action), { design, state } = useMessagingUI();
+    const allowed = state.conversation?.canSend !== false;
+    return _jsxs(MessagingHeader, { children: [allowed && action?.onCall && _jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: action.label, onPress: action.onCall, style: { minWidth: 44, minHeight: 44, alignItems: 'center', justifyContent: 'center' }, children: _jsx(RobonoIcon, { name: "phone", size: 24, color: design.colors.foreground }) }), allowed && action?.onVideoCall && _jsx(Pressable, { accessibilityRole: "button", accessibilityLabel: action.videoLabel, onPress: action.onVideoCall, style: { minWidth: 44, minHeight: 44, alignItems: 'center', justifyContent: 'center' }, children: _jsx(RobonoIcon, { name: "video", size: 24, color: design.colors.foreground }) })] });
+}
+export function MessagingCallingScreen({ onCall, onVideoCall, videoCallLabel = 'Video call', callLabel = 'Voice call', components, unansweredCallId, onDismissCallMessage, ...props }) {
+    const state = useSyncExternalStore(props.client.subscribe, props.client.getSnapshot, props.client.getSnapshot);
+    const design = props.appearance ?? state.settings?.appearance;
+    const callingOnly = (onCall || onVideoCall) && design && state.settings && !state.settings.enabled;
+    return _jsx(Action.Provider, { value: onCall || onVideoCall ? { onCall, onVideoCall, label: callLabel, videoLabel: videoCallLabel } : null, children: _jsx(FollowUp.Provider, { value: unansweredCallId && onDismissCallMessage ? { callId: unansweredCallId, dismiss: onDismissCallMessage } : null, children: callingOnly ? _jsx(MessagingProvider, { ...props, children: _jsxs(View, { style: [{ flex: 1, backgroundColor: design.colors.background }, props.style], children: [_jsx(MessagingCallHeader, {}), _jsxs(View, { style: { flex: 1, alignItems: 'center', justifyContent: 'center', gap: 24, padding: 24 }, children: [_jsx(Text, { style: { fontSize: 28, fontWeight: '600', color: design.colors.foreground }, children: props.contact.name }), onCall && _jsxs(Pressable, { accessibilityRole: "button", accessibilityLabel: `Start ${callLabel.toLowerCase()}`, onPress: onCall, style: { minHeight: 56, minWidth: 160, borderRadius: 28, backgroundColor: design.colors.incoming, alignItems: 'center', justifyContent: 'center', padding: 16, flexDirection: 'row', gap: 12 }, children: [_jsx(RobonoIcon, { name: "phone", size: 24, color: design.colors.incomingText }), _jsx(Text, { style: { fontSize: 18, color: design.colors.incomingText }, children: callLabel })] }), onVideoCall && _jsxs(Pressable, { accessibilityRole: "button", accessibilityLabel: `Start ${videoCallLabel.toLowerCase()}`, onPress: onVideoCall, style: { minHeight: 56, padding: 16, borderRadius: 28, backgroundColor: design.colors.incoming, flexDirection: 'row', alignItems: 'center', gap: 12 }, children: [_jsx(RobonoIcon, { name: "video", size: 24, color: design.colors.incomingText }), _jsx(Text, { style: { color: design.colors.incomingText, fontSize: 18 }, children: videoCallLabel })] })] })] }) }) : _jsx(MessagingScreen, { ...props, components: { Header: MessagingCallHeader, Composer: CallingMessageComposer, ...components } }) }) });
+}

package/dist/expo-calling.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { type ExpoMessagingScreenProps } from './expo.js';
+import { type MessagingCallingScreenProps } from './calling.js';
+export type ExpoMessagingCallingScreenProps = Omit<ExpoMessagingScreenProps, 'renderConversation'> & Pick<MessagingCallingScreenProps, 'onCall' | 'callLabel' | 'onVideoCall' | 'videoCallLabel' | 'unansweredCallId' | 'onDismissCallMessage'>;
+/** Optional composition of the shared conversation, calling entry and native recording/review tools. */
+export declare function ExpoMessagingCallingScreen({ onCall, callLabel, onVideoCall, videoCallLabel, unansweredCallId, onDismissCallMessage, ...props }: ExpoMessagingCallingScreenProps): React.JSX.Element;

package/dist/expo-calling.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ExpoMessagingScreen } from './expo.js';
+import { MessagingCallingScreen } from './calling.js';
+/** Optional composition of the shared conversation, calling entry and native recording/review tools. */
+export function ExpoMessagingCallingScreen({ onCall, callLabel, onVideoCall, videoCallLabel, unansweredCallId, onDismissCallMessage, ...props }) {
+    return _jsx(ExpoMessagingScreen, { ...props, renderConversation: screen => _jsx(MessagingCallingScreen, { ...screen, onCall: onCall, callLabel: callLabel, onVideoCall: onVideoCall, videoCallLabel: videoCallLabel, unansweredCallId: unansweredCallId, onDismissCallMessage: onDismissCallMessage }) });
+}

package/dist/expo-media.d.ts

@@ -0,0 +1,19 @@
+import { type AudioMode } from 'expo-audio';
+import type { LocalMessagingMedia, MessagingMediaDevice, MessagingMediaStorage } from './media-controller.js';
+export interface MessagingAudioSession {
+    isAvailable?: (purpose?: 'recording' | 'playback') => boolean;
+    acquire(purpose: 'recording' | 'playback'): Promise<() => Promise<void>>;
+}
+/** Pass your app's call-state guard and restore mode, or supply your existing audio-session coordinator. */
+export declare function createExpoMessagingAudioSession(options?: {
+    isCallActive?: () => boolean;
+    restoreMode?: Partial<AudioMode>;
+}): MessagingAudioSession;
+export declare function copyMessagingCache(file: LocalMessagingMedia): Promise<LocalMessagingMedia>;
+export declare function createExpoMessagingDevice(audio: MessagingAudioSession): MessagingMediaDevice;
+/** Private-storage transport. The endpoint is YOUR authenticated backend, never a Robono API key on the phone. */
+export declare function createExpoMessagingStorage(options: {
+    url: string;
+    getAccessToken: () => Promise<string>;
+    streaming?: boolean;
+}): MessagingMediaStorage;

package/dist/expo-media.js

@@ -0,0 +1,388 @@
+import { AudioModule, RecordingPresets, createAudioPlayer, setAudioModeAsync } from 'expo-audio';
+import * as Picker from 'expo-image-picker';
+import * as Documents from 'expo-document-picker';
+import * as FS from 'expo-file-system/legacy';
+import * as Crypto from 'expo-crypto';
+import { defaultAttachmentLimits } from '@robono/messaging';
+let audioOwner = false;
+/** Pass your app's call-state guard and restore mode, or supply your existing audio-session coordinator. */
+export function createExpoMessagingAudioSession(options = {}) {
+    return { isAvailable: (purpose = 'playback') => purpose === 'playback' || !options.isCallActive?.(), async acquire(purpose) {
+            if (audioOwner)
+                throw Error('Finish the current recording first.');
+            if (purpose === 'recording' && options.isCallActive?.())
+                throw Error('Finish the current call before recording.');
+            audioOwner = true;
+            // The call owns its microphone, mode and output route. A playback lease
+            // borrows that session without changing any of them. Outside our call,
+            // mix rather than requesting exclusive focus from another calling app.
+            const borrowed = purpose === 'playback' && !!options.isCallActive?.();
+            try {
+                if (!borrowed)
+                    await setAudioModeAsync({ allowsRecording: purpose === 'recording', playsInSilentMode: true, shouldPlayInBackground: false, shouldRouteThroughEarpiece: false, interruptionMode: purpose === 'recording' ? 'doNotMix' : 'mixWithOthers' });
+            }
+            catch (e) {
+                audioOwner = false;
+                throw e;
+            }
+            let released = false;
+            return async () => {
+                if (released)
+                    return;
+                released = true;
+                try {
+                    if (!borrowed && !options.isCallActive?.())
+                        await setAudioModeAsync(options.restoreMode ?? { allowsRecording: false, playsInSilentMode: true, shouldPlayInBackground: false, shouldRouteThroughEarpiece: false, interruptionMode: 'mixWithOthers' });
+                }
+                finally {
+                    audioOwner = false;
+                }
+            };
+        } };
+}
+function check(signal) { if (signal.aborted)
+    throw Error('Cancelled.'); }
+const cacheRoot = () => { if (!FS.cacheDirectory)
+    throw Error('Private device storage is unavailable.'); return FS.cacheDirectory + 'robono-messaging/'; };
+const ownedDirectories = new Set();
+async function cacheDirectory() { const dir = cacheRoot() + Crypto.randomUUID() + '/'; await FS.makeDirectoryAsync(dir, { intermediates: true }); ownedDirectories.add(dir); return dir; }
+const cacheName = (name) => name.replace(/[^a-zA-Z0-9._-]/g, '_').slice(-90) || 'Attachment';
+async function cachePath(name) { return (await cacheDirectory()) + cacheName(name); }
+async function removeUri(uri) {
+    if (!uri.startsWith(cacheRoot()))
+        return;
+    const dir = uri.slice(0, uri.lastIndexOf('/') + 1);
+    // Each owned directory contains exactly one private copy. Remove it in one
+    // native operation rather than making the next open wait for two deletions.
+    if (ownedDirectories.has(dir)) {
+        await FS.deleteAsync(dir, { idempotent: true });
+        ownedDirectories.delete(dir);
+    }
+    else
+        await FS.deleteAsync(uri, { idempotent: true });
+}
+async function remove(file) { await removeUri(file.uri); }
+async function pickedCopy(uri, fileName, mimeType, durationMs) {
+    try {
+        return await copied(uri, fileName, mimeType, durationMs);
+    }
+    finally {
+        if (FS.cacheDirectory && uri.startsWith(FS.cacheDirectory))
+            await FS.deleteAsync(uri, { idempotent: true }).catch(() => { });
+    }
+}
+export async function copyMessagingCache(file) { return copied(file.uri, file.fileName, file.mimeType, file.durationMs); }
+async function copied(uri, fileName, mimeType, durationMs) {
+    const target = await cachePath(fileName);
+    try {
+        await FS.copyAsync({ from: uri, to: target });
+        const info = await FS.getInfoAsync(target);
+        if (!info.exists || info.isDirectory)
+            throw Error('The file could not be read.');
+        return { uri: target, fileName, mimeType, byteSize: info.size, ...(durationMs === undefined ? {} : { durationMs: Math.ceil(durationMs) }) };
+    }
+    catch (e) {
+        await removeUri(target).catch(() => { });
+        throw e;
+    }
+}
+async function recordingDuration(uri) {
+    // Android resets recorder status to zero after automatic stop. Read the finished file.
+    const player = createAudioPlayer(uri);
+    try {
+        const deadline = Date.now() + 5000;
+        while (!player.isLoaded && Date.now() < deadline)
+            await new Promise(r => setTimeout(r, 40));
+        const ms = Math.ceil(player.duration * 1000);
+        if (!player.isLoaded || !Number.isFinite(ms) || ms < 1)
+            throw Error('The recording length could not be read. Record again.');
+        return ms;
+    }
+    finally {
+        player.remove();
+    }
+}
+const extensionMimes = { jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', gif: 'image/gif', webp: 'image/webp', heic: 'image/heic', heif: 'image/heif', avif: 'image/avif', mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm', '3gp': 'video/3gpp', pdf: 'application/pdf', txt: 'text/plain', csv: 'text/csv', zip: 'application/zip', doc: 'application/msword', docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', xls: 'application/vnd.ms-excel', xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', ppt: 'application/vnd.ms-powerpoint', pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation' };
+function mime(value, name) { return value?.toLowerCase() || extensionMimes[name.split('.').at(-1)?.toLowerCase() ?? ''] || 'application/octet-stream'; }
+export function createExpoMessagingDevice(audio) {
+    let recorder = null, release = null;
+    let recordingDeadline = 0;
+    let starting = null;
+    let stopping = null;
+    return {
+        async pick(kind, settings, signal, source) {
+            if (source === 'camera' && (!['image', 'video'].includes(kind) || !settings.appearance.showCamera))
+                throw Error('Camera capture is unavailable.');
+            if (source === 'call-video' && (kind !== 'video' || !settings.enabled || !settings.features.video || settings.unansweredCalls?.video !== 'video'))
+                throw Error('Video messages after a call are unavailable.');
+            const limits = (settings.attachments ?? defaultAttachmentLimits())[kind];
+            if (kind === 'document') {
+                const result = await Documents.getDocumentAsync({ type: limits.allowedMimeTypes, multiple: false, copyToCacheDirectory: true });
+                if (signal.aborted) {
+                    for (const a of result.assets ?? [])
+                        if (FS.cacheDirectory && a.uri.startsWith(FS.cacheDirectory))
+                            await FS.deleteAsync(a.uri, { idempotent: true }).catch(() => { });
+                    check(signal);
+                }
+                if (result.canceled)
+                    return null;
+                const asset = result.assets[0];
+                if (!asset)
+                    return null;
+                return pickedCopy(asset.uri, asset.name, mime(asset.mimeType, asset.name));
+            }
+            if ((source === 'camera' || source === 'call-video')) {
+                const permission = await Picker.requestCameraPermissionsAsync();
+                check(signal);
+                if (!permission.granted)
+                    throw Error('Camera permission is needed to take photos or record videos.');
+            }
+            const result = await ((source === 'camera' || source === 'call-video') ? Picker.launchCameraAsync : Picker.launchImageLibraryAsync)({ mediaTypes: source === 'call-video' ? ['videos'] : (source === 'camera' || source === 'call-video') ? ([...((settings.features?.image ?? kind === 'image') ? ['images'] : []), ...(settings.features?.video ? ['videos'] : [])]) : kind === 'image' ? ['images'] : ['videos'], ...((source === 'camera' || source === 'call-video') ? { videoMaxDuration: settings.attachments?.video?.maxDurationSeconds ?? 60 } : {}), allowsMultipleSelection: false, allowsEditing: false, quality: 1, preferredAssetRepresentationMode: Picker.UIImagePickerPreferredAssetRepresentationMode.Current });
+            if (signal.aborted) {
+                for (const a of result.assets ?? [])
+                    if (FS.cacheDirectory && a.uri.startsWith(FS.cacheDirectory))
+                        await FS.deleteAsync(a.uri, { idempotent: true }).catch(() => { });
+                check(signal);
+            }
+            if (result.canceled)
+                return null;
+            const asset = result.assets[0];
+            if (!asset)
+                return null;
+            const video = (source === 'camera' || source === 'call-video') ? (asset.type === 'video' || asset.mimeType?.startsWith('video/')) : kind === 'video';
+            const name = asset.fileName ?? asset.uri.split('/').at(-1) ?? (kind === 'image' ? 'Photo' : 'Video');
+            if (video && (!asset.duration || !Number.isFinite(asset.duration))) {
+                if (FS.cacheDirectory && asset.uri.startsWith(FS.cacheDirectory))
+                    await FS.deleteAsync(asset.uri, { idempotent: true }).catch(() => { });
+                throw Error('The video length could not be read. Choose another video.');
+            }
+            return pickedCopy(asset.uri, name, mime(asset.mimeType, name), video ? asset.duration : undefined);
+        },
+        async startRecording(maximum, signal) {
+            if (starting || recorder)
+                throw Error('A recording is already in progress.');
+            const work = (async () => {
+                const permission = await AudioModule.requestRecordingPermissionsAsync();
+                check(signal);
+                if (!permission.granted)
+                    throw Error('Microphone permission is needed to record a voice message.');
+                release = await audio.acquire('recording');
+                try {
+                    check(signal);
+                    recorder = new AudioModule.AudioRecorder({ ...RecordingPresets.HIGH_QUALITY, isMeteringEnabled: true });
+                    await recorder.prepareToRecordAsync({ ...RecordingPresets.HIGH_QUALITY, isMeteringEnabled: true });
+                    check(signal); // Leave room for AAC encoder/container padding; the backend checks final file duration.
+                    const captureMs = Math.max(100, maximum - 100);
+                    recorder.record({ forDuration: captureMs / 1000 });
+                    recordingDeadline = Date.now() + captureMs;
+                }
+                catch (e) {
+                    if (recorder) {
+                        await recorder.stop().catch(() => { });
+                        const uri = recorder.uri;
+                        recorder.release();
+                        recorder = null;
+                        if (uri?.startsWith(FS.cacheDirectory ?? 'file://unavailable/'))
+                            await FS.deleteAsync(uri, { idempotent: true }).catch(() => { });
+                    }
+                    await release?.();
+                    release = null;
+                    throw e;
+                }
+            })();
+            starting = work;
+            try {
+                await work;
+            }
+            finally {
+                if (starting === work)
+                    starting = null;
+            }
+        },
+        recordingStatus() { const state = recorder?.getStatus(); return { durationMs: state?.durationMillis ?? 0, level: typeof state?.metering === 'number' ? Math.pow(10, state.metering / 40) : undefined, recording: !!state?.isRecording && audio.isAvailable?.('recording') !== false, limitReached: !state?.isRecording && Date.now() >= recordingDeadline }; },
+        async stopRecording() {
+            if (stopping)
+                return stopping;
+            const work = (async () => {
+                if (starting)
+                    await starting.catch(() => { });
+                const current = recorder;
+                recorder = null;
+                if (!current)
+                    return null;
+                let original = null;
+                try {
+                    const before = current.getStatus();
+                    if (before.isRecording)
+                        await current.stop();
+                    original = current.uri;
+                    if (!original)
+                        return null;
+                    const duration = await recordingDuration(original);
+                    return await copied(original, 'Voice message.m4a', 'audio/mp4', duration);
+                }
+                finally {
+                    current.release();
+                    if (original?.startsWith(FS.cacheDirectory ?? 'file://unavailable/'))
+                        await FS.deleteAsync(original, { idempotent: true }).catch(() => { });
+                    await release?.();
+                    release = null;
+                }
+            })();
+            stopping = work;
+            try {
+                return await work;
+            }
+            finally {
+                if (stopping === work)
+                    stopping = null;
+            }
+        }, remove,
+    };
+}
+function https(value) { const url = new URL(value); if (url.protocol !== 'https:' || url.username || url.password)
+    throw Error('A secure media URL is required.'); return url.href; }
+/** Private-storage transport. The endpoint is YOUR authenticated backend, never a Robono API key on the phone. */
+export function createExpoMessagingStorage(options) {
+    const endpoint = https(options.url);
+    async function request(operation, input, signal) {
+        const token = await options.getAccessToken();
+        if (!token)
+            throw Error('Sign in to continue.');
+        const bounded = new AbortController();
+        const cancel = () => bounded.abort();
+        signal?.addEventListener('abort', cancel, { once: true });
+        if (signal?.aborted)
+            bounded.abort();
+        const timeout = setTimeout(cancel, operation === 'complete' ? 120000 : 15000);
+        try {
+            const response = await fetch(endpoint, { method: 'POST', redirect: 'error', signal: bounded.signal, headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify({ ...input, operation }) });
+            const result = await response.json();
+            if (!response.ok) {
+                const error = Object.assign(Error(result?.error?.message ?? 'The file could not be transferred. Try again.'), { status: response.status });
+                throw error;
+            }
+            return result;
+        }
+        finally {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', cancel);
+        }
+    }
+    async function playbackPlan(message, signal) {
+        check(signal);
+        if (message.deleted)
+            throw Error('This attachment is no longer available.');
+        const grant = message.attachmentDownload;
+        const granted = grant && grant.messageId === message.id && grant.conversationId === message.conversationId && grant.assetId === message.media?.assetId && Number.isFinite(grant.expiresAt) && grant.expiresAt > Date.now() + 5000 && grant.expiresAt <= Date.now() + 60000;
+        const plan = granted ? { url: grant.url, media: message.media, headers: undefined } : await request('download', { conversationId: message.conversationId, messageId: message.id }, signal);
+        check(signal);
+        const media = plan.media;
+        if (!media || media.assetId !== message.media?.assetId || !Number.isSafeInteger(media.byteSize) || media.byteSize < 1 || media.byteSize > 104857600)
+            throw Error('Invalid attachment size or identity.');
+        return { ...plan, url: https(plan.url), media };
+    }
+    async function cancellable(task, context, run) {
+        check(context.signal);
+        const cancel = () => { void task.cancelAsync().catch(() => { }); };
+        context.signal.addEventListener('abort', cancel, { once: true });
+        try {
+            const result = await run();
+            check(context.signal);
+            return result;
+        }
+        finally {
+            context.signal.removeEventListener('abort', cancel);
+        }
+    }
+    return {
+        async stream(message, context) {
+            check(context.signal);
+            if (message.deleted)
+                throw Error('This attachment is no longer available.');
+            if (options.streaming === false || !['voice', 'video'].includes(message.kind) || !message.media?.assetId.startsWith('robono-r2:'))
+                return null;
+            const plan = await playbackPlan(message, context.signal);
+            // The native player requests byte ranges directly from the same private,
+            // metered gateway. No file copy or thumbnail precedes playback.
+            const { assetId, ...media } = plan.media;
+            return { ...media, uri: plan.url, stream: { headers: plan.headers } };
+        },
+        async upload(file, context) {
+            const { uri, ...metadata } = file;
+            const plan = await request('prepare', { uploadId: context.uploadId, conversationId: context.conversationId, kind: context.kind, file: metadata }, context.signal);
+            check(context.signal);
+            if (plan.media)
+                return plan.media;
+            const task = FS.createUploadTask(https(plan.url), uri, { httpMethod: 'PUT', uploadType: FS.FileSystemUploadType.BINARY_CONTENT, headers: plan.headers ?? {}, sessionType: FS.FileSystemSessionType.FOREGROUND }, p => context.onProgress(p.totalBytesExpectedToSend > 0 ? p.totalBytesSent / p.totalBytesExpectedToSend : 0));
+            const result = await cancellable(task, context, () => task.uploadAsync());
+            // An immutable PUT may already have succeeded before its response was lost.
+            // A 412 is not success by itself: complete still verifies ownership and bytes.
+            if (!result || result.status !== 412 && (result.status < 200 || result.status >= 300))
+                throw Error('Upload failed. Try again.');
+            // Verification is repeatable for the same upload. A transient inspector
+            // failure must not upload the bytes again or create a second attachment.
+            for (let attempt = 0;; attempt++) {
+                check(context.signal);
+                try {
+                    const complete = await request('complete', { uploadId: context.uploadId, conversationId: context.conversationId }, context.signal);
+                    return complete.media;
+                }
+                catch (error) {
+                    if (attempt >= 2 || ![502, 503, 504].includes(error.status ?? 0))
+                        throw error;
+                    check(context.signal);
+                    await new Promise((resolve, reject) => {
+                        const cancel = () => { clearTimeout(timer); context.signal.removeEventListener('abort', cancel); reject(Error('Cancelled')); };
+                        const timer = setTimeout(() => { context.signal.removeEventListener('abort', cancel); resolve(); }, 1000 * (attempt + 1));
+                        context.signal.addEventListener('abort', cancel, { once: true });
+                        if (context.signal.aborted)
+                            cancel();
+                    });
+                }
+            }
+        },
+        async download(message, context) {
+            check(context.signal);
+            if (message.deleted)
+                throw Error('This attachment is no longer available.');
+            // Local directory preparation needs no media access. Run it alongside
+            // authorization, but never start the transfer until both have succeeded.
+            const [authorized, prepared] = await Promise.allSettled([
+                playbackPlan(message, context.signal),
+                cacheDirectory(),
+            ]);
+            const dir = prepared.status === 'fulfilled' ? prepared.value : null;
+            let path = null;
+            try {
+                if (authorized.status === 'rejected')
+                    throw authorized.reason;
+                if (prepared.status === 'rejected')
+                    throw prepared.reason;
+                check(context.signal);
+                const plan = authorized.value, media = plan.media;
+                if (!media || !Number.isSafeInteger(media.byteSize) || media.byteSize < 1 || media.byteSize > 104857600)
+                    throw Error('Invalid attachment size.');
+                path = prepared.value + cacheName(media.fileName);
+                const task = FS.createDownloadResumable(https(plan.url), path, { headers: plan.headers ?? {}, sessionType: FS.FileSystemSessionType.FOREGROUND }, p => {
+                    if (p.totalBytesWritten > media.byteSize)
+                        void task.cancelAsync().catch(() => { });
+                    context.onProgress(p.totalBytesWritten / media.byteSize);
+                });
+                const result = await cancellable(task, context, () => task.downloadAsync());
+                if (!result || result.status !== 200)
+                    throw Error('Download failed. Try again.');
+                const info = await FS.getInfoAsync(path);
+                if (!info.exists || info.isDirectory || info.size !== media.byteSize)
+                    throw Error('The attachment could not be verified.');
+                return { uri: path, mimeType: media.mimeType, fileName: media.fileName, byteSize: media.byteSize, ...(media.durationMs ? { durationMs: media.durationMs } : {}) };
+            }
+            catch (e) {
+                if (dir)
+                    await removeUri(path ?? dir + 'Attachment').catch(() => { });
+                throw e;
+            }
+        },
+        async discard(uploadId) { await request('discard', { uploadId }); },
+    };
+}

package/dist/expo.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+import { type MessagingAppearance } from '@robono/messaging';
+import { type MessagingScreenProps } from './index.js';
+import { MessagingMediaController, type LocalMessagingMedia, type MessagingMediaStorage } from './media-controller.js';
+import { type MediaReadyStage } from './media-readiness.js';
+import { type MessagingAudioSession } from './expo-media.js';
+export { createExpoMessagingAudioSession, createExpoMessagingDevice, createExpoMessagingStorage } from './expo-media.js';
+export type { MessagingAudioSession } from './expo-media.js';
+export type { LocalMessagingMedia, MessagingMediaStorage, MediaTransferOptions } from './media-controller.js';
+export { MessagingMediaController } from './media-controller.js';
+export declare function MessagingMediaOverlay({ controller, audio, appearance, inlineVoice, inlineRecorder }: {
+    controller: MessagingMediaController;
+    audio: MessagingAudioSession;
+    appearance: MessagingAppearance;
+    inlineVoice?: boolean;
+    inlineRecorder?: boolean;
+}): React.JSX.Element | null;
+export interface ExpoMessagingScreenProps extends Omit<MessagingScreenProps, 'pickAttachment' | 'openAttachment'> {
+    storage: MessagingMediaStorage;
+    audioSession: MessagingAudioSession;
+    /** Optional timing callback from native image/frame/playback readiness, measured from opening. */
+    onMediaReady?: (event: {
+        messageId: string;
+        kind: string;
+        stage: MediaReadyStage;
+        elapsedMs: number;
+    }) => void;
+    /** Preload a bounded set of small recent attachments while this conversation is open. Default true. */
+    preloadRecentMedia?: boolean;
+    /** Compose a conversation with the supplied media adapters. */
+    renderConversation?: (props: MessagingScreenProps) => React.ReactNode;
+    /** Resolve an authorized recent attachment to an adapter-owned cache copy, never a library original. */
+    resolveAttachmentChoice?: (id: string, signal: AbortSignal) => Promise<LocalMessagingMedia | null>;
+}
+/** Optional ready-made recording, preview, upload and download tools for both mobile platforms. */
+export declare function ExpoMessagingScreen({ storage, audioSession, renderConversation, preloadRecentMedia, ...props }: ExpoMessagingScreenProps): React.JSX.Element;