pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/text/Text.variants.js

@@ -0,0 +1,98 @@
+"use strict";
+
+/**
+ * `variant` is the level as well as the size. Without this, `react-native-web` renders every
+ * heading as `<h1>` (see `core/heading`).
+ */
+export const HEADING_LEVELS = {
+  h1: 1,
+  h2: 2,
+  h3: 3,
+  h4: 4
+};
+
+/** Runtime companion to `TextVariant`, so the WCAG test can enumerate every variant a consumer can pass. */
+export const TEXT_VARIANTS = ['body', 'body-sm', 'caption', 'label', 'label-sm', 'overline'];
+
+/**
+ * The `fg` roles a text variant may bind to. `fg.subtle` is deliberately NOT one of them: it is the
+ * flat `gray[500]` rung tuned to the 3:1 non-text tier, and measures 3.19:1 against `bg.canvas` on
+ * emerald light — the exact defect `Timeline.test.ts` already documents. Text has no large-text
+ * exemption to fall back on (its smallest variants are `xs`), so the union is closed at the two
+ * derived, measured roles.
+ */
+
+export const HEADING_VARIANTS = {
+  h1: 'label',
+  h2: 'label',
+  h3: 'label-sm',
+  h4: 'label-sm'
+};
+const VARIANT_CONFIG = {
+  body: {
+    fontSize: 'md',
+    weight: 'regular',
+    color: 'default'
+  },
+  'body-sm': {
+    fontSize: 'sm',
+    weight: 'regular',
+    color: 'default'
+  },
+  caption: {
+    fontSize: 'xs',
+    weight: 'regular',
+    color: 'muted'
+  },
+  label: {
+    fontSize: 'md',
+    weight: 'semibold',
+    color: 'default'
+  },
+  'label-sm': {
+    fontSize: 'sm',
+    weight: 'semibold',
+    color: 'default'
+  },
+  overline: {
+    fontSize: 'xs',
+    weight: 'bold',
+    color: 'muted'
+  }
+};
+const HEADING_OVERRIDES = {
+  h1: {
+    fontSize: '3xl'
+  },
+  h2: {
+    fontSize: '2xl'
+  },
+  h3: {
+    fontSize: 'xl'
+  },
+  h4: {
+    fontSize: 'lg'
+  }
+};
+
+/** The role colour a variant resolves to. Pure, so the WCAG test measures it without a `Theme`. */
+export function resolveTextColor(colors, variant) {
+  return colors.fg[VARIANT_CONFIG[variant].color];
+}
+export function resolveTextStyle(theme, variant) {
+  const config = VARIANT_CONFIG[variant];
+  return {
+    ...theme.fontStyleForWeight(theme.fontWeights[config.weight]),
+    fontSize: theme.fontSizes[config.fontSize],
+    color: resolveTextColor(theme.colors, variant)
+  };
+}
+export function resolveHeadingStyle(theme, variant) {
+  const base = resolveTextStyle(theme, HEADING_VARIANTS[variant]);
+  const override = HEADING_OVERRIDES[variant];
+  return override ? {
+    ...base,
+    fontSize: theme.fontSizes[override.fontSize]
+  } : base;
+}
+//# sourceMappingURL=Text.variants.js.map

package/lib/module/modules/text/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { Text, Heading } from "./Text.js";
+//# sourceMappingURL=index.js.map

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

