feat: add stickyPathHeaders prop to ObjectView and update documentation

Author: genwolff

API_DOCUMENTATION.md

@@ -43,6 +43,7 @@ export type ObjectViewProps = {
   arrayGroupSize?: number;
   resolver?: Map<any, ResolverFn>;
   highlightUpdate?: boolean;
+  stickyPathHeaders?: boolean;
   preview?: boolean;
   nonEnumerable?: boolean;
   includeSymbols?: boolean;
@@ -64,6 +65,7 @@ export type ObjectViewProps = {
 | `arrayGroupSize` | `0` | When greater than `1`, adds an array grouping resolver that presents ranges like `[0…49]`. |
 | `resolver` | `undefined` | Custom resolver map merged on top of the built-in resolver map. Keys are constructors; values are `ResolverFn`s. |
 | `highlightUpdate` | `false` | Enables flash-highlighting when a node's value changes. |
+| `stickyPathHeaders` | `true` | Keeps the current ancestor row pinned to the top of the viewport while its children scroll; set to `false` for legacy, non-sticky behaviour. |
 | `preview` | `true` | Shows inline previews (e.g. `Array(10)` or string snippets) for collapsed nodes. |
 | `nonEnumerable` | `false` | Includes non-enumerable properties when traversing objects. |
 | `includeSymbols` | `false` | Includes symbol-keyed properties during traversal and in previews. |

README.md

@@ -12,6 +12,7 @@ React Object View targets React 19 projects (Node 22+ / Yarn 4 recommended) and
 ## ✨ Features
 
 - **Virtualized tree view** – only visible rows render, so 100k+ nodes stay smooth.
+- **Sticky path headers** – pin ancestor rows while scrolling so nested contexts stay visible.
 - **Resolver system** – promises, maps, sets, errors, dates, regexes, iterables, grouped proxies, and custom classes.
 - **Lazy `valueGetter`** – keeps data fresh without forcing heavy re-renders.
 - **Grouping for huge payloads** – `arrayGroupSize` & `objectGroupSize` bucket massive collections (objects must be enumerated first—see note below).
@@ -76,6 +77,7 @@ Wrap dynamic data in `useMemo`/`useCallback` so the virtual tree only re-walks w
 | `arrayGroupSize` | `number` | `0` | Splits very large arrays into range buckets (`[0…999]`) for faster navigation. |
 | `resolver` | `Map<any, ResolverFn>` | `undefined` | Merge in custom resolvers keyed by constructor. |
 | `highlightUpdate` | `boolean` | `false` | Flash updated values via `useChangeFlashClasses`. |
+| `stickyPathHeaders` | `boolean` | `true` | Pins the current node's ancestor label while you scroll through its children; disable to revert to free-scrolling rows. |
 | `preview` | `boolean` | `true` | Show inline previews (`Array(5)`, `'abc…'`) on collapsed rows. |
 | `nonEnumerable` | `boolean` | `false` | Include non-enumerable properties during traversal. |
 | `includeSymbols` | `boolean` | `false` | Include symbol keys when enumerating or previewing objects. |

USAGE_GUIDE.md

@@ -192,6 +192,20 @@ return (
 );
 ```
 
+### Sticky Path Headers
+
+Deeply nested trees can feel disorienting because the parent context scrolls away. Leave `stickyPathHeaders` enabled (default) to pin the current ancestor row while you browse its children, or flip it off when you prefer pure free-flow scrolling:
+
+```tsx
+<ObjectView
+  valueGetter={counterGetter}
+  expandLevel={2}
+  stickyPathHeaders={false} // opt out of the pinning behaviour
+/>
+```
+
+Use this prop when embedding the viewer inside panels with their own sticky headers so you can decide which element controls the vertical stacking order.
+
 ### Line Numbers & Layout Tweaks
 
 Control how each row is rendered and surfaced: