Spanish/app_features.md

# Spanish Conjugation Apps — Feature Comparison

Side-by-side feature analysis of **Conjuga** (this project), **ConjuGato**, and **Conjuu ES**, based on App Store screenshots, extracted app data, and this repository's source.

---

## Conjuga (this project)

**Platform:** iOS 18+ (iOS 26 required for Foundation Models features)
**Monetization:** —
**Tech stack:** SwiftUI + SwiftData (dual local / CloudKit stores), SharedModels Swift Package, Foundation Models, Vision, Speech, WidgetKit

The Practice tab is organised into three sections — **Conjugation**, **Vocabulary**, and **Reading**.

### Practice — Conjugation

- **Six core conjugation modes** — flashcards, typing, multiple choice, handwriting (Apple Pencil + finger), sentence builder, full table (all persons at once)
- **Focus modes** — weak verbs (SM-2 SRS), irregularity drills (spelling / stem / unique, selectable), common tenses
- **Quick answer review** with per-form irregular-span highlighting

### Practice — Vocabulary

- **Vocab Flashcards** — English → Spanish verb recall over the verb table, filtered by enabled Levels (shared with the Verbs-tab filter). Two-layer SRS: a position-based in-session learning queue (Again/Hard requeue 5–10 cards later, Good moves ~20 ahead, a second Good or Easy graduates) on top of the long-term SM-2 schedule. Due-first session ordering, session size configurable in Settings.
  - **Quiz mode** — tap-to-reveal + Again/Hard/Good/Easy rating
  - **Learn mode** — both sides shown at once, Next/Previous browsing on a loop, no rating
- **Vocab Multiple Choice** — same pool/SRS; pick the Spanish verb from 4 options, distractors prefer matching part of speech
- **Vocab SRS Review** — spaced repetition over *course* vocabulary (distinct from the verb-table flashcards) with Again / Hard / Good / Easy rating

### Practice — Reading

- **AI short stories** — generated stories with tappable words + comprehension quiz
- **Books** — full-length bilingual EPUB-imported books; chapter reader with tap-to-define, Spanish/English toggle, and read-aloud (TTS with active-word highlighting, tap-to-pause-and-define, voice + speed picker)
- **Lyrics practice** — search Spanish songs, translate line by line
- **Conversational practice** — on-device AI chat partner (Apple Foundation Models) with 10 scenarios, tappable words that open dictionary or on-demand AI lookup
- **Listening practice** — listen-and-type + pronunciation scoring via Speech framework, word-by-word match
- **Cloze practice** — fill-in-the-blank with distractor generation from vocab pool

### Verb Reference

- **1,750 verbs**, 5 levels (Basic / Elementary / Intermediate / Advanced / Expert), 209 K pre-conjugated forms
- **20 tenses** with character-level irregular-span highlighting (spelling / stem / unique)
- **Irregularity filter** — All / Any Irregular / Spelling Change / Stem Change / Unique Irregular — combinable with level
- **Per-verb detail** with per-form English translations and tense-grouped table
- **Text-to-speech** on any conjugated form

### Grammar & Content

- **20 tense guides** — teacher-handout depth: usage cases, conjugation tables, common irregulars, mnemonics (WEIRDO, ESCAPA, etc.), pitfalls, and contrast with neighbouring tenses
- **36 grammar topic notes** (ser/estar, por/para, preterite/imperfect, subjunctive triggers, personal *a*, suffixes, irregular yo forms, stem-changers, etc.) — each with a mnemonic, contrast examples, and a common-pitfalls section
- **Guide cross-links** — tense guides and grammar notes link bidirectionally ("Related grammar" / "Used in tenses" chips)
- **Grammar exercises** — interactive quizzes for core topics
- **Course decks** — weekly vocabulary with example sentences, week tests, cumulative checkpoint exams
- **Extra Study** — star cards during course flashcard review; each week surfaces an "Extra Study" row to drill just the starred cards (iCloud-synced)
- **Textbook reader** — 30 chapters of *Complete Spanish Step-by-Step* with 251 interactive exercises (keyboard + Apple Pencil), vocab tables rendered as paired Spanish→English grids
- **Textbook extraction pipeline** — XHTML + answer-key parsers, macOS Vision image OCR, PDF page OCR, LLM-vision vocab-pair pass, NSSpellChecker validator, language-aware auto-fixer
- **Books pipeline** (`Scripts/books/`) — EPUB → chapter JSON extractor, Claude-subagent translation pass, bundler

