@@ -61,14 +61,14 @@ This helper is for **content subtrees** whose height is not externally constrain
6161
6262 ### Systems
6363
64-| System | Description |
65-| -------------------------- | --------------------------------------------------------- |
66-| Flexbox layout engine | Sizing, alignment, gap |
67-| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar |
68-| Layering | Multiple viewport layers, composited bottom-to-top |
69-| Mouse/scroll hit detection | Pointer-driven, topmost layer first, innermost node wins |
70-| Focus management | Keyboard-driven, for `TextInput` and clickable containers |
71-| Keyboard input | Kitty-first input with tmux/legacy compatibility |
64+| System | Description |
65+| -------------------------- | ------------------------------------------------------------ |
66+| Flexbox layout engine | Sizing, alignment, gap |
67+| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar |
68+| Layering | Multiple viewport layers, composited bottom-to-top |
69+| Mouse/scroll hit detection | Pointer-driven, topmost layer first, innermost-first routing |
70+| Focus management | Keyboard-driven, for `TextInput` and clickable containers |
71+| Keyboard input | Kitty-first input with tmux/legacy compatibility |
7272
7373 ---
7474
@@ -94,32 +94,34 @@ HStack(props, children);
9494
9595 Shared by both VStack and HStack. Containers also accept styling props (see [Styling](#styling)).
9696
97-| Prop | Type | Description |
98-| ---------------- | -------------------------------------------------------------------------- | --------------------------------------------------- |
99-| `width` | `number \| string` | Fixed cells or percentage (`"50%"`) |
100-| `height` | `number \| string` | Fixed cells or percentage (`"100%"`) |
101-| `flex` | `number` | Flex grow factor, proportional to siblings |
102-| `minWidth` | `number` | Minimum width constraint |
103-| `maxWidth` | `number` | Maximum width constraint |
104-| `minHeight` | `number` | Minimum height constraint |
105-| `maxHeight` | `number` | Maximum height constraint |
106-| `padding` | `{ x?: number, y?: number }` | Internal padding (cells) |
107-| `gap` | `number` | Spacing between children (cells) |
108-| `justifyContent` | `string` | Distribute children along the main axis |
109-| `alignItems` | `string` | Align children along the cross axis |
110-| `flexWrap` | `"nowrap" \| "wrap"` | Wrap children to next line (HStack only) |
111-| `overflow` | `"hidden" \| "scroll"` | Content overflow behavior (default: `"hidden"`) |
112-| `scrollbar` | `boolean` | Show scrollbar indicator |
113-| `scrollStep` | `number` | Mouse wheel step in cells (default: adaptive) |
114-| `scrollOffset` | `number` | Scroll position in cells (controlled) |
115-| `onScroll` | `(offset: number, maxOffset: number) => void` | Called on scroll input |
116-| `onClick` | `() => void` | Called on mouse click or Enter when focused |
117-| `focusable` | `boolean` | Opt out of focus (default: `true` if `onClick`) |
118-| `focused` | `boolean` | Whether this element is focused (controlled) |
119-| `onFocus` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element receives focus |
120-| `onBlur` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element loses focus |
121-| `focusStyle` | `StyleProps` | Style overrides applied when focused |
122-| `onKeyPress` | `(key: string) => boolean \| void` | Key event handler. Return `false` to keep bubbling. |
97+| Prop | Type | Description |
98+| ---------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
99+| `width` | `number \| string` | Fixed cells or percentage (`"50%"`) |
100+| `height` | `number \| string` | Fixed cells or percentage (`"100%"`) |
101+| `flex` | `number` | Flex grow factor, proportional to siblings |
102+| `minWidth` | `number` | Minimum width constraint |
103+| `maxWidth` | `number` | Maximum width constraint |
104+| `minHeight` | `number` | Minimum height constraint |
105+| `maxHeight` | `number` | Maximum height constraint |
106+| `padding` | `{ x?: number, y?: number }` | Internal padding (cells) |
107+| `gap` | `number` | Spacing between children (cells) |
108+| `justifyContent` | `string` | Distribute children along the main axis |
109+| `alignItems` | `string` | Align children along the cross axis |
110+| `flexWrap` | `"nowrap" \| "wrap"` | Wrap children to next line (HStack only) |
111+| `overflow` | `"hidden" \| "scroll"` | Content overflow behavior (default: `"hidden"`) |
112+| `scrollbar` | `boolean` | Show scrollbar indicator |
113+| `scrollStep` | `number` | Mouse wheel step in cells (default: adaptive) |
114+| `scrollOffset` | `number` | Scroll position in cells (controlled) |
115+| `onScroll` | `ScrollHandler` | Called on scroll input. Return `false` to keep bubbling. |
116+| `onClick` | `() => void` | Called on mouse click or Enter when focused |
117+| `focusable` | `boolean` | Opt out of focus (default: `true` if `onClick`) |
118+| `focused` | `boolean` | Whether this element is focused (controlled) |
119+| `onFocus` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element receives focus |
120+| `onBlur` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element loses focus |
121+| `focusStyle` | `StyleProps` | Style overrides applied when focused |
122+| `onKeyPress` | `(key: string) => boolean \| void` | Key event handler. Return `false` to keep bubbling. |
123+
124+`ScrollHandler` is `((offset: number, maxOffset: number) => void) | ((offset: number, maxOffset: number) => boolean)`. Only an exact `false` return continues propagation to the next scrollable ancestor; any other return value consumes the scroll event. The union preserves source compatibility for legacy void callbacks whose expression bodies incidentally return another value.
123125
124126 ### Sizing
125127
@@ -260,6 +262,8 @@ VStack({
260262
261263 In controlled mode, mouse wheel events fire `onScroll` with the new offset and maximum offset (total content size minus viewport size); the UI only moves when the app passes the updated `scrollOffset` back.
262264
265+For containers, `onScroll` may return `false` to decline handling and continue scroll propagation to the next scrollable ancestor. Any other return value (`undefined`, `true`, or no return) consumes the scroll event and stops propagation, preserving backward compatibility with existing void handlers.
266+
263267 ### Scroll Step
264268
265269 Mouse wheel scrolling moves by a configurable **step size** measured in cells along the container's main axis.
@@ -319,12 +323,14 @@ Scroll is **pointer-driven**, not focus-driven. Mouse wheel events are routed sp
319323 1. Terminal reports mouse position via SGR mouse mode
320324 2. Starting from the **topmost layer**, find the deepest node at `(x, y)`
321325 3. If the layer has a node at that position, it handles the event. Otherwise, try the next layer down.
322-4. For scroll: walk up the ancestor chain to find the nearest scrollable node (container with `overflow: "scroll"`, or TextInput)
326+4. For scroll: walk up the ancestor chain from the deepest hit node, considering scrollable nodes innermost-first (containers with `overflow: "scroll"`, or TextInput)
323327 5. For click: walk up to find the nearest container with `onClick`
324328
325329 ### Nested Scrollable Containers
326330
327-**Innermost scrollable wins.** The deepest scrollable ancestor of the hit target handles the event.
331+Wheel events start at the deepest scrollable ancestor of the hit target. For scrollable containers, if the container's `onScroll` returns `false`, the event continues to the next scrollable ancestor. Otherwise, that first target handles the event and propagation stops. Existing void `onScroll` handlers preserve current behavior because `undefined` consumes the event.
332+
333+TextInput participates as a scrollable target with framework-managed scroll, but it does not expose `onScroll`; once a TextInput is the scroll target, it handles wheel input directly.
328334
329335 ### Architecture Requirements