WrittenWord

A comprehensive iPad Bible study application combining modern SwiftUI development with advanced biblical scholarship tools

WrittenWord is an offline-first Bible study platform designed specifically for iPad, featuring text highlighting, handwritten annotations via Apple Pencil, note-taking, bookmarks, cross-references, footnotes, interlinear word lookup for Greek and Hebrew original language study, and continuous book-level scrolling.

Features

Bible Reading

• NASB 1995 Translation: Complete New American Standard Bible (1995 edition) with all 66 books
• Offline-First: All biblical text stored locally using SwiftData
• Smooth Navigation: NavigationSplitView architecture with sidebar navigation
• Continuous Scrolling: Seamless vertical scrolling between chapters within a book
• Chapter-by-Chapter Reading: Traditional chapter view with optimized verse rendering
• Reading Modes: Toggle between compact and spacious layouts with configurable whitespace for annotation space
• Italic Rendering: Proper italic display for translator-supplied words in the NASB text
• Red Letter Display: Words of Jesus displayed in red with configurable toggle in Settings

Study Tools

• Text Highlighting: Select and highlight verses with customizable colors
• PencilKit Annotations: Verse-anchored handwritten notes and drawings with Apple Pencil, with floating compact toolbar
• Full-Page Drawing: Dedicated full-page PencilKit canvas for detailed verse notes
• Note-Taking: Create detailed study notes linked to specific verses or chapters
• Bookmarks: Save and organize important passages with categories, colors, and pinning
• Cross-References: STEPBible-sourced cross-reference links between passages with confidence scores
• Footnotes: Translation footnotes displayed inline with nested tag support
• Search Functionality: Fast, comprehensive search across the entire Bible with predicated queries
• Concordance: Explore word usage across the Bible via Strong's number lookup
• Study Export: Export highlights, bookmarks, and notes as shareable Markdown with Lockman 500-verse limit compliance

Interlinear Word Lookup

• Greek & Hebrew Analysis: Tap any word to view original language information
• Word Details:
  • Original text (Greek/Hebrew)
  • Transliteration
  • Strong's concordance numbers
  • English gloss/definition
  • Detailed morphological analysis (part of speech, tense, mood, voice, case, etc.)
  • Word position tracking within verses
• Coverage: Complete Greek NT (STEPBible TAGNT) and Hebrew OT (TAHOT) interlinear data for all 66 books
• Alignment: 94.4% adjusted accuracy across 421K words with function word bridging
• Multi-Word Phrase Spanning: Alignment bridges over NASB-inserted function words (articles, prepositions) to correctly map multi-word Greek/Hebrew phrases
• Original Language Mode: Inline highlighting with per-word tint rendering and punctuation exclusion
• Lexicon: Full Greek and Hebrew lexicons with Strong's number lookup, definitions, and brief glosses

Customization

• Theme System: 5 themes — System, Light, Dark, Sepia, and Sand — with full color compliance across all views
• Font Options: 4 font families — System, Serif (Georgia), Rounded, and Monospaced
• Adjustable Text: Configurable font size, line spacing, and left/right margins
• Continue Where You Left Off: Resume banner on launch with last reading position

Data Protection

• User Data Backup: Three-layer protection — local rolling backups, iCloud device backup, and pre-migration snapshots
• CloudKit Sync: iCloud sync for highlights, bookmarks, notes, and annotations across devices
• SwiftData Migration Plan: VersionedSchema and SchemaMigrationPlan baseline for safe schema evolution
• Pre-seeded Database: reference.sqlite ships pre-built for instant launch — no first-run seeding delay

Technology Stack

• Language: Swift
• UI Framework: SwiftUI with UIKit integration (TextKit 1 for verse rendering, PencilKit for annotations)
• Data Persistence: SwiftData with two-store architecture (read-only reference store + read-write user store)
• Cloud Sync: CloudKit (user store)
• Minimum iOS: 18.6
• Platform: iPad only (iPhone version planned)
• Xcode: Folder-synced groups (objectVersion 77)

Architecture

Two-Store SwiftData Design

WrittenWord uses a single ModelContainer with two ModelConfiguration instances:

• Reference Store (reference.sqlite): Bible text, interlinear words, cross-references, footnotes, lexicon entries — pre-seeded, read-only by convention
• User Store (default location): Highlights, bookmarks, notes, chapter annotations, book annotations — read-write with CloudKit sync

Data Pipeline

convert_nasb.py → align_interlinear.py → validate_alignment.py → compress_bundle_json.py → ReferenceDBGenerator → reference.sqlite

Python scripts process source data into compressed .jsonz files, which the ReferenceDBGenerator macOS CLI target loads into a SwiftData store. The resulting reference.sqlite is copied into the app bundle.

Codebase

• 83 production Swift files (~20,715 lines)
• 11 test files (2,355 lines, 154 test methods)
• 11 Python pipeline scripts (6,146 lines)
• ~16 MB bundled resources (compressed from 169 MB via .jsonz format)

Getting Started

Prerequisites

• Xcode 16.0+
• iOS 18.6+ iPad simulator or device
• macOS 15.0+ (for ReferenceDBGenerator target)

Setup

1. Clone the repository

   git clone https://github.com/yourusername/WrittenWord.git
   cd WrittenWord

2. Generate Reference Database (if not present)

   # Run the ReferenceDBGenerator macOS target in Xcode
   # Then manually add reference.sqlite to Copy Bundle Resources

