@alia.onl/sdk 13.1.0 → 15.2.1

package/src/index.ts

@@ -6,6 +6,7 @@
 export type { AliaChatAgent, AliaChatState } from './components/AliaChatContent';
 export { AliaChatSheet } from './components/AliaChatSheet';
 export type { AliaChatSheetProps, AliaChatSheetRef } from './components/AliaChatSheet';
+export type { AliaTurn } from './components/AliaChatContent';
 export { AliaChatScreen } from './components/AliaChatScreen';
 export type { AliaChatScreenProps } from './components/AliaChatScreen';
 
@@ -19,6 +20,9 @@ export type { AmbientFieldProps } from './components/AmbientField';
 export { ALIA_AVATAR, AliaAvatar } from './components/AliaAvatar';
 export { DEFAULT_AGENT_CHARACTER, readAgentCharacter } from './lib/agent-character';
 export type { AliaAvatarProps, AliaAvatarState } from './components/AliaAvatar';
+export { AliaAvatarIcon } from './components/AliaAvatarIcon';
+export { useAliaActivity } from './hooks/useAliaActivity';
+export type { UseAliaActivityOptions } from './hooks/useAliaActivity';
 export { IdentityMark } from './components/IdentityMark';
 export type { IdentityMarkProps, IdentityMarkState } from './components/IdentityMark';
 export { AliaMarkdown } from './components/Markdown';
@@ -26,7 +30,14 @@ export type { AliaMarkdownProps, RenderCodeBlock } from './components/Markdown';
 export { AliaWelcomeMessage } from './components/AliaWelcomeMessage';
 export { PlanPreviewCard } from './components/PlanPreviewCard';
 export { AskedQuestions, QuestionCard } from './components/QuestionCard';
+export { AliaComposer } from './components/AliaComposer';
+export type {
+  AliaComposerProps,
+  AliaComposerQuestions,
+  AliaComposerSuggestions,
+} from './components/AliaComposer';
 export { ComposerSuggestions } from './components/ComposerSuggestions';
+export { usePendingQuestions } from './hooks/usePendingQuestions';
 export { useComposerSuggestions, useSuggestionQuery } from './hooks/useComposerSuggestions';
 export { composerCompletions } from './lib/suggestions';
 export type { Completion } from './lib/suggestions';
@@ -44,13 +55,17 @@ export type { UseAliaChatOptions, UseAliaChatReturn } from './hooks/useAliaChat'
 export { AliaChatStreamError } from './lib/chat-stream';
 export type { AliaChatFailure } from './lib/chat-stream';
 
-// ── Text-to-speech / speech-to-text (no livekit) ──
+// ── Read aloud and dictation (no call, no audio engine) ──
 export { useTTS } from './hooks/useTTS';
 export type { UseTTSOptions } from './hooks/useTTS';
-export { useSpeechToText, useSTTStore } from './hooks/useSpeechToText';
+export { useDictation, useDictationStore } from './hooks/useDictation';
+export type { UseDictationOptions, DictationState } from './hooks/useDictation';
+export { DictationError, requestTranscription } from './lib/dictation';
+export type { DictationErrorCode, TranscriptionResult } from './lib/dictation';
 export { VOICE_ERROR_MESSAGES } from './lib/speech-messages';
 export type { VoiceErrorCode } from './lib/speech-messages';
-export type { UseSTTOptions } from './hooks/useSpeechToText';
+export { SpeechClipError } from './lib/speech-synthesis';
+export type { SpeechClipErrorCode } from './lib/speech-synthesis';
 
 // ── Model catalogue (GET /catalogue) ──
 // Exported so a consumer building its own picker reads the real models the
