Stabilize inline selector keyboard handling (#4617)

## Thinking Path

> - Paperclip's board UI relies on compact selectors for frequent issue
and agent edits.
> - Inline selectors often live inside larger keyboard-aware surfaces
such as composers and popovers.
> - Arrow, enter, tab, and escape keys handled by the selector should
not leak to parent document shortcuts.
> - Stale company selection should also stay hidden until the company
list confirms it is valid.
> - This pull request tightens inline selector keyboard handling and
adds regression coverage for stale company bootstrap behavior.
> - The benefit is fewer accidental parent interactions and safer
company-scoped UI initialization.

## What Changed

- Added a stable empty `recentOptionIds` default so selector filtering
does not get a new array every render.
- Mirrored highlighted option state into a ref so Enter/Tab commits the
current highlighted option reliably after keyboard navigation.
- Stopped propagation for selector-owned navigation/commit/escape keys.
- Added jsdom regressions for inline selector keyboard handling and
CompanyProvider stale selection behavior.

## Verification

- `pnpm exec vitest run ui/src/components/InlineEntitySelector.test.tsx
ui/src/context/CompanyContext.test.tsx`
- Targeted selector and CompanyProvider tests pass cleanly without React
`act(...)` warnings.
- Screenshots not attached: this is keyboard/state behavior covered by
component tests.

## Risks

- Low risk: changes are scoped to inline selector key handling and
tests. The main behavior shift is intentionally preventing handled
selector keys from reaching parent listeners.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex coding agent based on GPT-5, tool-enabled local
repository and shell access, Paperclip heartbeat context.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/components/InlineEntitySelector.test.tsx

@@ -0,0 +1,80 @@
+// @vitest-environment jsdom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { InlineEntitySelector } from "./InlineEntitySelector";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("InlineEntitySelector", () => {
+  let container: HTMLDivElement;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+    document.body.innerHTML = "";
+  });
+
+  it("keeps handled search navigation keys inside the popover", async () => {
+    const root = createRoot(container);
+    const onChange = vi.fn();
+    const documentKeyDown = vi.fn();
+    document.addEventListener("keydown", documentKeyDown);
+
+    act(() => {
+      root.render(
+        <InlineEntitySelector
+          value=""
+          options={[
+            { id: "agent:agent-1", label: "CodexCoder" },
+            { id: "agent:agent-2", label: "DesignBot" },
+          ]}
+          placeholder="Assignee"
+          noneLabel="No assignee"
+          searchPlaceholder="Search assignees..."
+          emptyMessage="No assignees found."
+          onChange={onChange}
+        />,
+      );
+    });
+
+    const trigger = container.querySelector("button") as HTMLButtonElement | null;
+    expect(trigger).not.toBeNull();
+
+    await act(async () => {
+      trigger?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+
+    const searchInput = document.querySelector('input[placeholder="Search assignees..."]') as HTMLInputElement | null;
+    expect(searchInput).not.toBeNull();
+    searchInput?.focus();
+
+    await act(async () => {
+      await Promise.resolve();
+    });
+
+    await act(async () => {
+      searchInput?.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "ArrowDown" }));
+    });
+
+    expect(documentKeyDown).not.toHaveBeenCalled();
+
+    await act(async () => {
+      searchInput?.dispatchEvent(new KeyboardEvent("keydown", { bubbles: true, key: "Enter" }));
+    });
+
+    expect(documentKeyDown).not.toHaveBeenCalled();
+    expect(onChange).toHaveBeenCalledWith("agent:agent-1");
+
+    document.removeEventListener("keydown", documentKeyDown);
+    act(() => {
+      root.unmount();
+    });
+  });
+});

ui/src/components/InlineEntitySelector.tsx

