Merge pull request #78 from re-marked/codex/docs-correct-viewport-box-defaults

docs: correct viewport hook and box defaults

Author: re-marked

README.md

@@ -191,7 +191,7 @@ See [release notes](https://github.com/re-marked/yokai/releases) for what's in e
 | `useApp()` | `{ exit }` |
 | `useStdin()` | Stdin stream + `isRawModeSupported` |
 | `useStdout()` | Stdout stream + `write` |
-| `useTerminalViewport()` | `{ columns, rows }`, updates on resize |
+| `useTerminalViewport()` | `[ref, entry]`, where `entry.isVisible` tracks whether the referenced element is currently in the terminal viewport |
 | `useFocus(options?)` | `{ ref, isFocused, focus }` — per-element focus tracking + imperative focus |
 | `useFocusManager()` | `{ focused, focus, focusNext, focusPrevious, blur }` — global focus actions, reactive to changes |
 | `useInterval(fn, ms)` | Stable interval that cleans up on unmount |

docs/AGENTS.md

@@ -22,7 +22,7 @@ Guide for AI agents writing code that uses yokai. Read this before generating yo
 | `<AlternateScreen mouseTracking pasteThreshold={n}>` | Manually writing `\x1b[?1049h`, `\x1b[?1000h`, `\x1b[?2004h`, parsing `200~`/`201~` for paste |
 | `<ScrollBox stickyScroll>` | Manual scroll-offset tracking + viewport math |
 | `<Link>` | Hand-rolled OSC 8 escape sequences |
-| `useTerminalViewport()` | Reading `process.stdout.columns` directly |
+| `<Box onResize>` / `TerminalSizeContext` | Reading `process.stdout.columns` directly |
 | `useApp().exit()` | `process.exit()` |
 
 The high-level component handles edge cases (lost-release recovery, gesture cancellation on FOCUS_OUT, drag-time z-boost, focus-visible chrome) that hand-rolled equivalents miss.

docs/concepts/layout.md

@@ -10,14 +10,16 @@ Percent values (`width: '50%'`, `marginLeft: '10%'`) resolve against the parent'
 
 ## Defaults
 
+These are the consumer-facing defaults applied by `<Box>`. The underlying Yoga port keeps its own native defaults internally, but `<Box>` sets the values most Yokai apps actually see.
+
 | Property | Yokai default | CSS default |
 |---|---|---|
-| `flexDirection` | `'column'` | `'row'` |
-| `flexShrink` | `0` | `1` |
+| `flexDirection` | `'row'` | `'row'` |
+| `flexShrink` | `1` | `1` |
 | `alignItems` | `'stretch'` | `'stretch'` |
 | `display` | `'flex'` | `'inline'` |
 
-`flexDirection: 'column'` matches Yoga's default and aligns with terminal stacking. `flexShrink: 0` is the port's default — children keep their measured size unless the parent overflows. Set `flexShrink={1}` to opt into CSS-style shrink.
+Use `flexDirection="column"` for the common terminal pattern where rows stack vertically. Set `flexShrink={0}` on chrome that must not collapse, such as title bars, footers, and fixed-width sidebars.
 
 ## Spacing
 

docs/faq.md

@@ -8,7 +8,7 @@ Short answers to recurring questions. Each links to the canonical doc page when
 A React reconciler for the terminal. Pure-TS Yoga flexbox, diff-based screen output, ScrollBox with viewport culling. Mount React components, get ANSI on stdout. See [README](./README.md).
 
 **How is it different from Ink?**
-Forked from Ink via claude-code-kit. Pure-TypeScript Yoga (no WASM), per-cell frame diffing with DECSTBM scroll hints, native ScrollBox with viewport culling, mouse events with gesture capture, drag/drop/resize primitives, focus groups with arrow navigation, alt-screen, z-index for absolutes. `flexShrink` defaults to `0` (matches Yoga, not CSS or Ink).
+Forked from Ink via claude-code-kit. Pure-TypeScript Yoga (no WASM), per-cell frame diffing with DECSTBM scroll hints, native ScrollBox with viewport culling, mouse events with gesture capture, drag/drop/resize primitives, focus groups with arrow navigation, alt-screen, z-index for absolutes. The public `<Box>` component defaults `flexShrink` to `1` (matching CSS and Ink) while the low-level Yoga port keeps Yoga's native defaults internally.
 
 **When NOT to use yokai?**
 For one-shot CLI output (a `--help` screen, a single status line) reach for plain `console.log` or `chalk`. yokai's payoff is interactive trees and sustained renders.
@@ -32,8 +32,8 @@ Standard package install. The build artifacts are emitted by the workspace; no s
 **Why is my Box empty?**
 A Box with no `width`/`height` and no children collapses to zero. Add `flexGrow={1}` to take available space, or set explicit dimensions. See [styles reference](./reference/styles.md).
 
-**Why does flexShrink behave differently from CSS?**
-Yokai inherits Yoga's default of `flexShrink: 0`. CSS and Ink default to `1`. To allow a child to shrink past content size, set `flexShrink={1}` explicitly. See [styles reference](./reference/styles.md).
+**Why does my fixed chrome collapse under layout pressure?**
+`<Box>` defaults to `flexShrink={1}`, matching CSS and Ink. That is usually right for content, but fixed chrome such as title bars, footers, and sidebars should opt out with `flexShrink={0}`. See [styles reference](./reference/styles.md).
 
 **Why is my absolute element not where I put it?**
 `top`/`left`/`right`/`bottom` are relative to the nearest positioned ancestor (the parent Box, in yokai). Percent strings are percent of parent. `zIndex` is honored only on `position: 'absolute'` and only sorts among siblings of the same parent. See [styles reference](./reference/styles.md).
@@ -71,7 +71,7 @@ The capture cannot be released mid-flight (matches `setPointerCapture`). Track a
 ## Resize
 
 **Why does my content get clipped?**
-`<Resizable>` clips overflow by default — content larger than the resized box is hidden. Set the inner content to `flexShrink={1}` or use a ScrollBox inside.
+`<Resizable>` clips overflow by default — content larger than the resized box is hidden. Let flexible inner content keep the default `flexShrink={1}`, mark fixed chrome with `flexShrink={0}`, or use a ScrollBox inside.
 
 **Can I shrink past content size?**
 Yes — pass `minSize={{ width: 1, height: 1 }}` or whatever floor you want. The default min is content size.
@@ -85,4 +85,4 @@ Use `import { logForDebugging } from '@yokai-tui/shared'`. Direct `console.log`
 Use `renderSync` with a fake `stdout`, then assert on the captured frame. See [testing guide](./guides/testing.md).
 
 **How do I handle terminal resize?**
-Read viewport reactively via `useTerminalViewport()`, or bind `onResize` on a Box. SIGWINCH can pulse rapidly during a window-drag-resize — debounce reactive reads. See [troubleshooting](./troubleshooting.md).
+Bind `onResize` on a Box to receive `{ columns, rows }` from SIGWINCH. `useTerminalViewport()` is for visibility tracking of a referenced element, not terminal dimensions. Resize can pulse rapidly during a window-drag-resize, so debounce expensive state updates. See [troubleshooting](./troubleshooting.md).

docs/guides/debugging.md

@@ -80,5 +80,5 @@ See [troubleshooting.md](./troubleshooting.md). The frequent ones:
 - Output mixes with `console.log` → set `patchConsole: true` (default) or write to stderr
 - Mouse events do nothing → wrap the tree in `<AlternateScreen>`
 - `useFocus` reports never-focused → attach `ref` AND pass `tabIndex={0}` on the Box
-- Layout collapses unexpectedly → set `flexShrink={1}` (yokai's default is 0, not 1)
+- Layout chrome collapses unexpectedly -> set `flexShrink={0}` on title bars, footers, and other fixed chrome
 - Ctrl+C does not exit → check `exitOnCtrlC: true` on render options, or that no `useInput` handler is swallowing the event

docs/guides/migration-from-ink.md

@@ -69,13 +69,9 @@ Yokai honors `Styles.zIndex` on `position: 'absolute'` nodes. Stacking is per-pa
 
 ### Pure-TS Yoga
 
-Layout runs through `@yokai-tui/shared`'s pure-TypeScript flexbox engine — no WASM, no native binding. One default differs from Ink:
+Layout runs through `@yokai-tui/shared`'s pure-TypeScript flexbox engine — no WASM, no native binding. The low-level Yoga port keeps Yoga's native defaults internally, but the public `<Box>` component applies Ink/CSS-like defaults (`flexDirection="row"`, `flexShrink={1}`).
 
-| Property | Ink default | yokai default |
-|----------|-------------|---------------|
-| `flexShrink` | 1 (CSS) | 0 |
-
-Existing Ink layouts that relied on automatic shrinking need `flexShrink={1}` set explicitly.
+If fixed chrome such as title bars, footers, or sidebars disappears under layout pressure, set `flexShrink={0}` on that chrome.
 
 ## Removed / renamed APIs
 

docs/reference/events.md

@@ -207,7 +207,7 @@ Terminal resize. Source: `events/resize-event.ts`. Extends `Event`.
 
 **Methods**: `stopImmediatePropagation()`.
 
-**Fires when**: SIGWINCH on the controlling stdout. Bound via `onResize` on `<Box>` (bubble only) or read reactively via `useTerminalViewport`.
+**Fires when**: SIGWINCH on the controlling stdout. Bound via `onResize` on `<Box>` (bubble only). `useTerminalViewport()` is a referenced-element visibility hook and does not expose terminal `{ columns, rows }`.
 
 **Propagation**: bubble only.
 

docs/reference/styles.md

@@ -25,9 +25,9 @@ Every property on the `Styles` type. Source: `packages/renderer/src/styles.ts`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `flexDirection` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `'column'` | Yoga default |
+| `flexDirection` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `'row'` | `<Box>` default; pass `'column'` for stacked rows |
 | `flexGrow` | `number` | `0` | |
-| `flexShrink` | `number` | `0` | **Differs from CSS / Ink (which default to 1).** Pass `1` to enable shrinking |
+| `flexShrink` | `number` | `1` | `<Box>` default matches CSS / Ink. Pass `0` for chrome that must not collapse |
 | `flexBasis` | `number \| string` | `NaN` | Cells or percent string |
 | `flexWrap` | `'nowrap' \| 'wrap' \| 'wrap-reverse'` | `'nowrap'` | |
 | `alignItems` | `'flex-start' \| 'center' \| 'flex-end' \| 'stretch'` | `'stretch'` | Cross-axis |

docs/troubleshooting.md

@@ -16,19 +16,19 @@ Tab cycling is global; arrow navigation is opt-in. Wrap the focusable region in
 
 ### Box overflows its parent
 
-Yoga does not shrink children by default. Set `flexShrink={1}` on the child, or `overflow="hidden"` on the parent to clip. For text, also set `wrap="truncate"` or similar.
+`<Box>` children shrink by default (`flexShrink={1}`), matching CSS and Ink. If overflow is intentional chrome, set `flexShrink={0}` on that fixed child; otherwise add `overflow="hidden"` on the parent to clip. For text, also set `wrap="truncate"` or similar.
 
 ### Text is cut off mid-word
 
-Set `wrap="wrap"` on the `<Text>`, or widen the parent container. Wrapping respects terminal width via `useTerminalViewport`. For fixed columns, set `width` on the enclosing Box.
+Set `wrap="wrap"` on the `<Text>`, or widen the parent container. Wrapping follows the terminal width reported through layout/resize; for fixed columns, set `width` on the enclosing Box.
 
 ### Colors don't show
 
 Check the terminal's color capability. Set `FORCE_COLOR=1` to override detection in pipes and CI. `FORCE_COLOR=3` forces 24-bit. If colors render as raw ANSI escapes in output, the terminal is not interpreting them — check `TERM` is set.
 
 ### Layout flickers on resize
 
-Debounce reactive reads from `useTerminalViewport`, or batch state changes in a single `setState` call. Resize fires SIGWINCH, which can pulse rapidly during a drag-resize of the terminal window itself.
+Debounce `onResize` work, or batch state changes in a single `setState` call. Resize fires SIGWINCH, which can pulse rapidly during a drag-resize of the terminal window itself. `useTerminalViewport()` tracks referenced-element visibility, not terminal dimensions.
 
 ### Drag handle doesn't respond after I add a wrapper around it