@experiaapp/webchat-react-native 2.0.1

package/lib/adapters/expoDefaults.js

@@ -0,0 +1,539 @@
+"use strict";
+// src/adapters/expoDefaults.ts
+//
+// BATTERIES-INCLUDED default adapters. These let `<WebChat config={...} />` work
+// with ZERO host adapter code: when the matching Expo peer is installed they
+// auto-wire image/document picking, file->base64 reads, and audio record/play;
+// when the peer is ABSENT each factory returns `undefined` so the existing
+// feature-detect/`?? ` gating degrades gracefully (attach row hidden, recorder
+// suppressed, throwing-reader fallback) exactly as if no prop were passed.
+//
+// Every Expo lib is an OPTIONAL peer (see package.json peerDependenciesMeta) and
+// is required LAZILY (inside a factory, never at module top-level) behind a
+// try/catch — mirroring src/ui/Icon.tsx loadSvg() / src/adapters/webrtc.ts.
+//
+// CRITICAL: the require MUST use a STATIC LITERAL string — `require("expo-font")`,
+// via `safeRequire(() => require("expo-font"), …)` — NOT a dynamic
+// `require(variable)`. Metro only bundles static requires; a dynamic require throws
+// "Dynamic require … not supported by Metro" AT RUNTIME (node/jest tolerate it, so
+// unit tests won't catch it) and silently disables every adapter on-device. Because
+// these are static, Metro bundles the named packages: a batteries-included build
+// must have the Expo peers installed (the example + README do). At runtime a missing
+// NATIVE module is caught here -> the factory returns undefined and the feature
+// degrades gracefully (button hidden / system font / link fallback).
+//
+// Note (bare React Native, no Expo prebuild): these Expo modules require the
+// `expo-modules-core` runtime. In an Expo-managed/dev-client app that is already
+// present; in a bare RN app the consumer must run `npx install-expo-modules`
+// once so the autolinked native side exists. See README / package.json comment.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpoPicker = createExpoPicker;
+exports.createExpoReadBase64 = createExpoReadBase64;
+exports.createExpoFontLoader = createExpoFontLoader;
+exports.createExpoAudioAdapter = createExpoAudioAdapter;
+/**
+ * Best-effort lazy require of an optional Expo peer. Returns `undefined` when the
+ * module is not installed (or fails to resolve) so callers feature-detect on the
+ * shape rather than crashing on a missing dependency. Mirrors Icon.tsx loadSvg().
+ */
+function safeRequire(load, label) {
+    var _a;
+    try {
+        // `load` MUST contain a STATIC literal require, e.g. () => require("expo-font").
+        // Metro only bundles static requires — a dynamic `require(variable)` throws
+        // "Dynamic require … not supported by Metro" at runtime, which is what silently
+        // disabled EVERY default adapter on-device (node/jest tolerate dynamic require,
+        // so the unit tests never caught it).
+        return load();
+    }
+    catch (e) {
+        // DEV diagnostic: surface WHY an optional peer didn't resolve (native module
+        // missing from the running build, or package not installed). Silent in release.
+        adapterLog(`require("${label}") FAILED — ${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}`);
+        return undefined;
+    }
+}
+/** DEV-only adapter-resolution diagnostic (prints to Metro; silent in release). */
+function adapterLog(...args) {
+    if (globalThis.__DEV__ === true) {
+        // eslint-disable-next-line no-console
+        console.log("[webchat adapters]", ...args);
+    }
+}
+// ---------------------------------------------------------------------------
+// Picker (expo-image-picker + expo-document-picker) -> PickerAdapter
+// ---------------------------------------------------------------------------
+/** jpg|png|heic|… inferred from a URI/name tail, lower-cased, query-stripped. */
+function extOf(s) {
+    const clean = s.split("?")[0];
+    const dot = clean.lastIndexOf(".");
+    return dot >= 0 ? clean.slice(dot + 1).toLowerCase() : "";
+}
+/** Infer an image/video mime from a file extension, defaulting to image/jpeg. */
+function imageMimeFromExt(ext) {
+    if (ext === "png")
+        return "image/png";
+    if (ext === "heic" || ext === "heif")
+        return "image/heic";
+    if (ext === "mp4")
+        return "video/mp4";
+    if (ext === "m4v")
+        return "video/x-m4v";
+    return "image/jpeg";
+}
+/**
+ * Normalize one `expo-image-picker` asset to the SDK {@link Asset}.
+ *
+ * expo-image-picker field -> SDK Asset:
+ *   uri      -> uri
+ *   fileName -> name   (synthesized `image_<ts>.<ext>` when null — common on Android/camera-roll)
+ *   mimeType -> mimeType (inferred from the uri extension when null; `type:'video'` biases mp4)
+ *   fileSize -> size   (0 fallback; the encode-time cap re-checks the real bytes)
+ *   base64   -> base64 (present because we request `base64:true`, so readBase64 is skipped)
+ */
+function normalizeImageAsset(a) {
+    var _a, _b, _c, _d, _e, _f;
+    const ext = extOf((_a = a === null || a === void 0 ? void 0 : a.uri) !== null && _a !== void 0 ? _a : "") || ((a === null || a === void 0 ? void 0 : a.type) === "video" ? "mp4" : "jpg");
+    const mimeType = (_b = a === null || a === void 0 ? void 0 : a.mimeType) !== null && _b !== void 0 ? _b : ((a === null || a === void 0 ? void 0 : a.type) === "video" ? imageMimeFromExt(ext === "jpg" ? "mp4" : ext) : imageMimeFromExt(ext));
+    return {
+        uri: (_c = a === null || a === void 0 ? void 0 : a.uri) !== null && _c !== void 0 ? _c : "",
+        name: (_d = a === null || a === void 0 ? void 0 : a.fileName) !== null && _d !== void 0 ? _d : `image_${Date.now()}.${ext}`,
+        mimeType,
+        size: (_e = a === null || a === void 0 ? void 0 : a.fileSize) !== null && _e !== void 0 ? _e : 0,
+        base64: (_f = a === null || a === void 0 ? void 0 : a.base64) !== null && _f !== void 0 ? _f : undefined,
+    };
+}
+/**
+ * Normalize one `expo-document-picker` asset to the SDK {@link Asset}.
+ *
+ * expo-document-picker field -> SDK Asset:
+ *   uri      -> uri (a file:// cache uri because we pass copyToCacheDirectory:true)
+ *   name     -> name (synthesized when null)
+ *   mimeType -> mimeType (pdf inferred from ext; else application/octet-stream — which
+ *               validateSelection rejects as unsupported-type, the desired safe default)
+ *   size     -> size (0 fallback)
+ *   (no base64 — documents carry no eager payload, so readBase64(uri) supplies it)
+ */
+function normalizeDocumentAsset(a) {
+    var _a, _b, _c, _d, _e, _f;
+    const ext = extOf((_a = a === null || a === void 0 ? void 0 : a.name) !== null && _a !== void 0 ? _a : "") || extOf((_b = a === null || a === void 0 ? void 0 : a.uri) !== null && _b !== void 0 ? _b : "");
+    return {
+        uri: (_c = a === null || a === void 0 ? void 0 : a.uri) !== null && _c !== void 0 ? _c : "",
+        name: (_d = a === null || a === void 0 ? void 0 : a.name) !== null && _d !== void 0 ? _d : `file_${Date.now()}${ext ? "." + ext : ""}`,
+        mimeType: (_e = a === null || a === void 0 ? void 0 : a.mimeType) !== null && _e !== void 0 ? _e : (ext === "pdf" ? "application/pdf" : "application/octet-stream"),
+        size: (_f = a === null || a === void 0 ? void 0 : a.size) !== null && _f !== void 0 ? _f : 0,
+    };
+}
+/**
+ * Default {@link PickerAdapter} backed by Expo. Returns `undefined` when NEITHER
+ * expo-image-picker nor expo-document-picker is installed — so the attach button
+ * stays hidden (feature-detect parity with the absent-prop case). When only one
+ * lib is present the adapter exposes only that method (a partial picker is valid;
+ * the Surface omits the missing row).
+ */
+function createExpoPicker() {
+    const ImagePicker = safeRequire(() => require("expo-image-picker"), "expo-image-picker");
+    const DocumentPicker = safeRequire(() => require("expo-document-picker"), "expo-document-picker");
+    // SDK 56's modern file picker (expo-file-system File.pickFileAsync). It is the
+    // New-Architecture-native replacement for expo-document-picker, whose
+    // getDocumentAsync can HANG on the New Arch (presents nothing, never resolves).
+    // Preferred for documents when present; getDocumentAsync is the fallback.
+    const FS = safeRequire(() => require("expo-file-system"), "expo-file-system");
+    const FilePickCtor = FS === null || FS === void 0 ? void 0 : FS.File;
+    const hasFilePick = typeof (FilePickCtor === null || FilePickCtor === void 0 ? void 0 : FilePickCtor.pickFileAsync) === "function";
+    const hasImages = typeof (ImagePicker === null || ImagePicker === void 0 ? void 0 : ImagePicker.launchImageLibraryAsync) === "function";
+    const hasDocs = typeof (DocumentPicker === null || DocumentPicker === void 0 ? void 0 : DocumentPicker.getDocumentAsync) === "function";
+    adapterLog("picker — expo-image-picker:", hasImages ? "READY" : ImagePicker ? "loaded but no launchImageLibraryAsync" : "NOT AVAILABLE (native missing → rebuild)", "| documents:", hasFilePick ? "READY (File.pickFileAsync)" : hasDocs ? "READY (getDocumentAsync)" : "NOT AVAILABLE (native missing → rebuild)");
+    if (!hasImages && !hasDocs && !hasFilePick)
+        return undefined;
+    const adapter = {};
+    if (hasImages) {
+        adapter.pickImages = async (opts) => {
+            var _a, _b, _c;
+            // Permission: a denial is treated as a cancel ([] per contract), never a throw.
+            const req = ImagePicker.requestMediaLibraryPermissionsAsync;
+            if (typeof req === "function") {
+                const perm = await req();
+                if (perm && perm.granted === false)
+                    return [];
+            }
+            // mediaTypes: pass the SDK 51+ string-array form directly. Do NOT reference
+            // ImagePicker.MediaTypeOptions — passing its enum member fires the SDK 52+
+            // deprecation warning (parseMediaTypes warns on `=== a MediaTypeOptions value`).
+            const mediaTypes = ["images"];
+            let result;
+            try {
+                result = await ImagePicker.launchImageLibraryAsync({
+                    mediaTypes,
+                    allowsMultipleSelection: (_a = opts === null || opts === void 0 ? void 0 : opts.allowsMultiple) !== null && _a !== void 0 ? _a : true,
+                    base64: true, // eager base64 => toMediaEntry short-circuits readBase64 for images
+                    quality: (_b = opts === null || opts === void 0 ? void 0 : opts.quality) !== null && _b !== void 0 ? _b : 0.8,
+                });
+            }
+            catch (e) {
+                // A throw is almost always the NATIVE module missing from the running dev
+                // client (the JS exists so this method is wired, but the native call fails).
+                // Surface it (the Composer's stagePick otherwise swallows it -> the picker
+                // silently never opens) and treat as a cancel. Fix: rebuild the dev client.
+                adapterLog(`pickImages FAILED — ${(_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : e} (runtime pick error; if the OS sheet NEVER opens, the native module is missing → rebuild)`);
+                return [];
+            }
+            // Modern API: { canceled: boolean; assets }. `canceled` is spelled with one L.
+            if (result === null || result === void 0 ? void 0 : result.canceled)
+                return [];
+            const assets = Array.isArray(result === null || result === void 0 ? void 0 : result.assets) ? result.assets : [];
+            return assets.map(normalizeImageAsset);
+        };
+    }
+    if (hasImages) {
+        adapter.pickVideos = async (opts) => {
+            var _a, _b, _c;
+            // Permission: a denial is treated as a cancel ([] per contract), never a throw.
+            const req = ImagePicker.requestMediaLibraryPermissionsAsync;
+            if (typeof req === "function") {
+                const perm = await req();
+                if (perm && perm.granted === false)
+                    return [];
+            }
+            // mediaTypes: pass the string-array form directly (warning-free on SDK 56).
+            const mediaTypes = ["videos"];
+            let result;
+            try {
+                result = await ImagePicker.launchImageLibraryAsync({
+                    mediaTypes,
+                    allowsMultipleSelection: (_a = opts === null || opts === void 0 ? void 0 : opts.allowsMultiple) !== null && _a !== void 0 ? _a : true,
+                    // Videos can be large; do NOT request eager base64 (it would inflate the
+                    // payload in memory). readBase64(uri) supplies the payload at encode time,
+                    // exactly like documents. `type:'video'` biases normalizeImageAsset to mp4.
+                    quality: (_b = opts === null || opts === void 0 ? void 0 : opts.quality) !== null && _b !== void 0 ? _b : 0.8,
+                });
+            }
+            catch (e) {
+                adapterLog(`pickVideos FAILED — ${(_c = e === null || e === void 0 ? void 0 : e.message) !== null && _c !== void 0 ? _c : e} (runtime pick error; if the OS sheet NEVER opens, the native module is missing → rebuild)`);
+                return [];
+            }
+            // Modern API: { canceled: boolean; assets }. `canceled` is spelled with one L.
+            if (result === null || result === void 0 ? void 0 : result.canceled)
+                return [];
+            const assets = Array.isArray(result === null || result === void 0 ? void 0 : result.assets) ? result.assets : [];
+            return assets.map(normalizeImageAsset);
+        };
+    }
+    if (hasDocs || hasFilePick) {
+        adapter.pickDocuments = async (opts) => {
+            var _a, _b, _c, _d;
+            // PREFERRED — expo-file-system File.pickFileAsync (SDK 56, New-Arch native).
+            // expo-document-picker's getDocumentAsync HANGS on the New Architecture (the OS
+            // sheet never presents and the promise never resolves), so try the modern picker
+            // first and only fall through to getDocumentAsync if it is unavailable/throws.
+            if (hasFilePick) {
+                try {
+                    const res = await FilePickCtor.pickFileAsync((opts === null || opts === void 0 ? void 0 : opts.allowsMultiple)
+                        ? { multipleFiles: true, ...((opts === null || opts === void 0 ? void 0 : opts.mimeTypes) ? { mimeTypes: opts.mimeTypes } : {}) }
+                        : { ...((opts === null || opts === void 0 ? void 0 : opts.mimeTypes) ? { mimeTypes: opts.mimeTypes } : {}) });
+                    if (!res || res.canceled)
+                        return [];
+                    const files = Array.isArray(res.result)
+                        ? res.result
+                        : res.result
+                            ? [res.result]
+                            : [];
+                    // File implements Blob: uri/name/size + `type` (MIME) → normalize to Asset.
+                    // `type` may be an EMPTY string (Blob.type unknown); coerce to undefined so
+                    // normalizeDocumentAsset's extension fallback resolves it (.pdf → application/pdf)
+                    // — otherwise "" slips past its `?? ` and validateSelection rejects a valid PDF.
+                    return files.map((f) => normalizeDocumentAsset({
+                        uri: f === null || f === void 0 ? void 0 : f.uri,
+                        name: f === null || f === void 0 ? void 0 : f.name,
+                        mimeType: (typeof (f === null || f === void 0 ? void 0 : f.type) === "string" && f.type) || undefined,
+                        size: f === null || f === void 0 ? void 0 : f.size,
+                    }));
+                }
+                catch (e) {
+                    adapterLog(`pickDocuments: File.pickFileAsync FAILED — ${(_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e}${hasDocs ? " — falling back to getDocumentAsync" : ""}`);
+                    if (!hasDocs)
+                        return [];
+                    // fall through to getDocumentAsync
+                }
+            }
+            let result;
+            try {
+                result = await DocumentPicker.getDocumentAsync({
+                    // expo-document-picker accepts a string[] of MIME types directly. iOS maps
+                    // them to UTIs; Android honors them as EXTRA_MIME_TYPES. Non-standard mimes
+                    // a chooser ignores are re-enforced post-pick by validateSelection.
+                    type: (_b = opts === null || opts === void 0 ? void 0 : opts.mimeTypes) !== null && _b !== void 0 ? _b : ["*/*"],
+                    multiple: (_c = opts === null || opts === void 0 ? void 0 : opts.allowsMultiple) !== null && _c !== void 0 ? _c : false,
+                    // REQUIRED: yields a stable file:// cache uri readBase64 can read (a raw
+                    // content:// uri can be revoked before the read runs).
+                    copyToCacheDirectory: true,
+                });
+            }
+            catch (e) {
+                // This method only exists when getDocumentAsync IS present (hasDocs), so a throw
+                // here is a RUNTIME error, NOT a missing module — most often "Different document
+                // picking in progress" (a concurrent launch; now guarded by Composer.stagePick),
+                // or a permissions/UTI issue. Only if the OS sheet NEVER opens at all is the
+                // native module missing → add "expo-document-picker" to plugins and REBUILD.
+                adapterLog(`pickDocuments FAILED — ${(_d = e === null || e === void 0 ? void 0 : e.message) !== null && _d !== void 0 ? _d : e} (runtime pick error; if the OS sheet NEVER opens, the native module is missing → rebuild)`);
+                return [];
+            }
+            // Modern API: { canceled: true } on cancel; legacy <=48: { type: 'cancel' }.
+            if ((result === null || result === void 0 ? void 0 : result.canceled) || (result === null || result === void 0 ? void 0 : result.type) === "cancel")
+                return [];
+            // Modern: assets[]; legacy success returned a flat { uri, name, size, mimeType }.
+            const assets = Array.isArray(result === null || result === void 0 ? void 0 : result.assets)
+                ? result.assets
+                : (result === null || result === void 0 ? void 0 : result.uri)
+                    ? [result]
+                    : [];
+            return assets.map(normalizeDocumentAsset);
+        };
+    }
+    return adapter;
+}
+// ---------------------------------------------------------------------------
+// readBase64 (expo-file-system) -> (uri) => Promise<string>  (RAW base64)
+// ---------------------------------------------------------------------------
+/**
+ * Default file->base64 reader backed by `expo-file-system`. Returns RAW base64
+ * (no `data:` prefix) — `toDataUrl` adds the prefix downstream. Only invoked for
+ * assets WITHOUT eager base64 (documents, recorded audio); image-picker assets
+ * carry `base64` and short-circuit it.
+ *
+ * SDK drift: SDK 54 promoted the OO `File`/`Directory` API to the package root and
+ * DEPRECATED the classic functions. On SDK 56 the root `readAsStringAsync` is a STUB
+ * that THROWS at runtime ("This method will throw in runtime"), so we MUST prefer the
+ * OO `new File(uri).base64()` and only fall back to `readAsStringAsync` on OLDER SDKs
+ * (<=53) where the `File` class doesn't exist. Returns `undefined` when the lib is
+ * absent (provider's throwing reader still only fires if an attach without eager
+ * base64 is actually attempted).
+ */
+function createExpoReadBase64() {
+    var _a, _b;
+    // Static require of the ROOT package only. `expo-file-system/legacy` is
+    // intentionally NOT required: a static require of a possibly-absent subpath would
+    // FAIL the Metro bundle. The SDK-56 root exposes the new File API (preferred) and
+    // a throwing `readAsStringAsync` stub (legacy fallback only) — both handled below.
+    const root = safeRequire(() => require("expo-file-system"), "expo-file-system");
+    // SDK 54+ OO API FIRST: `new File(uri).base64()` -> Promise<string> (RAW base64).
+    // CRITICAL: this MUST come before readAsStringAsync. On SDK 56 the root
+    // `readAsStringAsync` is a DEPRECATED STUB that throws at runtime, so preferring it
+    // (the previous order) made every NON-image attach fail at encode — recorded audio,
+    // picked video, and documents have no eager base64, so they hit this reader and
+    // surfaced as WebChatError("send", "media encode failed") -> "[webchat] error send".
+    // The File API is the only working root path on current SDKs.
+    const FileCtor = root === null || root === void 0 ? void 0 : root.File;
+    if (typeof FileCtor === "function") {
+        return async (uri) => {
+            const out = new FileCtor(uri).base64();
+            return typeof (out === null || out === void 0 ? void 0 : out.then) === "function" ? await out : out;
+        };
+    }
+    // Legacy SDKs (<=53): classic readAsStringAsync at the root (works there; on SDK 56
+    // it would throw, but on <=53 there is no File class so this is the only path).
+    if (typeof (root === null || root === void 0 ? void 0 : root.readAsStringAsync) === "function") {
+        const encoding = (_b = (_a = root.EncodingType) === null || _a === void 0 ? void 0 : _a.Base64) !== null && _b !== void 0 ? _b : "base64";
+        return (uri) => root.readAsStringAsync(uri, { encoding });
+    }
+    return undefined;
+}
+/**
+ * Stable RN family name for one tenant font entry. Web uses a single CSS family
+ * with per-weight `@font-face`; RN cannot share one family across weights via
+ * `loadAsync`, so each weight is registered as its OWN family. The name is
+ * derived from the entry's `fontName` (preferred — already weight-specific like
+ * "Tajawal-Bold") else its `fontWeight`, sanitized to `[A-Za-z0-9_-]`, e.g.
+ * `webchat-Tajawal-Bold` or `webchat-700`. Returns `undefined` when neither
+ * `fontName` nor `fontWeight` is present (entry is unkeyable -> skipped).
+ */
+function brandFontFamilyName(font) {
+    var _a;
+    const raw = (_a = font === null || font === void 0 ? void 0 : font.fontName) !== null && _a !== void 0 ? _a : font === null || font === void 0 ? void 0 : font.fontWeight;
+    if (raw == null || String(raw).trim() === "")
+        return undefined;
+    const safe = String(raw).trim().replace(/[^A-Za-z0-9_-]/g, "-");
+    return `webchat-${safe}`;
+}
+/**
+ * Default brand-font loader backed by `expo-font`. Returns `undefined` (no-op)
+ * when expo-font is absent — so Metro never pulls the native module into the
+ * import graph and the jest suite (where it is not installed) keeps working,
+ * exactly like the other expo defaults.
+ *
+ * When present it returns `loadBrandFonts(fontFamily)`, an async loader that:
+ *   - maps each provided font entry to a stable RN family name (`webchat-{…}`),
+ *   - calls `Font.loadAsync({ [familyName]: url })` for each (in parallel via
+ *     Promise.all), TOLERATING individual failures (a bad url drops just that
+ *     weight, never rejects the whole batch),
+ *   - RESOLVES to a `weight -> familyName` map for the apply phase. The map is
+ *     keyed by each entry's `fontWeight` (so `resolveFontFamily(map, weight)`
+ *     can look a weight up); entries without a `fontWeight` are still loaded but
+ *     are only reachable via the family-level `name` key (added when present).
+ *
+ * An empty/undefined `fonts` array resolves to `{}` (no fonts loaded).
+ */
+function createExpoFontLoader() {
+    const Font = safeRequire(() => require("expo-font"), "expo-font");
+    if (!Font || typeof Font.loadAsync !== "function")
+        return undefined;
+    return async (fontFamily) => {
+        const fonts = Array.isArray(fontFamily === null || fontFamily === void 0 ? void 0 : fontFamily.fonts) ? fontFamily.fonts : [];
+        const map = {};
+        if (fonts.length === 0)
+            return map;
+        await Promise.all(fonts.map(async (f) => {
+            const url = f === null || f === void 0 ? void 0 : f.url;
+            const familyName = brandFontFamilyName(f);
+            // Skip unkeyable (no fontName/fontWeight) or sourceless entries.
+            if (!url || !familyName)
+                return;
+            try {
+                await Font.loadAsync({ [familyName]: url });
+            }
+            catch {
+                // Tolerate a single weight failing to load (bad url, network, decode):
+                // the rest of the batch still resolves and that weight just falls back
+                // to the system font via resolveFontFamily returning undefined.
+                return;
+            }
+            // Only expose successfully-loaded families in the returned map.
+            if ((f === null || f === void 0 ? void 0 : f.fontWeight) != null && String(f.fontWeight).trim() !== "") {
+                map[String(f.fontWeight)] = familyName;
+            }
+            // Family-level alias (web `name`) maps to the first loaded family so the
+            // apply phase can resolve "the brand font" without a specific weight.
+            if ((fontFamily === null || fontFamily === void 0 ? void 0 : fontFamily.name) && !map[fontFamily.name]) {
+                map[fontFamily.name] = familyName;
+            }
+        }));
+        return map;
+    };
+}
+// ---------------------------------------------------------------------------
+// Audio playback (expo-audio) -> AudioAdapter (PLAYBACK-CAPABLE default)
+// ---------------------------------------------------------------------------
+// B6 CODEC / ENGINE FLAG — READ BEFORE CHANGING.
+// ------------------------------------------------------------------------
+// The audio engine is `expo-audio` (the dead `expo-av` was removed: 16.x does
+// not build on Expo SDK 56). expo-audio splits its surface in two:
+//
+//   • PLAYBACK is IMPERATIVE  -> createAudioPlayer(uri) | player.play() |
+//     player.pause() | player.remove(). This fits the AudioAdapter object shape,
+//     so the DEFAULT adapter implements play()/stop() here.
+//   • RECORDING is HOOK-ONLY  -> useAudioRecorder(RecordingPresets.HIGH_QUALITY)
+//     can ONLY be called from inside a React component (Rules of Hooks). It does
+//     NOT fit a plain object method. So the default adapter does NOT record: it
+//     delegates recording to the <AudioRecorder> component path (Phase 2), which
+//     drives the hook and produces a RecordingResult through the same contract.
+//     Here startRecording()/stopRecording() are inert no-op stubs (they keep the
+//     AudioAdapter type satisfied) and MUST NOT be used to capture a note.
+//
+// CODEC: expo-audio's HIGH_QUALITY preset records MPEG-4 / AAC (.m4a) on BOTH iOS
+// and Android — it CANNOT produce Ogg/Opus (the SDK's web-parity CANONICAL_AUDIO_MIME).
+// The recorder component (Phase 2) HONESTLY returns the real container mime; we do
+// NOT mislabel m4a bytes as audio/ogg. For the voice note to pass validateSelection,
+// "audio/mp4" / "audio/aac" / "audio/m4a" are in src/core/media.ts ALLOW_LIST.
+//
+// ⚠️ OPEN DEPENDENCY (B6): the WEB widget only ever sent audio/ogg;codecs=opus.
+// Backend/infra acceptance of m4a/aac voice notes MUST BE CONFIRMED. If the backend
+// rejects them, substitute an Opus-capable recorder behind this same AudioAdapter
+// (expo-audio alone cannot do Opus) so mimeType genuinely equals CANONICAL_AUDIO_MIME.
+// Do NOT "solve" this by lying about the mime.
+const RECORDED_AUDIO_MIME = "audio/mp4"; // .m4a / AAC container (iOS + Android)
+/**
+ * Default PLAYBACK-CAPABLE {@link AudioAdapter} backed by `expo-audio`. Returns
+ * `undefined` when expo-audio is absent (received-voice falls back to a download
+ * tile — parity with the absent-prop case).
+ *
+ * PLAYBACK (imperative, fully implemented here):
+ *   play(uri)  -> createAudioPlayer(uri); player.play(); retain the player.
+ *   stop()     -> retained player.pause() + player.remove() (MUST remove() to free
+ *                 native resources); null-safe; a single active player is retained,
+ *                 so a new play() removes any prior one first.
+ *
+ * RECORDING (delegated to Phase 2 component): startRecording()/stopRecording() are
+ * inert stubs that keep the AudioAdapter type satisfied. expo-audio's recorder is
+ * HOOK-ONLY (useAudioRecorder), so the real capture lives in the <AudioRecorder>
+ * component (Phase 2) which drives the hook and yields a RecordingResult tagged with
+ * the m4a container mime above. The default object adapter cannot call a hook.
+ */
+function createExpoAudioAdapter() {
+    const audio = safeRequire(() => require("expo-audio"), "expo-audio");
+    adapterLog("audio — expo-audio:", audio ? (typeof audio.createAudioPlayer === "function" ? "READY" : "loaded but no createAudioPlayer") : "NOT AVAILABLE (native missing → rebuild)");
+    if (!audio || typeof audio.createAudioPlayer !== "function")
+        return undefined;
+    // Single retained active player (imperative). play() replaces any prior one;
+    // stop() pauses + removes it to free native resources, then clears the ref.
+    let player = null;
+    // Subscription to expo-audio's "playbackStatusUpdate" (position/duration/finish);
+    // removed alongside the player so no stale listener fires after stop/replace.
+    let statusSub = null;
+    function releasePlayer() {
+        var _a, _b, _c;
+        try {
+            (_a = statusSub === null || statusSub === void 0 ? void 0 : statusSub.remove) === null || _a === void 0 ? void 0 : _a.call(statusSub);
+        }
+        catch {
+            /* best-effort */
+        }
+        statusSub = null;
+        if (!player)
+            return;
+        try {
+            (_b = player.pause) === null || _b === void 0 ? void 0 : _b.call(player);
+        }
+        catch {
+            /* best-effort: never throw out of release */
+        }
+        try {
+            (_c = player.remove) === null || _c === void 0 ? void 0 : _c.call(player); // REQUIRED to free expo-audio native resources
+        }
+        catch {
+            /* best-effort */
+        }
+        player = null;
+    }
+    return {
+        // RECORDING is provided by the Phase 2 <AudioRecorder> component (expo-audio
+        // useAudioRecorder hook), NOT by this object adapter — these stubs only keep
+        // the AudioAdapter type satisfied for the playback-capable default. The flag
+        // below tells <AudioRecorder> to drive the hook directly instead of calling
+        // these inert stubs (a host-injected imperative recorder leaves it unset and
+        // its real startRecording/stopRecording are used as-is).
+        recordingDelegated: true,
+        async startRecording() {
+            /* no-op: default recording is delegated to the AudioRecorder component */
+        },
+        async stopRecording() {
+            // Inert result, tagged with the container mime the Phase 2 recorder emits.
+            return { uri: "", mimeType: RECORDED_AUDIO_MIME, durationMs: 0 };
+        },
+        async play(uri, opts) {
+            var _a;
+            // Replace any currently-retained player so only one note plays at a time.
+            releasePlayer();
+            const p = audio.createAudioPlayer(uri);
+            player = p;
+            // Live progress: subscribe to expo-audio's status events so the player UI can
+            // show "current / total" and reset on finish. currentTime/duration are SECONDS
+            // in expo-audio → convert to ms. Guarded so engines without addListener degrade
+            // gracefully (no progress; the UI keeps showing the recorded total).
+            const onStatus = opts === null || opts === void 0 ? void 0 : opts.onStatus;
+            if (onStatus && typeof (p === null || p === void 0 ? void 0 : p.addListener) === "function") {
+                statusSub = p.addListener("playbackStatusUpdate", (st) => {
+                    var _a, _b, _c, _d, _e, _f, _g;
+                    const durationMs = Math.max(0, Math.round(((_b = (_a = st === null || st === void 0 ? void 0 : st.duration) !== null && _a !== void 0 ? _a : p === null || p === void 0 ? void 0 : p.duration) !== null && _b !== void 0 ? _b : 0) * 1000));
+                    const positionMs = Math.max(0, Math.round(((_d = (_c = st === null || st === void 0 ? void 0 : st.currentTime) !== null && _c !== void 0 ? _c : p === null || p === void 0 ? void 0 : p.currentTime) !== null && _d !== void 0 ? _d : 0) * 1000));
+                    const isPlaying = (_f = (_e = st === null || st === void 0 ? void 0 : st.playing) !== null && _e !== void 0 ? _e : p === null || p === void 0 ? void 0 : p.playing) !== null && _f !== void 0 ? _f : true;
+                    const didJustFinish = (_g = st === null || st === void 0 ? void 0 : st.didJustFinish) !== null && _g !== void 0 ? _g : (durationMs > 0 && positionMs >= durationMs);
+                    onStatus({ positionMs, durationMs, isPlaying, didJustFinish });
+                });
+            }
+            (_a = p === null || p === void 0 ? void 0 : p.play) === null || _a === void 0 ? void 0 : _a.call(p);
+        },
+        async stop() {
+            releasePlayer();
+        },
+    };
+}

