feat(tui): add page-scroll keys and / filter alias

- PgDn/PgUp and Ctrl-D/Ctrl-U move by half the visible pager height in
  the main lists, the session detail pager, the help pager, and the P
  overlay (model cursor and per-model session list)
- / opens the live fuzzy filter, an alias for f, in the main views and
  the P overlay; help and footer advertise both
- the mouse wheel over the open help overlay now scrolls it instead of
  closing it; a plain click still closes

Author: Gheat1

src/opentab/tui/app.py

@@ -2472,6 +2472,14 @@ def move(self, delta: int) -> None:
             if n:
                 self.day_index = max(0, min(self.day_index + delta, n - 1))
 
+    def _page_step(self, stdscr: curses.window | None) -> int:
+        # Half the visible pager height (the window minus chrome, mirroring
+        # Renderer.max_scroll) -- the PgDn/PgUp and Ctrl-D/Ctrl-U stride.
+        if stdscr is None:
+            return 10
+        height, _width = stdscr.getmaxyx()
+        return max(1, (height - 9) // 2)
+
     def jump(self, to_end: bool, stdscr: curses.window | None = None) -> None:
         if self.view == "browse":
             if self.browse_mode == "projects":
@@ -2741,12 +2749,16 @@ def handle_key(self, stdscr: curses.window, key: int) -> bool:
         if self.price_prompt:
             return self.handle_price_prompt_key(key)
         if self.help:
-            # A pager like the price overlay: j/k/arrows and g/G scroll;
+            # A pager like the price overlay: j/k/arrows, page keys and g/G scroll;
             # any other key closes it.
             if key in (ord("j"), curses.KEY_DOWN):
                 self.help_scroll += 1
             elif key in (ord("k"), curses.KEY_UP):
                 self.help_scroll = max(0, self.help_scroll - 1)
+            elif key in (curses.KEY_NPAGE, 4):  # PgDn / Ctrl-D
+                self.help_scroll += self._page_step(stdscr)  # clamped on draw
+            elif key in (curses.KEY_PPAGE, 21):  # PgUp / Ctrl-U
+                self.help_scroll = max(0, self.help_scroll - self._page_step(stdscr))
             elif key == ord("g"):
                 self.help_scroll = 0
             elif key == ord("G"):
@@ -2760,8 +2772,8 @@ def handle_key(self, stdscr: curses.window, key: int) -> bool:
             if self.filter_active:
                 return self.handle_filter_key(key)
             if self.prices_model is not None:
-                return self._handle_price_sessions_key(key)
-            return self._handle_price_models_key(key)
+                return self._handle_price_sessions_key(key, stdscr)
+            return self._handle_price_models_key(key, stdscr)
         if self.trends:
             current = self.trend_tabs[self.trend_tab % len(self.trend_tabs)]
             if current == "Calendar":
@@ -2890,7 +2902,7 @@ def handle_key(self, stdscr: curses.window, key: int) -> bool:
         if key == ord("B"):
             self.toggle_bookmarks_view()
             return True
-        if key == ord("f"):
+        if key in (ord("f"), ord("/")):
             if not self.can_filter_current_view():
                 self.notify(
                     "nothing to filter here — open a sessions, projects, or models list", "error"
@@ -2955,6 +2967,12 @@ def handle_key(self, stdscr: curses.window, key: int) -> bool:
         if key in (ord("k"), curses.KEY_UP):
             self.move(-1)
             return True
+        if key in (curses.KEY_NPAGE, 4):  # PgDn / Ctrl-D
+            self.move(self._page_step(stdscr))
+            return True
+        if key in (curses.KEY_PPAGE, 21):  # PgUp / Ctrl-U
+            self.move(-self._page_step(stdscr))
+            return True
         return True
 
     def prices_view_label(self, view: str | None = None) -> str:
@@ -2971,11 +2989,11 @@ def cycle_prices_view(self) -> None:
         self.prices_scroll = 0
         self.notice = f"view: {self.prices_view_label()}"
 
-    def _handle_price_models_key(self, key: int) -> bool:
-        # The P overlay's model list: j/k/arrows move a cursor, g/G jump to ends,
-        # Enter drills into the selected model's sessions, s sorts by a column, p
-        # cycles the layout (by vendor / by provider / flat), f filters, r refreshes,
-        # e exports the table; any other key closes the overlay.
+    def _handle_price_models_key(self, key: int, stdscr: curses.window | None = None) -> bool:
+        # The P overlay's model list: j/k/arrows move a cursor, page keys stride,
+        # g/G jump to ends, Enter drills into the selected model's sessions, s sorts
+        # by a column, p cycles the layout (by vendor / by provider / flat), f
+        # filters, r refreshes, e exports the table; any other key closes the overlay.
         n = len(self.priced_model_names())
         if key in (ord("s"), ord("S")):
             self.open_sort_menu()
@@ -2987,6 +3005,10 @@ def _handle_price_models_key(self, key: int) -> bool:
             self.prices_index = min(self.prices_index + 1, max(0, n - 1))
         elif key in (ord("k"), curses.KEY_UP):
             self.prices_index = max(0, self.prices_index - 1)
+        elif key in (curses.KEY_NPAGE, 4):  # PgDn / Ctrl-D
+            self.prices_index = min(self.prices_index + self._page_step(stdscr), max(0, n - 1))
+        elif key in (curses.KEY_PPAGE, 21):  # PgUp / Ctrl-U
+            self.prices_index = max(0, self.prices_index - self._page_step(stdscr))
         elif key == ord("g"):
             self.prices_index = 0
         elif key == ord("G"):
@@ -2998,7 +3020,7 @@ def _handle_price_models_key(self, key: int) -> bool:
                 self.prices_scroll = 0
         elif key in (ord("r"), ord("R")):
             self.refresh_prices_action()  # keeps the overlay open
-        elif key == ord("f"):
+        elif key in (ord("f"), ord("/")):
             self.filter_active = True
             self._filter_before = self.query
             self.prices_scroll = 0
@@ -3008,13 +3030,18 @@ def _handle_price_models_key(self, key: int) -> bool:
             self.show_prices = False
         return True
 
-    def _handle_price_sessions_key(self, key: int) -> bool:
-        # The P overlay's per-model drill-in: j/k/arrows and g/G scroll the session
-        # list; Esc/left/backspace backs out to the model list; any other key closes.
+    def _handle_price_sessions_key(self, key: int, stdscr: curses.window | None = None) -> bool:
+        # The P overlay's per-model drill-in: j/k/arrows, page keys and g/G scroll the
+        # session list; Esc/left/backspace backs out to the model list; any other key
+        # closes.
         if key in (ord("j"), curses.KEY_DOWN):
             self.prices_scroll += 1
         elif key in (ord("k"), curses.KEY_UP):
             self.prices_scroll = max(0, self.prices_scroll - 1)
+        elif key in (curses.KEY_NPAGE, 4):  # PgDn / Ctrl-D
+            self.prices_scroll += self._page_step(stdscr)  # clamped on draw
+        elif key in (curses.KEY_PPAGE, 21):  # PgUp / Ctrl-U
+            self.prices_scroll = max(0, self.prices_scroll - self._page_step(stdscr))
         elif key == ord("g"):
             self.prices_scroll = 0
         elif key == ord("G"):
@@ -3110,7 +3137,11 @@ def handle_mouse(self) -> bool:
                 self.launch_menu = None  # click cancels the launch picker
             return True
         if self.help:
-            if up or down or click or double:
+            if up:
+                self.help_scroll = max(0, self.help_scroll - 3)
+            elif down:
+                self.help_scroll += 3  # clamped to the last page on draw
+            elif click or double:
                 self.help = False
             return True
         if self.show_prices:

src/opentab/tui/renderer.py

@@ -593,7 +593,7 @@ def draw_footer(self, stdscr: curses.window, height: int, width: int) -> None:
         # appears only where it does something (like "s/S sort").
         parts.append(("R range", self.range_label() != "all time"))
         if self.can_filter_current_view():
-            parts.append(("f filter", bool(self.query)))
+            parts.append(("f,/ filter", bool(self.query)))
         parts += [
             ("T trends", self.trends),
             ("P prices", self.show_prices),
@@ -1987,6 +1987,7 @@ def help_sections(self) -> list[tuple[str, list[tuple]]]:
                         "(per-tool / MCP spend, OpenCode); Sources joins in the merged 'all' view",
                     ),
                     ("j / k", "move in the list (↑/↓ too), or scroll the detail pane"),
+                    ("PgDn/PgUp", "move / scroll by half a page (Ctrl-D / Ctrl-U too)"),
                     ("g / G", "jump to the top / bottom"),
                     (
                         "mouse",
@@ -2005,7 +2006,7 @@ def help_sections(self) -> list[tuple[str, list[tuple]]]:
                     ("a", "show all time, keeping the current selection where possible"),
                     ("s", "open the sort picker for the visible list (j/k move · Enter · Esc)"),
                     (
-                        "f",
+                        "f or /",
                         "live filter — fuzzy over sessions (title/project/id), projects and "
                         "Models; substring over Prices",
                         "while filtering: ↑/↓ select · Enter keep · Esc cancel · Ctrl-U clear",

test_opentab.py

@@ -1396,6 +1396,81 @@ def test_jk_scrolls_the_help_overlay():
     assert not app.help
 
 
+def test_mouse_wheel_scrolls_the_help_overlay():
+    # The wheel over the open help pages it (like the P overlay) instead of
+    # closing it; a plain click still closes.
+    app = app_with([workflow("a", "2026-06-01 12:00:00")])
+    app.handle_key(None, ord("?"))
+    assert app.help and app.help_scroll == 0
+    app._wheel_down = getattr(ot.curses, "BUTTON5_PRESSED", 0) or ot.curses.REPORT_MOUSE_POSITION
+    orig = ot.curses.getmouse
+    try:
+        ot.curses.getmouse = lambda: (0, 0, 0, 0, app._wheel_down)  # wheel down
+        app.handle_mouse()
+        assert app.help and app.help_scroll == 3
+        ot.curses.getmouse = lambda: (0, 0, 0, 0, ot.curses.BUTTON4_PRESSED)  # wheel up
+        app.handle_mouse()
+        assert app.help and app.help_scroll == 0
+        app.handle_mouse()  # floored at the top, still open
+        assert app.help and app.help_scroll == 0
+        ot.curses.getmouse = lambda: (0, 0, 0, 0, ot.curses.BUTTON1_CLICKED)  # click closes
+        app.handle_mouse()
+        assert not app.help
+    finally:
+        ot.curses.getmouse = orig
+
+
+def test_page_keys_stride_lists_by_half_a_screen():
+    # PgDn/PgUp and Ctrl-D/Ctrl-U move by half the visible pager height; headless
+    # (no screen to measure) the stride is a fixed 10 rows.
+    app = app_with([workflow(f"s{i:02d}", "2026-06-01 12:00:00") for i in range(25)])
+    app.view = "zoom"
+    app.tab = app.current_tabs().index("Sessions")
+    app.handle_key(None, ot.curses.KEY_NPAGE)
+    assert app.workflow_index == 10
+    app.handle_key(None, 4)  # Ctrl-D
+    assert app.workflow_index == 20
+    app.handle_key(None, ot.curses.KEY_NPAGE)  # clamped at the last row
+    assert app.workflow_index == 24
+    app.handle_key(None, ot.curses.KEY_PPAGE)
+    assert app.workflow_index == 14
+    app.handle_key(None, 21)  # Ctrl-U
+    assert app.workflow_index == 4
+    app.handle_key(None, 21)  # floored at the top
+    assert app.workflow_index == 0
+    # with a real screen the stride is half the pager height (height - 9)
+    assert app._page_step(FakeScreen(29, 80)) == 10
+    assert app._page_step(FakeScreen(5, 80)) == 1  # never 0 on a tiny window
+
+
+def test_page_keys_scroll_the_detail_help_and_prices_pagers():
+    app = app_with([workflow("a", "2026-06-01 12:00:00", directory="/x")])
+    app.view = "session"
+    app.handle_key(None, ot.curses.KEY_NPAGE)  # detail pager, via move()
+    assert app.scroll == 10
+    app.handle_key(None, 21)  # Ctrl-U back up
+    assert app.scroll == 0
+    app.handle_key(None, ord("?"))  # the help pager
+    app.handle_key(None, 4)  # Ctrl-D
+    assert app.help and app.help_scroll == 10
+    app.handle_key(None, ot.curses.KEY_PPAGE)
+    assert app.help and app.help_scroll == 0
+    app.handle_key(None, ord("q"))  # close help (any other key)
+    app.view = "browse"
+    app._model_by_root = {
+        "a": [
+            _model_row("claude-opus-4-8", 5.0, 10),
+            _model_row("gpt-5-codex", 2.0, 10),
+            _model_row("claude-haiku-4-5", 1.0, 10),
+        ]
+    }
+    app.handle_key(None, ord("P"))  # the P overlay's model cursor
+    app.handle_key(None, ot.curses.KEY_NPAGE)
+    assert app.show_prices and app.prices_index == 2  # clamped to the last of 3 rows
+    app.handle_key(None, 21)
+    assert app.show_prices and app.prices_index == 0
+
+
 def test_help_sections_group_and_cover_the_keymap():
     # The help overlay is grouped; help_sections() is the content source of truth
     # (draw_help only wraps/colours it). Lock the sections and that the load-bearing
@@ -1415,7 +1490,21 @@ def test_help_sections_group_and_cover_the_keymap():
             assert len(row) >= 2 and row[0] and row[1]  # (key, summary, *notes)
             assert all(isinstance(note, str) and note for note in row[2:])
             keys.add(row[0])
-    for binding in ("p / t", "Enter / +", "R", "f", "b / B", "L", "T", "P", "$", "c", "C", "q"):
+    for binding in (
+        "p / t",
+        "Enter / +",
+        "PgDn/PgUp",
+        "R",
+        "f or /",
+        "b / B",
+        "L",
+        "T",
+        "P",
+        "$",
+        "c",
+        "C",
+        "q",
+    ):
         assert binding in keys, f"missing help entry for {binding}"
 
 
@@ -5395,6 +5484,28 @@ def test_f_enters_live_filter_mode():
     assert app.handle_key(None, 3) is False
 
 
+def test_slash_is_an_alias_for_the_filter_key():
+    app = app_with(
+        [
+            workflow("a", "2026-06-01 12:00:00", title="alpha"),
+            workflow("b", "2026-06-02 12:00:00", title="beta"),
+        ]
+    )
+    app.view = "zoom"
+    app.tab = app.current_tabs().index("Sessions")
+    assert app.handle_key(None, ord("/")) and app.filter_active
+    for ch in "bet":
+        app.handle_key(None, ord(ch))
+    assert [w.title for w in app.current_sessions()] == ["beta"]
+    app.handle_key(None, 10)  # Enter keeps the filter and leaves the mode
+    assert not app.filter_active and app.query == "bet"
+    # `/` also opens the P overlay's filter, like `f`
+    app.handle_key(None, ord("x"))  # clear the committed filter first
+    app.handle_key(None, ord("P"))
+    assert app.show_prices and not app.filter_active
+    assert app.handle_key(None, ord("/")) and app.filter_active and app.show_prices
+
+
 def test_f_is_a_noop_where_no_list_is_filtered():
     # The time-browse main view shows Months/Days, not a session/project list, so the
     # query would filter nothing -- "f" must not enter filter mode there, and the