fix(dexdex): enforce Esc-close and critical-input autofocus contracts (#268)

## Summary
- add repository/app-level UX rules requiring Esc-close dialogs and
autofocus on single critical-input forms
- update DexDex docs contracts to include the same UX invariants
- implement shared hooks (useEscapeToClose, useFocusOnShow) and apply
them across DexDex dialog/form surfaces
- add and extend tests for create-dialog Escape behavior and autofocus
scenarios

## Testing
- pnpm --filter dexdex test
- (from apps/dexdex) pnpm test

Author: kdy1

AGENTS.md

@@ -236,6 +236,8 @@ enum DexDexComponent {
 ### Frontend Design Rules
 
 - Frontend work in `apps/` must follow Toss Design Guidelines for UX/UI decisions across web and mobile surfaces.
+- If a form has a single critical input, that input must receive focus when the form is shown.
+- Dialog UIs must support closing with the `Esc` key.
 
 ### Shell Command Safety Rules
 

apps/AGENTS.md

@@ -5,6 +5,8 @@
 - Keep repository and domain rules in the appropriate `AGENTS.md` files.
 - Write all source and comments in English.
 - Follow Toss Design Guidelines for frontend UX/UI decisions across web and mobile apps.
+- If a form has a single critical input, that input must receive focus when the form is shown.
+- Dialog UIs must support closing with the `Esc` key.
 
 ### Scope in This Domain
 
@@ -54,6 +56,8 @@ enum DevkitMiniAppId {
 - Global shortcut question-handoff behavior (default binding, waiting-session routing, empty fallback) must remain aligned with DexDex app/server/proto contracts.
 - Menu bar tray behavior remains status-only unless docs explicitly expand scope; status derivation must use active-workspace contract semantics.
 - Session fork UX must keep parent-session immutability guarantees and remain limited to documented lifecycle actions.
+- Single critical-input forms in DexDex must auto-focus the input when shown.
+- DexDex dialog UIs must close with `Esc`.
 
 ### Multi-Component Contract Sync
 

apps/dexdex/src/App.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { describe, expect, it, beforeEach } from "vitest";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
@@ -485,6 +485,22 @@ describe("App", () => {
     await screen.findByTestId("task-list");
     await user.click(screen.getByTestId("create-task-button"));
     expect(screen.getByTestId("create-dialog")).toBeTruthy();
+    const promptInput = screen.getByTestId("task-prompt-input");
+    await waitFor(() => {
+      expect(document.activeElement).toBe(promptInput);
+    });
+  });
+
+  it("closes create task dialog with Escape", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<App />);
+
+    await screen.findByTestId("task-list");
+    await user.click(screen.getByTestId("create-task-button"));
+    expect(screen.getByTestId("create-dialog")).toBeTruthy();
+
+    await user.keyboard("{Escape}");
+    expect(screen.queryByTestId("create-dialog")).toBeNull();
   });
 
   it("creates a new task via dialog", async () => {
@@ -600,6 +616,34 @@ describe("App", () => {
     expect(screen.getByTestId("reject-button")).toBeTruthy();
   });
 
+  it("auto-focuses the revise input when revise mode opens", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<App />);
+
+    await screen.findByTestId("task-row-task-002");
+    await user.click(screen.getByTestId("task-row-task-002"));
+    await screen.findByTestId("plan-decisions");
+    await user.click(screen.getByTestId("revise-button"));
+
+    const reviseInput = screen.getByTestId("revision-note-input");
+    await waitFor(() => {
+      expect(document.activeElement).toBe(reviseInput);
+    });
+  });
+
+  it("auto-focuses session input for waiting-for-input subtasks", async () => {
+    const user = userEvent.setup();
+    renderWithProviders(<App />);
+
+    await screen.findByTestId("task-row-task-004");
+    await user.click(screen.getByTestId("task-row-task-004"));
+    const sessionInput = await screen.findByTestId("session-input-textarea");
+
+    await waitFor(() => {
+      expect(document.activeElement).toBe(sessionInput);
+    });
+  });
+
   it("shows subtask timeline in task detail", async () => {
     const user = userEvent.setup();
     renderWithProviders(<App />);

apps/dexdex/src/features/reviews/inline-comment-thread.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import type { ReviewComment } from "../../lib/mock-data";
+import { InlineCommentThread } from "./inline-comment-thread";
+
+const ACTIVE_COMMENT: ReviewComment = {
+  reviewCommentId: "comment-1",
+  body: "Please simplify this branch logic.",
+  filePath: "src/app.ts",
+  side: "RIGHT",
+  lineNumber: 42,
+  status: "ACTIVE",
+  prTrackingId: "pr-1",
+  createdAt: "2026-03-14T00:00:00Z",
+  updatedAt: "2026-03-14T00:00:00Z",
+};
+
+describe("InlineCommentThread", () => {
+  it("auto-focuses reply textarea when reply editor opens", async () => {
+    const user = userEvent.setup();
+    render(
+      <InlineCommentThread
+        filePath={ACTIVE_COMMENT.filePath}
+        lineNumber={ACTIVE_COMMENT.lineNumber}
+        side={ACTIVE_COMMENT.side}
+        comments={[ACTIVE_COMMENT]}
+        onReply={vi.fn()}
+        onResolve={vi.fn()}
+        onReopen={vi.fn()}
+        onDelete={vi.fn()}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "+ Reply" }));
+    const replyInput = screen.getByPlaceholderText("Reply... (Cmd+Enter to submit)");
+
+    await waitFor(() => {
+      expect(document.activeElement).toBe(replyInput);
+    });
+  });
+});

apps/dexdex/src/features/reviews/inline-comment-thread.tsx

@@ -3,8 +3,9 @@
  * Renders a thread of comments anchored to a specific file/line position.
  */
 
-import { type CSSProperties, useState } from "react";
+import { type CSSProperties, useRef, useState } from "react";
 import type { ReviewComment } from "../../lib/mock-data";
+import { useFocusOnShow } from "../../hooks/use-dialog-accessibility";
 
 interface InlineCommentThreadProps {
   filePath: string;
@@ -29,6 +30,9 @@ export function InlineCommentThread({
 }: InlineCommentThreadProps) {
   const [replyText, setReplyText] = useState("");
   const [showReply, setShowReply] = useState(false);
+  const replyInputRef = useRef<HTMLTextAreaElement>(null);
+
+  useFocusOnShow(showReply, replyInputRef);
 
   const isResolved = comments.length > 0 && comments[0].status === "RESOLVED";
 
@@ -116,6 +120,7 @@ export function InlineCommentThread({
         {showReply ? (
           <div>
             <textarea
+              ref={replyInputRef}
               value={replyText}
               onChange={(e) => setReplyText(e.target.value)}
               onKeyDown={handleKeyDown}

apps/dexdex/src/features/sessions/session-fork-panel.tsx

@@ -3,13 +3,14 @@
  * Supports creating new forks, archiving active forks, and navigating to forked sessions.
  */
 
-import { type CSSProperties, useCallback, useState } from "react";
+import { type CSSProperties, useCallback, useRef, useState } from "react";
 import {
   useListForkedSessions,
   useForkSessionMutation,
   useArchiveForkedSessionMutation,
   useListSessionCapabilities,
 } from "../../hooks/use-dexdex-queries";
+import { useEscapeToClose, useFocusOnShow } from "../../hooks/use-dialog-accessibility";
 import { toViewAgentCapability } from "../../lib/adapters";
 import { SessionForkStatus, SessionForkIntent, AgentSessionStatus } from "../../lib/status";
 import type { AgentCapability } from "../../lib/mock-data";
@@ -44,10 +45,19 @@ export function SessionForkPanel({ workspaceId, parentSessionId, onNavigateToSes
   const [showCreateDialog, setShowCreateDialog] = useState(false);
   const [forkIntent, setForkIntent] = useState<SessionForkIntent>(SessionForkIntent.EXPLORE_ALTERNATIVE);
   const [forkPrompt, setForkPrompt] = useState("");
+  const forkPromptRef = useRef<HTMLTextAreaElement>(null);
 
   const capabilities: AgentCapability[] = (capabilitiesQuery.data?.capabilities ?? []).map(toViewAgentCapability);
   const supportsFork = capabilities.some((c) => c.supportsFork);
 
+  const closeCreateDialog = useCallback(() => {
+    setShowCreateDialog(false);
+    setForkPrompt("");
+  }, []);
+
+  useEscapeToClose(showCreateDialog, closeCreateDialog);
+  useFocusOnShow(showCreateDialog, forkPromptRef);
+
   const handleCreateFork = useCallback(() => {
     if (!forkPrompt.trim()) return;
     forkMutation.mutate(
@@ -59,13 +69,12 @@ export function SessionForkPanel({ workspaceId, parentSessionId, onNavigateToSes
       },
       {
         onSuccess: () => {
-          setShowCreateDialog(false);
-          setForkPrompt("");
+          closeCreateDialog();
           setForkIntent(SessionForkIntent.EXPLORE_ALTERNATIVE);
         },
       },
     );
-  }, [workspaceId, parentSessionId, forkIntent, forkPrompt, forkMutation]);
+  }, [workspaceId, parentSessionId, forkIntent, forkPrompt, forkMutation, closeCreateDialog]);
 
   const handleArchive = useCallback(
     (sessionId: string) => {
@@ -243,6 +252,7 @@ export function SessionForkPanel({ workspaceId, parentSessionId, onNavigateToSes
             ))}
           </select>
           <textarea
+            ref={forkPromptRef}
             value={forkPrompt}
             onChange={(e) => setForkPrompt(e.target.value)}
             placeholder="Describe what this fork should explore..."
@@ -253,10 +263,7 @@ export function SessionForkPanel({ workspaceId, parentSessionId, onNavigateToSes
           <div style={{ display: "flex", gap: "var(--space-2)", marginTop: "var(--space-2)", justifyContent: "flex-end" }}>
             <button
               style={buttonStyle}
-              onClick={() => {
-                setShowCreateDialog(false);
-                setForkPrompt("");
-              }}
+              onClick={closeCreateDialog}
               data-testid="fork-cancel-button"
             >
               Cancel

apps/dexdex/src/features/sessions/session-input-form.tsx

@@ -3,8 +3,9 @@
  * Supports Cmd/Ctrl+Enter to submit and Enter for newline.
  */
 
-import { type CSSProperties, useCallback, useState } from "react";
+import { type CSSProperties, useCallback, useRef, useState } from "react";
 import { useSubmitSessionInputMutation } from "../../hooks/use-dexdex-queries";
+import { useFocusOnShow } from "../../hooks/use-dialog-accessibility";
 
 interface SessionInputFormProps {
   workspaceId: string;
@@ -15,6 +16,9 @@ interface SessionInputFormProps {
 export function SessionInputForm({ workspaceId, sessionId, onSubmitted }: SessionInputFormProps) {
   const [inputText, setInputText] = useState("");
   const submitMutation = useSubmitSessionInputMutation();
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  useFocusOnShow(true, inputRef);
 
   const handleSubmit = useCallback(() => {
     if (!inputText.trim()) return;
@@ -96,6 +100,7 @@ export function SessionInputForm({ workspaceId, sessionId, onSubmitted }: Sessio
     <div style={containerStyle} data-testid="session-input-form">
       <label style={labelStyle}>Session Input</label>
       <textarea
+        ref={inputRef}
         value={inputText}
         onChange={(e) => setInputText(e.target.value)}
         onKeyDown={handleKeyDown}

apps/dexdex/src/features/tasks/create-dialog.tsx

@@ -2,13 +2,14 @@
  * Create task dialog component.
  */
 
-import { type CSSProperties, type FormEvent, useEffect, useMemo, useState } from "react";
+import { type CSSProperties, type FormEvent, useEffect, useMemo, useRef, useState } from "react";
 import { AgentCliType } from "../../gen/v1/dexdex_pb";
 import {
   useGetWorkspaceSettings,
   useListRepositoryGroups,
   useListSessionCapabilities,
 } from "../../hooks/use-dexdex-queries";
+import { useEscapeToClose, useFocusOnShow } from "../../hooks/use-dialog-accessibility";
 
 interface CreateDialogProps {
   isOpen: boolean;
@@ -34,6 +35,7 @@ export function CreateDialog({ isOpen, workspaceId, onClose, onCreate }: CreateD
   const [selectedRepoGroupId, setSelectedRepoGroupId] = useState("");
   const [selectedAgent, setSelectedAgent] = useState<AgentCliType>(AgentCliType.UNSPECIFIED);
   const [usePlanMode, setUsePlanMode] = useState(false);
+  const promptInputRef = useRef<HTMLTextAreaElement>(null);
 
   const repoGroupsQuery = useListRepositoryGroups(workspaceId);
   const capabilitiesQuery = useListSessionCapabilities(workspaceId);
@@ -78,6 +80,9 @@ export function CreateDialog({ isOpen, workspaceId, onClose, onCreate }: CreateD
     }
   }, [selectedAgentSupportsPlanMode, usePlanMode]);
 
+  useEscapeToClose(isOpen, onClose);
+  useFocusOnShow(isOpen, promptInputRef);
+
   if (!isOpen) return null;
 
   const canSubmit = prompt.trim().length > 0 && selectedRepoGroupId.trim().length > 0 && selectedAgent !== AgentCliType.UNSPECIFIED;
@@ -160,11 +165,11 @@ export function CreateDialog({ isOpen, workspaceId, onClose, onCreate }: CreateD
             </label>
             <textarea
               id="task-prompt"
+              ref={promptInputRef}
               style={textareaStyle}
               value={prompt}
               onChange={(e) => setPrompt(e.target.value)}
               placeholder="Describe exactly what the coding agent should do..."
-              autoFocus
               data-testid="task-prompt-input"
             />
           </div>

apps/dexdex/src/features/tasks/plan-decisions.tsx

@@ -2,9 +2,10 @@
  * Plan decision controls for subtasks waiting for plan approval.
  */
 
-import { type CSSProperties, useState } from "react";
+import { type CSSProperties, useRef, useState } from "react";
 import { PlanDecision, SubTaskStatus } from "../../lib/status";
 import type { SubTask } from "../../lib/mock-data";
+import { useFocusOnShow } from "../../hooks/use-dialog-accessibility";
 
 interface PlanDecisionsProps {
   subtask: SubTask;
@@ -14,6 +15,9 @@ interface PlanDecisionsProps {
 export function PlanDecisions({ subtask, onDecision }: PlanDecisionsProps) {
   const [revisionNote, setRevisionNote] = useState("");
   const [showReviseInput, setShowReviseInput] = useState(false);
+  const revisionInputRef = useRef<HTMLTextAreaElement>(null);
+
+  useFocusOnShow(showReviseInput, revisionInputRef);
 
   if (subtask.status !== SubTaskStatus.WAITING_FOR_PLAN_APPROVAL) {
     return null;
@@ -69,6 +73,7 @@ export function PlanDecisions({ subtask, onDecision }: PlanDecisionsProps) {
       {showReviseInput && (
         <div style={{ marginTop: "var(--space-2)" }}>
           <textarea
+            ref={revisionInputRef}
             style={{
               width: "100%",
               padding: "var(--space-2)",

apps/dexdex/src/hooks/use-dialog-accessibility.ts

@@ -0,0 +1,39 @@
+import { type RefObject, useEffect } from "react";
+
+export function useEscapeToClose(enabled: boolean, onClose: () => void): void {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") {
+        return;
+      }
+
+      event.preventDefault();
+      event.stopPropagation();
+      onClose();
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => {
+      document.removeEventListener("keydown", handleKeyDown);
+    };
+  }, [enabled, onClose]);
+}
+
+export function useFocusOnShow<TElement extends HTMLElement>(
+  enabled: boolean,
+  elementRef: RefObject<TElement | null>,
+): void {
+  useEffect(() => {
+    if (!enabled) return;
+
+    const frameId = requestAnimationFrame(() => {
+      elementRef.current?.focus();
+    });
+
+    return () => {
+      cancelAnimationFrame(frameId);
+    };
+  }, [enabled, elementRef]);
+}