From c77b3966ad3e30581aa7e6eca04540f3e5859110 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 20 Mar 2026 04:58:14 +0000
Subject: [PATCH] fix(web): a11y, loading UX, and chat error surfaces

- Add AppLoadingPlaceholder with role=status for auth/route shells
- Surface usePersistentChat stream errors with dismiss; resetChatError clears status
- Show history loading spinner; empty non-new chat copy; memo-friendly startEdit
- Conversation: aria-label on message log; scroll button label
- Model selector: stop Tab key trap; model row favorite/info aria-labels
- Inline errors: decorative icon hidden; details toggle type and aria-expanded
- Landing staircase: aria-hidden decoration

Co-authored-by: Leo <leoisadev1@users.noreply.github.com>
---
 .../__tests__/chat-interface.test.tsx         |  1 +
 .../components/ai-elements/conversation.tsx   |  4 +-
 .../components/app-loading-placeholder.tsx    | 44 +++++++++++++
 .../src/components/chat/chat-interface.tsx    | 30 +++++++--
 .../src/components/chat/chat-message-list.tsx | 61 +++++++++++++++++--
 .../components/chat/inline-error-message.tsx  |  5 +-
 apps/web/src/components/model-selector.tsx    |  4 --
 .../components/model-selector/model-item.tsx  |  2 +
 .../__tests__/use-persistent-chat.test.ts     | 18 ++++++
 apps/web/src/hooks/use-persistent-chat.ts     | 10 ++-
 apps/web/src/routes/__root.tsx                |  8 +--
 apps/web/src/routes/c/$chatId.tsx             |  3 +-
 apps/web/src/routes/index.tsx                 |  4 +-
 13 files changed, 167 insertions(+), 27 deletions(-)
 create mode 100644 apps/web/src/components/app-loading-placeholder.tsx

diff --git a/apps/web/src/components/__tests__/chat-interface.test.tsx b/apps/web/src/components/__tests__/chat-interface.test.tsx
index 2d66ff3d..5ac2b2a7 100644
--- a/apps/web/src/components/__tests__/chat-interface.test.tsx
+++ b/apps/web/src/components/__tests__/chat-interface.test.tsx
@@ -231,6 +231,7 @@ function makeDefaultState() {
 		chatId: null,
 		isResuming: false,
 		resumedContent: '',
+		resetChatError: vi.fn(),
 	}
 }
 
