@exegia/corpora-ui 0.20.0 → 0.22.0

package/dist-lib/components/composed/tree/type.d.ts

@@ -7,8 +7,11 @@ export interface TreeNode {
     /** Leading icon. Required in practice for `sidebar` — it is all that
      * remains of a row while the rail is collapsed. */
     icon?: React.ReactNode;
-    /** Renders an anchor. Without one the row is a button; `toc` leaves
-     * default to `#{id}` so they scroll to the matching heading. */
+    /** Route metadata for the consumer's `onNavigate` — every row renders as
+     * a button, so this is never turned into an anchor element. Read it (with
+     * `target`) off the node your handler receives. One native behaviour is
+     * kept: `toc` rows below the route level jump to `#{id}` after select
+     * (a `#hash` href overrides the id; a non-hash href disables the jump). */
     href?: string;
     target?: "_blank" | "_self" | "_parent" | "_top";
     disabled?: boolean;
@@ -23,14 +26,29 @@ export interface TreeNode {
 export type TreeVariant = "navigation" | "toc" | "sidebar" | "files";
 /** Where a dragged row lands relative to its drop target. */
 export type TreeDropPosition = "before" | "after" | "inside";
+/** Key for one tree’s state in the store. Any stable string; `useTree`
+ * generates one when you don't pass it. */
+export type TreeInstanceId = string;
+/** Row a drag hovers, and where the drop would land. */
+export interface TreeDropTarget {
+    id: string;
+    position: TreeDropPosition;
+}
 interface TreeBaseProps {
     items: TreeNode[];
+    /** Key this tree's state under a name your app can address —
+     * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+     * anywhere under `ExegiaProvider`. Without one the tree generates a key
+     * and its state is dropped when it unmounts. */
+    treeId?: TreeInstanceId;
     /** Never set on the data form — `tree` selects the controller form. */
     tree?: never;
     /** `id` of the current entry — matches any depth. Its ancestors expand. */
     activeId?: string;
-    /** Fires for every selection (rows and leaves alike), after the row's
-     * anchor default — wire your router's navigate here. */
+    /** Fires for every selection (rows and leaves alike), after the node's
+     * own `onSelect`. Rows are buttons, so this is the routing path — wire
+     * your router's navigate here. `toc` rows below the route level still jump
+     * to `#{id}` natively, after this fires. */
     onNavigate?: (node: TreeNode) => void;
     /** Expand/collapse cues. Silent until `bindSounds()`. */
     sound?: boolean;
@@ -62,11 +80,13 @@ export type TreeProps = TreeDataProps | TreeControllerProps;
 export type TreeDataProps = TreeBaseProps & (({
     /** Nested app navigation. With 3 levels of nodes the top level
      * becomes collapsible section names (styled as headings, not
-     * links); with 2 it renders plain link rows. */
+     * rows); with 2 it renders plain selectable rows. */
     variant: "navigation";
 } & TreeReadonlyProps) | ({
-    /** Table of contents: top-level nodes are routes, leaf nodes are
-     * in-page anchors (`#{id}` unless the node carries an `href`). */
+    /** Table of contents: top-level nodes are routes (handled in
+     * `onNavigate`); rows below jump to `#{id}` after select, like an
+     * anchor would. Parents select on the row and expand from a
+     * separate overlay chevron. */
     variant: "toc";
 } & TreeReadonlyProps) | ({
     /** Single-level icon rail. `collapsed` shrinks rows to their
@@ -91,6 +111,11 @@ export type TreeDataProps = TreeBaseProps & (({
  * controlled when passed and hook-owned when its `default*` twin is used
  * instead. */
 export interface UseTreeOptions {
+    /** Key this tree's state under a name your app can address —
+     * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+     * anywhere under `ExegiaProvider`. Without one the hook generates a key
+     * and the state is dropped when the component unmounts. */
+    treeId?: TreeInstanceId;
     /** Which shape the tree takes — gates rename/reorder (`files`) and the
      * collapsible rail (`sidebar`). */
     variant: TreeVariant;
@@ -127,6 +152,8 @@ export interface UseTreeOptions {
 /** Everything the tree can do, callable from outside the component.
  * Returned by `useTree` and accepted by `<Tree tree={…} />`. */
 export interface TreeController {
+    /** The key this tree's state is stored under. */
+    treeId: TreeInstanceId;
     variant: TreeVariant;
     items: TreeNode[];
     /** `navigation` with 3 levels of nodes — depth 0 renders as sections. */
@@ -165,28 +192,99 @@ export interface TreeController {
     /** Whether reorder is wired up at all. */
     canMove: boolean;
     move: (id: string, parentId: string | null, index: number) => void;
+    /** Back to the values the tree mounted with. */
+    reset: () => void;
     dnd: TreeDndContextValue;
 }
 /** @internal What a row needs from the root, threaded through context so
- * the recursive rows stay prop-light. */
+ * the recursive rows stay prop-light.
+ *
+ * Deliberately free of tree state. Rows read state from per-node atoms, so
+ * this value keeps its identity for the life of the tree and expanding one
+ * branch no longer re-renders every row through context. */
 export interface TreeContextValue {
-    tree: TreeController;
+    treeId: TreeInstanceId;
     renderTrailing?: (node: TreeNode) => React.ReactNode;
+    dnd: TreeDndHandlers;
 }
-/** @internal Drag state shared by every row (all `null`/no-op outside
- * `files`). */
-export interface TreeDndContextValue {
+/** @internal The drag event handlers, stable for the life of the tree —
+ * they read drag state out of the store instead of closing over it, so
+ * handing them to every row costs no re-renders. */
+export interface TreeDndHandlers {
     enabled: boolean;
-    draggedId: string | null;
-    /** Row the pointer is over and where the drop would land. */
-    dropTarget: {
-        id: string;
-        position: TreeDropPosition;
-    } | null;
     onRowDragStart: (event: React.DragEvent, id: string) => void;
     onRowDragOver: (event: React.DragEvent, node: TreeNode) => void;
     onRowDragLeave: (event: React.DragEvent) => void;
     onRowDrop: (event: React.DragEvent, node: TreeNode) => void;
     onRowDragEnd: () => void;
 }
+/** @internal Handlers plus live drag state — what `TreeController.dnd`
+ * exposes (all `null`/no-op outside `files`). */
+export interface TreeDndContextValue extends TreeDndHandlers {
+    draggedId: string | null;
+    /** Row the pointer is over and where the drop would land. */
+    dropTarget: TreeDropTarget | null;
+}
+/** Everything observable about one tree, for consumers reading it by id. */
+export interface TreeState {
+    variant: TreeVariant;
+    items: TreeNode[];
+    activeId?: string;
+    expandedIds: ReadonlySet<string>;
+    collapsed: boolean;
+    renamingId: string | null;
+    sectioned: boolean;
+    sectionIds: string[];
+    canRename: boolean;
+    canMove: boolean;
+    draggedId: string | null;
+    dropTarget: TreeDropTarget | null;
+}
+/** Everything doable to one tree from outside its component. */
+export interface TreeActions {
+    expand: (id: string) => void;
+    collapse: (id: string) => void;
+    toggleExpanded: (id: string) => void;
+    expandAll: () => void;
+    collapseAll: () => void;
+    reveal: (id: string) => void;
+    setCollapsed: (collapsed: boolean) => void;
+    toggleCollapsed: () => void;
+    select: (id: string) => void;
+    startRename: (id: string) => void;
+    cancelRename: () => void;
+    rename: (id: string, label: string) => void;
+    move: (id: string, parentId: string | null, index: number) => void;
+    setItems: (items: TreeNode[]) => void;
+    reset: () => void;
+}
+/** @internal Projection of `useTree`'s options — primitives only, so the
+ * store write runs once per real change instead of once per render. */
+export interface TreeConfig {
+    variant: TreeVariant;
+    sound: boolean;
+    controlsItems: boolean;
+    controlsActiveId: boolean;
+    controlsCollapsed: boolean;
+    managesItems: boolean;
+    hasRenameHandler: boolean;
+    hasMoveHandler: boolean;
+}
+/** @internal Latest option callbacks. Only write atoms read this, so it
+ * can be refreshed every commit without re-rendering anything. */
+export interface TreeHandlers {
+    onNavigate?: (node: TreeNode) => void;
+    onItemsChange?: (items: TreeNode[]) => void;
+    onExpandedChange?: (ids: string[]) => void;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    onRename?: (id: string, label: string) => void;
+    onMove?: (id: string, parentId: string | null, index: number) => void;
+}
+/** @internal What an instance starts from, replayed by `resetTreeAtom`. */
+export interface TreeSeed {
+    items: TreeNode[];
+    activeId?: string;
+    collapsed: boolean;
+    expandedIds?: string[];
+}
 export {};

package/dist-lib/components/composed/tree/use-tree-dnd.d.ts

@@ -1,7 +1,18 @@
-import { TreeDndContextValue, TreeNode, UseTreeOptions } from './type';
-/** Owns drag state for the `files` variant: which row is in flight, which
- * row the pointer rests on and where the drop would land. Everything is
- * component state — `dataTransfer` is set for interop but never read, so
- * the flow also works where the store is unavailable (tests, some
- * webviews). Without `onMove` every handler is inert. */
-export declare function useTreeDnd(items: readonly TreeNode[], onMove: UseTreeOptions["onMove"]): TreeDndContextValue;
+import { TreeDndContextValue, TreeDndHandlers, TreeInstanceId } from './type';
+/**
+ * The drag handlers for the `files` variant, stable for the life of the tree.
+ *
+ * Nothing here subscribes to drag state: items, the dragged id and the drop
+ * target are read out of the store when a handler runs. That is what lets
+ * every row share one handler object without re-rendering when a drag moves —
+ * and it keeps `useTree` from subscribing to data it also projects from
+ * props, which would loop on an inline `items` array.
+ *
+ * Inert unless the tree `canMove`. `dataTransfer` is set for interop but
+ * never read, so the flow also works where the store is unavailable (tests,
+ * some webviews).
+ */
+export declare function useTreeDndHandlers(treeId: TreeInstanceId): TreeDndHandlers;
+/** The handlers plus live drag state, for `TreeController.dnd`. Rows take the
+ * handlers alone and read the state per node instead. */
+export declare function useTreeDnd(treeId: TreeInstanceId): TreeDndContextValue;

package/dist-lib/components/composed/tree/use-tree-state.d.ts

@@ -0,0 +1,25 @@
+import { TreeActions, TreeInstanceId, TreeState } from './type';
+/**
+ * Read the tree registered under `treeId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { collapsed, activeId } = useTreeState("app-nav")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on any
+ * change. A component that reads one field should subscribe to that field's
+ * atom instead: `useAtomValue(treeCollapsedAtom("app-nav"))`.
+ */
+export declare function useTreeState(treeId: TreeInstanceId): TreeState;
+/**
+ * Drive the tree registered under `treeId` from anywhere. Writes only — the
+ * caller never re-renders when the tree changes, so this is what a command
+ * palette, a keyboard shortcut or a route guard should reach for.
+ *
+ * ```tsx
+ * const nav = useTreeActions("app-nav")
+ * <Button onClick={nav.collapseAll}>Collapse all</Button>
+ * ```
+ */
+export declare function useTreeActions(treeId: TreeInstanceId): TreeActions;

package/dist-lib/components/composed/tree/use-tree.d.ts

@@ -16,5 +16,9 @@ import { TreeController, UseTreeOptions } from './type';
  * <Tree tree={tree} />
  * <Button onClick={tree.collapseAll}>Collapse all</Button>
  * ```
+ *
+ * State lives in Jotai atoms keyed by `treeId`, so anything under
+ * `ExegiaProvider` can drive this tree without the controller — name it and
+ * reach for `useTreeState(treeId)` / `useTreeActions(treeId)` elsewhere.
  */
 export declare function useTree(options: UseTreeOptions): TreeController;

package/dist-lib/components/composed/user-avatar.d.ts

@@ -1,30 +1,7 @@
-import { AvatarPrimitive } from '../ui/avatar';
-import * as React from "react";
-export interface UserAvatarProps extends Omit<AvatarPrimitive.Root.Props, "children"> {
-    /** Image URL. Without one the initials show immediately — no skeleton. */
-    src?: string;
-    /** Drives the initials, and the alt text unless `alt` overrides it. */
-    name?: string;
-    /** Overrides the initials derived from `name`. */
-    initials?: string;
-    /**
-     * Alt text for the image. Pass "" when adjacent text already names the
-     * person — the image is then decorative.
-     */
-    alt?: string;
-    /**
-     * Force the skeleton, for when the identity itself is still being fetched.
-     * Omitted, it follows the image: a passed `src` skeletons until it resolves.
-     */
-    loading?: boolean;
-}
-/** "Jenny Hamilton" → "JH", "luna" → "L". */
-export declare function initialsFrom(name: string): string;
 /**
- * Identity avatar: an image when one is given, initials otherwise.
- *
- * 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.
+ * Back-compat path. The avatar moved to `components/user-avatar/` (split
+ * into component / atoms / hooks); this module re-exports it so existing
+ * imports keep resolving to the one implementation. Prefer the new path.
  */
-export declare function UserAvatar({ src, name, initials, alt, loading: loadingProp, className, ...props }: UserAvatarProps): React.ReactElement;
+export { UserAvatar, initialsFrom, useUserAvatar, useUserAvatarActions, useUserAvatarState, } from '../user-avatar';
+export type { UserAvatarProps, UserPresence } from '../user-avatar';

package/dist-lib/components/user-avatar/__tests__/user-avatar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-lib/components/user-avatar/component.d.ts

@@ -1,10 +1,3 @@
 import { UserAvatarProps } from './type';
 import * as React from "react";
-/**
- * Identity avatar: an image when one is given, initials otherwise.
- *
- * 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.
- */
-export declare function UserAvatar({ src, name, initials, alt, loading: loadingProp, className, ...props }: UserAvatarProps): React.ReactElement;
+export declare function UserAvatar({ src, name, initials, alt, loading: loadingProp, presence: presenceProp, bezel, avatarId, className, style, ...props }: UserAvatarProps): React.ReactElement;

package/dist-lib/components/user-avatar/index.d.ts

@@ -4,7 +4,12 @@ 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';
+export { DEFAULT_BEZEL_ANGLE, removeUserAvatarInstance, resetUserAvatarAtom, setUserAvatarBezelAngleAtom, setUserAvatarPresenceAtom, toggleUserAvatarPresenceAtom, userAvatarBezelAngleAtom, userAvatarIsOnlineAtom, userAvatarPresenceAtom, userAvatarStateAtom, } from './user-avatar-atom';
 export type * from './type';
 export declare const Avatar: {
     AudioWave: typeof AudioWave;

package/dist-lib/components/user-avatar/presence-badge.d.ts

@@ -0,0 +1,16 @@
+import { 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 declare function PresenceBadge({ presence, lightAngle, className, }: {
+    presence: UserPresence;
+    lightAngle?: number;
+    className?: string;
+}): import("react").JSX.Element;

package/dist-lib/components/user-avatar/type.d.ts

@@ -1,6 +1,11 @@
 import { AvatarPrimitive } from '../ui/avatar';
 import type * as React from "react";
 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"> {
     /** Image URL. Without one the initials show immediately — no skeleton. */
     src?: string;
@@ -18,6 +23,54 @@ export interface UserAvatarProps extends Omit<AvatarPrimitive.Root.Props, "child
      * 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, 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;
+    /**
+     * 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;
+    /** 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. */
+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 {
     className?: string;

package/dist-lib/components/user-avatar/use-user-avatar-state.d.ts

@@ -0,0 +1,26 @@
+import { UserAvatarActions, UserAvatarInstanceId, UserAvatarState } from './type';
+/**
+ * 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 declare function useUserAvatarState(avatarId: UserAvatarInstanceId): UserAvatarState;
+/**
+ * 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 declare function useUserAvatarActions(avatarId: UserAvatarInstanceId): UserAvatarActions;

package/dist-lib/components/user-avatar/use-user-avatar.d.ts

@@ -0,0 +1,37 @@
+import { ImageStatus, UserAvatarInstanceId, UserPresence } from './type';
+import * as React from "react";
+export interface UseUserAvatarOptions {
+    avatarId?: UserAvatarInstanceId;
+    /** Controlled presence. `undefined` leaves the store in charge. */
+    presence?: UserPresence;
+    /** Track the pointer for the bezel highlight. */
+    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 {
+    avatarId: UserAvatarInstanceId;
+    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. */
+    ref: React.RefObject<HTMLElement | null>;
+}
+/**
+ * Binds one avatar to its slice of the store: projects the controlled
+ * `presence` prop, tracks the image status, and — while `bezel` is on —
+ * follows the pointer with a rAF-coalesced `pointermove` listener that turns
+ * the pointer's bearing from the avatar's centre into `bezelAngle`.
+ *
+ * Unnamed avatars key off `useId` and are dropped from the store on unmount;
+ * a named `avatarId` outlives its component so a presence set elsewhere
+ * survives a remount.
+ */
+export declare function useUserAvatar(options: UseUserAvatarOptions): UserAvatarBinding;

package/dist-lib/components/user-avatar/user-avatar-atom.d.ts

@@ -0,0 +1,64 @@
+import { UserAvatarConfig, UserAvatarInstanceId, UserAvatarState, UserPresence } from './type';
+/** Light from the top-left, the classic emboss, until a pointer moves. */
+export declare const DEFAULT_BEZEL_ANGLE = 315;
+type Family<AtomType> = ((id: UserAvatarInstanceId) => AtomType) & {
+    remove: (id: UserAvatarInstanceId) => void;
+};
+/** `null` = no badge. */
+export declare const userAvatarPresenceAtom: Family<import('jotai').PrimitiveAtom<UserPresence | null> & {
+    init: UserPresence | null;
+}>;
+/** Degrees clockwise from 12 o'clock — where the bezel highlight sits. */
+export declare const userAvatarBezelAngleAtom: Family<import('jotai').PrimitiveAtom<number> & {
+    init: number;
+}>;
+export declare const userAvatarImageStatusAtom: Family<import('jotai').PrimitiveAtom<import('@base-ui/react').ImageLoadingStatus> & {
+    init: import('@base-ui/react').ImageLoadingStatus;
+}>;
+/** Rim lightness of the loaded image, `null` until sampled (or unsampleable). */
+export declare const userAvatarImageToneAtom: Family<import('jotai').PrimitiveAtom<number | null> & {
+    init: number | null;
+}>;
+/** @internal Which fields the mounted component controls from props. */
+export declare const userAvatarConfigAtom: Family<import('jotai').PrimitiveAtom<UserAvatarConfig> & {
+    init: UserAvatarConfig;
+}>;
+export declare const userAvatarIsOnlineAtom: Family<import('jotai').Atom<boolean>>;
+/** Whole-state read for callers that want the object; field atoms above are
+ * cheaper for components that watch one thing. */
+export declare const userAvatarStateAtom: Family<import('jotai').Atom<UserAvatarState>>;
+/** Inert while a `presence` prop controls the avatar — the prop is truth. */
+export declare const setUserAvatarPresenceAtom: Family<import('jotai').WritableAtom<null, [presence: UserPresence | null], void> & {
+    init: null;
+}>;
+/** online ⇄ offline; a badge-less avatar comes online. */
+export declare const toggleUserAvatarPresenceAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Stored as given — continuous, not wrapped into [0, 360): the rim is
+ * rotated with a CSS transition, and an unwrapped angle is what lets a
+ * 359° → 1° move take the short way round. Written on every pointer frame,
+ * so it stays a bare set — no config gate, no side effects. */
+export declare const setUserAvatarBezelAngleAtom: Family<import('jotai').WritableAtom<null, [angle: number], void> & {
+    init: null;
+}>;
+/** @internal Reported by the image element; drives the skeleton. */
+export declare const setUserAvatarImageStatusAtom: Family<import('jotai').WritableAtom<null, [status: import('@base-ui/react').ImageLoadingStatus], void> & {
+    init: null;
+}>;
+/** @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 declare const setUserAvatarImageToneAtom: Family<import('jotai').WritableAtom<null, [tone: number | null], void> & {
+    init: null;
+}>;
+/** @internal Projection of the mounted component's controlled props. */
+export declare const projectUserAvatarPropsAtom: Family<import('jotai').WritableAtom<null, [config: UserAvatarConfig, presence: UserPresence | null | undefined], void> & {
+    init: null;
+}>;
+export declare const resetUserAvatarAtom: Family<import('jotai').WritableAtom<null, [], void> & {
+    init: null;
+}>;
+/** Forget an avatar entirely — every family drops the key so the store can
+ * release its state. Call on teardown of a named instance. */
+export declare function removeUserAvatarInstance(id: UserAvatarInstanceId): void;
+export {};

package/dist-lib/components/user-avatar/utils.d.ts

@@ -1,2 +1,24 @@
 /** "Jenny Hamilton" → "JH", "luna" → "L". */
 export declare function initialsFrom(name: string): string;
+/**
+ * Average perceived lightness, 0 (black) → 1 (white), of an image's outer
+ * band — the pixels the bezel ring overlays — or `null` when it cannot be
+ * measured: no DOM/canvas (SSR, test DOM), a decode failure, or a host
+ * without CORS headers (the sample needs a CORS-clean image; the avatar's
+ * own `<img>` is left untouched, so a non-CORS host still displays).
+ * Results are memoised per `src`, so a room of the same face samples once.
+ */
+export declare function measureRimTone(src: string): Promise<number | null>;
+/**
+ * Bezel highlight/shadow alphas for an image whose rim lightness is `tone`
+ * (0 → 1). Against a dark rim the white highlight is eased off (it glares)
+ * and the black shadow pushed up (it has to darken mid-tones to register);
+ * against a pale rim the reverse — the highlight can be full (it barely
+ * shows) and the shadow is what carries the emboss, so it sits lighter.
+ * Linear between; the end points are tuned by eye on a dark and a light
+ * photo in both themes.
+ */
+export declare function bezelAlphasForTone(tone: number): {
+    hi: number;
+    lo: number;
+};

package/dist-lib/index.d.ts

@@ -20,11 +20,14 @@ export * from './components/ui/separator';
 export * from './components/ui/skeleton';
 export * from './components/ui/spinner';
 export * from './components/ui/textarea';
+export * from './components/composed/logo';
 export * from './components/composed/password-input';
 export * from './components/composed/social-providers';
 export * from './components/composed/tree';
-export * from './components/composed/user-avatar';
+export { DEFAULT_BEZEL_ANGLE, PresenceBadge, UserAvatar, initialsFrom, removeUserAvatarInstance, resetUserAvatarAtom, setUserAvatarBezelAngleAtom, setUserAvatarPresenceAtom, toggleUserAvatarPresenceAtom, useUserAvatar, useUserAvatarActions, useUserAvatarState, userAvatarBezelAngleAtom, userAvatarIsOnlineAtom, userAvatarPresenceAtom, userAvatarStateAtom, } from './components/user-avatar';
+export type { UseUserAvatarOptions, UserAvatarActions, UserAvatarBinding, UserAvatarInstanceId, UserAvatarProps, UserAvatarState, UserPresence, } from './components/user-avatar';
 export * from './components/blocks/auth/auth-shell';
+export * from './components/blocks/auth/auth-state';
 export * from './components/blocks/auth/code-auth-block';
 export * from './components/blocks/auth/forgot-password-block';
 export * from './components/blocks/auth/linked-accounts-block';
@@ -34,14 +37,14 @@ export * from './components/blocks/auth/passkey-manager-block';
 export * from './components/blocks/auth/passkey-sign-in-block';
 export * from './components/blocks/auth/signup-block';
 export * from './components/blocks/auth/update-password-block';
-export * from './components/blocks/nav/sidebar-block';
 export * from './components/blocks/nav/sidebar';
 export * from './components/blocks/shell';
 export { default as ShellLayout } from './components/blocks/shell';
 export * from './components/blocks/scaffold';
 export { default as Layout } from './components/blocks/layout';
-export * from './components/blocks/profile/profile-card-block';
+export * from './components/blocks/profile';
 export * from './components/motion/shared-layout-bg';
+export * from './state';
 export { AnimatedPanel as AnimatedSidebar, AnimatedPanelProvider as AnimatedSidebarProvider, AnimatedPanelTrigger as AnimatedSidebarTrigger, AnimatedPanelInset as AnimatedSidebarInset, } from './components/blocks/shell';
 export * from './lib/auth-accent';
 export * from './lib/ease';