@exegia/corpora-ui 0.20.0 → 0.21.0

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

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test"
+import { act, fireEvent, render, screen } from "@testing-library/react"
+import { createStore, Provider } from "jotai"
+
+import { UserAvatar } from "../component"
+import {
+  DEFAULT_BEZEL_ANGLE,
+  removeUserAvatarInstance,
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  userAvatarBezelAngleAtom,
+  userAvatarIsOnlineAtom,
+  userAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "../user-avatar-atom"
+import { useUserAvatarActions, useUserAvatarState } from "../use-user-avatar-state"
+import type { UserAvatarActions, UserAvatarState } from "../type"
+
+const badge = () => document.querySelector('[data-slot="user-avatar-presence"]')
+const bezel = () => document.querySelector('[data-slot="user-avatar-bezel"]')
+const frame = () =>
+  document.querySelector<HTMLElement>('[data-slot="user-avatar-frame"]')
+/** The rim's rotation, parsed. The component damps the stored bearing
+ * (`bezelAngle * 0.8`) so the highlight trails the pointer slightly. */
+const BEZEL_DAMPING = 0.8
+const rimRotation = () => {
+  const match = /rotate\((-?[\d.]+)deg\)/.exec(bezel()?.getAttribute("style") ?? "")
+  return match ? Number(match[1]) : Number.NaN
+}
+
+describe("UserAvatar · presence badge", () => {
+  test("no presence, no badge", () => {
+    render(<UserAvatar name="Jenny Hamilton" />)
+    expect(badge()).toBeNull()
+  })
+
+  test("online is a filled dot named for AT; offline a hollow ring", () => {
+    const { rerender } = render(
+      <UserAvatar name="Jenny Hamilton" presence="online" />
+    )
+    expect(badge()?.getAttribute("data-presence")).toBe("online")
+    expect(screen.getByRole("img", { name: "Online" })).toBeDefined()
+    expect(badge()?.className).toContain("bg-emerald-500")
+
+    rerender(<UserAvatar name="Jenny Hamilton" presence="offline" />)
+    expect(screen.getByRole("img", { name: "Offline" })).toBeDefined()
+    expect(badge()?.className).toContain("border-2")
+
+    // Releasing the prop clears the badge — a real transition for a user.
+    rerender(<UserAvatar name="Jenny Hamilton" />)
+    expect(badge()).toBeNull()
+  })
+
+  test("online reflects the badge colour onto the disc; offline does not", async () => {
+    const reflection = () =>
+      document.querySelector('[data-slot="user-avatar-reflection"]')
+    const { rerender } = render(
+      <UserAvatar name="Jenny Hamilton" presence="online" />
+    )
+    expect(reflection()).not.toBeNull()
+    // Static — no transform, unlike the bezel rim.
+    expect(reflection()?.getAttribute("style")).toBeNull()
+    expect(reflection()?.className).toContain("radial-gradient")
+    // Initials disc: the smaller, fainter pool.
+    expect(reflection()?.hasAttribute("data-image")).toBe(false)
+    expect(reflection()?.className).toContain("[--reflect-peak:16%]")
+    // A requested-but-not-loaded src still shows initials — still the small
+    // pool; only a loaded photo gets the larger one.
+    // happy-dom's Image reports naturalWidth 0 (Base UI reads that as a
+    // failed preload) — a broken src keeps the initials and the small pool.
+    rerender(
+      <UserAvatar name="Jenny Hamilton" presence="online" src="/broken.jpg" />
+    )
+    expect(reflection()?.hasAttribute("data-image")).toBe(false)
+
+    // Stand in a preload that succeeds: now a photo is on screen.
+    const RealImage = window.Image
+    window.Image = class {
+      complete = true
+      naturalWidth = 72
+      onload: (() => void) | null = null
+      onerror: (() => void) | null = null
+      src = ""
+    } as unknown as typeof window.Image
+    try {
+      rerender(
+        <UserAvatar name="Jenny Hamilton" presence="online" src="/ok.jpg" />
+      )
+      await act(async () => {
+        await new Promise((r) => setTimeout(r, 0))
+      })
+      expect(reflection()?.hasAttribute("data-image")).toBe(true)
+      expect(reflection()?.className).toContain("[--reflect-peak:30%]")
+    } finally {
+      window.Image = RealImage
+    }
+    rerender(<UserAvatar name="Jenny Hamilton" presence="offline" />)
+    expect(reflection()).toBeNull()
+  })
+
+  test("the badge carries a sheen lit from the bezel angle; none without a bezel", async () => {
+    const sheen = () =>
+      document.querySelector('[data-slot="user-avatar-presence-sheen"]')
+    const { rerender } = render(
+      <UserAvatar avatarId="sheen" name="Jenny Hamilton" presence="online" />
+    )
+    expect(sheen()).not.toBeNull()
+    const rot = () =>
+      Number(/rotate\((-?[\d.]+)deg\)/.exec(sheen()?.getAttribute("style") ?? "")?.[1])
+    expect(rot()).toBeCloseTo(DEFAULT_BEZEL_ANGLE * BEZEL_DAMPING, 5)
+
+    // Same light as the rim: a pointer move rotates both together.
+    const host = frame() as HTMLElement
+    host.getBoundingClientRect = () =>
+      ({ left: 100, top: 100, width: 40, height: 40, right: 140, bottom: 140 }) as DOMRect
+    await act(async () => {
+      fireEvent.pointerMove(window, { clientX: 200, clientY: 120 })
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    })
+    expect(rot()).toBeCloseTo(90 * BEZEL_DAMPING, 5)
+    expect(rot()).toBeCloseTo(rimRotation(), 5)
+
+    rerender(<UserAvatar bezel={false} name="Jenny Hamilton" presence="online" />)
+    expect(sheen()).toBeNull()
+    removeUserAvatarInstance("sheen")
+  })
+
+  test("the root carries data-presence for styling hooks", () => {
+    render(<UserAvatar name="Jenny Hamilton" presence="online" />)
+    expect(
+      document
+        .querySelector('[data-slot="user-avatar"]')
+        ?.getAttribute("data-presence")
+    ).toBe("online")
+  })
+})
+
+describe("UserAvatar · bezel", () => {
+  test("on by default: an emboss shadow on the root and a rotated rim", () => {
+    render(<UserAvatar name="Jenny Hamilton" />)
+    const root = document.querySelector('[data-slot="user-avatar"]')
+    expect(root?.hasAttribute("data-bezel")).toBe(true)
+    expect(root?.className).toContain("shadow-[inset")
+    // Rests at the classic top-left light until a pointer moves.
+    expect(rimRotation()).toBeCloseTo(DEFAULT_BEZEL_ANGLE * BEZEL_DAMPING, 5)
+  })
+
+  test("bezel={false} renders a flat disc", () => {
+    render(<UserAvatar bezel={false} name="Jenny Hamilton" />)
+    expect(bezel()).toBeNull()
+    expect(
+      document.querySelector('[data-slot="user-avatar"]')?.hasAttribute("data-bezel")
+    ).toBe(false)
+  })
+
+  test("the rim follows the pointer's bearing from the avatar's centre", async () => {
+    render(<UserAvatar avatarId="lit" name="Jenny Hamilton" />)
+    const host = frame() as HTMLElement
+    // happy-dom rects are 0×0; give the frame a box the hook can measure.
+    host.getBoundingClientRect = () =>
+      ({ left: 100, top: 100, width: 40, height: 40, right: 140, bottom: 140 }) as DOMRect
+
+    // Pointer straight to the right of centre (120,120) → 3 o'clock → 90°.
+    await act(async () => {
+      fireEvent.pointerMove(window, { clientX: 200, clientY: 120 })
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    })
+    expect(rimRotation()).toBeCloseTo(90 * BEZEL_DAMPING, 5)
+
+    // Straight below → 6 o'clock → 180°.
+    await act(async () => {
+      fireEvent.pointerMove(window, { clientX: 120, clientY: 300 })
+      await new Promise((r) => requestAnimationFrame(() => r(null)))
+    })
+    expect(rimRotation()).toBeCloseTo(180 * BEZEL_DAMPING, 5)
+    removeUserAvatarInstance("lit")
+  })
+})
+
+describe("UserAvatar · store", () => {
+  test("presence, toggle, isOnline and reset on an isolated store", () => {
+    const store = createStore()
+    expect(store.get(userAvatarPresenceAtom("a"))).toBeNull()
+    store.set(setUserAvatarPresenceAtom("a"), "online")
+    expect(store.get(userAvatarIsOnlineAtom("a"))).toBe(true)
+    store.set(toggleUserAvatarPresenceAtom("a"))
+    expect(store.get(userAvatarPresenceAtom("a"))).toBe("offline")
+    // A badge-less avatar comes online on toggle.
+    store.set(setUserAvatarPresenceAtom("a"), null)
+    store.set(toggleUserAvatarPresenceAtom("a"))
+    expect(store.get(userAvatarPresenceAtom("a"))).toBe("online")
+
+    store.set(setUserAvatarBezelAngleAtom("a"), 400)
+    // Continuous — not wrapped — so a CSS rotation takes the short way.
+    expect(store.get(userAvatarBezelAngleAtom("a"))).toBe(400)
+    store.set(setUserAvatarBezelAngleAtom("a"), Number.NaN)
+    expect(store.get(userAvatarBezelAngleAtom("a"))).toBe(400)
+
+    store.set(resetUserAvatarAtom("a"))
+    expect(store.get(userAvatarStateAtom("a"))).toEqual({
+      presence: null,
+      bezelAngle: DEFAULT_BEZEL_ANGLE,
+      imageStatus: "idle",
+    })
+    removeUserAvatarInstance("a")
+  })
+
+  test("a controlled presence prop wins over store writes; hooks by id read and drive", () => {
+    let actions!: UserAvatarActions
+    let state!: UserAvatarState
+    function Probe() {
+      actions = useUserAvatarActions("me")
+      state = useUserAvatarState("me")
+      return null
+    }
+    const store = createStore()
+    const { rerender } = render(
+      <Provider store={store}>
+        <UserAvatar avatarId="me" name="Jenny Hamilton" presence="offline" />
+        <Probe />
+      </Provider>
+    )
+    expect(state.presence).toBe("offline")
+    act(() => actions.setPresence("online"))
+    // Controlled: the store write is inert, the badge stays offline.
+    expect(badge()?.getAttribute("data-presence")).toBe("offline")
+
+    // Uncontrolled: the store drives the badge from anywhere.
+    rerender(
+      <Provider store={store}>
+        <UserAvatar avatarId="me" name="Jenny Hamilton" />
+        <Probe />
+      </Provider>
+    )
+    expect(badge()).toBeNull()
+    act(() => actions.setPresence("online"))
+    expect(badge()?.getAttribute("data-presence")).toBe("online")
+    expect(state.presence).toBe("online")
+    act(() => actions.togglePresence())
+    expect(badge()?.getAttribute("data-presence")).toBe("offline")
+    removeUserAvatarInstance("me")
+  })
+})

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

@@ -5,49 +5,148 @@ import * as React from "react"
 import { Avatar, AvatarImage } from "@/components/ui/avatar"
 import { cn } from "@/lib/utils"
 import { Fallback } from "./fallback"
-import type { ImageStatus, UserAvatarProps } from "./type"
+import { PresenceBadge } from "./presence-badge"
+import type { UserAvatarProps } from "./type"
+import { useUserAvatar } from "./use-user-avatar"
 
 /**
- * Identity avatar: an image when one is given, initials otherwise.
+ * Identity avatar: an image when one is given, initials otherwise, with an
+ * optional presence badge and a pointer-lit bezel.
  *
  * A passed `src` is assumed to be remote, so the slot holds a skeleton until
  * the image resolves rather than flashing initials that are about to be
  * replaced. A failed load settles on the initials.
+ *
+ * State (presence, bezel angle, image status) lives in Jotai atoms keyed by
+ * `avatarId` — name the avatar and `useUserAvatarActions(id).setPresence()`
+ * flips its badge from anywhere under `ExegiaProvider`.
  */
+/** The rim (and the badge sheen) trail the pointer's bearing slightly rather
+ * than pointing dead at it — a touch of lag reads as weight. */
+const BEZEL_DAMPING = 0.8
+
 export function UserAvatar({
   src,
   name = "",
   initials,
   alt,
   loading: loadingProp,
+  presence: presenceProp,
+  bezel = true,
+  avatarId,
   className,
+  style,
   ...props
 }: UserAvatarProps): React.ReactElement {
-  const [status, setStatus] = React.useState<ImageStatus>("idle")
+  const hasImage = src !== undefined
+  const avatar = useUserAvatar({
+    avatarId,
+    presence: presenceProp,
+    bezel,
+    hasImage,
+  })
+  const { presence, bezelAngle, imageStatus, setImageStatus, ref } = avatar
+
   const loading =
     loadingProp ??
-    (src !== undefined && (status === "idle" || status === "loading"))
+    (hasImage && (imageStatus === "idle" || imageStatus === "loading"))
+  // A photo is actually on screen — not merely requested. A broken or
+  // still-loading `src` shows initials/skeleton and should be treated as
+  // the flat disc it is.
+  const showsImage = hasImage && loadingProp !== true && imageStatus === "loaded"
 
   return (
-    <Avatar
-      className={cn(
-        "size-8 border-2 border-white bg-neutral-800 text-xl",
-        className
-      )}
-      data-loading={loading || undefined}
-      data-slot="user-avatar"
-      {...props}
+    // The frame is what the badge and bezel hang off: the Avatar root clips
+    // to its circle, and the badge has to sit on the rim, half outside it.
+    // Sizing classes still target the Avatar — the frame shrink-wraps it.
+    <span
+      className="relative inline-flex shrink-0 rounded-full"
+      data-slot="user-avatar-frame"
+      ref={ref as React.RefObject<HTMLSpanElement>}
     >
-      {/* Held back while forced-loading: a loaded image would hide the
-          fallback the skeleton lives in. */}
-      {src === undefined || loadingProp === true ? null : (
-        <AvatarImage
-          alt={alt ?? name}
-          onLoadingStatusChange={setStatus}
-          src={src}
+      <Avatar
+        className={cn(
+          "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 &&
+            "shadow-[inset_0_3px_3px_--theme(--color-white/80%),inset_0_-1px_2px_--theme(--color-black/15%)] dark:shadow-[inset_0_1px_1px_--theme(--color-white/5%),inset_0_-8px_2px_--theme(--color-black/20%)]",
+          className
+        )}
+        data-avatar-id={avatar.avatarId}
+        data-bezel={bezel ? "" : undefined}
+        data-loading={loading || undefined}
+        data-presence={presence ?? undefined}
+        data-slot="user-avatar"
+        style={style}
+        {...props}
+      >
+        {/* Held back while forced-loading: a loaded image would hide the
+            fallback the skeleton lives in. */}
+        {!hasImage || loadingProp === true ? null : (
+          <AvatarImage
+            alt={alt ?? name}
+            onLoadingStatusChange={setImageStatus}
+            src={src}
+          />
+        )}
+        <Fallback name={name} initials={initials} loading={loading} />
+      </Avatar>
+      {presence === "online" ? (
+        // The badge's green "reflected" onto the disc: a static radial wash
+        // anchored at the badge corner that fades inward, so the dot reads
+        // as a light source sitting on the avatar rather than a sticker on
+        // it. Does not move with the bezel — it belongs to the badge, not
+        // the pointer. Sits above the image, below the bezel and the badge.
+        <span
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute inset-0 rounded-full",
+            // One gradient, four knobs: colour, peak alpha, mid alpha, reach.
+            // Light mode is quieter than dark (a green wash on a pale disc
+            // reads as a stain, on a dark one as a glow), and an initials
+            // disc — flat, no photo to sit on — takes a smaller, fainter
+            // pool than an image does.
+            "[--reflect:--theme(--color-emerald-500)] dark:[--reflect:--theme(--color-emerald-400)]",
+            showsImage
+              ? "[--reflect-peak:30%] [--reflect-mid:12%] [--reflect-reach:56%] dark:[--reflect-peak:40%] dark:[--reflect-mid:16%] dark:[--reflect-reach:60%]"
+              : "[--reflect-peak:16%] [--reflect-mid:6%] [--reflect-reach:40%] dark:[--reflect-peak:26%] dark:[--reflect-mid:9%] dark:[--reflect-reach:46%]",
+            "bg-[radial-gradient(circle_at_88%_88%,color-mix(in_oklab,var(--reflect)_var(--reflect-peak),transparent)_0%,color-mix(in_oklab,var(--reflect)_var(--reflect-mid),transparent)_22%,transparent_var(--reflect-reach))]",
+            "transition-opacity duration-150 ease-smooth-out"
+          )}
+          data-image={showsImage ? "" : undefined}
+          data-slot="user-avatar-reflection"
+        />
+      ) : null}
+      {bezel ? (
+        // 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.
+        <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%)]",
+            // 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))]",
+            "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)` }}
+        />
+      ) : null}
+      {presence ? (
+        <PresenceBadge
+          lightAngle={bezel ? bezelAngle * BEZEL_DAMPING : undefined}
+          presence={presence}
         />
-      )}
-      <Fallback name={name} initials={initials} loading={loading} />
-    </Avatar>
+      ) : null}
+    </span>
   )
 }

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

