pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/core/MODULE.md

@@ -4,9 +4,13 @@ Cross-cutting mechanism every module imports. No feature logic, no components.
 
 | Folder | Purpose | Docs |
 |--------|---------|------|
-| `style/` | `LayoutStyle` + the variant resolver (below) | this file |
-| `icon/` | shared lucide icon registry (`IconName`, `Icon`) — hoisted out of `modules/button/` so every future module reuses one registry instead of re-declaring its own. Grows one glyph at a time as new modules need them (latest: `filter`, added for `filter-sheet`) — see `icon/MODULE.md`. | `icon/MODULE.md` |
+| `style/` | `LayoutStyle` + the variant resolver (below) + `sx()` (spacing/flex shorthand, below) — published as `pixelize-native-library/style` | this file |
+| `icon/` | shared lucide icon registry (`IconName`, `Icon`; 56 glyphs) — hoisted out of `modules/button/` so every one of the 39 shipped modules reuses one registry instead of re-declaring its own | `icon/MODULE.md` |
 | `a11y/` | shared accessibility hooks (`useReducedMotion`) — hoisted out of `modules/button/` for the same reason | `a11y/MODULE.md` |
+| `device/` | the `low \| mid \| high` device tier every motion and list-window decision reads | `device/MODULE.md` |
+| `motion/` | the single global animation gate (`useMotion`, `config.ts`, the preset hooks) | `motion/MODULE.md` |
+| `list/` | `VirtualList` / `VirtualSectionList` — the one windowed list every list-bearing module renders through (FlashList when the peer is installed, FlatList otherwise) | this file |
+| `heading/` | `HeadingText`/`HeadingView` (typed `aria-level`) + `HEADING_LEVEL` — the fixed level every `accessibilityRole="header"` site needs so `react-native-web` doesn't render it as `<h1>` | `heading/MODULE.md` |
 
 ## Escape-hatch doctrine
 
@@ -15,12 +19,11 @@ size** a component without being able to **restyle** it — a component whose ap
 override is a component we can never change.
 
 The narrowness is measured, not assumed. Across 906 real library usages in 4 web apps: `style=` **0**,
-`className=` **1** (and it was dead code), `sx=` **16** — a 1.9% escape hatch. Width/height was
-**13.9%**, and every one of those was a *declared prop*. Consumers need sizing, not restyling.
+`className=` **1** (dead code), `sx=` **16** — a 1.9% escape hatch. Width/height was **13.9%**, and
+every one of those was a *declared prop*. Consumers need sizing, not restyling.
 
 So `style` is typed `LayoutStyle`: margin, width/height, flex, alignSelf. `Pick`, never `Omit` — an
-`Omit` would silently admit each key React Native adds to `ViewStyle` on a version bump, decaying the
-guarantee with no change to our code.
+`Omit` would silently admit each key React Native adds to `ViewStyle` on a version bump.
 
 The escape hatch that actually matters on RN is **`useThemeColors()` returning resolved values** —
 `placeholderTextColor`, `android_ripple`, SVG `fill`, and React Navigation chrome accept no token
@@ -28,20 +31,18 @@ object. Reach for that, never for a style prop.
 
 ## Containment invariants
 
-1. **`style` appears exactly once** — on the outermost node, **last** in the array, so layout wins.
+1. **`style` appears exactly once** — outermost node, **last** in the array, so layout wins.
 2. **No `{...rest}`. Ever.** A rest spread re-opens every prop the allowlist just closed.
 3. **Internals never receive consumer style** — no `labelStyle`, no `iconStyle`, no `slotProps`.
 4. **Icons take a name, not a node** — `icon?: IconName`, so an app cannot inject arbitrary UI.
-5. **Colour is never a prop; tone is** — `tone="danger"`, never `color="#a00"`. Appearance is a
-   closed union (`variant` / `size` / `tone`).
+5. **Colour is never a prop; tone is** — `tone="danger"`, never `color="#a00"`.
 
 **The one exception:** a component wrapping a native primitive (`TextInput`) may expose
-`containerStyle?: LayoutStyle` for the outer box only — the primitive needs its own layout box.
-Never `inputStyle`.
+`containerStyle?: LayoutStyle` for the outer box only. Never `inputStyle`.
 
 ## Variant resolver
 