diff --git a/apps/web/src/components/ai-elements/conversation.tsx b/apps/web/src/components/ai-elements/conversation.tsx
index 58c7289e..76e9b4ab 100644
--- a/apps/web/src/components/ai-elements/conversation.tsx
+++ b/apps/web/src/components/ai-elements/conversation.tsx
@@ -83,6 +83,7 @@ export const Conversation = ({ className, children, showScrollButton = false, ..
           ref={scrollRef}
           className="absolute inset-0 overflow-y-auto"
           role="log"
+          aria-label="Chat messages"
         >
           {children}
           {/* Anchor element for scroll-to-bottom */}
@@ -92,10 +93,11 @@ export const Conversation = ({ className, children, showScrollButton = false, ..
         {showScrollButton && !isAtBottom && (
           <button
             type="button"
+            aria-label="Scroll to latest message"
             className="absolute bottom-4 left-1/2 -translate-x-1/2 z-10 rounded-full shadow-lg flex size-11 md:size-9 items-center justify-center bg-background border border-border hover:bg-muted active:scale-95 transition-all"
             onClick={scrollToBottom}
           >
-            <ArrowDownIcon className="size-5 md:size-4" />
+            <ArrowDownIcon className="size-5 md:size-4" aria-hidden />
           </button>
         )}
       </div>
diff --git a/apps/web/src/components/app-loading-placeholder.tsx b/apps/web/src/components/app-loading-placeholder.tsx
new file mode 100644
index 00000000..934d6545
--- /dev/null
+++ b/apps/web/src/components/app-loading-placeholder.tsx
@@ -0,0 +1,44 @@
+import { cn } from "@/lib/utils";
+
+type AppLoadingPlaceholderProps = {
+	/** Announced to screen readers */
+	message?: string;
+	className?: string;
+	/** Matches authenticated shell: sidebar stub + main pane */
+	variant?: "app-shell" | "simple";
+};
+
+/**
+ * Accessible loading placeholder for route-level and auth-gated suspense states.
+ */
+export function AppLoadingPlaceholder({
+	message = "Loading",
+	className,
+	variant = "simple",
+}: AppLoadingPlaceholderProps) {
+	if (variant === "app-shell") {
+		return (
+			<div
+				className={cn("flex h-screen w-full bg-sidebar", className)}
+				role="status"
+				aria-live="polite"
+				aria-busy="true"
+			>
+				<span className="sr-only">{message}</span>
+				<div className="w-64 shrink-0 bg-sidebar" aria-hidden="true" />
+				<div className="flex-1 bg-background" aria-hidden="true" />
+			</div>
+		);
+	}
+
+	return (
+		<div
+			className={cn("flex h-full w-full bg-background", className)}
+			role="status"
+			aria-live="polite"
+			aria-busy="true"
+		>
+			<span className="sr-only">{message}</span>
+		</div>
+	);
+}
diff --git a/apps/web/src/components/chat/chat-interface.tsx b/apps/web/src/components/chat/chat-interface.tsx
index c667641a..c68e87e7 100644
--- a/apps/web/src/components/chat/chat-interface.tsx
+++ b/apps/web/src/components/chat/chat-interface.tsx
@@ -51,6 +51,8 @@ export function ChatInterface({ chatId }: ChatInterfaceProps) {
 		error,
 		stop,
 		isNewChat,
+		isLoadingMessages,
+		resetChatError,
 	} = usePersistentChat({
 		chatId,
 		onChatCreated: (newChatId) => {
@@ -92,7 +94,9 @@ export function ChatInterface({ chatId }: ChatInterfaceProps) {
 				messages={messages}
 				isLoading={isLoading}
 				isNewChat={isNewChat}
-				error={error ?? null}
+				isLoadingHistory={Boolean(chatId) && isLoadingMessages}
+				streamError={error ?? null}
+				onDismissStreamError={resetChatError}
 				stop={stop}
 				handleSubmit={handleSubmit}
 				onEditMessage={editMessage}
@@ -114,7 +118,9 @@ interface ChatInterfaceContentProps {
 	}>;
 	isLoading: boolean;
 	isNewChat: boolean;
-	error: Error | null;
+	isLoadingHistory: boolean;
+	streamError: Error | null;
+	onDismissStreamError: () => void;
 	stop: () => void;
 	handleSubmit: (message: PromptInputMessage) => Promise<void>;
 	onEditMessage: (messageId: string, newContent: string) => Promise<void>;
@@ -128,7 +134,9 @@ const ChatInterfaceContent = memo(function ChatInterfaceContent({
 	messages,
 	isLoading,
 	isNewChat,
-	error: _error,
+	isLoadingHistory,
+	streamError,
+	onDismissStreamError,
 	stop,
 	handleSubmit,
 	onEditMessage,
@@ -137,6 +145,8 @@ const ChatInterfaceContent = memo(function ChatInterfaceContent({
 	textareaRef,
 }: ChatInterfaceContentProps) {
 	const controller = usePromptInputController();
+	const promptValueRef = useRef(controller.textInput.value);
+	promptValueRef.current = controller.textInput.value;
 	const [editingMessageId, setEditingMessageId] = useState<string | null>(null);
 	const [isSavingEdit, setIsSavingEdit] = useState(false);
 	const savedDraftRef = useRef<string>("");
@@ -201,14 +211,14 @@ const ChatInterfaceContent = memo(function ChatInterfaceContent({
 
 	const startEdit = useCallback(
 		(messageId: string, content: string) => {
-			savedDraftRef.current = controller.textInput.value;
+			savedDraftRef.current = promptValueRef.current;
 			setEditingMessageId(messageId);
 			setInput(content);
 			setTimeout(() => {
 				textareaRef.current?.focus();
 			}, 0);
 		},
-		[controller.textInput.value, setInput, textareaRef],
+		[setInput, textareaRef],
 	);
 
 	const cancelEdit = useCallback(() => {
@@ -260,6 +270,9 @@ const ChatInterfaceContent = memo(function ChatInterfaceContent({
 				messages={messages}
 				isLoading={isLoading}
 				isNewChat={isNewChat}
+				isLoadingHistory={isLoadingHistory}
+				streamError={streamError}
+				onDismissStreamError={onDismissStreamError}
 				onPromptSelect={onPromptSelect}
 				onRetryMessage={onRetryMessage}
 				onForkMessage={onForkMessage}
@@ -270,11 +283,16 @@ const ChatInterfaceContent = memo(function ChatInterfaceContent({
 			<div className="px-2 md:px-4 pt-2 md:pt-4 pb-[max(0.5rem,env(safe-area-inset-bottom))] md:pb-4">
 				<div className="mx-auto max-w-3xl">
 					{editingMessageId && (
-						<div className="mb-2 flex items-center justify-between rounded-lg bg-primary/10 border border-primary/20 px-3 py-2">
+						<div
+							className="mb-2 flex items-center justify-between rounded-lg bg-primary/10 border border-primary/20 px-3 py-2"
+							role="status"
+							aria-live="polite"
+						>
 							<span className="text-sm text-primary font-medium">Editing message</span>
 							<button
 								type="button"
 								onClick={cancelEdit}
+								aria-label="Cancel editing message"
 								className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
 							>
 								<XIcon className="size-3" />
diff --git a/apps/web/src/components/chat/chat-message-list.tsx b/apps/web/src/components/chat/chat-message-list.tsx
index bca560a9..46345b96 100644
--- a/apps/web/src/components/chat/chat-message-list.tsx
+++ b/apps/web/src/components/chat/chat-message-list.tsx
@@ -1,4 +1,5 @@
 import { memo, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Loader2Icon, XIcon } from "lucide-react";
 import { toast } from "sonner";
 import { cn } from "@/lib/utils";
 import { useConversationScroll, Conversation, ConversationContent } from "@/components/ai-elements/conversation";
@@ -36,10 +37,16 @@ function AutoScroll({ messageCount }: { messageCount: number }) {
 
 function LoadingIndicator() {
 	return (
-		<div className="flex items-center gap-1.5 py-2">
-			<span className="size-2 animate-bounce rounded-full bg-foreground/40 [animation-delay:0ms]" />
-			<span className="size-2 animate-bounce rounded-full bg-foreground/40 [animation-delay:150ms]" />
-			<span className="size-2 animate-bounce rounded-full bg-foreground/40 [animation-delay:300ms]" />
+		<div
+			className="flex items-center gap-1.5 py-2"
+			role="status"
+			aria-live="polite"
+			aria-busy="true"
+		>
+			<span className="sr-only">Assistant is responding</span>
+			<span className="size-2 animate-bounce rounded-full bg-foreground/40 [animation-delay:0ms]" aria-hidden />
+			<span className="size-2 animate-bounce rounded-full bg-foreground/40 [animation-delay:150ms]" aria-hidden />
+			<span className="size-2 animate-bounce rounded-full bg-foreground/40 [animation-delay:300ms]" aria-hidden />
 		</div>
 	);
 }
@@ -54,6 +61,10 @@ export interface ChatMessageListProps {
 	}>;
 	isLoading: boolean;
 	isNewChat: boolean;
+	/** True while Convex history for an existing chat is still loading */
+	isLoadingHistory?: boolean;
+	streamError?: Error | null;
+	onDismissStreamError?: () => void;
 	onPromptSelect: (prompt: string) => void;
 	onRetryMessage: (messageId: string, modelId?: string) => Promise<void>;
 	onForkMessage: (messageId: string, modelId?: string) => Promise<void>;
@@ -66,6 +77,9 @@ export const ChatMessageList = memo(function ChatMessageList({
 	messages,
 	isLoading,
 	isNewChat,
+	isLoadingHistory = false,
+	streamError = null,
+	onDismissStreamError,
 	onPromptSelect,
 	onRetryMessage,
 	onForkMessage,
@@ -241,9 +255,44 @@ export const ChatMessageList = memo(function ChatMessageList({
 		<Conversation className="flex-1 px-2 md:px-4" showScrollButton>
 			<AutoScroll messageCount={messages.length} />
 			<ConversationContent className="mx-auto max-w-3xl pt-16 md:pt-6 pb-16 px-2 md:px-4">
-				{messages.length === 0 && isNewChat ? (
+				{streamError && (
+					<div
+						role="alert"
+						className="mb-4 flex gap-3 rounded-xl border border-destructive/30 bg-destructive/10 p-4 text-sm"
+					>
+						<div className="min-w-0 flex-1">
+							<p className="font-medium text-destructive">Something went wrong</p>
+							<p className="mt-1 text-destructive/80">{streamError.message}</p>
+						</div>
+						{onDismissStreamError ? (
+							<button
+								type="button"
+								onClick={onDismissStreamError}
+								className="shrink-0 rounded-lg p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+								aria-label="Dismiss error"
+							>
+								<XIcon className="size-4" />
+							</button>
+						) : null}
+					</div>
+				)}
+				{isLoadingHistory && messages.length === 0 ? (
+					<div
+						className="flex flex-col items-center justify-center gap-3 py-16 text-muted-foreground"
+						role="status"
+						aria-live="polite"
+						aria-busy="true"
+					>
+						<Loader2Icon className="size-8 animate-spin" aria-hidden />
+						<span className="sr-only">Loading conversation</span>
+					</div>
+				) : messages.length === 0 && isNewChat ? (
 					<StartScreen onPromptSelect={onPromptSelect} />
-				) : messages.length === 0 ? null : (
+				) : messages.length === 0 ? (
+					<p className="py-12 text-center text-sm text-muted-foreground">
+						No messages in this chat yet. Send a message below to start.
+					</p>
+				) : (
 					<>
 						{processedMessages.map((item, itemIndex) => {
 							if (item.shouldSkip) return null;
diff --git a/apps/web/src/components/chat/inline-error-message.tsx b/apps/web/src/components/chat/inline-error-message.tsx
index bb379cf1..ed7e61ed 100644
--- a/apps/web/src/components/chat/inline-error-message.tsx
+++ b/apps/web/src/components/chat/inline-error-message.tsx
@@ -61,12 +61,13 @@ export function InlineErrorMessage({ error, onRetry }: InlineErrorMessageProps)
 	return (
 		<div className="w-full rounded-xl border border-destructive/30 bg-destructive/10 p-4">
 			<div className="flex items-start gap-3">
-				<div className="flex-shrink-0 mt-0.5">
+				<div className="flex-shrink-0 mt-0.5" aria-hidden>
 					<svg
 						className="size-5 text-destructive"
 						fill="none"
 						viewBox="0 0 24 24"
 						stroke="currentColor"
+						aria-hidden
 					>
 						<path
 							strokeLinecap="round"
@@ -85,8 +86,10 @@ export function InlineErrorMessage({ error, onRetry }: InlineErrorMessageProps)
 					{error.details && (
 						<div className="mt-2">
 							<button
+								type="button"
 								onClick={() => setShowDetails(!showDetails)}
 								className="text-xs text-destructive/60 hover:text-destructive transition-colors"
+								aria-expanded={showDetails}
 							>
 								{showDetails ? "Hide details" : "Show details"}
 							</button>
diff --git a/apps/web/src/components/model-selector.tsx b/apps/web/src/components/model-selector.tsx
index 99596426..e6c365ec 100644
--- a/apps/web/src/components/model-selector.tsx
+++ b/apps/web/src/components/model-selector.tsx
@@ -170,10 +170,6 @@ export function ModelSelector({
 					e.preventDefault();
 					handleClose();
 					break;
-				case "Tab":
-					e.preventDefault();
-					handleClose();
-					break;
 			}
 		}
 
diff --git a/apps/web/src/components/model-selector/model-item.tsx b/apps/web/src/components/model-selector/model-item.tsx
index fcc9109d..a524ac08 100644
--- a/apps/web/src/components/model-selector/model-item.tsx
+++ b/apps/web/src/components/model-selector/model-item.tsx
@@ -71,6 +71,7 @@ export function ModelItem({
 							: "text-muted-foreground/20 hover:text-amber-400 opacity-0 group-hover:opacity-100",
 					)}
 					title={isFavorite ? "Remove from favorites" : "Add to favorites"}
+					aria-label={isFavorite ? `Remove ${model.name} from favorites` : `Add ${model.name} to favorites`}
 				>
 					<StarIcon filled={isFavorite} className="size-4" />
 				</button>
@@ -117,6 +118,7 @@ export function ModelItem({
 						onInfoHover();
 					}}
 					className="flex size-6 items-center justify-center rounded-md text-muted-foreground/40 transition-all duration-150 hover:text-foreground hover:bg-accent/80"
+					aria-label={`Model details for ${model.name}`}
 				>
 					<InfoIcon className="size-3.5" />
 				</button>
diff --git a/apps/web/src/hooks/__tests__/use-persistent-chat.test.ts b/apps/web/src/hooks/__tests__/use-persistent-chat.test.ts
index 53a1139a..2ae945f2 100644
--- a/apps/web/src/hooks/__tests__/use-persistent-chat.test.ts
+++ b/apps/web/src/hooks/__tests__/use-persistent-chat.test.ts
@@ -265,6 +265,7 @@ describe("initial state shape", () => {
 		expect(typeof result.current.retryMessage).toBe("function");
 		expect(typeof result.current.forkMessage).toBe("function");
 		expect(typeof result.current.stop).toBe("function");
+		expect(typeof result.current.resetChatError).toBe("function");
 	});
 });
 
@@ -411,6 +412,23 @@ describe("error tracking", () => {
 		});
 		expect(result.current.error).toBeUndefined();
 	});
+
+	it("resetChatError clears error and returns status from error to ready", async () => {
+		mockStartBackgroundStream.mockRejectedValueOnce(new Error("boom"));
+
+		const { result } = renderChat();
+		await act(async () => {
+			await result.current.sendMessage({ text: "Hello" });
+		});
+		expect(result.current.status).toBe("error");
+		expect(result.current.error).toBeTruthy();
+
+		await act(async () => {
+			result.current.resetChatError();
+		});
+		expect(result.current.error).toBeUndefined();
+		expect(result.current.status).toBe("ready");
+	});
 });
 
 // ---------------------------------------------------------------------------
diff --git a/apps/web/src/hooks/use-persistent-chat.ts b/apps/web/src/hooks/use-persistent-chat.ts
index 4a0006ef..00431283 100644
--- a/apps/web/src/hooks/use-persistent-chat.ts
+++ b/apps/web/src/hooks/use-persistent-chat.ts
@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useQuery } from "convex/react";
 import { api } from "@server/convex/_generated/api";
 import type { UIMessage } from "ai";
@@ -30,6 +30,8 @@ export interface UsePersistentChatReturn {
 	chatId: string | null;
 	isResuming: boolean;
 	resumedContent: string;
+	/** Clears the last stream/send error and returns status from `error` to `ready` when applicable */
+	resetChatError: () => void;
 }
 
 export function usePersistentChat({
@@ -84,6 +86,11 @@ export function usePersistentChat({
 		streamingRef,
 	});
 
+	const resetChatError = useCallback(() => {
+		setError(undefined);
+		setStatus((prev) => (prev === "error" ? "ready" : prev));
+	}, []);
+
 	const { sendMessage, editMessage, retryMessage, forkMessage } = useChatActions({
 		convexUserId,
 		isUserLoading,
@@ -117,5 +124,6 @@ export function usePersistentChat({
 		chatId: currentChatId,
 		isResuming,
 		resumedContent,
+		resetChatError,
 	};
 }
diff --git a/apps/web/src/routes/__root.tsx b/apps/web/src/routes/__root.tsx
index 3cb952f1..5710d7a2 100644
--- a/apps/web/src/routes/__root.tsx
+++ b/apps/web/src/routes/__root.tsx
@@ -17,6 +17,7 @@ import { usePostHogPageView } from "../providers/posthog";
 import { convexClient } from "../lib/convex";
 import { useGlobalShortcuts } from "@/hooks/use-global-shortcuts";
 import { ShortcutsDialog } from "@/components/shortcuts-dialog";
+import { AppLoadingPlaceholder } from "@/components/app-loading-placeholder";
 import type { InitialAuthUser } from "../lib/auth-client";
 
 import appCss from "../styles.css?url";
@@ -193,12 +194,7 @@ function AppShell() {
   const showHelpButton = isAuthenticated && (pathname === "/" || pathname.startsWith("/c/"));
 
   if (!convexClient || loading) {
-    return (
-      <div className="flex h-screen w-full bg-sidebar">
-        <div className="w-64 shrink-0 bg-sidebar" />
-        <div className="flex-1 bg-background" />
-      </div>
-    );
+    return <AppLoadingPlaceholder variant="app-shell" message="Loading application" />;
   }
 
   if (!isAuthenticated) {
diff --git a/apps/web/src/routes/c/$chatId.tsx b/apps/web/src/routes/c/$chatId.tsx
index 19a14f6c..a8bc0821 100644
--- a/apps/web/src/routes/c/$chatId.tsx
+++ b/apps/web/src/routes/c/$chatId.tsx
@@ -11,6 +11,7 @@ import { useAuth } from "@/lib/auth-client";
 import { ChatInterface } from "@/components/chat";
 import { Button } from "@/components/ui/button";
 import { convexClient } from "@/lib/convex";
+import { AppLoadingPlaceholder } from "@/components/app-loading-placeholder";
 
 export const Route = createFileRoute("/c/$chatId")({
   head: () => ({
@@ -27,7 +28,7 @@ function ChatPage() {
   const { isAuthenticated, loading } = useAuth();
 
   if (!convexClient || loading) {
-    return <div className="flex h-full bg-background" />;
+    return <AppLoadingPlaceholder message="Loading" />;
   }
 
   if (!isAuthenticated) {
diff --git a/apps/web/src/routes/index.tsx b/apps/web/src/routes/index.tsx
index 424041f6..18cb14a7 100644
--- a/apps/web/src/routes/index.tsx
+++ b/apps/web/src/routes/index.tsx
@@ -4,6 +4,7 @@ import { useAuth } from "../lib/auth-client";
 import { Button } from "../components/ui/button";
 import { ChatInterface } from "../components/chat";
 import { convexClient } from "../lib/convex";
+import { AppLoadingPlaceholder } from "../components/app-loading-placeholder";
 
 export const Route = createFileRoute('/')({
   component: HomePage,
@@ -104,6 +105,7 @@ function InteractiveStaircase({
       className={`${className} relative`}
       onMouseMove={handleMouseMove}
       onMouseLeave={handleMouseLeave}
+      aria-hidden
     >
       {squares.map(({ col, row, key }) => {
         const rightPos = (gridSize - 1 - col) * stepSize
@@ -241,7 +243,7 @@ function HomePage() {
   }, [isAuthenticated]);
 
   if (!convexClient || loading) {
-    return <div className="flex h-full bg-background" />;
+    return <AppLoadingPlaceholder message="Loading" />;
   }
 
   if (!isAuthenticated) {