@ews-admin/global-design-system 1.35.0 → 1.36.0

package/src/components/AssistantChat/assistantMarkdown.tsx

@@ -0,0 +1,105 @@
+import React from "react";
+
+/**
+ * The tiny markdown subset the assistant contract allows: paragraphs, bullet
+ * lists, **bold** and [links](url). Everything else is plain text, so a
+ * payload can never inject markup. Links to the current origin open in the
+ * same tab (the host app may route them itself through `onLinkClick`);
+ * links to other sites open in a new tab.
+ */
+const INLINE = /(\*\*[^*]+\*\*|\[[^\]]+\]\((?:https?:\/\/|\/)[^)\s]+\))/g;
+
+export interface AssistantMarkdownOptions {
+  /**
+   * Called when a link is clicked, before the browser follows it. Call
+   * `event.preventDefault()` to navigate otherwise (e.g. the host router).
+   */
+  onLinkClick?: (href: string, event: React.MouseEvent<HTMLAnchorElement>) => void;
+  /** Whether a link leaves the current site; such links open in a new tab. */
+  isExternal?: (href: string) => boolean;
+}
+
+/** Absolute URL on another origin. Without a window (server rendering) every absolute URL counts as external. */
+export function isExternalLink(href: string): boolean {
+  if (!/^https?:\/\//i.test(href)) return false;
+  if (typeof window === "undefined" || !window.location?.origin) return true;
+  try {
+    return new URL(href).origin !== window.location.origin;
+  } catch {
+    return true;
+  }
+}
+
+function renderInline(text: string, keyPrefix: string, options: AssistantMarkdownOptions): React.ReactNode[] {
+  const nodes: React.ReactNode[] = [];
+  const isExternal = options.isExternal ?? isExternalLink;
+  let last = 0;
+  let index = 0;
+  for (const match of text.matchAll(INLINE)) {
+    const start = match.index ?? 0;
+    if (start > last) nodes.push(text.slice(last, start));
+    const token = match[0];
+    if (token.startsWith("**")) {
+      nodes.push(
+        <strong key={`${keyPrefix}-b${index}`}>{token.slice(2, -2)}</strong>
+      );
+    } else {
+      const close = token.indexOf("](");
+      const label = token.slice(1, close);
+      const href = token.slice(close + 2, -1);
+      const external = isExternal(href);
+      nodes.push(
+        <a
+          key={`${keyPrefix}-a${index}`}
+          href={href}
+          className="font-medium text-ews-primary underline underline-offset-2 hover:text-ews-primary-hover"
+          target={external ? "_blank" : undefined}
+          rel={external ? "noopener noreferrer" : undefined}
+          onClick={options.onLinkClick ? (event) => options.onLinkClick?.(href, event) : undefined}
+        >
+          {label}
+        </a>
+      );
+    }
+    last = start + token.length;
+    index++;
+  }
+  if (last < text.length) nodes.push(text.slice(last));
+  return nodes;
+}
+
+export function renderAssistantMarkdown(
+  content: string,
+  options: AssistantMarkdownOptions = {}
+): React.ReactNode[] {
+  const blocks = content.replace(/\r\n/g, "\n").split(/\n{2,}/);
+  const out: React.ReactNode[] = [];
+  blocks.forEach((block, blockIndex) => {
+    const lines = block.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length === 0) return;
+    const isList = lines.every((line) => /^\s*[-*•]\s+/.test(line));
+    if (isList) {
+      out.push(
+        <ul key={`l${blockIndex}`} className="my-2 list-disc space-y-1 ps-5">
+          {lines.map((line, lineIndex) => (
+            <li key={lineIndex}>
+              {renderInline(line.replace(/^\s*[-*•]\s+/, ""), `l${blockIndex}-${lineIndex}`, options)}
+            </li>
+          ))}
+        </ul>
+      );
+    } else {
+      out.push(
+        <p key={`p${blockIndex}`} className="my-2 first:mt-0 last:mb-0">
+          {lines.map((line, lineIndex) => (
+            <React.Fragment key={lineIndex}>
+              {lineIndex > 0 && <br />}
+              {renderInline(line, `p${blockIndex}-${lineIndex}`, options)}
+            </React.Fragment>
+          ))}
+        </p>
+      );
+    }
+  });
+  return out;
+}

package/src/components/AssistantChat/index.ts

