@jupyter-ai/persona-manager 0.1.2 → 0.2.0-a0

package/lib/persona-controls.d.ts

@@ -27,6 +27,36 @@ export type Control = {
  * The user's current selection seeds each control's `selection`.
  */
 export declare function buildControls(persona: PersonaAwareness | null, settings: PersonaSettings): Control[];
+/**
+ * Decide which persona list the toolbar should display: a freshly read empty
+ * list is treated as a transient blip (e.g. a Yjs awareness sync hiccup
+ * during a persona reload) rather than "no personas", so the toolbar keeps
+ * showing the previous list instead of unmounting - `PersonaControls` hides
+ * itself entirely when `personas.length === 0`, so accepting every empty
+ * read verbatim flashes the whole toolbar (persona name, model picker,
+ * everything) to nothing and back on each blip. A genuinely personas-less
+ * chat never reads a non-empty list in the first place, so this doesn't mask
+ * that case - it only guards against reverting an already-populated list.
+ */
+export declare function reconcilePersonas(previous: PersonaOption[], next: PersonaOption[]): PersonaOption[];
+/**
+ * Decide which selected-persona state the toolbar should track: a fresh
+ * null read is treated as a transient blip (the same class of awareness
+ * sync hiccup `reconcilePersonas` guards against, e.g. during a persona
+ * reload) rather than "nothing selected", so the toolbar keeps the last
+ * known state instead of dropping it. This one is not just cosmetic:
+ * `buildControls` returns `[]` for a null persona state, so `controls`
+ * reads empty and `PersonaControls` conditionally unmounts `ControlsRow`
+ * entirely - destroying any open `ControlMenu`'s own state (its search
+ * query, its open popover) mid-interaction, not merely blanking a label.
+ *
+ * Only for the *recurring* awareness-driven read, not the initial one: the
+ * initial read (on mount, or when `selectedId` itself changes to a
+ * different persona) must apply unconditionally, including a genuine null
+ * result, or switching personas could show the previous persona's stale
+ * state under the new selection.
+ */
+export declare function reconcilePersonaState(previous: PersonaAwareness | null, next: PersonaAwareness | null): PersonaAwareness | null;
 /**
  * Decide how to reconcile the current selection with a freshly read persona
  * list: the new selection to apply, or `undefined` to keep the current one.
@@ -51,10 +81,35 @@ export declare function showLoadingPlaceholder(hasAwareness: boolean, managerRes
  * control's kind. A null value resets that control to the persona's default.
  */
 export declare function applyControlChange(settings: PersonaSettings, control: Control, value: string | null): PersonaSettings;
+/** One selectable row in a control's dropdown: an option, or the leading
+ * "Default" row (`id: null`). */
+type Choice = {
+    id: string | null;
+    primary: string;
+    description: string | null;
+};
+/**
+ * Filter a control's choices by a search query: a case-insensitive substring
+ * match against each choice's name. An empty (or whitespace-only) query
+ * matches everything, so a freshly opened menu shows the full list. The
+ * leading "Default" choice (`id: null`) is excluded from filtering entirely -
+ * always kept, and always first - since it's a fixed, load-bearing option
+ * (what "no explicit selection" resolves to), not just another item to
+ * search among.
+ */
+export declare function filterChoices(choices: Choice[], query: string): Choice[];
 /**
- * A dropdown for a control, titled with the control's label. The first choice
- * row is "Default" (selection = null); the rest are the persona's advertised
- * options (selection = that option's id). Exported for tests.
+ * A searchable dropdown for a control, titled with the control's label. The
+ * first choice row is always "Default" (selection = null, never filtered
+ * out); the rest are the persona's advertised options (selection = that
+ * option's id), filtered by the search box as the user types. Exported for
+ * tests.
+ *
+ * Built on `Popover` rather than `Menu`/`MenuList`: `MenuList` owns its own
+ * keyboard handling (arrow keys, type-ahead-by-letter) which would fight a
+ * text input for keystrokes, so with a search box in the picture this
+ * component manages its own keyboard navigation (`focusedIndex`) instead of
+ * relying on `MenuList`'s.
  */
 export declare function ControlMenu(props: {
     control: Control;
@@ -117,3 +172,4 @@ export declare function PersonaControls(props: InputToolbarRegistry.IToolbarItem
      */
     controlRegistry?: IPersonaControlRegistry;
 }): JSX.Element | null;
+export {};

package/lib/persona-controls.js

@@ -1,5 +1,5 @@
 import React, { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from 'react';
-import { Button, ListItemText, ListSubheader, Menu, MenuItem, Popover, Skeleton } from '@mui/material';
+import { Button, ListItemText, ListSubheader, Menu, MenuItem, Popover, Skeleton, TextField } from '@mui/material';
 import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown';
 import CheckIcon from '@mui/icons-material/Check';
 import MoreHorizIcon from '@mui/icons-material/MoreHoriz';
@@ -89,6 +89,40 @@ export function buildControls(persona, settings) {
     }
     return controls;
 }
+/**
+ * Decide which persona list the toolbar should display: a freshly read empty
+ * list is treated as a transient blip (e.g. a Yjs awareness sync hiccup
+ * during a persona reload) rather than "no personas", so the toolbar keeps
+ * showing the previous list instead of unmounting - `PersonaControls` hides
+ * itself entirely when `personas.length === 0`, so accepting every empty
+ * read verbatim flashes the whole toolbar (persona name, model picker,
+ * everything) to nothing and back on each blip. A genuinely personas-less
+ * chat never reads a non-empty list in the first place, so this doesn't mask
+ * that case - it only guards against reverting an already-populated list.
+ */
+export function reconcilePersonas(previous, next) {
+    return next.length ? next : previous;
+}
+/**
+ * Decide which selected-persona state the toolbar should track: a fresh
+ * null read is treated as a transient blip (the same class of awareness
+ * sync hiccup `reconcilePersonas` guards against, e.g. during a persona
+ * reload) rather than "nothing selected", so the toolbar keeps the last
+ * known state instead of dropping it. This one is not just cosmetic:
+ * `buildControls` returns `[]` for a null persona state, so `controls`
+ * reads empty and `PersonaControls` conditionally unmounts `ControlsRow`
+ * entirely - destroying any open `ControlMenu`'s own state (its search
+ * query, its open popover) mid-interaction, not merely blanking a label.
+ *
+ * Only for the *recurring* awareness-driven read, not the initial one: the
+ * initial read (on mount, or when `selectedId` itself changes to a
+ * different persona) must apply unconditionally, including a genuine null
+ * result, or switching personas could show the previous persona's stale
+ * state under the new selection.
+ */
+export function reconcilePersonaState(previous, next) {
+    return next !== null && next !== void 0 ? next : previous;
+}
 /**
  * Decide how to reconcile the current selection with a freshly read persona
  * list: the new selection to apply, or `undefined` to keep the current one.
@@ -192,6 +226,11 @@ function ChoiceMenuItem(props) {
     // MenuList clones the row it picks for initial focus with extra props
     // (tabIndex, autoFocus); forward them to the MenuItem, or no row is ever
     // focused and the menu's arrow-key and type-ahead handling never engages.
+    // Shared by OverflowControlsMenu (still a real Menu/MenuList, still
+    // depends on this) and ControlMenu (no longer rendered inside a
+    // MenuList - see the comment there - so this spread is a no-op for it,
+    // and it leaves `role` at MenuItem's own default rather than overriding
+    // it, to avoid disturbing OverflowControlsMenu's ARIA contract).
     const { primary, description: rawDescription, selected, onSelect, ...menuItemProps } = props;
     const description = rawDescription &&
         rawDescription.trim().toLowerCase() !== primary.trim().toLowerCase()
@@ -204,6 +243,24 @@ function ChoiceMenuItem(props) {
             } }),
         selected ? (React.createElement(CheckIcon, { className: `${MENU_CLASS}-check`, fontSize: "small" })) : null));
 }
+/**
+ * Filter a control's choices by a search query: a case-insensitive substring
+ * match against each choice's name. An empty (or whitespace-only) query
+ * matches everything, so a freshly opened menu shows the full list. The
+ * leading "Default" choice (`id: null`) is excluded from filtering entirely -
+ * always kept, and always first - since it's a fixed, load-bearing option
+ * (what "no explicit selection" resolves to), not just another item to
+ * search among.
+ */
+export function filterChoices(choices, query) {
+    const defaultChoice = choices.filter(c => c.id === null);
+    const rest = choices.filter(c => c.id !== null);
+    const q = query.trim().toLowerCase();
+    const filteredRest = q
+        ? rest.filter(c => c.primary.toLowerCase().includes(q))
+        : rest;
+    return [...defaultChoice, ...filteredRest];
+}
 /**
  * The "Default" row shown at the top of every control. Selecting it sets the
  * user's value to null, i.e. "use the persona's current value". Its label shows
@@ -231,30 +288,104 @@ function ControlMenuSubheader(props) {
 // static; ListSubheader's own copy is hidden behind the wrapper.
 ControlMenuSubheader.muiSkipListHighlight = true;
 /**
- * A dropdown for a control, titled with the control's label. The first choice
- * row is "Default" (selection = null); the rest are the persona's advertised
- * options (selection = that option's id). Exported for tests.
+ * A searchable dropdown for a control, titled with the control's label. The
+ * first choice row is always "Default" (selection = null, never filtered
+ * out); the rest are the persona's advertised options (selection = that
+ * option's id), filtered by the search box as the user types. Exported for
+ * tests.
+ *
+ * Built on `Popover` rather than `Menu`/`MenuList`: `MenuList` owns its own
+ * keyboard handling (arrow keys, type-ahead-by-letter) which would fight a
+ * text input for keystrokes, so with a search box in the picture this
+ * component manages its own keyboard navigation (`focusedIndex`) instead of
+ * relying on `MenuList`'s.
  */
 export function ControlMenu(props) {
     const { control, onSelect } = props;
     const [anchor, setAnchor] = useState(null);
+    const [query, setQuery] = useState('');
+    // Index into the *filtered* choice list (Default row included at 0), for
+    // arrow-key navigation. Reset whenever the query changes, since the
+    // previously-focused row may no longer be in the filtered list.
+    const [focusedIndex, setFocusedIndex] = useState(0);
     // The heading names the menu for assistive tech: the subheader itself is a
     // roleless, never-focused list row, so without this wiring the popup has no
     // accessible name at all.
     const headingId = useId();
+    const choices = [
+        { id: null, primary: defaultChoiceLabel(control), description: null },
+        ...control.options.map(o => ({
+            id: o.id,
+            primary: o.name,
+            description: o.description
+        }))
+    ];
+    const filtered = filterChoices(choices, query);
+    const close = () => {
+        setAnchor(null);
+        setQuery('');
+        setFocusedIndex(0);
+    };
+    const select = (id) => {
+        close();
+        onSelect(id);
+    };
+    const handleQueryChange = (event) => {
+        setQuery(event.target.value);
+        setFocusedIndex(0);
+    };
+    const handleKeyDown = (event) => {
+        if (!filtered.length) {
+            if (event.key === 'Escape') {
+                close();
+            }
+            return;
+        }
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault();
+                setFocusedIndex(i => (i + 1) % filtered.length);
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                setFocusedIndex(i => (i - 1 + filtered.length) % filtered.length);
+                break;
+            case 'Enter': {
+                event.preventDefault();
+                const choice = filtered[focusedIndex];
+                if (choice) {
+                    select(choice.id);
+                }
+                break;
+            }
+            case 'Escape':
+                event.preventDefault();
+                close();
+                break;
+        }
+    };
+    // Open focused on the currently selected row (falling back to Default,
+    // index 0, when the selection is stale/absent) - computed fresh on each
+    // open rather than via a lazy useState initializer, since this component
+    // instance persists across opens/closes (only `anchor` toggles), so a
+    // one-time initializer would never re-run for a later open.
+    const openMenu = (event) => {
+        setAnchor(event.currentTarget);
+        const idx = choices.findIndex(c => c.id === control.selection);
+        setFocusedIndex(idx >= 0 ? idx : 0);
+    };
     return (React.createElement(React.Fragment, null,
-        React.createElement(Button, { className: `${SELECTOR_CLASS} ${SELECTOR_CLASS}-control-btn`, size: "small", variant: "text", disableRipple: true, endIcon: React.createElement(ArrowDropDownIcon, { className: `${SELECTOR_CLASS}-arrow` }), onClick: event => setAnchor(event.currentTarget), title: control.label },
+        React.createElement(Button, { className: `${SELECTOR_CLASS} ${SELECTOR_CLASS}-control-btn`, size: "small", variant: "text", disableRipple: true, endIcon: React.createElement(ArrowDropDownIcon, { className: `${SELECTOR_CLASS}-arrow` }), onClick: openMenu, title: control.label },
             React.createElement("span", { className: `${SELECTOR_CLASS}-control-value` }, currentControlLabel(control))),
-        React.createElement(Menu, { anchorEl: anchor, open: !!anchor, onClose: () => setAnchor(null), MenuListProps: { 'aria-labelledby': headingId }, ...menuAnchorProps },
+        React.createElement(Popover, { anchorEl: anchor, open: !!anchor, onClose: close, ...menuAnchorProps },
             React.createElement(ControlMenuSubheader, { id: headingId, label: control.label }),
-            React.createElement(ChoiceMenuItem, { primary: defaultChoiceLabel(control), description: null, selected: control.selection === null, onSelect: () => {
-                    setAnchor(null);
-                    onSelect(null);
-                } }),
-            control.options.map(option => (React.createElement(ChoiceMenuItem, { key: option.id, primary: option.name, description: option.description, selected: control.selection === option.id, onSelect: () => {
-                    setAnchor(null);
-                    onSelect(option.id);
-                } }))))));
+            control.options.length > 0 ? (React.createElement(TextField, { autoFocus: true, fullWidth: true, size: "small", variant: "standard", placeholder: `Search ${control.label.toLowerCase()}`, value: query, onChange: handleQueryChange, onKeyDown: handleKeyDown, className: `${MENU_CLASS}-search-input` })) : null,
+            React.createElement("div", { role: "group", "aria-labelledby": headingId, className: `${MENU_CLASS}-search-list` }, filtered.length ? (filtered.map((choice, index) => {
+                var _a;
+                return (React.createElement(ChoiceMenuItem, { key: (_a = choice.id) !== null && _a !== void 0 ? _a : '__default__', primary: choice.primary, description: choice.description, selected: control.selection === choice.id, onSelect: () => select(choice.id), className: index === focusedIndex
+                        ? `${MENU_CLASS}-kbd-focused`
+                        : undefined }));
+            })) : (React.createElement(MenuItem, { disabled: true }, "No matches"))))));
 }
 /**
  * The overflow popover: controls that did not fit inline, shown as a single flat
@@ -567,7 +698,7 @@ export function PersonaControls(props) {
             return;
         }
         const list = manager.personas;
-        setPersonas(list);
+        setPersonas(prev => reconcilePersonas(prev, list));
         setSelectedId(current => {
             const next = reconcileSelection(list, current, userPicked.current);
             return next === undefined ? current : next;
@@ -596,14 +727,19 @@ export function PersonaControls(props) {
     };
     // Track the selected persona's view in state, re-reading on every awareness
     // change (a persona updating usage, model, or commands) so the toolbar
-    // reflects the latest published state.
+    // reflects the latest published state. The first read (right below)
+    // applies unconditionally, since it runs whenever `selectedId` itself
+    // changes and must reflect the newly selected persona, even a genuinely
+    // absent one; every later read goes through reconcilePersonaState so a
+    // transient blip doesn't blank this out - see its comment for why that
+    // matters more than it looks like it should.
     useEffect(() => {
         if (!awareness || !manager || !selectedId) {
             setPersonaState(null);
             return;
         }
-        const read = () => setPersonaState(readSelectedPersona());
-        read();
+        setPersonaState(readSelectedPersona());
+        const read = () => setPersonaState(prev => reconcilePersonaState(prev, readSelectedPersona()));
         awareness.on('change', read);
         return () => {
             awareness.off('change', read);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jupyter-ai/persona-manager",
-    "version": "0.1.2",
+    "version": "0.2.0-a0",
     "description": "The core manager & registry for AI personas in Jupyter AI",
     "keywords": [
         "jupyter",

package/src/__tests__/persona-controls-menus.spec.tsx

@@ -5,7 +5,7 @@
  * type-ahead, and Enter drive the choice rows.
  */
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {
   Control,
@@ -14,6 +14,16 @@ import {
 } from '../persona-controls';
 
 const SUBHEADER_SELECTOR = 'li.jp-jai-controlMenu-subheader';
+const KBD_FOCUSED_SELECTOR = 'li.jp-jai-controlMenu-kbd-focused';
+const RESULTS_SELECTOR = 'div.jp-jai-controlMenu-search-list';
+
+// The trigger button shows the current effective value as its own label
+// (e.g. "Beta" when that's selected), which can collide with a row of the
+// same name in the open dropdown - scope result-row queries to the results
+// list, not the whole document, to avoid matching the button too.
+function results(): HTMLElement {
+  return document.querySelector(RESULTS_SELECTOR) as HTMLElement;
+}
 
 function modelControl(selection: string | null): Control {
   return {
@@ -37,6 +47,14 @@ function focused(): HTMLElement {
   return document.activeElement as HTMLElement;
 }
 
+// ControlMenu shows keyboard navigation as a visual highlight on the
+// currently-considered row rather than moving real DOM focus off the search
+// input (see the comment on ControlMenu in persona-controls.tsx) - so
+// keyboard-driven tests read this instead of `focused()`.
+function highlighted(): HTMLElement | null {
+  return document.querySelector(KBD_FOCUSED_SELECTOR);
+}
+
 describe('control menus', () => {
   describe('control dropdown', () => {
     async function openMenu(
@@ -54,55 +72,75 @@ describe('control menus', () => {
       expect(heading().textContent).toBe('Model');
       expect(heading().hasAttribute('tabindex')).toBe(false);
       expect(heading().id).toBeTruthy();
-      expect(screen.getByRole('menu').getAttribute('aria-labelledby')).toBe(
-        heading().id
-      );
       // Sticky, so the title stays visible while a long option list scrolls.
       expect(heading().classList.contains('MuiListSubheader-sticky')).toBe(
         true
       );
     });
 
-    it('focuses the selected row and moves focus with the keyboard', async () => {
+    it('opens with the search box focused, so typing filters immediately', async () => {
+      await openMenu(modelControl('beta'));
+      expect(focused()).toBe(screen.getByPlaceholderText('Search model'));
+    });
+
+    it('highlights the selected row on open, without moving real focus off the search box', async () => {
       const user = await openMenu(modelControl('beta'));
-      // Rows: heading, "Default (Alpha)", "Alpha", "Beta"; "Beta" is selected.
-      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Beta' }));
-      // Wrapping from the last row skips the heading to the first choice row.
+      expect(highlighted()?.textContent).toContain('Beta');
+      // Real DOM focus never leaves the search box - arrow keys move the
+      // highlight, not focus, so the user can keep typing at any point.
       await user.keyboard('{ArrowDown}');
-      expect(focused()).toBe(
-        screen.getByRole('menuitem', { name: 'Default (Alpha)' })
-      );
+      expect(focused()).toBe(screen.getByPlaceholderText('Search model'));
+    });
+
+    it('falls back to the Default row when the selection is stale', async () => {
+      // A selection id the persona no longer advertises matches no row;
+      // initial highlight then falls back to the Default row.
+      await openMenu(modelControl('stale'));
+      expect(highlighted()?.textContent).toContain('Default (Alpha)');
+    });
+
+    it('moves the highlight with the arrow keys, wrapping at both ends', async () => {
+      // Rows: "Default (Alpha)", "Alpha", "Beta"; starts on "Beta" (selected).
+      const user = await openMenu(modelControl('beta'));
+      expect(highlighted()?.textContent).toContain('Beta');
       await user.keyboard('{ArrowDown}');
-      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Alpha' }));
-      // Type-ahead: "b" jumps to Beta.
-      await user.keyboard('b');
-      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Beta' }));
+      expect(highlighted()?.textContent).toContain('Default (Alpha)');
+      await user.keyboard('{ArrowUp}');
+      expect(highlighted()?.textContent).toContain('Beta');
     });
 
-    it('leaves focus in place when type-ahead matches only the heading', async () => {
+    it('filters rows by the search text, always keeping the Default row', async () => {
       const user = await openMenu(modelControl('beta'));
-      // First key after open, so it cannot buffer onto a previous press: "m"
-      // matches the heading ("Model") and no choice row, and the heading
-      // never takes focus.
-      await user.keyboard('m');
-      expect(focused()).toBe(screen.getByRole('menuitem', { name: 'Beta' }));
+      await user.keyboard('bet');
+      // getByText throws if not found, so a successful call is itself the
+      // presence assertion.
+      within(results()).getByText('Beta');
+      within(results()).getByText('Default (Alpha)');
+      expect(within(results()).queryByText('Alpha')).toBeNull();
     });
 
-    it('falls back to the first choice row when the selection is stale', async () => {
-      // A selection id the persona no longer advertises leaves no row
-      // selected; initial focus then skips the heading to the first row.
-      await openMenu(modelControl('stale'));
-      expect(focused()).toBe(
-        screen.getByRole('menuitem', { name: 'Default (Alpha)' })
-      );
+    it('resets the highlight to the first (filtered) row as the search text changes', async () => {
+      const user = await openMenu(modelControl('beta'));
+      await user.keyboard('bet');
+      // Only "Default (Alpha)" and "Beta" match; highlight resets to the
+      // first row rather than staying on an index that may no longer exist.
+      expect(highlighted()?.textContent).toContain('Default (Alpha)');
     });
 
-    it('activates the focused row with Enter', async () => {
+    it('activates the highlighted row with Enter', async () => {
       const onSelect = jest.fn();
       const user = await openMenu(modelControl(null), onSelect);
       await user.keyboard('{ArrowDown}{ArrowDown}{Enter}');
       expect(onSelect).toHaveBeenCalledWith('beta');
     });
+
+    it('closes on Escape without selecting anything', async () => {
+      const onSelect = jest.fn();
+      const user = await openMenu(modelControl('beta'), onSelect);
+      await user.keyboard('{Escape}');
+      expect(screen.queryByPlaceholderText('Search model')).toBeNull();
+      expect(onSelect).not.toHaveBeenCalled();
+    });
   });
 
   describe('overflow menu', () => {

package/src/__tests__/persona-controls.spec.ts

@@ -8,6 +8,9 @@ import { PersonaOption } from '../awareness';
 
 import {
   buildControls,
+  filterChoices,
+  reconcilePersonas,
+  reconcilePersonaState,
   reconcileSelection,
   showLoadingPlaceholder
 } from '../persona-controls';
@@ -112,6 +115,40 @@ describe('buildControls', () => {
   });
 });
 
+describe('reconcilePersonas', () => {
+  it('accepts a fresh non-empty list', () => {
+    const previous = [personaOption('a')];
+    const next = [personaOption('a'), personaOption('b')];
+    expect(reconcilePersonas(previous, next)).toBe(next);
+  });
+
+  it('keeps the previous list on a transient empty read', () => {
+    const previous = [personaOption('a'), personaOption('b')];
+    expect(reconcilePersonas(previous, [])).toBe(previous);
+  });
+
+  it('stays empty when nothing has ever loaded', () => {
+    expect(reconcilePersonas([], [])).toEqual([]);
+  });
+});
+
+describe('reconcilePersonaState', () => {
+  it('accepts a fresh non-null read', () => {
+    const previous = personaAwareness({});
+    const next = personaAwareness({});
+    expect(reconcilePersonaState(previous, next)).toBe(next);
+  });
+
+  it('keeps the previous state on a transient null read', () => {
+    const previous = personaAwareness({});
+    expect(reconcilePersonaState(previous, null)).toBe(previous);
+  });
+
+  it('stays null when nothing has ever loaded', () => {
+    expect(reconcilePersonaState(null, null)).toBeNull();
+  });
+});
+
 describe('reconcileSelection', () => {
   it('keeps a valid selection', () => {
     expect(
@@ -177,3 +214,40 @@ describe('showLoadingPlaceholder', () => {
     expect(showLoadingPlaceholder(false, false, false, false)).toBe(false);
   });
 });
+
+describe('filterChoices', () => {
+  const opus = { id: 'opus-48', primary: 'Opus 4.8', description: null };
+  const fable = { id: 'fable-5', primary: 'Fable 5', description: null };
+  const defaultChoice = {
+    id: null,
+    primary: 'Default (Opus 4.8)',
+    description: null
+  };
+  const choices = [defaultChoice, opus, fable];
+
+  it('returns everything for an empty query', () => {
+    expect(filterChoices(choices, '')).toEqual(choices);
+  });
+
+  it('returns everything for a whitespace-only query', () => {
+    expect(filterChoices(choices, '   ')).toEqual(choices);
+  });
+
+  it('matches case-insensitively as a substring', () => {
+    expect(filterChoices(choices, 'fable')).toEqual([defaultChoice, fable]);
+    expect(filterChoices(choices, 'FABLE')).toEqual([defaultChoice, fable]);
+    expect(filterChoices(choices, 'abl')).toEqual([defaultChoice, fable]);
+  });
+
+  it('always keeps the Default row first, even when it would not match', () => {
+    expect(filterChoices(choices, 'fable')).toEqual([defaultChoice, fable]);
+  });
+
+  it('drops non-Default choices with no match', () => {
+    expect(filterChoices(choices, 'nonexistent')).toEqual([defaultChoice]);
+  });
+
+  it('handles a Default-only list (no options advertised)', () => {
+    expect(filterChoices([defaultChoice], 'anything')).toEqual([defaultChoice]);
+  });
+});

package/src/persona-controls.tsx

@@ -13,7 +13,8 @@ import {
   Menu,
   MenuItem,
   Popover,
-  Skeleton
+  Skeleton,
+  TextField
 } from '@mui/material';
 import ArrowDropDownIcon from '@mui/icons-material/ArrowDropDown';
 import CheckIcon from '@mui/icons-material/Check';
@@ -154,6 +155,48 @@ export function buildControls(
   return controls;
 }
 
+/**
+ * Decide which persona list the toolbar should display: a freshly read empty
+ * list is treated as a transient blip (e.g. a Yjs awareness sync hiccup
+ * during a persona reload) rather than "no personas", so the toolbar keeps
+ * showing the previous list instead of unmounting - `PersonaControls` hides
+ * itself entirely when `personas.length === 0`, so accepting every empty
+ * read verbatim flashes the whole toolbar (persona name, model picker,
+ * everything) to nothing and back on each blip. A genuinely personas-less
+ * chat never reads a non-empty list in the first place, so this doesn't mask
+ * that case - it only guards against reverting an already-populated list.
+ */
+export function reconcilePersonas(
+  previous: PersonaOption[],
+  next: PersonaOption[]
+): PersonaOption[] {
+  return next.length ? next : previous;
+}
+
+/**
+ * Decide which selected-persona state the toolbar should track: a fresh
+ * null read is treated as a transient blip (the same class of awareness
+ * sync hiccup `reconcilePersonas` guards against, e.g. during a persona
+ * reload) rather than "nothing selected", so the toolbar keeps the last
+ * known state instead of dropping it. This one is not just cosmetic:
+ * `buildControls` returns `[]` for a null persona state, so `controls`
+ * reads empty and `PersonaControls` conditionally unmounts `ControlsRow`
+ * entirely - destroying any open `ControlMenu`'s own state (its search
+ * query, its open popover) mid-interaction, not merely blanking a label.
+ *
+ * Only for the *recurring* awareness-driven read, not the initial one: the
+ * initial read (on mount, or when `selectedId` itself changes to a
+ * different persona) must apply unconditionally, including a genuine null
+ * result, or switching personas could show the previous persona's stale
+ * state under the new selection.
+ */
+export function reconcilePersonaState(
+  previous: PersonaAwareness | null,
+  next: PersonaAwareness | null
+): PersonaAwareness | null {
+  return next ?? previous;
+}
+
 /**
  * Decide how to reconcile the current selection with a freshly read persona
  * list: the new selection to apply, or `undefined` to keep the current one.
@@ -280,10 +323,17 @@ function ChoiceMenuItem(props: {
   description: string | null;
   selected: boolean;
   onSelect: () => void;
+  /** Extra class name, used by ControlMenu to show keyboard focus. */
+  className?: string;
 }): JSX.Element {
   // MenuList clones the row it picks for initial focus with extra props
   // (tabIndex, autoFocus); forward them to the MenuItem, or no row is ever
   // focused and the menu's arrow-key and type-ahead handling never engages.
+  // Shared by OverflowControlsMenu (still a real Menu/MenuList, still
+  // depends on this) and ControlMenu (no longer rendered inside a
+  // MenuList - see the comment there - so this spread is a no-op for it,
+  // and it leaves `role` at MenuItem's own default rather than overriding
+  // it, to avoid disturbing OverflowControlsMenu's ARIA contract).
   const {
     primary,
     description: rawDescription,
@@ -318,6 +368,33 @@ function ChoiceMenuItem(props: {
   );
 }
 
+/** One selectable row in a control's dropdown: an option, or the leading
+ * "Default" row (`id: null`). */
+type Choice = {
+  id: string | null;
+  primary: string;
+  description: string | null;
+};
+
+/**
+ * Filter a control's choices by a search query: a case-insensitive substring
+ * match against each choice's name. An empty (or whitespace-only) query
+ * matches everything, so a freshly opened menu shows the full list. The
+ * leading "Default" choice (`id: null`) is excluded from filtering entirely -
+ * always kept, and always first - since it's a fixed, load-bearing option
+ * (what "no explicit selection" resolves to), not just another item to
+ * search among.
+ */
+export function filterChoices(choices: Choice[], query: string): Choice[] {
+  const defaultChoice = choices.filter(c => c.id === null);
+  const rest = choices.filter(c => c.id !== null);
+  const q = query.trim().toLowerCase();
+  const filteredRest = q
+    ? rest.filter(c => c.primary.toLowerCase().includes(q))
+    : rest;
+  return [...defaultChoice, ...filteredRest];
+}
+
 /**
  * The "Default" row shown at the top of every control. Selecting it sets the
  * user's value to null, i.e. "use the persona's current value". Its label shows
@@ -354,9 +431,17 @@ function ControlMenuSubheader(props: {
 ControlMenuSubheader.muiSkipListHighlight = true;
 
 /**
- * A dropdown for a control, titled with the control's label. The first choice
- * row is "Default" (selection = null); the rest are the persona's advertised
- * options (selection = that option's id). Exported for tests.
+ * A searchable dropdown for a control, titled with the control's label. The
+ * first choice row is always "Default" (selection = null, never filtered
+ * out); the rest are the persona's advertised options (selection = that
+ * option's id), filtered by the search box as the user types. Exported for
+ * tests.
+ *
+ * Built on `Popover` rather than `Menu`/`MenuList`: `MenuList` owns its own
+ * keyboard handling (arrow keys, type-ahead-by-letter) which would fight a
+ * text input for keystrokes, so with a search box in the picture this
+ * component manages its own keyboard navigation (`focusedIndex`) instead of
+ * relying on `MenuList`'s.
  */
 export function ControlMenu(props: {
   control: Control;
@@ -364,10 +449,86 @@ export function ControlMenu(props: {
 }): JSX.Element {
   const { control, onSelect } = props;
   const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+  const [query, setQuery] = useState('');
+  // Index into the *filtered* choice list (Default row included at 0), for
+  // arrow-key navigation. Reset whenever the query changes, since the
+  // previously-focused row may no longer be in the filtered list.
+  const [focusedIndex, setFocusedIndex] = useState(0);
   // The heading names the menu for assistive tech: the subheader itself is a
   // roleless, never-focused list row, so without this wiring the popup has no
   // accessible name at all.
   const headingId = useId();
+
+  const choices: Choice[] = [
+    { id: null, primary: defaultChoiceLabel(control), description: null },
+    ...control.options.map(o => ({
+      id: o.id,
+      primary: o.name,
+      description: o.description
+    }))
+  ];
+  const filtered = filterChoices(choices, query);
+
+  const close = (): void => {
+    setAnchor(null);
+    setQuery('');
+    setFocusedIndex(0);
+  };
+
+  const select = (id: string | null): void => {
+    close();
+    onSelect(id);
+  };
+
+  const handleQueryChange = (
+    event: React.ChangeEvent<HTMLInputElement>
+  ): void => {
+    setQuery(event.target.value);
+    setFocusedIndex(0);
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent): void => {
+    if (!filtered.length) {
+      if (event.key === 'Escape') {
+        close();
+      }
+      return;
+    }
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        setFocusedIndex(i => (i + 1) % filtered.length);
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        setFocusedIndex(i => (i - 1 + filtered.length) % filtered.length);
+        break;
+      case 'Enter': {
+        event.preventDefault();
+        const choice = filtered[focusedIndex];
+        if (choice) {
+          select(choice.id);
+        }
+        break;
+      }
+      case 'Escape':
+        event.preventDefault();
+        close();
+        break;
+    }
+  };
+
+  // Open focused on the currently selected row (falling back to Default,
+  // index 0, when the selection is stale/absent) - computed fresh on each
+  // open rather than via a lazy useState initializer, since this component
+  // instance persists across opens/closes (only `anchor` toggles), so a
+  // one-time initializer would never re-run for a later open.
+  const openMenu = (event: React.MouseEvent<HTMLElement>): void => {
+    setAnchor(event.currentTarget);
+    const idx = choices.findIndex(c => c.id === control.selection);
+    setFocusedIndex(idx >= 0 ? idx : 0);
+  };
+
   return (
     <>
       <Button
@@ -376,43 +537,63 @@ export function ControlMenu(props: {
         variant="text"
         disableRipple
         endIcon={<ArrowDropDownIcon className={`${SELECTOR_CLASS}-arrow`} />}
-        onClick={event => setAnchor(event.currentTarget)}
+        onClick={openMenu}
         title={control.label}
       >
         <span className={`${SELECTOR_CLASS}-control-value`}>
           {currentControlLabel(control)}
         </span>
       </Button>
-      <Menu
+      <Popover
         anchorEl={anchor}
         open={!!anchor}
-        onClose={() => setAnchor(null)}
-        MenuListProps={{ 'aria-labelledby': headingId }}
+        onClose={close}
         {...menuAnchorProps}
       >
         <ControlMenuSubheader id={headingId} label={control.label} />
-        <ChoiceMenuItem
-          primary={defaultChoiceLabel(control)}
-          description={null}
-          selected={control.selection === null}
-          onSelect={() => {
-            setAnchor(null);
-            onSelect(null);
-          }}
-        />
-        {control.options.map(option => (
-          <ChoiceMenuItem
-            key={option.id}
-            primary={option.name}
-            description={option.description}
-            selected={control.selection === option.id}
-            onSelect={() => {
-              setAnchor(null);
-              onSelect(option.id);
-            }}
+        {control.options.length > 0 ? (
+          <TextField
+            autoFocus
+            fullWidth
+            size="small"
+            variant="standard"
+            placeholder={`Search ${control.label.toLowerCase()}`}
+            value={query}
+            onChange={handleQueryChange}
+            onKeyDown={handleKeyDown}
+            className={`${MENU_CLASS}-search-input`}
           />
-        ))}
-      </Menu>
+        ) : null}
+        {/* role="group", not "listbox": MenuItem's own default role
+            (menuitem) would mismatch a listbox's expected "option"
+            children, and changing MenuItem's role risks disturbing
+            OverflowControlsMenu, which shares ChoiceMenuItem and still
+            relies on the real Menu/MenuList's own ARIA menu semantics. */}
+        <div
+          role="group"
+          aria-labelledby={headingId}
+          className={`${MENU_CLASS}-search-list`}
+        >
+          {filtered.length ? (
+            filtered.map((choice, index) => (
+              <ChoiceMenuItem
+                key={choice.id ?? '__default__'}
+                primary={choice.primary}
+                description={choice.description}
+                selected={control.selection === choice.id}
+                onSelect={() => select(choice.id)}
+                className={
+                  index === focusedIndex
+                    ? `${MENU_CLASS}-kbd-focused`
+                    : undefined
+                }
+              />
+            ))
+          ) : (
+            <MenuItem disabled>No matches</MenuItem>
+          )}
+        </div>
+      </Popover>
     </>
   );
 }
@@ -961,7 +1142,7 @@ export function PersonaControls(
       return;
     }
     const list = manager.personas;
-    setPersonas(list);
+    setPersonas(prev => reconcilePersonas(prev, list));
     setSelectedId(current => {
       const next = reconcileSelection(list, current, userPicked.current);
       return next === undefined ? current : next;
@@ -993,14 +1174,22 @@ export function PersonaControls(
 
   // Track the selected persona's view in state, re-reading on every awareness
   // change (a persona updating usage, model, or commands) so the toolbar
-  // reflects the latest published state.
+  // reflects the latest published state. The first read (right below)
+  // applies unconditionally, since it runs whenever `selectedId` itself
+  // changes and must reflect the newly selected persona, even a genuinely
+  // absent one; every later read goes through reconcilePersonaState so a
+  // transient blip doesn't blank this out - see its comment for why that
+  // matters more than it looks like it should.
   useEffect(() => {
     if (!awareness || !manager || !selectedId) {
       setPersonaState(null);
       return;
     }
-    const read = () => setPersonaState(readSelectedPersona());
-    read();
+    setPersonaState(readSelectedPersona());
+    const read = () =>
+      setPersonaState(prev =>
+        reconcilePersonaState(prev, readSelectedPersona())
+      );
     awareness.on('change', read);
     return () => {
       awareness.off('change', read);

package/style/base.css

@@ -319,6 +319,39 @@
   border-top: none;
 }
 
+/* Search box in a control's dropdown (ControlMenu - the searchable model/
+   settings picker). Sits between the subheader and the choice list; the
+   choice list scrolls independently (see below) so the box stays visible
+   while scrolling a long, filtered result set. */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-search-input {
+  padding: 4px 12px 8px;
+}
+
+/* stylelint-disable-next-line selector-class-pattern -- theming MUI's input classes */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-search-input .MuiInput-root {
+  font-family: var(--jp-ui-font-family);
+  font-size: var(--jp-ui-font-size1);
+}
+
+/* The choice list scrolls on its own, independent of the paper's own
+   max-height bound (see .jp-jai-controlMenu-paper above) - without this the
+   search box could scroll out of view along with the results, the opposite
+   of the point of keeping it pinned at the top. */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-search-list {
+  overflow-y: auto;
+  max-height: calc(60vh - 80px);
+}
+
+/* Keyboard-focused row when navigating the search results with arrow keys.
+   ControlMenu no longer renders choices inside a MenuList - see the comment
+   on ControlMenu in persona-controls.tsx - so this is a plain state-driven
+   highlight rather than real DOM/MUI focus styling, matching the existing
+   hover/selected treatment for visual consistency. */
+/* stylelint-disable-next-line selector-class-pattern -- theming MUI's menu item classes */
+.jp-jai-controlMenu-paper .jp-jai-controlMenu-kbd-focused.MuiMenuItem-root {
+  background-color: var(--jp-layout-color2);
+}
+
 /* Usage chip: a small ring gauge and percent of the active persona's context
    fill, next to the persona it describes. Borderless, matching the overflow
    button. The ring fill and percent take the chip's color, so the warn/error