@@ -13,7 +13,8 @@ component wrapping a native `TextInput` (CLAUDE.md).
 | `Textarea.variants.ts` | Pure resolvers (`TEXTAREA_SIZES`, `resolveTextareaStatus`, `resolveTextareaAccessibility`) + the themed structural resolvers `textareaFieldStructure` / `textareaLayout`. No React. |
 | `index.ts` | Public surface: `Textarea`, `TextareaProps`, `TextareaSize`, `TextareaStatus`. |
 | `__tests__/Textarea.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + a11y contract. |
-| `__tests__/Textarea.render.test.tsx` | Render: value/placeholder, `onChangeText` wiring, disabled blocking, status, helper/error message, focus ring. |
+| `__tests__/Textarea.render.test.tsx` | Render: value/placeholder, `onChangeText` wiring, disabled blocking, status, helper/error message, focus-ring tween + reached opacity. |
+| `__tests__/Textarea.motion.test.tsx` | Motion: the reduce-motion snap for the ring and the immediate message removal. |
 
 ## Props
 
@@ -25,7 +26,8 @@ component wrapping a native `TextInput` (CLAUDE.md).
 | `size` | `sm \| md \| lg` | `md` | Fixed internal `minHeight` (72 / 96 / 128dp) — not a numeric prop. |
 | `status` | `default \| error` | `default` | Closed union — drives the field boundary + message colour. |
 | `disabled` | `boolean` | `false` | `editable={false}` + dimmed; blocks `changeText`. |
-| `label` | `string` | — | Rendered above the field; also the field's `accessibilityLabel`. |
+| `label` | `string` | — | Rendered above the field; falls back into the field's `accessibilityLabel`. |
+| `accessibilityLabel` | `string` | `label` | Overrides the label fallback — needed when the visible label lives elsewhere (e.g. a `FormField` wrapper). Previously absent: `label` was the only way in. |
 | `helperText` | `string` | — | Shown when `status` is `default`, or as the `error` fallback (see below). |
 | `errorText` | `string` | — | Shown instead of `helperText` when `status` is `error` and it's provided. |
 | `maxLength` | `number` | — | Passed straight to `TextInput`. |
@@ -52,18 +54,26 @@ No `icon` prop: multiline fields don't carry a leading/trailing icon in this cat
   0`, applied only when `Platform.OS === "web"`) suppresses the browser's own default focus outline,
   which would otherwise double up visibly with the themed ring above. Native is untouched, since
   `outlineWidth` also drives TV remote-control focus there.
-- **No motion in this component.** The focus ring is a plain conditional render, exactly like Button's
-  own ring (which is also not animated) — `useReducedMotion` gates only real animation (Button's press
-  fade), and there is none here, so WCAG 2.3.3 is not applicable.
+- **2.3.3** — two things animate, both `opacity` only, on the native driver: the always-mounted focus
+  ring crossfades (`Textarea.tsx:99`, `fast`) and the helper/error message fades in and out
+  (`useEnterExit`). Both are guarded by `if (!motion.enabled) { …setValue(to); return; }`, so under
+  reduce motion the ring is at its final opacity on the very next render and the message is removed
+  outright rather than faded — pinned by `Textarea.motion.test.tsx`.
 - No `accessibilityRole` override: RN's `TextInput` already exposes the native text-field
   role/behaviour on both platforms, and RN's `AccessibilityRole` union has no closer ARIA-style
   `textbox` value to assign.
-- `accessibilityState={{ disabled }}` tracks the same flag `editable` uses.
-- The label `Text` and the helper/error `Text` are both hidden from assistive tech
-  (`accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`) — their content
-  is carried by the `TextInput`'s own `accessibilityLabel` / `accessibilityHint` (RN's platform
-  equivalent of `aria-describedby`), so a screen-reader user gets ONE announcement at the field, not a
-  separate stop for the label/message plus a repeat on focus.
+- `aria-disabled` tracks the same flag `editable` uses — flat, not `accessibilityState={{…}}`:
+  react-native-web drops the object form entirely.
+- **3.3.1 — CORRECTED to match `FormField`'s own stated rule.** `errorText` now joins the accessible
+  NAME and sets `aria-invalid`, instead of riding `accessibilityHint` — a hint is advisory and some
+  readers suppress it, which a validity message must never be (same fix as `Input`). `helperText`
+  (genuinely advisory) stays on `accessibilityHint` for native.
+- The label `Text` is hidden from assistive tech on native
+  (`accessibilityElementsHidden` + `importantForAccessibility="no-hide-descendants"`) — its content
+  is carried by the field's own `accessibilityLabel`. The helper/error `Text` is hidden the same way
+  on native (carried by `accessibilityHint`), but on web — where `accessibilityHint` reaches nothing
+  at all — it is instead what the field's `aria-describedby` points at by real `nativeID`, omitted
+  whenever the shown message is the error (already in the name).
 
 ## Why `status` is a union, not a `color`
 
@@ -72,8 +82,8 @@ Same reasoning as Button's `tone`: every colour a field boundary or message can
 
 ## Patterns the other modules can copy
 
