pixelize-native-library 1.0.7 → 1.2.1

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

@@ -1,7 +1,7 @@
 # markdown/ — a dependency-free markdown renderer
 
 `Markdown` parses and renders a markdown string with a small hand-rolled parser — no third-party
-markdown/renderer dependency. Supported: h1–h3, bold, italic, inline code, fenced code blocks
+markdown/renderer dependency. Supported: h1–h6, bold, italic, inline code, fenced code blocks
 (monospace block on a `bg.sunken` fill, no copy button), unordered/ordered lists, links,
 blockquotes, paragraphs. The parser never throws: malformed input degrades to literal text, an
 unclosed fence swallows the rest of the input as code.
@@ -16,7 +16,8 @@ unclosed fence swallows the rest of the input as code.
 | `index.ts` | Public surface: `Markdown`, `MarkdownProps`, `parseMarkdown`, node types. |
 | `__tests__/parseMarkdown.test.ts` | Pure: every block/inline form + malformed-input robustness. |
 | `__tests__/Markdown.test.ts` | Pure: WCAG contrast for text/link/quote roles (all brands × modes). |
-| `__tests__/Markdown.render.test.tsx` | Render: headings, lists, code, link press wiring. |
+| `__tests__/Markdown.render.test.tsx` | Render: headings, lists, code, link press wiring, every heading of a 60-section document reaching the tree (the rotor guard — see Performance), and the block/list-item safety caps (below-cap unchanged, above-cap capped + affordance reveals everything). |
+| `__tests__/Markdown.dom.test.tsx` | Real DOM (`jest.web.config.js`): a `#`/`##`/`###` document renders real `<h1>`/`<h2>`/`<h3>` tags, not three `<h1>`s. |
 
 ## Props
 
@@ -31,8 +32,12 @@ unclosed fence swallows the rest of the input as code.
 
 Body/list text `fg.default`, blockquote `fg.muted` behind a `border.default` left rule
 (decorative, Divider's reasoning), code on `bg.sunken`, links `accent.text` + underline
-(`link` a11y role), headings `2xl bold` / `xl semibold` / `lg semibold` with the `header` a11y
-role. Monospace is the platform face (Menlo/monospace) — the token layer has no mono family.
+(`link` a11y role), headings `2xl bold` (h1) / `xl semibold` (h2) / `lg semibold` (h3+) with the
+`header` a11y role. **`aria-level` carries the real `#`-count (1–6), no longer clamped to 3** — a
+`react-native-web` heading with no `aria-level` renders `<h1>` regardless of role, so every heading
+used to collapse to the same DOM tag (see `core/heading/MODULE.md`). Levels 4–6 share level 3's
+type size — the document's *structure* is what the level communicates below `lg`. Monospace is the
+platform face (Menlo/monospace) — the token layer has no mono family.
 
 ## Known gaps
 
@@ -41,4 +46,33 @@ role. Monospace is the platform face (Menlo/monospace) — the token layer has n
 
 ## Performance
 
-Wrapped in `React.memo`; the parse is `useMemo`'d on `content`.
+The parse is `useMemo`'d on `content`; the **render tree** is the other half of the cost, so:
+
+- Each block renders through `MarkdownBlock`, a `React.memo`'d component. Its props (`theme`,
+  `colors`, `onLinkPress`, and the block node itself) are stable while `content` is unchanged, so a
+  parent re-render re-renders no block.
+- `colors` is `useMemo`'d on `theme.colors`; the root style array is `useMemo`'d on `(theme, style)`.
+- **A document is never virtualized.** Every block renders, always — a plain `.map()`, no
+  `VirtualList`, no block-count threshold. Two reasons, and the first is not a performance
+  trade-off:
+  1. **The heading outline is the document's navigation.** A screen reader's rotor lists the
+     `accessibilityRole="header"` nodes that are *in the tree*; windowing leaves ~10 blocks mounted,
+     so a 60-heading document offered a rotor a handful of entries and no way to reach the rest
+     (WCAG 2.4.1). Unlike a list of records, a document's own structure is the affordance.
+  2. `Markdown` is normally embedded in a caller's `ScrollView`, where a nested VirtualizedList is
+     an error in React Native regardless.
+  The cost is bounded by the content: blocks come from parsing one `content` string, which is a
+  chat message or a notes body, not an unbounded dataset. If a caller ever does need a virtualized
+  document, that is a different component with a different accessibility contract.
+- **Safety caps exist for pathological/misuse input only — they do NOT contradict the above.**
+  `MAX_RENDERED_BLOCKS` (300) and `MAX_LIST_ITEMS` (50, per list block, independent of the block
+  cap) bound a degenerate `content` string; below either cap a document/list renders exactly as
+  before. Above it, a `Button` ("Show full document" / "+N more items") mounts the real, full tree
+  on press — never a re-introduction of windowing, so the rotor contract holds once expanded.
+- Links render through a memo'd `MarkdownLink` so no per-link closure is rebuilt each render.
+
+## Modernization (v1.0.7)
+
+- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
+
+- **Round 2 visual** — radii retarget (`radii.md`/`lg`/`xl`/`full`), `borderCurve: continuous` on md+ corners; floating surfaces wire platform elevation/highlight where applicable.

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

