pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/app-bar/AppBar.js

@@ -0,0 +1,179 @@
+"use strict";
+
+/**
+ * AppBar — a themed top bar for screen headers: a required title, an optional subtitle, an optional
+ * back affordance, and optional leading/trailing icon actions. Every action is a library `Button`
+ * (icon-only, ghost) driven by a closed `IconName` — never a hand-rolled `Pressable` or a consumer
+ * `ReactNode` slot that would bypass the API contract.
+ *
+ * No `accessibilityRole` on the bar itself: like `Card`, this is a plain grouping container. The
+ * title carries `accessibilityRole="header"` at level 1 (WCAG 1.3.1 / 2.4.6 — it is the screen's
+ * heading, the one the rest of the screen's outline nests under, and
+ * rotor heading navigation is a primary way screen-reader users move around an app); the subtitle
+ * reads as its own `Text`, and each composed `Button` carries its own role/state.
+ *
+ * Its only motion is `useTitleCrossfade` below — opacity on the title box, nothing else. Elevation
+ * on scroll would need a public scroll-offset prop, which the API contract does not justify here.
+ */
+
+import { memo, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Text, View } from "react-native";
+import { HEADING_LEVEL, HeadingText } from "../../core/heading/index.js";
+import { useAnimatedValue, useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { Button } from "../button/index.js";
+import { appBarActionsRowStructure, appBarSideStructure, appBarSideTrailingStructure, appBarStructure, appBarTitleBoxStructure, resolveAppBarColors } from "./AppBar.variants.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const BACK_LABEL = "Back";
+function normalizeTrailingActions(trailing) {
+  if (trailing === undefined) return [];
+  if (Array.isArray(trailing)) return trailing;
+  return [trailing];
+}
+/**
+ * Dissolves the title box when the title or subtitle changes: fade out, swap the text, fade back
+ * in. Opacity only, native driver. First mount never animates — the navigator already animates a
+ * header appearing, and a second fade there reads as a stutter.
+ */
+function useTitleCrossfade(title, subtitle) {
+  const motion = useMotion();
+  const opacity = useAnimatedValue(1);
+  const running = useRef(null);
+  const fadeInPending = useRef(false);
+  const [displayed, setDisplayed] = useState({
+    title,
+    subtitle
+  });
+  useEffect(() => {
+    if (displayed.title === title && displayed.subtitle === subtitle) {
+      if (!fadeInPending.current) return;
+      fadeInPending.current = false;
+      running.current?.stop();
+      if (!motion.enabled) {
+        opacity.setValue(1);
+        return;
+      }
+      running.current = motion.timing(opacity, 1, {
+        duration: "fast",
+        easing: "decelerate"
+      });
+      running.current.start();
+      return;
+    }
+    running.current?.stop();
+    if (!motion.enabled) {
+      opacity.setValue(1);
+      setDisplayed({
+        title,
+        subtitle
+      });
+      return;
+    }
+    running.current = motion.timing(opacity, 0, {
+      duration: "fast",
+      easing: "accelerate"
+    });
+    running.current.start(({
+      finished
+    }) => {
+      if (!finished) return;
+      fadeInPending.current = true;
+      setDisplayed({
+        title,
+        subtitle
+      });
+    });
+  }, [title, subtitle, displayed, motion, opacity]);
+  useEffect(() => () => running.current?.stop(), []);
+  const stale = displayed.title !== title || displayed.subtitle !== subtitle;
+  return {
+    displayed,
+    opacity,
+    stale
+  };
+}
+export const AppBar = /*#__PURE__*/memo(function AppBar({
+  title,
+  subtitle,
+  onBack,
+  leading,
+  trailing,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const colors = resolveAppBarColors(theme.colors);
+  const trailingActions = useMemo(() => normalizeTrailingActions(trailing), [trailing]);
+  const {
+    displayed,
+    opacity,
+    stale
+  } = useTitleCrossfade(title, subtitle);
+  const titleBoxStyle = useMemo(() => [appBarTitleBoxStructure(theme), {
+    opacity
+  }], [theme, opacity]);
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [appBarStructure(theme), {
+      backgroundColor: colors.background,
+      borderBottomColor: colors.border
+    }, style],
+    children: [/*#__PURE__*/_jsx(View, {
+      style: appBarSideStructure(theme),
+      children: onBack !== undefined ? /*#__PURE__*/_jsx(Button, {
+        icon: "arrow-left",
+        accessibilityLabel: BACK_LABEL,
+        variant: "ghost",
+        tone: "neutral",
+        onPress: onBack,
+        testID: testID === undefined ? undefined : `${testID}-back`
+      }) : leading !== undefined ? /*#__PURE__*/_jsx(Button, {
+        icon: leading.icon,
+        accessibilityLabel: leading.accessibilityLabel,
+        variant: "ghost",
+        tone: "neutral",
+        onPress: leading.onPress,
+        testID: testID === undefined ? undefined : `${testID}-leading`
+      }) : null
+    }), /*#__PURE__*/_jsxs(Animated.View, {
+      style: titleBoxStyle
+      // The outgoing title is still mounted (and still an accessibility element) while it fades,
+      // so without this a screen reader can announce the title of the screen just left.
+      ,
+      accessibilityElementsHidden: stale,
+      importantForAccessibility: stale ? "no-hide-descendants" : "auto",
+      testID: testID === undefined ? undefined : `${testID}-title`,
+      children: [/*#__PURE__*/_jsx(HeadingText, {
+        accessibilityRole: "header",
+        "aria-level": HEADING_LEVEL.screen,
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.bold), {
+          fontSize: theme.fontSizes.lg,
+          color: colors.title
+        }],
+        children: displayed.title
+      }), displayed.subtitle !== undefined && /*#__PURE__*/_jsx(Text, {
+        numberOfLines: 1,
+        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+          fontSize: theme.fontSizes.xs,
+          color: colors.subtitle
+        }],
+        children: displayed.subtitle
+      })]
+    }), /*#__PURE__*/_jsx(View, {
+      style: appBarSideTrailingStructure(theme),
+      children: trailingActions.length > 0 ? /*#__PURE__*/_jsx(View, {
+        style: appBarActionsRowStructure(theme),
+        children: trailingActions.map((action, index) => /*#__PURE__*/_jsx(Button, {
+          icon: action.icon,
+          accessibilityLabel: action.accessibilityLabel,
+          variant: "ghost",
+          tone: "neutral",
+          onPress: action.onPress,
+          testID: testID === undefined ? undefined : `${testID}-trailing-${index}`
+        }, `${action.icon}-${action.accessibilityLabel}-${index}`))
+      }) : null
+    })]
+  });
+});
+//# sourceMappingURL=AppBar.js.map