### Offline Dictionary

- **Reverse index of 175 K verb forms + 200 common words**, cached to disk
- **Tappable-word lookup** in chat bubbles and stories; falls back to Foundation Models `@Generable ChatWordInfo` when a word isn't in the dictionary

### Progress & Sync

- **SM-2 spaced repetition** for conjugation review, course vocab, and verb-table vocab (separate `VerbReviewCard` schedule)
- **In-session learning queue** for vocab practice — position-based requeue layered on top of the SM-2 schedule
- **Streaks, daily goals, accuracy stats, achievement badges**
- **Study-time tracking** per day (foreground time)
- **CloudKit private-database sync** — review cards, verb review cards, user progress, test results, daily logs, saved songs, stories, conversations, textbook exercise attempts, extra-study marks
- **Background app refresh** for widget data

### Widgets

- **Combined dashboard** (word of day + stats)
- **Word-of-day** standalone
- Both refresh daily and on app backgrounding

### Settings & Filters

- **Selectable verb level** (shared between Settings and the Verbs-tab filter) and **enabled tenses**
- **Include vosotros** toggle
- **Auto-fill verb stem** toggle for Full Table practice
- **Cards per session** — vocab flashcard / multiple-choice session size (10–50 or All)
- **Feature reference** page in Settings documenting every feature and which settings affect it

### Data (in repo)

| Asset | Count |
|-------|-------|
| Verbs | 1,750 |
| Verb forms (pre-conjugated) | 209,014 |
| Irregular span annotations | 23,795 |
| Tenses | 20 |
| Tense guides | 20 (enriched to teacher-handout depth) |
| Grammar notes | 36 |
| Textbook chapters | 30 |
| Textbook exercises | 251 |
| Offline dictionary forms | 175,425 |
| Bundled books | 1 (Olly Richards — *Spanish Short Stories Vol 2*, 13 chapters) |

---

## ConjuGato

**Platform:** iOS (iPad-style app via Mac Catalyst)
**Monetization:** One-time purchase, no subscriptions
**Tech stack:** .NET MAUI (Xamarin), SQLite, MvvmCross

### Practice Mode

- **Flashcard-style quiz** — shows English meaning, infinitive, tense tag (Presente/Subjuntivo), random pronoun
- **Tap to reveal** answer below the blank line
- **Daily goal tracker** — progress bar at top (e.g. 25/100)
- **Self-rating** — rate answers as Easy/Hard after reveal (no typing)
- **Spaced repetition** — tracks conjugation ratings with star system (1–5 stars) and heart indicators
- **Practice history** — shows today/yesterday verb performance with star ratings

### Verb Reference

- **1,750 verbs** ranked by frequency/popularity
- **Searchable verb list** sorted by popularity
- **Full conjugation tables** per verb with Indicative/Subjunctive/Others tabs
- **All 6 persons** — yo, tú, él/ella/Ud., nosotros, vosotros, ellos/ellas/Uds.
- **27 tenses** including progressive forms and compound tenses

### Grammar Explanations

- **Visual conjugation breakdown** — shows stem + ending decomposition (e.g. `habl- → drop ending → +o`)
- **Color-coded irregular highlighting** — each span of an irregular form colored by change type (spelling, stem, unique)
- **Irregularity classification** — each form labeled as Regular (green), Spelling change, Stem change, or Highly irregular
- **Star ratings** — ★★★ regular, ★★ stem change, ★ irregular
- **Similar forms listed** — shows other verbs that follow the same pattern (e.g. "Similar forms: satisfago, deshago")
- **Tense guides** — explains what each tense is used for with:
  - Usage rules in plain English
  - Mnemonics (e.g. "apply the movie rule: Imperfect = setting, Preterite = plot")
  - Example sentences with Spanish + English + audio
  - Tips for avoiding common confusions (e.g. Preterite vs Imperfect)

### Mnemonic Rhymes

- **Rhyming verb groups** — groups verbs that sound alike for memorization (e.g. picar, pecar, pegar, pagar, pasar, pisar, pesar, pensar)
- **Dedicated Rhymes tab** in bottom navigation

### Audio

- **Tap to pronounce** any conjugation in the verb table
- **Auto-pronounce answers** option in settings
- **Audio on tense guide examples**
- Uses iOS text-to-speech (no bundled audio files)

### Settings & Filters

