pixelize-native-library 1.2.1 → 1.3.0

package/lib/module/modules/radio-group/MODULE.md

@@ -9,8 +9,8 @@ without collapsing the individually-focusable rows into one.
 
 | File | Role |
 |------|------|
-| `RadioGroup.tsx` | The component. Row composition, press wiring, a11y wiring. |
-| `RadioGroup.variants.ts` | Pure resolvers (`RADIO_GROUP_SIZES`, `resolveRadioGroupColors`, `resolveRadioRowAccessibility`) + the themed/untethemed structural resolvers (`radioGroupStructure`, `radioRowStructure`, `radioRingStructure`, `radioDotStructure`). No React, no lucide. |
+| `RadioGroup.tsx` | The component. Row composition, press wiring, a11y wiring. Focus ring geometry uses `FOCUS_RING_GAP` / `FOCUS_RING_WIDTH` from `core/style/focusRing`. |
+| `RadioGroup.variants.ts` | Pure resolvers (`RADIO_GROUP_SIZES`, `resolveRadioGroupColors`, `resolveRadioRowAccessibility`, `resolveRadioGroupKeyIndex`) + the themed/untethemed structural resolvers (`radioGroupStructure`, `radioRowStructure`, `radioRingStructure`, `radioDotStructure`). `MIN_TOUCH_TARGET` from `core/a11y/touchTarget`. No React, no lucide. |
 | `index.ts` | Public surface: `RadioGroup`, `RadioGroupProps`, `RadioGroupOption`, `RadioGroupSize`. |
 | `__tests__/RadioGroup.test.ts` | Pure: WCAG contrast (label-on-canvas, label-on-pressed-row, ring, dot — all brands × modes) + touch target + a11y contract. |
 | `__tests__/RadioGroup.render.test.tsx` | Render: selection, press blocking when disabled, per-row a11y state. |
@@ -24,7 +24,7 @@ without collapsing the individually-focusable rows into one.
 | `onValueChange` | `(value: string) => void` | — | Fires with the pressed option's `value`; gated off while `disabled`. |
 | `disabled` | `boolean` | `false` | Dims every row and blocks all presses. |
 | `size` | `sm \| md` | `md` | Both rows are 44 dp tall (see WCAG below); `sm` is the denser variant through its smaller ring/dot/font and tighter gaps. |
-| `accessibilityLabel` | `string` | — | Names the `radiogroup` container. Previously absent, so the container was announced unnamed — a reader heard each option's own label but nothing saying what the set was FOR (WCAG 1.3.1). |
+| `accessibilityLabel` | `string` | — | Names the `radiogroup` container — without it a reader hears each option's label but nothing saying what the set is FOR (WCAG 1.3.1). |
 | `style` | `LayoutStyle` | — | Layout-only, outermost (the container `View`), applied exactly once, last. |
 | `testID` | `string` | — | Container's testID; each row gets `` `${testID}-${option.value}` ``, and the focused row a `` `${testID}-${option.value}-focus-ring` `` child, when set. |
 
@@ -61,12 +61,12 @@ closed union of appearances. The ring is always `border.interactive`; the select
   handler also calls `.focus()` on the newly-selected row's node, because the tab stop moved and DOM
   focus has to follow it or the ring is stranded on the old row. RN's TypeScript `ViewPropTypes.d.ts`
   omits `onKeyDown` (its Flow types declare it), so the container `View` is re-typed once, locally.
-- **2.4.7 (focus visible)** — Button's `border.focus` ring, drawn a 2dp gap OUTSIDE the row (nothing
-  in the group clips), on the focused row only, never while disabled. Rows also carry
+- **2.4.7 (focus visible)** — `border.focus` ring (`core/style/focusRing` offsets), drawn outside the
+  row (nothing in the group clips), on the focused row only, never while disabled. Rows also carry
   `focusable={!disabled}` — RN's `Pressable` stays focusable when disabled, which on a TV remote
   would otherwise land on a row that renders no ring (same fix NumberInput's steppers use).
 - **2.3.3** — n/a for selection dot (conditional render). Row presses use `usePressState` (scale +
-  state-layer overlay), which snaps under reduce motion.
+  state-layer overlay), which snaps under reduce motion. Rows also carry `android_ripple`.
 - Disabled rows are exempt from the contrast minimum (WCAG 1.4.3), so the uniform `opacity: 0.5`
   dim is correct, same as Button.
 