package/lib/module/modules/app-bar/AppBar.variants.js

@@ -0,0 +1,72 @@
+"use strict";
+
+/**
+ * AppBar's style + colour resolution — same split as `Button.variants` / `Badge.variants`:
+ *  - STRUCTURE (row layout, title box flex, side min-width for touch targets) lives in the themed
+ *    `appBarStructure` resolver, static per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveAppBarColors`, never a raw ramp
+ *    and never a hardcoded hex.
+ *
+ * Free of React and lucide, so the WCAG + behaviour tests import this directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
+ */
+
+import { createThemedVariants } from "../../core/style/index.js";
+
+/** Matches `Button`'s `MIN_TOUCH_TARGET` — each side slot reserves at least 44dp for icon actions. */
+export const APP_BAR_SIDE_MIN_WIDTH = 44;
+/**
+ * Maps AppBar onto the theme's role colours. No `tone`/`color` prop to widen — every colour this
+ * bar can show is one of these role lookups (same reasoning as `Divider`/`Card`).
+ */
+export function resolveAppBarColors(colors) {
+  return {
+    background: colors.bg.surface,
+    border: colors.border.default,
+    title: colors.fg.default,
+    subtitle: colors.fg.muted
+  };
+}
+
+/**
+ * Structural styles only — the header row, title box, and side slots. No colours (resolved
+ * separately, applied inline over this), so these compile once per theme identity via the
+ * `WeakMap`-cached themed resolver and never rebuilds per render.
+ */
+export const appBarStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    paddingHorizontal: theme.space[2],
+    paddingVertical: theme.space[2],
+    columnGap: theme.space[1],
+    borderBottomWidth: theme.borderWidths.thin
+  }
+}));
+export const appBarSideStructure = createThemedVariants(_theme => ({
+  base: {
+    minWidth: APP_BAR_SIDE_MIN_WIDTH,
+    justifyContent: "center"
+  }
+}));
+export const appBarSideTrailingStructure = createThemedVariants(_theme => ({
+  base: {
+    minWidth: APP_BAR_SIDE_MIN_WIDTH,
+    justifyContent: "center",
+    alignItems: "flex-end"
+  }
+}));
+export const appBarTitleBoxStructure = createThemedVariants(theme => ({
+  base: {
+    flex: 1,
+    paddingHorizontal: theme.space[1]
+  }
+}));
+export const appBarActionsRowStructure = createThemedVariants(theme => ({
+  base: {
+    flexDirection: "row",
+    alignItems: "center",
+    columnGap: theme.space[1]
+  }
+}));
+//# sourceMappingURL=AppBar.variants.js.map

