@exegia/corpora-ui 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exegia/corpora-ui",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "shadcn-ready React UI library for the corpora manuscript-research apps.",
   "license": "MIT",
   "repository": {

package/src/components/blocks/layout.ts

@@ -1,7 +1,35 @@
-import ShellLayout from "@/components/blocks/shell"
+import ShellLayout, {
+  AnimatedPanel,
+  AnimatedPanelTrigger,
+  useShellPanels,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitMeasuredAtom,
+  shellFitMetricsAtom,
+  shellFitPanelBoundsAtom,
+  shellFitPanelWidthAtom,
+  shellFitRequestedWidthAtom,
+  shellFitStateAtom,
+} from "@/components/blocks/shell"
 
 const Layout = {
-  Main: ShellLayout
+  Main: ShellLayout,
+  Panel: AnimatedPanel,
+  Trigger: AnimatedPanelTrigger,
+}
+
+export {
+  useShellPanels,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitMeasuredAtom,
+  shellFitMetricsAtom,
+  shellFitPanelBoundsAtom,
+  shellFitPanelWidthAtom,
+  shellFitRequestedWidthAtom,
+  shellFitStateAtom,
 }
 
 export default Layout

package/src/components/blocks/profile/profile-card-block.tsx

@@ -103,7 +103,7 @@ export interface ProfileCardBlockProps {
    * its avatar — for an icon-collapsed sidebar rail. The fold animates: the
    * identity lines and chevron slide to zero width, the avatar stays put.
    * Controlled when passed. Left unset, the card follows the `AnimatedPanel`
-   * it sits in (a `SidebarBlock` footer folds with the rail on its own), and
+   * it sits in (a panel footer folds with the rail on its own), and
    * outside a panel starts from `defaultVariant`.
    */
   variant?: ProfileCardVariant

package/src/components/blocks/shell/index.ts

@@ -27,17 +27,4 @@ export * from "./animated-panel-inset"
 export * from "./animated-panel-provider"
 export * from "./animated-panel-trigger"
 
-export * from "./animated-sidebar-header"
-export * from "./animated-sidebar-content"
-export * from "./animated-sidebar-footer"
-export * from "./animated-sidebar-group"
-export * from "./animated-sidebar-group-label"
-export * from "./animated-sidebar-group-content"
-export * from "./animated-sidebar-menu"
-export * from "./animated-sidebar-menu-item"
-export * from "./animated-sidebar-menu-sub"
-export * from "./animated-sidebar-menu-sub-item"
-export * from "./animated-sidebar-menu-sub-button"
-export * from "./animated-sidebar-menu-button"
-
 export { ShellLayout as default }

package/src/components/composed/__tests__/logo.test.tsx

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test"
+import { render, screen } from "@testing-library/react"
+
+import { Logo } from "../logo"
+
+const root = () => document.querySelector<HTMLElement>('[data-slot="logo"]')
+const wordmark = () =>
+  document.querySelector<HTMLElement>('[data-slot="logo-wordmark"]')
+const monogram = () =>
+  document.querySelector<HTMLElement>('[data-slot="logo-monogram"]')
+
+describe("Logo", () => {
+  test("defaults: monogram tile from the name, name as the wordmark", () => {
+    render(<Logo name="Corpora Codex" />)
+    expect(monogram()?.textContent).toBe("CC")
+    expect(wordmark()?.textContent).toBe("Corpora Codex")
+    expect(root()?.tagName).toBe("SPAN")
+    expect(root()?.getAttribute("data-variant")).toBe("full")
+  })
+
+  test("a custom mark wins over src; src renders a decorative image", () => {
+    const { rerender } = render(
+      <Logo name="Corpora" src="https://example.com/mark.png" />
+    )
+    expect(monogram()).toBeNull()
+    expect(document.querySelector("img")?.getAttribute("alt")).toBe("")
+    rerender(
+      <Logo
+        name="Corpora"
+        src="https://example.com/mark.png"
+        mark={<svg data-testid="mark" />}
+      />
+    )
+    expect(document.querySelector("img")).toBeNull()
+    expect(screen.getByTestId("mark")).toBeTruthy()
+  })
+
+  test("href renders a link named for AT regardless of variant", () => {
+    render(<Logo name="Corpora" href="/" variant="mark" />)
+    const link = screen.getByRole("link", { name: "Corpora" })
+    expect(link.getAttribute("href")).toBe("/")
+    expect(link.getAttribute("data-slot")).toBe("logo")
+  })
+
+  test("variant=mark folds the wordmark: hidden from AT, root keeps the name", () => {
+    const { rerender } = render(<Logo name="Corpora" variant="mark" />)
+    expect(wordmark()?.getAttribute("aria-hidden")).toBe("true")
+    expect(root()?.getAttribute("aria-label")).toBe("Corpora")
+    expect(root()?.getAttribute("data-variant")).toBe("mark")
+    // Unfolded, the visible wordmark is the name — no double label.
+    rerender(<Logo name="Corpora" variant="full" />)
+    expect(wordmark()?.getAttribute("aria-hidden")).toBeNull()
+    expect(root()?.getAttribute("aria-label")).toBeNull()
+  })
+
+  test("a custom wordmark replaces the name text", () => {
+    render(<Logo name="Corpora" wordmark={<span>corpora/ui</span>} />)
+    expect(wordmark()?.textContent).toBe("corpora/ui")
+  })
+})

package/src/components/composed/logo.tsx

@@ -0,0 +1,159 @@
+"use client"
+
+import * as React from "react"
+import { motion, useReducedMotion } from "motion/react"
+import type { Variants } from "motion/react"
+
+import { EASE_OUT } from "@/lib/ease.ts"
+import { cn } from "@/lib/utils"
+import { initialsFrom } from "@/components/user-avatar"
+
+/** `full` shows mark + wordmark; `mark` folds the wordmark away — an icon
+ * rail, a favicon-sized corner. */
+export type LogoVariant = "full" | "mark"
+
+export interface LogoProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+  /**
+   * Brand name. Labels the logo for AT (and the link, when `href` renders
+   * one), drives the default wordmark, and the monogram tile when no mark
+   * is given.
+   */
+  name: string
+  /** Custom mark — an inline SVG sized to fill its box. Wins over `src`. */
+  mark?: React.ReactNode
+  /** Image URL for the mark. Decorative — `name` labels the logo. */
+  src?: string
+  /** Wordmark content. Defaults to `name`. */
+  wordmark?: React.ReactNode
+  /** `full` (default) or `mark` — the wordmark folds away, animated. */
+  variant?: LogoVariant
+  /** Renders the logo as a link — the usual "mark goes home" affordance. */
+  href?: string
+}
+
+/** Wordmark fold/unfold — the same envelope the profile card's identity
+ * lines use, so a logo and a profile card folding in the same rail move as
+ * one. Kept local: composed components do not reach into blocks. Expressed
+ * as named variants for consistency with the profile card's fold envelope —
+ * house style for multi-property fold states, not a motion requirement. */
+const WORDMARK_VARIANTS: Variants = {
+  open: {
+    width: "auto",
+    opacity: 1,
+    x: 0,
+    transition: { duration: 0.2, delay: 0.08, ease: EASE_OUT },
+  },
+  folded: {
+    width: 0,
+    opacity: 0,
+    x: -4,
+    transition: { duration: 0.12, ease: EASE_OUT },
+  },
+}
+
+const WORDMARK_VARIANTS_REDUCED: Variants = {
+  open: { width: "auto", opacity: 1, x: 0, transition: { duration: 0.16, ease: EASE_OUT } },
+  folded: { width: 0, opacity: 0, x: 0, transition: { duration: 0.16, ease: EASE_OUT } },
+}
+
+/**
+ * Brand lockup: a mark beside a wordmark. The mark is whatever the brand
+ * has — an SVG (`mark`), an image (`src`), or, given neither, a monogram
+ * tile derived from `name`. `variant="mark"` folds the wordmark away with
+ * the same motion a collapsing rail uses, so the lockup can sit in one and
+ * follow its fold. With `href` the whole lockup is a link named by `name`.
+ *
+ * Sizing rides on the mark: it defaults to `size-8`; restyle via
+ * `[&_[data-slot=logo-mark]]:size-*` or wrap in a text-size context for the
+ * wordmark, which inherits.
+ */
+export function Logo({
+  name,
+  mark,
+  src,
+  wordmark,
+  variant = "full",
+  href,
+  className,
+  ...props
+}: LogoProps): React.ReactElement {
+  const reduce = useReducedMotion()
+  const folded = variant === "mark"
+
+  const markNode = mark ?? (
+    src !== undefined ? (
+      // Decorative: the root's `name` (visible wordmark or aria-label)
+      // already names the brand.
+      <img alt="" className="size-full object-contain" src={src} />
+    ) : (
+      <span
+        aria-hidden="true"
+        className="flex size-full items-center justify-center rounded-lg bg-foreground font-semibold text-background text-[45cqw]"
+        data-slot="logo-monogram"
+      >
+        {initialsFrom(name)}
+      </span>
+    )
+  )
+
+  const content = (
+    <>
+      <span
+        className="size-8 shrink-0 @container [&_svg]:size-full"
+        data-slot="logo-mark"
+      >
+        {markNode}
+      </span>
+      <motion.span
+        animate={folded ? "folded" : "open"}
+        variants={reduce ? WORDMARK_VARIANTS_REDUCED : WORDMARK_VARIANTS}
+        // Folded, the wordmark is gone for AT too — the root's label names
+        // the brand on its own.
+        aria-hidden={folded || undefined}
+        className={cn(
+          "min-w-0 overflow-hidden font-semibold whitespace-nowrap tracking-tight",
+          folded && "pointer-events-none",
+          // 0px wide while folded, but the flex gap before it would still
+          // offset the mark — pull it back by that gap.
+          folded && "-ml-2"
+        )}
+        data-slot="logo-wordmark"
+        initial={false}
+      >
+        {wordmark ?? name}
+      </motion.span>
+    </>
+  )
+
+  const rootClassName = cn(
+    "inline-flex shrink-0 items-center gap-2 text-foreground",
+    className
+  )
+
+  return href !== undefined ? (
+    <a
+      // Always labelled: the folded state hides the wordmark, and a link
+      // must not lose its name mid-animation.
+      aria-label={name}
+      className={rootClassName}
+      data-slot="logo"
+      data-variant={variant}
+      href={href}
+      {...props}
+    >
+      {content}
+    </a>
+  ) : (
+    <span
+      aria-label={folded ? name : undefined}
+      className={rootClassName}
+      data-slot="logo"
+      data-variant={variant}
+      role={folded ? "img" : undefined}
+      {...props}
+    >
+      {content}
+    </span>
+  )
+}

package/src/components/user-avatar/__tests__/user-avatar.test.tsx

@@ -8,13 +8,16 @@ import {
   removeUserAvatarInstance,
   resetUserAvatarAtom,
   setUserAvatarBezelAngleAtom,
+  setUserAvatarImageToneAtom,
   setUserAvatarPresenceAtom,
   toggleUserAvatarPresenceAtom,
   userAvatarBezelAngleAtom,
+  userAvatarImageToneAtom,
   userAvatarIsOnlineAtom,
   userAvatarPresenceAtom,
   userAvatarStateAtom,
 } from "../user-avatar-atom"
+import { bezelAlphasForTone } from "../utils"
 import { useUserAvatarActions, useUserAvatarState } from "../use-user-avatar-state"
 import type { UserAvatarActions, UserAvatarState } from "../type"
 
@@ -179,6 +182,43 @@ describe("UserAvatar · bezel", () => {
   })
 })
 
