@opengeni/react 0.40.0 → 0.42.1

package/dist/voice-recording-owner.d.ts

@@ -0,0 +1,12 @@
+export declare const VOICE_RECORDING_OWNER_SESSION_KEY = "opengeni.voice-recording-owner.v1";
+export type VoiceRecordingOwnerLease = {
+    ownerId: string;
+    release: () => void;
+};
+/**
+ * Acquire one document-scoped owner identity shared by every voice hook in the
+ * current document. The session-stored candidate survives reload, while the
+ * held lock/handshake prevents opener-created or duplicated tabs from reusing
+ * that identity concurrently.
+ */
+export declare function acquireDefaultVoiceRecordingOwnerLease(): Promise<VoiceRecordingOwnerLease>;

package/dist/voice-recording-store.d.ts

@@ -0,0 +1,124 @@
+export type VoiceRecordingCaptureState = "capturing" | "stopped" | "discarded";
+export type VoiceRecordingUploadState = "pending" | "syncing" | "retrying" | "complete";
+export type VoiceRecordingTranscriptionState = "pending" | "transcribing" | "retrying" | "complete";
+export type VoiceRecordingFinalizationState = "pending" | "transcript-ready" | "handed-off";
+export type VoiceRecordingChunkUploadState = "pending" | "syncing" | "complete";
+export type VoiceRecordingManifest = {
+    version: 1;
+    recordingId: string;
+    workspaceId: string;
+    createdAt: string;
+    updatedAt: string;
+    mimeType: string;
+    codec: string | null;
+    captureState: VoiceRecordingCaptureState;
+    uploadState: VoiceRecordingUploadState;
+    transcriptionState: VoiceRecordingTranscriptionState;
+    finalizationState: VoiceRecordingFinalizationState;
+    /** Tab/process lease. A different owner may take over only after this heartbeat is stale. */
+    ownerId: string | null;
+    ownerHeartbeatAt: string | null;
+    /** Authoritative provider result, persisted before any composer draft mutation. */
+    transcriptText: string | null;
+    nextChunkNumber: number;
+    chunkCount: number;
+    totalBytes: number;
+    totalDurationMilliseconds: number;
+};
+export type VoiceRecordingChunk = {
+    recordingId: string;
+    chunkNumber: number;
+    capturedAt: string;
+    startMilliseconds: number;
+    durationMilliseconds: number;
+    mimeType: string;
+    codec: string | null;
+    byteLength: number;
+    sha256: string;
+    uploadState: VoiceRecordingChunkUploadState;
+    audio: Blob;
+};
+export type PersistVoiceRecordingChunkInput = {
+    recordingId: string;
+    ownerId?: string | undefined;
+    chunkNumber: number;
+    capturedAt: string;
+    startMilliseconds: number;
+    durationMilliseconds: number;
+    mimeType: string;
+    audio: Blob;
+};
+export type PersistVoiceRecordingChunkResult = {
+    manifest: VoiceRecordingManifest;
+    chunk: VoiceRecordingChunk;
+    deduplicated: boolean;
+};
+export interface VoiceRecordingStore {
+    createManifest(manifest: VoiceRecordingManifest): Promise<void>;
+    getManifest(recordingId: string): Promise<VoiceRecordingManifest | null>;
+    listRecoverableManifests(workspaceId: string, ownership?: {
+        ownerId: string;
+        staleBefore: string;
+    }): Promise<VoiceRecordingManifest[]>;
+    claimManifest(recordingId: string, ownerId: string, claimedAt: string, staleBefore: string): Promise<VoiceRecordingManifest>;
+    listChunks(recordingId: string): Promise<VoiceRecordingChunk[]>;
+    persistChunk(input: PersistVoiceRecordingChunkInput): Promise<PersistVoiceRecordingChunkResult>;
+    updateManifest(recordingId: string, update: Partial<Pick<VoiceRecordingManifest, "captureState" | "uploadState" | "transcriptionState" | "finalizationState" | "ownerId" | "ownerHeartbeatAt" | "transcriptText">>, updatedAt: string, ownerId?: string | undefined): Promise<VoiceRecordingManifest>;
+    discard(recordingId: string, ownerId?: string | undefined): Promise<void>;
+    cleanupHandedOffManifests(ownership: {
+        ownerId: string;
+        staleBefore: string;
+    }): Promise<number>;
+    close(): Promise<void>;
+}
+export declare class VoiceRecordingStorageUnavailableError extends Error {
+    constructor();
+}
+export declare class VoiceRecordingNotFoundError extends Error {
+    constructor(recordingId: string);
+}
+export declare class VoiceRecordingChunkConflictError extends Error {
+    constructor(recordingId: string, chunkNumber: number);
+}
+export declare class VoiceRecordingChunkSequenceError extends Error {
+    constructor(expected: number, received: number);
+}
+export declare class VoiceRecordingOwnedError extends Error {
+    constructor(recordingId: string);
+}
+export declare function createVoiceRecordingManifest(input: {
+    recordingId: string;
+    workspaceId: string;
+    mimeType: string;
+    createdAt: string;
+    ownerId?: string | null | undefined;
+}): VoiceRecordingManifest;
+export declare function prepareVoiceRecordingChunk(input: PersistVoiceRecordingChunkInput): Promise<VoiceRecordingChunk>;
+export declare function planVoiceRecordingChunkCommit(input: {
+    manifest: VoiceRecordingManifest;
+    chunk: VoiceRecordingChunk;
+    existingChunk: VoiceRecordingChunk | null;
+}): PersistVoiceRecordingChunkResult;
+export declare class IndexedDbVoiceRecordingStore implements VoiceRecordingStore {
+    private readonly database;
+    constructor(options?: {
+        indexedDB?: IDBFactory | null;
+        databaseName?: string;
+    });
+    createManifest(manifest: VoiceRecordingManifest): Promise<void>;
+    getManifest(recordingId: string): Promise<VoiceRecordingManifest | null>;
+    listRecoverableManifests(workspaceId: string, ownership?: {
+        ownerId: string;
+        staleBefore: string;
+    }): Promise<VoiceRecordingManifest[]>;
+    claimManifest(recordingId: string, ownerId: string, claimedAt: string, staleBefore: string): Promise<VoiceRecordingManifest>;
+    listChunks(recordingId: string): Promise<VoiceRecordingChunk[]>;
+    persistChunk(input: PersistVoiceRecordingChunkInput): Promise<PersistVoiceRecordingChunkResult>;
+    updateManifest(recordingId: string, update: Partial<Pick<VoiceRecordingManifest, "captureState" | "uploadState" | "transcriptionState" | "finalizationState" | "ownerId" | "ownerHeartbeatAt" | "transcriptText">>, updatedAt: string, ownerId?: string | undefined): Promise<VoiceRecordingManifest>;
+    discard(recordingId: string, ownerId?: string | undefined): Promise<void>;
+    cleanupHandedOffManifests(ownership: {
+        ownerId: string;
+        staleBefore: string;
+    }): Promise<number>;
+    close(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/react",
-  "version": "0.40.0",
+  "version": "0.42.1",
   "description": "React hooks and styled components for OpenGeni: live session streaming, chat composer, message timeline, session status, and fleet views — token-themed (CSS variables), dark-first, built on Tailwind v4 + Radix + Motion.",
   "license": "Apache-2.0",
   "repository": {
@@ -75,7 +75,7 @@
     "@dnd-kit/utilities": "3.2.2",
     "@fontsource-variable/noto-sans-arabic": "5.2.10",
     "@fontsource-variable/noto-sans-jp": "5.2.10",
-    "@opengeni/sdk": "^0.40.0",
+    "@opengeni/sdk": "^0.42.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.8.0",
     "motion": "^12.0.0",

package/src/components/composer-transcription-control.tsx

@@ -4,11 +4,20 @@ import type {
   TranscriptionAdapter,
   WorkspaceTranscriptionPolicy,
 } from "@opengeni/sdk";
-import { LoaderCircleIcon, MicIcon, SquareIcon, XIcon } from "lucide-react";
+import {
+  ClipboardPasteIcon,
+  LoaderCircleIcon,
+  MicIcon,
+  RefreshCwIcon,
+  SquareIcon,
+  Trash2Icon,
+  XIcon,
+} from "lucide-react";
 import { AnimatePresence, motion } from "motion/react";
 import { useEffect, useState, type MouseEvent, type ReactElement } from "react";
 import { cn } from "../lib/cn";
 import { useVoiceInput } from "../hooks/use-voice-input";
+import type { VoiceRecordingStore } from "../voice-recording-store";
 import { useChatComposer } from "./composer";
 import { Tooltip, TooltipContent, TooltipTrigger } from "./tooltip";
 
@@ -28,7 +37,12 @@ export type ComposerTranscriptionMessages = {
   retry: string;
   requestingPermission: string;
   recording: string;
+  saving: string;
   transcribing: string;
+  recovered: string;
+  recoveredTranscript: string;
+  insertRecoveredTranscript: string;
+  discardRecovered: string;
   unavailableDisabled: string;
   unavailable: string;
   errorPermissionDenied: string;
@@ -36,6 +50,9 @@ export type ComposerTranscriptionMessages = {
   errorUnavailable: string;
   errorTooLarge: string;
   errorInvalidAudio: string;
+  errorStorageUnavailable: string;
+  errorRetryable: string;
+  errorHandoffUncertain: string;
   errorUnknown: string;
 };
 
@@ -46,7 +63,12 @@ const defaultMessages: ComposerTranscriptionMessages = {
   retry: "Retry voice input",
   requestingPermission: "Requesting microphone…",
   recording: "Recording. Press Escape to cancel.",
+  saving: "Saving audio locally…",
   transcribing: "Transcribing…",
+  recovered: "Recording recovered and saved locally.",
+  recoveredTranscript: "Transcript saved locally. Check your draft before inserting.",
+  insertRecoveredTranscript: "Insert saved transcript",
+  discardRecovered: "Discard saved recording",
   unavailableDisabled: "Voice input is unavailable while the composer is disabled.",
   unavailable: "Voice input is unavailable for this workspace.",
   errorPermissionDenied: "Microphone permission was denied. Your draft was not changed.",
@@ -54,6 +76,9 @@ const defaultMessages: ComposerTranscriptionMessages = {
   errorUnavailable: "Voice input is not configured.",
   errorTooLarge: "Recording is too large. Try a shorter message.",
   errorInvalidAudio: "The recording could not be read. Try again.",
+  errorStorageUnavailable: "Voice input stopped because audio could not be saved safely.",
+  errorRetryable: "Recording is saved locally. Retry transcription when ready.",
+  errorHandoffUncertain: "Transcript is saved. Check your draft before inserting it again.",
   errorUnknown: "Voice input could not start. Try again.",
 };
 
@@ -72,6 +97,10 @@ export type ComposerTranscriptionControlProps = {
   onDiagnostic?: unknown;
   messages?: Partial<ComposerTranscriptionMessages> | undefined;
   className?: string | undefined;
+  /** Test/embed seam. Production defaults to origin-scoped IndexedDB. */
+  createRecordingStore?: (() => VoiceRecordingStore) | undefined;
+  /** Test/embed seam. Production acquires a coordinated browser-document owner lease. */
+  createOwnerId?: (() => string) | undefined;
 };
 
 const WAVEFORM_BARS = 18;
@@ -88,6 +117,8 @@ export function ComposerTranscriptionControl({
   workspaceEnabled = false,
   messages: overrides,
   className,
+  createRecordingStore,
+  createOwnerId,
 }: ComposerTranscriptionControlProps) {
   const composer = useChatComposer();
   const messages = { ...defaultMessages, ...overrides };
@@ -100,15 +131,26 @@ export function ComposerTranscriptionControl({
     setValue: composer.setValue,
     focusInput: composer.focusInput,
     disabled: composer.disabled,
+    createRecordingStore,
+    createOwnerId,
   });
   const { status } = transcription;
   const active =
-    status === "requesting-permission" || status === "recording" || status === "transcribing";
+    status === "requesting-permission" ||
+    status === "recording" ||
+    status === "saving" ||
+    status === "transcribing";
+  const recoverable =
+    transcription.hasRecoverableRecording &&
+    (status === "recovered" || status === "transcript-ready" || status === "error");
+  const savedTranscript = status === "transcript-ready" && transcription.savedTranscript !== null;
   const unavailableMessage = composer.disabled
     ? messages.unavailableDisabled
     : !capability?.available || !workspaceEnabled
       ? messages.unavailable
-      : null;
+      : !transcription.available
+        ? messages.errorStorageUnavailable
+        : null;
   const idleLabel = unavailableMessage ?? (status === "error" ? messages.retry : messages.start);
   const errorMessage = transcription.error
     ? transcriptionErrorMessage(transcription.error, messages)
@@ -118,11 +160,17 @@ export function ComposerTranscriptionControl({
       ? messages.requestingPermission
       : status === "recording"
         ? messages.recording
-        : status === "transcribing"
-          ? messages.transcribing
-          : status === "error"
-            ? (errorMessage ?? messages.errorUnknown)
-            : unavailableMessage;
+        : status === "saving"
+          ? messages.saving
+          : status === "transcribing"
+            ? messages.transcribing
+            : status === "recovered"
+              ? messages.recovered
+              : status === "transcript-ready"
+                ? messages.recoveredTranscript
+                : status === "error"
+                  ? (errorMessage ?? messages.errorUnknown)
+                  : unavailableMessage;
 
   function start(event: MouseEvent<HTMLButtonElement>) {
     if (unavailableMessage) {
@@ -138,16 +186,72 @@ export function ComposerTranscriptionControl({
       data-transcription-status={status}
     >
       <AnimatePresence mode="popLayout" initial={false}>
-        {active ? (
+        {recoverable ? (
           <motion.span
-            key={status === "transcribing" ? "transcribing" : "capture"}
+            key="recovered"
+            initial={{ opacity: 0, scale: 0.96 }}
+            animate={{ opacity: 1, scale: 1 }}
+            exit={{ opacity: 0, scale: 0.96 }}
+            transition={{ duration: 0.16, ease: [0.22, 1, 0.36, 1] }}
+            className={cn(
+              "inline-flex h-8 min-w-0 items-center gap-1 rounded-og-md border border-og-border/80",
+              "bg-og-surface-2/70 pl-2 pr-1 pointer-coarse:h-11",
+            )}
+          >
+            <span className="max-w-44 truncate text-og-xs text-og-fg-muted max-sm:max-w-28">
+              {savedTranscript
+                ? (errorMessage ?? messages.recoveredTranscript)
+                : status === "error"
+                  ? (errorMessage ?? messages.errorRetryable)
+                  : messages.recovered}
+            </span>
+            <Tip tip={savedTranscript ? messages.insertRecoveredTranscript : messages.retry}>
+              <button
+                type="button"
+                onClick={() =>
+                  savedTranscript
+                    ? void transcription.insertSavedTranscript()
+                    : transcription.retry()
+                }
+                aria-label={savedTranscript ? messages.insertRecoveredTranscript : messages.retry}
+                className={cn(
+                  "inline-flex size-7 shrink-0 items-center justify-center rounded-og-sm",
+                  "bg-og-fg text-og-bg transition-colors duration-150 motion-reduce:transition-none",
+                  "hover:bg-og-fg-muted pointer-coarse:size-11",
+                )}
+              >
+                {savedTranscript ? (
+                  <ClipboardPasteIcon className="size-3.5" />
+                ) : (
+                  <RefreshCwIcon className="size-3.5" />
+                )}
+              </button>
+            </Tip>
+            <Tip tip={messages.discardRecovered}>
+              <button
+                type="button"
+                onClick={() => void transcription.discard()}
+                aria-label={messages.discardRecovered}
+                className={cn(
+                  "inline-flex size-7 shrink-0 items-center justify-center rounded-og-sm",
+                  "text-og-fg-muted transition-colors duration-150 motion-reduce:transition-none",
+                  "hover:bg-og-surface-3 hover:text-og-status-failed pointer-coarse:size-11",
+                )}
+              >
+                <Trash2Icon className="size-3.5" />
+              </button>
+            </Tip>
+          </motion.span>
+        ) : active ? (
+          <motion.span
+            key={status === "transcribing" || status === "saving" ? "processing" : "capture"}
             initial={{ opacity: 0, scale: 0.96 }}
             animate={{ opacity: 1, scale: 1 }}
             exit={{ opacity: 0, scale: 0.96 }}
             transition={{ duration: 0.16, ease: [0.22, 1, 0.36, 1] }}
             className={cn(
               "inline-flex h-8 items-center gap-1 rounded-og-md border border-og-border/80",
-              "bg-og-surface-2/70 pl-2 pr-1 pointer-coarse:h-9",
+              "bg-og-surface-2/70 pl-2 pr-1 pointer-coarse:h-11",
             )}
           >
             {status === "requesting-permission" ? (
@@ -165,7 +269,7 @@ export function ComposerTranscriptionControl({
                 ) : null}
                 <VoiceWaveform
                   stream={status === "recording" ? transcription.stream : null}
-                  mode={status === "transcribing" ? "transcribing" : "recording"}
+                  mode={status === "recording" ? "recording" : "transcribing"}
                 />
               </span>
             )}
@@ -180,7 +284,7 @@ export function ComposerTranscriptionControl({
                     className={cn(
                       "inline-flex size-7 shrink-0 items-center justify-center rounded-og-sm",
                       "text-og-fg-muted transition-colors duration-150 motion-reduce:transition-none",
-                      "hover:bg-og-surface-3 hover:text-og-fg pointer-coarse:size-9",
+                      "hover:bg-og-surface-3 hover:text-og-fg pointer-coarse:size-11",
                     )}
                   >
                     <XIcon className="size-3.5" />
@@ -194,16 +298,16 @@ export function ComposerTranscriptionControl({
                     className={cn(
                       "inline-flex size-7 shrink-0 items-center justify-center rounded-og-sm",
                       "bg-og-fg text-og-bg transition-colors duration-150 motion-reduce:transition-none",
-                      "hover:bg-og-fg-muted pointer-coarse:size-9",
+                      "hover:bg-og-fg-muted pointer-coarse:size-11",
                     )}
                   >
                     <SquareIcon className="size-2.5 fill-current" />
                   </button>
                 </Tip>
               </>
-            ) : status === "transcribing" ? (
+            ) : status === "transcribing" || status === "saving" ? (
               <span className="og-shimmer-text px-1.5 text-og-xs font-medium whitespace-nowrap">
-                {messages.transcribing}
+                {status === "saving" ? messages.saving : messages.transcribing}
               </span>
             ) : (
               <span className="px-1.5 text-og-xs text-og-fg-muted whitespace-nowrap">
@@ -224,7 +328,7 @@ export function ComposerTranscriptionControl({
               aria-pressed={false}
               aria-disabled={unavailableMessage !== null}
               className={cn(
-                "inline-flex size-8 shrink-0 items-center justify-center rounded-og-md pointer-coarse:size-9",
+                "inline-flex size-8 shrink-0 items-center justify-center rounded-og-md pointer-coarse:size-11",
                 "text-og-fg-muted transition-colors duration-150 motion-reduce:transition-none",
                 unavailableMessage
                   ? "cursor-not-allowed opacity-45"
@@ -236,7 +340,7 @@ export function ComposerTranscriptionControl({
           </Tip>
         )}
       </AnimatePresence>
-      {status === "error" && errorMessage ? (
+      {status === "error" && errorMessage && !recoverable ? (
         <Tip tip={errorMessage}>
           <span
             aria-hidden="true"
@@ -364,6 +468,14 @@ function transcriptionErrorMessage(code: string, messages: ComposerTranscription
       return messages.errorTooLarge;
     case "invalid_audio":
       return messages.errorInvalidAudio;
+    case "storage_unavailable":
+      return messages.errorStorageUnavailable;
+    case "network":
+    case "provider":
+    case "timeout":
+      return messages.errorRetryable;
+    case "handoff_uncertain":
+      return messages.errorHandoffUncertain;
     case "unknown":
       return messages.errorUnknown;
     default:

package/src/composer.ts

@@ -71,9 +71,38 @@ export type {
   ComposerTranscriptionControlProps,
   ComposerTranscriptionMessages,
 } from "./components/composer-transcription-control";
-export { useVoiceInput } from "./hooks/use-voice-input";
+export {
+  VOICE_RECORDING_CLIENT_MAX_DURATION_SECONDS,
+  VOICE_RECORDING_OWNER_HEARTBEAT_MILLISECONDS,
+  VOICE_RECORDING_OWNER_STALE_MILLISECONDS,
+  VOICE_RECORDING_TIMESLICE_MILLISECONDS,
+  useVoiceInput,
+} from "./hooks/use-voice-input";
 export type {
   UseVoiceInputOptions,
   UseVoiceInputResult,
   VoiceInputStatus,
 } from "./hooks/use-voice-input";
+export {
+  IndexedDbVoiceRecordingStore,
+  VoiceRecordingChunkConflictError,
+  VoiceRecordingChunkSequenceError,
+  VoiceRecordingNotFoundError,
+  VoiceRecordingOwnedError,
+  VoiceRecordingStorageUnavailableError,
+  createVoiceRecordingManifest,
+  planVoiceRecordingChunkCommit,
+  prepareVoiceRecordingChunk,
+} from "./voice-recording-store";
+export type {
+  PersistVoiceRecordingChunkInput,
+  PersistVoiceRecordingChunkResult,
+  VoiceRecordingCaptureState,
+  VoiceRecordingChunk,
+  VoiceRecordingChunkUploadState,
+  VoiceRecordingFinalizationState,
+  VoiceRecordingManifest,
+  VoiceRecordingStore,
+  VoiceRecordingTranscriptionState,
+  VoiceRecordingUploadState,
+} from "./voice-recording-store";