package/lib/module/modules/app-bar/MODULE.md

@@ -0,0 +1,68 @@
+# app-bar/ — a themed top bar for screen headers
+
+`AppBar` groups a required title, an optional subtitle, an optional back affordance, and optional
+leading/trailing icon actions into one header row. Every action is a library `Button` (icon-only,
+ghost) driven by a closed `IconName` — never a consumer `ReactNode` slot.
+
+## Files
+
+| File | Role |
+|------|------|
+| `AppBar.tsx` | The component. Composes ghost `Button`s for back/leading/trailing actions; `style` last. |
+| `AppBar.variants.ts` | Pure resolver (`resolveAppBarColors`) + themed structural resolvers. No React, no lucide. |
+| `index.ts` | Public surface: `AppBar`, `AppBarProps`, `AppBarAction`, `IconName`. |
+| `__tests__/AppBar.test.ts` | Pure: WCAG 1.4.3 on the title, colour-mapping contract, side min-width floor. |
+| `__tests__/AppBar.render.test.tsx` | Render: title/subtitle, heading role + level, back press, trailing action press, title crossfade (including the outgoing title leaving the accessibility tree), consumer `style` last. |
+| `__tests__/AppBar.dom.test.tsx` | Real DOM (`jest.web.config.js`): the title renders a real `<h1>`. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `title` | `string` | — | Required. Single-line, bold, `fg.default`. |
+| `subtitle` | `string` | — | Optional. Single-line, `fg.muted`. |
+| `onBack` | `() => void` | — | Renders `arrow-left` ghost button labelled "Back". |
+| `leading` | `AppBarAction` | — | Custom leading action when `onBack` is absent. |
+| `trailing` | `AppBarAction \| AppBarAction[]` | — | One or more trailing icon actions. |
+| `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
+| `testID` | `string` | — | Forwarded to the outermost `View`. |
+
+## Accessibility contract (WCAG)
+
+- **1.3.1 / 2.4.6 — the title is a level-1 heading.** It carries `accessibilityRole="header"` and
+  `aria-level={1}` (`HEADING_LEVEL.screen`, `core/heading`) — without a level, `react-native-web`
+  still renders `<h1>` by default, but every OTHER heading on the screen (`Section`, `EmptyState`,
+  `DataTable` headers) would collapse to `<h1>` too. Level 1 is deliberate: the title is the screen's
+  own heading, the one the rest of the screen's outline nests under. AppBar + `Section` are what
+  almost every screen is built from, so without it rotor heading navigation — a primary way
+  screen-reader users move around an app — finds nothing on the screen at all. The subtitle stays
+  plain text: it is supporting copy, not a second heading level.
+- **No `accessibilityRole` on the bar itself** — like `Card`, a plain grouping container; each
+  composed `Button` carries its own role/state.
+- **The outgoing title is hidden while it crossfades.** The old text stays mounted for the whole
+  fade-out, so the title box carries `accessibilityElementsHidden` +
+  `importantForAccessibility="no-hide-descendants"` (both props, the idiom `Textarea` uses) for
+  exactly that window — otherwise a reader can announce the heading of the screen just left. Under
+  reduced motion there is no fade, so it is never hidden.
+- **4.1.3** — n/a: a title change is a heading change, not a status message, and the navigator
+  already announces the screen change. Nothing here calls `useAnnounce` (that would double-speak).
+
+## Motion
+
+One animation only: a **title crossfade**. When `title` or `subtitle` changes the title box fades
+out, swaps the text, and fades back in — opacity only, native driver, all timing resolved through
+`useMotion()` (`fast` + `accelerate`/`decelerate`). The displayed text therefore lags the prop by
+one fade-out, so the *old* title dissolves rather than the new one flashing.
+
+- **No animation on first mount** — the navigator already animates a header appearing.
+- **Reduce-motion (WCAG 2.3.3)** snaps opacity with `setValue` and swaps the text immediately.
+- In-flight animations are stopped on effect re-run and on unmount.
+- Elevation-on-scroll was considered and rejected: it needs a public scroll-offset prop, and the
+  API contract does not widen props without cause.
+- The title box carries `testID={`${testID}-title`}` for tests.
+
+## Performance
+
+Wrapped in `React.memo`. Trailing actions are normalised through `useMemo` so a stable array
+reference is not required from the caller. The title box's style array is `useMemo`'d so the
+`Animated.View` is not handed a fresh array each render.

package/lib/module/modules/app-bar/index.js

@@ -0,0 +1,10 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/app-bar`. Value exports and type exports are split for
+ * `verbatimModuleSyntax`. The style/colour resolvers stay internal — a consumer configures an AppBar
+ * through its props, never by importing its internals.
+ */
+
+export { AppBar } from "./AppBar.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/avatar/Avatar.js