@@ -1,8 +1,17 @@
 "use strict";
 
-import { Fragment, memo, useMemo } from "react";
+/**
+ * A markdown document is rendered whole, never virtualized: the heading outline is what a screen
+ * reader's rotor navigates, and windowing would expose only the ~10 blocks currently on screen
+ * (WCAG 2.4.1). It is also normally embedded in a caller's ScrollView, where a nested
+ * VirtualizedList is an error in its own right.
+ */
+
+import { Fragment, memo, useCallback, useMemo, useState } from "react";
 import { Platform, StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
+import { Button } from "../button/index.js";
+import { HeadingText } from "../../core/heading/index.js";
+import { useTheme } from "../../theme/hooks.js";
 import { markdownBlockquoteStructure, markdownCodeBlockStructure, markdownListRowStructure, markdownListStructure, markdownStructure, resolveMarkdownColors, resolveMarkdownHeading } from "./Markdown.variants.js";
 import { parseMarkdown } from "./parseMarkdown.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -10,6 +19,33 @@ const MONO_FONT = Platform.select({
   ios: "Menlo",
   default: "monospace"
 });
+
+/**
+ * Safety caps for pathological/misuse input, not windowing (see MODULE.md "Performance") — below
+ * these numbers a document renders exactly as before; above, an affordance mounts the real, full
+ * tree on press, so the WCAG 2.4.1 rotor contract holds once expanded.
+ */
+// Comfortably covers long-form docs/notes (the existing 60-heading test is a fifth of it) while
+// bounding a document of thousands of blocks.
+export const MAX_RENDERED_BLOCKS = 300;
+// Covers realistic checklists/notes lists; bounds a single oversized list regardless of doc length.
+export const MAX_LIST_ITEMS = 50;
+const MarkdownLink = /*#__PURE__*/memo(function MarkdownLink({
+  content,
+  url,
+  color,
+  onLinkPress
+}) {
+  const handlePress = useCallback(() => onLinkPress?.(url), [onLinkPress, url]);
+  return /*#__PURE__*/_jsx(Text, {
+    accessibilityRole: "link",
+    onPress: onLinkPress === undefined ? undefined : handlePress,
+    style: [styles.link, {
+      color
+    }],
+    children: content
+  });
+});
 function renderInline(nodes, theme, colors, onLinkPress) {
   return nodes.map((node, index) => {
     switch (node.type) {
@@ -32,13 +68,11 @@ function renderInline(nodes, theme, colors, onLinkPress) {
           children: node.content
         }, index);
       case "link":
-        return /*#__PURE__*/_jsx(Text, {
-          accessibilityRole: "link",
-          onPress: onLinkPress === undefined ? undefined : () => onLinkPress(node.url),
-          style: [styles.link, {
-            color: colors.link
-          }],
-          children: node.content
+        return /*#__PURE__*/_jsx(MarkdownLink, {
+          content: node.content,
+          url: node.url,
+          color: colors.link,
+          onLinkPress: onLinkPress
         }, index);
       default:
         return /*#__PURE__*/_jsx(Fragment, {
@@ -47,19 +81,28 @@ function renderInline(nodes, theme, colors, onLinkPress) {
     }
   });
 }
-function renderBlock(block, index, theme, colors, onLinkPress) {
+const MarkdownBlock = /*#__PURE__*/memo(function MarkdownBlock({
+  block,
+  theme,
+  colors,
+  onLinkPress
+}) {
+  // Called unconditionally (rules of hooks) though only the "list" case below reads it.
+  const [itemsExpanded, setItemsExpanded] = useState(false);
+  const expandItems = useCallback(() => setItemsExpanded(true), []);
   switch (block.type) {
     case "heading":
       {
         const spec = resolveMarkdownHeading(theme, block.level);
-        return /*#__PURE__*/_jsx(Text, {
+        return /*#__PURE__*/_jsx(HeadingText, {
           accessibilityRole: "header",
+          "aria-level": block.level,
           style: [theme.fontStyleForWeight(theme.fontWeights[spec.fontWeight]), {
             fontSize: spec.fontSize,
             color: colors.heading
           }],
           children: renderInline(block.children, theme, colors, onLinkPress)
-        }, index);
+        });
       }
     case "code-block":
       return /*#__PURE__*/_jsx(View, {
@@ -73,7 +116,7 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
           }],
           children: block.content
         })
-      }, index);
+      });
     case "blockquote":
       return /*#__PURE__*/_jsx(View, {
         style: [markdownBlockquoteStructure(theme), {
@@ -86,27 +129,37 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
           }],
           children: renderInline(block.children, theme, colors, onLinkPress)
         })
-      }, index);
+      });
     case "list":