-In-house, zero dependency — this file is why NativeWind / Unistyles / Tamagui were rejected.
+In-house, zero dependency — this is why NativeWind / Unistyles / Tamagui were rejected.
 
 ```ts
 const buttonVariants = createThemedVariants((theme: Theme) => ({
@@ -51,21 +52,15 @@ const buttonVariants = createThemedVariants((theme: Theme) => ({
     size: { sm: { height: 32 }, md: { height: 40 } },
   },
   defaultVariants: { variant: "solid", size: "md" },
-  compoundVariants: [{ when: { variant: "outline", size: "sm" }, style: { borderWidth: 2 } }],
 }));
 
 // The prop type is DERIVED — adding a variant above widens it with no second declaration.
 type ButtonProps = VariantProps<typeof buttonVariants> & { style?: LayoutStyle };
-
-const Button = ({ variant, size, style }: ButtonProps) => {
-  const theme = useTheme();
-  return <Pressable style={[buttonVariants(theme, { variant, size }), style]} />;
-};
 ```
 
-Resolution order is `base` → variant groups **in config order** → matching compounds, so a later
-group overrides an earlier one and a compound overrides both. Consumer `style` is appended by the
-component (invariant 1) — the resolver never takes it, so it can never leak to an internal node.
+Resolution order is `base` → variant groups **in config order** → matching compounds. Consumer
+`style` is appended by the component (invariant 1) — the resolver never takes it, so it can never
+leak to an internal node.
 
 | Export | Output |
 |--------|--------|
@@ -73,22 +68,120 @@ component (invariant 1) — the resolver never takes it, so it can never leak to
 | `createTextVariants` / `createThemedTextVariants` | `StyleProp<TextStyle>` |
 | `variantFactory<S>()` / `themedVariantFactory<S>()` | bind another style kind (e.g. `ImageStyle`) |
 
-The factories are curried because TypeScript has no partial type-argument inference: a single
-`createVariants<S, V>` would force callers to spell out `V` just to pick a style kind. Currying fixes
-`S` and leaves `V` inferred from the config literal — which is also what keeps style literals like
-`flexDirection: "row"` from widening to `string`.
+The factories are curried (TS has no partial type-argument inference) — fixes `S`, leaves `V` inferred.
+
+**Caching:** static configs (`createVariants`) flatten to one named sheet, registered in
+`StyleSheet.create` **eagerly at module load**. Themed configs (`createThemedVariants`) can't do
+that — theme-dependent values change with brand/mode — so the sheet compiles on **first use per
+theme** and is cached in a `WeakMap` keyed by theme **identity**. This requires the provider to hand
+out a stable theme object per (brand, mode); a theme rebuilt every render would recompile every sheet
+every render.
 
-### Caching strategy
+## `sx()` — spacing/flex shorthand for app screens
 
-Styles must be registered once, not rebuilt per render.
+Orthogonal to the escape-hatch doctrine above (which governs what a **consumer app can pass into a
+library component**). `sx()` is the opposite direction: a plain function an app (or internal
+component) calls to **build its own `ViewStyle`** without hand-writing padding/margin/gap numbers.
 
-- **Static** (`createVariants`): the config is flattened to one named sheet and passed to
-  `StyleSheet.create` **eagerly at module load**. Resolution then only picks entries out of it.
-- **Themed** (`createThemedVariants`): theme-dependent values *cannot* live in a module-level
-  `StyleSheet.create` — they change with brand and mode. The sheet is compiled on **first use per
-  theme** and cached in a `WeakMap` keyed by theme **identity**: registered once per theme, never per
-  render, and a retired theme's sheet is garbage-collectable.
-- **This requires the provider to hand out a stable theme object per (brand, mode).** A theme rebuilt
-  every render would recompile every sheet every render — correct output, silently terrible perf.
+```ts
+import { sx } from "pixelize-native-library/style";
+
+<View style={sx({ row: true, gap: 2, px: 4, align: "center" })}>
+```
 
