rv-bible-cli 0.1.6 → 0.1.8

package/README.md

@@ -123,6 +123,7 @@ When you read a chapter in a terminal, rvb opens a full-screen interactive reade
 | `d` | enter study mode |
 | `c` | enter copy mode |
 | `/` | find text in current chapter |
+| `?` | search the whole Bible — type a query, browse results, Enter opens |
 | `:` | jump to any book — type `rom 8`, `jn 3`, etc. |
 | `[` / `]` | go back / forward (like browser history) |
 | `H` | go to home screen |
@@ -134,7 +135,7 @@ When you read a chapter in a terminal, rvb opens a full-screen interactive reade
 
 Deep-dive into footnotes and cross-references. Press `d` while reading any chapter.
 
-- A cursor highlights the current verse
+- A cursor highlights the current verse — the chapter view auto-scrolls to keep it vertically centered as you move
 - The bottom panel shows the **full** footnote text for that verse — header line with marker + word + numbered cross-references, then the wrapped commentary body underneath
 - **Type a number** to follow a cross-reference — you'll jump to that chapter and land on the exact verse
 - Press `[` to go back to where you were

package/dist/format.d.ts

@@ -8,6 +8,7 @@ export declare function getZoom(): number;
 export declare function zoomIn(): void;
 export declare function zoomOut(): void;
 export declare function zoomReset(): void;
+export declare function getMargin(): number;
 export declare function wrapWords(text: string, maxWidth: number, ansi?: boolean): string[];
 export declare function renderFootnoteBlock(footnotes: Footnote[]): string;
 export declare function renderNoteDisplayAll(verse: Verse, footnotes: Footnote[], bookName: string): string;

package/dist/format.js