+describe("UserAvatar · bezel tone", () => {
+  test("alphas lean on the shadow over a pale rim and ease the highlight over a dark one", () => {
+    const dark = bezelAlphasForTone(0)
+    const light = bezelAlphasForTone(1)
+    expect(dark.hi).toBeLessThan(light.hi)
+    expect(dark.lo).toBeGreaterThan(light.lo)
+    // Out-of-range input clamps rather than extrapolating past [0, 1].
+    expect(bezelAlphasForTone(-3)).toEqual(dark)
+    expect(bezelAlphasForTone(7)).toEqual(light)
+  })
+
+  test("without a sampled tone the rim carries no inline alphas — the theme's defaults apply", () => {
+    render(<UserAvatar name="Jenny Hamilton" />)
+    const rim = bezel()
+    expect(rim?.hasAttribute("data-tone")).toBe(false)
+    expect(rim?.getAttribute("style")).not.toContain("--bezel-hi-a")
+    // The defaults live in classes, per theme, so a photo-less disc is lit
+    // for the page it sits on.
+    expect(rim?.className).toContain("[--bezel-hi-a:1]")
+    expect(rim?.className).toContain("dark:[--bezel-hi-a:0.18]")
+  })
+
+  test("the tone atom clamps and clears", () => {
+    const store = createStore()
+    store.set(setUserAvatarImageToneAtom("t"), 1.7)
+    expect(store.get(userAvatarImageToneAtom("t"))).toBe(1)
+    store.set(setUserAvatarImageToneAtom("t"), 0.3)
+    expect(store.get(userAvatarImageToneAtom("t"))).toBe(0.3)
+    store.set(setUserAvatarImageToneAtom("t"), Number.NaN)
+    expect(store.get(userAvatarImageToneAtom("t"))).toBeNull()
+    store.set(setUserAvatarImageToneAtom("t"), 0.5)
+    store.set(resetUserAvatarAtom("t"))
+    expect(store.get(userAvatarImageToneAtom("t"))).toBeNull()
+    removeUserAvatarInstance("t")
+  })
+})
+
 describe("UserAvatar · store", () => {
   test("presence, toggle, isOnline and reset on an isolated store", () => {
     const store = createStore()
@@ -203,6 +243,7 @@ describe("UserAvatar · store", () => {
       presence: null,
       bezelAngle: DEFAULT_BEZEL_ANGLE,
       imageStatus: "idle",
+      imageTone: null,
     })
     removeUserAvatarInstance("a")
   })

package/src/components/user-avatar/component.tsx

@@ -8,6 +8,7 @@ import { Fallback } from "./fallback"
 import { PresenceBadge } from "./presence-badge"
 import type { UserAvatarProps } from "./type"
 import { useUserAvatar } from "./use-user-avatar"
+import { bezelAlphasForTone } from "./utils"
 
 /**
  * Identity avatar: an image when one is given, initials otherwise, with an
@@ -44,8 +45,10 @@ export function UserAvatar({
     presence: presenceProp,
     bezel,
     hasImage,
+    src,
   })
-  const { presence, bezelAngle, imageStatus, setImageStatus, ref } = avatar
+  const { presence, bezelAngle, imageStatus, imageTone, setImageStatus, ref } =
+    avatar
 
   const loading =
     loadingProp ??
@@ -54,6 +57,10 @@ export function UserAvatar({
   // still-loading `src` shows initials/skeleton and should be treated as
   // the flat disc it is.
   const showsImage = hasImage && loadingProp !== true && imageStatus === "loaded"
+  // With a photo on screen and its rim sampled, the bezel's alphas follow the
+  // photo rather than the theme: the ring sits on the image, not the page.
+  const bezelAlphas =
+    showsImage && imageTone !== null ? bezelAlphasForTone(imageTone) : null
 
   return (
     // The frame is what the badge and bezel hang off: the Avatar root clips
@@ -66,7 +73,11 @@ export function UserAvatar({
     >
       <Avatar
         className={cn(
-          "size-8 border-1 border-white bg-neutral-800! text-xl dark:border-neutral-900",
+          // `@container` lets the fallback size its initials in cqw — a
+          // fraction of whatever `size-*` the caller put on this element —
+          // instead of a fixed text step. `text-xl` stays as the fallback for
+          // engines without container units.
+          "@container size-8 border-1 border-white bg-neutral-800! text-xl dark:border-neutral-900",
           // The emboss itself: an inset drop toward the light's opposite side
           // is what the ring below is rotated against.
           bezel &&
@@ -122,23 +133,42 @@ export function UserAvatar({
         // A conic highlight → shadow sweep, masked to a thin rim and rotated
         // so the highlight faces the pointer. Rotation (not the gradient
         // angle) is what moves, because `transform` transitions and a
-        // gradient stop does not. Light and dark pick their own alphas via
-        // the two CSS vars; the gradient reads them.
+        // gradient stop does not. The highlight is white and the shadow
+        // black at alphas `--bezel-hi-a` / `--bezel-lo-a`: light and dark
+        // pick their own defaults (a white rim glares on a dark page), and a
+        // sampled photo overrides both inline so the ring is weighted against
+        // the image it actually sits on — scaled by `--bezel-hi-k`, because
+        // the rim borders the page as much as the photo and the same white
+        // that lifts a dark portrait off a light page glares on a dark one.
         <span
           aria-hidden="true"
           className={cn(
             "pointer-events-none absolute inset-0 rounded-full",
-            "[--bezel-hi:--theme(--color-white)] [--bezel-lo:--theme(--color-black/20%)]",
-            "dark:[--bezel-hi:--theme(--color-white/18%)] dark:[--bezel-lo:--theme(--color-black/40%)]",
+            "[--bezel-hi-a:1] [--bezel-lo-a:0.2] dark:[--bezel-hi-a:0.18] dark:[--bezel-lo-a:0.4]",
+            "[--bezel-hi-k:1] dark:[--bezel-hi-k:0.55]",
+            "[--bezel-hi:color-mix(in_oklab,white_calc(var(--bezel-hi-a)*100%),transparent)]",
+            "[--bezel-lo:color-mix(in_oklab,black_calc(var(--bezel-lo-a)*100%),transparent)]",
             // Starts at 6 o'clock: shadow there, highlight peaking at 12 (50%),
             // symmetric either side — so rotate(angle) puts the highlight at
             // exactly `bezelAngle` clockwise from 12.
             "bg-[conic-gradient(from_180deg,var(--bezel-lo)_0%,transparent_24%,transparent_28%,var(--bezel-hi)_50%,transparent_72%,transparent_76%,var(--bezel-lo)_100%)]",
-            "[mask-image:radial-gradient(farthest-side,transparent_calc(95%-4px),#000_calc(100%-2px))]",
+            // Rim width is a share of the radius, not a px count, so the
+            // bezel reads the same at size-8 and size-16: solid over the outer
+            // 8%, feathering in over the 14% inside that.
+            "[mask-image:radial-gradient(farthest-side,transparent_78%,#000_92%)]",
             "mix-blend-normal transition-transform duration-150 ease-smooth-out motion-reduce:transition-none"
           )}
           data-slot="user-avatar-bezel"
-          style={{ transform: `rotate(${bezelAngle * BEZEL_DAMPING}deg)` }}
+          data-tone={imageTone === null ? undefined : imageTone.toFixed(2)}
+          style={{
+            transform: `rotate(${bezelAngle * BEZEL_DAMPING}deg)`,
+            ...(bezelAlphas
+              ? {
+                  "--bezel-hi-a": `calc(${bezelAlphas.hi.toFixed(2)} * var(--bezel-hi-k))`,
+                  "--bezel-lo-a": bezelAlphas.lo.toFixed(2),
+                }
+              : null),
+          }}
         />
       ) : null}
       {presence ? (

package/src/components/user-avatar/fallback.tsx

@@ -12,7 +12,9 @@ export function Fallback({
   loading?: boolean
 }) {
   return (
-    <AvatarFallback>
+    // Initials scale with the disc: 42% of the avatar's width (≈ text-xl on
+    // size-12), resolved against the `@container` on the Avatar root.
+    <AvatarFallback className="text-[42cqw]">
       {loading ? (
         <Skeleton
           className="size-full rounded-full"

package/src/components/user-avatar/type.ts

@@ -41,8 +41,11 @@ export interface UserAvatarProps extends Omit<
   presence?: UserPresence
   /**
    * Embossed rim whose highlight follows the pointer, so the avatar reads as
-   * a lit bezel rather than a flat disc. Light and dark aware; static under
-   * reduced motion. On by default — pass `false` for a flat disc.
+   * a lit bezel rather than a flat disc. Light and dark aware, and with a
+   * photo it samples the image's rim lightness (CORS permitting) to weight
+   * highlight against shadow, so the emboss reads on a dark portrait and a
+   * pale one alike. Static under reduced motion. On by default — pass
+   * `false` for a flat disc.
    */
   bezel?: boolean
   /**
@@ -62,6 +65,11 @@ export interface UserAvatarState {
    * `((a % 360) + 360) % 360` if you need it normalised. */
   bezelAngle: number
   imageStatus: ImageStatus
+  /** Perceived lightness of the loaded image's rim, 0 (black) → 1 (white),
+   * or `null` while unknown — no image yet, or one that could not be sampled
+   * (non-CORS host, no canvas). The bezel's highlight/shadow alphas follow
+   * it so the emboss reads on a dark photo and a pale one alike. */
+  imageTone: number | null
 }
 
 /** Write-only handles onto one avatar. Nothing here re-renders the caller. */

package/src/components/user-avatar/use-user-avatar.ts

@@ -15,10 +15,13 @@ import {
   removeUserAvatarInstance,
   setUserAvatarBezelAngleAtom,
   setUserAvatarImageStatusAtom,
+  setUserAvatarImageToneAtom,
   userAvatarBezelAngleAtom,
   userAvatarImageStatusAtom,
+  userAvatarImageToneAtom,
   userAvatarPresenceAtom,
 } from "./user-avatar-atom"
+import { measureRimTone } from "./utils"
 
 export interface UseUserAvatarOptions {
   avatarId?: UserAvatarInstanceId
@@ -28,6 +31,9 @@ export interface UseUserAvatarOptions {
   bezel: boolean
   /** Only meaningful with an image — no image, no status to track. */
   hasImage: boolean
+  /** The image URL, sampled for its rim lightness once it has loaded so the
+   * bezel can pick alphas that read against it. Omit to skip sampling. */
+  src?: string
 }
 
 export interface UserAvatarBinding {
@@ -35,6 +41,8 @@ export interface UserAvatarBinding {
   presence: UserPresence | null
   bezelAngle: number
   imageStatus: ImageStatus
+  /** Rim lightness of the loaded image, 0–1, or `null` while unknown. */
+  imageTone: number | null
   /** Hand to the image's `onLoadingStatusChange`. Stable. */
   setImageStatus: (status: ImageStatus) => void
   /** Attach to the avatar root — the bezel is lit relative to its centre. */
@@ -56,7 +64,7 @@ const ANGLE_EPSILON = 1.5
  * survives a remount.
  */
 export function useUserAvatar(options: UseUserAvatarOptions): UserAvatarBinding {
-  const { presence: presenceProp, bezel, hasImage } = options
+  const { presence: presenceProp, bezel, hasImage, src } = options
   const generatedId = React.useId()
   const avatarId = options.avatarId ?? generatedId
   const controlsPresence = presenceProp !== undefined
@@ -69,6 +77,7 @@ export function useUserAvatar(options: UseUserAvatarOptions): UserAvatarBinding
   const project = useSetAtom(projectUserAvatarPropsAtom(avatarId))
   const setBezelAngle = useSetAtom(setUserAvatarBezelAngleAtom(avatarId))
   const setImageStatus = useSetAtom(setUserAvatarImageStatusAtom(avatarId))
+  const setImageTone = useSetAtom(setUserAvatarImageToneAtom(avatarId))
 
   // Layout effect: the projection must land before children read the store
   // in the same commit. Primitive deps, so no loop guard is needed here.
@@ -86,6 +95,7 @@ export function useUserAvatar(options: UseUserAvatarOptions): UserAvatarBinding
   const presence = useAtomValue(userAvatarPresenceAtom(avatarId))
   const bezelAngle = useAtomValue(userAvatarBezelAngleAtom(avatarId))
   const imageStatus = useAtomValue(userAvatarImageStatusAtom(avatarId))
+  const imageTone = useAtomValue(userAvatarImageToneAtom(avatarId))
 
   const ref = React.useRef<HTMLElement | null>(null)
   const reduce = useReducedMotion()
@@ -140,5 +150,31 @@ export function useUserAvatar(options: UseUserAvatarOptions): UserAvatarBinding
     if (!hasImage) setImageStatus("idle")
   }, [hasImage, setImageStatus])
 
-  return { avatarId, presence, bezelAngle, imageStatus, setImageStatus, ref }
+  // Once the image is on screen, read how light its rim is so the bezel's
+  // highlight and shadow can be weighted against it. Cleared whenever the
+  // image changes or goes away — a stale tone from the previous photo would
+  // light the new one wrong for a frame. Sampling is async (a second, CORS
+  // clean decode of the same URL, memoised per src); the cancelled flag
+  // keeps a slow sample from landing on a later src.
+  React.useEffect(() => {
+    setImageTone(null)
+    if (!bezel || !hasImage || !src || imageStatus !== "loaded") return
+    let cancelled = false
+    void measureRimTone(src).then((tone) => {
+      if (!cancelled) setImageTone(tone)
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [bezel, hasImage, src, imageStatus, setImageTone])
+
+  return {
+    avatarId,
+    presence,
+    bezelAngle,
+    imageStatus,
+    imageTone,
+    setImageStatus,
+    ref,
+  }
 }

package/src/components/user-avatar/user-avatar-atom.ts

@@ -105,6 +105,12 @@ export const userAvatarImageStatusAtom = stateFamily<ImageStatus>(
   "idle"
 )
 
+/** Rim lightness of the loaded image, `null` until sampled (or unsampleable). */
+export const userAvatarImageToneAtom = stateFamily<number | null>(
+  "imageTone",
+  null
+)
+
 /** @internal Which fields the mounted component controls from props. */
 export const userAvatarConfigAtom = stateFamily<UserAvatarConfig>(
   "config",
@@ -126,6 +132,7 @@ export const userAvatarStateAtom = readFamily<UserAvatarState>(
     presence: get(userAvatarPresenceAtom(id)),
     bezelAngle: get(userAvatarBezelAngleAtom(id)),
     imageStatus: get(userAvatarImageStatusAtom(id)),
+    imageTone: get(userAvatarImageToneAtom(id)),
   })
 )
 
@@ -168,6 +175,18 @@ export const setUserAvatarImageStatusAtom = actionFamily<[status: ImageStatus]>(
   }
 )
 
+/** @internal Written by the hook once the loaded image has been sampled;
+ * cleared (null) when the image changes or goes away. Clamped to [0, 1]. */
+export const setUserAvatarImageToneAtom = actionFamily<[tone: number | null]>(
+  "setImageTone",
+  (_get, set, id, tone) => {
+    set(
+      userAvatarImageToneAtom(id),
+      tone === null || !Number.isFinite(tone) ? null : Math.min(1, Math.max(0, tone))
+    )
+  }
+)
+
 /** @internal Projection of the mounted component's controlled props. */
 export const projectUserAvatarPropsAtom = actionFamily<
   [config: UserAvatarConfig, presence: UserPresence | null | undefined]
@@ -187,6 +206,7 @@ export const resetUserAvatarAtom = actionFamily<[]>(
     set(userAvatarPresenceAtom(id), null)
     set(userAvatarBezelAngleAtom(id), DEFAULT_BEZEL_ANGLE)
     set(userAvatarImageStatusAtom(id), "idle")
+    set(userAvatarImageToneAtom(id), null)
     set(userAvatarConfigAtom(id), DEFAULT_CONFIG)
   }
 )