-Each call returns a fresh array of cached style objects; RN diffs the array cheaply.
+Deliberately narrow — spacing (`p`/`m`/`gap` families) and flex (`row`, `wrap`, `align`, `justify`,
+`center`, `flex`/`grow`/`shrink`/`self`) only. No color, no typography, no borders — those stay on
+`useThemeColors()` and the variant resolver above.
+
+`p`/`m`/`gap` (and directional variants) take an `SxSpaceToken`, an 8-step subset (0–32dp) of the
+full 17-step `SpaceToken` scale, curated to real spacing use — sizing (avatar/icon dimensions) is a
+different scale on purpose. Call it inline for a one-off, or hoist into `StyleSheet.create`/`useMemo`
+for anything reused or passed to a `React.memo`'d child — a fresh `sx()` result every render defeats
+that child's memoization.
+
+**Frozen in dev** (`__DEV__` only, zero cost in prod): a hoisted `sx()` result is a *shared* object,
+so `styles.header.gap = 4` would silently corrupt it for every caller — freezing catches that early.
+Spreading (`{ ...sx({...}), extra: 1 }`) is unaffected — spread always produces a fresh object.
+
+## `list/` — VirtualList
+
+One windowed list for all 15 list-bearing modules. Device-tier window sizing (`core/device`),
+FlashList when the optional peer resolves, FlatList otherwise. `resolveFlashList()` returns `null`
+under Jest by design, so **only the FlatList branch is test-coverable** — the FlashList branch is
+asserted by nothing except its tier→`drawDistance` mapping
+(`__tests__/VirtualList.tuning.test.ts`).
+
+**The two branches do not take the same props.** Verified against `@shopify/flash-list@2.3.2`:
+`getItemLayout`, `initialNumToRender`, `maxToRenderPerBatch` and `updateCellsBatchingPeriod` have
+**zero** occurrences in its dist — forwarding them (as this file did, behind a
+`ComponentType<FlatListProps<T>>` cast) made every module's tier tuning and every hand-computed
+`getItemLayout` inert for consumers who install the peer. v2's one windowing knob is
+`drawDistance` (dp beyond the viewport; its own default is 250), so the tier maps to that instead,
+and `getItemLayout` is not passed at all — it has no meaning there. The FlatList branch keeps the
+five-prop tuning unchanged. FlashList also never passes `separators`, so `renderItem` goes through a
+memoized adapter rather than a cast.
+
+`resolveFlashList()` runs **once at module scope**. It used to `require()` inside a try/catch on
+every render, constructing and catching a module-resolution error per render per mounted list
+whenever the optional peer was absent.
+
+**The prop surface is a curated allowlist, never `{...rest}`.** `core/list` is internal, so it is a
+wider surface than a public module's — but the width is deliberate, and each entry is a prop a
+module legitimately needs: `ListHeaderComponent` / `ListFooterComponent` / `ListEmptyComponent`,
+`stickyHeaderIndices`, `contentContainerStyle`, `numColumns`, `keyboardShouldPersistTaps`,
+`itemHeight` / `getItemLayout`, and `accessibilityRole` / `accessibilityLabel` / `accessibilityHint`.
+
+A prop missing from this interface does not make a module do without it — it makes the module
+re-express it locally, usually wrongly. `data-table` had no `ListHeaderComponent`, so "sticky" was
+re-expressed as *position*: with `stickyHeader={false}` the column header rendered **after** every
+row, and a screen reader read N rows before the labels naming them (WCAG 1.3.2). Widen this
+interface rather than working around it in a module.
+
+- **`accessibilityRole` defaults to `"list"`** so every consumer inherits it instead of each adding
+  its own — the role was previously absent library-wide. Consumers that are not lists override it
+  (a menu surface passes `"menu"`).
+- **`keyboardShouldPersistTaps`** is required by any list under a focused text field, or the first
+  row tap is swallowed as a keyboard dismiss (WCAG 2.1.1). `"handled"` is right when dismissing on
+  a background tap is *wanted* (`combobox`, in a sheet); `"always"` when the list's own lifetime is
+  bound to the keyboard (`rich-text-editor`'s mention dropdown) — see each module's MODULE.md.
+- **`itemHeight` is for uniform rows only.** It derives a `getItemLayout` whose offsets are exact
+  only if every row is that tall; variable rows must omit it (wrong offsets scroll to the wrong
+  place, and OS font scaling makes any guess worse — `timeline`, `markdown`, `more-items`). Pass
+  `getItemLayout` directly when the offsets are exact but not uniform — `data-table` does, to
+  account for the header cell sitting above row 0.
+- **Prop memoization is mandatory**, not a style preference: FlashList memoizes on prop identity, so
+  the derived `getItemLayout` is `useMemo`'d here and every array/object/callback a module passes in
+  must be too, or the child's `React.memo` is silently defeated.
+- **FlashList v2 removed `estimatedItemSize` / `estimatedListSize` / `estimatedFirstItemOffset` /
+  `onBlankArea` / `disableAutoLayout`** — it auto-sizes. Do not reintroduce them.
+
+| Test | Covers |
+|------|--------|
+| `__tests__/VirtualList.props.test.tsx` | Header/footer/empty slots render in the right order; sticky/content-style/columns forwarding; the default `"list"` role and its override; `itemHeight` → `getItemLayout`, explicit `getItemLayout` winning, and its referential stability. |
+| `__tests__/VirtualList.keyboard.test.tsx` | `keyboardShouldPersistTaps` forwarded verbatim, RN's own default when omitted. |
+| `__tests__/VirtualList.tuning.test.ts` | The tier → `drawDistance` mapping — the only assertable part of the FlashList branch. |
+| `__tests__/VirtualSectionList.sections.test.tsx` | The three flattening contracts below. |
+| `__tests__/VirtualSectionList.perf.test.tsx` | Mounted rows stay bounded for a 10k dataset. |
+
+### VirtualSectionList
+
+Flattens `sections` into one windowed list. Three contracts, each of which was a bug found in audit
+and is now covered by `__tests__/VirtualSectionList.sections.test.tsx`:
+
+1. **An empty section keeps its header.** `sections.flatMap(s => s.data.map(…))` emitted nothing for
+   a section with no rows, so a titled section silently vanished. Empty sections now flatten to a
+   header-only row (`item === undefined`).
+2. **One header per section, keyed on position, not identity.** The header used to also fire when an
+   item was *reference-equal* to its section's first item, so `[a, b, a]` emitted two headers. It is
+   `index === 0` and nothing else.
+3. **Header-bearing rows are taller.** A single `itemHeight` described both kinds of row. Exact
+   offsets need `sectionHeaderHeight` too; given both, `getItemLayout` is a prefix sum over the
+   flattened rows. Given only `itemHeight`, **no** `getItemLayout` is passed — measuring is correct,
+   guessing is not. `modules/section-list` currently passes only `itemHeight` and so measures; it
+   can opt back into exact offsets by passing its header height.
+
+## 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/core/a11y/MODULE.md

@@ -8,15 +8,138 @@ once instead of each re-implementing the same hook.
 
 | File | Role |
 |------|------|
-| `index.ts` | `useReducedMotion()` — WCAG 2.3.3. |
+| `index.ts` | `useReducedMotion()` — WCAG 2.3.3. `useAnnounce()` — WCAG 4.1.3. |
+| `announce.ts` / `announce.web.ts` | `useAnnouncer()` — the platform's "say this now" primitive behind `useAnnounce`. |
+| `keyboard.ts` / `keyboard.web.ts` | Physical-keyboard interaction — WCAG 2.1.1 / 2.4.3. Native file is all no-ops. |
+| `labels.ts` | Accessibility-label phrasings that must read identically everywhere the same action appears (WCAG 3.2.4) — currently `removeAccessibilityLabel()`. |
 
-## Pattern
+**Internal only.** Nothing here is a package subpath export (`package.json` `exports` is generated
+from `src/modules/` alone) — these are helpers modules import, never part of the public surface.
+
+## Platform pairs (`announce`, `keyboard`)
+
+**Why `.ts` / `.web.ts`, not `Platform.OS`.** Metro resolves the `.web.ts` file only for a web
+bundle, so the DOM code never enters the native graph; a `Platform.OS` branch would ship it. Jest's
+`react-native` preset has no `web` platform, so a bare `../keyboard` import always resolves the
+native file — the web half is tested either by importing `../keyboard.web` explicitly
+(`keyboard.web.test.ts`) or by the jsdom project, whose `moduleFileExtensions` put `web.ts` first
+(`*.dom.test.tsx` under `jest.web.config.js`).
+
+**DOM types are module-local.** `tsconfig` sets `"lib": ["ESNext"]`, so `document`/`HTMLElement`/
+`KeyboardEvent` don't exist as types. Each `.web.ts` declares a small structural surface plus
+`declare const document` — both erase at emit. **Never augment `react-native`'s types instead**: that
+ships through `lib/typescript/**` and makes `onKeyDown` look valid on native for every consumer.
+
+## Patterns
 
 `useReducedMotion()` returns the live OS reduce-motion setting (initial async read +
 `reduceMotionChanged` subscription). A module uses it to zero out an animation's duration, never to
 skip the animation's *effect* (state must still change, just without the transition).
 
+**One module-level store, read through `useSyncExternalStore`.** The probe and the native
+`reduceMotionChanged` listener are opened by the *first* subscriber and closed when the last one
+leaves — hook instances are store reads, not subscriptions of their own. It used to open both per
+mount, so ten `<Button>`s cost 20 listeners and 20 async bridge round-trips. `useMotion()` therefore
+costs one read: it resolves the tier through `resolveDeviceTier(reduced)` rather than calling
+`useDeviceTier()`, which would read the same store a second time.
+
+**It seeds `true`, not `false`.** `AccessibilityInfo.isReduceMotionEnabled()` resolves after the
+first commit *and* after the first effect pass, so a `false` seed reports "motion is fine" for that
+window and every correctly-written gate in the library runs anyway (WCAG 2.3.3). The last OS answer
+is cached per process, so only the very first mount in an app run pays the pessimistic seed —
+without that cache, every later mount would lose its enter animation for a user who never asked for
+less motion. `resetReducedMotionCache()` is test-only; it also invalidates a probe still in flight,
+so a promise from a previous suite cannot land in the next one.
+
+`useAnnounce(message)` announces when `message` becomes present or changes — never on every render,
+and never twice for the same string. `undefined` means "nothing to announce".
+
+**Why it exists:** `accessibilityLiveRegion` is an **Android-only** RN prop, so a status message
+relying on it alone is announced by nothing on iOS. The imperative call reaches VoiceOver and
+TalkBack alike — the mechanism `Toast.show()` established.
+
+**The rule that comes with it:** a caller must NOT also put `accessibilityLiveRegion` on the message
+it renders, or Android announces twice. Either use this hook and drop the live region (`input`,
+`form-field`, `file-upload`, `toast`), or keep the live region gated to
+`Platform.OS === "android"` and don't call this hook (`combobox`'s empty state).
+
+## Announcing (`announce.ts` / `announce.web.ts`)
+
+The transition rule ("changed, and not `undefined`") stays in `useAnnounce` for **both** platforms;
+`useAnnouncer()` supplies only the primitive that speaks, so the two cannot drift.
+
+**`react-native-web@0.21.2` ships `announceForAccessibility` as an empty function body**
+(`dist/exports/AccessibilityInfo/index.js`), so every WCAG 4.1.3 status message in the library was
+silent on web. The web primitive is one shared ARIA live region; four details make it *speak*:
+
+- **`aria-live="polite"`** (+ `role="status"`), never `assertive` — nothing here earns interrupting
+  the user mid-sentence.
+- **In the document, empty, before the text lands** — the fill is deferred one task. A node inserted
+  with its text already in it gives the reader nothing to diff and is routinely never announced.
+- **Two regions alternate.** Re-writing the identical string to one node is not a DOM mutation, so a
+  repeat would be silent — and `useAnnounce` re-announces a message that cleared and came back.
+- **Visually hidden = the clip technique.** `display:none`/`visibility:hidden` drop the node out of
+  the accessibility tree, which is the whole point of the node.
+
+One region per document, retained by the first `useAnnouncer()` and released by the last (the
+`useReducedMotion` store's shape). **Teardown is deferred a task on purpose:** StrictMode runs
+mount → unmount → mount, and removing the region on that middle cleanup would discard the fill the
+first mount just queued, while the second mount (correctly) does not re-announce.
+
+Tested in jsdom against real `react-native-web` (`__tests__/announce.dom.test.tsx`), which proves
+the DOM is shaped right. **Only a real VoiceOver/NVDA/TalkBack pass proves it is spoken.**
+
+## Keyboard (`keyboard.ts` / `keyboard.web.ts`)
+
+Imported directly (`core/a11y/keyboard`), not through `index.ts`. Five exports:
+
+| Export | What it does |
+|--------|--------------|
+| `useDismissOnEscape(active, onDismiss)` | Capture-phase `keydown` on `document`; Escape → `stopPropagation()` + dismiss. |
+| `useFocusTrap(ref, active)` | Focuses the first tabbable, cycles Tab/Shift+Tab, **restores focus on deactivate**. |
+| `useRovingKeys(ref, active, options)` | Capture-phase `keydown` on the container: arrows per `orientation`, Home/End, Enter/Space, optional typeahead. |
+| `useSpaceActivation(ref, onActivate, active?)` | Makes **Space** activate a non-`button` role. |
+| `focusItemProps(index, activeIndex)` | `{ tabIndex: 0 \| -1 }` — pure, real on both platforms. |
+
+**Why `useSpaceActivation` is a ref hook, not a props object.** `onKeyDown` is in no RN type and
+`{...rest}` is lint-banned, so a returned props bag cannot reach a `Pressable` at all. RNW's
+`PressResponder.isValidKeyPress` is `Enter || (Space && isButtonish)`, and `isButtonish` needs a
+`button` tag or `role="button"` — so `role="checkbox" | "radio" | "tab" | "menuitem"` render as a
+`div` where Space scrolls the page instead of activating. **Do not "fix" that by changing the role.**
+First consumer: `checkbox` (`Checkbox.tsx`, where Space is the primary key).
+
+## Accessibility state props — flat, never object-shaped
+
+See `docs/PLATFORM-A11Y-PROPS.md` for the full rationale. Summary: `accessibilityState={{…}}`,
+`accessibilityValue={{…}}` and `accessibilityHint` are silently discarded by
+`react-native-web@0.21.2`'s `createDOMProps` allowlist, which is flat (`aria-selected`,
+`aria-expanded`, `aria-checked`, `aria-busy`, `aria-disabled`, …). React Native itself accepts the
+flat form natively and merges it into `accessibilityState`, so every module's `resolve*Accessibility()`
+in `*.variants.ts` returns flat `aria-*` keys, spread 1:1 onto the JSX. The two exceptions with no
+native equivalent (`aria-current`, `aria-pressed`) emit BOTH the flat web prop and the nearest
+native `accessibilityState` key.
+
 ## Known gaps
 
