Implement guided study session v1

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {

.gitattributes

@@ -1,3 +1,20 @@
+# Default: normalize line endings to LF on commit. Windows checkouts without
+# core.autocrlf configured will no longer introduce CRLF into the repo.
+* text=auto eol=lf
+
+# Binary assets: never touch line endings
+*.db binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.webp binary
+*.ttf binary
+*.otf binary
+*.woff binary
+*.woff2 binary
+*.ico binary
+
+# LFS-tracked source art
 _tools/art_sources/*.jpg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.jpeg filter=lfs diff=lfs merge=lfs -text
 _tools/art_sources/*.png filter=lfs diff=lfs merge=lfs -text

_tools/build_sqlite.py

@@ -24,7 +24,7 @@
 from build_sqlite_schema import create_schema
 from build_sqlite_loaders import (
  populate_books, populate_chapters, populate_verses,
- populate_book_intros, populate_people, populate_scholars,
+ populate_book_intros, populate_proof_text_guards, populate_people, populate_scholars,
  populate_places, populate_map_stories, populate_ancient_borders,
  populate_word_studies,
  populate_synoptic, populate_topics, populate_debate_topics,
@@ -93,6 +93,7 @@ def main():
 
  print(f" [OK] verses: {populate_verses(cur)} rows")
  print(f" [OK] book_intros: {populate_book_intros(cur)} rows")
+ print(f" [OK] proof_text_guards: {populate_proof_text_guards(cur)} rows")
  print(f" [OK] people: {populate_people(cur)} rows")
  print(f" [OK] scholars: {populate_scholars(cur)} rows")
  print(f" [OK] places: {populate_places(cur)} rows")

_tools/build_sqlite_loaders.py

@@ -15,6 +15,7 @@
 AUDIT_DIR = ROOT / '_tools' / 'audit'
 REFERENCE_MATRIX_PATH = AUDIT_DIR / 'reference_matrix.json'
 TRANSLATIONS_DIR = ROOT / 'app' / 'assets' / 'translations'
+PROOF_TEXT_GUARDS_PATH = META / 'proof-text-guards.json'
 
 # Translations config — must match build_sqlite.py
 AVAILABLE_TRANSLATIONS = {'kjv', 'asv'}
@@ -471,6 +472,51 @@ def populate_book_intros(cur):
  return count
 
 
+def populate_proof_text_guards(cur):
+ if not PROOF_TEXT_GUARDS_PATH.exists():
+ return 0
+ guards = _load_json(PROOF_TEXT_GUARDS_PATH)
+ count = 0
+ for guard in guards:
+ suggested = guard.get('suggested_chapter')
+ # Each guard must explicitly name the chapter to point the reader at. A
+ # self-reference is valid (the UX is often "read this verse in the full
+ # context of its own chapter"), but silently falling back to the guard's
+ # own location on a missing/malformed `suggested_chapter` masks
+ # data-quality bugs. Fail loudly instead.
+ if not isinstance(suggested, dict):
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} is missing "
+ f"`suggested_chapter` or it is not an object"
+ )
+ suggested_book_id = suggested.get('book_id')
+ suggested_chapter_num = suggested.get('chapter_num')
+ if not suggested_book_id or not suggested_chapter_num:
+ raise ValueError(
+ f"proof_text_guards: guard {guard.get('ref')!r} has incomplete "
+ f"`suggested_chapter` (book_id={suggested_book_id!r}, "
+ f"chapter_num={suggested_chapter_num!r}); both are required"
+ )
+ cur.execute(
+ 'INSERT OR REPLACE INTO proof_text_guards '
+ '(ref, book_id, chapter_num, verse_num, common_misreading, '
+ 'actual_context_summary, suggested_book_id, suggested_chapter_num) '
+ 'VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+ (
+ guard['ref'],
+ guard['book_id'],
+ guard['chapter_num'],
+ guard['verse_num'],
+ guard['common_misreading'],
+ guard['actual_context_summary'],
+ suggested_book_id,
+ suggested_chapter_num,
+ ),
+ )
+ count += 1
+ return count
+
+
 def populate_people(cur):
  data = _load_json(META / 'people.json')
  people = data.get('people', [])

_tools/build_sqlite_schema.py

@@ -92,6 +92,19 @@
  at_a_glance TEXT
 );
 
+CREATE TABLE proof_text_guards (
+ ref TEXT PRIMARY KEY,
+ book_id TEXT NOT NULL REFERENCES books(id),
+ chapter_num INTEGER NOT NULL,
+ verse_num INTEGER NOT NULL,
+ common_misreading TEXT NOT NULL,
+ actual_context_summary TEXT NOT NULL,
+ suggested_book_id TEXT NOT NULL,
+ suggested_chapter_num INTEGER NOT NULL
+);
+CREATE INDEX idx_proof_text_guards_lookup
+ ON proof_text_guards(book_id, chapter_num, verse_num);
+
 CREATE TABLE people (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,

app/__tests__/components/guidedStudy/ConfidenceBadge.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ConfidenceBadge } from '@/components/guidedStudy/ConfidenceBadge';
+
+describe('ConfidenceBadge', () => {
+ it('renders the human label for each confidence level', () => {
+ const { getByText, rerender } = renderWithProviders(<ConfidenceBadge level="consensus" />);
+ expect(getByText('Consensus')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="majority" />);
+ expect(getByText('Majority')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="debated" />);
+ expect(getByText('Debated')).toBeTruthy();
+
+ rerender(<ConfidenceBadge level="minority" />);
+ expect(getByText('Minority')).toBeTruthy();
+ });
+
+ it('renders nothing when level is undefined', () => {
+ const { toJSON } = renderWithProviders(<ConfidenceBadge />);
+ expect(toJSON()).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/ContextGuardBanner.test.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { ContextGuardBanner } from '@/components/guidedStudy/ContextGuardBanner';
+
+const guard = {
+ ref: 'jeremiah 29:11',
+ book_id: 'jeremiah',
+ chapter_num: 29,
+ verse_num: 11,
+ common_misreading: 'Personal promise of prosperity',
+ actual_context_summary: 'Letter to Judean exiles in Babylon',
+ suggested_book_id: 'jeremiah',
+ suggested_chapter_num: 29,
+};
+
+describe('ContextGuardBanner', () => {
+ it('renders nothing when no guard is passed', () => {
+ const { toJSON } = renderWithProviders(
+ <ContextGuardBanner guard={null} onReadContext={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders the common-misreading copy and action link', () => {
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(getByText('READ IN CONTEXT')).toBeTruthy();
+ expect(getByText('Personal promise of prosperity')).toBeTruthy();
+ expect(getByText('Open the surrounding chapter')).toBeTruthy();
+ });
+
+ it('fires onReadContext when the action row is tapped', () => {
+ const onReadContext = jest.fn();
+ const { getByText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={onReadContext} />,
+ );
+ fireEvent.press(getByText('Open the surrounding chapter'));
+ expect(onReadContext).toHaveBeenCalledTimes(1);
+ });
+
+ it('hides itself after the dismiss button is tapped', () => {
+ const { queryByText, getByLabelText } = renderWithProviders(
+ <ContextGuardBanner guard={guard} onReadContext={jest.fn()} />,
+ );
+ expect(queryByText('READ IN CONTEXT')).toBeTruthy();
+ fireEvent.press(getByLabelText('Dismiss context note'));
+ expect(queryByText('READ IN CONTEXT')).toBeNull();
+ });
+});

app/__tests__/components/guidedStudy/HomeReviewDueCard.test.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { HomeReviewDueCard } from '@/components/guidedStudy/HomeReviewDueCard';
+
+describe('HomeReviewDueCard', () => {
+ it('renders nothing when count is zero', () => {
+ const { toJSON } = renderWithProviders(
+ <HomeReviewDueCard count={0} onPress={jest.fn()} />,
+ );
+ expect(toJSON()).toBeNull();
+ });
+
+ it('renders singular copy when exactly 1 prompt is due', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={1} onPress={jest.fn()} />,
+ );
+ expect(getByText('1 prompt due today')).toBeTruthy();
+ });
+
+ it('renders pluralized copy for multiple prompts', () => {
+ const { getByText } = renderWithProviders(
+ <HomeReviewDueCard count={7} onPress={jest.fn()} />,
+ );
+ expect(getByText('7 prompts due today')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <HomeReviewDueCard count={3} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('3 study review prompts due'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/PanelRecommendationRow.test.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { PanelRecommendationRow } from '@/components/guidedStudy/PanelRecommendationRow';
+
+describe('PanelRecommendationRow', () => {
+ const baseRec = {
+ key: 'ctx-1',
+ title: 'Historical Context',
+ subtitle: 'Ancient Near Eastern background',
+ panelType: 'ctx',
+ };
+
+ it('renders title and subtitle', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={jest.fn()} />,
+ );
+ expect(getByText('Historical Context')).toBeTruthy();
+ expect(getByText('Ancient Near Eastern background')).toBeTruthy();
+ });
+
+ it('renders a confidence badge when a level is provided', () => {
+ const { getByText } = renderWithProviders(
+ <PanelRecommendationRow
+ recommendation={{ ...baseRec, confidence: 'debated' } as any}
+ onPress={jest.fn()}
+ />,
+ );
+ expect(getByText('Debated')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <PanelRecommendationRow recommendation={baseRec as any} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Open Historical Context'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionCTA.test.tsx

@@ -0,0 +1,25 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionCTA } from '@/components/guidedStudy/StudySessionCTA';
+
+describe('StudySessionCTA', () => {
+ const estimate = { readMin: 3, guidedMin: 8, deepMin: 20 };
+
+ it('renders the estimate line with all three durations', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={jest.fn()} />,
+ );
+ expect(getByText('Study this chapter')).toBeTruthy();
+ expect(getByText('3 min read · 8 min guided · 20 min deep')).toBeTruthy();
+ });
+
+ it('fires onPress when tapped', () => {
+ const onPress = jest.fn();
+ const { getByLabelText } = renderWithProviders(
+ <StudySessionCTA estimate={estimate} onPress={onPress} />,
+ );
+ fireEvent.press(getByLabelText('Study this chapter'));
+ expect(onPress).toHaveBeenCalledTimes(1);
+ });
+});

app/__tests__/components/guidedStudy/StudySessionStepper.test.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { fireEvent } from '@testing-library/react-native';
+import { renderWithProviders } from '../../helpers/renderWithProviders';
+import { StudySessionStepper } from '@/components/guidedStudy/StudySessionStepper';
+
+describe('StudySessionStepper', () => {
+ it('renders all five canonical steps', () => {
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={jest.fn()} />,
+ );
+ ['Scene', 'Observe', 'Explore', 'Synthesize', 'Review'].forEach((label) => {
+ expect(getByText(label)).toBeTruthy();
+ });
+ });
+
+ it('fires onSelect with the tapped step key', () => {
+ const onSelect = jest.fn();
+ const { getByText } = renderWithProviders(
+ <StudySessionStepper activeStep="scene" onSelect={onSelect} />,
+ );
+ fireEvent.press(getByText('Explore'));
+ expect(onSelect).toHaveBeenCalledWith('explore');
+ });
+});

app/__tests__/db/userDatabase.test.ts

@@ -5,7 +5,9 @@
 const mockExecAsync = jest.fn().mockResolvedValue(undefined);
 const mockGetAllAsync = jest.fn().mockResolvedValue([]);
 const mockRunAsync = jest.fn().mockResolvedValue({ changes: 0 });
-const mockWithTransactionAsync = jest.fn().mockImplementation(async (cb: () => Promise<void>) => cb());
+const mockWithTransactionAsync = jest
+ .fn()
+ .mockImplementation(async (cb: () => Promise<void>) => cb());
 const mockOpenDatabaseAsync = jest.fn();
 
 jest.mock('expo-sqlite', () => ({
@@ -76,11 +78,12 @@ describe('userDatabase', () => {
  it('skips already applied migrations', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate all migrations already applied
  mockGetAllAsync.mockResolvedValueOnce(
- Array.from({ length: 18 }, (_, i) => ({ version: i + 1 })),
+ Array.from({ length: MIGRATION_COUNT }, (_, i) => ({ version: i + 1 })),
  );
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
  // withTransactionAsync should NOT have been called since all migrations are applied
  expect(mockWithTransactionAsync).not.toHaveBeenCalled();
@@ -89,12 +92,13 @@ describe('userDatabase', () => {
  it('runs pending migrations in order', async () => {
  jest.doMock('react-native', () => ({ Platform: { OS: 'ios' } }));
  jest.resetModules();
+ userDatabaseModule = require('@/db/userDatabase');
+ const { MIGRATION_COUNT } = userDatabaseModule;
  // Simulate only version 1 applied
  mockGetAllAsync.mockResolvedValueOnce([{ version: 1 }]);
- userDatabaseModule = require('@/db/userDatabase');
  await userDatabaseModule.initUserDatabase();
- // Should run 17 remaining migrations (2 through 18)
- expect(mockWithTransactionAsync).toHaveBeenCalledTimes(17);
+ // Should run the remaining migrations (2 through MIGRATION_COUNT)
+ expect(mockWithTransactionAsync).toHaveBeenCalledTimes(MIGRATION_COUNT - 1);
  });
 
  it('throws on migration failure', async () => {