pixelize-native-library 1.0.6 → 1.2.0

package/lib/module/modules/markdown/parseMarkdown.js

@@ -0,0 +1,153 @@
+"use strict";
+
+/**
+ * A small hand-rolled markdown parser — no dependencies, never throws. Supports the subset the
+ * renderer draws: h1–h6, bold, italic, inline code, fenced code blocks, unordered/ordered lists,
+ * links, blockquotes, paragraphs. Anything malformed degrades to literal text.
+ */
+
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
+const UNORDERED_RE = /^\s*[-*+]\s+(.*)$/;
+const ORDERED_RE = /^\s*\d+[.)]\s+(.*)$/;
+const BLOCKQUOTE_RE = /^\s*>\s?(.*)$/;
+const FENCE_RE = /^\s*```/;
+const INLINE_RE = /`([^`\n]+)`|\[([^\]\n]+)\]\(([^()\s]+)\)|\*\*([^*\n]+)\*\*|__([^_\n]+)__|\*([^*\n]+)\*|_([^_\n]+)_/g;
+export function parseInline(text) {
+  const nodes = [];
+  let last = 0;
+  INLINE_RE.lastIndex = 0;
+  for (let match = INLINE_RE.exec(text); match !== null; match = INLINE_RE.exec(text)) {
+    if (match.index > last) nodes.push({
+      type: "text",
+      content: text.slice(last, match.index)
+    });
+    const [, code, linkText, linkUrl, bold, boldAlt, italic, italicAlt] = match;
+    if (code !== undefined) nodes.push({
+      type: "code",
+      content: code
+    });else if (linkText !== undefined && linkUrl !== undefined) nodes.push({
+      type: "link",
+      content: linkText,
+      url: linkUrl
+    });else if (bold !== undefined) nodes.push({
+      type: "bold",
+      content: bold
+    });else if (boldAlt !== undefined) nodes.push({
+      type: "bold",
+      content: boldAlt
+    });else if (italic !== undefined) nodes.push({
+      type: "italic",
+      content: italic
+    });else if (italicAlt !== undefined) nodes.push({
+      type: "italic",
+      content: italicAlt
+    });
+    last = match.index + match[0].length;
+  }
+  if (last < text.length) nodes.push({
+    type: "text",
+    content: text.slice(last)
+  });
+  return nodes;
+}
+function parseBlocks(content) {
+  const lines = content.split(/\r?\n/);
+  const blocks = [];
+  let paragraph = [];
+  const flushParagraph = () => {
+    if (paragraph.length === 0) return;
+    blocks.push({
+      type: "paragraph",
+      children: parseInline(paragraph.join(" "))
+    });
+    paragraph = [];
+  };
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? "";
+    if (FENCE_RE.test(line)) {
+      flushParagraph();
+      const body = [];
+      i += 1;
+      // An unclosed fence swallows the rest of the input rather than failing.
+      while (i < lines.length && !FENCE_RE.test(lines[i] ?? "")) {
+        body.push(lines[i] ?? "");
+        i += 1;
+      }
+      i += 1;
+      blocks.push({
+        type: "code-block",
+        content: body.join("\n")
+      });
+      continue;
+    }
+    const heading = HEADING_RE.exec(line);
+    if (heading !== null) {
+      flushParagraph();
+      const level = (heading[1] ?? "#").length;
+      blocks.push({
+        type: "heading",
+        level,
+        children: parseInline(heading[2] ?? "")
+      });
+      i += 1;
+      continue;
+    }
+    if (BLOCKQUOTE_RE.test(line)) {
+      flushParagraph();
+      const quoted = [];
+      while (i < lines.length) {
+        const quote = BLOCKQUOTE_RE.exec(lines[i] ?? "");
+        if (quote === null) break;
+        quoted.push(quote[1] ?? "");
+        i += 1;
+      }
+      blocks.push({
+        type: "blockquote",
+        children: parseInline(quoted.join(" ").trim())
+      });
+      continue;
+    }
+    if (UNORDERED_RE.test(line) || ORDERED_RE.test(line)) {
+      flushParagraph();
+      const ordered = ORDERED_RE.test(line) && !UNORDERED_RE.test(line);
+      const itemRe = ordered ? ORDERED_RE : UNORDERED_RE;
+      const items = [];
+      while (i < lines.length) {
+        const item = itemRe.exec(lines[i] ?? "");
+        if (item === null) break;
+        items.push(parseInline(item[1] ?? ""));
+        i += 1;
+      }
+      blocks.push({
+        type: "list",
+        ordered,
+        items
+      });
+      continue;
+    }
+    if (line.trim() === "") {
+      flushParagraph();
+      i += 1;
+      continue;
+    }
+    paragraph.push(line.trim());
+    i += 1;
+  }
+  flushParagraph();
+  return blocks;
+}
+export function parseMarkdown(content) {
+  try {
+    return parseBlocks(content);
+  } catch {
+    return [{
+      type: "paragraph",
+      children: [{
+        type: "text",
+        content
+      }]
+    }];
+  }
+}
+//# sourceMappingURL=parseMarkdown.js.map

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