-- None yet — grows as more shared a11y concerns surface (e.g. a `useAccessibilityAnnounce` if a
-  later component needs live-region announcements).
+- **Still silent on web:** `toast/Toast.tsx` (`show()`) and `copy-button/CopyButton.tsx` call
+  `AccessibilityInfo.announceForAccessibility` directly. Both sit inside a component, so the fix is
+  `const announce = useAnnouncer()` + `announce(…)` — no new API, native unchanged.
+- **Still silent on iOS:** the remaining `accessibilityLiveRegion` call sites (`date-picker/PickerField`).
+  RNW 0.21.2 forwards the prop to `aria-live` with its deprecation warning commented out, so web and
+  Android are fine. Converge on `useAnnounce` + dropping the prop; a props-bag helper can't work
+  (JSX spread is lint-banned). `pagination` and `combobox`'s error text converged in the
+  accessibility-props migration (2026-08); `combobox`'s empty state deliberately keeps its
+  `Platform.OS === "android"`-gated live region instead — iOS/VoiceOver announces a text-content
+  change in an already-visible node without it, so `useAnnounce` there would double-speak.
+- No `useAccessibilityFocus` (programmatically moving reader focus) — nothing has needed it yet.
+- Six modules besides `checkbox` need `useSpaceActivation` (radio, tab, menu item, …) — only
+  `checkbox` is wired so far.
+- `useFocusTrap` does not pull focus back when it escapes the subtree by means other than Tab
+  (a click outside, or a programmatic `focus()`); it only cycles Tab at the ends.
+- **A consumer that freezes the value at mount still reads the pre-probe seed.**
+  `message-bubble/MessageBubble.tsx:41` does `useRef(motion.decorative)`, so the very first bubble
+  mounted in a process keeps whatever the seed said. The cache makes that one mount, not every
+  mount; the real fix belongs in the module.
+- A probe that settles after the last reader unmounts still writes the cache on purpose (the next
+  mount wants that answer). There is no per-instance `mounted` guard any more — the store simply has
+  no listeners to notify.