-      return /*#__PURE__*/_jsx(View, {
-        style: markdownListStructure(theme),
-        children: block.items.map((item, itemIndex) => /*#__PURE__*/_jsxs(View, {
-          style: markdownListRowStructure(theme),
-          children: [/*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-              fontSize: theme.fontSizes.md,
-              color: colors.listMarker
-            }],
-            children: block.ordered ? `${itemIndex + 1}.` : "•"
-          }), /*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.regular), styles.listContent, {
-              fontSize: theme.fontSizes.md,
-              color: colors.text
-            }],
-            children: renderInline(item, theme, colors, onLinkPress)
+      {
+        const visibleItems = itemsExpanded || block.items.length <= MAX_LIST_ITEMS ? block.items : block.items.slice(0, MAX_LIST_ITEMS);
+        const hiddenCount = block.items.length - visibleItems.length;
+        return /*#__PURE__*/_jsxs(View, {
+          style: markdownListStructure(theme),
+          children: [visibleItems.map((item, itemIndex) => /*#__PURE__*/_jsxs(View, {
+            style: markdownListRowStructure(theme),
+            children: [/*#__PURE__*/_jsx(Text, {
+              style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+                fontSize: theme.fontSizes.md,
+                color: colors.listMarker
+              }],
+              children: block.ordered ? `${itemIndex + 1}.` : "•"
+            }), /*#__PURE__*/_jsx(Text, {
+              style: [theme.fontStyleForWeight(theme.fontWeights.regular), styles.listContent, {
+                fontSize: theme.fontSizes.md,
+                color: colors.text
+              }],
+              children: renderInline(item, theme, colors, onLinkPress)
+            })]
+          }, itemIndex)), hiddenCount > 0 && /*#__PURE__*/_jsx(Button, {
+            variant: "link",
+            tone: "neutral",
+            size: "sm",
+            label: `+${hiddenCount} more items`,
+            onPress: expandItems
           })]
-        }, itemIndex))
-      }, index);
+        });
+      }
     default:
       return /*#__PURE__*/_jsx(Text, {
         style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
@@ -114,9 +167,9 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
           color: colors.text
         }],
         children: renderInline(block.children, theme, colors, onLinkPress)
-      }, index);
+      });
   }