@@ -109,6 +109,9 @@ function contentWidth() {
 function margin() {
     return ' '.repeat(ZOOM_LEVELS[currentZoom].margin);
 }
+export function getMargin() {
+    return ZOOM_LEVELS[currentZoom].margin;
+}
 // ── Visible-length helper ────────────────────────────────────────────────────
 // Strip ANSI escape codes before measuring — needed for word-wrap width checks
 // on text that may contain chalk styling (e.g. highlighted markers in notes mode).

package/dist/index.js

@@ -397,9 +397,7 @@ program
             const bookName = getBookInfo(v.book)?.full_name ?? v.book;
             const ref = `${bookName} ${v.chapter}:${v.verse}`;
             const cleanText = stripMarkers(v.text);
-            // Truncate to ~150 chars for scanability
-            const truncated = cleanText.length > 150 ? cleanText.substring(0, 147) + '...' : cleanText;
-            const highlighted = highlightTerms(truncated, terms);
+            const highlighted = highlightTerms(cleanText, terms);
             // Wrap the text at ~76 chars with 4-space indent
             const maxW = Math.min((process.stdout.columns ?? 80) - 4, 76);
             const words = highlighted.split(' ');

package/dist/ui/Pager.js

@@ -3,8 +3,8 @@ import { useState, useMemo, useEffect, useCallback, useRef } from 'react';
 import { render, Box, Text, useInput, useApp, useStdout } from 'ink';
 import chalk from 'chalk';
 import clipboard from 'clipboardy';
-import { getVersesByRef, getSectionHeaders, getFootnotesForChapter, getFootnotesForVerses, getCrossRefsForVerse, getBookInfo, getAllBooks, } from '../db.js';
-import { renderVerses, stripMarkers, highlightTerms, toSuperscript, wrapWords, zoomIn, zoomOut, zoomReset, getZoom } from '../format.js';
+import { getVersesByRef, getSectionHeaders, getFootnotesForChapter, getFootnotesForVerses, getCrossRefsForVerse, getBookInfo, getAllBooks, isInConcordance, getTopicVerses, searchFTS, } from '../db.js';
+import { renderVerses, stripMarkers, highlightTerms, toSuperscript, wrapWords, zoomIn, zoomOut, zoomReset, getZoom, getMargin } from '../format.js';
 import { saveLastRead, getLastRead } from '../state.js';
 import { resolveBook } from '../parser.js';
 import { getNextChapter, getPrevChapter } from './nav.js';
@@ -12,6 +12,20 @@ import { getNextChapter, getPrevChapter } from './nav.js';
 function stripAnsi(s) {
     return s.replace(/\x1b\[[0-9;]*m/g, '');
 }
+// Footer keybind helpers: magenta for the key, dim for the description,
+// dim middle dot as separator. Keeps "this is a key you can press" visually
+// distinct from the prose around it. When `/` separates two keys in a
+// compound (e.g. `[/]`, `g/G`, `Tab/⇧Tab`), the slash itself drops to dim so
+// the keys stand out. A lone `/` (e.g. the find command) stays magenta.
+function kb(key, desc) {
+    const parts = key.split('/');
+    const isCompound = parts.length > 1 && parts.every(p => p.length > 0);
+    const styledKey = isCompound
+        ? parts.map(k => chalk.magenta(k)).join(chalk.dim('/'))
+        : chalk.magenta(key);
+    return `${styledKey} ${chalk.dim(desc)}`;
+}
+const FOOTER_SEP = chalk.dim(' · ');
 // Detect verse-number lines by checking for chalk.dim() ANSI code (\x1b[2m) before
 // a superscript character. This distinguishes verse numbers (dim) from inline footnote
 // markers (cyan) that could appear at the start of word-wrapped continuation lines.
@@ -125,11 +139,17 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
     // Copy mode state
     const [cursorIdx, setCursorIdx] = useState(0);
     const [selStart, setSelStart] = useState(null);
-    // Search mode state
-    const [searchQuery, setSearchQuery] = useState('');
-    const [searchSubmitted, setSearchSubmitted] = useState(false);
-    const [searchMatches, setSearchMatches] = useState([]);
-    const [matchIdx, setMatchIdx] = useState(0);
+    // Find-in-chapter mode state (the `/` modal)
+    const [findQuery, setFindQuery] = useState('');
+    const [findSubmitted, setFindSubmitted] = useState(false);
+    const [findMatches, setFindMatches] = useState([]);
+    const [findIdx, setFindIdx] = useState(0);
+    // Global search session state (the `?` modal — full Bible search)
+    const [gsearchInput, setGsearchInput] = useState('');
+    const [gsearchSession, setGsearchSession] = useState(null);
+    // Holds the search terms to highlight in the next-rendered chapter (consumed by
+    // a useEffect once `lines` rebuilds). Array so multi-term queries highlight all words.
+    const pendingFindTermsRef = useRef(null);
     // Goto mode state
     const [gotoInput, setGotoInput] = useState('');
     // Navigation history: back/forward stacks (refs so useInput always sees latest)
@@ -277,64 +297,106 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
     useEffect(() => {
         setPanelScrollOffset(0);
     }, [studyCursorIdx, book, chapter, mode]);
-    // Clamp scroll when content or viewport changes
+    // Clamp scroll when content or viewport changes. Normal mode uses the strict
+    // maxScroll clamp (can't scroll past content). Study mode allows overscroll so
+    // the last verse can still center — the visible slice is padded with empty rows
+    // when scrollOffset > maxScroll, keeping the panel anchored to the bottom.
     const maxScroll = Math.max(0, lines.length - viewportH);
+    const overscrollLimit = Math.max(0, lines.length - 1);
     useEffect(() => {
-        setScrollOffset(prev => Math.min(prev, maxScroll));
-    }, [maxScroll]);
-    // Keep the study-mode cursor verse fully visible above the footnote panel.
-    // Triggers when cursor moves OR viewport shrinks (panel grew with longer notes).
+        if (mode !== 'study') {
+            setScrollOffset(prev => Math.min(prev, maxScroll));
+        }
+        else {
+            setScrollOffset(prev => Math.min(prev, overscrollLimit));
+        }
+    }, [maxScroll, overscrollLimit, mode]);
+    // Center the cursor verse in study mode. If the verse fits in the viewport,
+    // place its midpoint at viewportH/2. If the verse is taller than the viewport
+    // (rare — long verse with markers wrapping), pin its start to the top so the
+    // beginning is always visible. Triggers on cursor move and viewport resize.
     useEffect(() => {
         if (mode !== 'study' || verseMap.length === 0)
             return;
         const entry = verseMap[studyCursorIdx];
         if (!entry)
             return;
-        setScrollOffset(prev => {
-            // Cursor verse extends below the visible viewport — pull it in from the bottom
-            if (entry.endLine >= prev + viewportH) {
-                return Math.max(0, entry.endLine - viewportH + 1);
-            }
-            // Cursor verse starts above the visible viewport — pull it in from the top
-            if (entry.startLine < prev) {
-                return entry.startLine;
-            }
-            return prev;
-        });
-    }, [studyCursorIdx, viewportH, mode, verseMap]);
+        const verseH = entry.endLine - entry.startLine + 1;
+        let target;
+        if (verseH >= viewportH) {
+            target = entry.startLine;
+        }
+        else {
+            const verseMid = entry.startLine + Math.floor(verseH / 2);
+            target = verseMid - Math.floor(viewportH / 2);
+        }
+        target = Math.max(0, Math.min(target, overscrollLimit));
+        setScrollOffset(target);
+    }, [studyCursorIdx, viewportH, mode, verseMap, overscrollLimit]);
     // ── Search highlights ────────────────────────────────────────────────────
