@@ -41,12 +41,13 @@ impl Widget for State {
             .config
             .lines
             .map_or(height as usize, |lines| lines.min(height as usize));
-        let rows = self.document.extract_rows_from_current(height);
-        let line_numbers = self
-            .config
-            .show_line_numbers
-            .then(|| self.document.line_numbers_from_current(height));
-        self.create_graphemes_from_rows(&rows, 0, line_numbers)
+        let (viewport_start, active_row) = self.document.project_viewport(height);
+        let rows = self.document.extract_rows_from(viewport_start, height);
+        let line_numbers = self.config.show_line_numbers.then(|| {
+            self.document
+                .line_numbers_from_viewport(viewport_start, height)
+        });
+        self.create_graphemes_from_rows(&rows, active_row, line_numbers)
     }
 }
 
@@ -97,7 +98,7 @@ impl State {
     /// Interprets a content position in a viewport projection as a semantic target.
     pub fn hit_at_viewport(&self, position: ContentPosition) -> Option<JsonHit> {
         self.document
-            .row_index_at_visible_offset_from_current(position.row)
+            .row_index_at_viewport_position(position.row)
             .map(|row_index| JsonHit::Toggle { row_index })
     }
 }
@@ -113,7 +114,7 @@ mod tests {
     use super::*;
 
     #[test]
-    fn viewport_projection_is_bounded_and_resolves_hits_from_cursor() {
+    fn viewport_projection_is_bounded_and_resolves_hits() {
         let value = serde_json::json!({
             "first": "one",
             "second": {
@@ -126,6 +127,9 @@ mod tests {
             config: Config::default(),
         };
 
+        state.create_graphemes_in_viewport(80, 2);
+        state.document.down();
+        state.create_graphemes_in_viewport(80, 2);
         state.document.down();
         let projected = state.create_graphemes_in_viewport(80, 2);
         let rendered = projected.graphemes.to_string();
@@ -134,7 +138,7 @@ mod tests {
         assert!(rendered.contains("\"second\": {"));
         assert!(!rendered.contains("\"nested\": \"two\""));
         assert!(!rendered.contains("\"third\": \"three\""));
-        assert_eq!(projected.cursor.unwrap().row, 0);
+        assert_eq!(projected.cursor.unwrap().row, 1);
 
         let JsonHit::Toggle { row_index } = state
             .hit_at_viewport(ContentPosition { row: 1, column: 4 })
@@ -145,6 +149,61 @@ mod tests {
         assert!(collapsed.graphemes.to_string().contains("\"second\": {…}"));
     }
 
+    #[test]
+    fn viewport_projection_stays_stable_until_cursor_leaves_it() {
+        let value = serde_json::json!({
+            "first": 1,
+            "second": 2,
+            "third": 3,
+            "fourth": 4
+        });
+        let mut state = State {
+            document: Document::new([&value]),
+            config: Config::default(),
+        };
+
+        let initial = state.create_graphemes_in_viewport(80, 3);
+        assert!(initial.graphemes.to_string().starts_with("{"));
+        assert_eq!(initial.cursor.unwrap().row, 0);
+
+        state.document.down();
+        let moved_inside = state.create_graphemes_in_viewport(80, 3);
+        assert!(moved_inside.graphemes.to_string().starts_with("{"));
+        assert_eq!(moved_inside.cursor.unwrap().row, 1);
+
+        state.document.down();
+        let moved_to_edge = state.create_graphemes_in_viewport(80, 3);
+        assert!(moved_to_edge.graphemes.to_string().starts_with("{"));
+        assert_eq!(moved_to_edge.cursor.unwrap().row, 2);
+
+        state.document.down();
+        let moved_outside = state.create_graphemes_in_viewport(80, 3);
+        assert!(
+            moved_outside
+                .graphemes
+                .to_string()
+                .starts_with("\"first\": 1")
+        );
+        assert_eq!(moved_outside.cursor.unwrap().row, 2);
+
+        state.document.up();
+        let moved_back_inside = state.create_graphemes_in_viewport(80, 3);
+        assert!(
+            moved_back_inside
+                .graphemes
+                .to_string()
+                .starts_with("\"first\": 1")
+        );
+        assert_eq!(moved_back_inside.cursor.unwrap().row, 1);
+
+        state.document.up();
+        state.create_graphemes_in_viewport(80, 3);
+        state.document.up();
+        let moved_above = state.create_graphemes_in_viewport(80, 3);
+        assert!(moved_above.graphemes.to_string().starts_with("{"));
+        assert_eq!(moved_above.cursor.unwrap().row, 0);
+    }
+
     #[test]
     fn configured_line_limit_bounds_viewport_projection() {
         let value = serde_json::json!({"first": 1, "second": 2});
@@ -193,7 +252,7 @@ mod tests {
     }
 
     #[test]
-    fn viewport_projection_uses_stable_line_numbers_from_cursor() {
+    fn viewport_projection_uses_stable_line_numbers() {
         let value = serde_json::json!({"first": 1, "second": 2, "third": 3});
         let mut state = State {
             document: Document::new([&value]),
@@ -203,6 +262,8 @@ mod tests {
             },
         };
 
+        state.create_graphemes_in_viewport(80, 2);
+        state.document.down();
         state.document.down();
         state.document.down();
 
 
@@ -1,17 +1,22 @@
+use std::cell::Cell;
+
 use super::jsonz::{self, Row, RowOperation};
+use crate::structured::{ProjectionViewport, projection_viewport};
 
 /// Represents a navigable JSON document, allowing for efficient row navigation and folding.
 #[derive(Clone)]
 pub struct Document {
     rows: Vec<Row>,
     position: usize,
+    viewport: Cell<ProjectionViewport>,
 }
 
 impl Document {
     pub fn new<'a, I: IntoIterator<Item = &'a serde_json::Value>>(iter: I) -> Self {
         Self {
             rows: jsonz::create_rows(iter),
             position: 0,
+            viewport: Cell::default(),
         }
     }
 }
@@ -27,6 +32,14 @@ impl Document {
         self.rows.extract(self.position, n)
     }
 
+    pub(super) fn project_viewport(&self, n: usize) -> (usize, usize) {
+        projection_viewport(&self.rows, self.position, n, &self.viewport)
+    }
+
+    pub(super) fn extract_rows_from(&self, position: usize, n: usize) -> Vec<Row> {
+        self.rows.extract(position, n)
+    }
+
     /// Returns all currently visible rows from the beginning of the document.
     pub fn visible_rows(&self) -> Vec<Row> {
         self.rows.extract(self.rows.head(), usize::MAX)
@@ -37,9 +50,8 @@ impl Document {
         self.line_numbers_from(self.rows.head(), usize::MAX)
     }
 
-    /// Returns stable one-based line numbers for rows projected from the cursor.
-    pub(super) fn line_numbers_from_current(&self, n: usize) -> Vec<usize> {
-        self.line_numbers_from(self.position, n)
+    pub(super) fn line_numbers_from_viewport(&self, position: usize, n: usize) -> Vec<usize> {
+        self.line_numbers_from(position, n)
     }
 
     /// Returns the number of rows in the fully expanded document.
@@ -92,6 +104,14 @@ impl Document {
         row_index_at_visible_position(&self.rows, self.position, visible_offset)
     }
 
+    pub(super) fn row_index_at_viewport_position(&self, visible_position: usize) -> Option<usize> {
+        let viewport = self.viewport.get();
+        viewport
+            .initialized
+            .then(|| row_index_at_visible_position(&self.rows, viewport.start, visible_position))
+            .flatten()
+    }
+
     /// Sets the visibility of all rows.
     pub fn set_nodes_visibility(&mut self, collapsed: bool) {
         self.rows.set_rows_visibility(collapsed);
 
@@ -10,6 +10,8 @@ pub mod yaml;
 #[cfg_attr(docsrs, doc(cfg(feature = "tree")))]
 pub mod tree;
 
+use std::cell::Cell;
+
 use promkit_core::grapheme::StyledGraphemes;
 
 fn with_line_numbers(
@@ -128,3 +130,107 @@ pub trait RowOperation {
     /// Extract up to `n` visible rows starting from `current`.
     fn extract(&self, current: usize, n: usize) -> Vec<Self::Row>;
 }
+
+#[derive(Clone, Copy, Debug, Default)]
+pub(crate) struct ProjectionViewport {
+    start: usize,
+    cursor: usize,
+    cursor_row: usize,
+    height: usize,
+    initialized: bool,
+}
+
+pub(crate) fn projection_viewport<R>(
+    rows: &Vec<R>,
+    cursor: usize,
+    height: usize,
+    viewport: &Cell<ProjectionViewport>,
+) -> (usize, usize)
+where
+    Vec<R>: RowOperation<Row = R>,
+{
+    if rows.is_empty() || height == 0 {
+        return (rows.head(), 0);
+    }
+
+    let previous = viewport.get();
+    let (start, cursor_row) = if !previous.initialized {
+        place_cursor_from(rows, rows.head(), cursor, height)
+    } else if previous.height != height {
+        place_cursor_from(rows, previous.start, cursor, height)
+    } else if cursor == previous.cursor {
+        (previous.start, previous.cursor_row)
+    } else if cursor > previous.cursor && is_next(rows, previous.cursor, cursor) {
+        if previous.cursor_row + 1 < height {
+            (previous.start, previous.cursor_row + 1)
+        } else {
+            (rows.down(previous.start), height - 1)
+        }
+    } else if cursor < previous.cursor && is_previous(rows, previous.cursor, cursor) {
+        if previous.cursor_row > 0 {
+            (previous.start, previous.cursor_row - 1)
+        } else {
+            (cursor, 0)
+        }
+    } else {
+        place_cursor_from(rows, previous.start, cursor, height)
+    };
+
+    viewport.set(ProjectionViewport {
+        start,
+        cursor,
+        cursor_row,
+        height,
+        initialized: true,
+    });
+    (start, cursor_row)
+}
+
+#[inline]
+fn is_next<R>(rows: &Vec<R>, previous: usize, cursor: usize) -> bool
+where
+    Vec<R>: RowOperation<Row = R>,
+{
+    cursor == previous.saturating_add(1) || rows.down(previous) == cursor
+}
+
+#[inline]
+fn is_previous<R>(rows: &Vec<R>, previous: usize, cursor: usize) -> bool
+where
+    Vec<R>: RowOperation<Row = R>,
+{
+    cursor.saturating_add(1) == previous || rows.up(previous) == cursor
+}
+
+fn place_cursor_from<R>(rows: &Vec<R>, start: usize, cursor: usize, height: usize) -> (usize, usize)
+where
+    Vec<R>: RowOperation<Row = R>,
+{
+    if cursor < start {
+        return (cursor, 0);
+    }
+
+    let mut position = start;
+    for cursor_row in 0..height {
+        if position == cursor {
+            return (start, cursor_row);
+        }
+        let next = rows.down(position);
+        if next == position {
+            break;
+        }
+        position = next;
+    }
+
+    let mut start = cursor;
+    let mut cursor_row = 0;
+    while cursor_row + 1 < height {
+        let previous = rows.up(start);
+        if previous == start {
+            break;
+        }
+        start = previous;
+        cursor_row += 1;
+    }
+    (start, cursor_row)
+}