@@ -5,7 +5,26 @@ import { Fallback } from "./fallback"
 export { AudioWave } from "./audio-wave"
 export { UserAvatar } from "./component"
 export { Fallback } from "./fallback"
+export { PresenceBadge } from "./presence-badge"
 export { initialsFrom } from "./utils"
+export { useUserAvatar } from "./use-user-avatar"
+export type { UseUserAvatarOptions, UserAvatarBinding } from "./use-user-avatar"
+export { useUserAvatarActions, useUserAvatarState } from "./use-user-avatar-state"
+// The public atom surface. `@internal` atoms (config, image status, the
+// props projection) stay unexported on purpose — `export *` would make every
+// internal a breaking-change surface for consumer apps.
+export {
+  DEFAULT_BEZEL_ANGLE,
+  removeUserAvatarInstance,
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  userAvatarBezelAngleAtom,
+  userAvatarIsOnlineAtom,
+  userAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "./user-avatar-atom"
 export type * from "./type"
 
 export const Avatar = {

package/src/components/user-avatar/presence-badge.tsx

@@ -0,0 +1,56 @@
+import { cn } from "@/lib/utils"
+import type { UserPresence } from "./type"
+
+/**
+ * Corner dot naming whether the person is reachable. Sits on the avatar
+ * frame, outside the clipped circle, with a background-coloured ring so it
+ * reads against any image. Colour is not the only signal: `offline` is a
+ * hollow ring, `online` a filled dot, and the label is spelled out for AT.
+ *
+ * `lightAngle` (degrees clockwise from 12) lays a faint sheen across the dot
+ * from that side — the same angle the avatar's bezel is lit from, so the two
+ * highlights agree and the badge reads as a bead sitting in the same light.
+ */
+export function PresenceBadge({
+  presence,
+  lightAngle,
+  className,
+}: {
+  presence: UserPresence
+  lightAngle?: number
+  className?: string
+}) {
+  const online = presence === "online"
+  return (
+    <span
+      aria-label={online ? "Online" : "Offline"}
+      className={cn(
+        "absolute right-0 bottom-0 box-content size-[22%] min-h-1.5 min-w-1.5 overflow-hidden rounded-full",
+        "ring-2 ring-background transition-colors duration-150 ease-smooth-out",
+        online
+          ? "bg-emerald-500 dark:bg-emerald-400"
+          : "border-2 border-muted-foreground/60 bg-background dark:border-muted-foreground/70",
+        className
+      )}
+      data-presence={presence}
+      data-slot="user-avatar-presence"
+      role="img"
+    >
+      {lightAngle !== undefined ? (
+        // Highlight at 12 o'clock, fading out by the middle, rotated so it
+        // faces the light. Rotation transitions; the gradient is static.
+        <span
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute inset-0 rounded-full",
+            "bg-[linear-gradient(to_bottom,--theme(--color-white/55%),--theme(--color-white/12%)_38%,transparent_58%)]",
+            "dark:bg-[linear-gradient(to_bottom,--theme(--color-white/40%),--theme(--color-white/8%)_38%,transparent_58%)]",
+            "transition-transform duration-150 ease-smooth-out motion-reduce:transition-none"
+          )}
+          data-slot="user-avatar-presence-sheen"
+          style={{ transform: `rotate(${lightAngle}deg)` }}
+        />
+      ) : null}
+    </span>
+  )
+}

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