+    // Highlights every space-separated token in findQuery (so multi-term gsearch
+    // results like "only begotten" light up both words). For pure single-word find,
+    // this collapses to the original single-term behavior.
     const displayLines = useMemo(() => {
-        if (!searchSubmitted || searchMatches.length === 0)
+        if (!findSubmitted || findMatches.length === 0)
             return lines;
-        const q = searchQuery.toLowerCase();
+        const queryTerms = findQuery.split(/\s+/).filter(Boolean);
+        if (queryTerms.length === 0)
+            return lines;
+        const lowers = queryTerms.map(t => t.toLowerCase());
         return lines.map((line) => {
             const stripped = stripAnsi(line);
-            if (!stripped.toLowerCase().includes(q))
+            const lower = stripped.toLowerCase();
+            if (!lowers.some(l => lower.includes(l)))
                 return line;
-            return highlightTerms(stripped, [searchQuery]);
+            return highlightTerms(stripped, queryTerms);
         });
-    }, [lines, searchSubmitted, searchMatches, searchQuery]);
+    }, [lines, findSubmitted, findMatches, findQuery]);
     // ── Navigation helpers ───────────────────────────────────────────────────
     const restoreMode = useCallback(() => {
         setMode(studyActiveRef.current ? 'study' : 'normal');
-        setSearchSubmitted(false);
-        setSearchQuery('');
-        setSearchMatches([]);
+        setFindSubmitted(false);
+        setFindQuery('');
+        setFindMatches([]);
         setStudyRefInput('');
         setStudyCursorIdx(0);
     }, []);
     const navigate = useCallback((newBook, newChapter, pushHistory = true) => {
         const sameChapter = newBook === bookRef.current && newChapter === chapterRef.current;
-        // Same-chapter cross-ref follow: jump cursor directly. Don't reset state via
-        // restoreMode (would clobber cursor to 0), don't push to history (cursor isn't tracked there).
+        // Same-chapter target: jump cursor (study) or scroll (normal) directly without
+        // re-rendering the chapter. Exits any modal mode (gsearch-list, etc.) via restoreMode.
         if (sameChapter && pendingVerseRef.current) {
             const target = pendingVerseRef.current;
             pendingVerseRef.current = null;
             let idx = verseMap.findIndex(e => e.verse === target);
             if (idx < 0)
                 idx = verseMap.findIndex(e => e.verse.startsWith(target));
-            if (idx >= 0)
-                setStudyCursorIdx(idx);
+            if (idx >= 0) {
+                const entry = verseMap[idx];
+                if (studyActiveRef.current) {
+                    setStudyCursorIdx(idx);
+                }
+                else {
+                    setScrollOffset(Math.max(0, entry.startLine - 2));
+                }
+            }
+            // Highlight pending terms in current chapter (no new `lines` to trigger the effect).
+            const terms = pendingFindTermsRef.current;
+            if (terms && terms.length > 0) {
+                pendingFindTermsRef.current = null;
+                const lowers = terms.map(t => t.toLowerCase());
+                const matches = [];
+                for (let i = 0; i < lines.length; i++) {
+                    const lower = stripAnsi(lines[i]).toLowerCase();
+                    if (lowers.some(l => lower.includes(l)))
+                        matches.push(i);
+                }
+                setFindQuery(terms.join(' '));
+                setFindMatches(matches);
+                setFindSubmitted(true);
+                setFindIdx(0);
+            }
+            setMode(studyActiveRef.current ? 'study' : 'normal');
             saveLastRead(newBook, newChapter);
             return;
         }
@@ -347,7 +409,7 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         setScrollOffset(0);
         restoreMode();
         saveLastRead(newBook, newChapter);
-    }, [restoreMode, verseMap]);
+    }, [restoreMode, verseMap, lines]);
     const goBack = useCallback(() => {
         const hist = historyRef.current;
         if (hist.length === 0)
@@ -415,35 +477,149 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         setSelStart(null);
     }, [selStart, cursorIdx, verses, bookName, chapter]);
     // ── Search helpers ───────────────────────────────────────────────────────