@@ -0,0 +1,25 @@
+export { AssistantChat, conversationTitle } from "./AssistantChat";
+export { AssistantComposer, MAX_MESSAGE_LENGTH } from "./AssistantComposer";
+export type { AssistantComposerProps } from "./AssistantComposer";
+export { AssistantConfirmationCard } from "./AssistantConfirmationCard";
+export type { AssistantConfirmationCardProps } from "./AssistantConfirmationCard";
+export { AssistantConversationList } from "./AssistantConversationList";
+export type { AssistantConversationListProps } from "./AssistantConversationList";
+export { AssistantMessages } from "./AssistantMessages";
+export type { AssistantMessagesProps } from "./AssistantMessages";
+export { AssistantSuggestionCard } from "./AssistantSuggestionCard";
+export type { AssistantSuggestionCardProps } from "./AssistantSuggestionCard";
+export { isExternalLink, renderAssistantMarkdown } from "./assistantMarkdown";
+export type { AssistantMarkdownOptions } from "./assistantMarkdown";
+export type {
+  AssistantChatProps,
+  AssistantChatTexts,
+  AssistantCitation,
+  AssistantConfirmation,
+  AssistantConversationSummary,
+  AssistantEvent,
+  AssistantLanguage,
+  AssistantMessage,
+  AssistantSuggestion,
+  AssistantTransport,
+} from "./AssistantChat.types";

package/src/components/AssistantLauncher/AssistantLauncher.tsx