package/lib/adapters/picker.d.ts

@@ -0,0 +1,67 @@
+/**
+ * A normalized file selected from the device, independent of the underlying
+ * picker library. `base64` is optional: some pickers return it eagerly, others
+ * require a separate read (see {@link toMediaEntry}).
+ */
+export interface Asset {
+    /** local file URI (file://… or content://…) */
+    uri: string;
+    /** display name including extension, e.g. "photo.jpg" */
+    name: string;
+    /** MIME type, e.g. "image/jpeg", "application/pdf" */
+    mimeType: string;
+    /** raw byte size before base64 inflation */
+    size: number;
+    /** eagerly-provided base64 payload (no data: prefix), when available */
+    base64?: string;
+}
+export interface PickImagesOptions {
+    /** allow selecting more than one image */
+    allowsMultiple?: boolean;
+    /** 0..1 compression quality hint passed to the native picker */
+    quality?: number;
+    /** longest-edge resize hint passed to the native picker */
+    maxDimension?: number;
+}
+export interface PickDocumentsOptions {
+    allowsMultiple?: boolean;
+    /** allow-listed MIME types the picker should restrict to */
+    mimeTypes?: string[];
+}
+/**
+ * The injectable picker surface. An empty array means the user cancelled.
+ * Both capabilities are OPTIONAL so a host can ship a partial picker (e.g.
+ * images only); the Surface feature-detects with `picker?.pickImages` and only
+ * offers the corresponding selector row when a method is present.
+ */
+export interface PickerAdapter {
+    pickImages?(opts?: PickImagesOptions): Promise<Asset[]>;
+    pickVideos?(opts?: PickImagesOptions): Promise<Asset[]>;
+    pickDocuments?(opts?: PickDocumentsOptions): Promise<Asset[]>;
+}
+/**
+ * The shape of a single `user_uttered.media[]` entry. The payload is a
+ * self-describing data URL so the existing base64-in-socket transport carries
+ * it unchanged (web parity).
+ */
+export interface MediaEntry {
+    /** "data:<mimeType>;base64,<payload>" */
+    data: string;
+    name: string;
+    mimeType: string;
+    size: number;
+}
+/**
+ * Build a `data:` URL from a MIME type and raw base64 payload.
+ * Pure — no I/O.
+ */
+export declare function toDataUrl(mimeType: string, base64: string): string;
+/**
+ * Pure transform: turn an {@link Asset} into a {@link MediaEntry} carrying a
+ * base64 data URL. Base64 acquisition is injected via `readBase64` so this
+ * stays I/O-free and testable with a fake reader.
+ *
+ * If the asset already carries `base64` it is used directly and `readBase64`
+ * is not called; otherwise `readBase64(asset.uri)` supplies the payload.
+ */
+export declare function toMediaEntry(asset: Asset, readBase64: (uri: string) => Promise<string>): Promise<MediaEntry>;