@@ -68,6 +83,7 @@ export type { Catalogue, CatalogueEntry, ModelSelection, ReasoningEffort } from
 export type {
   ChatMessage,
   ToolInvocation,
+  AliaAttachment,
   AliaSuggestion,
   ResearchProgress,
   ResearchSource,

package/src/lib/activity-socket.ts

@@ -0,0 +1,102 @@
+import { io, type Socket } from 'socket.io-client';
+import type { AliaAvatarState } from '../components/AliaAvatar';
+import { useAliaActivityStore } from './activity-store';
+
+/** A run that goes quiet this long is over: a crashed run never says `idle`. */
+export const ACTIVITY_QUIET_MS = 90_000;
+/** Between tries after the server refuses a handshake (socket.io does not retry those itself). */
+const RETRY_MS = 5_000;
+
+const STATES: ReadonlySet<string> = new Set<AliaAvatarState>([
+  'idle',
+  'thinking',
+  'working',
+  'writing',
+]);
+
+interface Connection {
+  socket: Socket;
+  refs: number;
+  quiet: Map<string, ReturnType<typeof setTimeout>>;
+  retry: ReturnType<typeof setTimeout> | null;
+}
+
+/** One connection per API origin, however many buttons ask for it. */
+const connections = new Map<string, Connection>();
+
+function open(url: string, getToken: () => string | null): Connection {
+  const socket = io(url, {
+    transports: ['websocket'],
+    // Read on every (re)connect, so a rotated access token is the one that goes out.
+    auth: (cb) => cb({ token: getToken() }),
+    reconnection: true,
+    reconnectionAttempts: Infinity,
+    reconnectionDelay: 1000,
+    reconnectionDelayMax: 10_000,
+  });
+  const connection: Connection = { socket, refs: 0, quiet: new Map(), retry: null };
+  const store = useAliaActivityStore.getState;
+
+  const reset = (): void => {
+    for (const timer of connection.quiet.values()) clearTimeout(timer);
+    connection.quiet.clear();
+    store().clearRemote();
+  };
+
+  socket.on('connect', () => socket.emit('subscribe-alia-activity'));
+  // What happened while disconnected is unknown; a stale "working" is worse than idle.
+  socket.on('disconnect', reset);
+  socket.on('connect_error', () => {
+    // A refused handshake (no token yet, an expired one) ends the socket's own retrying.
+    if (socket.active || connection.retry !== null) return;
+    connection.retry = setTimeout(() => {
+      connection.retry = null;
+      socket.connect();
+    }, RETRY_MS);
+  });
+  socket.on('alia:activity', (event: unknown) => {
+    if (typeof event !== 'object' || event === null) return;
+    const { state, sessionId } = event as { state?: unknown; sessionId?: unknown };
+    if (typeof sessionId !== 'string' || typeof state !== 'string' || !STATES.has(state)) return;
+    const pending = connection.quiet.get(sessionId);
+    if (pending !== undefined) clearTimeout(pending);
+    connection.quiet.delete(sessionId);
+    store().setRemote(sessionId, state as AliaAvatarState);
+    if (state !== 'idle') {
+      connection.quiet.set(
+        sessionId,
+        setTimeout(() => {
+          connection.quiet.delete(sessionId);
+          store().setRemote(sessionId, 'idle');
+        }, ACTIVITY_QUIET_MS),
+      );
+    }
+  });
+  return connection;
+}
+
+/**
+ * Listen for Alia's activity on the person's behalf. Every caller shares the one connection for
+ * `url`; the last to release closes it. Returns the release.
+ */
+export function acquireActivitySocket(url: string, getToken: () => string | null): () => void {
+  let held = connections.get(url);
+  if (!held) {
+    held = open(url, getToken);
+    connections.set(url, held);
+  }
+  const connection = held;
+  connection.refs++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (--connection.refs > 0) return;
+    connections.delete(url);
+    if (connection.retry !== null) clearTimeout(connection.retry);
+    connection.socket.removeAllListeners();
+    connection.socket.disconnect();
+    for (const timer of connection.quiet.values()) clearTimeout(timer);
+    useAliaActivityStore.getState().clearRemote();
+  };
+}

package/src/lib/activity-store.ts