- **Tense filters** — toggle individual tenses on/off: Present, Preterite, Imperfect, Conditional, Future, all Subjunctive forms
- **Show progressive forms** toggle
- **Show tense names in Spanish** toggle
- **Verb ending filters** — practice only -AR, -ER, or -IR verbs
- **Conjugation difficulty filters:**
  - Fully regular
  - With spelling changes
  - With stem changes
  - Highly irregular
- **Hide "vosotros" conjugations**
- **Auto-pronounce answers**
- **Verb count display** — shows how many verbs match current filters (e.g. "848")

### Navigation

- **5 tabs:** Practice, Rhymes, Verbs, Settings (bottom bar)
- **"Get Pro" tab** for upgrade

### Data (extracted)

| Asset | Count |
|-------|-------|
| Verbs | 1,750 |
| Irregular verb forms | 14,163 |
| Irregular span annotations | 23,795 |
| Irregularity bitmasks | 627 verbs |
| Example sentences | separate SQLite DB |
| Translations | 8 languages |

---

## Conjuu ES

**Platform:** macOS native + iOS
**Monetization:** Free tier (25 Basic verbs) + paid unlock
**Tech stack:** Native Swift/Obj-C, Core Data

### Practice Mode

- **Typing-based quiz** — fill in all 5 person forms (yo, tú, él, nosotros, ellos) for a given verb + tense
- **Full-table entry** — type all forms at once, then tap "Answer" to check
- **Progress counter** — "1/5" in top-left shows quiz position
- **Session-based practice** — complete a set of verbs per session
- **Keyboard input** — full keyboard with Spanish character support
- **Hard/Easy self-rating** after each answer

### Verb Reference

- **621 verbs** with frequency rankings
- **Searchable verb list**
- **Full conjugation tables** — all 6 persons × 20 tenses
- **4-language translations** — English, Japanese, Chinese Simplified, Chinese Traditional
- **Regularity labeling** — ordinary, irregular, regular, orto (orthographic change)

### Grammar Explanations

- **Tense guide popups** — full-screen modal with:
  - Conjugation ending table showing -AR/-ER/-IR patterns side by side
  - Color-coded endings (stem in white, ending in colored text)
  - Numbered usage rules
  - Example sentences with Spanish + English translations
  - "GOT IT!" dismiss button
- **7 usage categories** for Present tense alone:
  1. Current actions and situations
  2. Abilities and descriptions
  3. Habitual actions
  4. Absolute and universal truths
  5. Actions in the near future
  6. Recounting historical events
  7. Conditional sentences

### Tense Selection

- **20 tenses** organized by mood:
  - **Indicative:** Presente, Perfecto, Imperfecto, Pluscuamperfecto, Pretérito, Pretérito Anterior, Futuro, Futuro Perfecto
  - **Subjunctive:** Presente, Perfecto, Imperfecto I, Imperfecto II, Pluscuamperfecto I, Pluscuamperfecto II
  - **Conditional:** Presente, Perfecto (listed under Indicative in UI)
  - **Imperative:** Afirmativo, Negativo (listed under Subjunctive in UI)
- **Checkbox toggles** — enable/disable each tense for practice
- **All visible at once** in sidebar panel

### Study Lists & Difficulty Levels

- **8 built-in levels:**
  - Basic (25 verbs)
  - Elementary 1–3 (83 verbs)
  - Intermediate 1–4 (112 verbs)
  - Advanced (344 verbs)
- **"All verbs"** option (621 verbs)
- **Custom lists** — "My Lists" section with ability to create personal lists
- **Pinboard** — save specific verbs for focused review
- **Study/Review toggle** — switch between learning and review modes

### Audio

- Not visible in screenshots (no speaker icons on practice screen)
- macOS app may use system TTS

### Settings & Filters

- **Tense selection panel** — sidebar with checkboxes per tense
- **Study list selection** — dropdown for difficulty level
- **Daily goal** — choose practice intensity:
  - 20 verbs / ~5 min (Casual)
  - 50 verbs / ~10 min (Regular)
  - 75 verbs / ~15 min (Focused)
  - 100 verbs / ~20 min (Committed)

### Navigation

- **macOS sidebar** with Study/Review tabs
- **iOS bottom tabs:** Practice, Rhymes, Get Pro, Verbs, Settings
- **Study Lists** in left sidebar with collapsible groups

### Data (extracted)

| Asset | Count |
|-------|-------|
| Verbs | 621 |
| Conjugated rows | 12,406 (all forms pre-computed) |
| Tenses | 20 |
| Tense guides | 20 (with usage rules + examples) |
| Conjugation rule templates | 20 tenses × 3 verb types |
| Difficulty levels | 8 |
| Translations | 4 languages |