package/lib/adapters/picker.js

@@ -0,0 +1,37 @@
+"use strict";
+// src/adapters/picker.ts
+//
+// Picker capability behind an injectable interface so the framework-agnostic
+// core never calls a native module directly. Real impls (Expo
+// `expo-image-picker`/`expo-document-picker`, bare `react-native-image-picker`/
+// `react-native-document-picker`) are constructed in the example apps and
+// injected; unit tests use a fake that returns canned `Asset[]`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDataUrl = toDataUrl;
+exports.toMediaEntry = toMediaEntry;
+/**
+ * Build a `data:` URL from a MIME type and raw base64 payload.
+ * Pure — no I/O.
+ */
+function toDataUrl(mimeType, base64) {
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * Pure transform: turn an {@link Asset} into a {@link MediaEntry} carrying a
+ * base64 data URL. Base64 acquisition is injected via `readBase64` so this
+ * stays I/O-free and testable with a fake reader.
+ *
+ * If the asset already carries `base64` it is used directly and `readBase64`
+ * is not called; otherwise `readBase64(asset.uri)` supplies the payload.
+ */
+async function toMediaEntry(asset, readBase64) {
+    const base64 = asset.base64 != null && asset.base64.length > 0
+        ? asset.base64
+        : await readBase64(asset.uri);
+    return {
+        data: toDataUrl(asset.mimeType, base64),
+        name: asset.name,
+        mimeType: asset.mimeType,
+        size: asset.size,
+    };
+}