@@ -1,32 +1,57 @@
 "use strict";
 
 /**
- * Avatar — a circular identity glyph: a remote image, initials, or (with neither) a plain neutral
- * placeholder. No press handling, no loading spinner, no animation — the simplest module in the
+ * Avatar — an identity glyph: a remote image, initials, or (with neither) a plain placeholder,
+ * circular or rounded. No press handling, no loading spinner — one of the simplest modules in the
  * library, which is exactly why its accessibility default differs from every sibling: an avatar
  * usually sits beside a visible name, so `accessibilityLabel` is optional, not a required trap (see
  * `Avatar.variants.ts` → `resolveAvatarAccessibility`).
+ *
+ * The image is `expo-image`, not RN's `Image`, for one reason that matters on a recycled list: RN's
+ * `Image` keeps painting the old bitmap until the new URI resolves, so a FlashList row hands the
+ * next row the previous subject's face. `recyclingKey` blanks it on the spot.
+ *
+ * The image's fade-in is expo-image's own native `transition`, timed from the global motion system —
+ * deliberately not an `Animated.Value`. An avatar renders per list row, so it must add no JS-driven
+ * animation, no mount animation and no loop; the fade is load-triggered and runs entirely natively.
  */
 
-import { memo } from "react";
-import { Image, StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
-import { AVATAR_SIZES, avatarStructure, resolveAvatarAccessibility, resolveAvatarColors } from "./Avatar.variants.js";
+import { memo, useMemo } from "react";
+import { StyleSheet, Text, View } from "react-native";
+import { MediaImage } from "../../core/media/index.js";
+import { useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
+import { AVATAR_SIZES, avatarStructure, resolveAvatarAccessibility, resolveAvatarColors, resolveAvatarIdentityColors } from "./Avatar.variants.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 export const Avatar = /*#__PURE__*/memo(function Avatar({
   size = "md",
+  shape = "circle",
   source,
   initials,
+  identity,
+  recyclingKey,
   accessibilityLabel,
   style,
   testID
 }) {
   const theme = useTheme();
+  const motion = useMotion();
   const spec = AVATAR_SIZES[size];
-  const colors = resolveAvatarColors(theme.colors);
   const a11y = resolveAvatarAccessibility({
     accessibilityLabel
   });
+  const colors = useMemo(() => identity === undefined || identity.length === 0 ? resolveAvatarColors(theme.colors) : resolveAvatarIdentityColors(theme.palette, identity), [theme.colors, theme.palette, identity]);
+  const rootStyle = useMemo(() => [avatarStructure(theme, {
+    size,
+    shape
+  }), {
+    backgroundColor: colors.containerBg
+  }, style], [theme, size, shape, colors, style]);
+  const initialsStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.semibold), {
+    fontSize: spec.fontSize,
+    color: colors.initialsText
+  }], [theme, spec, colors]);
+  const transition = motion.enabled ? motion.duration("fast") : 0;
   return /*#__PURE__*/_jsx(View, {
     testID: testID,
     accessible: a11y.accessible,
@@ -34,22 +59,17 @@ export const Avatar = /*#__PURE__*/memo(function Avatar({
     accessibilityLabel: a11y.accessibilityLabel,
     accessibilityElementsHidden: a11y.accessibilityElementsHidden,
     importantForAccessibility: a11y.importantForAccessibility,
-    style: [avatarStructure(theme, {
-      size
-    }), {
-      backgroundColor: colors.containerBg
-    }, style],
-    children: source ? /*#__PURE__*/_jsx(Image, {
+    style: rootStyle,
+    children: source ? /*#__PURE__*/_jsx(MediaImage, {
       testID: testID === undefined ? undefined : `${testID}-image`,
       source: source,
-      resizeMode: "cover",
+      contentFit: "cover",
+      transition: transition,
+      recyclingKey: recyclingKey ?? source.uri,
       style: StyleSheet.absoluteFill
     }) : initials ? /*#__PURE__*/_jsx(Text, {
       numberOfLines: 1,
-      style: [theme.fontStyleForWeight(theme.fontWeights.semibold), {
-        fontSize: spec.fontSize,
-        color: colors.initialsText
-      }],
+      style: initialsStyle,
       children: initials.slice(0, 2)
     }) : null
   });

package/lib/module/modules/avatar/Avatar.variants.js

@@ -18,7 +18,11 @@
  * only `react-native`'s `StyleSheet`, as `core/style` and `Button.variants.ts` do).
  */
 
+import { resolveFilledAccent } from "../../theme/tokens/builders/accentText.js";
 import { createThemedVariants } from "../../core/style/index.js";
+
+/** `circle` for a person, `rounded` for an organisation/product, `square` for tiles/thumbnails. */
+
 /**
  * Avatar-specific dimensions. Kept a plain constant — no theme dependency — same as `BUTTON_SIZES` /
  * `CHECKBOX_SIZES`, so the render layer and tests share one source of truth for the diameter.
@@ -59,6 +63,32 @@ export function resolveAvatarColors(colors) {
     initialsText: colors.fg.default
   };
 }
+
+/** The ramp names an identity seed hashes onto — never the brand ramp, which would make every
+ *  identity look alike. Slot order mirrors web's `AVATAR_COLORS` so a given name lands on the same
+ *  hue on both platforms; `cyan` stands in for web's violet (this palette ships one purple ramp). */
+export const AVATAR_IDENTITY_RAMPS = ["purple", "blue", "green", "orange", "red", "pink", "cyan", "teal"];
+/** Web's `avatarColor` hash, character for character, so both platforms agree on the slot. */
+export function avatarIdentityRamp(seed) {
+  let hash = 0;
+  for (let i = 0; i < seed.length; i += 1) {
+    hash = seed.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return AVATAR_IDENTITY_RAMPS[Math.abs(hash) % AVATAR_IDENTITY_RAMPS.length];
+}
+/**
+ * A stable per-identity fill drawn from the palette's own hue ramps, with its label DERIVED by the
+ * same `resolveFilledAccent` walk every filled surface in this library uses. Web hashes onto eight
+ * fixed hex swatches and inks them with `onFilled`, which is why two of its eight measure ~2:1
+ * against white; walking a real ramp instead clears AA on every brand × mode (`Avatar.test.ts`).
+ */
+export function resolveAvatarIdentityColors(palette, seed) {
+  const filled = resolveFilledAccent(palette[avatarIdentityRamp(seed)]);
+  return {
+    containerBg: filled.fill,
+    initialsText: filled.label
+  };
+}
 /**
  * Derives the accessibility surface once, purely, so the "decorative unless labelled" contract is
  * testable without a renderer. Unlike `Button`'s icon-only shape or `Checkbox`'s unlabelled shape,
@@ -93,8 +123,7 @@ export const avatarStructure = createThemedVariants(theme => ({
   base: {
     alignItems: "center",
     justifyContent: "center",
-    overflow: "hidden",
-    borderRadius: theme.radii.full
+    overflow: "hidden"
   },
   variants: {
     size: {
@@ -118,10 +147,22 @@ export const avatarStructure = createThemedVariants(theme => ({
         width: AVATAR_SIZES.xl.box,
         height: AVATAR_SIZES.xl.box
       }
+    },
+    shape: {
+      circle: {
+        borderRadius: theme.radii.full
+      },
+      rounded: {
+        borderRadius: theme.radii.base
+      },
+      square: {
+        borderRadius: theme.radii.none
+      }
     }
   },
   defaultVariants: {
-    size: "md"
+    size: "md",
+    shape: "circle"
   }
 }));
 //# sourceMappingURL=Avatar.variants.js.map

package/lib/module/modules/avatar/MODULE.md

@@ -1,8 +1,8 @@
 # avatar/ — a circular identity glyph (image, initials, or a plain placeholder)
 
-`Avatar` is the simplest module in the library — no press handling, no loading state, no
-animation — which is exactly why its accessibility default is the one place it deliberately
-diverges from `Button`/`Checkbox`: an avatar is almost always rendered beside a visible name, so
+`Avatar` is one of the simplest modules in the library — no press handling, no loading state —
+which is exactly why its accessibility default is the one place it deliberately diverges from
+`Button`/`Checkbox`: an avatar is almost always rendered beside a visible name, so
 `accessibilityLabel` is optional rather than a required trap.
 
 ## Files
@@ -10,29 +10,45 @@ diverges from `Button`/`Checkbox`: an avatar is almost always rendered beside a
 | File | Role |
 |------|------|
 | `Avatar.tsx` | The component. Fallback precedence (image → initials → placeholder), a11y wiring. |
-| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. No React. |
-| `index.ts` | Public surface: `Avatar`, `AvatarProps`, `AvatarSize`. |
-| `__tests__/Avatar.test.ts` | Pure: WCAG contrast (all brands × modes) + the size scale + the a11y contract. |
-| `__tests__/Avatar.render.test.tsx` | Render: fallback precedence, size scale, decorative-vs-labelled a11y. |
+| `Avatar.variants.ts` | Pure resolvers (`AVATAR_SIZES`, `resolveAvatarColors`, `resolveAvatarIdentityColors`, `avatarIdentityRamp`, `resolveAvatarAccessibility`) + the themed structural variant resolver `avatarStructure`. No React. |
+| `index.ts` | Public surface: `Avatar`, `AvatarProps`, `AvatarSize`, `AvatarShape`. |
+| `__tests__/Avatar.test.ts` | Pure: WCAG contrast for the neutral **and** every identity fill (all brands × modes) + the identity hash + the size scale + the a11y contract. |
+| `__tests__/Avatar.render.test.tsx` | Render: fallback precedence, size scale, shape, identity fill, recycling key, decorative-vs-labelled a11y. |
 
 ## Props
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `size` | `xs \| sm \| md \| lg \| xl` | `md` | Diameters 24 / 32 / 40 / 56 / 72 dp. |
+| `shape` | `circle \| rounded` | `circle` | `rounded` (the brand `radii.base`) for an org/product; a person stays circular. |
 | `source` | `{ uri: string }` | — | A remote image. Wins over `initials` when present. |
 | `initials` | `string` | — | Shown when there is no `source`. Clipped to the first two characters. |
+| `identity` | `string` | — | Seeds a stable hashed fill for the initials/placeholder state. Absent → the neutral fill. |
+| `recyclingKey` | `string` | `source.uri` | Blanks the image the instant it changes — see Recycled lists below. |
 | `accessibilityLabel` | `string` | — | **Optional** — see Accessibility contract below. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | The image (when `source` is set) also gets `${testID}-image`. |
 
-No `tone`/`color` prop: an avatar has exactly one neutral identity (`resolveAvatarColors`), the
-same reasoning as `Checkbox`'s colour resolver — there is nothing for an app to widen.
+No `tone`/`color` prop. `identity` is a *seed*, not a colour: it hashes onto one of eight of the
+palette's own hue ramps and derives its label with the same `resolveFilledAccent` walk every filled
+surface here uses, so an app still cannot introduce an off-palette or unreadable value. Web hashes
+onto eight fixed hex swatches and inks them with `onFilled`, which is why two of its eight measure
+~2:1 against white; the slot order matches web's so a given org lands on the same hue on both.
+
+## Recycled lists — why `expo-image`, not RN's `Image`
+
+Avatar is the one image on every recycled FlashList row. RN's `Image` keeps painting the old bitmap
+until the new URI resolves, so a scrolled row shows the **previous** subject's face for a beat.
+`expo-image`'s `recyclingKey` blanks it on the spot; a 120 ms `transition` comes along with it.
+`expo-image` is an **optional peer** — the same shape `FileUpload` uses for the native pickers.
+The image itself now renders through `core/media`'s shared `MediaImage` (expo-image when installed,
+RN `Image` fallback otherwise) instead of calling `getExpoImage()` directly — same behavior, one
+fewer place to special-case the optional-peer fallback.
 
 ## Accessibility contract (WCAG)
 
-- **1.4.3** — initials text is `fg.default` on `bg.sunken`; measured ≥ 4.5:1 for every brand × mode
-  (`resolveAvatarColors`, tested in `Avatar.test.ts`).
+- **1.4.3** — initials text is `fg.default` on `bg.sunken`, or a derived label on the identity fill;
+  both measured ≥ 4.5:1 for every brand × mode (`Avatar.test.ts`).
 - **Decorative by default, unlike `Button`'s icon-only shape.** `Button`/`Checkbox` make an
   unlabelled interactive element a type error, because their label is the *only* carrier of
   meaning for a screen-reader user. An avatar is not interactive and is almost always adjacent to
@@ -49,14 +65,14 @@ same reasoning as `Checkbox`'s colour resolver — there is nothing for an app t
 
 ## Patterns copied from `Button`/`Checkbox`
 
-1. **Structure vs colour split.** Diameter + the circular radius → `createThemedVariants`
-   (`avatarStructure`, registered once per theme). Colour → resolved from role tokens
-   (`resolveAvatarColors`), applied inline.
+1. **Structure vs colour split.** Diameter + radius → `createThemedVariants` (`avatarStructure`,
+   registered once per theme). Colour → resolved from role tokens (`resolveAvatarColors`) or the
+   palette's hue ramps (`resolveAvatarIdentityColors`), applied inline.
 2. **Pure, testable resolvers** in `Avatar.variants.ts` (no React) so the WCAG + accessibility
    contract is unit-tested by measuring real palettes — never eyeballed.
 3. **`radii.full` clips a circle for any diameter.** One token (a finite `9999`, not `Infinity` —
    RN rejects non-finite style values) covers every size instead of each variant computing its own
-   `box / 2`.
+   `box / 2`; `shape="rounded"` swaps it for `radii.base`.
 4. **`style: LayoutStyle` last and once, no `{...rest}`** — internals never receive consumer style.
 
 ## Testing note — hidden elements and React Native Testing Library
@@ -74,3 +90,9 @@ the tree but intentionally unreachable by assistive tech — see `Avatar.render.
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). No child library component receives a derived array/object/callback, so no `useCallback`/`useMemo` was needed.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
+- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.