@@ -6,6 +6,13 @@ export type ImageStatus = Parameters<
   NonNullable<AvatarPrimitive.Image.Props["onLoadingStatusChange"]>
 >[0]
 
+/** Whether the person is reachable right now — drawn as the corner badge. */
+export type UserPresence = "online" | "offline"
+
+/** Key for one avatar's state in the store. Any stable string; `useUserAvatar`
+ * generates one when the component does not name itself. */
+export type UserAvatarInstanceId = string
+
 export interface UserAvatarProps extends Omit<
   AvatarPrimitive.Root.Props,
   "children"
@@ -26,6 +33,49 @@ export interface UserAvatarProps extends Omit<
    * Omitted, it follows the image: a passed `src` skeletons until it resolves.
    */
   loading?: boolean
+  /**
+   * Corner badge: a green dot for `online`, a hollow grey ring for `offline`.
+   * Omitted, no badge — unless the avatar is driven by id and something set
+   * its presence in the store. Controlled when passed.
+   */
+  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.
+   */
+  bezel?: boolean
+  /**
+   * Name this avatar's slice of the store so `useUserAvatarState(id)` /
+   * `useUserAvatarActions(id)` can read or drive it from anywhere under
+   * `ExegiaProvider`. Unnamed avatars key off `useId` and are dropped on
+   * unmount.
+   */
+  avatarId?: UserAvatarInstanceId
+}
+
+/** Everything the store knows about one avatar. */
+export interface UserAvatarState {
+  presence: UserPresence | null
+  /** Bezel light direction in degrees, clockwise from 12 o'clock. Continuous
+   * (may leave [0, 360)) so the rim's CSS rotation never spins the long way;
+   * `((a % 360) + 360) % 360` if you need it normalised. */
+  bezelAngle: number
+  imageStatus: ImageStatus
+}
+
+/** Write-only handles onto one avatar. Nothing here re-renders the caller. */
+export interface UserAvatarActions {
+  setPresence: (presence: UserPresence | null) => void
+  togglePresence: () => void
+  setBezelAngle: (angle: number) => void
+  reset: () => void
+}
+
+/** @internal Which fields the mounted component controls from props. The
+ * store must never overwrite a controlled value. */
+export interface UserAvatarConfig {
+  controlsPresence: boolean
 }
 
 export interface IAudioWaveProps {

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

@@ -0,0 +1,60 @@
+"use client"
+
+import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import type {
+  UserAvatarActions,
+  UserAvatarInstanceId,
+  UserAvatarState,
+} from "./type"
+import {
+  resetUserAvatarAtom,
+  setUserAvatarBezelAngleAtom,
+  setUserAvatarPresenceAtom,
+  toggleUserAvatarPresenceAtom,
+  userAvatarStateAtom,
+} from "./user-avatar-atom"
+
+/**
+ * Read the avatar registered under `avatarId` from anywhere below
+ * `ExegiaProvider` — no props, no ref, no provider of its own.
+ *
+ * ```tsx
+ * const { presence } = useUserAvatarState("me")
+ * ```
+ *
+ * Returns the whole state object, so the caller re-renders on any change —
+ * including every bezel frame while a pointer moves. A component that only
+ * cares about presence should subscribe to that atom instead:
+ * `useAtomValue(userAvatarPresenceAtom("me"))`.
+ */
+export function useUserAvatarState(
+  avatarId: UserAvatarInstanceId
+): UserAvatarState {
+  return useAtomValue(userAvatarStateAtom(avatarId))
+}
+
+/**
+ * Write-only handles onto the avatar registered under `avatarId`. Nothing
+ * here subscribes, so a presence indicator elsewhere in the app can flip
+ * the badge without re-rendering when the avatar changes.
+ *
+ * ```tsx
+ * const { setPresence } = useUserAvatarActions("me")
+ * socket.on("presence", (p) => setPresence(p))
+ * ```
+ */
+export function useUserAvatarActions(
+  avatarId: UserAvatarInstanceId
+): UserAvatarActions {
+  const setPresence = useSetAtom(setUserAvatarPresenceAtom(avatarId))
+  const togglePresence = useSetAtom(toggleUserAvatarPresenceAtom(avatarId))
+  const setBezelAngle = useSetAtom(setUserAvatarBezelAngleAtom(avatarId))
+  const reset = useSetAtom(resetUserAvatarAtom(avatarId))
+
+  return React.useMemo(
+    () => ({ setPresence, togglePresence, setBezelAngle, reset }),
+    [setPresence, togglePresence, setBezelAngle, reset]
+  )
+}