@@ -0,0 +1,53 @@
+import { create } from 'zustand';
+import type { AliaAvatarState } from '../components/AliaAvatar';
+
+type Sources = Readonly<Record<string, AliaAvatarState>>;
+
+/**
+ * What Alia is doing, from every place that can know. Two sources feed it and neither owns it:
+ *
+ * - `local`: the turns running in THIS app, one entry per `useAliaChat` instance (the sheet);
+ * - `remote`: runs the server reports for the person, one entry per agent session, so a button
+ *   reacts to work that is not in any open chat.
+ *
+ * An idle source holds no entry, so neither map grows with use.
+ */
+interface AliaActivityStore {
+  local: Sources;
+  remote: Sources;
+  setLocal(source: string, state: AliaAvatarState): void;
+  setRemote(session: string, state: AliaAvatarState): void;
+  clearRemote(): void;
+}
+
+function put(map: Sources, key: string, state: AliaAvatarState): Sources {
+  if (state === 'idle') {
+    if (!(key in map)) return map;
+    const { [key]: _gone, ...rest } = map;
+    return rest;
+  }
+  return map[key] === state ? map : { ...map, [key]: state };
+}
+
+export const useAliaActivityStore = create<AliaActivityStore>((set) => ({
+  local: {},
+  remote: {},
+  setLocal: (source, state) => set((s) => ({ local: put(s.local, source, state) })),
+  setRemote: (session, state) => set((s) => ({ remote: put(s.remote, session, state) })),
+  clearRemote: () => set((s) => (Object.keys(s.remote).length === 0 ? s : { remote: {} })),
+}));
+
+/** The most telling thing any source is doing: a tool call outranks thinking, thinking outranks writing. */
+const RANK: Record<AliaAvatarState, number> = { idle: 0, writing: 1, thinking: 2, working: 3 };
+
+export function busiest(...maps: ReadonlyArray<Sources>): AliaAvatarState {
+  let top: AliaAvatarState = 'idle';
+  for (const map of maps) {
+    for (const state of Object.values(map)) if (RANK[state] > RANK[top]) top = state;
+  }
+  return top;
+}
+
+/** A primitive, so a subscriber re-renders when the state changes and not when a session does. */
+export const selectAliaActivity = (s: AliaActivityStore): AliaAvatarState =>
+  busiest(s.local, s.remote);

package/src/lib/api-url.ts

@@ -0,0 +1,2 @@
+/** Where Alia's API is: `EXPO_PUBLIC_ALIA_API_URL`, then `https://api.alia.onl`. */
+export const ALIA_API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api.alia.onl';

package/src/lib/attachment-intake.ts

