graduate avatar collection canvas (#153)

**Category:** improvement
**User Impact:** Everyone now chooses agent avatars from the
full-screen, pannable collection canvas.
**Problem:** The collection canvas remained behind an experiment,
leaving production users on a separate inline picker and requiring two
avatar-selection paths to stay maintained.
**Solution:** Make the collection canvas the single avatar-picker
experience across the agent builder and profile, then remove the
experiment registration and legacy picker implementation. The canvas
shows a neutral Berd loading state while its catalog loads. On agent
profiles, it waits for persistence before closing and preserves failed
selections for retry; in the builder, selections join the existing
working buffer without prematurely saving unrelated edits.

<details>
<summary>File changes</summary>

**scripts/design-system-audit.mjs**
Removes a stale baseline exception after the retired inline profile
editor styling was deleted.


**src/features/agents/capabilities/__tests__/AgentBuilderCapability.test.tsx**
Stops configuring the graduated experiment in capability setup.

**src/features/agents/lib/getCachedAvatarMedia.ts**
Moves cached avatar media lookup into a neutral shared utility used by
the permanent canvas.

**src/features/agents/ui/AgentAvatarSection.tsx**
Removes the retired inline avatar customization surface.

**src/features/agents/ui/AgentBuilderRail.tsx**
Makes the collection canvas the sole avatar library path in compact and
full-page builders.

**src/features/agents/ui/AgentDetailPage.tsx**
Opens the collection canvas directly from profile avatar customization
and removes the legacy inline branch.

**src/features/agents/ui/AvatarCollectionOverlay.tsx**
Reads cached media through the neutral avatar utility, shows a neutral
loading state, and supports async owners that preserve failed selections
for retry.

**src/features/agents/ui/AvatarLibraryPicker.tsx**
Removes the retired inline avatar library implementation.

**src/features/agents/ui/__tests__/AgentBuilderRail.test.tsx**
Updates builder expectations for the always-on canvas, removes
experiment-specific cases, and pins that avatar selection joins the
existing working buffer without prematurely saving unrelated edits.

**src/features/agents/ui/__tests__/AgentsView.entry.test.tsx**
Covers permanent canvas opening from agent profiles, persistence,
closure, telemetry, and failed-write behavior.

**src/features/agents/ui/__tests__/AvatarCollectionOverlay.test.tsx**
Covers loading feedback and retrying a failed selection without losing
canvas context.

**src/features/agents/ui/__tests__/AvatarLibraryPicker.test.tsx**
Removes tests for the retired inline picker.

**src/features/experiments/__tests__/ExperimentsSettings.test.tsx**
Updates the supported experiment registry expectation.

**src/features/experiments/experimentDefinitions.ts**
Removes the avatar collection canvas experiment definition and
identifier.

**src/shared/i18n/__tests__/agentAvatarAffordanceLocaleParity.test.ts**
Narrows locale parity coverage to the remaining profile avatar
affordance copy.

**src/shared/i18n/locales/en/agents.json**
Removes English copy used only by the retired inline picker.

**src/shared/i18n/locales/en/settings.json**
Removes the graduated experiment’s English settings copy.

**src/shared/i18n/locales/es/agents.json**
Removes Spanish copy used only by the retired inline picker.

**src/shared/i18n/locales/es/settings.json**
Removes the graduated experiment’s Spanish settings copy.

</details>

<img width="2152" height="1522" alt="Screenshot 2026-08-20 at 6 07
44 PM"
src="https://github.com/user-attachments/assets/563f3706-cef1-404c-84d3-cca0e86985ea"
/>

---------

Signed-off-by: Matt Toohey <contact@matttoohey.com>
Co-authored-by: Matt Toohey <contact@matttoohey.com>

Author: morgmart

scripts/design-system-audit.mjs

@@ -113,7 +113,6 @@ const buttonStylingPattern =
   /(?:^|[\s"'`(])(?:bg-(?!transparent\b)[a-z[]|text-(?:foreground|muted|primary|secondary|destructive|accent|current|white|black|surface|app|sidebar)|border-(?:input|border|destructive|primary|accent|current|surface)|hover:(?!opacity-100\b)|active:(?:bg|text|border|opacity)|focus-visible:(?:bg|text|border)|data-\[state=open\]:(?:bg|text)|aria-expanded:(?:bg|text)|shadow-(?!none)|opacity-(?!0\b|100\b)\d|backdrop-|ring-(?!offset|ring\b|\d))/;
 
 const buttonStylingBaseline = new Set([
-  "src/features/agents/ui/AgentDetailPage.tsx",
   "src/features/chat/ui/ChatInputToolbar.tsx",
   "src/features/chat/ui/MessageBubbleActions.tsx",
   "src/features/chat/ui/PersonaPicker.tsx",

src/features/agents/capabilities/__tests__/AgentBuilderCapability.test.tsx

@@ -61,8 +61,6 @@ import {
   useChatSessionStore,
   type ChatSession,
 } from "@/features/chat/stores/chatSessionStore";
-import { setExperimentEnabled } from "@/features/experiments/experimentPreferences";
-import { AVATAR_COLLECTION_PAGE_EXPERIMENT_ID } from "@/features/experiments/experimentDefinitions";
 import type { AgentSourceEntry } from "@/shared/api/agents";
 
 const existingAgentSource: AgentSourceEntry = {
@@ -125,7 +123,6 @@ describe("AgentBuilderCapability keep-save telemetry", () => {
     );
     apiMocks.listPersonas.mockResolvedValue([]);
     resetAgentBuilderSourceLifecycleForTests();
-    setExperimentEnabled(AVATAR_COLLECTION_PAGE_EXPERIMENT_ID, false);
     useAgentStore.setState({
       personas: [],
       personasLoading: false,

src/features/agents/lib/getCachedAvatarMedia.ts

@@ -0,0 +1,12 @@
+import type { AvatarLibraryState } from "@/features/agents/hooks/useAvatarLibrary";
+
+export function getCachedAvatarMedia(
+  cachedAvatarMediaById: AvatarLibraryState["cachedAvatarMediaById"],
+  catalogVersion: string | undefined,
+  avatarId: string,
+) {
+  const cachedMediaEntry = cachedAvatarMediaById[avatarId];
+  return cachedMediaEntry?.catalogVersion === catalogVersion
+    ? cachedMediaEntry.media
+    : undefined;
+}

src/features/agents/ui/AgentAvatarSection.tsx

@@ -8,13 +8,12 @@ import {
 import { useTranslation } from "react-i18next";
 import {
   IconAlertTriangle,
-  IconArrowLeft,
   IconLayoutSidebarLeftExpand,
   IconPhoto,
   IconSparkles,
   IconX,
 } from "@tabler/icons-react";
-import { avatarRef, isLibraryAvatarRef } from "@/shared/avatars/catalog";
+import { avatarRef } from "@/shared/avatars/catalog";
 import { normalizeAvatarUrl } from "@/shared/lib/avatarUrl";
 import { cn } from "@/shared/lib/cn";
 import type { AgentSourceEntry } from "@/shared/api/agents";
@@ -44,10 +43,7 @@ import {
   PLACEHOLDER_AGENT_BODY,
   promoteDraft,
 } from "@/features/agents/lib/agentBuilderSession";
-import { useExperiment } from "@/features/experiments/experimentPreferences";
-import { AVATAR_COLLECTION_PAGE_EXPERIMENT_ID } from "@/features/experiments/experimentDefinitions";
 import { AvatarCollectionOverlay } from "@/features/agents/ui/AvatarCollectionOverlay";
-import { AvatarLibraryPicker } from "@/features/agents/ui/AvatarLibraryPicker";
 import { ProviderModelFields } from "@/features/agents/ui/PersonaFields/ProviderModelFields";
 import { FORM_FIELD_CLASS } from "@/shared/ui/form-field-tokens";
 import { hasRealAgentDescription } from "@/shared/api/agents";
@@ -139,15 +135,6 @@ export function AgentBuilderRail({
   const [failedMissingDraftRecoveryKey, setFailedMissingDraftRecoveryKey] =
     useState<string | null>(null);
   const avatarLibrary = useAvatarLibrary(true);
-  const avatarCollectionExperiment = useExperiment(
-    AVATAR_COLLECTION_PAGE_EXPERIMENT_ID,
-  );
-  // When on, "library" renders as the full-surface collection canvas overlay
-  // (portal over the whole app) instead of the inline picker. The chat +
-  // builder stay mounted underneath, so composer drafts, resize state, all survive the takeover.
-  const avatarCollectionOverlayEnabled = Boolean(
-    avatarCollectionExperiment?.enabled,
-  );
   const isWaitingForDraftTarget = !targetAgentPath;
   const missingDraftRecoveryKey = `${sessionId}:${targetAgentPath ?? "pending"}`;
   const [previousMissingDraftRecoveryKey, setPreviousMissingDraftRecoveryKey] =
@@ -197,20 +184,6 @@ export function AgentBuilderRail({
     typeof data?.properties?.avatar === "string" ? data.properties.avatar : "";
   const trimmedAvatar = avatarRaw.trim();
   const normalizedAvatar = normalizeAvatarUrl(trimmedAvatar);
-  const [selectedCollectionId, setSelectedCollectionId] = useState<
-    string | null
-  >(null);
-  const selectedCollectionLabel = useMemo(() => {
-    if (!selectedCollectionId) {
-      return null;
-    }
-    return (
-      avatarLibrary.catalog?.collections.find(
-        (collection) => collection.id === selectedCollectionId,
-      )?.label ?? null
-    );
-  }, [avatarLibrary.catalog, selectedCollectionId]);
-
   const provider = (data?.properties?.provider as string | undefined) ?? "";
   const modelProviderId =
     (data?.properties?.modelProviderId as string | undefined) ?? "";
@@ -232,9 +205,10 @@ export function AgentBuilderRail({
 
   const onSelectAvatar = useCallback(
     (selectedAvatarRef: string) => {
+      // Avatar selection joins the same working buffer as every other field.
+      // Existing-agent edits stay local until Save; drafts keep their normal
+      // debounced durability rather than making this field a separate commit.
       writeProperty("avatar", selectedAvatarRef);
-      setSelectedCollectionId(null);
-      setAvatarPanel("closed");
     },
     [writeProperty],
   );
@@ -261,10 +235,6 @@ export function AgentBuilderRail({
       : null;
   const effectiveAvatar =
     normalizedAvatar ?? (defaultAvatarId ? avatarRef(defaultAvatarId) : null);
-  const selectedAvatarRefValue =
-    effectiveAvatar && isLibraryAvatarRef(effectiveAvatar)
-      ? effectiveAvatar
-      : null;
   const selectedAvatarMediaState = useAvatarMediaState(effectiveAvatar);
 
   const onChangeProvider = useCallback(
@@ -524,53 +494,15 @@ export function AgentBuilderRail({
     </aside>
   );
 
-  // Rendered by both the compact rail and the full-page builder. Declared once
-  // so picker changes cannot be applied to one layout and silently missed in
-  // the other.
-  const avatarLibraryPickerNode = (
-    <AvatarLibraryPicker
-      library={avatarLibrary}
-      selectedAvatarRef={selectedAvatarRefValue}
-      onSelectAvatar={onSelectAvatar}
-      onPreviewError={() => {}}
-      selectedCollectionId={selectedCollectionId}
-      onSelectCollection={setSelectedCollectionId}
-    />
-  );
-
   const avatarCollectionOverlayNode =
-    avatarCollectionOverlayEnabled && avatarPanel === "library" ? (
+    avatarPanel === "library" ? (
       <AvatarCollectionOverlay
         library={avatarLibrary}
-        initialCollectionId={selectedCollectionId}
         onSelectAvatar={onSelectAvatar}
-        onClose={() => {
-          setSelectedCollectionId(null);
-          setAvatarPanel("closed");
-        }}
+        onClose={() => setAvatarPanel("closed")}
       />
     ) : null;
 
-  const pickerHeaderNode = (
-    <div className={cn(STICKY_HEADER_CLASS, "flex items-center gap-2")}>
-      <Button
-        type="button"
-        variant="ghost"
-        size="icon-xs"
-        aria-label={t("builderRail.backToForm")}
-        onClick={() => {
-          if (selectedCollectionId) setSelectedCollectionId(null);
-          else setAvatarPanel("closed");
-        }}
-      >
-        <IconArrowLeft className="size-4" aria-hidden="true" />
-      </Button>
-      <h2 className="truncate text-sm font-normal text-foreground">
-        {selectedCollectionLabel ?? t("builderRail.chooseAvatarTitle")}
-      </h2>
-    </div>
-  );
-
   if (error === "parse") {
     return shell(
       headerNode,
@@ -666,17 +598,6 @@ export function AgentBuilderRail({
     );
   }
 
-  // With the collection canvas experiment on, the "library" panel renders as
-  // the full-surface overlay (mounted below) instead of swapping the rail
-  // body, so the form stays visible underneath the frosted glass.
-  if (
-    avatarPanel === "library" &&
-    !fullPage &&
-    !avatarCollectionOverlayEnabled
-  ) {
-    return shell(pickerHeaderNode, avatarLibraryPickerNode);
-  }
-
   const avatarNode = (
     <section>
       <button
@@ -824,35 +745,7 @@ export function AgentBuilderRail({
     </>
   );
 
-  const fullPageLeftColumn =
-    avatarPanel === "library" && !avatarCollectionOverlayEnabled ? (
-      <div className="flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto px-8 py-6 xl:px-12 xl:py-8">
-        <div className="flex items-center gap-2 text-sm text-foreground">
-          <Button
-            type="button"
-            variant="ghost"
-            size="icon-xs"
-            className="-ml-1 shrink-0"
-            aria-label={t("builderRail.backToForm")}
-            onClick={() => {
-              if (selectedCollectionId) {
-                setSelectedCollectionId(null);
-              } else {
-                setAvatarPanel("closed");
-              }
-            }}
-          >
-            <IconArrowLeft className="size-4" aria-hidden="true" />
-          </Button>
-          <h3 className="truncate text-sm font-normal text-foreground">
-            {selectedCollectionLabel ?? t("builderRail.chooseAvatarTitle")}
-          </h3>
-        </div>
-        {avatarLibraryPickerNode}
-      </div>
-    ) : (
-      <div className="flex flex-col">{avatarNode}</div>
-    );
+  const fullPageLeftColumn = <div className="flex flex-col">{avatarNode}</div>;
 
   if (fullPage) {
     return (