package/lib/module/core/a11y/announce.js

@@ -0,0 +1,30 @@
+"use strict";
+
+/**
+ * Native/default counterpart of `announce.web.ts`: the one imperative "say this now" primitive
+ * behind `useAnnounce`. On iOS/Android the OS owns the announcement queue, so this is a direct
+ * `AccessibilityInfo.announceForAccessibility` call and nothing else.
+ *
+ * The `.ts` / `.web.ts` pair (the `keyboard.ts` precedent) is what keeps the DOM code out of the
+ * native dependency graph entirely: Metro resolves `announce.web.ts` only for a web bundle, and
+ * Jest (whose `react-native` preset has no `web` platform) always resolves THIS file. A
+ * `Platform.OS` branch would instead ship the DOM code to native.
+ *
+ * The de-duplication that stops an unchanged message repeating lives one layer up in `useAnnounce`,
+ * deliberately: both platforms then share one set of semantics, and this primitive speaks every
+ * time it is called — exactly what `announceForAccessibility` does.
+ */
+
+import { AccessibilityInfo } from "react-native";
+function announce(message) {
+  AccessibilityInfo.announceForAccessibility(message);
+}
+
+/**
+ * Returns the process-wide announce function. A hook rather than a bare export so the web half can
+ * own a live region's lifetime without changing this signature; here there is nothing to set up.
+ */
+export function useAnnouncer() {
+  return announce;
+}
+//# sourceMappingURL=announce.js.map