@@ -1,4 +1,4 @@
-import { forwardRef, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { forwardRef, useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { Check } from "lucide-react";
 import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
 import { orderItemsBySelectedAndRecent } from "../lib/recent-selections";
@@ -29,6 +29,8 @@ interface InlineEntitySelectorProps {
   openOnFocus?: boolean;
 }
 
+const EMPTY_RECENT_OPTION_IDS: string[] = [];
+
 export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySelectorProps>(
   function InlineEntitySelector(
     {
@@ -43,7 +45,7 @@ export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySe
       className,
       renderTriggerValue,
       renderOption,
-      recentOptionIds = [],
+      recentOptionIds = EMPTY_RECENT_OPTION_IDS,
       disablePortal,
       openOnFocus = true,
     },
@@ -52,6 +54,7 @@ export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySe
     const [open, setOpen] = useState(false);
     const [query, setQuery] = useState("");
     const [highlightedIndex, setHighlightedIndex] = useState(0);
+    const highlightedIndexRef = useRef(0);
     const inputRef = useRef<HTMLInputElement>(null);
     const shouldPreventCloseAutoFocusRef = useRef(false);
     const isPointerDownRef = useRef(false);
@@ -72,11 +75,17 @@ export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySe
 
     const currentOption = options.find((option) => option.id === value) ?? null;
 
+    const setHighlightedIndexValue = useCallback((next: number | ((current: number) => number)) => {
+      const resolved = typeof next === "function" ? next(highlightedIndexRef.current) : next;
+      highlightedIndexRef.current = resolved;
+      setHighlightedIndex(resolved);
+    }, []);
+
     useEffect(() => {
       if (!open) return;
       const selectedIndex = filteredOptions.findIndex((option) => option.id === value);
-      setHighlightedIndex(selectedIndex >= 0 ? selectedIndex : 0);
+      setHighlightedIndexValue(selectedIndex >= 0 ? selectedIndex : 0);
-    }, [filteredOptions, open, value]);
+    }, [filteredOptions, open, setHighlightedIndexValue, value]);
 
     const commitSelection = (index: number, moveNext: boolean) => {
       const option = filteredOptions[index] ?? filteredOptions[0];
@@ -153,14 +162,16 @@ export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySe
             onKeyDown={(event) => {
               if (event.key === "ArrowDown") {
                 event.preventDefault();
-                setHighlightedIndex((current) =>
+                event.stopPropagation();
+                setHighlightedIndexValue((current) =>
                   filteredOptions.length === 0 ? 0 : (current + 1) % filteredOptions.length,
                 );
                 return;
               }
               if (event.key === "ArrowUp") {
                 event.preventDefault();
-                setHighlightedIndex((current) => {
+                event.stopPropagation();
+                setHighlightedIndexValue((current) => {
                   if (filteredOptions.length === 0) return 0;
                   return current <= 0 ? filteredOptions.length - 1 : current - 1;
                 });
@@ -168,16 +179,19 @@ export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySe
               }
               if (event.key === "Enter") {
                 event.preventDefault();
-                commitSelection(highlightedIndex, true);
+                event.stopPropagation();
+                commitSelection(highlightedIndexRef.current, true);
                 return;
               }
               if (event.key === "Tab" && !event.shiftKey) {
                 event.preventDefault();
-                commitSelection(highlightedIndex, true);
+                event.stopPropagation();
+                commitSelection(highlightedIndexRef.current, true);
                 return;
               }
               if (event.key === "Escape") {
                 event.preventDefault();
+                event.stopPropagation();
                 setOpen(false);
               }
             }}
@@ -197,7 +211,7 @@ export const InlineEntitySelector = forwardRef<HTMLButtonElement, InlineEntitySe
                       "flex w-full items-center gap-2 rounded px-2 py-1.5 text-left text-sm touch-manipulation",
                       isHighlighted && "bg-accent",
                     )}
-                    onMouseEnter={() => setHighlightedIndex(index)}
+                    onMouseEnter={() => setHighlightedIndexValue(index)}
                     onClick={() => commitSelection(index, true)}
                   >
                     {renderOption ? renderOption(option, isSelected) : <span className="truncate">{option.label}</span>}

ui/src/context/CompanyContext.test.tsx

@@ -1,10 +1,64 @@
-import { describe, expect, it } from "vitest";
+// @vitest-environment jsdom
-import { resolveBootstrapCompanySelection, shouldClearStoredCompanySelection } from "./CompanyContext";
+
+import { act, useEffect } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { Company } from "@paperclipai/shared";
+import { queryKeys } from "../lib/queryKeys";
+import {
+  CompanyProvider,
+  resolveBootstrapCompanySelection,
+  shouldClearStoredCompanySelection,
+  useCompany,
+} from "./CompanyContext";
+
+const mockCompaniesApi = vi.hoisted(() => ({
+  list: vi.fn(),
+  create: vi.fn(),
+}));
+
+vi.mock("../api/companies", () => ({
+  companiesApi: mockCompaniesApi,
+}));
 
 const activeCompany = { id: "company-1" };
 const secondActiveCompany = { id: "company-2" };
 const archivedCompany = { id: "archived-company" };
 
+function makeCompany(id: string): Company {
+  return {
+    id,
+    name: "Paperclip",
+    description: null,
+    status: "active",
+    pauseReason: null,
+    pausedAt: null,
+    issuePrefix: "PAP",
+    issueCounter: 1,
+    budgetMonthlyCents: 0,
+    spentMonthlyCents: 0,
+    requireBoardApprovalForNewAgents: false,
+    feedbackDataSharingEnabled: false,
+    feedbackDataSharingConsentAt: null,
+    feedbackDataSharingConsentByUserId: null,
+    feedbackDataSharingTermsVersion: null,
+    brandColor: null,
+    logoAssetId: null,
+    logoUrl: null,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}
+
+function Probe({ onSelectedCompanyId }: { onSelectedCompanyId: (companyId: string | null) => void }) {
+  const { selectedCompanyId } = useCompany();
+  useEffect(() => {
+    onSelectedCompanyId(selectedCompanyId);
+  }, [onSelectedCompanyId, selectedCompanyId]);
+  return <div data-selected-company-id={selectedCompanyId ?? ""} />;
+}
+
 describe("resolveBootstrapCompanySelection", () => {
   it("does not expose a stale stored company id before companies load", () => {
     expect(resolveBootstrapCompanySelection({
@@ -69,3 +123,72 @@ describe("shouldClearStoredCompanySelection", () => {
     })).toBe(true);
   });
 });
+
+describe("CompanyProvider", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+  let queryClient: QueryClient;
+
+  beforeEach(() => {
+    (globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+    localStorage.clear();
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    queryClient = new QueryClient({
+      defaultOptions: {
+        queries: { retry: false },
+      },
+    });
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      root.unmount();
+    });
+    queryClient.clear();
+    container.remove();
+    vi.clearAllMocks();
+  });
+
+  it("does not expose a stale stored company id before companies load", async () => {
+    localStorage.setItem("paperclip.selectedCompanyId", "stale-company");
+    mockCompaniesApi.list.mockImplementation(() => new Promise(() => {}));
+    const seen: Array<string | null> = [];
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <CompanyProvider>
+            <Probe onSelectedCompanyId={(companyId) => seen.push(companyId)} />
+          </CompanyProvider>
+        </QueryClientProvider>,
+      );
+    });
+
+    expect(seen).toEqual([null]);
+  });
+
+  it("replaces a stale stored company id with the first loaded company", async () => {
+    localStorage.setItem("paperclip.selectedCompanyId", "stale-company");
+    queryClient.setQueryData(queryKeys.companies.all, {
+      companies: [makeCompany("company-1")],
+      unauthorized: false,
+    });
+    mockCompaniesApi.list.mockImplementation(() => new Promise(() => {}));
+    const seen: Array<string | null> = [];
+
+    await act(async () => {
+      root.render(
+        <QueryClientProvider client={queryClient}>
+          <CompanyProvider>
+            <Probe onSelectedCompanyId={(companyId) => seen.push(companyId)} />
+          </CompanyProvider>
+        </QueryClientProvider>,
+      );
+    });
+
+    expect(seen).toEqual([null, "company-1"]);
+    expect(localStorage.getItem("paperclip.selectedCompanyId")).toBe("company-1");
+  });
+});