@nualang/nualang-ui-components 0.1.1420 → 0.1.1421

package/README.md

@@ -35,6 +35,37 @@ If webapp is caching previous versions (Add a character to the end of the .tgz,
 pnpm add ../ui-components/nualang-ui-components-0.1.XXXa.tgz
 ```
 
+## Local Development with `npm link`
+Links this repo directly into `app`, so changes here show up instantly with no
+repacking or reinstalling. Requires both repos cloned as sibling folders
+(`ui-components` and `app` side by side, same parent directory).
+
+1. **Here in `ui-components`**, start the watcher (it cleans `dist/` before its first
+   compile, so it's always safe to run - no separate build step needed):
+   ```bash
+   pnpm run watch     # leave this running
+   ```
+2. **In `app`**, link it in and start the dev server:
+   ```bash
+   npm run link:ui-components
+   npm start
+   ```
+3. Edit a component here under `src/` and save - it recompiles automatically, `app`'s
+   dev server rebuilds, and a browser reload shows your change.
+4. **In `app`** when you're done, switch back to the published version:
+   ```bash
+   npm run unlink:ui-components
+   ```
+
+**If you delete or rename a file while the watcher is already running**, restart
+`pnpm run watch`. Babel's `--watch` mode only ever adds/updates compiled output - it
+never removes a stale file from `dist/` for a source file that's gone, which can leave
+`app` resolving a module that no longer exists in `src/`. Restarting re-runs the clean
+step and fixes it.
+
+Heads up: an `npm install` in `app` will quietly replace the link with the published
+version - just re-run `npm run link:ui-components` to relink.
+
 ## Publish to npm
 Normall, you should just update the version number in package.json and commit
 your updates. When you updated are merged to main, gitlab CI/CD will add a

package/dist/Chat/BottomBar/BottomBar.js

@@ -9,6 +9,7 @@ import Tooltip from "@mui/material/Tooltip";
 import Divider from "@mui/material/Divider";
 import Paper from "@mui/material/Paper";
 import Typography from "@mui/material/Typography";
+import CircularProgress from "@mui/material/CircularProgress";
 import MicIcon from "@mui/icons-material/Mic";
 import MicOffIcon from "@mui/icons-material/MicOff";
 import SendIcon from "@mui/icons-material/Send";
@@ -81,6 +82,7 @@ export default function BottomBar({
   handleKeyPress,
   handleUpdate,
   isListening,
+  isMicBusy = false,
   handleAttachFile,
   handleRecord,
   handleAdd,
@@ -131,6 +133,11 @@ export default function BottomBar({
   const textInput = useRef(null);
   const activeRef = inputRef ? inputRef : textInput;
   const isSmallScreen = useMediaQuery(theme.breakpoints.down("md"));
+
+  // isMicBusy spans the async mic start/stop window (permission prompt,
+  // audio worklet setup, socket teardown) - without this the button just
+  // goes inert with no explanation.
+  const micButtonLabel = isMicBusy ? t("loading") : isListening ? t("click_to_stop") : t("click_to_speak");
   const TextInput = /*#__PURE__*/_jsx("div", {
     className: classes.input,
     id: "keyboardInput",
@@ -236,7 +243,6 @@ export default function BottomBar({
           children: isSmallScreen ? /*#__PURE__*/_jsx(_Fragment, {
             children: /*#__PURE__*/_jsx(IconButton, {
               sx: {
-                color: isListening ? "red" : "inherit",
                 animation: showMicReminder ? "reminder 1.6s ease-in-out infinite" : "none",
                 "@keyframes reminder": {
                   "0%": {
@@ -253,24 +259,27 @@ export default function BottomBar({
               onClick: onClickRecord,
               edge: "start",
               id: "voiceInput",
+              color: isListening ? "error" : "inherit",
               disabled: disableInput,
+              "aria-busy": isMicBusy,
+              "aria-label": micButtonLabel,
               size: "large",
               ref: buttonRef,
-              children: isListening ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(MicIcon, {})
+              children: isMicBusy ? /*#__PURE__*/_jsx(CircularProgress, {
+                size: 20,
+                color: "inherit"
+              }) : isListening ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(MicIcon, {})
             })
           }) : /*#__PURE__*/_jsx(_Fragment, {
             children: /*#__PURE__*/_jsx(Button, {
               sx: {
-                color: "white",
-                backgroundColor: isListening ? "#d32f2f" : "#2d7b30",
                 padding: 1,
                 paddingLeft: 2,
                 paddingRight: 2,
                 borderRadius: 3,
-                border: "1.5px solid black",
+                border: "1.5px solid transparent",
                 "&:hover": {
-                  backgroundColor: isListening ? "#d32f2f" : "#2d7b30",
-                  border: "1.5px solid white"
+                  border: "1.5px solid black"
                 },
                 animation: showMicReminder ? "reminder 1.6s ease-in-out infinite" : "none",
                 "@keyframes reminder": {
@@ -286,18 +295,22 @@ export default function BottomBar({
                 }
               },
               onClick: onClickRecord,
-              startIcon: isListening ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(MicIcon, {}),
+              startIcon: isMicBusy ? /*#__PURE__*/_jsx(CircularProgress, {
+                size: 20,
+                color: "inherit"
+              }) : isListening ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(MicIcon, {}),
               color: isListening ? "error" : "success",
               disabled: disableInput,
+              "aria-busy": isMicBusy,
               variant: "contained",
               id: "voiceInput",
               ref: buttonRef,
-              children: isListening ? t("click_to_stop") : t("click_to_speak")
+              children: micButtonLabel
             })
           })
         }), /*#__PURE__*/_jsx(Typography, {
           sx: {
-            marginLeft: 1.5,
+            marginLeft: isSmallScreen ? 0.75 : 1.5,
             marginRight: 1,
             my: "auto",
             fontWeight: "bold"

package/dist/Chat/Chat.js

@@ -23,6 +23,7 @@ function Chat({
   handleBack,
   handleClose,
   handleRecord,
+  isMicBusy = false,
   handleAdd,
   handleSend,
   handleUpdate,
@@ -178,6 +179,7 @@ function Chat({
       focusInput: focusInput,
       handleInputChange: handleInputChange,
       isListening: isListening,
+      isMicBusy: isMicBusy,
       handleRecord: handleRecord,
       handleSend: handleSend,
       handleAdd: handleAdd,

package/dist/Exercises/Bot/Bot.js

@@ -606,6 +606,7 @@ function Bot({
         t: t,
         authenticated: authenticated,
         disableInput: !authenticated || isSpeaking || isRecognizingDisabled ? true : false,
+        isMicBusy: isRecognizingDisabled,
         messages: botMessages,
         placeholder: !recognizing ? placeholder : "",
         translationEnabled: isTranslationEnabled,

package/dist/Exercises/ListenAndSpeak/ListenAndSpeak.js

@@ -2,7 +2,7 @@ import { useState, useEffect, useRef } from "react";
 import { Joyride, STATUS } from "react-joyride";
 import { makeStyles } from "tss-react/mui";
 import { useTheme } from "@mui/material/styles";
-import { Grid, Slide, IconButton, Button, Toolbar, AppBar, Dialog, Typography, Box, Tooltip } from "@mui/material";
+import { Grid, Slide, IconButton, Button, Toolbar, AppBar, Dialog, Typography, Box, Tooltip, CircularProgress } from "@mui/material";
 import { styled } from "@mui/system";
 import LightbulbIcon from "@mui/icons-material/Lightbulb";
 import Replay from "@mui/icons-material/Replay";
@@ -227,9 +227,12 @@ function ListenAndSpeak({
       });
     }
     if (recognizing && interimTranscript === "" && finalTranscript === "") {
-      // Set a timer to stop listening if no audio is detected after 10 seconds
+      // Set a timer to stop listening if no audio is detected after 10 seconds.
+      // Without the snackbar here the mic just switches off with no
+      // explanation, indistinguishable from the student stopping it themselves.
       timer = setTimeout(() => {
         stopListening();
+        openSnackbar?.("We didn't hear anything, please try again.", "warning");
       }, 10000);
     }
     return () => clearTimeout(timer);
@@ -455,6 +458,12 @@ function ListenAndSpeak({
     }
   };
   const isListeningIndicatorTextVisible = recognizing && interimTranscript === "" && finalTranscript === "" ? true : false;
+
+  // isRecognizingDisabled spans the async mic start/stop window (permission
+  // prompt, audio worklet setup, socket teardown) - without a distinct label
+  // and icon here the button just goes inert with no explanation.
+  const isMicBusy = isRecognizingDisabled;
+  const micButtonLabel = isMicBusy ? t("loading") : recognizing ? t("click_to_stop") : t("click_to_speak");
   const navigate = useNavigate();
   const goBackToAssignment = () => {
     navigate(`/classrooms/${classroomId}#Assignments`);
@@ -696,32 +705,33 @@ function ListenAndSpeak({
               [theme.breakpoints.down("md")]: {
                 height: "50px",
                 width: "200px",
-                color: "white",
                 padding: 2,
                 fontSize: "16px",
                 borderRadius: 3
               },
               height: "70px",
               width: "250px",
-              color: "white",
-              backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
               padding: 1,
               fontSize: "20px",
               borderRadius: 5,
               border: "1.5px solid transparent",
               "&:hover": {
-                backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
                 border: "1.5px solid black"
               }
             }),
             onClick: () => handleMic(currentPhrase ? currentPhrase.phrase : ""),
-            startIcon: recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
+            startIcon: isMicBusy ? /*#__PURE__*/_jsx(CircularProgress, {
+              size: 20,
+              color: "inherit"
+            }) : recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
             color: recognizing ? "error" : "success",
             disabled: isSpeaking || !isSocketConnected || isRecognizingDisabled,
+            "aria-busy": isMicBusy,
+            "aria-label": micButtonLabel,
             id: "voiceInput",
             variant: "contained",
             ref: btnRef,
-            children: recognizing ? t("click_to_stop") : t("click_to_speak")
+            children: micButtonLabel
           })
         }), /*#__PURE__*/_jsx(Grid, {
           children: /*#__PURE__*/_jsx(Typography, {

package/dist/Exercises/Pronouncer/Pronouncer.js

@@ -2,7 +2,7 @@ import { useState, useEffect, useRef } from "react";
 import { Joyride, STATUS } from "react-joyride";
 import { makeStyles } from "tss-react/mui";
 import { useTheme } from "@mui/material/styles";
-import { Grid, Slide, IconButton, Button, Toolbar, AppBar, Dialog, Typography, Box, Tooltip } from "@mui/material";
+import { Grid, Slide, IconButton, Button, Toolbar, AppBar, Dialog, Typography, Box, Tooltip, CircularProgress } from "@mui/material";
 import { styled } from "@mui/system";
 import LightbulbIcon from "@mui/icons-material/Lightbulb";
 import Replay from "@mui/icons-material/Replay";
@@ -228,9 +228,12 @@ function Pronouncer({
       });
     }
     if (recognizing && interimTranscript === "" && finalTranscript === "") {
-      // Set a timer to stop listening if no audio is detected after 10 seconds
+      // Set a timer to stop listening if no audio is detected after 10 seconds.
+      // Without the snackbar here the mic just switches off with no
+      // explanation, indistinguishable from the student stopping it themselves.
       timer = setTimeout(() => {
         stopListening();
+        openSnackbar?.("We didn't hear anything, please try again.", "warning");
       }, 10000);
     }
     return () => clearTimeout(timer);
@@ -467,6 +470,12 @@ function Pronouncer({
     }
   };
   const isListeningIndicatorTextVisible = recognizing && interimTranscript === "" && finalTranscript === "" ? true : false;
+
+  // isRecognizingDisabled spans the async mic start/stop window (permission
+  // prompt, audio worklet setup, socket teardown) - without a distinct label
+  // and icon here the button just goes inert with no explanation.
+  const isMicBusy = isRecognizingDisabled;
+  const micButtonLabel = isMicBusy ? t("loading") : recognizing ? t("click_to_stop") : t("click_to_speak");
   const navigate = useNavigate();
   const goBackToAssignment = () => {
     navigate(`/classrooms/${classroomId}#Assignments`);
@@ -751,32 +760,33 @@ function Pronouncer({
               [theme.breakpoints.down("md")]: {
                 height: "50px",
                 width: "200px",
-                color: "white",
                 padding: 2,
                 fontSize: "16px",
                 borderRadius: 3
               },
               height: "70px",
               width: "250px",
-              color: "white",
-              backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
               padding: 1,
               fontSize: "20px",
               borderRadius: 5,
               border: "1.5px solid transparent",
               "&:hover": {
-                backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
                 border: "1.5px solid black"
               }
             }),
             onClick: () => handleMic(currentPhrase ? currentPhrase.phrase : ""),
-            startIcon: recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
+            startIcon: isMicBusy ? /*#__PURE__*/_jsx(CircularProgress, {
+              size: 20,
+              color: "inherit"
+            }) : recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
             color: recognizing ? "error" : "success",
             disabled: isSpeaking || !isSocketConnected || isRecognizingDisabled,
+            "aria-busy": isMicBusy,
+            "aria-label": micButtonLabel,
             id: "voiceInput",
             variant: "contained",
             ref: btnRef,
-            children: recognizing ? t("click_to_stop") : t("click_to_speak")
+            children: micButtonLabel
           })
         }), /*#__PURE__*/_jsx(Grid, {
           children: /*#__PURE__*/_jsx(Typography, {

package/dist/Exercises/Roleplay/Games/ActItOutGameListeningAndSpeaking/ActItOutGame.js

@@ -1,5 +1,5 @@
 import { useState, useEffect, useRef } from "react";
-import { Box, Button, Typography, Grid, Avatar, Dialog } from "@mui/material";
+import { Box, Button, Typography, Grid, Avatar, Dialog, CircularProgress } from "@mui/material";
 import { makeStyles } from "tss-react/mui";
 import Person from "@mui/icons-material/Person";
 import Mic from "@mui/icons-material/Mic";
@@ -101,6 +101,12 @@ function AnswerOptions({
       buttonRef.current.focus();
     }
   }, [isSpeaking, isSocketConnected]);
+
+  // isRecognizingDisabled spans the async mic start/stop window (permission
+  // prompt, audio worklet setup, socket teardown) - without a distinct label
+  // and icon here the button just goes inert with no explanation.
+  const isMicBusy = isRecognizingDisabled;
+  const micButtonLabel = isMicBusy ? t("loading") : recognizing ? t("click_to_stop") : t("click_to_speak");
   return /*#__PURE__*/_jsxs(Box, {
     sx: theme => ({
       display: "flex",
@@ -176,27 +182,28 @@ function AnswerOptions({
       children: [/*#__PURE__*/_jsx(Button, {
         sx: theme => ({
           [theme.breakpoints.down("md")]: {
-            color: "white",
             borderRadius: 3
           },
-          color: "white",
-          backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
           mb: theme.spacing(2),
           border: "1.5px solid transparent",
           "&:hover": {
-            backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
             border: "1.5px solid black"
           }
         }),
         onClick: () => handleMic(text),
-        startIcon: recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
+        startIcon: isMicBusy ? /*#__PURE__*/_jsx(CircularProgress, {
+          size: 20,
+          color: "inherit"
+        }) : recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
         color: recognizing ? "error" : "success",
         disabled: isSpeaking || !isSocketConnected || isRecognizingDisabled,
         id: "voiceInput",
         variant: "contained",
         size: "large",
         ref: buttonRef,
-        children: recognizing ? t("click_to_stop") : t("click_to_speak")
+        "aria-busy": isMicBusy,
+        "aria-label": micButtonLabel,
+        children: micButtonLabel
       }), /*#__PURE__*/_jsx(Typography, {
         role: "status",
         variant: "h6",
@@ -434,9 +441,12 @@ function RoleplayGame({
   useEffect(() => {
     let timer;
     if (recognizing && interimTranscript === "" && finalTranscript === "") {
-      // Set a timer to stop listening if no audio is detected after 10 seconds
+      // Set a timer to stop listening if no audio is detected after 10 seconds.
+      // Without the snackbar here the mic just switches off with no
+      // explanation, indistinguishable from the student stopping it themselves.
       timer = setTimeout(() => {
         stopListening();
+        openSnackbar?.("We didn't hear anything, please try again.", "warning");
       }, 10000);
     }
     return () => clearTimeout(timer);

package/dist/Exercises/Roleplay/Games/ActItOutGameSpeaking/ActItOutGame.js

@@ -1,5 +1,5 @@
 import { useState, useEffect, useRef } from "react";
-import { Box, Button, Typography, Grid, Avatar, Dialog } from "@mui/material";
+import { Box, Button, Typography, Grid, Avatar, Dialog, CircularProgress } from "@mui/material";
 import { makeStyles } from "tss-react/mui";
 import Person from "@mui/icons-material/Person";
 import RecordVoiceOverIcon from "@mui/icons-material/RecordVoiceOver";
@@ -92,6 +92,12 @@ function AnswerOptions({
       buttonRef.current.focus();
     }
   }, [isSpeaking, isSocketConnected]);
+
+  // isRecognizingDisabled spans the async mic start/stop window (permission
+  // prompt, audio worklet setup, socket teardown) - without a distinct label
+  // and icon here the button just goes inert with no explanation.
+  const isMicBusy = isRecognizingDisabled;
+  const micButtonLabel = isMicBusy ? t("loading") : recognizing ? t("click_to_stop") : t("click_to_speak");
   return /*#__PURE__*/_jsxs(Box, {
     sx: theme => ({
       display: "flex",
@@ -167,28 +173,28 @@ function AnswerOptions({
       children: [/*#__PURE__*/_jsx(Button, {
         sx: theme => ({
           [theme.breakpoints.down("md")]: {
-            color: "white",
             borderRadius: 3
           },
-          color: "white",
-          backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
           mb: theme.spacing(2),
           border: "1.5px solid transparent",
           "&:hover": {
-            backgroundColor: recognizing ? "#d32f2f" : "#2d7b30",
             border: "1.5px solid black"
           }
         }),
         onClick: () => handleMic(text),
-        startIcon: recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
+        startIcon: isMicBusy ? /*#__PURE__*/_jsx(CircularProgress, {
+          size: 20,
+          color: "inherit"
+        }) : recognizing ? /*#__PURE__*/_jsx(MicOffIcon, {}) : /*#__PURE__*/_jsx(Mic, {}),
         color: recognizing ? "error" : "success",
         disabled: isSpeaking || !isSocketConnected || isRecognizingDisabled,
         id: "voiceInput",
         variant: "contained",
         size: "large",
         ref: buttonRef,
-        "aria-label": ariaLiveText,
-        children: recognizing ? t("click_to_stop") : t("click_to_speak")
+        "aria-busy": isMicBusy,
+        "aria-label": ariaLiveText || micButtonLabel,
+        children: micButtonLabel
       }), /*#__PURE__*/_jsx(Typography, {
         role: "status",
         variant: "h6",
@@ -427,9 +433,12 @@ function RoleplayGame({
   useEffect(() => {
     let timer;
     if (recognizing && interimTranscript === "" && finalTranscript === "") {
-      // Set a timer to stop listening if no audio is detected after 10 seconds
+      // Set a timer to stop listening if no audio is detected after 10 seconds.
+      // Without the snackbar here the mic just switches off with no
+      // explanation, indistinguishable from the student stopping it themselves.
       timer = setTimeout(() => {
         stopListening();
+        openSnackbar?.("We didn't hear anything, please try again.", "warning");
       }, 10000);
     }
     return () => clearTimeout(timer);

package/dist/hooks/useRecognition.js

@@ -9,7 +9,7 @@ const ENDPOINT = import.meta.env.REACT_APP_GCLOUD_SPEECH || "wss://speech-rec-se
 const socket = io(ENDPOINT, {
   withCredentials: true,
   autoConnect: false,
-  transports: ["websocket"] // use WebSocket only
+  transports: ["websocket", "polling"] // use WebSocket, fallback to polling if necessary
 });
 socket.on("connect_error", error => {
   // revert to classic upgrade
@@ -54,6 +54,24 @@ export default function useRecognition(props = {}) {
   const stopAudioRecordingTimeoutIdRef = useRef();
   const streamRef = useRef();
   const serverErrorRef = useRef();
+  const hasAlertedConnectionErrorRef = useRef(false);
+  // Guards against a second click landing during the async start-up window,
+  // before recognizing/isRecognizingDisabled state has re-rendered the button.
+  const isStartingRef = useRef(false);
+
+  // Lets us query, e.g., how often students end up on the polling fallback
+  // (a proxy for "couldn't connect via websocket") or hit connect errors.
+  function trackConnectionDiagnostics(eventName, extra = {}) {
+    if (typeof trackRecommendedEvent !== "function") {
+      return;
+    }
+    trackRecommendedEvent(eventName, {
+      A1_browser: `${getBrowserInfo(navigator.userAgent)}`,
+      A2_machine_info: `${getMachineInfo(navigator.userAgent)}`,
+      A3_exercise: gameId ? `${exerciseName}-${gameId}` : `${exerciseName}`,
+      ...extra
+    });
+  }
   async function loadModule() {
     try {
       await audioContextRef.current.audioWorklet.addModule(`/worklets/recording-processor-v2.js`);
@@ -72,7 +90,9 @@ export default function useRecognition(props = {}) {
         });
         await loadModule();
       }
-      audioContextRef.current.resume();
+      // Must be awaited - an unawaited rejection here would leave the
+      // context suspended with no error surfaced, silently killing capture.
+      await audioContextRef.current.resume();
     } catch (e) {
       console.error(`Sorry, there was an issue setting up the audio context`, e);
       throw e;
@@ -80,13 +100,71 @@ export default function useRecognition(props = {}) {
   }
   useEffect(() => {
     function onConnect() {
+      hasAlertedConnectionErrorRef.current = false;
       setIsSocketConnected(true);
+      // socket.io.engine.transport.name is "polling" here only when the
+      // websocket attempt failed and it fell back - the clearest signal we
+      // have that a student couldn't connect via websocket.
+      trackConnectionDiagnostics("speech_recognition_socket_connected", {
+        A4_transport: socket.io.engine.transport.name
+      });
     }
     function onDisconnect() {
       setIsSocketConnected(false);
+      // The server-side recognize stream/session is gone with the connection
+      // (no state recovery), so leaving recognizing:true would keep streaming
+      // audio into a void with no feedback until the 10s no-transcript timer.
+      setRecognitionState(prevState => {
+        if (stopAudioRecordingTimeoutIdRef.current) {
+          clearTimeout(stopAudioRecordingTimeoutIdRef.current);
+          stopAudioRecordingTimeoutIdRef.current = null;
+        }
+        // A start() in flight (isStartingRef/isRecognizingDisabled set, but
+        // recognizing not yet true) needs the same unwind as an active
+        // recording - otherwise it's neither idle nor recovered, and the
+        // getUserMedia continuation below would still flip recognizing:true
+        // once it resolves against a dead socket.
+        const isStarting = isStartingRef.current || prevState.isRecognizingDisabled;
+        if (!prevState.recognizing && !isStarting) {
+          // Truly idle - nothing to unwind, but the mic button is about to go
+          // disabled - without this the student just finds a dead button
+          // later with no explanation. Guarded so it only fires once per
+          // disconnected streak.
+          if (!hasAlertedConnectionErrorRef.current) {
+            hasAlertedConnectionErrorRef.current = true;
+            recognitionAlert("Connection to the speech recognition service was lost. The microphone will be unavailable until it reconnects.");
+          }
+          return prevState;
+        }
+        isStartingRef.current = false;
+        closeAll(true);
+        if (!hasAlertedConnectionErrorRef.current) {
+          hasAlertedConnectionErrorRef.current = true;
+          recognitionAlert(prevState.recognizing ? "Connection to the speech recognition service was lost while recording. Please try again." : "Connection to the speech recognition service was lost while starting the microphone. Please try again.");
+        }
+        return {
+          ...prevState,
+          recognizing: false,
+          isRecognizingDisabled: false
+        };
+      });
+    }
+    function onConnectError(error) {
+      console.error(error);
+      trackConnectionDiagnostics("speech_recognition_connect_error", {
+        A4_error_message: `${error?.message}`
+      });
+      // Without this, a blocked/failed connection (e.g. a school network
+      // firewall blocking the websocket) leaves the mic button silently
+      // disabled with no feedback to the student.
+      if (!hasAlertedConnectionErrorRef.current) {
+        hasAlertedConnectionErrorRef.current = true;
+        recognitionAlert("Could not connect to the speech recognition service. Please check your network connection (some school Wi-Fi/firewalls block this) and refresh the page.");
+      }
     }
     socket.on("connect", onConnect);
     socket.on("disconnect", onDisconnect);
+    socket.on("connect_error", onConnectError);
 
     // no-op if the socket is already connected
     socket.connect();
@@ -94,14 +172,19 @@ export default function useRecognition(props = {}) {
       socket.disconnect();
       socket.off("connect", onConnect);
       socket.off("disconnect", onDisconnect);
-      closeAll();
+      socket.off("connect_error", onConnectError);
+      closeAll(false, true);
     };
   }, []);
 
   /**
    * Stops recording and closes everything down. Runs on error or on stop.
+   * By default the AudioContext is only suspended, not closed, so the next
+   * start() can reuse it instead of re-fetching/re-registering the audio
+   * worklet module (a source of noticeable start-up lag). Pass fullClose
+   * when the hook itself is unmounting and the context should be released.
    */
-  function closeAll(keepSocketAlive) {
+  function closeAll(keepSocketAlive, fullClose = false) {
     // Clear the listeners (prevents issue if opening and closing repeatedly)
     if (keepSocketAlive) {
       socket.off("speechData");
@@ -114,6 +197,7 @@ export default function useRecognition(props = {}) {
         track.stop();
       });
     }
+    streamRef.current = null;
     if (processorRef.current) {
       if (audioInputRef.current) {
         try {
@@ -122,19 +206,30 @@ export default function useRecognition(props = {}) {
           logger.warn(`Attempt to disconnect input failed: ${error}`);
         }
       }
-      processorRef.current.disconnect(audioContextRef.current.destination);
+      try {
+        processorRef.current.disconnect(audioContextRef.current?.destination);
+      } catch (error) {
+        logger.warn(`Attempt to disconnect processor failed: ${error}`);
+      }
+    }
+    audioInputRef.current = null;
+    processorRef.current = null;
+    if (!audioContextRef.current) {
+      return;
     }
-    if (audioContextRef.current) {
+    if (fullClose) {
       audioContextRef.current.close().then(function () {
-        audioInputRef.current = null;
-        processorRef.current = null;
         audioContextRef.current = null;
       });
+    } else {
+      audioContextRef.current.suspend().catch(error => {
+        logger.warn(`Failed to suspend audio context: ${error}`);
+      });
     }
   }
-  function recognitionAlert(message) {
+  function recognitionAlert(message, severity = "error") {
     if (openSnackbar) {
-      openSnackbar(message, "error");
+      openSnackbar(message, severity);
     } else {
       alert(message);
     }
@@ -148,7 +243,15 @@ export default function useRecognition(props = {}) {
   const initRecording = async (gcloudParams, onData, onError) => {
     try {
       await setupAudioContext();
-      const handleSuccess = function (stream) {
+      const handleSuccess = async function (stream) {
+        streamRef.current = stream;
+        if (!socket.connected) {
+          // Dropped while getUserMedia was resolving - don't buffer a stale
+          // startGoogleCloudStream for a session the server already tore
+          // down. onDisconnect owns the alert/state reset.
+          closeAll(true);
+          return;
+        }
         const gcloudConfig = {
           config: {
             encoding: "LINEAR16",
@@ -167,12 +270,28 @@ export default function useRecognition(props = {}) {
         };
         socket.emit("startGoogleCloudStream", gcloudConfig, version); // init socket Google Speech Connection
 
-        streamRef.current = stream;
         audioInputRef.current = audioContextRef.current.createMediaStreamSource(stream);
         serverErrorRef.current = null;
         processorRef.current = new AudioWorkletNode(audioContextRef.current, "recording-processor-v2");
         processorRef.current.connect(audioContextRef.current.destination);
-        audioContextRef.current.resume();
+        try {
+          // Awaited so a rejection reaches the getUserMedia .catch() below
+          // instead of vanishing as an unhandled rejection.
+          await audioContextRef.current.resume();
+        } catch (resumeError) {
+          // stream/audioInput/processor are already live at this point -
+          // without this the mic track and worklet node would leak past the
+          // failure that the outer .catch() alerts and resets state for.
+          closeAll(true);
+          throw resumeError;
+        }
+        if (!socket.connected) {
+          // Dropped mid-resume; onDisconnect has already (or is about to)
+          // close these same resources, so stop instead of wiring nodes onto
+          // a torn-down session.
+          closeAll(true);
+          return;
+        }
         audioInputRef.current.connect(processorRef.current);
         processorRef.current.port.onmessage = event => {
           const audioData = event.data;
@@ -188,50 +307,86 @@ export default function useRecognition(props = {}) {
           socket.emit("binaryData", result, version);
         };
         if (window.MediaRecorder) {
-          mediaRecorderRef.current = new MediaRecorder(stream);
-          mediaRecorderRef.current.ondataavailable = e => {
-            const audioChunks = [];
-            audioChunks.push(e.data);
-            const audioBlob = new Blob(audioChunks, {
-              type: mediaRecorderRef.current.mimeType
-            });
-            const audioUrl = URL.createObjectURL(audioBlob);
-            setRecognitionState(prevState => ({
-              ...prevState,
-              attemptAudioURL: audioUrl,
-              audioBlob: audioBlob
-            }));
-          };
-          mediaRecorderRef.current.start();
+          // This only powers the "listen back to your attempt" playback
+          // feature, not recognition itself. A codec/construction failure
+          // here (seen in some embedded/older WebKit webviews) must not
+          // abort the recording flow that already started above.
+          try {
+            mediaRecorderRef.current = new MediaRecorder(stream);
+            mediaRecorderRef.current.ondataavailable = e => {
+              const audioChunks = [];
+              audioChunks.push(e.data);
+              const audioBlob = new Blob(audioChunks, {
+                type: mediaRecorderRef.current.mimeType
+              });
+              const audioUrl = URL.createObjectURL(audioBlob);
+              setRecognitionState(prevState => ({
+                ...prevState,
+                attemptAudioURL: audioUrl,
+                audioBlob: audioBlob
+              }));
+            };
+            mediaRecorderRef.current.start();
+          } catch (mediaRecorderError) {
+            console.error("Failed to start MediaRecorder for attempt playback", mediaRecorderError);
+            mediaRecorderRef.current = null;
+          }
         }
-        if (/Android|webOS|Safari|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
+        if (
+        // Excludes bare "Safari", which also matches every desktop
+        // Chrome/Edge/Firefox UA string and was adding this delay for
+        // almost all browsers, not just mobile ones.
+        /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)) {
           // wait half second to indicate recording, this helps prevent speech being lost at the start
           return new Promise(resolve => setTimeout(resolve, 500));
         }
       };
       if (navigator && navigator.mediaDevices && navigator.mediaDevices.getUserMedia) {
         navigator.mediaDevices.getUserMedia(constraints).then(handleSuccess).then(() => {
+          isStartingRef.current = false;
+          // socket.connected is checked directly (not the isSocketConnected
+          // state, which may not have re-rendered yet) so a disconnect that
+          // landed mid-setup can't be raced into recognizing:true - onDisconnect
+          // already unwound this startup, so just release what handleSuccess
+          // just created.
+          if (!socket.connected) {
+            closeAll(true);
+            return;
+          }
           if (!serverErrorRef.current) {
             setRecognitionState(prevState => ({
               ...prevState,
-              recognizing: true
+              recognizing: true,
+              isRecognizingDisabled: false
             }));
           }
         }).catch(err => {
           /* handle the error */
           console.error(err);
-          if (["Permission denied", "The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission.", "The request is not allowed by the user agent or the platform in the current context."].includes(err?.message)) {
-            recognitionAlert("Permission denied, Please allow microphone access and refresh the page.");
+          // Match on err.name (the DOMException standard) rather than the
+          // message text, which varies by browser/locale and previously
+          // meant most getUserMedia failures (e.g. a Permissions-Policy
+          // block when embedded in an iframe/webview such as an LMS app)
+          // were logged but never surfaced to the student.
+          const isEmbedded = typeof window !== "undefined" && window.self !== window.top;
+          if (["NotAllowedError", "PermissionDeniedError", "SecurityError"].includes(err?.name)) {
+            recognitionAlert(isEmbedded ? "Microphone access was blocked. If you're inside another app, make sure it allows microphone access." : "Permission denied, Please allow microphone access and refresh the page.");
+          } else {
+            recognitionAlert("Could not access the microphone. Please refresh the page and try again.");
           }
+          isStartingRef.current = false;
           setRecognitionState(prevState => ({
             ...prevState,
-            recognizing: false
+            recognizing: false,
+            isRecognizingDisabled: false
           }));
         });
       } else {
+        isStartingRef.current = false;
         setRecognitionState(prevState => ({
           ...prevState,
-          recognizing: false
+          recognizing: false,
+          isRecognizingDisabled: false
         }));
         recognitionAlert("Speech recognition not supported, please try another browser.");
       }
@@ -250,6 +405,12 @@ export default function useRecognition(props = {}) {
         }
       });
     } catch (error) {
+      isStartingRef.current = false;
+      setRecognitionState(prevState => ({
+        ...prevState,
+        recognizing: false,
+        isRecognizingDisabled: false
+      }));
       if (onError) {
         onError(error);
       }
@@ -280,7 +441,7 @@ export default function useRecognition(props = {}) {
     };
     trackRecommendedEvent("speech_recognition_no_transcript", eventBody);
   };
-  const stopRecording = (keepSocketAlive, triggerEvent) => {
+  const stopRecording = (keepSocketAlive, triggerEvent, fullClose = false) => {
     // indicate end stream to trigger interim transcript to return as final transcript
     if (socket) {
       indicateEndStream();
@@ -289,7 +450,7 @@ export default function useRecognition(props = {}) {
       mediaRecorderRef.current.stop();
     }
     setTimeout(() => {
-      closeAll(keepSocketAlive);
+      closeAll(keepSocketAlive, fullClose);
       setRecognitionState(prevState => ({
         ...prevState,
         isRecognizingDisabled: false
@@ -305,7 +466,7 @@ export default function useRecognition(props = {}) {
   };
   useEffect(() => {
     return () => {
-      stopRecording(false);
+      stopRecording(false, false, true);
     };
   }, []);
   const startRecognition = (lang, speechContexts, model) => {
@@ -408,6 +569,16 @@ export default function useRecognition(props = {}) {
     stop();
   };
   const start = (lang, speechContexts, model) => {
+    // Ignore a repeat click while a start is already in flight or once
+    // recognizing - a ref check because it must be synchronous, unlike state.
+    if (isStartingRef.current || recognitionState.recognizing) {
+      return;
+    }
+    isStartingRef.current = true;
+    setRecognitionState(prevState => ({
+      ...prevState,
+      isRecognizingDisabled: true
+    }));
     stopAudioRecordingTimeoutIdRef.current = setTimeout(() => {
       stop();
     }, audioRecordingLimit);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nualang/nualang-ui-components",
-  "version": "0.1.1420",
+  "version": "0.1.1421",
   "type": "module",
   "main": "dist/index.js",
   "files": [
@@ -177,6 +177,7 @@
     "build-storybook": "storybook build",
     "clean": "rimraf dist",
     "compile": "pnpm run clean && cross-env NODE_ENV=production babel src/components --out-dir dist --copy-files --no-copy-ignored",
+    "watch": "pnpm run clean && cross-env NODE_ENV=production babel src/components --out-dir dist --copy-files --no-copy-ignored --watch",
     "version": "pnpm run compile && git add -A",
     "postversion": "pnpm publish && git push && git push --tags",
     "localpack": "pnpm run compile && pnpm pack",