feat: badge-linked profile avatars (TASK-22142)

e2e/shots/fixtures.spec.ts

@@ -11,7 +11,7 @@
 import { expect, test, type Page } from '@playwright/test'
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
-import { FIXTURE_PARAM, FIXTURE_STORAGE_KEY } from '../../src/dev/fixtures/active'
+import { FIXTURE_PARAM, FIXTURE_STORAGE_KEY, fixtureHref } from '../../src/dev/fixtures/active'
 import { FIXTURES } from '../../src/dev/fixtures/registry'
 
 const OUT_DIR = process.env.SHOTS_OUT ?? 'e2e/__shots__/current'
@@ -129,10 +129,7 @@ for (const [name, fixture] of Object.entries(FIXTURES)) {
         await page.clock.setFixedTime(FROZEN_NOW)
         await page.addInitScript(seenOnceModals)
 
-        // a fixture route may already pin url state (?method=bank) — join accordingly
-        await page.goto(`${fixture.route}${fixture.route.includes('?') ? '&' : '?'}${FIXTURE_PARAM}=${name}`, {
-            waitUntil: 'domcontentloaded',
-        })
+        await page.goto(fixtureHref(fixture.route, name), { waitUntil: 'domcontentloaded' })
         await settle(page)
 
         // A build without NEXT_PUBLIC_VERCEL_ENV=preview ignores the param and

src/app/dev/fixtures/FixtureList.tsx

@@ -3,7 +3,7 @@
 import Card from '@/components/Global/Card'
 import DevNoteCard from '@/app/(mobile-ui)/dev/_components/DevNoteCard'
 import DevPageShell from '@/app/(mobile-ui)/dev/_components/DevPageShell'
-import { clearFixture, FIXTURE_PARAM } from '@/dev/fixtures/active'
+import { clearFixture, FIXTURE_PARAM, fixtureHref } from '@/dev/fixtures/active'
 import { FIXTURES } from '@/dev/fixtures/registry'
 
 export default function FixtureList() {
@@ -20,7 +20,7 @@ export default function FixtureList() {
                     const fixture = FIXTURES[name]
                     // Plain <a>: a soft navigation would keep the previous fixture's
                     // React Query cache, so the screen would show stale state.
-                    const href = `${fixture.route}?${FIXTURE_PARAM}=${name}`
+                    const href = fixtureHref(fixture.route, name)
                     return (
                         <a key={name} href={href}>
                             <Card className="cursor-pointer p-4">

src/components/Avatar/AvatarPicker.tsx

@@ -0,0 +1,170 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { useTranslations } from 'next-intl'
+import { updateUserById } from '@/app/actions/users'
+import { Button } from '@/components/0_Bruddle/Button'
+import { useToast } from '@/components/0_Bruddle/Toast'
+import { Drawer, DrawerContent, DrawerDescription, DrawerHeader, DrawerTitle } from '@/components/Global/Drawer'
+import { useAuth } from '@/context/authContext'
+import { twMerge } from '@/utils/tw'
+import { badgeAvatarKeys, offerBasics } from './avatar.utils'
+import { roveAvatarTiles } from './avatarPicker.utils'
+import { UserAvatar } from './UserAvatar'
+
+interface AvatarPickerProps {
+    open: boolean
+    onOpenChange: (open: boolean) => void
+}
+
+/**
+ * The profile avatar picker (TASK-22142): what the user's badges unlocked,
+ * then one row of the basics everyone has. A tap saves at once; the dice
+ * rerolls the offered row and never the pick; "use my initial" clears it.
+ * The API validates the pick against the same pool, so a locked key never
+ * lands even if the manifest and the catalog drift.
+ */
+export function AvatarPicker({ open, onOpenChange }: AvatarPickerProps) {
+    const t = useTranslations('avatar')
+    const tCommon = useTranslations('common')
+    const { user, fetchUser } = useAuth()
+    const { toast } = useToast()
+
+    const userId = user?.user.userId
+    const username = user?.user.username ?? undefined
+    const saved = user?.user.avatarKey ?? null
+    const badges = user?.user.badges ?? []
+    const held = badges.map((badge) => badge.code)
+    const badgeName = Object.fromEntries(badges.map((badge) => [badge.code, badge.name]))
+    const unlocked = badgeAvatarKeys(held)
+
+    // The tile moves on tap; the slot behind the drawer moves after fetchUser
+    // lands. `pending` overrides `saved` while a burst drains. Saves are
+    // SERIALIZED: one POST at a time, always the latest tap next, so the
+    // server can never commit an older key last. One refetch per burst, in
+    // a finally, so a thrown save cannot wedge the picker.
+    const [pending, setPending] = useState<string | null | undefined>(undefined)
+    const wanted = useRef<string | null | undefined>(undefined)
+    const draining = useRef(false)
+    const pick = pending === undefined ? saved : pending
+
+    const drain = async () => {
+        draining.current = true
+        try {
+            // a tap that lands while the refetch is in flight queues on
+            // `wanted`; drain again rather than drop it with the finally
+            do {
+                while (wanted.current !== undefined) {
+                    const key = wanted.current
+                    wanted.current = undefined
+                    try {
+                        const { error } = await updateUserById({ userId, avatarKey: key })
+                        if (error) toast({ type: 'error', message: t('saveFailed') })
+                    } catch {
+                        toast({ type: 'error', message: t('saveFailed') })
+                    }
+                }
+                await fetchUser()
+            } while (wanted.current !== undefined)
+        } finally {
+            draining.current = false
+            setPending(undefined)
+        }
+    }
+
+    const save = (key: string | null) => {
+        if (!userId) return
+        setPending(key)
+        wanted.current = key
+        if (!draining.current) void drain()
+    }
+
+    // the offered row of five basics: dealt on open, redealt by the dice
+    const [offer, setOffer] = useState<string[]>([])
+    useEffect(() => {
+        if (open) setOffer(offerBasics(saved))
+        // deal once per open; the pick joins the row by being picked from it
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [open])
+    const rollDice = () => setOffer(offerBasics(pick))
+
+    // human labels: "Bug Whisperer · beetle" for a badge avatar, the slug for a basic
+    const label = (key: string) => {
+        const [kind, code, slug] = key.split('.')
+        return kind === 'badge' ? `${badgeName[code] ?? code} · ${slug}` : code
+    }
+
+    const tiles = (keys: string[], groupLabel: string) => {
+        const focusIndex = Math.max(0, keys.indexOf(pick ?? ''))
+        return (
+            <div
+                role="radiogroup"
+                aria-label={groupLabel}
+                className="grid grid-cols-5 gap-2"
+                onKeyDown={roveAvatarTiles}
+            >
+                {keys.map((key, index) => {
+                    const checked = key === pick
+                    return (
+                        <button
+                            key={key}
+                            type="button"
+                            role="radio"
+                            aria-checked={checked}
+                            aria-label={label(key)}
+                            tabIndex={index === focusIndex ? 0 : -1}
+                            onClick={() => save(key)}
+                            className={twMerge(
+                                'flex min-h-11 items-center justify-center rounded-sm border border-border-disabled bg-background-default p-1 focus-visible:outline-[3px] focus-visible:outline-action-focus',
+                                checked && 'border-2 border-border-default shadow-4'
+                            )}
+                        >
+                            <UserAvatar name={username} avatarKey={key} size="small" />
+                        </button>
+                    )
+                })}
+            </div>
+        )
+    }
+
+    return (
+        <Drawer open={open} onOpenChange={onOpenChange}>
+            <DrawerContent className="p-4">
+                <DrawerHeader className="p-0 pb-4 text-left">
+                    <DrawerTitle className="text-heading-s text-foreground-primary">{t('title')}</DrawerTitle>
+                    <DrawerDescription>{t('description')}</DrawerDescription>
+                </DrawerHeader>
+                <div className="flex flex-col gap-6">
+                    <section className="flex flex-col gap-2">
+                        <div className="flex items-baseline justify-between text-label-m text-foreground-secondary uppercase">
+                            <span>{t('fromBadges')}</span>
+                            {unlocked.length > 0 && (
+                                <span className="normal-case">{t('unlocked', { count: unlocked.length })}</span>
+                            )}
+                        </div>
+                        {unlocked.length > 0 ? (
+                            tiles(unlocked, t('fromBadges'))
+                        ) : (
+                            <p className="text-body-s text-foreground-secondary">{t('noBadgeAvatars')}</p>
+                        )}
+                    </section>
+                    <section className="flex flex-col gap-2">
+                        <div className="text-label-m text-foreground-secondary uppercase">{t('basics')}</div>
+                        {tiles(offer, t('basics'))}
+                    </section>
+                    <div className="flex flex-col gap-2">
+                        <Button variant="stroke" className="w-full" onClick={rollDice}>
+                            {t('rollDice')}
+                        </Button>
+                        <Button variant="purple" className="w-full" onClick={() => onOpenChange(false)}>
+                            {tCommon('done')}
+                        </Button>
+                        <Button variant="transparent" className="w-full" onClick={() => save(null)}>
+                            {t('useInitial')}
+                        </Button>
+                    </div>
+                </div>
+            </DrawerContent>
+        </Drawer>
+    )
+}

src/components/Avatar/UserAvatar.tsx

@@ -0,0 +1,61 @@
+'use client'
+
+import Image from 'next/image'
+import { useTranslations } from 'next-intl'
+import AvatarWithBadge from '@/components/Profile/AvatarWithBadge'
+import { AVATAR_SIZE_CLASSES, type AvatarSize } from '@/components/Profile/avatar-size.consts'
+import { twMerge } from '@/utils/tw'
+import { avatarSrc, letterAvatarSrc } from './avatar.utils'
+
+interface UserAvatarProps {
+    /** Display name: the source of the day-0 letter sticker and of the label. */
+    name?: string
+    avatarKey?: string | null
+    size?: AvatarSize
+    className?: string
+}
+
+/**
+ * The user's own avatar (TASK-22142): the picked sticker, plain on the page —
+ * a sticker carries its own colours and edge, so no circle and no palette ring
+ * (art direction, 2026-09-03). Without a pick, the first letter of the name as
+ * a sticker. A name that does not start with a-z falls through to the
+ * first-letter avatar, which stays the one place that renders a bare initial.
+ */
+export function UserAvatar({ name, avatarKey, size = 'extra-small', className }: UserAvatarProps) {
+    const t = useTranslations('common')
+    const picked = avatarKey ? avatarSrc(avatarKey) : null
+    const letter = picked ? null : letterAvatarSrc(name)
+    const art = picked ?? letter
+
+    if (!art) {
+        return name ? (
+            <AvatarWithBadge size={size} name={name} firstLetterOnly className={className} />
+        ) : (
+            <AvatarWithBadge
+                size={size}
+                icon="user"
+                className={twMerge(
+                    'border border-avatar-yellow-border bg-avatar-yellow text-avatar-yellow-foreground',
+                    className
+                )}
+                iconFillColor="var(--color-avatar-yellow-foreground)"
+            />
+        )
+    }
+
+    return (
+        <span
+            {...(name
+                ? { role: 'img', 'aria-label': t('userAvatarAlt', { username: name }) }
+                : { 'aria-hidden': true })}
+            className={twMerge(
+                'inline-flex shrink-0 items-center justify-center',
+                AVATAR_SIZE_CLASSES[size],
+                className
+            )}
+        >
+            <Image src={art} alt="" width={176} height={176} unoptimized className="size-full object-contain" />
+        </span>
+    )
+}