@@ -0,0 +1,408 @@
+import { ArrowUp, AudioLines, Maximize2, Mic, Minimize2, X } from "lucide-react";
+import React, { useCallback, useEffect, useId, useRef, useState } from "react";
+import { listAssistantConversations, saveAssistantConversation } from "../../assistant/store";
+import { useSpeechRecognition } from "../../hooks/useSpeechRecognition";
+import { cn, generateId } from "../../utils";
+import { AssistantChat } from "../AssistantChat/AssistantChat";
+import type {
+  AssistantChatProps,
+  AssistantConversationSummary,
+  AssistantMessage,
+} from "../AssistantChat/AssistantChat.types";
+import { MAX_MESSAGE_LENGTH } from "../AssistantChat/AssistantComposer";
+
+export interface AssistantLauncherTexts {
+  /** Placeholder of the bar ("Posez une question…"); also the dialog's accessible name. */
+  open: string;
+  /** The close button of the panel. */
+  close: string;
+  /** The voice button of the bar; falls back to `open`. */
+  voice?: string;
+  /** The expand / collapse button of the panel; fall back to `open` / `close`. */
+  expand?: string;
+  collapse?: string;
+  /** The history button of the panel; falls back to `texts.recentConversations`. */
+  history?: string;
+}
+
+export interface AssistantLauncherProps
+  extends Omit<AssistantChatProps, "className" | "layout" | "queuedPrompt" | "historyOpen" | "onHistoryOpenChange"> {
+  launcherTexts: AssistantLauncherTexts;
+  /** Controlled open state; the launcher manages it when absent. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Controlled expanded (wide) state; the launcher manages it when absent. */
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  /**
+   * Pixels between the bar and the bottom of the viewport, so the bar sits
+   * above a host bottom navigation. Default 16.
+   */
+  bottomOffset?: number;
+  /** Renders nothing at all (e.g. a feature toggle off). */
+  hidden?: boolean;
+  /** Extra classes on the bar. */
+  className?: string;
+  /** Extra classes on the panel (e.g. a wider max width). */
+  panelClassName?: string;
+}
+
+const DIRECTION: Record<AssistantChatProps["language"], "ltr" | "rtl"> = {
+  fr: "ltr",
+  en: "ltr",
+  ar: "rtl",
+};
+
+/**
+ * MED-1787: the in-app entry to the assistant for Medecine360-ui and the
+ * dashboard. A floating bar at the bottom of the page (brand badge, a text
+ * field "Posez une question…", push-to-talk mic, voice button, send) opens a
+ * slide-over panel hosting AssistantChat in its `panel` layout; clicking the
+ * field opens the panel too, a spoken question is sent as it opens. From
+ * tablets up the panel can be expanded to a dashboard reaching the middle of
+ * the screen, with the conversation list beside the thread; in the narrow
+ * layout a history button shows that list over the thread.
+ *
+ * Conversation history is managed here with the shared browser store unless
+ * the host passes `conversations` itself: new conversations are remembered,
+ * selecting one loads it through `transport.getConversation`.
+ *
+ * The chat stays mounted while the panel is closed, so the conversation in
+ * progress survives open/close. Escape and the overlay close the panel; focus
+ * goes to the composer on open and back to the bar on close. In Arabic the
+ * panel slides from the left (`end-0` follows `dir`).
+ */
+export const AssistantLauncher: React.FC<AssistantLauncherProps> = ({
+  launcherTexts,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  expanded,
+  defaultExpanded = false,
+  onExpandedChange,
+  bottomOffset = 16,
+  hidden = false,
+  className,
+  panelClassName,
+  headerAction,
+  voice = true,
+  conversations: hostConversations,
+  activeConversationId: hostActiveId,
+  initialMessages: hostInitialMessages,
+  onConversationCreated,
+  onSelectConversation,
+  onNewConversation,
+  ...chatProps
+}) => {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const isOpen = open ?? uncontrolledOpen;
+  const [uncontrolledExpanded, setUncontrolledExpanded] = useState(defaultExpanded);
+  const isExpanded = expanded ?? uncontrolledExpanded;
+  const [historyOpen, setHistoryOpen] = useState(false);
+  const [draft, setDraft] = useState("");
+  const [queuedPrompt, setQueuedPrompt] = useState<{ id: string; content: string } | null>(null);
+  const panelId = useId();
+  const barRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLElement>(null);
+  const wasOpenRef = useRef(isOpen);
+
+  // Managed history (browser store) unless the host provides the list.
+  const hostManaged = hostConversations !== undefined;
+  const [storedConversations, setStoredConversations] = useState<AssistantConversationSummary[]>([]);
+  const [managedActiveId, setManagedActiveId] = useState<string | null>(null);
+  const [managedMessages, setManagedMessages] = useState<AssistantMessage[] | undefined>(undefined);
+  useEffect(() => {
+    if (!hostManaged) setStoredConversations(listAssistantConversations());
+  }, [hostManaged]);
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (open === undefined) setUncontrolledOpen(next);
+      onOpenChange?.(next);
+    },
+    [onOpenChange, open]
+  );
+
+  const setExpanded = useCallback(
+    (next: boolean) => {
+      if (expanded === undefined) setUncontrolledExpanded(next);
+      onExpandedChange?.(next);
+      if (next) setHistoryOpen(false);
+    },
+    [expanded, onExpandedChange]
+  );
+
+  /** Opens the panel; a non-empty text is sent as the first message. */
+  const submitFromBar = useCallback(
+    (content: string) => {
+      const trimmed = content.trim();
+      if (trimmed) {
+        setQueuedPrompt({ id: generateId("q"), content: trimmed.slice(0, MAX_MESSAGE_LENGTH) });
+      }
+      setDraft("");
+      setOpen(true);
+    },
+    [setOpen]
+  );
+
+  const speech = useSpeechRecognition({
+    language: chatProps.language,
+    onInterim: (text) => setDraft(text),
+    onResult: (text) => submitFromBar(text),
+  });
+
+  const handleConversationCreated = useCallback(
+    (conversation: AssistantConversationSummary) => {
+      if (!hostManaged) {
+        setStoredConversations(saveAssistantConversation(conversation));
+        setManagedActiveId(conversation.id);
+      }
+      onConversationCreated?.(conversation);
+    },
+    [hostManaged, onConversationCreated]
+  );
+
+  const handleSelectConversation = useCallback(
+    (conversationId: string) => {
+      onSelectConversation?.(conversationId);
+      if (hostManaged || conversationId === managedActiveId) return;
+      const load = async () => {
+        try {
+          const loaded = await chatProps.transport.getConversation?.(conversationId);
+          setManagedMessages(loaded?.messages ?? []);
+        } catch {
+          setManagedMessages([]);
+        }
+        setManagedActiveId(conversationId);
+      };
+      void load();
+    },
+    [chatProps.transport, hostManaged, managedActiveId, onSelectConversation]
+  );
+
+  const handleNewConversation = useCallback(() => {
+    if (!hostManaged) {
+      setManagedActiveId(null);
+      setManagedMessages(undefined);
+    }
+    onNewConversation?.();
+  }, [hostManaged, onNewConversation]);
+
+  // Escape closes; the page behind does not scroll while the panel is open.
+  useEffect(() => {
+    if (!isOpen || hidden) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.body.style.overflow = previousOverflow;
+    };
+  }, [hidden, isOpen, setOpen]);
+
+  // Focus: into the composer on open, back to the bar on close.
+  useEffect(() => {
+    if (isOpen) {
+      panelRef.current?.querySelector("textarea")?.focus();
+    } else if (wasOpenRef.current) {
+      barRef.current?.focus();
+    }
+    wasOpenRef.current = isOpen;
+  }, [isOpen]);
+
+  if (hidden) return null;
+
+  const dir = DIRECTION[chatProps.language];
+  const showMic = voice && speech.supported;
+  const expandLabel = launcherTexts.expand ?? launcherTexts.open;
+  const collapseLabel = launcherTexts.collapse ?? launcherTexts.close;
+  const texts = launcherTexts.history ? { ...chatProps.texts, history: launcherTexts.history } : chatProps.texts;
+
+  return (
+    <>
+      {!isOpen && (
+        <div
+          dir={dir}
+          className="pointer-events-none fixed inset-x-0 z-40 flex justify-center px-4"
+          style={{ bottom: bottomOffset }}
+          data-testid="assistant-launcher-bar"
+        >
+          <div
+            role="group"
+            aria-label={launcherTexts.open}
+            className={cn(
+              "pointer-events-auto flex w-full max-w-2xl items-center gap-2 rounded-2xl border border-ews-gray-100 bg-white py-2 pe-2 ps-3",
+              "shadow-[0_8px_30px_rgba(15,23,42,0.14)]",
+              className
+            )}
+          >
+            <button
+              ref={barRef}
+              type="button"
+              onClick={() => setOpen(true)}
+              aria-label={launcherTexts.open}
+              aria-haspopup="dialog"
+              aria-expanded={false}
+              aria-controls={panelId}
+              className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl bg-gradient-to-br from-ews-primary to-ews-primary-hover text-base font-bold text-white shadow-sm focus:outline-none focus:ring-2 focus:ring-ews-primary/40"
+              data-testid="assistant-launcher"
+            >
+              {chatProps.texts.brandName.charAt(0)}
+            </button>
+            {/* The field opens the panel: typing happens in the panel composer, which gets the focus. */}
+            <input
+              type="text"
+              readOnly
+              value={draft}
+              onMouseDown={(event) => {
+                event.preventDefault();
+                setOpen(true);
+              }}
+              onFocus={() => setOpen(true)}
+              onKeyDown={(event) => {
+                if (event.key === "Enter" || event.key === " ") {
+                  event.preventDefault();
+                  setOpen(true);
+                }
+              }}
+              placeholder={speech.listening ? chatProps.texts.listening : launcherTexts.open}
+              aria-label={launcherTexts.open}
+              aria-haspopup="dialog"
+              aria-controls={panelId}
+              className="min-w-0 flex-1 cursor-text bg-transparent py-2 text-lg text-ews-gray-800 placeholder:text-ews-gray-400 focus:outline-none"
+              data-testid="assistant-launcher-input"
+            />
+            {showMic && (
+              <button
+                type="button"
+                aria-label={chatProps.texts.holdToTalk}
+                aria-pressed={speech.listening}
+                title={chatProps.texts.holdToTalk}
+                onMouseDown={speech.start}
+                onMouseUp={speech.stop}
+                onMouseLeave={speech.listening ? speech.stop : undefined}
+                onTouchStart={speech.start}
+                onTouchEnd={speech.stop}
+                onKeyDown={(event) => {
+                  if (event.key === " " || event.key === "Enter") {
+                    event.preventDefault();
+                    if (speech.listening) speech.stop();
+                    else speech.start();
+                  }
+                }}
+                className={cn(
+                  "flex h-10 w-10 shrink-0 items-center justify-center rounded-full transition-colors focus:outline-none focus:ring-2 focus:ring-ews-primary",
+                  speech.listening
+                    ? "bg-ews-error text-white animate-pulse"
+                    : "text-ews-gray-600 hover:bg-ews-gray-100 hover:text-ews-primary"
+                )}
+                data-testid="assistant-launcher-mic"
+              >
+                <Mic className="h-5 w-5" aria-hidden="true" />
+              </button>
+            )}
+            <button
+              type="button"
+              onClick={() => setOpen(true)}
+              aria-label={launcherTexts.voice ?? launcherTexts.open}
+              title={launcherTexts.voice ?? launcherTexts.open}
+              className="flex h-10 w-10 shrink-0 items-center justify-center rounded-full bg-ews-gray-100 text-ews-gray-700 transition-colors hover:bg-ews-gray-200 focus:outline-none focus:ring-2 focus:ring-ews-primary"
+              data-testid="assistant-launcher-voice"
+            >
+              <AudioLines className="h-5 w-5" aria-hidden="true" />
+            </button>
+            <button
+              type="button"
+              onClick={() => submitFromBar(draft)}
+              aria-label={chatProps.texts.send}
+              title={chatProps.texts.send}
+              className="flex h-11 w-11 shrink-0 items-center justify-center rounded-xl bg-ews-primary text-white shadow-sm transition-colors hover:bg-ews-primary-hover focus:outline-none focus:ring-2 focus:ring-ews-primary focus:ring-offset-1"
+              data-testid="assistant-launcher-send"
+            >
+              <ArrowUp className="h-5 w-5" aria-hidden="true" />
+            </button>
+          </div>
+        </div>
+      )}
+
+      <div
+        dir={dir}
+        className={cn("fixed inset-0 z-[90]", !isOpen && "hidden")}
+        aria-hidden={!isOpen}
+        data-testid="assistant-launcher-panel"
+      >
+        <div
+          className="absolute inset-0 bg-black/40"
+          onClick={() => setOpen(false)}
+          data-testid="assistant-launcher-overlay"
+        />
+        <section
+          ref={panelRef}
+          id={panelId}
+          role="dialog"
+          aria-modal="true"
+          aria-label={launcherTexts.open}
+          data-expanded={isExpanded}
+          className={cn(
+            "absolute inset-y-0 end-0 flex w-full flex-col bg-white shadow-2xl transition-[width,max-width] duration-200",
+            // Expanded: a dashboard reaching the middle of the screen (never full width), tablets and up.
+            isExpanded ? "sm:max-w-md md:w-[max(50vw,40rem)] md:max-w-none" : "sm:max-w-md",
+            panelClassName
+          )}
+        >
+          <AssistantChat
+            {...chatProps}
+            texts={texts}
+            voice={voice}
+            layout={isExpanded ? "wide" : "panel"}
+            queuedPrompt={queuedPrompt}
+            conversations={hostManaged ? hostConversations : storedConversations}
+            activeConversationId={hostManaged ? hostActiveId : managedActiveId}
+            initialMessages={hostManaged ? hostInitialMessages : managedMessages}
+            onConversationCreated={handleConversationCreated}
+            onSelectConversation={handleSelectConversation}
+            onNewConversation={handleNewConversation}
+            historyOpen={historyOpen}
+            onHistoryOpenChange={setHistoryOpen}
+            className="flex-1"
+            headerAction={
+              <>
+                {headerAction}
+                <button
+                  type="button"
+                  onClick={() => setExpanded(!isExpanded)}
+                  aria-label={isExpanded ? collapseLabel : expandLabel}
+                  aria-pressed={isExpanded}
+                  title={isExpanded ? collapseLabel : expandLabel}
+                  className="hidden rounded-full p-2 text-ews-gray-500 hover:bg-ews-gray-100 hover:text-ews-gray-900 focus:outline-none focus:ring-2 focus:ring-ews-primary md:inline-flex"
+                  data-testid="assistant-launcher-expand"
+                >
+                  {isExpanded ? (
+                    <Minimize2 className="h-5 w-5" aria-hidden="true" />
+                  ) : (
+                    <Maximize2 className="h-5 w-5" aria-hidden="true" />
+                  )}
+                </button>
+                <button
+                  type="button"
+                  onClick={() => setOpen(false)}
+                  aria-label={launcherTexts.close}
+                  title={launcherTexts.close}
+                  className="rounded-full p-2 text-ews-gray-500 hover:bg-ews-gray-100 hover:text-ews-gray-900 focus:outline-none focus:ring-2 focus:ring-ews-primary"
+                  data-testid="assistant-launcher-close"
+                >
+                  <X className="h-5 w-5" aria-hidden="true" />
+                </button>
+              </>
+            }
+          />
+        </section>
+      </div>
+    </>
+  );
+};