-1. **The visible helper/error `Text` and the `accessibilityHint` are the SAME computed string**
-   (`resolveTextareaAccessibility().accessibilityHint`) — never two separate strings that could drift.
+1. **The visible helper/error `Text` and the announced message are the SAME computed string**
+   (`resolveTextareaAccessibility().message`) — never two separate strings that could drift.
 2. **When `status` is `error`, the message slot always renders in the danger colour** — `errorText` if
    given, else `helperText` as a fallback — because the field itself is invalid; a bare `helperText` in
    error state still reads as "something's wrong", not as an unrelated hint styled inconsistently.
@@ -89,3 +99,9 @@ Same reasoning as Button's `tone`: every colour a field boundary or message can
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Renders only host elements (`View`/`Text`/`TextInput`) — nothing to memoize.
+
+## 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.

package/lib/module/modules/textarea/Textarea.js

@@ -5,11 +5,15 @@
  * does not depend on it). Same closed-prop shape the rest of the catalogue follows: `size` / `status`
  * are closed unions, colour is resolved from `RoleColors`, and `containerStyle` is the one documented
  * `LayoutStyle` exception for a component wrapping a native `TextInput` (CLAUDE.md).
+ *
+ * Motion comes from `core/motion`: the focus ring crossfades and the helper/error message fades in
+ * and out, both gated by `useMotion()`'s reduce-motion resolution.
  */
 