package/lib/module/core/a11y/announce.web.js

@@ -0,0 +1,134 @@
+"use strict";
+
+/**
+ * Web implementation of the library's screen-reader announcement primitive. Metro only resolves
+ * this file for a web bundle (see `announce.ts`), so it is the one place that may assume a DOM.
+ *
+ * **Why it exists at all.** `react-native-web@0.21.2` ships
+ * `AccessibilityInfo.announceForAccessibility` as an empty function body
+ * (`dist/exports/AccessibilityInfo/index.js`) — every WCAG 4.1.3 status message in the library is
+ * silent on web without this. The web equivalent is an ARIA live region, which the platform reads
+ * out when its text *changes*, so the whole job here is producing a change a screen reader can see.
+ *
+ * **Why the DOM types are hand-written.** `tsconfig.json` sets `"lib": ["ESNext"]` — `document` and
+ * `HTMLElement` do not exist as types in `src/`, `any` is lint-banned, and augmenting
+ * `react-native`'s types would ship DOM-only APIs to every consumer's native build through
+ * `lib/typescript/**`. A module-local structural surface plus `declare const document` erases
+ * completely at emit, the same contract `keyboard.web.ts` established at this boundary.
+ */
+
+import { useEffect } from "react";
+/** `typeof` rather than a null check: a bare `document` reference throws outside a browser. */
+function getDocument() {
+  return typeof document === "undefined" ? undefined : document;
+}
+
+/** How the DOM tests find the region; changing it is a contract change, not a rename. */
+const CONTAINER_ATTRIBUTE = "data-pixelize-announcer";
+
+/**
+ * The clip technique, and only the clip technique. `display:none` and `visibility:hidden` both drop
+ * the node out of the accessibility tree, which is the entire point of the node.
+ */
+const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;" + "overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0;";
+let container = null;
+let regions = null;
+/** Which of the pair receives the next message. */
+let useSecond = false;
+let mountCount = 0;
+let teardownTimer = null;
+/** Bumped on teardown so a fill still queued against a removed region cannot land. */
+let generation = 0;
+function createRegion(doc) {
+  const region = doc.createElement("div");
+  // `polite` waits for a pause; `assertive` cuts the user off mid-sentence, which no status message
+  // in this library warrants. `role="status"` carries the same politeness for readers that map it.
+  region.setAttribute("role", "status");
+  region.setAttribute("aria-live", "polite");
+  region.setAttribute("aria-atomic", "true");
+  return region;
+}
+
+/** Idempotent: one container with one region pair for the whole document, however many hooks mount. */
+function mountRegions() {
+  if (container !== null) return;
+  const doc = getDocument();
+  const body = doc?.body;
+  if (doc === undefined || body == null) return;
+  const node = doc.createElement("div");
+  node.setAttribute(CONTAINER_ATTRIBUTE, "");
+  node.setAttribute("style", VISUALLY_HIDDEN);
+  const first = createRegion(doc);
+  const second = createRegion(doc);
+  node.appendChild(first);
+  node.appendChild(second);
+  body.appendChild(node);
+  container = node;
+  regions = [first, second];
+  useSecond = false;
+}
+function unmountRegions() {
+  generation += 1;
+  container?.remove();
+  container = null;
+  regions = null;
+}
+
+/**
+ * Puts `message` in front of the screen reader. Two things make this actually speak rather than
+ * merely look right in the DOM:
+ *
+ * 1. **The fill is deferred a task.** A live region that is inserted with its text already in it
+ *    gives the reader nothing to diff and is routinely announced by nothing at all. The region is
+ *    always in the document and empty first, and gains its text in a later task.
+ * 2. **The pair alternates.** Writing the identical string to the same node is not a DOM mutation,
+ *    so a repeat would be silent — and `useAnnounce` re-announces a message that cleared and came
+ *    back, matching `announceForAccessibility`, which speaks on every call. Alternating means every
+ *    announcement is an empty-to-text change on a node, whatever the previous message was.
+ */
+function announce(message) {
+  const pair = regions;
+  if (pair === null) return;
+  const [first, second] = pair;
+  const target = useSecond ? second : first;
+  const previous = useSecond ? first : second;
+  useSecond = !useSecond;
+
+  // Drop the message the reader was last given so the two regions never both hold status text.
+  previous.textContent = "";
+  target.textContent = "";
+  const opened = generation;
+  setTimeout(() => {
+    if (opened === generation) target.textContent = message;
+  }, 0);
+}
+
+/**
+ * Retains the shared live region for the lifetime of the calling component, and returns the
+ * announce function. Same shape as `useReducedMotion`'s store: process-wide setup opened by the
+ * first consumer and closed by the last, never one per hook instance.
+ *
+ * Teardown is deferred a task because StrictMode (and any remount) runs mount → unmount → mount
+ * back to back: removing the region synchronously on that middle cleanup would invalidate the fill
+ * the first mount just queued, and the second mount does not re-announce.
+ */
+export function useAnnouncer() {
+  useEffect(() => {
+    mountCount += 1;
+    if (teardownTimer !== null) {
+      clearTimeout(teardownTimer);
+      teardownTimer = null;
+    }
+    mountRegions();
+    return () => {
+      mountCount -= 1;
+      if (mountCount > 0) return;
+      teardownTimer = setTimeout(() => {
+        teardownTimer = null;
+        if (mountCount === 0) unmountRegions();
+      }, 0);
+    };
+  }, []);
+  return announce;
+}
+//# sourceMappingURL=announce.web.js.map