---

## Feature Comparison

| Feature | Conjuga | ConjuGato | Conjuu ES |
|---------|---------|-----------|-----------|
| **Verb count** | 1,750 | 1,750 | 621 |
| **Tenses** | 20 | 27 | 20 |
| **Practice style** | Flashcards, typing, MC, handwriting, sentence builder, full table | Flashcard (tap to reveal) | Typing (fill in forms) |
| **Input method** | All four (type / tap / write / speak) | Self-rate (no typing) | Type conjugation |
| **Daily goals** | Numeric counter + streaks + study-time | Numeric counter (25/100) | 4 presets (Casual→Committed) |
| **Spaced repetition** | SM-2 (verb forms + vocab cards) | Yes (star + heart ratings) | Session-based review |
| **Grammar breakdown** | Character-level irregular span highlighting | Color-coded span highlighting | Ending table + usage rules |
| **Irregularity detail** | 3-level (spelling/stem/unique) + per-verb badges + filter | 3-level with character spans | 4-label (ordinary/irregular/regular/orto) |
| **Tense explanations** | 20 guides + 20 grammar notes with 100+ exercises each | In-app guides with mnemonics | Modal popups with usage categories |
| **Example sentences** | Per-tense + per-card + per-story + in textbook | Per-tense with audio | Per-tense in guide popups |
| **Audio** | TTS on any form + pronunciation scoring | Tap any conjugation + auto-pronounce | Not prominent |
| **Difficulty levels** | 5 levels + irregularity filter (combinable) | Filter by irregularity type | 8 graded word lists |
| **Custom lists** | — | No | Yes (My Lists + Pinboard) |
| **Verb filters** | Level + irregularity category + tense selection + search | Ending type + irregularity + tense | Tense checkboxes + level |
| **AI features** | On-device chat, stories, word lookups (Foundation Models) | — | — |
| **Textbook** | 30 chapters, 251 exercises, ~3,100 vocab pairs (OCR pipeline) | — | — |
| **Listening / speech** | Listen-and-type + pronunciation scoring | — | — |
| **Offline dictionary** | 175 K forms | — | — |
| **Lyrics** | Search + translate | — | — |
| **CloudKit sync** | Yes (private database) | — | — |
| **Widgets** | Combined + word-of-day | — | — |
| **Platform** | iOS 18+ (iOS 26 for AI) | iOS (Catalyst) | macOS + iOS |
| **Monetization** | — | One-time purchase | Free tier + paid |
| **vosotros toggle** | Yes | Yes | Not visible |

## Unique Strengths

### Conjuga excels at:
- **Breadth of modes** — six conjugation practice styles plus cloze, listening, lyrics, chat, stories, textbook, and vocab review in one app
- **AI integration** — on-device Foundation Models power the chat partner, story generator, and dictionary fallback lookup with no cloud round-trips
- **Textbook reader** — full *Complete Spanish Step-by-Step* textbook with 251 interactive exercises and 3,100 OCR-paired vocab cards, built via an in-repo extraction pipeline
- **Combinable filters** — Level × Irregularity × search on the verb list, with per-row category badges
- **Multi-input practice** — type, tap, Apple Pencil handwriting, and voice (pronunciation scoring)
- **Offline dictionary** — 175 K verb-form reverse index makes word lookups instant and network-free
- **CloudKit sync** — progress, tests, saved content, and conversations travel between devices

### ConjuGato excels at:
- **Breadth** — nearly 3× the verbs
- **Irregularity teaching** — character-level color-coded highlighting showing exactly *why* each form is irregular
- **Rhyming mnemonics** — unique memorization technique grouping similar-sounding verbs
- **Audio integration** — every conjugation is tappable for pronunciation
- **Quick practice** — flashcard format is faster per verb than typing
- **Tense coverage** — 27 tenses including progressive forms

### Conjuu ES excels at:
- **Active recall** — typing forces recall vs passive recognition
- **Complete conjugation tables** — every form pre-computed and stored
- **Structured difficulty** — 8 graded levels from Basic to Advanced
- **Tense explanations** — richer usage guides with numbered categories
- **Conjugation rules** — extractable ending patterns for all verb types
- **Custom study lists** — personalized verb collections
- **Multi-platform** — native macOS app with full-screen practice
- **Full-table practice** — fill in all 5 persons at once, not just one random pronoun