-import { memo, useState } from "react";
-import { Platform, StyleSheet, Text, TextInput, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
+import { memo, useCallback, useEffect, useId, useMemo, useRef } from "react";
+import { Animated, Platform, StyleSheet, Text, TextInput, View } from "react-native";
+import { useAnimatedValue, useEnterExit, useMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { resolveTextareaAccessibility, resolveTextareaStatus, textareaFieldStructure, textareaLayout, TEXTAREA_SIZES } from "./Textarea.variants.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // Matches Button's own focus ring exactly: a small gap OUTSIDE the field, on the canvas, because
@@ -26,6 +30,7 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
     status = "default",
     disabled = false,
     label,
+    accessibilityLabel,
     helperText,
     errorText,
     maxLength,
@@ -33,19 +38,74 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
     testID
   } = props;
   const theme = useTheme();
-  const [focused, setFocused] = useState(false);
+  const motion = useMotion();
   const spec = TEXTAREA_SIZES[size];
   const statusColors = resolveTextareaStatus(theme.colors, status);
   const a11y = resolveTextareaAccessibility({
     label,
+    accessibilityLabel,
     helperText,
     errorText,
     status,
     disabled
   });
-  const message = a11y.accessibilityHint;
+  const message = a11y.message;
+  // Links the rendered helper line to the field on web, where `accessibilityHint` does not exist.
+  const hintId = useId();
+  const messageMotion = useEnterExit(message !== undefined);
+  // Holds the text on screen while the exit tween runs.
+  const lastMessage = useRef(message);
+  if (message !== undefined) lastMessage.current = message;
+  const ringOpacity = useAnimatedValue(0);
+  const ringAnimation = useRef(null);
+  const setRingVisible = useCallback(visible => {
+    ringAnimation.current?.stop();
+    const to = visible ? 1 : 0;
+    if (!motion.enabled) {
+      ringOpacity.setValue(to);
+      return;
+    }
+    ringAnimation.current = motion.timing(ringOpacity, to, {
+      duration: "fast"
+    });
+    ringAnimation.current.start();
+  }, [motion, ringOpacity]);
+  useEffect(() => () => ringAnimation.current?.stop(), []);
+  const handleFocus = useCallback(() => {
+    if (!disabled) setRingVisible(true);
+  }, [disabled, setRingVisible]);
+  const handleBlur = useCallback(() => setRingVisible(false), [setRingVisible]);
+  const rootStyle = useMemo(() => [textareaLayout(theme), containerStyle], [theme, containerStyle]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.medium), {
+    fontSize: theme.fontSizes.sm,
+    color: theme.colors.fg.default
+  }], [theme]);
+  const fieldStyle = useMemo(() => [textareaFieldStructure(theme, {
+    size
+  }), {
+    borderColor: statusColors.border
+  }, disabled && styles.dimmed], [theme, size, statusColors.border, disabled]);
+  const inputTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: spec.fontSize,
+    color: theme.colors.fg.default,
+    minHeight: spec.minHeight
+  }, styles.input, Platform.OS === "web" && styles.webOutlineReset], [theme, spec.fontSize, spec.minHeight]);
+  const focusRingStyle = useMemo(() => ({
+    position: "absolute",
+    top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
+    borderWidth: FOCUS_RING_WIDTH,
+    borderColor: theme.colors.border.focus,
+    borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
+  }), [theme]);
+  const messageStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    fontSize: theme.fontSizes.xs,
+    color: statusColors.message
+  }], [theme, statusColors.message]);
   return /*#__PURE__*/_jsxs(View, {
-    style: [textareaLayout(theme), containerStyle],
+    style: rootStyle,
     children: [label !== undefined &&
     /*#__PURE__*/
     // Hidden from AT: its text is carried by the TextInput's own `accessibilityLabel` below, so a
@@ -55,17 +115,10 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
     _jsx(Text, {
       accessibilityElementsHidden: true,
       importantForAccessibility: "no-hide-descendants",
-      style: [theme.fontStyleForWeight(theme.fontWeights.medium), {
-        fontSize: theme.fontSizes.sm,
-        color: theme.colors.fg.default
-      }],
+      style: labelStyle,
       children: label
     }), /*#__PURE__*/_jsxs(View, {
-      style: [textareaFieldStructure(theme, {
-        size
-      }), {
-        borderColor: statusColors.border
-      }, disabled && styles.dimmed],
+      style: fieldStyle,
       children: [/*#__PURE__*/_jsx(TextInput, {
         testID: testID,
         value: value,
@@ -78,41 +131,31 @@ export const Textarea = /*#__PURE__*/memo(function Textarea(props) {
         textAlignVertical: "top",
         accessibilityLabel: a11y.accessibilityLabel,
         accessibilityHint: a11y.accessibilityHint,
-        accessibilityState: a11y.accessibilityState,
-        onFocus: () => setFocused(true),
-        onBlur: () => setFocused(false),
-        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-          fontSize: spec.fontSize,
-          color: theme.colors.fg.default,
-          minHeight: spec.minHeight
-        }, styles.input, Platform.OS === "web" && styles.webOutlineReset]
-      }), focused && /*#__PURE__*/_jsx(View, {
+        "aria-describedby": a11y.accessibilityHint === undefined ? undefined : hintId,
+        "aria-invalid": a11y["aria-invalid"],
+        "aria-disabled": a11y["aria-disabled"],
+        onFocus: handleFocus,
+        onBlur: handleBlur,
+        style: inputTextStyle
+      }), /*#__PURE__*/_jsx(Animated.View, {
         pointerEvents: "none",
         testID: "textarea-focus-ring",
-        style: {
-          position: "absolute",
-          top: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-          left: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-          right: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-          bottom: -(FOCUS_RING_GAP + FOCUS_RING_WIDTH),
-          borderWidth: FOCUS_RING_WIDTH,
-          borderColor: theme.colors.border.focus,
-          borderRadius: theme.radii.base + FOCUS_RING_GAP + FOCUS_RING_WIDTH
-        }
+        style: [focusRingStyle, {
+          opacity: ringOpacity
+        }]
       })]
-    }), message !== undefined &&
+    }), messageMotion.mounted && lastMessage.current !== undefined &&
     /*#__PURE__*/
-    // Hidden from AT for the same reason as the label — its content is already the TextInput's
-    // `accessibilityHint` (RN has no `aria-describedby`; `accessibilityHint` is the platform
-    // equivalent), so this Text is the sighted-user copy of the same one string.
-    _jsx(Text, {
+    // Hidden from AT on native for the same reason as the label — the same string already rides
+    // the field's `accessibilityHint` (helper) or its `accessibilityLabel` (error), so a second
+    // stop here would repeat it. On web `accessibilityElementsHidden` is not forwarded, and this
+    // node is instead what the field's `aria-describedby` points at.
+    _jsx(Animated.Text, {
+      nativeID: hintId,
       accessibilityElementsHidden: true,
       importantForAccessibility: "no-hide-descendants",
-      style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-        fontSize: theme.fontSizes.xs,
-        color: statusColors.message
-      }],
-      children: message
+      style: [messageStyle, messageMotion.style],
+      children: lastMessage.current
     })]
   });
 });