@@ -16,11 +16,13 @@ own, not a dependency on the `Modal` component.
 
 | File | Role |
 |------|------|
-| `Menu.tsx` | The component. `cloneElement` trigger composition, `Modal` + backdrop + row list, open/close state. |
-| `Menu.variants.ts` | Pure resolver (`resolveMenuItemColor`) + the themed structural resolvers (`menuOverlayStructure`, `menuSheetStructure`, `menuRowStructure`). No React, no lucide. |
+| `Menu.tsx` | The component. `cloneElement` trigger composition, `Modal` + backdrop + row list, open/close state. Rows are a plain `.map()` inside a `ScrollView` (built only while `open`) — action menus are short lists, so `FlatList`'s VirtualizedList setup on every open was measurable open-time cost with no windowing benefit at current call sites; `ScrollView` keeps the sheet's `maxHeight: 320` scrollable for a list that doesn't fit, without that per-open setup cost. |
+| `Menu.variants.ts` | Pure resolvers (`resolveMenuItemColor`, `resolveMenuRowPressedBackground`) + the themed structural resolvers (`menuOverlayStructure`, `menuSheetStructure`, `menuRowStructure`). No React, no lucide. |
 | `index.ts` | Public surface: `Menu`, `MenuProps`, `MenuItem`, `MenuTriggerProps`, `MenuItemTone`, `IconName` (re-exported from `core/icon`). |
 | `__tests__/Menu.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + the tone→role mapping. |
-| `__tests__/Menu.render.test.tsx` | Render: open/close, trigger `onPress` chaining, disabled gating, item selection, backdrop dismiss, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/Menu.render.test.tsx` | Render: open/close, trigger `onPress` chaining, disabled gating, item selection, backdrop dismiss, the sheet's menu/modal semantics on BOTH paths, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__tests__/Menu.keyboard.test.tsx` | Web keyboard: roving tabindex, arrows/Home/End/typeahead, Space activation, Escape. Routes the mocked helpers into the real `keyboard.web` implementation. |
+| `__tests__/Menu.motion.test.tsx` | Reduce motion (WCAG 2.3.3), both halves: motion off → the sheet opens already at rest with no `Animated.timing` and `animationType="none"`; motion on → it really tweens from the entrance transform (forcing Animated's JS driver, since a native-driven value never advances under Jest). |
 
 ## Props
 
@@ -29,7 +31,7 @@ own, not a dependency on the `Modal` component.
 | `trigger` | `ReactElement<MenuTriggerProps>` | — | Required. A single element accepting `onPress` (e.g. a `Button`). Cloned to chain its `onPress` with opening the menu. |
 | `items` | `{ label: string; icon?: IconName; onPress: () => void; tone?: "default" \| "danger" }[]` | — | Required. Rendered in order; `danger` renders the row in `status.danger.text`. |
 | `disabled` | `boolean` | `false` | Blocks the menu from opening. Does **not** restyle the trigger — see "Design decisions" below. |
-| `testID` | `string` | — | Seeds `${testID}-backdrop` and `${testID}-item-${index}`. Not applied to the trigger — the trigger owns its own `testID`. |
+| `testID` | `string` | — | Seeds `${testID}-backdrop`, `${testID}-sheet` and `${testID}-item-${index}`. Not applied to the trigger — the trigger owns its own `testID`. |
 
 No `style` prop — like Tooltip, Menu renders no sized node of its own for an app to place; the
 trigger keeps whatever layout it already has. `variant`/`size` are also absent: Menu has one fixed
@@ -37,8 +39,16 @@ row size, since an action list's row height isn't a caller-facing choice.
 
 ## Accessibility contract (WCAG)
 
-- **4.1.2 / semantics** — every row is `accessibilityRole="menuitem"`. The backdrop is
-  `accessible={false}` (same as Select's) so it isn't announced as a separate focusable element.
+- **4.1.2 / semantics** — the sheet carries `accessibilityRole="menu"`, the container role its
+  `accessibilityRole="menuitem"` rows need (rows without one are announced as loose menu items with
+  no menu). The backdrop is `accessible={false}` (same as Select's) so it isn't announced as a
+  separate focusable element.
+- **4.1.2 / modal semantics** — the sheet also carries `accessibilityViewIsModal` +
+  `onAccessibilityEscape={closeMenu}`, the pair `Modal.tsx` establishes for its own panel. Both are
+  set on the sheet node itself, BEFORE the portal branch, so they apply on **both** paths: RN's own
+  `<Modal>` presents a separate native surface, but the web-portal path renders no `<Modal>` at all,
+  and without this the whole page behind the menu stayed in the accessibility tree and reachable by
+  swipe on web.
 - **1.4.3** — every row's label is measured ≥ 4.5:1 against the sheet fill (`bg.surface`), for both
   `default` (`fg.default`) and `danger` (`status.danger.text`) tones, across all 8 brands × both
   modes.
@@ -50,7 +60,7 @@ row size, since an action list's row height isn't a caller-facing choice.
 - **Icon-only rule (rule 5) does not apply** — every row always renders a visible `label` text; a
   menu row is never icon-only.
 - **2.3.3** — the menu's `animationType` is `"none"` instead of `"fade"` when `useReducedMotion()`
-  is true.
+  is true, and the sheet's own scale/lift `setValue`s straight to rest (`Menu.motion.test.tsx`).
 - Backdrop press closes the menu without calling any item's `onPress` — dismissal and selection are
   two distinct code paths (`closeMenu` vs. `selectItem`), so a stray tap can never accidentally fire
   an action.
@@ -66,8 +76,7 @@ row size, since an action list's row height isn't a caller-facing choice.
    `onLongPress`/`onPressOut` injection).
 4. **RN's own `Modal`, not this library's** — same reasoning as Select: a quick transient overlay,
    not a persistent app dialog with a title/children contract.
-5. **Closed `tone` union** — `default | danger`, resolved from role colours, never a free-form
-   `color` prop.
+5. **Closed `tone` union** — `default | danger`, resolved from role colours, never a free-form `color` prop.
 
 ## Design decisions specific to this module
 
@@ -89,15 +98,37 @@ row size, since an action list's row height isn't a caller-facing choice.
   `Popover`-style module with real anchor measurement would be the place to fix this, not a prop
   added here — the same deferral Tooltip's own docs make for its unmeasured bubble placement.
 
+## Keyboard (web)
+
+Wired to `core/a11y/keyboard` (all no-ops on native). The item list is **one tab stop**: exactly one
+row carries `tabIndex={0}` (`focusItemProps`) and the arrows / Home / End / typeahead move it
+(`useRovingKeys` on the sheet, capture phase). Each row focuses itself when it becomes the active
+one — the tabindex alone only names the tab stop, and `useFocusTrap` needs the focused node to still
+be tabbable or Tab escapes the menu. `useFocusTrap` also restores focus to the trigger on close, and
+`useDismissOnEscape` closes on Escape.
+
+**`useRovingKeys` gets no `onActivate`.** RNW already presses a `menuitem` on Enter, and Space is
+supplied per row by `useSpaceActivation` (RNW's `isValidKeyPress` needs a `button` tag/role, which
+`menuitem` deliberately is not) — passing `onActivate` too would run the item twice.
+
 ## Known gaps
 
 - No measured anchor position (see above) — the sheet always centers, regardless of where the
   trigger sits on screen.
-- No submenu / nested items — v1 is a single flat action list, matching the spec this module was
-  built against.
-- No keyboard/arrow-key navigation between rows (touch-only interaction model, same scope as
-  Select's option list).
+- **No SCREEN-READER focus trap on Android.** Tab is trapped on web (`useFocusTrap`) and the sheet
+  declares `accessibilityViewIsModal`, which iOS VoiceOver honours; Android has no sibling-hiding
+  equivalent and relies on RN's own `<Modal>` surface instead. Same gap `Modal`'s own docs record.
+- No submenu / nested items — v1 is a single flat action list.
+- **Arrowing past the mounted window does not scroll.** `core/list` exposes no imperative handle,
+  so with `items.length >= 15` (the `VirtualList` branch) End can name an item the list has not
+  mounted, and focus stays put. Fixing it needs a `scrollToIndex` on `core/list`.
 
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `openMenu`/`closeMenu` are `useCallback`'d, and the inline `onPress` previously injected into the caller-supplied `trigger` via `cloneElement` on every render is extracted to `handleTriggerPress` (`useCallback`, deps `[trigger, openMenu]`) — `trigger` is a consumer-supplied child (typically this library's own `Button`), so a fresh callback there would defeat its memo. `selectItem` and the per-row `onPress` stay inline: they go to `Pressable`/`Icon` (host elements / primitive props), not a memoized child.
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `openMenu`/`closeMenu` are `useCallback`'d, and the inline `onPress` previously injected into the caller-supplied `trigger` via `cloneElement` on every render is extracted to `handleTriggerPress` (`useCallback`, deps `[trigger, openMenu]`) — `trigger` is a consumer-supplied child (typically this library's own `Button`), so a fresh callback there would defeat its memo. `selectItem` and the per-row `onPress` stay inline: they go to `Pressable`/`Icon` (host elements / primitive props), not a memoized child. The sheet subtree (backdrop + rows) is built only while `open` — a closed menu mounts nothing beyond the trigger. Rows are rendered with a plain `.map()` inside a `ScrollView` (not `FlatList`): action menus are short, and mounting a fresh `VirtualizedList` on the same commit as the modal fade-in was measurable open-time cost (~2× p50 in a Jest open benchmark for a 2-item list) with no windowing benefit at current call sites — `ScrollView` has no such per-open setup and still lets a list taller than the sheet's `maxHeight: 320` scroll, which a bare `.map()` with no scroll container would silently lose. Rows get `bg.sunken` press feedback (`resolveMenuRowPressedBackground`, same non-`bg.hover` reasoning as `RadioGroup`/`Accordion`), measured in `Menu.test.ts`.
+
+## 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/menu/Menu.js

@@ -1,39 +1,84 @@
 "use strict";
 
 /**
- * Menu — a small anchored action list opened from a caller-supplied trigger. Unlike Select (whose
- * open/closed state is a `value`/`onValueChange` pair the caller owns), Menu is self-contained: a
- * transient action list manages its own visibility, closing itself after every dismissal path.
+ * Menu — a small anchored action list opened from a caller-supplied trigger.
  *
- * The trigger is composed via `React.cloneElement` — never `{...rest}` — injecting only `onPress`,
- * chained after any handler the trigger already defined (the same "merge, never clobber" technique
- * Tooltip uses for its child). The dropdown itself is React Native's OWN `Modal`, imported directly
- * from `"react-native"` on purpose: this module must never depend on the library's own `Modal`
- * COMPONENT — this library's own `Modal` (built in parallel elsewhere) is for persistent app
- * dialogs with a title/children contract, not a quick transient overlay — the same distinction
- * Select already draws for its own option list.
+ * The sheet is the menu itself: it carries `accessibilityRole="menu"` over the `menuitem` rows, and
+ * the `accessibilityViewIsModal` / `onAccessibilityEscape` pair `Modal.tsx` establishes — set on the
+ * sheet node itself so the web-portal path (which has no RN `<Modal>`) is modal to assistive tech too.
  *
- * The one deliberate exception is the web portal mechanism: `ModalPortalContext`/`renderWebPortal`
- * are a plain context + a stateless helper with no React-tree footprint of their own (not the
- * `Modal` component), so Menu reads the same ones `Modal.tsx` and `Select.tsx` read to stay
- * consistent once a consumer opts in via `ModalPortalProvider` — see `../modal/ModalPortalContext.ts`.
+ * Motion split, same as this library's own `Modal`: RN `<Modal>`'s native `animationType` owns the
+ * scrim fade (in AND out, with no JS timer, so a selection closes the menu on the same tick it
+ * always did), and the global motion system (`core/motion`) owns the sheet's own scale + lift on
+ * enter. The sheet is centered rather than anchored (see MODULE.md), so it scales from its centre.
  */
 
-import { cloneElement, memo, useCallback, useContext, useState } from "react";
-import { Modal, Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
-import { useReducedMotion } from "../../core/a11y/index.js";
+import { cloneElement, memo, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { Animated, Modal, Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
+import { focusItemProps, useDismissOnEscape, useFocusTrap, useRovingKeys, useSpaceActivation } from "../../core/a11y/keyboard";
+import { useMotion } from "../../core/motion/index.js";
 import { Icon } from "../../core/icon/index.js";
-import { useTheme } from "../../theme/index.js";
+import { VirtualList } from "../../core/list/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { ModalPortalContext } from "../modal/ModalPortalContext.js";
 import { renderWebPortal } from "../modal/renderWebPortal";
-import { MENU_ROW_ICON_SIZE, menuOverlayStructure, menuRowStructure, menuSheetStructure, resolveMenuItemColor } from "./Menu.variants.js";
-
-/** The subset of props Menu reads from / injects into its trigger child. */
+import { MENU_ROW_ICON_SIZE, MENU_ROW_MIN_HEIGHT, menuOverlayStructure, menuRowStructure, menuSheetStructure, resolveMenuItemColor, resolveMenuRowPressedBackground } from "./Menu.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const VIRTUALIZE_THRESHOLD = 15;
 const ICON_STROKE = 2;
-// Decorative dismiss scrim behind the sheet — a design constant, not a role token: it is neither
-// text nor an interactive boundary, so WCAG's contrast minimums don't apply to it.
 const BACKDROP_SCRIM = "#00000099";
+const MenuRow = /*#__PURE__*/memo(function MenuRow({
+  item,
+  index,
+  tabIndex,
+  theme,
+  pressedRowBg,
+  onSelect,
+  testID
+}) {
+  const color = resolveMenuItemColor(theme.colors, item.tone ?? "default");
+  const handlePress = useCallback(() => onSelect(item), [onSelect, item]);
+  const rowRef = useRef(null);
+  const active = tabIndex === 0;
+
+  // The tabindex alone only names the tab stop — focus has to follow the arrows too, or the focus
+  // trap's Tab handler sees a focused row that is no longer tabbable and lets Tab leave the menu.
+  useEffect(() => {
+    if (!active || Platform.OS !== "web") return;
+    rowRef.current?.focus();
+  }, [active]);
+
+  // `menuitem` is not `button`, so RNW never presses on Space — see `core/a11y/keyboard.web.ts`.
+  useSpaceActivation(rowRef, handlePress);
+  const rowStyle = useCallback(({
+    pressed
+  }) => [menuRowStructure(theme), pressed && {
+    backgroundColor: pressedRowBg
+  }], [theme, pressedRowBg]);
+  const labelStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    flex: 1,
+    fontSize: theme.fontSizes.md,
+    color
+  }], [theme, color]);
+  return /*#__PURE__*/_jsxs(Pressable, {
+    ref: rowRef,
+    testID: testID ? `${testID}-item-${index}` : undefined,
+    accessibilityRole: "menuitem",
+    tabIndex: tabIndex,
+    onPress: handlePress,
+    style: rowStyle,
+    children: [item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
+      name: item.icon,
+      size: MENU_ROW_ICON_SIZE,
+      color: color,
+      strokeWidth: ICON_STROKE
+    }), /*#__PURE__*/_jsx(Text, {
+      numberOfLines: 1,
+      style: labelStyle,
+      children: item.label
+    })]
+  });
+});
 export const Menu = /*#__PURE__*/memo(function Menu({
   trigger,
   items,
@@ -41,21 +86,54 @@ export const Menu = /*#__PURE__*/memo(function Menu({
   testID
 }) {
   const theme = useTheme();
-  const reducedMotion = useReducedMotion();
+  const motion = useMotion();
   const portalContainer = useContext(ModalPortalContext);
   const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(0);
+  const sheetRef = useRef(null);
+  const enter = useRef(new Animated.Value(0)).current;
+  const entering = useRef(null);
+  useEffect(() => {
+    entering.current?.stop();
+    if (!open) {
+      enter.setValue(0);
+      return;
+    }
+    if (!motion.enabled) {
+      enter.setValue(1);
+      return;
+    }
+    enter.setValue(0);
+    entering.current = motion.timing(enter, 1, {
+      duration: "fast",
+      easing: "decelerate"
+    });
+    entering.current.start();
+  }, [open, motion, enter]);
+  useEffect(() => () => entering.current?.stop(), []);
   const openMenu = useCallback(() => {
     if (disabled) return;
+    setActiveIndex(0);
     setOpen(true);
   }, [disabled]);
   const closeMenu = useCallback(() => setOpen(false), []);
-  const selectItem = item => {
+  const selectItem = useCallback(item => {
     closeMenu();
     item.onPress();
-  };
+  }, [closeMenu]);
+  const typeaheadLabels = useMemo(() => items.map(item => item.label), [items]);
 
-  // Passed to `trigger` — a consumer-supplied CHILD component (typically this library's own
-  // Button) — via cloneElement, so it is memoized like any other child-bound callback.
+  // Keyboard (web only — every hook below is a no-op on native, see `core/a11y/keyboard.ts`).
+  // No `onActivate`: RNW already presses a `menuitem` on Enter, and each row's own
+  // `useSpaceActivation` owns Space — passing it here would activate the item twice.
+  useDismissOnEscape(open, closeMenu);
+  useFocusTrap(sheetRef, open);
+  useRovingKeys(sheetRef, open, {
+    count: items.length,
+    activeIndex,
+    onActiveIndexChange: setActiveIndex,
+    typeaheadLabels
+  });
   const handleTriggerPress = useCallback(event => {
     trigger.props.onPress?.(event);
     openMenu();
@@ -63,53 +141,78 @@ export const Menu = /*#__PURE__*/memo(function Menu({
   const clonedTrigger = /*#__PURE__*/cloneElement(trigger, {
     onPress: handleTriggerPress
   });
-  const sheet = /*#__PURE__*/_jsxs(_Fragment, {
+  const pressedRowBg = useMemo(() => resolveMenuRowPressedBackground(theme.colors), [theme.colors]);
+  const keyExtractor = useCallback((item, index) => `${item.label}-${index}`, []);
+  const renderItem = useCallback(({
+    item,
+    index
+  }) => /*#__PURE__*/_jsx(MenuRow, {
+    item: item,
+    index: index,
+    tabIndex: focusItemProps(index, activeIndex).tabIndex,
+    theme: theme,
+    pressedRowBg: pressedRowBg,
+    onSelect: selectItem,
+    testID: testID
+  }), [activeIndex, theme, pressedRowBg, selectItem, testID]);
+  const sheetStyle = useMemo(() => [menuSheetStructure(theme), {
+    backgroundColor: theme.colors.bg.surface,
+    transform: [{
+      scale: enter.interpolate({
+        inputRange: [0, 1],
+        outputRange: [motion.transform.pressScale, 1]
+      })
+    }, {
+      translateY: enter.interpolate({
+        inputRange: [0, 1],
+        outputRange: [motion.transform.offsetY, 0]
+      })
+    }]
+  }], [theme, enter, motion.transform.pressScale, motion.transform.offsetY]);
+
+  // Built only while open: a closed Menu must not materialize one element per item on every render
+  // of the screen that hosts it.
+  const sheet = open ? /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx(Pressable, {
       testID: testID ? `${testID}-backdrop` : undefined,
       accessible: false,
-      style: [StyleSheet.absoluteFill, {
-        backgroundColor: BACKDROP_SCRIM
-      }],
+      tabIndex: -1,
+      style: styles.backdrop,
       onPress: closeMenu
     }), /*#__PURE__*/_jsx(View, {
       style: menuOverlayStructure(theme),
       pointerEvents: "box-none",
-      children: /*#__PURE__*/_jsx(View, {
-        style: [menuSheetStructure(theme), {
-          backgroundColor: theme.colors.bg.surface
-        }],
-        children: /*#__PURE__*/_jsx(ScrollView, {
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        ref: sheetRef,
+        testID: testID ? `${testID}-sheet` : undefined
+        // The container role the `menuitem` rows below need, plus the modal semantics every other
+        // overlay in this library gives its panel. Declared HERE, before the portal branch, so the
+        // web-portal path — which renders no RN `<Modal>` at all — inherits them too.
+        ,
+        accessibilityRole: "menu",
+        accessibilityViewIsModal: true,
+        onAccessibilityEscape: closeMenu,
+        style: sheetStyle,
+        children: items.length >= VIRTUALIZE_THRESHOLD ? /*#__PURE__*/_jsx(VirtualList, {
+          data: items,
+          keyExtractor: keyExtractor,
+          renderItem: renderItem,
+          itemHeight: MENU_ROW_MIN_HEIGHT
+        }) : /*#__PURE__*/_jsx(ScrollView, {
           bounces: false,
-          children: items.map((item, index) => {
-            const color = resolveMenuItemColor(theme.colors, item.tone ?? "default");
-            return /*#__PURE__*/_jsxs(Pressable, {
-              testID: testID ? `${testID}-item-${index}` : undefined,
-              accessibilityRole: "menuitem",
-              onPress: () => selectItem(item),
-              style: menuRowStructure(theme),
-              children: [item.icon !== undefined && /*#__PURE__*/_jsx(Icon, {
-                name: item.icon,
-                size: MENU_ROW_ICON_SIZE,
-                color: color,
-                strokeWidth: ICON_STROKE
-              }), /*#__PURE__*/_jsx(Text, {
-                numberOfLines: 1,
-                style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-                  flex: 1,
-                  fontSize: theme.fontSizes.md,
-                  color
-                }],
-                children: item.label
-              })]
-            }, `${item.label}-${index}`);
-          })
+          children: items.map((item, index) => /*#__PURE__*/_jsx(MenuRow, {
+            item: item,
+            index: index,
+            tabIndex: focusItemProps(index, activeIndex).tabIndex,
+            theme: theme,
+            pressedRowBg: pressedRowBg,
+            onSelect: selectItem,
+            testID: testID
+          }, `${item.label}-${index}`))
         })
       })
     })]
-  });
-
-  // Web portal opt-in — see Modal.tsx's identical branch + ModalPortalContext.ts. Every other case
-  // (native, or web with no ModalPortalProvider) renders through RN's own <Modal> below, unchanged.
+  }) : null;
   const menu = Platform.OS === "web" && portalContainer != null ? open ? renderWebPortal(/*#__PURE__*/_jsx(View, {
     style: StyleSheet.absoluteFill,
     pointerEvents: "box-none",
@@ -117,7 +220,7 @@ export const Menu = /*#__PURE__*/memo(function Menu({
   }), portalContainer) : null : /*#__PURE__*/_jsx(Modal, {
     visible: open,
     transparent: true,
-    animationType: reducedMotion ? "none" : "fade",
+    animationType: motion.enabled ? "fade" : "none",
     onRequestClose: closeMenu,
     children: sheet
   });
@@ -125,4 +228,10 @@ export const Menu = /*#__PURE__*/memo(function Menu({
     children: [clonedTrigger, menu]
   });
 });
+const styles = StyleSheet.create({
+  backdrop: {
+    ...StyleSheet.absoluteFill,
+    backgroundColor: BACKDROP_SCRIM
+  }
+});
 //# sourceMappingURL=Menu.js.map

package/lib/module/modules/menu/Menu.variants.js

@@ -39,6 +39,16 @@ export function resolveMenuItemColor(colors, tone) {
   }
 }
 
+/**
+ * A row's background while pressed — `bg.sunken`, not `bg.hover`: same class of fix `Button`'s
+ * "neutral" tone and `RadioGroup`/`Accordion` document (the saturated `hover` mid-tone risks
+ * dropping a tinted label below 4.5:1; the pale `sunken` tint doesn't). One background for every
+ * tone: `default` and `danger` labels are both measured against it in `Menu.test.ts`.
+ */
+export function resolveMenuRowPressedBackground(colors) {
+  return colors.bg.sunken;
+}
+
 /**
  * Structural styles only — layout, padding, radius, border WIDTH. No colours (those are resolved
  * from `RoleColors` and applied inline), so this compiles once per theme identity via the themed

package/lib/module/modules/message-bubble/MODULE.md

@@ -0,0 +1,38 @@
+# message-bubble/
+
+Single chat bubble — `user` (accent) or `assistant` (surface + border). Plain `content` string.
+
+## Motion contract
+
+**No motion at all — this component animates nothing, on any tier.** It is a list cell (`core/motion/
+MODULE.md` rule 5: no per-row motion that runs during scroll), so it renders its final state on its
+first frame, exactly like `ListItem`.
+
+It used to play a decorative-gated `opacity` + `translateY` enter, guarded by an `entered` ref so it
+ran "at most once per mount". That property was true and beside the point: `FlatList` unmounts and
+remounts cells as they leave and re-enter its window, so the ref reset and **every bubble scrolled
+back into view faded in again** — per-row motion, mid-scroll, on the thread a chat screen can least
+afford it. `__tests__/MessageBubble.motion.test.tsx` now pins the absence of that animation.
+
+## Known gap
+
+There is no longer a "new message arrived" reveal. Mounting cannot express it (see above); scoping
+it to genuinely new messages needs an id or timestamp high-water mark the consumer owns, which would
+mean a new prop — not added speculatively.
+
+## Accessibility contract (WCAG)
+
+- **1.3.1** — who sent a turn is otherwise carried only by `alignSelf` and the fill colour
+  (`MessageBubble.variants.ts` `variant` styles), neither of which reaches assistive tech. The
+  accessible label is `"<sender>: <content>"` ("You" / "Assistant"), resolved by
+  `resolveMessageBubbleAccessibility` from the existing `variant` prop — no new prop needed. The
+  visible bubble still renders `content` alone; only the announced name carries the sender.
+
+## Props
+
+| Prop | Type | Default |
+|------|------|---------|
+| `variant` | `user \| assistant` | `assistant` |
+| `content` | `string` | — |
+| `style` | `LayoutStyle` | — |
+| `testID` | `string` | — |