rv-bible-cli 0.1.5 → 0.1.7

package/README.md

@@ -114,6 +114,7 @@ When you read a chapter in a terminal, rvb opens a full-screen interactive reade
 |-----|--------|
 | `j` / `k` / arrows | scroll up/down |
 | `Space` / `b` | page down/up |
+| `Tab` / `Shift+Tab` | scroll down / up by a quarter of the chapter |
 | `g` / `G` | jump to top / bottom |
 | left / right | prev / next chapter (even across books) |
 | `f` | toggle footnotes on/off |
@@ -133,19 +134,23 @@ 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
-- The bottom panel shows all footnotes for that verse with numbered cross-references
+- 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
 - Study mode stays active as you navigate — it's designed for chaining through references
+- If a verse has very long notes, the panel caps at half your terminal height — use `,` / `.` to scroll within it
 
 | Key | Action |
 |-----|--------|
-| up / down | move between verses |
+| up / down | move cursor up / down one verse |
 | left / right | prev / next chapter |
 | type number | follow a cross-reference |
 | `v` then up/down then `c` | select a range and copy |
 | `c` | copy current verse |
+| `Tab` / `Shift+Tab` | jump cursor by a quarter of the chapter |
+| `g` / `G` | cursor to first / last verse |
+| `,` / `.` | scroll the footnote panel up / down (when it overflows) |
 | `f` / `o` | toggle footnotes / outline |
 | `/` | find text |
 | `:` | jump to a book |

package/dist/format.d.ts

@@ -8,6 +8,8 @@ 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;
 export declare function renderNoteDisplay(verse: Verse, fn: 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).