@@ -93,9 +93,3 @@ closed union of appearances. The ring is always `border.interactive`; the select
 ## Performance
 
 Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The `options.map()` renders host `Pressable`/`View`/`Text`, not a library child component, so the inline per-row `onPress`/style closures were left as-is.
-
-## 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/radio-group/RadioGroup.js

@@ -15,6 +15,7 @@ import { Platform, Pressable, StyleSheet, Text, View } from "react-native";
 import Animated from "react-native-reanimated";
 import { usePressState } from "../../core/motion/usePressState.js";
 import { useHaptics } from "../../core/haptics/index.js";
+import { FOCUS_RING_GAP, FOCUS_RING_WIDTH } from "../../core/style/focusRing.js";
 import { rippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
 import { useTheme } from "../../theme/hooks.js";
 import { RADIO_GROUP_SIZES, radioDotStructure, radioGroupStructure, radioRingStructure, radioRowStructure, resolveRadioGroupColors, resolveRadioGroupKeyIndex, resolveRadioRowAccessibility } from "./RadioGroup.variants.js";
@@ -27,8 +28,6 @@ const KeyboardView = View;
 
 // Same offset ring as Button: `border.focus` a small gap OUTSIDE the row, on the canvas, which is
 // the surface that role token is proven ≥ 3:1 against (WCAG 2.4.11).
-const FOCUS_RING_WIDTH = 2;
-const FOCUS_RING_GAP = 2;
 const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
 function RadioRow({
   option,
@@ -60,9 +59,10 @@ function RadioRow({
   return /*#__PURE__*/_jsxs(View, {
     style: styles.rowHost,
     children: [focusedIndex === index && !disabled && /*#__PURE__*/_jsx(View, {
-      pointerEvents: "none",
       testID: testID ? `${testID}-${option.value}-focus-ring` : undefined,
-      style: [styles.focusRing, focusRingStyle]
+      style: [styles.focusRing, focusRingStyle, {
+        pointerEvents: 'none'
+      }]
     }), /*#__PURE__*/_jsxs(AnimatedPressable, {
       ref: node => {
         rowRefs.current[index] = node;
@@ -92,8 +92,9 @@ function RadioRow({
         overflow: "hidden"
       }, press.animatedStyle, disabled && styles.dimmed],
       children: [/*#__PURE__*/_jsx(Animated.View, {
-        pointerEvents: "none",
-        style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle]
+        style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle, {
+          pointerEvents: 'none'
+        }]
       }), /*#__PURE__*/_jsx(View, {
         style: [radioRingStructure(theme, {
           size

package/lib/module/modules/radio-group/RadioGroup.variants.js

@@ -10,10 +10,9 @@
  *    "selected"/"disabled" contract is unit-testable without rendering React Native.
  */
 
+import { MIN_TOUCH_TARGET, slopFor } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants, createVariants } from "../../core/style/index.js";
-/** Same floor as Button — Apple HIG minimum and WCAG 2.5.5 (AAA). */
-export const MIN_TOUCH_TARGET = 44;
-const slopFor = height => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - height) / 2));
+export { MIN_TOUCH_TARGET };
 /**
  * RadioGroup-specific dimensions. Kept a plain constant — no theme dependency — so the hit-target
  * test can assert `rowMinHeight + 2·hitSlop ≥ 44` without a provider, same as `BUTTON_SIZES`.

package/lib/module/modules/radio-group/RadioGroupProps.js

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

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

@@ -11,7 +11,7 @@ way to preview the drop position. Built on **one** shared `Gesture.Pan()`
 | File | Role |
 |------|------|
 | `Reorder.tsx` | The component. The single shared pan, the five shared values that drive every row, and the two `Button` up/down alternatives. `ReorderRow` is a private, memoized sub-component rendered through `VirtualList`. |
-| `Reorder.variants.ts` | Pure resolvers (`resolveReorderColors`, `resolveReorderMoveState`, `moveItem`, `resolveRowPitch`, `resolveDragTargetIndex`, `resolveRowShift`) + the themed/untethered structural resolvers. No React, no lucide. The two drag-math resolvers are `"worklet"`-marked so the UI thread can call them. |
+| `Reorder.variants.ts` | Pure resolvers (`resolveReorderColors`, `resolveReorderMoveState`, `moveItem`, `resolveRowPitch`, `resolveDragTargetIndex`, `resolveRowShift`, `resolveReorderRowLabel`, `resolveReorderMoveAnnouncement`) + the themed/untethered structural resolvers. No React, no lucide. The two drag-math resolvers are `"worklet"`-marked so the UI thread can call them. |
 | `index.ts` | Public surface: `Reorder`, `ReorderProps`, `ReorderItem`. |
 | `__tests__/Reorder.test.ts` | Pure: WCAG contrast (all brands × modes), grip touch target, and the drag/alternative-path arithmetic. |
 | `__tests__/Reorder.render.test.tsx` | Render: labels, grip hidden from a11y, grip drag gating, the WCAG 2.5.7 alternative in both directions, disabled gating, testID wiring, the reduced-motion row shift, and the shift reset on drop. Mocks both animation peers locally and captures the pan's callbacks so a test drives a real drag. |
@@ -72,7 +72,12 @@ No `variant`/`size`/`tone` — every row reads identically; the only per-row sta
 
 Every timing comes from `core/motion` — `useMotion().duration("fast")` for the lift and the row
 shift, `useMotion().transform.pressOpacity` for the lifted row's opacity. No local duration constant
-lives in this module. Only `opacity` and `transform` animate, on reanimated's UI thread.
+lives in this module. Only `opacity` and `transform` animate, on reanimated's UI thread. Lift fires
+`haptics.impact("light")` and a committed move fires `haptics.selection()`, both gated on
+`useReducedMotion()` being false. Drag completion hops to JS with `scheduleOnRN`
+(`react-native-worklets`), never the deprecated `runOnJS`.
+
+`react-native-gesture-handler` and `react-native-reanimated` are non-optional peers here.
 
 ## Accessibility contract (WCAG)
 
@@ -129,12 +134,3 @@ lives in this module. Only `opacity` and `transform` animate, on reanimated's UI
 reads the current `items`/`onReorder` through refs, so the `Gesture.Pan()` object never has to be
 rebuilt mid-drag (re-registering a `GestureDetector` mid-drag drops the live gesture). Row callbacks
 take an `index`/`id` argument, so no per-row closure is allocated in the render loop.
-
-## History (v1.0.7)
-
-Replaced the original `PanResponder` + per-row `Animated.Value` implementation — one responder AND
-one animated node per row, no virtualization, unusable past a few hundred rows — with the single
-shared gesture + `VirtualList` described above. `react-native-gesture-handler` and
-`react-native-reanimated` are non-optional peers. **No public prop API change.**
-
-Drag completion uses `scheduleOnRN` from `react-native-worklets` (not deprecated `runOnJS`).

package/lib/module/modules/reorder/Reorder.js

@@ -39,7 +39,8 @@ import { Text, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import Animated, { cancelAnimation, useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
-import { useAnnounce } from "../../core/a11y/index.js";
+import { useAnnounce, useReducedMotion } from "../../core/a11y/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
 import { VirtualList } from "../../core/list/index.js";
 import { useMotion } from "../../core/motion/index.js";
 import { useTheme } from "../../theme/hooks.js";
@@ -57,6 +58,8 @@ export const Reorder = /*#__PURE__*/memo(function Reorder({
 }) {
   const theme = useTheme();
   const motion = useMotion();
+  const haptics = useHaptics();
+  const reducedMotion = useReducedMotion();
   const colors = useMemo(() => resolveReorderColors(theme.colors), [theme.colors]);
   const rowPitch = resolveRowPitch(theme.space[2]);
   const activeIndex = useSharedValue(IDLE);
@@ -102,7 +105,8 @@ export const Reorder = /*#__PURE__*/memo(function Reorder({
       duration: liftMs
     }) : 1;
     setActiveRow(index);
-  }, [disabled, activeIndex, targetIndex, translationY, lift, motionEnabled, liftMs]);
+    if (!reducedMotion) haptics.impact("light");
+  }, [disabled, activeIndex, targetIndex, translationY, lift, motionEnabled, liftMs, reducedMotion, haptics]);
   const endDrag = useCallback(() => {
     const from = activeIndex.value;
     if (from === IDLE) return;
@@ -119,8 +123,9 @@ export const Reorder = /*#__PURE__*/memo(function Reorder({
       if (moved !== undefined) {
         setAnnouncement(resolveReorderMoveAnnouncement(moved.label, to, itemsRef.current.length));
       }
+      if (!reducedMotion) haptics.selection();
     }
-  }, [activeIndex, targetIndex, translationY, lift]);
+  }, [activeIndex, targetIndex, translationY, lift, reducedMotion, haptics]);
   const pan = useMemo(() => Gesture.Pan()
   // Without manual activation the pan swallows the virtualized list's own scroll gesture.
   .manualActivation(true).onTouchesMove((_event, manager) => {

package/lib/module/modules/reorder/Reorder.variants.js

@@ -16,7 +16,9 @@
  * only `react-native`'s `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
 
+import { MIN_TOUCH_TARGET, slopFor } from "../../core/a11y/touchTarget.js";
 import { createThemedVariants, createVariants } from "../../core/style/index.js";
+export { MIN_TOUCH_TARGET };
 
 /**
  * Fixed row height, in dp. A fixed height — rather than per-row `onLayout` measurement — is what
@@ -25,10 +27,6 @@ import { createThemedVariants, createVariants } from "../../core/style/index.js"
  */
 export const REORDER_ROW_HEIGHT = 56;
 
-/** The 44dp floor every touch target holds itself to (WCAG 2.5.5 AAA; comfortably clears 2.5.8). */
-export const MIN_TOUCH_TARGET = 44;
-const slopFor = dimension => Math.max(0, Math.ceil((MIN_TOUCH_TARGET - dimension) / 2));
-
 /** Grip bar glyph — three of these stacked make the drag-handle affordance. No `IconName` in the
  *  closed 22-name set represents a drag handle, and that set is never extended for one component
  *  (per the build brief), so the grip is hand-built from plain themed bars instead. */
@@ -56,6 +54,7 @@ export const GRIP_HIT_SLOP = {
  * one of these role lookups, guaranteed legible in both modes (same reasoning `resolveTimelineColors`
  * documents for its own tone-less component).
  */
+
 export function resolveReorderColors(colors) {
   return {
     rowBackground: colors.bg.surface,

package/lib/module/modules/reorder/ReorderProps.js

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

package/lib/module/modules/rich-text/MODULE.md

@@ -1,4 +1,4 @@
-# rich-text/
+# rich-text/ — a read-only renderer for sanitized HTML
 
 Read-only safe HTML renderer. Parse/sanitize in `parseRichText.ts` (ported from tickets/mobile). Heavy — subpath only.
 
@@ -29,8 +29,7 @@ safe schemes only) · `onImagePress` · `style` (layout-only, outermost, once, l
   muted 6.52 and link 5.06 on the canvas · mention label 4.82 on its own `accent.subtle` pill · code and
   `pre` 5.69 on `bg.sunken`. `quoteBorder` / `border` are decorative rules (1.08–1.43:1) with no contrast
   floor — they are pinned to `border.default` and asserted never to escalate to `border.interactive`/`focus`.
-- `blockquote`'s left border is `theme.borderWidths.thick` (2dp), not a raw literal `3` — a real,
-  visible 1px change to every rendered blockquote.
+- `blockquote`'s left border is `theme.borderWidths.thick`, never a raw literal.
 
 ## Performance
 
@@ -51,4 +50,5 @@ into inline spans inside one `Text` — which a `FlatList` cannot host. It also
 ## Known gaps
 
 - Tables are sanitized through but render as their text runs, not as a grid.
-- Images render as a `🖼 alt` placeholder — the library never fetches remote content itself.
+- Images render as a `🖼 alt` placeholder inside a `Pressable` — the library never fetches remote
+  content itself.

package/lib/module/modules/rich-text/RichTextProps.js

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

package/lib/module/modules/rich-text-editor/MODULE.md

@@ -26,7 +26,7 @@ button) — it is not the HTML and must not be used for persistence.
 
 | File | Role |
 |------|------|
-| `RichTextEditor.tsx` | The component: toolbar (`Button`), the native editor, the link dialog (`Modal` + `Input`), the mention dropdown. |
+| `RichTextEditor.tsx` | The component: toolbar (`Button`), the native editor, the link dialog (`Modal` + `Input`), the mention dropdown. Colocated props keep behavioural JSDoc on non-obvious fields only (no per-prop narration). |
 | `RichTextEditor.variants.ts` | Pure resolvers — toolbar item catalogue, `onChangeState` → active-action mapping, mention filtering, colour + `HtmlStyle` token mapping — plus the themed structural resolvers. No React, no native import (types-only from `react-native-enriched-html`). |
 | `index.ts` | Public surface: `RichTextEditor`, `RichTextEditorHandle`, `RichTextEditorProps`, `MentionUser`, `RichTextEditorImage`, `RichTextEditorToolbarAction`, `RICH_TEXT_EDITOR_TOOLBAR_ITEMS`. |
 | `__tests__/RichTextEditor.test.ts` | Pure: WCAG contrast for the field/mention pill/code/code-block/blockquote/link/list-marker colours (all brands × modes), the toolbar item catalogue, `onChangeState` mapping, mention filtering. |
@@ -142,8 +142,7 @@ dropdown now does.
 ## Accessibility
 
 - **Editor field accessible name.** The native `EnrichedTextInput` gets `accessibilityLabel` from
-  `accessibilityLabel ?? label` (`resolveRichTextEditorAccessibility`) — before this fix it had no
-  path to a name at all. On native the now-redundant visible `label` `Text` is hidden from
+  `accessibilityLabel ?? label` (`resolveRichTextEditorAccessibility`). On native the now-redundant visible `label` `Text` is hidden from
   assistive tech (`aria-hidden`) so the name isn't announced twice. **On web it stays exposed**:
   `react-native-enriched-html`'s web build renders a TipTap `EditorContent` and forwards no
   accessibility prop to the underlying `contenteditable` (only `enterkeyhint`), so the field itself
@@ -152,8 +151,8 @@ dropdown now does.
   close this gap.
 - **Toolbar toggle (pressed) state.** The 14 style-toggle buttons (all but the `image`/`mention`
   triggers, see `RichTextEditorToolbarItem.toggle`) pass `Button`'s `selected` prop, driven by the
-  same `activeActions` state that already drove the `variant="solid"` highlight — before this fix
-  the toggle was colour-only (WCAG 1.4.1) and announced nothing (4.1.2). `Button` itself resolves
+  same `activeActions` state that drives the `variant="solid"` highlight, so the toggle is never
+  colour-only (WCAG 1.4.1) and always announced (4.1.2). `Button` itself resolves
   `selected` into `aria-pressed` (web) / `accessibilityState.selected` (native), per
   `docs/PLATFORM-A11Y-PROPS.md`'s "genuinely diverge" case — RN has no `pressed` accessibility
   state at all. `image`/`mention` never receive `selected`: they open a picker, not toggle a style.
@@ -181,10 +180,8 @@ Every colour handed to the native `htmlStyle`/native props is a role lookup, nev
 
 ## Known gaps
 
-- **EAS Android dev-client build confirmed successful (build `22b8321f`, APK built) but NOT yet
-  verified on a physical device by the user.** Everything reported here is typecheck/build/unit-test
-  level — jest cannot render a native Fabric component, so nothing here claims the editor "works" on
-  device.
+- **Nothing here is device-verified.** Jest cannot render a native Fabric component, so the editor's
+  behaviour on device is a manual pass; the suite only covers the mocked surface.
 - `onChangeState.image.isBlocking` (the caret is somewhere an `<img>` can't go, e.g. inside a code
   block) is not honoured — the pick/upload still runs and native `addImage` then silently no-ops.
   Disabling the button on that flag is the follow-up.
@@ -219,10 +216,3 @@ Wrapped in `React.memo`. This component re-renders on every keystroke (`onChange
 
 No motion of its own — the editor's own visual state changes (toggle highlighting, focus ring) are
 instant, and the mention dropdown is a list, where per-row animation is forbidden.
-
-## 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.
-
-- **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/rich-text-editor/RichTextEditor.js

@@ -19,6 +19,7 @@
 import { forwardRef, memo, useCallback, useImperativeHandle, useMemo, useRef, useState } from "react";
 import { Platform, Pressable, ScrollView, StyleSheet, Text, View } from "react-native";
 import { EnrichedTextInput } from "react-native-enriched-html";
+import { FOCUS_RING_GAP, FOCUS_RING_WIDTH } from "../../core/style/focusRing.js";
 import { VirtualList } from "../../core/list/index.js";
 import { useTheme } from "../../theme/hooks.js";
 import { rippleColor } from "../../theme/platform/stateLayer.native.js";
@@ -71,8 +72,7 @@ const MentionRow = /*#__PURE__*/memo(function MentionRow({
 
 // Identical to `Input`/`Textarea`: the ring sits OUTSIDE the field, on the canvas, where
 // `border.focus` is the token proven ≥ 3:1.
-const FOCUS_RING_WIDTH = 2;
-const FOCUS_RING_GAP = 2;
+
 function RichTextEditorImpl({
   defaultValue,
   placeholder,
@@ -373,9 +373,10 @@ function RichTextEditorImpl({
           })
         })]
       }), focused && /*#__PURE__*/_jsx(View, {
-        pointerEvents: "none",
         testID: "rich-text-editor-focus-ring",
-        style: focusRingStyle
+        style: [focusRingStyle, {
+          pointerEvents: 'none'
+        }]
       })]
     }), /*#__PURE__*/_jsx(Modal, {
       visible: linkOpen,

package/lib/module/modules/rich-text-editor/RichTextEditorProps.js

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

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

@@ -0,0 +1,3 @@
+# save-bar/ — a floating dirty-state action bar
+
+Floating dirty-state action bar with safe-area padding.

package/lib/module/modules/save-bar/SaveBar.js

@@ -0,0 +1,49 @@
+"use strict";
+
+import { memo, useMemo } from "react";
+import { View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { useTheme } from "../../theme/hooks.js";
+import { Button } from "../button/index.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export const SaveBar = /*#__PURE__*/memo(function SaveBar({
+  dirty,
+  onSave,
+  onDiscard,
+  saveLabel = "Save",
+  discardLabel = "Discard",
+  saving = false,
+  style,
+  testID
+}) {
+  const theme = useTheme();
+  const insets = useSafeAreaInsets();
+  const barStyle = useMemo(() => ({
+    paddingHorizontal: theme.space[4],
+    paddingTop: theme.space[3],
+    paddingBottom: Math.max(theme.space[3], insets.bottom),
+    backgroundColor: theme.colors.bg.surface,
+    borderTopWidth: 1,
+    borderTopColor: theme.colors.border.default,
+    flexDirection: "row",
+    justifyContent: "flex-end",
+    gap: theme.space[2]
+  }), [theme, insets.bottom]);
+  if (!dirty) return null;
+  return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
+    style: [barStyle, style],
+    children: [onDiscard ? /*#__PURE__*/_jsx(Button, {
+      label: discardLabel,
+      variant: "ghost",
+      onPress: onDiscard,
+      disabled: saving
+    }) : null, /*#__PURE__*/_jsx(Button, {
+      label: saveLabel,
+      variant: "solid",
+      onPress: onSave,
+      loading: saving
+    })]
+  });
+});
+//# sourceMappingURL=SaveBar.js.map

package/lib/module/modules/save-bar/SaveBarProps.js

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

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

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

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

@@ -12,6 +12,7 @@ content instead of `children`.
 | `Screen.variants.ts` | Pure resolver (`resolveScreenColors`) + themed structural resolvers + `ScreenEdge` / `ScreenState` unions. |
 | `index.ts` | Public surface: `Screen`, `ScreenProps`, `ScreenEdge`, `ScreenState`. |
 | `__tests__/Screen.test.ts` | Pure: colour mapping, default edges. |
+| `__tests__/Screen.dom.test.tsx` | Render under `react-dom` — guards the shell against web-only regressions. |
 | `__tests__/Screen.render.test.tsx` | Render: default loading slot, idle children, consumer `style` last. Mocks `core/a11y` via `jest.requireActual` + override, not a full replacement — the default `LoadingState`/`ErrorState` slots call `useAnnounce`, which a full-replacement mock would drop. |
 
 ## Props
@@ -20,7 +21,7 @@ content instead of `children`.
 |------|------|---------|-------|
 | `children` | `ReactNode` | — | Shown when `state="idle"`. |
 | `appBar` | `ReactNode` | — | Top header slot. Receives top safe-area inset; body omits `top` from `edges`. |
-| `edges` | `ScreenEdge[]` | `["top"]` | Passed to `SafeAreaView`. |
+| `edges` | `readonly ScreenEdge[]` | `["top"]` | Passed to `SafeAreaView`. |
 | `padded` | `boolean` | `false` | Adds theme padding around content. |
 | `keyboardAvoiding` | `boolean` | `false` | Wraps in `KeyboardAvoidingView`. |
 | `keyboardVerticalOffset` | `number` | `0` | Passed to `KeyboardAvoidingView`. |
@@ -30,6 +31,7 @@ content instead of `children`.
 | `loading` | `ReactNode` | `<LoadingState />` | Custom loading slot. |
 | `empty` | `ReactNode` | — | Compose `EmptyState` here. |
 | `error` | `ReactNode` | — | Compose `ErrorState` here. |
+| `scrollLinked` | `boolean` | `false` | With `appBar`, uses `Animated.ScrollView` and publishes `scrollY` for `AppBar` `scrollEffect`. |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Forwarded to the outermost shell node. |
 
@@ -47,10 +49,10 @@ hand-rolled as `Screen` + `AppHeader`.
 
 ## Motion
 
-**None, deliberately.** Screen is a layout shell with no surface of its own to animate: a state
-swap (`idle` → `loading` → `error`) is the composed `LoadingState` / `EmptyState` / `ErrorState`
-block's business, and anything Screen could animate itself (a scroll-driven header, a state
-transition it owns) would need a new public prop. Consumers animate their own content.
+**Scroll link only.** `scrollLinked` publishes `scrollY` for a composed `AppBar`; the shell itself
+does not animate. Pull-to-refresh fires a light haptic as the refresh starts, before `onRefresh` (gated on
+reduce-motion and the provider haptics flag). State swaps (`idle` → `loading` → `error`) are handled
+by the composed `LoadingState` / `EmptyState` / `ErrorState` blocks, not by Screen.
 
 ## Performance
 

package/lib/module/modules/screen/Screen.js

@@ -5,9 +5,14 @@
  * optional `appBar` slot with safe-area edge splitting, and async-state slots.
  */
 
-import { memo, useMemo } from "react";
+import { memo, useCallback, useMemo } from "react";
 import { KeyboardAvoidingView, Platform, RefreshControl, ScrollView, View } from "react-native";
 import { SafeAreaView } from "react-native-safe-area-context";
+import Animated, { useAnimatedScrollHandler, useSharedValue } from "react-native-reanimated";
+import { useReducedMotion } from "../../core/a11y/index.js";
+import { useHaptics } from "../../core/haptics/index.js";
+import { ScreenScrollContext } from "../../core/screen-scroll/index.js";
+import { renderNodeSlot } from "../../core/slot/index.js";
 import { useTheme, useThemeColors } from "../../theme/hooks.js";
 import { LoadingState } from "../state-block/index.js";
 import { SCREEN_DEFAULT_EDGES, resolveScreenAppBarEdges, resolveScreenBodyEdges, resolveScreenColors, screenBodyStructure, screenPaddedStructure, screenRootStructure, screenScrollContentStructure, screenShellStructure, screenStateSlotStructure } from "./Screen.variants.js";
@@ -21,6 +26,7 @@ export const Screen = /*#__PURE__*/memo(function Screen({
   keyboardVerticalOffset = 0,
   refreshing = false,
   onRefresh,
+  scrollLinked = false,
   state = "idle",
   loading,
   empty,
@@ -30,47 +36,84 @@ export const Screen = /*#__PURE__*/memo(function Screen({
 }) {
   const theme = useTheme();
   const roleColors = useThemeColors();
+  const haptics = useHaptics();
+  const reducedMotion = useReducedMotion();
   const screenColors = resolveScreenColors(theme.colors);
   const hasAppBar = appBar !== undefined;
+  const scrollY = useSharedValue(0);
+  const scrollHandler = useAnimatedScrollHandler({
+    onScroll: event => {
+      scrollY.value = event.contentOffset.y;
+    }
+  });
+  const scrollContextValue = useMemo(() => ({
+    scrollY
+  }), [scrollY]);
+  const linkScroll = scrollLinked && hasAppBar && state === "idle";
   const bodyEdges = useMemo(() => resolveScreenBodyEdges(edges, hasAppBar), [edges, hasAppBar]);
   const appBarEdges = useMemo(() => resolveScreenAppBarEdges(edges, hasAppBar), [edges, hasAppBar]);
+  const slotTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+    color: theme.colors.fg.default,
+    fontSize: theme.fontSizes.md
+  }], [theme]);
   const body = useMemo(() => {
     if (state === "loading") {
       return /*#__PURE__*/_jsx(View, {
         style: screenStateSlotStructure(theme),
         testID: testID === undefined ? undefined : `${testID}-loading`,
-        children: loading ?? /*#__PURE__*/_jsx(LoadingState, {})
+        children: renderNodeSlot(loading ?? /*#__PURE__*/_jsx(LoadingState, {}), slotTextStyle)
       });
     }
     if (state === "empty") {
       return /*#__PURE__*/_jsx(View, {
         style: screenStateSlotStructure(theme),
         testID: testID === undefined ? undefined : `${testID}-empty`,
-        children: empty
+        children: renderNodeSlot(empty, slotTextStyle)
       });
     }
     if (state === "error") {
       return /*#__PURE__*/_jsx(View, {
         style: screenStateSlotStructure(theme),
         testID: testID === undefined ? undefined : `${testID}-error`,
-        children: error
+        children: renderNodeSlot(error, slotTextStyle)
       });
     }
-    return children;
-  }, [children, empty, error, loading, state, testID, theme]);
+    return renderNodeSlot(children, slotTextStyle);
+  }, [children, empty, error, loading, slotTextStyle, state, testID, theme]);
   const accent = roleColors.accent.solid;
+  const handleRefresh = useCallback(() => {
+    if (!reducedMotion) haptics.impact("light");
+    onRefresh?.();
+  }, [haptics, onRefresh, reducedMotion]);
   const refreshControl = useMemo(() => onRefresh === undefined ? undefined : /*#__PURE__*/_jsx(RefreshControl, {
     refreshing: refreshing,
-    onRefresh: onRefresh,
+    onRefresh: handleRefresh,
     colors: [accent],
     tintColor: accent
-  }), [onRefresh, refreshing, accent]);
-  const inner = refreshControl === undefined ? body : /*#__PURE__*/_jsx(ScrollView, {
-    contentContainerStyle: screenScrollContentStructure(),
-    refreshControl: refreshControl,
-    keyboardShouldPersistTaps: "handled",
-    children: body
-  });
+  }), [handleRefresh, onRefresh, refreshing, accent]);
+  const inner = useMemo(() => {
+    if (linkScroll) {
+      return /*#__PURE__*/_jsx(Animated.ScrollView, {
+        onScroll: scrollHandler,
+        scrollEventThrottle: 16,
+        contentContainerStyle: screenScrollContentStructure(),
+        refreshControl: refreshControl,
+        keyboardShouldPersistTaps: "handled",
+        children: body
+      });
+    }
+    if (refreshControl === undefined) return body;
+    return /*#__PURE__*/_jsx(ScrollView, {
+      contentContainerStyle: screenScrollContentStructure(),
+      refreshControl: refreshControl,
+      keyboardShouldPersistTaps: "handled",
+      children: body
+    });
+  }, [body, linkScroll, refreshControl, scrollHandler]);
+  const scrollWrappedInner = linkScroll ? /*#__PURE__*/_jsx(ScreenScrollContext.Provider, {
+    value: scrollContextValue,
+    children: inner
+  }) : inner;
   const background = screenColors.background;
   const shellStyle = useMemo(() => [screenShellStructure(theme), {
     backgroundColor: background
@@ -90,11 +133,11 @@ export const Screen = /*#__PURE__*/memo(function Screen({
     testID: testID,
     children: [appBarEdges.length > 0 ? /*#__PURE__*/_jsx(SafeAreaView, {
       edges: appBarEdges,
-      children: appBar
-    }) : appBar, /*#__PURE__*/_jsx(SafeAreaView, {
+      children: renderNodeSlot(appBar, slotTextStyle)
+    }) : renderNodeSlot(appBar, slotTextStyle), /*#__PURE__*/_jsx(SafeAreaView, {
       edges: bodyEdges,
       style: bodySafeAreaStyle,
-      children: inner
+      children: scrollWrappedInner
     })]
   }) : null;
   if (hasAppBar) {
@@ -108,11 +151,11 @@ export const Screen = /*#__PURE__*/memo(function Screen({
       testID: testID,
       children: [appBarEdges.length > 0 ? /*#__PURE__*/_jsx(SafeAreaView, {
         edges: appBarEdges,
-        children: appBar
-      }) : appBar, /*#__PURE__*/_jsx(SafeAreaView, {
+        children: renderNodeSlot(appBar, slotTextStyle)
+      }) : renderNodeSlot(appBar, slotTextStyle), /*#__PURE__*/_jsx(SafeAreaView, {
         edges: bodyEdges,
         style: bodySafeAreaStyle,
-        children: inner
+        children: scrollWrappedInner
       })]
     });
   }
@@ -121,7 +164,7 @@ export const Screen = /*#__PURE__*/memo(function Screen({
       edges: edges,
       style: legacyRootStyle,
       testID: testID,
-      children: inner
+      children: scrollWrappedInner
     });
   }
   return /*#__PURE__*/_jsx(KeyboardAvoidingView, {
@@ -132,7 +175,7 @@ export const Screen = /*#__PURE__*/memo(function Screen({
     children: /*#__PURE__*/_jsx(SafeAreaView, {
       edges: edges,
       style: legacySafeAreaStyle,
-      children: inner
+      children: scrollWrappedInner
     })
   });
 });

package/lib/module/modules/screen/ScreenProps.js

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