@@ -130,7 +173,9 @@ const styles = StyleSheet.create({
   // outline on top of the themed ring above it — a visible double border. Web-only: `outlineWidth`
   // also drives native TV remote-control focus, so zeroing it globally would break that.
   webOutlineReset: {
-    outlineWidth: 0
+    outlineStyle: "solid",
+    outlineWidth: 0,
+    borderWidth: 0
   }
 });
 //# sourceMappingURL=Textarea.js.map

package/lib/module/modules/textarea/Textarea.variants.js

@@ -58,19 +58,24 @@ export function resolveTextareaStatus(colors, status) {
 }
 /**
  * Derives the accessibility surface once, purely, so the label/hint/disabled contract is testable
- * without a renderer. React Native has no `aria-describedby`; `accessibilityHint` is the platform
- * equivalent, so the SAME string this returns is also what the component renders as the visible
- * helper/error `Text` — one source of truth, never two strings that could drift apart.
+ * without a renderer.
+ *
+ * Same split as `resolveInputAccessibility`, for the same reason: a validity message must not ride
+ * `accessibilityHint`, because a hint is advisory and some readers suppress it (the rule
+ * `resolveFormFieldAccessibility` already states). So `errorText` joins the NAME and sets
+ * `aria-invalid`, while the genuinely advisory `helperText` stays on the hint — which the component
+ * additionally links with `aria-describedby` on web, where `accessibilityHint` does not exist.
  */
 export function resolveTextareaAccessibility(input) {
   const isError = (input.status ?? "default") === "error";
-  const hint = isError && input.errorText ? input.errorText : input.helperText;
+  const errorInName = isError && input.errorText ? input.errorText : undefined;
+  const name = [input.accessibilityLabel ?? input.label, errorInName].filter(part => part !== undefined && part !== "");
   return {
-    accessibilityLabel: input.label,
-    accessibilityHint: hint,
-    accessibilityState: {
-      disabled: input.disabled === true
-    }
+    accessibilityLabel: name.length > 0 ? name.join(", ") : undefined,
+    accessibilityHint: errorInName === undefined ? input.helperText : undefined,
+    "aria-invalid": isError,
+    "aria-disabled": input.disabled === true,
+    message: errorInName ?? input.helperText
   };
 }
 

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

@@ -8,11 +8,12 @@ per-item emphasis, no animation.
 
 | File | Role |
 |------|------|
-| `Timeline.tsx` | The component. Maps `items` to rows; wires the decorative connector's hidden-from-AT props. |
+| `Timeline.tsx` | The component + the private memo'd `TimelineRow`. Row models, virtualization threshold, the container reveal, and the decorative connector's hidden-from-AT props. |
 | `Timeline.variants.ts` | Pure resolver (`resolveTimelineColors`) + the structural variant resolvers (`timelineRowStructure`, `timelineConnectorStructure`, `timelineMarkerStructure`, `timelineConnectorLineStructure`, `timelineContentStructure`) and the `TIMELINE_MARKER` size constants. No React, no lucide. |
 | `index.ts` | Public surface: `Timeline`, `TimelineProps`, `TimelineItem`, `IconName` (re-exported from `core/icon`). |
 | `__tests__/Timeline.test.ts` | Pure: WCAG contrast (all brands × modes) for title/description/timestamp and the icon-on-marker pairing, plus the decorative-connector colour-mapping regression guard (mirrors `Divider.test.ts`). |
 | `__tests__/Timeline.render.test.tsx` | Render: item order, description/timestamp omission, marker sizing per kind, connector line present on every row but the last, decorative hide vs exposed text, consumer `style` applies last. |
+| `__tests__/Timeline.perf.test.tsx` | Perf: mounted rows stay bounded for a 10k dataset; no fixed `getItemLayout` is claimed for variable-height rows; an unrelated outer `style` change mounts no extra rows. |
 
 ## Props
 