@@ -118,7 +121,7 @@ function visibleLength(s) {
 // ── Word-wrap helper ─────────────────────────────────────────────────────────
 // Wraps plain `text` to `maxWidth` columns. Returns array of line strings.
 // Use visibleLength=true when words may contain ANSI escape codes.
-function wrapWords(text, maxWidth, ansi = false) {
+export function wrapWords(text, maxWidth, ansi = false) {
     if (maxWidth < 20)
         return [text];
     const words = text.split(' ');

package/dist/index.js

@@ -2,6 +2,8 @@
 import { program } from 'commander';
 import chalk from 'chalk';
 import clipboard from 'clipboardy';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { parseRefList, resolveBook } from './parser.js';
 import { getVersesByRef, getSectionHeaders, getFootnotesForChapter, getFootnotesForVerses, getFootnote, getVerse, getBookInfo, getAllBooks, isInConcordance, getTopicVerses, searchFTS, } from './db.js';
 import { renderVerses, renderVerseInline, renderFootnoteBlock, renderNoteDisplay, renderNoteDisplayAll, stripMarkers, highlightTerms, } from './format.js';
@@ -10,10 +12,12 @@ import { getLastRead, saveLastRead } from './state.js';
 function stripAnsi(s) {
     return s.replace(/\x1b\[[0-9;]*m/g, '');
 }
+// Read version from package.json (single source of truth — avoids drift)
+const pkg = JSON.parse(readFileSync(path.join(import.meta.dirname, '../package.json'), 'utf-8'));
 program
     .name('rv')
     .description('Recovery Version Bible CLI')
-    .version('0.1.0')
+    .version(pkg.version)
     .enablePositionalOptions();
 // Formats a ParsedRef + book name into a display label: "John 3", "John 3:16", "John 3:16–18"
 function formatRefLabel(ref, bookName) {
@@ -393,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

@@ -4,7 +4,7 @@ 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, zoomIn, zoomOut, zoomReset, getZoom } from '../format.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.
@@ -144,6 +158,7 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
     const [studyCursorIdx, setStudyCursorIdx] = useState(0);
     const [studySelStart, setStudySelStart] = useState(null);
     const [studyRefInput, setStudyRefInput] = useState(''); // multi-digit ref number
+    const [panelScrollOffset, setPanelScrollOffset] = useState(0); // scroll within study panel when notes overflow cap
     const studyActiveRef = useRef(false); // persists across navigate so study mode survives ref follows
     const pendingVerseRef = useRef(null); // target verse to jump to after navigate
     // Flash message
@@ -215,10 +230,13 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         const panelLines = [];
         const verseLabel = `${bookName} ${chapter}:${v.verse}`;
         panelLines.push(`  ${chalk.bold(verseLabel)} ${chalk.dim(`— ${fns.length} note${fns.length === 1 ? '' : 's'}`)}`);
+        const BODY_INDENT = '     '; // 5 spaces — visually under the word, after marker
+        const bodyWidth = Math.max(20, cols - BODY_INDENT.length);
         for (const fn of fns) {
             // Extract the word the marker attaches to (first word after "Book ch:v word" in footnote text)
-            const fnTextParts = fn.text.split(/\s+/);
+            const fnTextParts = fn.text.trim().split(/\s+/);
             const word = fnTextParts[2] ?? ''; // "Joh 3:16 loved ..." → "loved"
+            const noteBody = fnTextParts.slice(3).join(' ').trim(); // everything after "Book ch:v word"
             const markerDisp = toSuperscript(fn.marker);
             const refs = refsByMarker.get(fn.marker) ?? [];
             // Deduplicate refs by target
@@ -230,42 +248,85 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
                 seen.add(key);
                 return true;
             });
-            if (uniqueRefs.length === 0) {
-                // Study note with no cross-refs — show truncated text
-                const notePreview = fn.text.length > 60 ? fn.text.substring(0, 57) + '...' : fn.text;
-                panelLines.push(`  ${chalk.cyan(markerDisp)} ${chalk.dim(word)}  ${chalk.dim(notePreview)}`);
+            // Build numbered ref labels (mutates studyRefs)
+            const refLabels = [];
+            for (const r of uniqueRefs) {
+                const refNum = studyRefs.length + 1;
+                const tgtBookName = getBookInfo(r.tgt_book)?.abbr ?? r.tgt_book;
+                const label = `${tgtBookName} ${r.tgt_chapter}:${r.tgt_verse}`;
+                studyRefs.push({
+                    num: refNum, marker: fn.marker,
+                    tgt_book: r.tgt_book, tgt_chapter: r.tgt_chapter, tgt_verse: r.tgt_verse, label,
+                });
+                refLabels.push(`${chalk.yellow(`[${refNum}]`)} ${chalk.dim(label)}`);
             }
-            else {
-                // Build numbered ref labels
-                const refLabels = [];
-                for (const r of uniqueRefs) {
-                    const refNum = studyRefs.length + 1;
-                    const tgtBookName = getBookInfo(r.tgt_book)?.abbr ?? r.tgt_book;
-                    const label = `${tgtBookName} ${r.tgt_chapter}:${r.tgt_verse}`;
-                    studyRefs.push({
-                        num: refNum, marker: fn.marker,
-                        tgt_book: r.tgt_book, tgt_chapter: r.tgt_chapter, tgt_verse: r.tgt_verse, label,
-                    });
-                    refLabels.push(`${chalk.yellow(`[${refNum}]`)} ${chalk.dim(label)}`);
+            // Header line: marker + word + refs (refs may be empty)
+            const refsPart = refLabels.length > 0 ? `  ${refLabels.join('  ')}` : '';
+            panelLines.push(`  ${chalk.cyan(markerDisp)} ${chalk.dim(word)}${refsPart}`);
+            // Body: wrap full note text under hanging indent, dim style. No truncation.
+            if (noteBody) {
+                const wrapped = wrapWords(noteBody, bodyWidth);
+                for (const wl of wrapped) {
+                    panelLines.push(`${BODY_INDENT}${chalk.dim(wl)}`);
                 }
-                // Compact: marker + word + refs on one line (wrap if needed)
-                const hasStudyNote = fn.text.length > 80;
-                const noteHint = hasStudyNote ? chalk.dim(' (note)') : '';
-                panelLines.push(`  ${chalk.cyan(markerDisp)} ${chalk.dim(word)}${noteHint}  ${refLabels.join('  ')}`);
             }
         }
         return { lines: panelLines, refs: studyRefs };
-    }, [mode, studyCursorIdx, verseMap, verses, book, chapter, bookName]);
+    }, [mode, studyCursorIdx, verseMap, verses, book, chapter, bookName, cols]);
+    // ── Study panel sizing & scroll (cap at 50% of screen, scrollable on overflow) ──
+    const panelLinesAll = studyPanel.lines;
+    const panelMaxH = Math.max(3, Math.floor(rows * 0.5));
+    const panelOverflow = panelLinesAll.length > panelMaxH;
+    const panelContentSlots = panelOverflow ? panelMaxH - 1 : panelLinesAll.length; // reserve 1 line for indicator
+    const maxPanelScroll = Math.max(0, panelLinesAll.length - panelContentSlots);
+    const panelScrollClamped = Math.max(0, Math.min(panelScrollOffset, maxPanelScroll));
+    const panelVisibleLines = panelLinesAll.slice(panelScrollClamped, panelScrollClamped + panelContentSlots);
+    const panelDisplayH = panelLinesAll.length > 0 ? panelVisibleLines.length + (panelOverflow ? 1 : 0) : 0;
     // ── Viewport height (shrinks when study panel is visible) ────────────
-    const studyPanelH = studyPanel.lines.length > 0 ? studyPanel.lines.length + 1 : 0; // +1 for separator
+    const studyPanelH = panelDisplayH > 0 ? panelDisplayH + 1 : 0; // +1 for separator above panel
     const hasFooter2 = mode === 'normal' || mode === 'study';
     const chromeH = 3 + (hasFooter2 ? 2 : 1) + studyPanelH; // header + sep + footer(s) + sep + panel
     const viewportH = Math.max(1, rows - chromeH);
-    // Clamp scroll when content or viewport changes
+    // Reset panel scroll when the verse cursor changes or when leaving study mode
+    useEffect(() => {
+        setPanelScrollOffset(0);
+    }, [studyCursorIdx, book, chapter, mode]);
+    // 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]);
+        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;
+        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 ────────────────────────────────────────────────────
     const displayLines = useMemo(() => {
         if (!searchSubmitted || searchMatches.length === 0)
@@ -288,6 +349,20 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         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).
+        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);
+            saveLastRead(newBook, newChapter);
+            return;
+        }
         if (pushHistory) {
             historyRef.current = [...historyRef.current, { book: bookRef.current, chapter: chapterRef.current, scroll: scrollRef.current }];
             forwardRef.current = [];
@@ -297,7 +372,7 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
         setScrollOffset(0);
         restoreMode();
         saveLastRead(newBook, newChapter);
-    }, [restoreMode]);
+    }, [restoreMode, verseMap]);
     const goBack = useCallback(() => {
         const hist = historyRef.current;
         if (hist.length === 0)
@@ -342,6 +417,11 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
     const scrollUp = useCallback(() => scrollTo(scrollOffset - 1), [scrollOffset, scrollTo]);
     const pageDown = useCallback(() => scrollTo(scrollOffset + viewportH - 2), [scrollOffset, viewportH, scrollTo]);
     const pageUp = useCallback(() => scrollTo(scrollOffset - viewportH + 2), [scrollOffset, viewportH, scrollTo]);
+    // Quarter-of-chapter slider — 4 presses spans top to bottom regardless of length
+    const scrollQuarter = useCallback((dir) => {
+        const q = Math.max(1, Math.floor(lines.length * 0.25));
+        scrollTo(scrollOffset + dir * q);
+    }, [lines.length, scrollOffset, scrollTo]);
     // ── Copy helpers ─────────────────────────────────────────────────────────
     const doCopy = useCallback(async () => {
         const lo = selStart !== null ? Math.min(selStart, cursorIdx) : cursorIdx;
@@ -598,26 +678,23 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
                 return;
             }
             if (input === 'j' || key.downArrow) {
-                setStudyCursorIdx(prev => {
-                    const next = Math.min(prev + 1, verseMap.length - 1);
-                    const entry = verseMap[next];
-                    if (entry && entry.startLine >= scrollOffset + viewportH) {
-                        scrollTo(entry.startLine - viewportH + 3);
-                    }
-                    return next;
-                });
+                setStudyCursorIdx(prev => Math.min(prev + 1, verseMap.length - 1));
                 setStudyRefInput('');
                 return;
             }
             if (input === 'k' || key.upArrow) {
-                setStudyCursorIdx(prev => {
-                    const next = Math.max(prev - 1, 0);
-                    const entry = verseMap[next];
-                    if (entry && entry.startLine < scrollOffset) {
-                        scrollTo(entry.startLine);
-                    }
-                    return next;
-                });
+                setStudyCursorIdx(prev => Math.max(prev - 1, 0));
+                setStudyRefInput('');
+                return;
+            }
+            // Cursor to first / last verse (cursor-visible effect handles scroll)
+            if (input === 'g') {
+                setStudyCursorIdx(0);
+                setStudyRefInput('');
+                return;
+            }
+            if (input === 'G') {
+                setStudyCursorIdx(Math.max(0, verseMap.length - 1));
                 setStudyRefInput('');
                 return;
             }
@@ -632,6 +709,23 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
                 setZoomState(getZoom());
                 return;
             }
+            // Quarter-of-chapter cursor jump (cursor-visible effect handles scroll)
+            if (key.tab) {
+                const step = Math.max(1, Math.floor(verseMap.length / 4));
+                const dir = key.shift ? -1 : 1;
+                setStudyCursorIdx(prev => Math.max(0, Math.min(verseMap.length - 1, prev + dir * step)));
+                setStudyRefInput('');
+                return;
+            }
+            // Panel scroll (only meaningful when notes panel overflows)
+            if (input === ',') {
+                setPanelScrollOffset(prev => Math.max(0, prev - 1));
+                return;
+            }
+            if (input === '.') {
+                setPanelScrollOffset(prev => Math.min(maxPanelScroll, prev + 1));
+                return;
+            }
             // Number keys: build ref number, then follow on Enter or after short delay
             if (input && /^[0-9]$/.test(input)) {
                 const newInput = studyRefInput + input;
@@ -786,6 +880,14 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             scrollTo(maxScroll);
             return;
         }
+        if (key.tab && key.shift) {
+            scrollQuarter(-1);
+            return;
+        }
+        if (key.tab) {
+            scrollQuarter(1);
+            return;
+        }
         if (input === 'n' || key.rightArrow) {
             if (searchSubmitted && searchMatches.length > 0) {
                 nextMatch();
@@ -926,18 +1028,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;
@@ -955,9 +1073,12 @@ 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;
             }
@@ -986,6 +1107,8 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
     const headerPad = Math.max(1, cols - stripAnsi(titleLeft).length - position.length - 2);
     const header = `${titleLeft}${' '.repeat(headerPad)}${chalk.dim(position)}`;
     // ── 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) {
@@ -996,38 +1119,81 @@ function Pager({ initialBook, initialChapter, initialNotes, initialOutline, star
             const countLabel = searchMatches.length === 0
                 ? 'no matches'
                 : `match ${matchIdx + 1}/${searchMatches.length}`;
-            footer1 = `  / ${searchQuery}  ${chalk.dim(countLabel)}  ${chalk.dim('n/N cycle · Esc clear')}`;
+            footer1 = `  / ${searchQuery}  ${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 = `  / ${searchQuery}${chalk.dim('_')}  ${[kb('Enter', 'search'), 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 === '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')}`;
-        footer2 = `  ${chalk.dim('↑↓ verse · ←→ ch · : goto · [/] back/fwd · d exit')}`;
+        footer1 = `  ${chalk.cyan('STUDY')}${inputHint}${rangeHint}  ${[
+            kb('#', 'ref'),
+            kb('v', 'range'),
+            kb('c', 'copy'),
+            toggleHint(notes, 'f', 'notes'),
+            toggleHint(outline, 'o', 'outline'),
+            kb('/', 'find'),
+        ].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 · ←→ 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'),
+        ].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 ───────────────────────────────────────────────────────────────
-    const studyPanelContent = studyPanel.lines.length > 0
-        ? studyPanel.lines.join('\n')
-        : null;
+    let studyPanelContent = null;
+    if (panelLinesAll.length > 0) {
+        const parts = [panelVisibleLines.join('\n')];
+        if (panelOverflow) {
+            const lo = panelScrollClamped + 1;
+            const hi = panelScrollClamped + panelVisibleLines.length;
+            const total = panelLinesAll.length;
+            parts.push(`  ${chalk.dim(`── ${lo}–${hi} of ${total} ·`)} ${kb(',/.', 'scroll')} ${chalk.dim('──')}`);
+        }
+        studyPanelContent = parts.join('\n');
+    }
     return (_jsxs(Box, { flexDirection: "column", height: rows, children: [_jsx(Text, { children: header }), _jsx(Text, { children: separator }), _jsx(Box, { flexGrow: 1, overflow: "hidden", children: _jsx(Text, { children: content }) }), _jsx(Text, { children: separator }), studyPanelContent && _jsx(Text, { children: studyPanelContent }), studyPanelContent && _jsx(Text, { children: separator }), _jsx(Text, { children: footer1 }), footer2 && _jsx(Text, { children: footer2 })] }));
 }
 // ── Launcher ─────────────────────────────────────────────────────────────────

package/package.json

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