package/lib/module/core/a11y/index.js

@@ -1,26 +1,92 @@
 "use strict";
 
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useSyncExternalStore } from "react";
 import { AccessibilityInfo } from "react-native";
+import { useAnnouncer } from "./announce";
+
+/**
+ * Last OS answer seen in this process. `isReduceMotionEnabled()` only resolves after the first
+ * commit, so without this every later mount would re-pay the pessimistic seed below and lose its
+ * enter animation for a user who never asked for less motion.
+ */
+let lastKnownReduceMotion = null;
+let nativeSubscription = null;
+/** Bumped by the test reset so a probe still in flight from a previous suite cannot land late. */
+let generation = 0;
+const listeners = new Set();
+function publish(value) {
+  if (lastKnownReduceMotion === value) return;
+  lastKnownReduceMotion = value;
+  for (const listener of listeners) listener();
+}
+
+/** One probe and one native listener for the whole process, opened by the first subscriber. */
+function openNativeSubscription() {
+  const opened = generation;
+  const apply = value => {
+    if (opened === generation) publish(value);
+  };
+  void AccessibilityInfo.isReduceMotionEnabled().then(apply);
+  nativeSubscription = AccessibilityInfo.addEventListener("reduceMotionChanged", apply);
+}
+function subscribe(onStoreChange) {
+  listeners.add(onStoreChange);
+  if (listeners.size === 1) openNativeSubscription();
+  return () => {
+    listeners.delete(onStoreChange);
+    if (listeners.size === 0) {
+      nativeSubscription?.remove();
+      nativeSubscription = null;
+    }
+  };
+}
+function getSnapshot() {
+  return lastKnownReduceMotion ?? true;
+}
+
+/** Test-only: drops the process cache so a suite can assert the pre-probe seed. */
+export function resetReducedMotionCache() {
+  generation += 1;
+  lastKnownReduceMotion = null;
+  nativeSubscription?.remove();
+  nativeSubscription = null;
+  if (listeners.size > 0) openNativeSubscription();
+}
 
 /**
  * Tracks the OS reduce-motion setting (WCAG 2.3.3) so a press/transition animation can be
- * suppressed for a user who has it on. Shared across every animated module — press fades,
- * expand/collapse, toasts — so the setting is read once per mount, not re-implemented per module.
+ * suppressed for a user who has it on. Every animated module reads this one store: ten `<Button>`s
+ * cost one native listener and one bridge round-trip, not ten of each.
+ *
+ * Seeds `true` until the async probe answers: a `false` seed makes `motion.enabled` (and on a
+ * high-tier device `motion.decorative`) true for the first commit AND the first effect pass, which
+ * defeats every correctly-written reduce-motion gate in the library at once.
  */
 export function useReducedMotion() {
-  const [reduced, setReduced] = useState(false);
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+/**
+ * Announces a status message to the screen reader when it becomes present, or changes (WCAG 4.1.3).
+ * `accessibilityLiveRegion` is Android-only, so it alone leaves iOS VoiceOver silent; this reaches
+ * VoiceOver, TalkBack and the browser alike.
+ *
+ * A caller must NOT also put `accessibilityLiveRegion` on the message it renders: on Android that
+ * announces twice. Pass `undefined` for "no message"; a message that stays the same is not repeated.
+ *
+ * The transition rule lives here, on both platforms: `useAnnouncer()` supplies only the platform's
+ * "say this now" primitive (`announceForAccessibility` on native, a shared ARIA live region on web,
+ * where that call is an empty function — see `announce.web.ts`).
+ */
+export function useAnnounce(message) {
+  const announce = useAnnouncer();
+  // Compared against, never rendered from: the effect must fire on a transition, not every render.
+  const announced = useRef(undefined);
   useEffect(() => {
-    let mounted = true;
-    void AccessibilityInfo.isReduceMotionEnabled().then(value => {
-      if (mounted) setReduced(value);
-    });
-    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduced);
-    return () => {
-      mounted = false;
-      sub.remove();
-    };
-  }, []);
-  return reduced;
+    if (message !== undefined && message !== announced.current) {
+      announce(message);
+    }
+    announced.current = message;
+  }, [announce, message]);
 }
 //# sourceMappingURL=index.js.map