@@ -31,10 +32,14 @@ reasoning `Divider`'s minimal prop set follows when a component has nothing to v
 - **4.1.2 / structure** — the marker + connecting line are purely decorative (removing them changes
   spacing, not meaning): the connector `View` wrapping both carries `accessibilityElementsHidden` +
   `importantForAccessibility="no-hide-descendants"` (the same pairing `Avatar` uses for its
-  decorative state), so neither the circle nor the line is announced. The title/description/
-  timestamp `Text` nodes are ordinary children of a plain, role-less `View` (the same "container has
-  nothing to announce; children carry their own semantics" reasoning `Card.tsx` documents), so they
-  stay in the accessibility tree, read in the order they appear.
+  decorative state), so neither the circle nor the line is announced.
+- **1.3.1 — a row's title/description/timestamp are ONE accessible node**, via
+  `resolveTimelineItemAccessibility`, not three loose `Text` siblings in a role-less `View` (that
+  shape was tried first and reverted: nothing but visual proximity said which timestamp belonged to
+  which title, the same class of failure `Banner` avoids by composing its own title + message the
+  same way). The content `View` carries `accessible` + `accessibilityRole="text"` +
+  `accessibilityLabel` (`"<title>. <description>. <timestamp>"`, omitted parts skipped); the visible
+  `Text` children are unchanged, so nothing on screen moves.
 - **1.4.3** — `title` (`fg.default`) and `description`/`timestamp` (`fg.muted`) are each measured
   ≥ 4.5:1 against `bg.canvas` for all 8 brands × both modes (`Timeline.test.ts`), the same reference
   surface `Input`/`Badge`/`Button` use for their own resting-state text. `timestamp` deliberately
@@ -50,7 +55,9 @@ reasoning `Divider`'s minimal prop set follows when a component has nothing to v
   `border.interactive`/`border.focus` tokens instead).
 - **Touch target (2.5.x)** — N/A. Timeline has no `onPress`; same reasoning `AVATAR_SIZES` documents
   for its own non-interactive diameters.
-- **2.3.3 (reduced motion)** — N/A. No animation.
+- **2.3.3 (reduced motion)** — the container reveal is skipped entirely when `useMotion().decorative`
+  is false, which reduced motion always forces (`core/motion`); the final state is `setValue`'d, never
+  tweened.
 
 ## Patterns copied from `button/` (the reference module), `avatar/`, and `divider/`
 
@@ -99,6 +106,31 @@ use the closed 22-name `IconName` set already in `core/icon`.
   `fg.muted` (the `readableOn()`-derived role every other module already trusts on `bg.canvas`),
   which clears AA on all 8 brands × both modes.
 
+## Reveal motion (decorative, one value for the whole list)
+
+A single `Animated.Value` on the outer container drives an opacity + `translateY` reveal
+(`core/motion`, `decelerate`); the `translateY` is an interpolation of that same value, so the whole
+thing is one native-driver node. Deliberately **not** per row: rows are recycled `VirtualList` cells,
+so a per-cell reveal would re-fire on every scroll-in and animate during scroll. Gated on
+`useMotion().decorative` (high tier only) — a reveal is pure decoration and is the first motion to
+drop. Stopped on effect cleanup and on unmount.
+
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The `items.map()` renders host `View`/`Text` plus this library's `Icon` with only primitive props — nothing to memoize.
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). Rows are a
+private, memo'd `TimelineRow` fed a memoized row model; `renderItem`/`keyExtractor` are `useCallback`'d
+and the reveal/root style arrays are memoized. Lists of `VIRTUALIZE_THRESHOLD` (20) items or more go
+through `core/list`'s `VirtualList` (device-tier windowing, FlashList when the peer is installed);
+shorter lists render inline so they compose inside a consumer's own `ScrollView`. **No `itemHeight`
+is passed** — a row is title-only (~45dp) up to title + description + timestamp (~88dp), and OS font
+scaling moves both, so any fixed height makes `getItemLayout` lie: wrong scroll offsets that get
+worse the larger the user's text (WCAG 1.4.4). Windowing without `getItemLayout` is correct, just
+slightly less precise — the same call `markdown/` and `more-items/` make. The row key is
+`item.id` when given, else a positional `timeline-index-<i>` — never one derived from `title`, which
+would remount a row on a text edit.
+
+## 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.