3. Build and Run

   • Select an iPad simulator or device
   • Press Cmd + R to build and run

Data Sources & Licensing

Bible Text

• Translation: NASB 1995 (New American Standard Bible, 1995 edition)
• License: Licensed from The Lockman Foundation. 500-verse sharing limit enforced in study exports.

Interlinear Data

• Greek New Testament: STEPBible TAGNT (Translators Amalgamated Greek New Testament)
  • Source: STEPBible-Data GitHub
  • License: Creative Commons Attribution 4.0 International
• Hebrew Old Testament: STEPBible TAHOT (Translators Amalgamated Hebrew Old Testament)
  • Source: STEPBible-Data GitHub
  • License: Creative Commons Attribution 4.0 International
• Alignment: Custom Python pipeline achieves 94.4% adjusted alignment across 421K words

Cross-References

• Source: STEPBible cross-reference data
• License: Creative Commons Attribution 4.0 International

Lexicons

• Greek Lexicon: Abbott-Smith's Manual Greek Lexicon (public domain), enriched with Dodson Greek-English Lexicon glosses (public domain)
  • Abbott-Smith source: Tyndale House / Translatable Exegetical Tools
  • Dodson source: biblicalhumanities/Dodson-Greek-Lexicon
  • Coverage: 5,453 entries, 99% briefGloss coverage
• Hebrew Lexicon: Brown-Driver-Briggs Hebrew and English Lexicon, enhanced by unfoldingWord (CC BY)
  • Coverage: ~7,500 entries, ~91% briefGloss coverage

Development Roadmap

Current Status (v1.1 In Development)

• Complete NASB 1995 Bible reading interface
• Text highlighting with multiple colors
• PencilKit verse-anchored handwritten annotations with compact floating toolbar
• Full-page drawing view for verse notes
• Note-taking system
• Bookmark management with categories and pinning
• Global search functionality with predicated queries
• Full interlinear lookup (Greek NT + Hebrew OT) with lexicon
• Interlinear alignment at 94.4% adjusted accuracy (421K words) with function word bridging
• Original language inline highlighting mode with per-word tint rendering and punctuation exclusion
• Concordance with frequency charts and section filtering
• Cross-references (STEPBible) with confidence scores
• Footnotes with nested tag support
• Continuous book-level scrolling
• Database indexes for query performance
• Theme-aware color system (5 themes, full audit completed)
• Reading mode toggle (compact/spacious)
• Italic text rendering
• Red letter display for words of Jesus with configurable toggle
• SwiftData VersionedSchema and migration plan baseline
• User data backup system with three-layer protection (local rolling backups, iCloud device backup, pre-migration snapshots)
• VoiceOver accessibility labels across interactive elements
• Pre-seeded reference.sqlite database for instant launch
• Study data export (Markdown) with Lockman 500-verse limit compliance
• Continue Where You Left Off — resume banner on launch with last reading position

Remaining Pre-Release Work

• OL Underline Alignment: Fix original language underline misalignment in OT (notably Gen 9:6–7, Psalm 119)
• Canvas Bounce: Resolve fast-scrolling canvas bounce in annotation mode
• Accessibility: Expand VoiceOver support to primary reading view and remaining interactive elements

Planned Features

• iPhone Version: Same codebase, typed notes instead of drawn notes (no PencilKit)
• Bidirectional Scrolling: Scroll up to prepend earlier chapters in continuous reading mode
• Study Plans: Guided reading plans and devotionals
• Verse Comparison: Side-by-side translation comparison
• Split View: Side-by-side passage or passage + notes view
• Keyboard Shortcuts: Magic Keyboard support for common actions
• Audio Bible: Integrated audio playback
• Commentary Integration: Matthew Henry, Barnes' Notes, etc.

Performance Considerations

Optimizations Implemented

• Pre-seeded Database: reference.sqlite ships ready — zero first-launch delay
• Database Indexes: Compound indexes on canonical coordinates across all 10 models
• Resource Compression: .jsonz format reduced bundle from 169 MB to ~16 MB
• Lazy Loading: Verses and interlinear data loaded on-demand per chapter
• Verse-Anchored Annotations: PencilKit strokes stored relative to verse positions for layout resilience
• Predicated Queries: All FetchDescriptor calls use predicates — no full-table scans on reference data
• Hash-Based Rendering: computeTextInputHash() prevents expensive text rebuilds in the primary text view
• Async Operations: Heavy operations run asynchronously with proper @MainActor isolation
• Annotation Persistence: Robust save pipeline with flush-on-toggle, flush-on-background, and flush-on-cleanup

Known Limitations

• Text selection for highlighting uses UITextView (TextKit 1) — performance trade-offs for complex selection
• PencilKit annotation reflow on font/margin changes is disabled (PKDrawing.transformed() corrupts stroke identifiers)
• Device rotation causes slight stroke offset (~4 verses) in annotations
• LazyVStack lacks scroll anchoring — bidirectional chapter prepending causes position jumps

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow Swift style guidelines
4. Write descriptive commit messages
5. Test thoroughly on both simulator and device
6. Submit a pull request with a clear description

License

This project is proprietary. See the LICENSE file for details.

Bible text (NASB 1995) is licensed from The Lockman Foundation. Interlinear data from STEPBible is used under CC BY 4.0. Greek lexicon from Abbott-Smith (public domain) enriched with Dodson (public domain). Hebrew lexicon from unfoldingWord Enhanced BDB (CC BY).