package/src/components/AssistantLauncher/index.ts

@@ -0,0 +1,2 @@
+export { AssistantLauncher } from "./AssistantLauncher";
+export type { AssistantLauncherProps, AssistantLauncherTexts } from "./AssistantLauncher";

package/src/hooks/index.ts

@@ -4,3 +4,5 @@ export { useIdleLock } from "./useIdleLock";
 export type { UseIdleLockOptions, UseIdleLockResult } from "./useIdleLock";
 export { useSelectField } from "./useSelectField";
 export type { UseSelectFieldProps } from "./useSelectField";
+export { useSpeechRecognition, getSpeechRecognition } from "./useSpeechRecognition";
+export type { UseSpeechRecognitionOptions } from "./useSpeechRecognition";

package/src/hooks/useSpeechRecognition.ts

@@ -0,0 +1,95 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** The subset of the Web Speech API the hook uses; browsers expose it unprefixed or as webkit*. */
+interface SpeechRecognitionLike {
+  lang: string;
+  interimResults: boolean;
+  continuous: boolean;
+  onresult: ((event: { results: ArrayLike<ArrayLike<{ transcript: string }>> }) => void) | null;
+  onerror: ((event: { error?: string }) => void) | null;
+  onend: (() => void) | null;
+  start(): void;
+  stop(): void;
+  abort(): void;
+}
+
+type SpeechRecognitionCtor = new () => SpeechRecognitionLike;
+
+const BCP47: Record<string, string> = { fr: "fr-FR", en: "en-US", ar: "ar-SA" };
+
+export function getSpeechRecognition(): SpeechRecognitionCtor | undefined {
+  if (typeof window === "undefined") return undefined;
+  const w = window as unknown as {
+    SpeechRecognition?: SpeechRecognitionCtor;
+    webkitSpeechRecognition?: SpeechRecognitionCtor;
+  };
+  return w.SpeechRecognition ?? w.webkitSpeechRecognition;
+}
+
+export interface UseSpeechRecognitionOptions {
+  /** `fr`, `en`, `ar` or a BCP 47 tag. */
+  language: string;
+  /** Called with the final transcript when recognition stops. */
+  onResult: (transcript: string) => void;
+  /** Called with interim text while the user speaks. */
+  onInterim?: (transcript: string) => void;
+}
+
+/**
+ * Push-to-talk on the browser speech API (MED-1783). `supported` is false on
+ * the server and in browsers without the API, so the app can hide the mic.
+ */
+export function useSpeechRecognition({
+  language,
+  onResult,
+  onInterim,
+}: UseSpeechRecognitionOptions) {
+  const [supported, setSupported] = useState(false);
+  const [listening, setListening] = useState(false);
+  const recognitionRef = useRef<SpeechRecognitionLike | null>(null);
+  const transcriptRef = useRef("");
+  const callbacks = useRef({ onResult, onInterim });
+  callbacks.current = { onResult, onInterim };
+
+  // Detected after mount: the server never has the API, and the markup must match.
+  useEffect(() => {
+    setSupported(getSpeechRecognition() !== undefined);
+  }, []);
+
+  const stop = useCallback(() => {
+    recognitionRef.current?.stop();
+  }, []);
+
+  const start = useCallback(() => {
+    const Ctor = getSpeechRecognition();
+    if (!Ctor || recognitionRef.current) return;
+    const recognition = new Ctor();
+    recognition.lang = BCP47[language] ?? language;
+    recognition.interimResults = true;
+    recognition.continuous = true;
+    transcriptRef.current = "";
+    recognition.onresult = (event) => {
+      let text = "";
+      for (let i = 0; i < event.results.length; i++) {
+        text += event.results[i][0]?.transcript ?? "";
+      }
+      transcriptRef.current = text.trim();
+      callbacks.current.onInterim?.(transcriptRef.current);
+    };
+    recognition.onerror = () => {
+      recognition.stop();
+    };
+    recognition.onend = () => {
+      recognitionRef.current = null;
+      setListening(false);
+      if (transcriptRef.current) callbacks.current.onResult(transcriptRef.current);
+    };
+    recognitionRef.current = recognition;
+    setListening(true);
+    recognition.start();
+  }, [language]);
+
+  useEffect(() => () => recognitionRef.current?.abort(), []);
+
+  return { supported, listening, start, stop };
+}