-    const submitSearch = useCallback(() => {
-        if (!searchQuery)
+    const submitFind = useCallback(() => {
+        if (!findQuery)
+            return;
+        const queryTerms = findQuery.split(/\s+/).filter(Boolean);
+        if (queryTerms.length === 0)
             return;
-        const q = searchQuery.toLowerCase();
+        const lowers = queryTerms.map(t => t.toLowerCase());
         const matches = [];
         for (let i = 0; i < lines.length; i++) {
-            if (stripAnsi(lines[i]).toLowerCase().includes(q))
+            const lower = stripAnsi(lines[i]).toLowerCase();
+            if (lowers.some(l => lower.includes(l)))
                 matches.push(i);
         }
-        setSearchMatches(matches);
-        setSearchSubmitted(true);
-        setMatchIdx(0);
+        setFindMatches(matches);
+        setFindSubmitted(true);
+        setFindIdx(0);
         if (matches.length > 0)
             scrollTo(matches[0]);
-    }, [searchQuery, lines, scrollTo]);
-    const nextMatch = useCallback(() => {
-        if (searchMatches.length === 0)
+    }, [findQuery, lines, scrollTo]);
+    const nextFindMatch = useCallback(() => {
+        if (findMatches.length === 0)
+            return;
+        const next = (findIdx + 1) % findMatches.length;
+        setFindIdx(next);
+        scrollTo(findMatches[next]);
+    }, [findIdx, findMatches, scrollTo]);
+    const prevFindMatch = useCallback(() => {
+        if (findMatches.length === 0)
             return;
-        const next = (matchIdx + 1) % searchMatches.length;
-        setMatchIdx(next);
-        scrollTo(searchMatches[next]);
-    }, [matchIdx, searchMatches, scrollTo]);
-    const prevMatch = useCallback(() => {
-        if (searchMatches.length === 0)
+        const prev = (findIdx - 1 + findMatches.length) % findMatches.length;
+        setFindIdx(prev);
+        scrollTo(findMatches[prev]);
+    }, [findIdx, findMatches, scrollTo]);
+    // ── Global search helpers (the `?` modal — full Bible search) ─────────────
+    // Page size for paginating results in the gsearch-list view (←/→ to page).
+    const GSEARCH_PAGE_SIZE = 100;
+    // Parse "in <book>" scope from tokens (mirrors CLI parseScope behavior)
+    const parseGsearchScope = useCallback((tokens) => {
+        for (let nameLen = 3; nameLen >= 1; nameLen--) {
+            const inIdx = tokens.length - nameLen - 1;
+            if (inIdx < 1)
+                continue;
+            if (tokens[inIdx]?.toLowerCase() !== 'in')
+                continue;
+            const resolved = resolveBook(tokens.slice(inIdx + 1, inIdx + 1 + nameLen).join(' '));
+            if (resolved)
+                return { queryTokens: tokens.slice(0, inIdx), book: resolved };
+        }
+        return { queryTokens: tokens, book: undefined };
+    }, []);
+    // Run the search. Single known concordance word → concordance, else FTS LIKE.
+    // Returns ALL results — pagination happens at render time (GSEARCH_PAGE_SIZE per page).
+    const executeGsearch = useCallback((rawInput) => {
+        const trimmed = rawInput.trim();
+        if (!trimmed)
+            return null;
+        const tokens = trimmed.split(/\s+/);
+        const { queryTokens, book: scopeBook } = parseGsearchScope(tokens);
+        if (queryTokens.length === 0)
+            return null;
+        const word = queryTokens.join(' ');
+        let results;
+        let terms;
+        if (queryTokens.length === 1 && isInConcordance(word)) {
+            results = getTopicVerses(word, scopeBook);
+            terms = [word];
+        }
+        else {
+            const ftsQuery = queryTokens.length === 1
+                ? `"${queryTokens[0].replace(/"/g, '')}"`
+                : queryTokens.map(t => `"${t.replace(/"/g, '')}"`).join(' AND ');
+            results = searchFTS(ftsQuery, scopeBook);
+            terms = queryTokens.map(t => t.replace(/"/g, '').trim()).filter(Boolean);
+        }
+        return { query: trimmed, results, terms, cursor: 0, pageIdx: 0 };
+    }, [parseGsearchScope]);
+    // Build the rendered result list lines + per-result line ranges (for cursor scroll).
+    // Renders only the current page (GSEARCH_PAGE_SIZE results); the cursor index in
+    // the session is page-local, so itemMap aligns directly.
+    const gsearchListData = useMemo(() => {
+        if (!gsearchSession)
+            return null;
+        const { results, terms, cursor, pageIdx } = gsearchSession;
+        const start = pageIdx * GSEARCH_PAGE_SIZE;
+        const pageResults = results.slice(start, start + GSEARCH_PAGE_SIZE);
+        const renderLines = [];
+        const itemMap = [];
+        const wrapWidth = Math.max(40, Math.min(cols - 10, 90));
+        pageResults.forEach((v, i) => {
+            const startLine = renderLines.length;
+            const bn = getBookInfo(v.book)?.full_name ?? v.book;
+            const ref = `${bn} ${v.chapter}:${v.verse}`;
+            const cleanText = stripMarkers(v.text);
+            const highlighted = highlightTerms(cleanText, terms);
+            const wrapped = wrapWords(highlighted, wrapWidth, true);
+            const mark = i === cursor ? chalk.magenta('›') : ' ';
+            renderLines.push(`  ${mark} ${chalk.bold(ref)}`);
+            for (const wl of wrapped)
+                renderLines.push(`      ${wl}`);
+            const endLine = renderLines.length - 1;
+            renderLines.push(''); // blank separator
+            itemMap.push({ startLine, endLine });
+        });
+        return { lines: renderLines, itemMap, pageResults };
+    }, [gsearchSession, cols]);
+    // Center the cursor result in the list viewport (same pattern as study mode).
+    const gsearchScroll = useMemo(() => {
+        if (mode !== 'gsearch-list' || !gsearchSession || !gsearchListData)
+            return 0;
+        const item = gsearchListData.itemMap[gsearchSession.cursor];
+        if (!item)
+            return 0;
+        const itemH = item.endLine - item.startLine + 1;
+        let target;
+        if (itemH >= viewportH) {
+            target = item.startLine;
+        }
+        else {
+            const itemMid = item.startLine + Math.floor(itemH / 2);
+            target = itemMid - Math.floor(viewportH / 2);
+        }
+        return Math.max(0, Math.min(target, Math.max(0, gsearchListData.lines.length - 1)));
+    }, [mode, gsearchSession, gsearchListData, viewportH]);
+    // After navigate from a search result, highlight ALL search terms in the new chapter
+    // (piggybacks on the chapter-find code path so n/N cycling works too). Doesn't
+    // scroll — the pendingVerseRef effect already positioned the cursor on the picked verse.
+    useEffect(() => {
+        const terms = pendingFindTermsRef.current;
+        if (!terms || terms.length === 0 || lines.length === 0)
             return;
-        const prev = (matchIdx - 1 + searchMatches.length) % searchMatches.length;
-        setMatchIdx(prev);
-        scrollTo(searchMatches[prev]);
-    }, [matchIdx, searchMatches, scrollTo]);
+        pendingFindTermsRef.current = null;
+        const lowers = terms.map(t => t.toLowerCase());
+        const matches = [];
+        for (let i = 0; i < lines.length; i++) {
+            const lower = stripAnsi(lines[i]).toLowerCase();
+            if (lowers.some(l => lower.includes(l)))
+                matches.push(i);
+        }
+        setFindQuery(terms.join(' '));
+        setFindMatches(matches);
+        setFindSubmitted(true);
+        setFindIdx(0);
+    }, [lines]);
     // ── Goto helpers ─────────────────────────────────────────────────────────
     const submitGoto = useCallback(() => {
         const trimmed = gotoInput.trim();
@@ -532,8 +708,8 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
                 if (matches.length > 0) {
                     if (lower === lastLetterRef.current) {
                         // Same letter again: cycle to next match after current position
-                        const nextMatch = matches.find(m => m.i > homeIdx) ?? matches[0];
-                        setHomeIdx(nextMatch.i);
+                        const nextLetterMatch = matches.find(m => m.i > homeIdx) ?? matches[0];
+                        setHomeIdx(nextLetterMatch.i);
                     }
                     else {
                         setHomeIdx(matches[0].i);
@@ -583,35 +759,145 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             }
             return;
         }
-        // ── Search mode ──────────────────────────────────────────────────────
-        if (mode === 'search') {
+        // ── Find-in-chapter mode (`/` modal) ────────────────────────────────
+        if (mode === 'find') {
             const returnMode = studyActiveRef.current ? 'study' : 'normal';
             if (key.escape) {
                 setMode(returnMode);
-                setSearchQuery('');
-                setSearchSubmitted(false);
-                setSearchMatches([]);
+                setFindQuery('');
+                setFindSubmitted(false);
+                setFindMatches([]);
                 return;
             }
             if (key.return) {
-                submitSearch();
+                submitFind();
                 setMode(returnMode);
                 return;
             }
             if (key.backspace || key.delete) {
-                setSearchQuery(prev => prev.slice(0, -1));
+                setFindQuery(prev => prev.slice(0, -1));
+                return;
+            }
+            if (findSubmitted && input === 'n') {
+                nextFindMatch();
                 return;
             }
-            if (searchSubmitted && input === 'n') {
-                nextMatch();
+            if (findSubmitted && input === 'N') {
+                prevFindMatch();
                 return;
             }
-            if (searchSubmitted && input === 'N') {
-                prevMatch();
+            if (input && !key.ctrl && !key.meta) {
+                setFindQuery(prev => prev + input);
+            }
+            return;
+        }
+        // ── Global-search input mode (`?` modal — type query) ───────────────
+        if (mode === 'gsearch-input') {
+            const returnMode = studyActiveRef.current ? 'study' : 'normal';
+            if (key.escape) {
+                setMode(returnMode);
+                setGsearchInput('');
+                return;
+            }
+            if (key.return) {
+                const trimmed = gsearchInput.trim();
+                if (!trimmed)
+                    return;
+                // Same query as the live session → restore the cached list at last cursor.
+                if (gsearchSession && gsearchSession.query === trimmed) {
+                    setMode('gsearch-list');
+                    setGsearchInput('');
+                    return;
+                }
+                const session = executeGsearch(gsearchInput);
+                if (session) {
+                    setGsearchSession(session);
+                    setMode('gsearch-list');
+                }
+                else {
+                    // Empty results case still gets a session so the list shows "0 results".
+                    setGsearchSession({ query: trimmed, results: [], terms: trimmed.split(/\s+/), cursor: 0, pageIdx: 0 });
+                    setMode('gsearch-list');
+                }
+                setGsearchInput('');
+                return;
+            }
+            if (key.backspace || key.delete) {
+                setGsearchInput(prev => prev.slice(0, -1));
                 return;
             }
             if (input && !key.ctrl && !key.meta) {
-                setSearchQuery(prev => prev + input);
+                setGsearchInput(prev => prev + input);
+            }
+            return;
+        }
+        // ── Global-search list mode (`?` modal — browse results) ────────────
+        if (mode === 'gsearch-list') {
+            if (!gsearchSession) {
+                setMode('normal');
+                return;
+            }
+            const totalResults = gsearchSession.results.length;
+            const pageCount = Math.max(1, Math.ceil(totalResults / GSEARCH_PAGE_SIZE));
+            const pageStart = gsearchSession.pageIdx * GSEARCH_PAGE_SIZE;
+            const pageEnd = Math.min(pageStart + GSEARCH_PAGE_SIZE, totalResults);
+            const pageLen = pageEnd - pageStart;
+            const returnMode = studyActiveRef.current ? 'study' : 'normal';
+            if (key.escape || input === 'q') {
+                setMode(returnMode);
+                return;
+            }
+            if (input === '?') {
+                setMode('gsearch-input');
+                setGsearchInput(gsearchSession.query);
+                return;
+            }
+            if (key.return) {
+                const v = gsearchSession.results[pageStart + gsearchSession.cursor];
+                if (v) {
+                    pendingVerseRef.current = v.verse;
+                    pendingFindTermsRef.current = gsearchSession.terms.length > 0 ? gsearchSession.terms : null;
+                    // navigate() calls restoreMode() which puts us back in normal/study.
+                    navigate(v.book, v.chapter);
+                }
+                return;
+            }
+            if (totalResults === 0)
+                return;
+            // Page navigation: ← prev page, → next page (cursor resets to top of new page).
+            if (key.leftArrow || input === 'h') {
+                if (gsearchSession.pageIdx > 0) {
+                    setGsearchSession(s => s ? { ...s, pageIdx: s.pageIdx - 1, cursor: 0 } : s);
+                }
+                return;
+            }
+            if (key.rightArrow || input === 'l') {
+                if (gsearchSession.pageIdx < pageCount - 1) {
+                    setGsearchSession(s => s ? { ...s, pageIdx: s.pageIdx + 1, cursor: 0 } : s);
+                }
+                return;
+            }
+            if (key.upArrow || input === 'k') {
+                setGsearchSession(s => s ? { ...s, cursor: Math.max(0, s.cursor - 1) } : s);
+                return;
+            }
+            if (key.downArrow || input === 'j') {
+                setGsearchSession(s => s ? { ...s, cursor: Math.min(pageLen - 1, s.cursor + 1) } : s);
+                return;
+            }
+            if (input === 'g') {
+                setGsearchSession(s => s ? { ...s, cursor: 0 } : s);
+                return;
+            }
+            if (input === 'G') {
+                setGsearchSession(s => s ? { ...s, cursor: Math.max(0, pageLen - 1) } : s);
+                return;
+            }
+            if (key.tab) {
+                const step = Math.max(1, Math.floor(pageLen / 4));
+                const dir = key.shift ? -1 : 1;
+                setGsearchSession(s => s ? { ...s, cursor: Math.max(0, Math.min(pageLen - 1, s.cursor + dir * step)) } : s);
+                return;
             }
             return;
         }
@@ -777,12 +1063,18 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
                 setGotoInput('');
                 return;
             }
-            // Search within chapter
+            // Find within chapter
             if (input === '/') {
-                setMode('search');
-                setSearchQuery('');
-                setSearchSubmitted(false);
-                setSearchMatches([]);
+                setMode('find');
+                setFindQuery('');
+                setFindSubmitted(false);
+                setFindMatches([]);
+                return;
+            }
+            // Global search (full Bible)
+            if (input === '?') {
+                setMode('gsearch-input');
+                setGsearchInput(gsearchSession?.query ?? '');
                 return;
             }
             return;
@@ -864,8 +1156,8 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             return;
         }
         if (input === 'n' || key.rightArrow) {
-            if (searchSubmitted && searchMatches.length > 0) {
-                nextMatch();
+            if (findSubmitted && findMatches.length > 0) {
+                nextFindMatch();
             }
             else {
                 goNext();
@@ -873,7 +1165,7 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             return;
         }
         if (input === 'N') {
-            prevMatch();
+            prevFindMatch();
             return;
         }
         if (input === 'p' || key.leftArrow) {
@@ -889,10 +1181,15 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             return;
         }
         if (input === '/') {
-            setMode('search');
-            setSearchQuery('');
-            setSearchSubmitted(false);
-            setSearchMatches([]);
+            setMode('find');
+            setFindQuery('');
+            setFindSubmitted(false);
+            setFindMatches([]);
+            return;
+        }
+        if (input === '?') {
+            setMode('gsearch-input');
+            setGsearchInput(gsearchSession?.query ?? '');
             return;
         }
         if (input === 'c') {
@@ -1003,18 +1300,34 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         const homeContent = homeLines.join('\n');
         let homeFooter;
         if (mode === 'home-chapter') {
-            homeFooter = `  ${chalk.dim('←/→ or type number · Enter go · Esc back')}`;
+            homeFooter = `  ${[
+                kb('←/→', 'ch'),
+                kb('0-9', 'jump'),
+                kb('Enter', 'go'),
+                kb('Esc', 'back'),
+            ].join(FOOTER_SEP)}`;
         }
         else {
             const lastRead = getLastRead();
-            const continueHint = lastRead ? 'Space continue · ' : '';
-            homeFooter = `  ${chalk.dim(`↑↓←→ navigate · Enter select · ${continueHint}type letter to jump · q quit`)}`;
+            const parts = [
+                kb('↑↓←→', 'navigate'),
+                kb('Enter', 'select'),
+            ];
+            if (lastRead)
+                parts.push(kb('Space', 'continue'));
+            parts.push(kb('a-z', 'jump'));
+            parts.push(kb('q', 'quit'));
+            homeFooter = `  ${parts.join(FOOTER_SEP)}`;
         }
         const homeSep = chalk.dim('─'.repeat(cols));
         return (_jsxs(Box, { flexDirection: "column", height: rows, children: [_jsx(Text, { children: chalk.bold('  rv') }), _jsx(Text, { children: homeSep }), _jsx(Box, { flexGrow: 1, overflow: "hidden", children: _jsx(Text, { children: homeContent }) }), _jsx(Text, { children: homeSep }), _jsx(Text, { children: homeFooter })] }));
     }
     // ── Chapter view: build visible content ──────────────────────────────────
     const visibleSlice = displayLines.slice(scrollOffset, scrollOffset + viewportH);
+    // Pad to exactly viewportH rows so the panel stays anchored to the bottom even
+    // when scrollOffset > maxScroll (study-mode overscroll for centering).
+    while (visibleSlice.length < viewportH)
+        visibleSlice.push('');
     // Apply cursor highlight for copy mode and study mode
     const contentLines = (mode === 'copy' || mode === 'study') ? visibleSlice.map((line, viewIdx) => {
         const absLine = scrollOffset + viewIdx;
@@ -1032,16 +1345,43 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
                         ? chalk.inverse(`› ${stripAnsi(line)}`)
                         : chalk.inverse(`  ${stripAnsi(line)}`);
                 }
-                // Study mode: subtle — just a › marker on first line, no bg change
+                // Study mode: subtle — just a › marker on first line, no bg change.
+                // Place cursor 3 columns left of the verse number so the gap stays
+                // constant regardless of margin (zoom level).
                 if (absLine === entry.startLine) {
-                    return `${chalk.cyan('›')}${line.substring(1)}`;
+                    const cursorCol = Math.max(0, getMargin() - 3);
+                    return `${line.slice(0, cursorCol)}${chalk.cyan('›')}${line.slice(cursorCol + 1)}`;
                 }
                 return line;
             }
         }
         return line;
     }) : visibleSlice;
-    const content = contentLines.join('\n');
+    // Global-search list view replaces the chapter content slot.
+    let content;
+    if (mode === 'gsearch-list' && gsearchSession && gsearchListData) {
+        const slice = gsearchListData.lines.slice(gsearchScroll, gsearchScroll + viewportH);
+        while (slice.length < viewportH)
+            slice.push('');
+        if (gsearchSession.results.length === 0) {
+            // Empty-state: center "no results" text in the viewport
+            const msg = chalk.dim(`  No results for "${gsearchSession.query}"`);
+            const padTop = Math.max(0, Math.floor(viewportH / 2) - 1);
+            const out = [];
+            for (let i = 0; i < padTop; i++)
+                out.push('');
+            out.push(msg);
+            while (out.length < viewportH)
+                out.push('');
+            content = out.join('\n');
+        }
+        else {
+            content = slice.join('\n');
+        }
+    }
+    else {
+        content = contentLines.join('\n');
+    }
     // ── Header ───────────────────────────────────────────────────────────────
     const CATEGORY_LABELS = {
         Moses: 'Books of Moses', Israel: 'History of Israel', Poetry: 'Poetry & Wisdom',
@@ -1061,45 +1401,115 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         ? `  ${title}  ${chalk.dim('·')}  ${chalk.dim(categoryLabel)}${zoomLabel}`
         : `  ${title}${zoomLabel}`;
     const headerPad = Math.max(1, cols - stripAnsi(titleLeft).length - position.length - 2);
-    const header = `${titleLeft}${' '.repeat(headerPad)}${chalk.dim(position)}`;
+    let header = `${titleLeft}${' '.repeat(headerPad)}${chalk.dim(position)}`;
+    // Override header for the global-search list view
+    if (mode === 'gsearch-list' && gsearchSession) {
+        const totalResults = gsearchSession.results.length;
+        const pageCount = Math.max(1, Math.ceil(totalResults / GSEARCH_PAGE_SIZE));
+        const pageStart = gsearchSession.pageIdx * GSEARCH_PAGE_SIZE;
+        const pageEnd = Math.min(pageStart + GSEARCH_PAGE_SIZE, totalResults);
+        const pageLen = pageEnd - pageStart;
+        const countLabel = totalResults === 0
+            ? 'no results'
+            : pageCount > 1
+                ? `page ${gsearchSession.pageIdx + 1}/${pageCount} · ${pageStart + 1}–${pageEnd} of ${totalResults}`
+                : `${totalResults} result${totalResults === 1 ? '' : 's'}`;
+        const gsTitleLeft = `  ${chalk.bold(`Search: "${gsearchSession.query}"`)}  ${chalk.dim('·')}  ${chalk.dim(countLabel)}`;
+        const gsPosition = pageLen > 0 ? `${gsearchSession.cursor + 1}/${pageLen}` : '';
+        const gsPad = Math.max(1, cols - stripAnsi(gsTitleLeft).length - gsPosition.length - 2);
+        header = `${gsTitleLeft}${' '.repeat(gsPad)}${chalk.dim(gsPosition)}`;
+    }
     // ── Footer (two lines for normal/study, one line for modal modes) ──────
+    // Toggle indicator: cyan when active (state cue), magenta key + dim desc when off.
+    const toggleHint = (on, key, desc) => on ? chalk.cyan(`${key} ${desc}`) : kb(key, desc);
     let footer1;
     let footer2 = null;
     if (flash) {
         footer1 = `  ${chalk.green(`✓ ${flash}`)}`;
     }
-    else if (mode === 'search') {
-        if (searchSubmitted) {
-            const countLabel = searchMatches.length === 0
+    else if (mode === 'find') {
+        if (findSubmitted) {
+            const countLabel = findMatches.length === 0
                 ? 'no matches'
-                : `match ${matchIdx + 1}/${searchMatches.length}`;
-            footer1 = `  / ${searchQuery}  ${chalk.dim(countLabel)}  ${chalk.dim('n/N cycle · Esc clear')}`;
+                : `match ${findIdx + 1}/${findMatches.length}`;
+            footer1 = `  / ${findQuery}  ${chalk.dim(countLabel)}  ${[kb('n/N', 'cycle'), kb('Esc', 'clear')].join(FOOTER_SEP)}`;
         }
         else {
-            footer1 = `  / ${searchQuery}${chalk.dim('_')}  ${chalk.dim('Enter search · Esc cancel')}`;
+            footer1 = `  / ${findQuery}${chalk.dim('_')}  ${[kb('Enter', 'find'), kb('Esc', 'cancel')].join(FOOTER_SEP)}`;
         }
     }
     else if (mode === 'goto') {
-        footer1 = `  : ${gotoInput}${chalk.dim('_')}  ${chalk.dim('e.g. rom 8 · Enter go · Esc cancel')}`;
+        footer1 = `  : ${gotoInput}${chalk.dim('_')}  ${chalk.dim('e.g. rom 8')}${FOOTER_SEP}${[kb('Enter', 'go'), kb('Esc', 'cancel')].join(FOOTER_SEP)}`;
+    }
+    else if (mode === 'gsearch-input') {
+        footer1 = `  ? ${gsearchInput}${chalk.dim('_')}  ${chalk.dim('try grace · "only begotten" · grace in romans')}${FOOTER_SEP}${[kb('Enter', 'search'), kb('Esc', 'cancel')].join(FOOTER_SEP)}`;
+    }
+    else if (mode === 'gsearch-list') {
+        const showPageHint = gsearchSession ? gsearchSession.results.length > GSEARCH_PAGE_SIZE : false;
+        const listKeys = [
+            kb('↑↓', 'select'),
+            kb('Tab/⇧Tab', 'quarter'),
+            kb('g/G', 'first/last'),
+        ];
+        if (showPageHint)
+            listKeys.push(kb('←→', 'page'));
+        listKeys.push(kb('Enter', 'open'), kb('?', 'edit'), kb('Esc', 'back'));
+        footer1 = `  ${listKeys.join(FOOTER_SEP)}`;
     }
     else if (mode === 'study') {
         const inputHint = studyRefInput ? ` ${chalk.yellow(studyRefInput)}${chalk.dim('_')}` : '';
         const rangeHint = studySelStart !== null ? chalk.dim(' (range)') : '';
-        const sNoteFlag = notes ? chalk.cyan('f notes') : chalk.dim('f notes');
-        const sOutlineFlag = outline ? chalk.cyan('o outline') : chalk.dim('o outline');
-        footer1 = `  ${chalk.cyan('STUDY')}${inputHint}${rangeHint}  ${chalk.dim('# ref · v range · c copy ·')} ${sNoteFlag} ${chalk.dim('·')} ${sOutlineFlag} ${chalk.dim('· / find')}`;
-        const panelHint = panelOverflow ? chalk.dim(' · ,/. note') : '';
-        footer2 = `  ${chalk.dim('↑↓ verse · Tab/⇧Tab quarter · g/G top/bot · ←→ ch · : goto · [/] back/fwd · d exit')}${panelHint}`;
+        footer1 = `  ${chalk.cyan('STUDY')}${inputHint}${rangeHint}  ${[
+            kb('#', 'ref'),
+            kb('v', 'range'),
+            kb('c', 'copy'),
+            toggleHint(notes, 'f', 'notes'),
+            toggleHint(outline, 'o', 'outline'),
+            kb('/', 'find'),
+            kb('?', 'search'),
+        ].join(FOOTER_SEP)}`;
+        const f2Parts = [
+            kb('↑↓', 'verse'),
+            kb('Tab/⇧Tab', 'quarter'),
+            kb('g/G', 'top/bot'),
+            kb('←→', 'ch'),
+            kb(':', 'goto'),
+            kb('[/]', 'back/fwd'),
+            kb('d', 'exit'),
+        ];
+        if (panelOverflow)
+            f2Parts.push(kb(',/.', 'note'));
+        footer2 = `  ${f2Parts.join(FOOTER_SEP)}`;
     }
     else if (mode === 'copy') {
         const rangeHint = selStart !== null ? chalk.dim(' (range active)') : '';
-        footer1 = `  ${chalk.cyan('COPY')}${rangeHint}  ${chalk.dim('↑↓ move · v range · Enter copy · Esc cancel')}`;
+        footer1 = `  ${chalk.cyan('COPY')}${rangeHint}  ${[
+            kb('↑↓', 'move'),
+            kb('v', 'range'),
+            kb('Enter', 'copy'),
+            kb('Esc', 'cancel'),
+        ].join(FOOTER_SEP)}`;
     }
     else {
-        const noteFlag = notes ? chalk.cyan('f notes') : chalk.dim('f notes');
-        const outlineFlag = outline ? chalk.cyan('o outline') : chalk.dim('o outline');
-        footer1 = `  ${noteFlag} ${chalk.dim('·')} ${outlineFlag} ${chalk.dim('· d study · c copy · / find')}`;
-        footer2 = `  ${chalk.dim('↑↓ scroll · Tab/⇧Tab quarter · g/G top/bot · ←→ ch · +/- width · : goto · H home · [/] back/fwd · q quit')}`;
+        footer1 = `  ${[
+            toggleHint(notes, 'f', 'notes'),
+            toggleHint(outline, 'o', 'outline'),
+            kb('d', 'study'),
+            kb('c', 'copy'),
+            kb('/', 'find'),
+            kb('?', 'search'),
+        ].join(FOOTER_SEP)}`;
+        footer2 = `  ${[
+            kb('↑↓', 'scroll'),
+            kb('Tab/⇧Tab', 'quarter'),
+            kb('g/G', 'top/bot'),
+            kb('←→', 'ch'),
+            kb('+/-', 'width'),
+            kb(':', 'goto'),
+            kb('H', 'home'),
+            kb('[/]', 'back/fwd'),
+            kb('q', 'quit'),
+        ].join(FOOTER_SEP)}`;
     }
     const separator = chalk.dim('· '.repeat(Math.floor(cols / 2)));
     // ── Render ───────────────────────────────────────────────────────────────
@@ -1110,7 +1520,7 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             const lo = panelScrollClamped + 1;
             const hi = panelScrollClamped + panelVisibleLines.length;
             const total = panelLinesAll.length;
-            parts.push(chalk.dim(`  ── ${lo}–${hi} of ${total} · ,/. scroll ──`));
+            parts.push(`  ${chalk.dim(`── ${lo}–${hi} of ${total} ·`)} ${kb(',/.', 'scroll')} ${chalk.dim('──')}`);
         }
         studyPanelContent = parts.join('\n');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rv-bible-cli",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Fast, offline terminal Bible reader for the Recovery Version. Footnotes, cross-references, concordance search, interactive pager.",
   "type": "module",
   "main": "dist/index.js",