@@ -0,0 +1,154 @@
+/**
+ * What the composer will take in, and how far a file has actually got.
+ *
+ * Alia had no answer to either question. A file reached the attachment strip
+ * by exactly one route — a picker that hands back a `uri` and asks nothing —
+ * so there was no size it would refuse, no kind it would separate, and, once
+ * drag-and-drop existed, no shared place to state those rules for a second
+ * route. Worse, a drag is a stateful gesture: the browser fires `dragenter`
+ * and `dragleave` for every element the pointer crosses, so a drop affordance
+ * driven by a boolean flickers off the instant the pointer moves from the bar
+ * onto the textarea INSIDE it. The counter that fixes that is four lines of
+ * arithmetic guarding a visible effect, which is precisely the kind of thing
+ * that is easy to get subtly wrong and almost impossible to watch going wrong.
+ *
+ * So it lives here, beside `turn-selection.ts`, under the same rule: nothing
+ * in this file may import react-native, read a store, or touch the DOM. The
+ * reader that moves the bytes is a platform adapter and lives with the
+ * composer; what can be decided by arithmetic is decided here, where it can be
+ * checked without mounting a composer or staging a drag.
+ */
+
+/**
+ * The largest file the composer will take.
+ *
+ * An attached image is not uploaded anywhere — the app's `attachment-utils.ts`
+ * inlines it into the request as a `data:` URL — so its bytes are carried in
+ * memory as a base64 string roughly a third larger than the file, twice over
+ * while the request is built. 20 MiB is the point past which that stops being
+ * a message and starts being a reason the tab dies.
+ */
+export const MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+
+export type IntakeKind = 'image' | 'document';
+
+/** Why a file was turned away. Each one has its own sentence to the user. */
+export type IntakeRefusal = 'empty' | 'too-large' | 'unsupported';
+
+export type IntakeVerdict =
+  | { accepted: true; kind: IntakeKind }
+  | { accepted: false; refusal: IntakeRefusal };
+
+export interface IntakeCandidate {
+  name: string;
+  mimeType: string;
+  size: number;
+}
+
+/**
+ * Extensions that name a picture when the browser will not.
+ *
+ * A dragged file's `type` is filled in from the OS, and it comes through empty
+ * often enough to matter — from an archive manager, from a file manager with a
+ * thin mime database, from anything that drops a path rather than a handle.
+ * Falling back to the name is not a nicety: without it a dropped `.png` is
+ * filed as a document, and a document is never inlined into the request at all.
+ */
+const IMAGE_EXTENSIONS = ['png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'avif', 'heic', 'heif'];
+
+/**
+ * Whether a candidate is a picture, by what the browser says first and by its
+ * name only when the browser said nothing.
+ */
+export function intakeKind(candidate: IntakeCandidate): IntakeKind {
+  if (candidate.mimeType.startsWith('image/')) return 'image';
+  const extension = candidate.name.split('.').pop()?.toLowerCase() ?? '';
+  return IMAGE_EXTENSIONS.includes(extension) ? 'image' : 'document';
+}
+
+/**
+ * The one gate both web routes pass through — pasted files and dropped ones —
+ * so a rule cannot hold for one and not the other.
+ *
+ * The zero-byte refusal is not pedantry about empty files. Dropping a FOLDER
+ * on web yields a `File` with size 0 and no type, in every browser; without
+ * this the composer accepts a tile named after a directory whose contents it
+ * will never have, and whose read completes with nothing in it.
+ */
+export function classifyIntake(candidate: IntakeCandidate): IntakeVerdict {
+  if (candidate.size <= 0) return { accepted: false, refusal: 'empty' };
+  if (candidate.size > MAX_ATTACHMENT_BYTES) return { accepted: false, refusal: 'too-large' };
+  return { accepted: true, kind: intakeKind(candidate) };
+}
+
+/** The four things that can happen to the count of drags over the composer. */
+export type DragStep = 'enter' | 'leave' | 'drop' | 'reset';
+
+/**
+ * How many dragged-over elements deep the pointer is.
+ *
+ * `dragenter` and `dragleave` fire per ELEMENT, not per target, and they fire
+ * in that order: moving from the bar onto the textarea inside it produces
+ * `dragenter` (textarea) then `dragleave` (bar). A boolean set by enter and
+ * cleared by leave therefore ends that move switched OFF while the pointer is
+ * still over the composer, and the affordance strobes as the pointer crosses
+ * each child on the way in. Counting elements instead is the standard answer,
+ * and the depth only reaches zero when the pointer has genuinely left
+ * everything.
+ *
+ * `drop` resets rather than decrements: the browser does not send the matching
+ * `dragleave` for the element the file landed on, so a decrement leaves the
+ * count stuck at one and the overlay pinned over the composer for good.
+ */
+export function nextDragDepth(depth: number, step: DragStep): number {
+  switch (step) {
+    case 'enter':
+      return depth + 1;
+    case 'leave':
+      // Clamped, because a `dragleave` can arrive without its `dragenter` — a
+      // drag that began before the listener was attached, or one whose
+      // `dragenter` was swallowed by an element that stopped propagation. A
+      // negative depth would then need two full entries before the overlay
+      // came back.
+      return Math.max(0, depth - 1);
+    case 'drop':
+    case 'reset':
+      return 0;
+  }
+}
+
+/**
+ * Whether this drag is carrying files at all.
+ *
+ * `DataTransfer.types` contains the literal `"Files"` when it is; dragging
+ * selected text or a link gives `"text/plain"` and `"text/uri-list"` instead.
+ * Without the question the composer lights up when the user drags a word
+ * across it, and then swallows the drop.
+ */
+export function dragCarriesFiles(types: readonly string[] | undefined): boolean {
+  return types !== undefined && types.includes('Files');
+}
+
+/**
+ * How far a read has got, as a fraction — or `null` when nothing measurable
+ * was reported.
+ *
+ * `null` is the important return, and it is why this is a function rather than
+ * a division at the call site. #608 §7: "Cuando no hay avance medible, mostrar
+ * actividad indeterminada. No inventar porcentajes." A `ProgressEvent` whose
+ * `lengthComputable` is false carries a `total` of 0, and dividing by it gives
+ * `NaN` or `Infinity` — both of which render as SOMETHING once handed to a
+ * bar, and that something is invented. Bloom's `use-attachment-queue.ts`
+ * invents its number outright, from a `Math.random()` ramp on a 50ms tick;
+ * nothing in this file may grow a timer.
+ */
+export function readFraction(progress: {
+  lengthComputable: boolean;
+  loaded: number;
+  total: number;
+}): number | null {
+  if (!progress.lengthComputable) return null;
+  if (!Number.isFinite(progress.total) || progress.total <= 0) return null;
+  if (!Number.isFinite(progress.loaded) || progress.loaded < 0) return null;
+  return Math.min(1, progress.loaded / progress.total);
+}

package/src/lib/attachment-tiles.ts

@@ -0,0 +1,74 @@
+import type { ComposerPanelAttachment } from '@oxy.so/bloom/composer-panel';
+import type { IntakeItem } from '../hooks/useAttachmentIntake';
+import type { AliaAttachment } from '../types';
+import { MAX_ATTACHMENT_BYTES } from './attachment-intake';
+import type { AliaChatLabels } from './labels';
+
+/**
+ * The composer's tiles: landed files, then the ones the intake still holds.
+ *
+ * A file whose read failed, or that was refused, stays in the strip with the
+ * sentence that says why — a drop of six where one did not make it is a
+ * sentence the user needs beside the five that did, not a toast that slides
+ * away. `retryable` marks the ones a second read could fix: a failed read,
+ * whose `File` the intake kept. A refusal is not: the same 30 MB file reaches
+ * the same verdict — and since Bloom's retry button is the panel's, drawn on
+ * every error tile once `onAttachmentRetry` is set, the composer shows a
+ * refusal as a toast rather than as a tile it would offer to retry.
+ */
+export interface ComposerTile extends ComposerPanelAttachment {
+  error?: string;
+  retryable?: boolean;
+}
+
+/** The words a tile and a refusal use. */
+type TileLabels = Pick<
+  AliaChatLabels,
+  'composerUntitled' | 'fileReadFailed' | 'fileTooLarge' | 'fileEmpty' | 'fileUnsupported'
+>;
+
+/** Why an intake item is not an attachment, or `undefined` while it is being read. */
+export function intakeError(item: IntakeItem, labels: TileLabels): string | undefined {
+  const name = item.name || labels.composerUntitled;
+  switch (item.status) {
+    case 'reading':
+      return undefined;
+    case 'failed':
+      return labels.fileReadFailed(name);
+    case 'refused':
+      if (item.refusal === 'unsupported') return labels.fileUnsupported(name);
+      return item.refusal === 'too-large'
+        ? labels.fileTooLarge(name, `${Math.round(MAX_ATTACHMENT_BYTES / (1024 * 1024))} MB`)
+        : labels.fileEmpty(name);
+  }
+}
+
+export function composerTiles(
+  attachments: readonly AliaAttachment[],
+  items: readonly IntakeItem[],
+  labels: TileLabels,
+): ComposerTile[] {
+  return [
+    ...attachments.map((a) => ({
+      id: a.id,
+      name: a.name,
+      kind: a.type === 'image' ? ('image' as const) : ('document' as const),
+      src: a.type === 'image' ? a.uri : undefined,
+    })),
+    ...items.map((item): ComposerTile => {
+      const tile: ComposerTile = {
+        id: item.id,
+        name: item.name || labels.composerUntitled,
+        kind: item.kind === 'image' ? 'image' : 'document',
+      };
+      if (item.status === 'reading') {
+        // Real progress only; an unmeasured read is an empty ring, not a guess.
+        tile.progress = item.fraction === null ? 0 : Math.round(item.fraction * 100);
+        return tile;
+      }
+      tile.error = intakeError(item, labels);
+      tile.retryable = item.status === 'failed';
+      return tile;
+    }),
+  ];
+}

package/src/lib/audio-level.ts

@@ -3,8 +3,8 @@
  * time constants, for every source that drives it.
  *
  * Dictation got here first and is the reference: the microphone's level is
- * taken as dBFS (on web, from an analyser beside the recognizer —
- * `speech-recognition.ts`), normalised against a -60 floor, and `useAmbientWave`
+ * taken as dBFS (on web, from an analyser beside the recorder —
+ * `dictation-recorder.ts`), normalised against a -60 floor, and `useAmbientWave`
  * smooths it with a fast attack and a slow decay before it reaches
  * `AmbientField`. That is the behaviour people like, so it is the behaviour
  * everything else adopts rather than re-invents — including "read aloud", which

package/src/lib/dictation-recorder-types.ts

@@ -0,0 +1,37 @@
+import type { DictationClip } from './dictation';
+
+/** Why the microphone could not record. */
+export type DictationRecorderErrorCode = 'mic-denied' | 'mic-unavailable';
+
+export class DictationRecorderError extends Error {
+  readonly code: DictationRecorderErrorCode;
+
+  constructor(code: DictationRecorderErrorCode, message?: string) {
+    super(message ?? code);
+    this.name = 'DictationRecorderError';
+    this.code = code;
+  }
+}
+
+/**
+ * A clip recorder for the composer's microphone:
+ *
+ * - web (`dictation-recorder.ts`): `MediaRecorder`, `audio/webm;codecs=opus`
+ *   or `audio/mp4` (Safari), level from an `AnalyserNode` on the same stream;
+ * - iOS / Android (`dictation-recorder.native.ts`): the `expo-audio`
+ *   recorder, `RecordingPresets.HIGH_QUALITY` (m4a/AAC → `audio/mp4`) with
+ *   metering on.
+ *
+ * Levels are the real recorder's, 0..1 on the dictation meter's dBFS scale.
+ */
+export interface DictationRecorder {
+  /**
+   * Ask for the microphone and start recording; resolves once the recorder
+   * says it started. Rejects with a {@link DictationRecorderError}.
+   */
+  start(onLevel: (level: number) => void): Promise<void>;
+  /** Stop and hand over the clip, or `null` when nothing was recorded. */
+  stop(): Promise<DictationClip | null>;
+  /** Stop and throw the clip away. */
+  cancel(): void;
+}

package/src/lib/dictation-recorder.native.ts

@@ -0,0 +1,90 @@
+/**
+ * Dictation's iOS / Android recorder: the `expo-audio` recorder (already a
+ * peer of this SDK), `RecordingPresets.HIGH_QUALITY` in mono with metering on.
+ * The clip is m4a/AAC, sent as `audio/mp4`. No new native module: the call's
+ * engine (`react-native-audio-api`) is not needed to record a clip.
+ */
+
+import { useMemo } from 'react';
+import {
+  RecordingPresets,
+  requestRecordingPermissionsAsync,
+  setAudioModeAsync,
+  useAudioRecorder,
+} from 'expo-audio';
+import { levelFromDbfs } from './audio-level';
+import type { DictationClip } from './dictation';
+import { DictationRecorderError, type DictationRecorder } from './dictation-recorder-types';
+
+export * from './dictation-recorder-types';
+
+const LEVEL_POLL_MS = 100;
+
+const OPTIONS = { ...RecordingPresets.HIGH_QUALITY, numberOfChannels: 1, isMeteringEnabled: true };
+
+export function useDictationRecorder(): DictationRecorder {
+  const recorder = useAudioRecorder(OPTIONS);
+
+  return useMemo(() => {
+    let levelTimer: ReturnType<typeof setInterval> | null = null;
+    let lastDurationMs = 0;
+    let recording = false;
+
+    const stopLevels = (): void => {
+      if (levelTimer !== null) clearInterval(levelTimer);
+      levelTimer = null;
+    };
+    const releaseSession = (): void => {
+      void setAudioModeAsync({ allowsRecording: false }).catch(() => undefined);
+    };
+
+    return {
+      async start(onLevel) {
+        const permission = await requestRecordingPermissionsAsync().catch(() => null);
+        if (!permission?.granted) throw new DictationRecorderError('mic-denied');
+        try {
+          await setAudioModeAsync({ allowsRecording: true, playsInSilentMode: true });
+          await recorder.prepareToRecordAsync();
+          recorder.record();
+        } catch {
+          releaseSession();
+          throw new DictationRecorderError('mic-unavailable');
+        }
+        recording = true;
+        lastDurationMs = 0;
+        levelTimer = setInterval(() => {
+          const status = recorder.getStatus();
+          lastDurationMs = status.durationMillis;
+          onLevel(typeof status.metering === 'number' ? levelFromDbfs(status.metering) : 0);
+        }, LEVEL_POLL_MS);
+      },
+
+      async stop(): Promise<DictationClip | null> {
+        if (!recording) return null;
+        recording = false;
+        stopLevels();
+        const durationMs = recorder.getStatus().durationMillis || lastDurationMs;
+        try {
+          await recorder.stop();
+        } finally {
+          releaseSession();
+        }
+        const uri = recorder.uri;
+        if (!uri) return null;
+        return {
+          file: { uri, name: 'dictation.m4a', type: 'audio/mp4' },
+          mediaType: 'audio/mp4',
+          durationMs,
+        };
+      },
+
+      cancel(): void {
+        if (!recording) return;
+        recording = false;
+        stopLevels();
+        void recorder.stop().catch(() => undefined);
+        releaseSession();
+      },
+    };
+  }, [recorder]);
+}