-}
+});
 export const Markdown = /*#__PURE__*/memo(function Markdown({
   content,
   onLinkPress,
@@ -124,12 +177,28 @@ export const Markdown = /*#__PURE__*/memo(function Markdown({
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveMarkdownColors(theme.colors);
+  const colors = useMemo(() => resolveMarkdownColors(theme.colors), [theme.colors]);
   const blocks = useMemo(() => parseMarkdown(content), [content]);
-  return /*#__PURE__*/_jsx(View, {
+  const rootStyle = useMemo(() => [markdownStructure(theme), style], [theme, style]);
+  const [blocksExpanded, setBlocksExpanded] = useState(false);
+  const expandBlocks = useCallback(() => setBlocksExpanded(true), []);
+  const visibleBlocks = blocksExpanded || blocks.length <= MAX_RENDERED_BLOCKS ? blocks : blocks.slice(0, MAX_RENDERED_BLOCKS);
+  const hiddenBlockCount = blocks.length - visibleBlocks.length;
+  return /*#__PURE__*/_jsxs(View, {
     testID: testID,
-    style: [markdownStructure(theme), style],
-    children: blocks.map((block, index) => renderBlock(block, index, theme, colors, onLinkPress))
+    style: rootStyle,
+    children: [visibleBlocks.map((block, index) => /*#__PURE__*/_jsx(MarkdownBlock, {
+      block: block,
+      theme: theme,
+      colors: colors,
+      onLinkPress: onLinkPress
+    }, `block-${index}-${block.type}`)), hiddenBlockCount > 0 && /*#__PURE__*/_jsx(Button, {
+      variant: "outline",
+      tone: "neutral",
+      size: "sm",
+      label: `Show full document (${hiddenBlockCount} more)`,
+      onPress: expandBlocks
+    })]
   });
 });
 const styles = StyleSheet.create({

package/lib/module/modules/markdown/Markdown.variants.js

@@ -18,6 +18,11 @@ export function resolveMarkdownColors(colors) {
     listMarker: colors.fg.muted
   };
 }
+/**
+ * SIZE only — `h4`–`h6` deliberately share `h3`'s size while keeping their own `aria-level`. The
+ * document's structure is what the heading level carries; three more type sizes below `lg` would
+ * be smaller than body text.
+ */
 export function resolveMarkdownHeading(theme, level) {
   switch (level) {
     case 1:
@@ -30,7 +35,7 @@ export function resolveMarkdownHeading(theme, level) {
         fontSize: theme.fontSizes.xl,
         fontWeight: "semibold"
       };
-    case 3:
+    default:
       return {
         fontSize: theme.fontSizes.lg,
         fontWeight: "semibold"
@@ -44,7 +49,8 @@ export const markdownStructure = createThemedVariants(theme => ({
 }));
 export const markdownCodeBlockStructure = createThemedVariants(theme => ({
   base: {
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     padding: theme.space[3]
   }
 }));

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

@@ -2,11 +2,11 @@
 
 /**
  * A small hand-rolled markdown parser — no dependencies, never throws. Supports the subset the
- * renderer draws: h1–h3, bold, italic, inline code, fenced code blocks, unordered/ordered lists,
+ * 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,3})\s+(.*)$/;
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
 const UNORDERED_RE = /^\s*[-*+]\s+(.*)$/;
 const ORDERED_RE = /^\s*\d+[.)]\s+(.*)$/;
 const BLOCKQUOTE_RE = /^\s*>\s?(.*)$/;
@@ -84,7 +84,7 @@ function parseBlocks(content) {
     const heading = HEADING_RE.exec(line);
     if (heading !== null) {
       flushParagraph();
-      const level = Math.min((heading[1] ?? "#").length, 3);
+      const level = (heading[1] ?? "#").length;
       blocks.push({
         type: "heading",
         level,

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,8 @@ 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`).
+  Row presses use `usePressState` (scale + state-layer overlay).
 - 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 +77,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 +99,47 @@ 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`.
+
+## Round 5 motion
+
+Dropped the ad hoc reanimated `FadeInDown` layer (per-row entrance, and the sheet's own former
+entrance-only Reanimated bounce). `enter` (`core/motion`) now drives the sheet's scale/lift/opacity
+AND the backdrop's fade together, and the web-portal path (no RN `<Modal>`) stays `mounted` through
+a real timed exit instead of unmounting instantly — the RNModal path is unaffected, still gated on
+`open` directly, since RN's own `animationType` already owns that surface's exit. `BACKDROP_SCRIM`'s
+opacity now comes from the shared `MOTION_TRANSFORM.scrimOpacity` (previously a mismatched `0x99`
+against Modal/Drawer/BottomSheet's `0x80`).
+
+## 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.