From 62613d4c7b57c7d32a6e5ad542aa676b05ed81e4 Mon Sep 17 00:00:00 2001
From: Navid Shad <navidshad72@gmail.com>
Date: Sun, 24 May 2026 18:56:56 +0300
Subject: [PATCH 1/5] feat(flashcard): new translation shape + L3+ fill-in
 cloze

Read the new chunk-aware translation shape and add a fill-in-the-blank
review card at Leitner level 3+, with recognition fallback.

- Stop reading linguistic_data.examples[] / phonetic.ipa (gone after the
  save-schema overhaul); show phrase.translation plus per-chunk
  definitions on the card back, matching what the save modal displays.
  Same fix applied to the bundle PhraseCard list.
- L3+ cloze: blank every confirmed chunk found in the source sentence;
  per-blank Check with green/red feedback, repeatable Recheck, and a
  Clear-wrong action to retry. Falls back to the recognition card when
  there is no chunk or the level is 1-2.
- Wire chunks / Leitner level / source sentence through the review
  session; read boxLevel from the Mongoose _doc fallback and pick chunks
  that actually appear in the sentence.
- Stable layout: fixed card height with internal scroll, and the cloze
  front is split into a flex-grow content area + a fixed-height action
  area so checking never shifts the sentence.
- Expose the Chunk type to the frontend.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend/components/bundle/PhraseCard.vue     |  11 +-
 .../practice/LeitnerReviewSession.vue         |  39 ++-
 frontend/components/widget/FlashCard.vue      | 273 ++++++++++++++----
 frontend/pages/practice/flashcards-[id].vue   |  23 +-
 frontend/types/database.type.ts               |   6 +-
 5 files changed, 284 insertions(+), 68 deletions(-)

diff --git a/frontend/components/bundle/PhraseCard.vue b/frontend/components/bundle/PhraseCard.vue
index dbfdf51..4e18f32 100644
--- a/frontend/components/bundle/PhraseCard.vue
+++ b/frontend/components/bundle/PhraseCard.vue
@@ -51,8 +51,8 @@
             </div>
 
             <div class="flex-1">
-                <TextArea type="text" :label="isLinguisticPhrase ? t('definition') : t('translation')"
-                    :placeholder="isLinguisticPhrase ? t('bundle.phrase_card.definition_placeholder') : t('bundle.phrase_card.translation_placeholder')"
+                <TextArea type="text" :label="t('translation')"
+                    :placeholder="t('bundle.phrase_card.translation_placeholder')"
                     v-model="translation" :error="!!error" :error-message="error || ''"
                     :loading="!!props.newPhrase && isSubmitting" :disabled="isLinguisticPhrase" />
             </div>
@@ -97,11 +97,10 @@ const isLinguisticPhrase = computed(() => {
     return props.phrase?.type === 'linguistic';
 });
 
-// Computed property for translation/definition value
+// Computed property for the translation value.
+// Show the same translation the user saw in the extension (translation.phrase),
+// not linguistic_data.definition (a whole-phrase explanation never shown on save).
 const translationValue = computed(() => {
-    if (isLinguisticPhrase.value) {
-        return props.phrase?.linguistic_data?.definition || '';
-    }
     return props.phrase?.translation || '';
 });
 
diff --git a/frontend/components/practice/LeitnerReviewSession.vue b/frontend/components/practice/LeitnerReviewSession.vue
index c74edfb..3e772ff 100644
--- a/frontend/components/practice/LeitnerReviewSession.vue
+++ b/frontend/components/practice/LeitnerReviewSession.vue
@@ -13,21 +13,25 @@
 		</div>
 
 		<div v-else class="flex h-full w-full flex-col items-center p-5 md:px-16 md:py-14">
+			<!-- Fixed height (viewport units) so the card never resizes when flipping between
+			     front/back; long content scrolls inside the card instead of growing the page. -->
 			<div
-				:class="['w-full flex-1 transition-all duration-300 ease-in-out', 'md:max-h-[80%] md:max-w-[80%]', 'lg:max-h-[65%] lg:max-w-[65%]']">
+				:class="['h-[58vh] w-full transition-all duration-300 ease-in-out', 'md:max-w-[80%]', 'lg:max-w-[65%]']">
 				<!-- Use WidgetFlashCard based on phrase type -->
 				<Transition name="fade-slide" mode="out-in">
 					<WidgetFlashCard v-if="currentPhrase && currentPhrase.type === 'normal'"
 						:key="`normal-${currentIndex}`" ref="flashCardRef" :phrase-type="'normal'"
 						:front="currentPhrase.phrase" :back="currentPhrase.translation" :context="currentPhrase.context"
-						:translation-language="currentPhrase.translation_language" />
+						:translation-language="currentPhrase.translation_language" :chunks="currentPhrase.chunks"
+						:leitner-level="cardLevel" :confirmed-chunk="cardChunk" :source-sentence="cardSentence" />
 
 					<WidgetFlashCard v-else-if="currentPhrase && currentPhrase.type === 'linguistic'"
 						:key="`linguistic-${currentIndex}`" ref="flashCardRef" :phrase-type="'linguistic'"
-						:front="currentPhrase.phrase"
-						:back="currentPhrase.linguistic_data?.definition || currentPhrase.phrase"
+						:front="currentPhrase.phrase" :back="currentPhrase.translation || currentPhrase.phrase"
 						:context="currentPhrase.context" :direction="currentPhrase.direction"
-						:language-info="currentPhrase.language_info" :linguistic-data="currentPhrase.linguistic_data" />
+						:language-info="currentPhrase.language_info" :linguistic-data="currentPhrase.linguistic_data"
+						:chunks="currentPhrase.chunks" :leitner-level="cardLevel" :confirmed-chunk="cardChunk"
+						:source-sentence="cardSentence" />
 
 					<WidgetFlashCard v-else-if="currentPhrase" :key="`fallback-${currentIndex}`" ref="flashCardRef"
 						:front="currentPhrase.phrase" :back="currentPhrase.translation || 'No translation'" />
@@ -93,6 +97,25 @@ const currentItem = computed(() => props.items[currentIndex.value]);
 const currentPhrase = computed(() => currentItem.value?.phrase as PhraseType);
 const totalItems = computed(() => props.items.length);
 
+// L3+ fill-in cloze inputs (level from the Leitner item, chunk + sentence from the phrase).
+// get-review-session returns raw Mongoose docs, so schema fields like boxLevel sit under `_doc`
+// rather than at the top level — read both so the level is found either way.
+const cardLevel = computed<number | undefined>(() => {
+	const item = currentItem.value as any;
+	return item?.boxLevel ?? item?._doc?.boxLevel;
+});
+const cardSentence = computed<string | null>(() => currentPhrase.value?.context ?? null);
+// Prefer the first confirmed chunk that actually appears in the source sentence. Chunk text and the
+// stored context can differ slightly (hyphenation, spacing), so blindly taking chunks[0] would drop to
+// recognition even when another chunk is a clean match. Falls back to chunks[0], then null.
+const cardChunk = computed<string | null>(() => {
+	const chunks = currentPhrase.value?.chunks || [];
+	if (!chunks.length) return null;
+	const sentence = (cardSentence.value || '').toLowerCase();
+	const matched = sentence ? chunks.find((c) => c.text && sentence.includes(c.text.toLowerCase())) : undefined;
+	return (matched || chunks[0])?.text ?? null;
+});
+
 onMounted(() => {
 	window.addEventListener('keydown', handleKeyDown);
 });
@@ -104,6 +127,12 @@ onUnmounted(() => {
 function handleKeyDown(event: KeyboardEvent) {
 	if (props.loading || props.items.length === 0) return;
 
+	// Don't hijack typing: while the cloze answer input (or any field) is focused, let keys through.
+	const target = event.target as HTMLElement | null;
+	if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable)) {
+		return;
+	}
+
 	switch (event.code) {
 		case 'Space':
 			event.preventDefault();
diff --git a/frontend/components/widget/FlashCard.vue b/frontend/components/widget/FlashCard.vue
index d397aad..e140ad4 100644
--- a/frontend/components/widget/FlashCard.vue
+++ b/frontend/components/widget/FlashCard.vue
@@ -1,9 +1,90 @@
 <template>
-    <div class="h-full w-full cursor-pointer select-none" @click="flipCard">
+    <div class="h-full w-full cursor-pointer select-none" @click="onCardClick">
         <Card :class="[!isFlipped ? 'bg-white' : 'bg-slate-100']"
             class="flex h-full items-center justify-center overflow-auto p-6">
+            <!-- ========== L3+ FILL-IN CLOZE PRESENTATION ========== -->
+            <template v-if="isClozeMode && clozeData">
+                <!-- Front: split into a flex-grow content area + a fixed-height action area, so changes to
+                     the buttons/status never reflow or move the sentence. -->
+                <div v-if="!isFlipped" class="flex h-full w-full flex-col">
+                    <!-- Content (grows, scrolls, vertically centered) -->
+                    <div class="flex min-h-0 flex-1 flex-col items-center justify-center overflow-auto px-2 text-center">
+                        <div class="mb-4 text-[11px] font-semibold uppercase tracking-widest text-gray-400">Fill in the
+                            blanks</div>
+                        <p class="w-full max-w-2xl text-lg font-medium leading-loose md:text-xl"
+                            :dir="props.direction?.source || 'ltr'">
+                            <template v-for="(seg, i) in clozeData.segments" :key="i">
+                                <span v-if="seg.type === 'text'">{{ seg.value }}</span>
+                                <input v-else v-model="clozeAnswers[seg.blankIndex]" type="text" @click.stop
+                                    @keyup.enter="checkCloze" :style="{ width: Math.max(seg.answer.length, 5) + 'ch' }"
+                                    class="mx-1 border-b-2 bg-transparent text-center align-bottom outline-none"
+                                    :class="clozeChecked && checkResults[seg.blankIndex] !== undefined
+                                        ? (checkResults[seg.blankIndex] ? 'border-green-500 text-green-600' : 'border-red-500 text-red-500')
+                                        : 'border-blue-500 text-gray-800'" />
+                            </template>
+                        </p>
+                    </div>
+
+                    <!-- Action (fixed height, never affects the content area above) -->
+                    <div class="flex h-24 shrink-0 flex-col items-center justify-center gap-2">
+                        <div class="flex items-center justify-center gap-3">
+                            <button @click.stop="checkCloze"
+                                class="rounded-lg bg-blue-600 px-6 py-2 text-sm font-medium text-white transition-opacity hover:opacity-90">
+                                {{ clozeChecked ? 'Recheck' : 'Check' }}
+                            </button>
+                            <button v-if="clozeChecked && !allBlanksCorrect" @click.stop="clearWrong"
+                                class="rounded-lg border border-gray-300 px-5 py-2 text-sm font-medium text-gray-600 transition-colors hover:bg-gray-50">
+                                Clear wrong
+                            </button>
+                        </div>
+                        <div class="h-5 overflow-hidden whitespace-nowrap text-sm font-medium"
+                            :class="allBlanksCorrect ? 'text-green-600' : 'text-gray-500'">
+                            <template v-if="clozeChecked">
+                                {{ allBlanksCorrect ? 'All correct!' : wrongCount + ' to fix — edit and check again' }}
+                            </template>
+                        </div>
+                    </div>
+                </div>
+
+                <!-- Back: full sentence revealed + per-chunk definitions + meaning (scrolls within the card) -->
+                <div v-else class="flex h-full w-full flex-col items-center overflow-auto py-6 text-center">
+                    <p class="mb-4 w-full max-w-2xl text-lg font-medium leading-loose md:text-xl"
+                        :dir="props.direction?.source || 'ltr'">
+                        <template v-for="(seg, i) in clozeData.segments" :key="i">
+                            <span v-if="seg.type === 'text'">{{ seg.value }}</span>
+                            <span v-else class="mx-1 font-bold text-blue-600">{{ seg.answer }}</span>
+                        </template>
+                    </p>
+
+                    <div v-if="clozeData.blanks.length" class="w-full max-w-2xl space-y-3">
+                        <div class="mb-1 text-center text-xs uppercase tracking-wide text-gray-400">Definition</div>
+                        <div v-for="(b, i) in clozeData.blanks" :key="i"
+                            class="rounded-lg border-l-4 border-blue-200 bg-gray-50 p-3 text-left">
+                            <div class="flex items-baseline justify-between gap-3">
+                                <span class="font-medium" :dir="props.direction?.source || 'ltr'">
+                                    {{ b.chunk.text }}
+                                </span>
+                                <span v-if="b.chunk.transliteration" class="shrink-0 text-xs text-gray-400"
+                                    :dir="props.direction?.target || 'ltr'">
+                                    {{ b.chunk.transliteration }}
+                                </span>
+                            </div>
+                            <div v-if="b.chunk.definition" class="mt-1 text-sm text-gray-600"
+                                :dir="props.direction?.target || 'ltr'">
+                                {{ b.chunk.definition }}
+                            </div>
+                        </div>
+                    </div>
+
+                    <div v-if="props.back" class="mt-4 text-base text-gray-600"
+                        :dir="props.direction?.target || 'ltr'">
+                        {{ props.back }}
+                    </div>
+                </div>
+            </template>
+
             <!-- ========== NORMAL TYPE PHRASE PRESENTATION ========== -->
-            <template v-if="phraseType === 'normal'">
+            <template v-else-if="phraseType === 'normal'">
                 <div class="flex h-full flex-col">
                     <!-- Top row: (empty left), lang code badge right -->
                     <div class="flex w-full items-start justify-between px-6 pt-4">
@@ -57,13 +138,10 @@
                                 <div class="mb-6 text-5xl font-medium" :dir="props.direction?.source || 'ltr'">
                                     {{ props.front || 'Front' }}
                                 </div>
-                                <!-- Phonetic Information in same row -->
-                                <div v-if="props.linguisticData?.phonetic"
-                                    class="flex items-center justify-center gap-6 text-gray-600">
-                                    <div v-if="props.linguisticData.phonetic.ipa" class="font-mono text-lg">/{{
-                                        props.linguisticData.phonetic.ipa }}/</div>
-                                    <div v-if="props.linguisticData.phonetic.transliteration"
-                                        class="text-lg font-medium" :dir="props.direction?.target || 'ltr'">
+                                <!-- Phonetic (transliteration only) -->
+                                <div v-if="props.linguisticData?.phonetic?.transliteration"
+                                    class="flex items-center justify-center text-gray-600">
+                                    <div class="text-lg font-medium" :dir="props.direction?.target || 'ltr'">
                                         {{ props.linguisticData.phonetic.transliteration }}
                                     </div>
                                 </div>
@@ -109,46 +187,39 @@
                                 </div>
                             </div>
 
-                            <!-- Main Content (centered) -->
-                            <div v-if="!showExamples" class="flex h-full w-full flex-col items-center justify-center">
-                                <div class="mb-3 text-center text-2xl font-medium"
-                                    :dir="props.direction?.target || 'ltr'">
-                                    {{ props.back || 'Translation' }}
-                                </div>
-                            </div>
+                            <!-- Main Content (translation + per-chunk definitions, mirrors the extension) -->
+                            <!-- Scroll-safe: the inner wrapper uses my-auto so it centers when it fits and -->
+                            <!-- scrolls from the top (no clipping) when chunks/definitions overflow. -->
+                            <div class="flex h-full w-full justify-center overflow-auto py-6">
+                                <div class="my-auto flex w-full flex-col items-center gap-6">
+                                    <!-- Translation -->
+                                    <div class="text-center text-2xl font-medium" :dir="props.direction?.target || 'ltr'">
+                                        {{ props.back || 'Translation' }}
+                                    </div>
 
-                            <!-- Examples Section (centered, only if toggled) -->
-                            <div v-if="showExamples && props.linguisticData?.examples?.length"
-                                class="flex h-full w-full flex-col items-center justify-center">
-                                <div class="w-full max-w-2xl rounded-lg bg-gray-50 p-4">
-                                    <div class="mb-3 text-center text-sm font-bold text-gray-700">Examples</div>
-                                    <div class="space-y-4">
-                                        <div v-for="(example, index) in props.linguisticData.examples" :key="index"
-                                            class="rounded-lg border-l-4 border-blue-200 bg-white p-3">
-                                            <div class="mb-2 text-sm font-medium"
-                                                :dir="props.direction?.target || 'ltr'">
-                                                {{ example.target }}
+                                        <!-- Definition: one block per confirmed chunk -->
+                                    <div v-if="props.chunks?.length" class="w-full max-w-2xl space-y-3">
+                                        <div class="mb-1 text-center text-xs uppercase tracking-wide text-gray-400">
+                                            Definition</div>
+                                        <div v-for="(chunk, index) in props.chunks" :key="index"
+                                            class="rounded-lg border-l-4 border-blue-200 bg-gray-50 p-3 text-left">
+                                            <div class="flex items-baseline justify-between gap-3">
+                                                <span class="font-medium" :dir="props.direction?.source || 'ltr'">
+                                                    {{ chunk.text }}
+                                                </span>
+                                                <span v-if="chunk.transliteration" class="shrink-0 text-xs text-gray-400"
+                                                    :dir="props.direction?.target || 'ltr'">
+                                                    {{ chunk.transliteration }}
+                                                </span>
                                             </div>
-                                            <div class="text-xs text-gray-500" :dir="props.direction?.source || 'ltr'">
-                                                {{ example.source }}
+                                            <div v-if="chunk.definition" class="mt-1 text-sm text-gray-600"
+                                                :dir="props.direction?.target || 'ltr'">
+                                                {{ chunk.definition }}
                                             </div>
                                         </div>
                                     </div>
                                 </div>
                             </div>
-
-                            <!-- Examples Toggle Button at bottom -->
-                            <div class="absolute bottom-8 left-0 right-0 flex justify-center">
-                                <button v-if="props.linguisticData?.examples?.length" @click.stop="toggleExamples"
-                                    class="rounded px-2 py-1 text-sm font-medium text-blue-600 underline transition-colors hover:text-blue-800 focus:outline-none">
-                                    {{
-                                        showExamples
-                                            ? 'Hide Examples'
-                                            : `Show Examples${props.linguisticData?.examples?.length ? `
-                                    (${props.linguisticData.examples.length})` : ''}`
-                                    }}
-                                </button>
-                            </div>
                         </div>
                     </template>
                 </div>
@@ -167,7 +238,7 @@
 
 <script setup lang="ts">
 import { Card } from 'pilotui/elements';
-import type { LinguisticData } from '~/types/database.type';
+import type { LinguisticData, Chunk } from '~/types/database.type';
 
 // Define the props interface for better type safety
 interface FlashCardProps {
@@ -190,10 +261,22 @@ interface FlashCardProps {
         target: string;
     };
     linguisticData?: LinguisticData;
+    /** Confirmed reusable patterns; rendered as per-chunk definitions on the linguistic back. */
+    chunks?: Chunk[];
+
+    // Leitner L3+ fill-in cloze
+    leitnerLevel?: number;
+    confirmedChunk?: string | null;
+    sourceSentence?: string | null;
 }
 
 const isFlipped = ref(false);
-const showExamples = ref(false);
+// Per-blank answers keyed by blank index, and whether the learner has pressed Check.
+const clozeAnswers = reactive<Record<number, string>>({});
+const clozeChecked = ref(false);
+// Snapshot of correctness from the last Check press (blankIndex -> correct?). Feedback only
+// updates on Check, so the learner can edit and re-check as many times as they want.
+const checkResults = reactive<Record<number, boolean>>({});
 
 const props = withDefaults(defineProps<FlashCardProps>(), {
     phraseType: 'normal',
@@ -201,24 +284,116 @@ const props = withDefaults(defineProps<FlashCardProps>(), {
     back: 'Back',
 });
 
+type ClozeSegment =
+    | { type: 'text'; value: string }
+    | { type: 'blank'; blankIndex: number; answer: string; chunk: Chunk };
+
+// Build a multi-blank cloze: blank every confirmed chunk that appears in the source sentence.
+// Returns the rendered segments (text + blanks) and the ordered list of blanks (for the answer key
+// and the back-side definition list). Returns null when there's no sentence or no chunk lands in it
+// (in which case the card falls back to the recognition presentation).
+const clozeData = computed(() => {
+    const sentence = props.sourceSentence || props.context || '';
+    const chunks = props.chunks || [];
+    if (!sentence || !chunks.length) return null;
+
+    const lower = sentence.toLowerCase();
+
+    // First occurrence of each chunk inside the sentence.
+    const hits = chunks
+        .map((chunk) => {
+            const text = (chunk.text || '').trim();
+            if (!text) return null;
+            const start = lower.indexOf(text.toLowerCase());
+            if (start === -1) return null;
+            return { start, end: start + text.length, chunk, answer: sentence.slice(start, start + text.length) };
+        })
+        .filter((h): h is NonNullable<typeof h> => h !== null)
+        .sort((a, b) => a.start - b.start);
+
+    if (!hits.length) return null;
+
+    // Drop overlapping chunks (keep the earliest), so blanks never collide.
+    const placed: typeof hits = [];
+    let lastEnd = -1;
+    for (const hit of hits) {
+        if (hit.start >= lastEnd) {
+            placed.push(hit);
+            lastEnd = hit.end;
+        }
+    }
+
+    const segments: ClozeSegment[] = [];
+    let cursor = 0;
+    placed.forEach((hit, blankIndex) => {
+        if (hit.start > cursor) segments.push({ type: 'text', value: sentence.slice(cursor, hit.start) });
+        segments.push({ type: 'blank', blankIndex, answer: hit.answer, chunk: hit.chunk });
+        cursor = hit.end;
+    });
+    if (cursor < sentence.length) segments.push({ type: 'text', value: sentence.slice(cursor) });
+
+    const blanks = placed.map((hit, blankIndex) => ({ blankIndex, answer: hit.answer, chunk: hit.chunk }));
+    return { segments, blanks };
+});
+
+const isClozeMode = computed(() => (props.leitnerLevel ?? 0) >= 3 && !!clozeData.value);
+
+function isBlankCorrect(blankIndex: number, answer: string) {
+    return (clozeAnswers[blankIndex] || '').trim().toLowerCase() === answer.trim().toLowerCase();
+}
+
+// Snapshot correctness for every blank; can be pressed repeatedly.
+function checkCloze() {
+    if (!clozeData.value) return;
+    clozeData.value.blanks.forEach((b) => {
+        checkResults[b.blankIndex] = isBlankCorrect(b.blankIndex, b.answer);
+    });
+    clozeChecked.value = true;
+}
+
+// Empty just the blanks that were wrong on the last check and return to the neutral (unchecked)
+// state, so the learner can retype and check again. Correct answers keep their text.
+function clearWrong() {
+    if (!clozeData.value) return;
+    clozeData.value.blanks.forEach((b) => {
+        if (checkResults[b.blankIndex] === false) delete clozeAnswers[b.blankIndex];
+    });
+    Object.keys(checkResults).forEach((k) => delete checkResults[Number(k)]);
+    clozeChecked.value = false;
+}
+
+const allBlanksCorrect = computed(() => {
+    if (!clozeData.value || !clozeChecked.value) return false;
+    return clozeData.value.blanks.every((b) => checkResults[b.blankIndex] === true);
+});
+
+const wrongCount = computed(() => {
+    if (!clozeData.value) return 0;
+    return clozeData.value.blanks.filter((b) => checkResults[b.blankIndex] === false).length;
+});
+
 function flipCard() {
     isFlipped.value = !isFlipped.value;
 }
 
-function toggleExamples() {
-    showExamples.value = !showExamples.value;
+function onCardClick() {
+    // In cloze mode the front is an exercise — don't flip on a stray tap until the learner has checked.
+    if (isClozeMode.value && !isFlipped.value && !clozeChecked.value) return;
+    flipCard();
 }
 
 defineExpose({
     flipCard,
 });
 
-// Reset flip state when phrase changes
+// Reset state when the card changes.
 watch(
-    () => props.front,
+    () => [props.front, props.sourceSentence],
     () => {
         isFlipped.value = false;
-        showExamples.value = false;
+        clozeChecked.value = false;
+        Object.keys(clozeAnswers).forEach((k) => delete clozeAnswers[Number(k)]);
+        Object.keys(checkResults).forEach((k) => delete checkResults[Number(k)]);
     }
 );
 </script>
diff --git a/frontend/pages/practice/flashcards-[id].vue b/frontend/pages/practice/flashcards-[id].vue
index 44c3666..505514c 100644
--- a/frontend/pages/practice/flashcards-[id].vue
+++ b/frontend/pages/practice/flashcards-[id].vue
@@ -6,14 +6,16 @@
                 <!-- ========== NORMAL TYPE FLASHCARD ========== -->
                 <WidgetFlashCard v-if="phrase && isNormalType" :key="`normal-${phraseIndex}`" :phrase-type="'normal'"
                     :front="phrase.phrase" :back="phrase.translation" :context="phrase.context"
-                    :translation-language="phrase.translation_language" />
+                    :translation-language="phrase.translation_language" :leitner-level="cardLevel"
+                    :confirmed-chunk="cardChunk" :source-sentence="cardSentence" />
 
                 <!-- ========== LINGUISTIC TYPE FLASHCARD ========== -->
                 <WidgetFlashCard v-else-if="phrase && isLinguisticType" :key="`linguistic-${phraseIndex}`"
                     :phrase-type="'linguistic'" :front="phrase.phrase"
-                    :back="phrase.linguistic_data?.definition || phrase.phrase" :context="phrase.context"
+                    :back="phrase.translation || phrase.phrase" :context="phrase.context"
                     :direction="phrase.direction" :language-info="phrase.language_info"
-                    :linguistic-data="phrase.linguistic_data" />
+                    :linguistic-data="phrase.linguistic_data" :chunks="phrase.chunks" :leitner-level="cardLevel"
+                    :confirmed-chunk="cardChunk" :source-sentence="cardSentence" />
 
                 <!-- ========== FALLBACK FOR UNKNOWN TYPE ========== -->
                 <WidgetFlashCard v-else-if="phrase" :key="`fallback-${phraseIndex}`" :front="phrase.phrase"
@@ -94,6 +96,11 @@ const isNextAvailable = computed(() => {
     return phraseIndex.value < totalPhrases.value - 1;
 });
 
+// L3+ fill-in cloze data, carried on the enriched phrase in Leitner mode (undefined otherwise → recognition card).
+const cardLevel = computed<number | undefined>(() => (phrase.value as any)?._leitnerLevel);
+const cardChunk = computed<string | null>(() => (phrase.value as any)?._confirmedChunk ?? null);
+const cardSentence = computed<string | null>(() => (phrase.value as any)?._sourceSentence ?? null);
+
 // ========== PHRASE TYPE DETECTION LOGIC ==========
 /**
  * Determines if the current phrase is of "normal" type
@@ -136,8 +143,14 @@ function fetchFlashcard() {
                 bundle.value = { title: 'Daily Review', phrases: [], refId: authUser.value?.id } as any;
                 return;
             }
-            // Map items to phrases
-            const phrases = res.items.map((i: any) => i.phrase);
+            // Map items to phrases, carrying through the Leitner level + confirmed chunk
+            // so the L3+ fill-in cloze can render (falls back to phrase fields until the RPC exposes them).
+            const phrases = res.items.map((i: any) => ({
+                ...i.phrase,
+                _leitnerLevel: i.boxLevel,
+                _confirmedChunk: i.confirmed_chunk ?? i.phrase?.chunks?.[0]?.text ?? null,
+                _sourceSentence: i.source_sentence ?? i.phrase?.context ?? null,
+            }));
             bundle.value = {
                 _id: res._id,
                 title: 'Daily Review',
diff --git a/frontend/types/database.type.ts b/frontend/types/database.type.ts
index 2045076..33443ef 100644
--- a/frontend/types/database.type.ts
+++ b/frontend/types/database.type.ts
@@ -1,5 +1,5 @@
 import { type FileDocument } from '@modular-rest/client/dist/types/types';
-import { type PhraseSchema, type LinguisticData } from '../../server/src/modules/phrase_bundle/db';
+import { type PhraseSchema, type LinguisticData, type Chunk } from '../../server/src/modules/phrase_bundle/db';
 
 export const DATABASE = {
     USER_CONTENT: 'user_content',
@@ -16,8 +16,8 @@ export const COLLECTIONS = {
     BOARD_ACTIVITY: 'board_activity',
 };
 
-// Re-export LinguisticData type for frontend use
-export type { LinguisticData };
+// Re-export LinguisticData + Chunk types for frontend use
+export type { LinguisticData, Chunk };
 
 export interface ProfileType {
     _id: string;

From 4249a0cd81df37c63bf4a16f5e352e0c1ba8af4c Mon Sep 17 00:00:00 2001
From: Navid Shad <navidshad72@gmail.com>
Date: Sun, 24 May 2026 21:02:22 +0300
Subject: [PATCH 2/5] feat(flashcard): modularize card modes + unified flip
 toggle

Refactor the monolithic flashcard into composables + per-mode pieces and
give every card type one consistent flip control.

- Extract useCardFlip (flip state + reset) and useClozeBlanks (pure
  buildClozeData + reactive cloze state: answers, snapshot check results,
  check/clear) into composables.
- Move the L3+ cloze UI into widget/flashcard/ClozeCard.vue; FlashCard now
  just resolves the mode and renders the right piece.
- Add widget/flashcard/FlashcardFlipToggle.vue: a single Question/Answer
  toggle shown on every card type that indicates the current side and is
  the one consistent way to flip (plus Space). Drops the inconsistent
  body-click-to-flip (recognition flipped on any tap, cloze front didn't).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 frontend/components/widget/FlashCard.vue      | 229 ++----------------
 .../components/widget/flashcard/ClozeCard.vue |  97 ++++++++
 .../widget/flashcard/FlashcardFlipToggle.vue  |  33 +++
 frontend/composables/useCardFlip.ts           |  19 ++
 frontend/composables/useClozeBlanks.ts        | 127 ++++++++++
 5 files changed, 302 insertions(+), 203 deletions(-)
 create mode 100644 frontend/components/widget/flashcard/ClozeCard.vue
 create mode 100644 frontend/components/widget/flashcard/FlashcardFlipToggle.vue
 create mode 100644 frontend/composables/useCardFlip.ts
 create mode 100644 frontend/composables/useClozeBlanks.ts

diff --git a/frontend/components/widget/FlashCard.vue b/frontend/components/widget/FlashCard.vue
index e140ad4..2b4c8dd 100644
--- a/frontend/components/widget/FlashCard.vue
+++ b/frontend/components/widget/FlashCard.vue
@@ -1,89 +1,16 @@
 <template>
-    <div class="h-full w-full cursor-pointer select-none" @click="onCardClick">
+    <div class="h-full w-full select-none">
         <Card :class="[!isFlipped ? 'bg-white' : 'bg-slate-100']"
-            class="flex h-full items-center justify-center overflow-auto p-6">
-            <!-- ========== L3+ FILL-IN CLOZE PRESENTATION ========== -->
-            <template v-if="isClozeMode && clozeData">
-                <!-- Front: split into a flex-grow content area + a fixed-height action area, so changes to
-                     the buttons/status never reflow or move the sentence. -->
-                <div v-if="!isFlipped" class="flex h-full w-full flex-col">
-                    <!-- Content (grows, scrolls, vertically centered) -->
-                    <div class="flex min-h-0 flex-1 flex-col items-center justify-center overflow-auto px-2 text-center">
-                        <div class="mb-4 text-[11px] font-semibold uppercase tracking-widest text-gray-400">Fill in the
-                            blanks</div>
-                        <p class="w-full max-w-2xl text-lg font-medium leading-loose md:text-xl"
-                            :dir="props.direction?.source || 'ltr'">
-                            <template v-for="(seg, i) in clozeData.segments" :key="i">
-                                <span v-if="seg.type === 'text'">{{ seg.value }}</span>
-                                <input v-else v-model="clozeAnswers[seg.blankIndex]" type="text" @click.stop
-                                    @keyup.enter="checkCloze" :style="{ width: Math.max(seg.answer.length, 5) + 'ch' }"
-                                    class="mx-1 border-b-2 bg-transparent text-center align-bottom outline-none"
-                                    :class="clozeChecked && checkResults[seg.blankIndex] !== undefined
-                                        ? (checkResults[seg.blankIndex] ? 'border-green-500 text-green-600' : 'border-red-500 text-red-500')
-                                        : 'border-blue-500 text-gray-800'" />
-                            </template>
-                        </p>
-                    </div>
-
-                    <!-- Action (fixed height, never affects the content area above) -->
-                    <div class="flex h-24 shrink-0 flex-col items-center justify-center gap-2">
-                        <div class="flex items-center justify-center gap-3">
-                            <button @click.stop="checkCloze"
-                                class="rounded-lg bg-blue-600 px-6 py-2 text-sm font-medium text-white transition-opacity hover:opacity-90">
-                                {{ clozeChecked ? 'Recheck' : 'Check' }}
-                            </button>
-                            <button v-if="clozeChecked && !allBlanksCorrect" @click.stop="clearWrong"
-                                class="rounded-lg border border-gray-300 px-5 py-2 text-sm font-medium text-gray-600 transition-colors hover:bg-gray-50">
-                                Clear wrong
-                            </button>
-                        </div>
-                        <div class="h-5 overflow-hidden whitespace-nowrap text-sm font-medium"
-                            :class="allBlanksCorrect ? 'text-green-600' : 'text-gray-500'">
-                            <template v-if="clozeChecked">
-                                {{ allBlanksCorrect ? 'All correct!' : wrongCount + ' to fix — edit and check again' }}
-                            </template>
-                        </div>
-                    </div>
-                </div>
+            class="relative flex h-full flex-col overflow-hidden">
+            <!-- One consistent flip control for every card type -->
+            <FlashcardFlipToggle :is-flipped="isFlipped" @flip="flipCard" />
 
-                <!-- Back: full sentence revealed + per-chunk definitions + meaning (scrolls within the card) -->
-                <div v-else class="flex h-full w-full flex-col items-center overflow-auto py-6 text-center">
-                    <p class="mb-4 w-full max-w-2xl text-lg font-medium leading-loose md:text-xl"
-                        :dir="props.direction?.source || 'ltr'">
-                        <template v-for="(seg, i) in clozeData.segments" :key="i">
-                            <span v-if="seg.type === 'text'">{{ seg.value }}</span>
-                            <span v-else class="mx-1 font-bold text-blue-600">{{ seg.answer }}</span>
-                        </template>
-                    </p>
-
-                    <div v-if="clozeData.blanks.length" class="w-full max-w-2xl space-y-3">
-                        <div class="mb-1 text-center text-xs uppercase tracking-wide text-gray-400">Definition</div>
-                        <div v-for="(b, i) in clozeData.blanks" :key="i"
-                            class="rounded-lg border-l-4 border-blue-200 bg-gray-50 p-3 text-left">
-                            <div class="flex items-baseline justify-between gap-3">
-                                <span class="font-medium" :dir="props.direction?.source || 'ltr'">
-                                    {{ b.chunk.text }}
-                                </span>
-                                <span v-if="b.chunk.transliteration" class="shrink-0 text-xs text-gray-400"
-                                    :dir="props.direction?.target || 'ltr'">
-                                    {{ b.chunk.transliteration }}
-                                </span>
-                            </div>
-                            <div v-if="b.chunk.definition" class="mt-1 text-sm text-gray-600"
-                                :dir="props.direction?.target || 'ltr'">
-                                {{ b.chunk.definition }}
-                            </div>
-                        </div>
-                    </div>
+            <div class="flex min-h-0 flex-1 items-center justify-center overflow-auto p-6">
+                <!-- ========== L3+ FILL-IN CLOZE PRESENTATION ========== -->
+                <ClozeCard v-if="isClozeMode" :source-sentence="props.sourceSentence" :context="props.context"
+                    :chunks="props.chunks" :direction="props.direction" :back="props.back" :is-flipped="isFlipped" />
 
-                    <div v-if="props.back" class="mt-4 text-base text-gray-600"
-                        :dir="props.direction?.target || 'ltr'">
-                        {{ props.back }}
-                    </div>
-                </div>
-            </template>
-
-            <!-- ========== NORMAL TYPE PHRASE PRESENTATION ========== -->
+                <!-- ========== NORMAL TYPE PHRASE PRESENTATION ========== -->
             <template v-else-if="phraseType === 'normal'">
                 <div class="flex h-full flex-col">
                     <!-- Top row: (empty left), lang code badge right -->
@@ -226,19 +153,25 @@
             </template>
 
             <!-- ========== FALLBACK FOR UNKNOWN TYPE ========== -->
-            <template v-else>
-                <div class="text-center text-xl text-gray-500">
-                    <span v-if="!isFlipped">{{ props.front || 'Front' }}</span>
-                    <span v-else>{{ props.back || 'Back' }}</span>
-                </div>
-            </template>
+                <template v-else>
+                    <div class="text-center text-xl text-gray-500">
+                        <span v-if="!isFlipped">{{ props.front || 'Front' }}</span>
+                        <span v-else>{{ props.back || 'Back' }}</span>
+                    </div>
+                </template>
+            </div>
         </Card>
     </div>
 </template>
 
 <script setup lang="ts">
+import { computed } from 'vue';
 import { Card } from 'pilotui/elements';
 import type { LinguisticData, Chunk } from '~/types/database.type';
+import { useCardFlip } from '~/composables/useCardFlip';
+import { buildClozeData } from '~/composables/useClozeBlanks';
+import ClozeCard from './flashcard/ClozeCard.vue';
+import FlashcardFlipToggle from './flashcard/FlashcardFlipToggle.vue';
 
 // Define the props interface for better type safety
 interface FlashCardProps {
@@ -270,130 +203,20 @@ interface FlashCardProps {
     sourceSentence?: string | null;
 }
 
-const isFlipped = ref(false);
-// Per-blank answers keyed by blank index, and whether the learner has pressed Check.
-const clozeAnswers = reactive<Record<number, string>>({});
-const clozeChecked = ref(false);
-// Snapshot of correctness from the last Check press (blankIndex -> correct?). Feedback only
-// updates on Check, so the learner can edit and re-check as many times as they want.
-const checkResults = reactive<Record<number, boolean>>({});
-
 const props = withDefaults(defineProps<FlashCardProps>(), {
     phraseType: 'normal',
     front: 'Front',
     back: 'Back',
 });
 
-type ClozeSegment =
-    | { type: 'text'; value: string }
-    | { type: 'blank'; blankIndex: number; answer: string; chunk: Chunk };
-
-// Build a multi-blank cloze: blank every confirmed chunk that appears in the source sentence.
-// Returns the rendered segments (text + blanks) and the ordered list of blanks (for the answer key
-// and the back-side definition list). Returns null when there's no sentence or no chunk lands in it
-// (in which case the card falls back to the recognition presentation).
-const clozeData = computed(() => {
-    const sentence = props.sourceSentence || props.context || '';
-    const chunks = props.chunks || [];
-    if (!sentence || !chunks.length) return null;
-
-    const lower = sentence.toLowerCase();
-
-    // First occurrence of each chunk inside the sentence.
-    const hits = chunks
-        .map((chunk) => {
-            const text = (chunk.text || '').trim();
-            if (!text) return null;
-            const start = lower.indexOf(text.toLowerCase());
-            if (start === -1) return null;
-            return { start, end: start + text.length, chunk, answer: sentence.slice(start, start + text.length) };
-        })
-        .filter((h): h is NonNullable<typeof h> => h !== null)
-        .sort((a, b) => a.start - b.start);
-
-    if (!hits.length) return null;
-
-    // Drop overlapping chunks (keep the earliest), so blanks never collide.
-    const placed: typeof hits = [];
-    let lastEnd = -1;
-    for (const hit of hits) {
-        if (hit.start >= lastEnd) {
-            placed.push(hit);
-            lastEnd = hit.end;
-        }
-    }
-
-    const segments: ClozeSegment[] = [];
-    let cursor = 0;
-    placed.forEach((hit, blankIndex) => {
-        if (hit.start > cursor) segments.push({ type: 'text', value: sentence.slice(cursor, hit.start) });
-        segments.push({ type: 'blank', blankIndex, answer: hit.answer, chunk: hit.chunk });
-        cursor = hit.end;
-    });
-    if (cursor < sentence.length) segments.push({ type: 'text', value: sentence.slice(cursor) });
-
-    const blanks = placed.map((hit, blankIndex) => ({ blankIndex, answer: hit.answer, chunk: hit.chunk }));
-    return { segments, blanks };
-});
-
-const isClozeMode = computed(() => (props.leitnerLevel ?? 0) >= 3 && !!clozeData.value);
+// Flip state (resets to the front whenever the card changes).
+const { isFlipped, flipCard } = useCardFlip(() => [props.front, props.sourceSentence]);
 
-function isBlankCorrect(blankIndex: number, answer: string) {
-    return (clozeAnswers[blankIndex] || '').trim().toLowerCase() === answer.trim().toLowerCase();
-}
-
-// Snapshot correctness for every blank; can be pressed repeatedly.
-function checkCloze() {
-    if (!clozeData.value) return;
-    clozeData.value.blanks.forEach((b) => {
-        checkResults[b.blankIndex] = isBlankCorrect(b.blankIndex, b.answer);
-    });
-    clozeChecked.value = true;
-}
-
-// Empty just the blanks that were wrong on the last check and return to the neutral (unchecked)
-// state, so the learner can retype and check again. Correct answers keep their text.
-function clearWrong() {
-    if (!clozeData.value) return;
-    clozeData.value.blanks.forEach((b) => {
-        if (checkResults[b.blankIndex] === false) delete clozeAnswers[b.blankIndex];
-    });
-    Object.keys(checkResults).forEach((k) => delete checkResults[Number(k)]);
-    clozeChecked.value = false;
-}
-
-const allBlanksCorrect = computed(() => {
-    if (!clozeData.value || !clozeChecked.value) return false;
-    return clozeData.value.blanks.every((b) => checkResults[b.blankIndex] === true);
-});
-
-const wrongCount = computed(() => {
-    if (!clozeData.value) return 0;
-    return clozeData.value.blanks.filter((b) => checkResults[b.blankIndex] === false).length;
-});
-
-function flipCard() {
-    isFlipped.value = !isFlipped.value;
-}
-
-function onCardClick() {
-    // In cloze mode the front is an exercise — don't flip on a stray tap until the learner has checked.
-    if (isClozeMode.value && !isFlipped.value && !clozeChecked.value) return;
-    flipCard();
-}
+// L3+ fill-in card when the level is 3+ and at least one confirmed chunk lands in the sentence;
+// otherwise fall back to the recognition card. The cloze exercise state lives inside ClozeCard.
+const isClozeMode = computed(() => (props.leitnerLevel ?? 0) >= 3 && !!buildClozeData(props.sourceSentence || props.context, props.chunks));
 
 defineExpose({
     flipCard,
 });
-
-// Reset state when the card changes.
-watch(
-    () => [props.front, props.sourceSentence],
-    () => {
-        isFlipped.value = false;
-        clozeChecked.value = false;
-        Object.keys(clozeAnswers).forEach((k) => delete clozeAnswers[Number(k)]);
-        Object.keys(checkResults).forEach((k) => delete checkResults[Number(k)]);
-    }
-);
 </script>
diff --git a/frontend/components/widget/flashcard/ClozeCard.vue b/frontend/components/widget/flashcard/ClozeCard.vue
new file mode 100644
index 0000000..2f6a358
--- /dev/null
+++ b/frontend/components/widget/flashcard/ClozeCard.vue
@@ -0,0 +1,97 @@
+<template>
+    <!-- Front: flex-grow content area + fixed-height action area, so the buttons/status never
+         reflow the sentence. -->
+    <div v-if="!isFlipped" class="flex h-full w-full flex-col">
+        <!-- Content (grows, scrolls, vertically centered) -->
+        <div class="flex min-h-0 flex-1 flex-col items-center justify-center overflow-auto px-2 text-center">
+            <div class="mb-4 text-[11px] font-semibold uppercase tracking-widest text-gray-400">Fill in the blanks</div>
+            <p v-if="clozeData" class="w-full max-w-2xl text-lg font-medium leading-loose md:text-xl"
+                :dir="direction?.source || 'ltr'">
+                <template v-for="(seg, i) in clozeData.segments" :key="i">
+                    <span v-if="seg.type === 'text'">{{ seg.value }}</span>
+                    <input v-else v-model="clozeAnswers[seg.blankIndex]" type="text" @click.stop
+                        @keyup.enter="checkCloze" :style="{ width: Math.max(seg.answer.length, 5) + 'ch' }"
+                        class="mx-1 border-b-2 bg-transparent text-center align-bottom outline-none"
+                        :class="clozeChecked && checkResults[seg.blankIndex] !== undefined
+                            ? (checkResults[seg.blankIndex] ? 'border-green-500 text-green-600' : 'border-red-500 text-red-500')
+                            : 'border-blue-500 text-gray-800'" />
+                </template>
+            </p>
+        </div>
+
+        <!-- Action (fixed height) -->
+        <div class="flex h-24 shrink-0 flex-col items-center justify-center gap-2">
+            <div class="flex items-center justify-center gap-3">
+                <button @click.stop="checkCloze"
+                    class="rounded-lg bg-blue-600 px-6 py-2 text-sm font-medium text-white transition-opacity hover:opacity-90">
+                    {{ clozeChecked ? 'Recheck' : 'Check' }}
+                </button>
+                <button v-if="clozeChecked && !allBlanksCorrect" @click.stop="clearWrong"
+                    class="rounded-lg border border-gray-300 px-5 py-2 text-sm font-medium text-gray-600 transition-colors hover:bg-gray-50">
+                    Clear wrong
+                </button>
+            </div>
+            <div class="h-5 overflow-hidden whitespace-nowrap text-sm font-medium"
+                :class="allBlanksCorrect ? 'text-green-600' : 'text-gray-500'">
+                <template v-if="clozeChecked">
+                    {{ allBlanksCorrect ? 'All correct!' : wrongCount + ' to fix — edit and check again' }}
+                </template>
+            </div>
+        </div>
+    </div>
+
+    <!-- Back: full sentence revealed + per-chunk definitions + meaning (scrolls within the card) -->
+    <div v-else class="flex h-full w-full flex-col items-center overflow-auto text-center">
+        <p v-if="clozeData" class="mb-4 w-full max-w-2xl text-lg font-medium leading-loose md:text-xl"
+            :dir="direction?.source || 'ltr'">
+            <template v-for="(seg, i) in clozeData.segments" :key="i">
+                <span v-if="seg.type === 'text'">{{ seg.value }}</span>
+                <span v-else class="mx-1 font-bold text-blue-600">{{ seg.answer }}</span>
+            </template>
+        </p>
+
+        <div v-if="clozeData?.blanks.length" class="w-full max-w-2xl space-y-3">
+            <div class="mb-1 text-center text-xs uppercase tracking-wide text-gray-400">Definition</div>
+            <div v-for="(b, i) in clozeData.blanks" :key="i"
+                class="rounded-lg border-l-4 border-blue-200 bg-gray-50 p-3 text-left">
+                <div class="flex items-baseline justify-between gap-3">
+                    <span class="font-medium" :dir="direction?.source || 'ltr'">{{ b.chunk.text }}</span>
+                    <span v-if="b.chunk.transliteration" class="shrink-0 text-xs text-gray-400"
+                        :dir="direction?.target || 'ltr'">
+                        {{ b.chunk.transliteration }}
+                    </span>
+                </div>
+                <div v-if="b.chunk.definition" class="mt-1 text-sm text-gray-600" :dir="direction?.target || 'ltr'">
+                    {{ b.chunk.definition }}
+                </div>
+            </div>
+        </div>
+
+        <div v-if="back" class="mt-4 text-base text-gray-600" :dir="direction?.target || 'ltr'">{{ back }}</div>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { toRef } from 'vue';
+import type { Chunk } from '~/types/database.type';
+import { useClozeBlanks } from '~/composables/useClozeBlanks';
+
+const props = defineProps<{
+    sourceSentence?: string | null;
+    context?: string;
+    chunks?: Chunk[];
+    direction?: { source: 'ltr' | 'rtl'; target: 'ltr' | 'rtl' };
+    back?: string;
+    isFlipped?: boolean;
+}>();
+
+const direction = toRef(props, 'direction');
+const back = toRef(props, 'back');
+const isFlipped = toRef(props, 'isFlipped');
+
+const { clozeData, clozeAnswers, clozeChecked, checkResults, checkCloze, clearWrong, allBlanksCorrect, wrongCount } =
+    useClozeBlanks(
+        () => props.sourceSentence || props.context || '',
+        () => props.chunks || []
+    );
+</script>
diff --git a/frontend/components/widget/flashcard/FlashcardFlipToggle.vue b/frontend/components/widget/flashcard/FlashcardFlipToggle.vue
new file mode 100644
index 0000000..8d8a08d
--- /dev/null
+++ b/frontend/components/widget/flashcard/FlashcardFlipToggle.vue
@@ -0,0 +1,33 @@
+<template>
+    <!-- Single, consistent flip control shared by every flashcard mode: shows which side is active
+         and lets the learner switch to the other one. -->
+    <div class="flex shrink-0 items-center justify-center gap-1 pt-2">
+        <button type="button" @click.stop="isFlipped && emit('flip')"
+            class="rounded-full px-3 py-1 text-[11px] font-semibold uppercase tracking-wide transition-colors"
+            :class="!isFlipped ? 'bg-blue-100 text-blue-700' : 'text-gray-400 hover:text-gray-600'">
+            {{ frontLabel }}
+        </button>
+        <span class="text-gray-300">·</span>
+        <button type="button" @click.stop="!isFlipped && emit('flip')"
+            class="rounded-full px-3 py-1 text-[11px] font-semibold uppercase tracking-wide transition-colors"
+            :class="isFlipped ? 'bg-blue-100 text-blue-700' : 'text-gray-400 hover:text-gray-600'">
+            {{ backLabel }}
+        </button>
+    </div>
+</template>
+
+<script setup lang="ts">
+withDefaults(
+    defineProps<{
+        isFlipped?: boolean;
+        frontLabel?: string;
+        backLabel?: string;
+    }>(),
+    {
+        frontLabel: 'Question',
+        backLabel: 'Answer',
+    }
+);
+
+const emit = defineEmits<{ (e: 'flip'): void }>();
+</script>
diff --git a/frontend/composables/useCardFlip.ts b/frontend/composables/useCardFlip.ts
new file mode 100644
index 0000000..585d43a
--- /dev/null
+++ b/frontend/composables/useCardFlip.ts
@@ -0,0 +1,19 @@
+import { ref, watch } from 'vue';
+
+/**
+ * Flip state for a flashcard. `resetKey` is a getter that changes when the card changes
+ * (e.g. the front text) — when it changes, the card flips back to the front automatically.
+ */
+export function useCardFlip(resetKey: () => unknown) {
+    const isFlipped = ref(false);
+
+    function flipCard() {
+        isFlipped.value = !isFlipped.value;
+    }
+
+    watch(resetKey, () => {
+        isFlipped.value = false;
+    });
+
+    return { isFlipped, flipCard };
+}
diff --git a/frontend/composables/useClozeBlanks.ts b/frontend/composables/useClozeBlanks.ts
new file mode 100644
index 0000000..444fc4c
--- /dev/null
+++ b/frontend/composables/useClozeBlanks.ts
@@ -0,0 +1,127 @@
+import { computed, reactive, ref, watch } from 'vue';
+import type { Chunk } from '~/types/database.type';
+
+export type ClozeSegment =
+    | { type: 'text'; value: string }
+    | { type: 'blank'; blankIndex: number; answer: string; chunk: Chunk };
+
+export interface ClozeData {
+    segments: ClozeSegment[];
+    blanks: { blankIndex: number; answer: string; chunk: Chunk }[];
+}
+
+/**
+ * Pure builder for a multi-blank cloze: blanks every confirmed chunk that appears in the source
+ * sentence (non-overlapping, in order). Returns null when there's no sentence or no chunk lands in
+ * it — callers treat null as "fall back to the recognition card".
+ */
+export function buildClozeData(sentence: string | null | undefined, chunks: Chunk[] | null | undefined): ClozeData | null {
+    const text = sentence || '';
+    const list = chunks || [];
+    if (!text || !list.length) return null;
+
+    const lower = text.toLowerCase();
+
+    // First occurrence of each chunk inside the sentence.
+    const hits = list
+        .map((chunk) => {
+            const t = (chunk.text || '').trim();
+            if (!t) return null;
+            const start = lower.indexOf(t.toLowerCase());
+            if (start === -1) return null;
+            return { start, end: start + t.length, chunk, answer: text.slice(start, start + t.length) };
+        })
+        .filter((h): h is NonNullable<typeof h> => h !== null)
+        .sort((a, b) => a.start - b.start);
+
+    if (!hits.length) return null;
+
+    // Drop overlapping chunks (keep the earliest) so blanks never collide.
+    const placed: typeof hits = [];
+    let lastEnd = -1;
+    for (const hit of hits) {
+        if (hit.start >= lastEnd) {
+            placed.push(hit);
+            lastEnd = hit.end;
+        }
+    }
+
+    const segments: ClozeSegment[] = [];
+    let cursor = 0;
+    placed.forEach((hit, blankIndex) => {
+        if (hit.start > cursor) segments.push({ type: 'text', value: text.slice(cursor, hit.start) });
+        segments.push({ type: 'blank', blankIndex, answer: hit.answer, chunk: hit.chunk });
+        cursor = hit.end;
+    });
+    if (cursor < text.length) segments.push({ type: 'text', value: text.slice(cursor) });
+
+    const blanks = placed.map((hit, blankIndex) => ({ blankIndex, answer: hit.answer, chunk: hit.chunk }));
+    return { segments, blanks };
+}
+
+/**
+ * Reactive state for the fill-in-the-blank cloze exercise: the per-blank answers, the snapshot of
+ * correctness from the last Check press, and the check/clear actions. Feedback only updates on
+ * Check, so the learner can edit and re-check as many times as they like. State resets whenever the
+ * source sentence changes (i.e. a new card).
+ */
+export function useClozeBlanks(getSentence: () => string | null | undefined, getChunks: () => Chunk[] | null | undefined) {
+    const clozeAnswers = reactive<Record<number, string>>({});
+    const clozeChecked = ref(false);
+    const checkResults = reactive<Record<number, boolean>>({});
+
+    const clozeData = computed(() => buildClozeData(getSentence(), getChunks()));
+
+    function isBlankCorrect(blankIndex: number, answer: string) {
+        return (clozeAnswers[blankIndex] || '').trim().toLowerCase() === answer.trim().toLowerCase();
+    }
+
+    // Snapshot correctness for every blank; can be pressed repeatedly.
+    function checkCloze() {
+        if (!clozeData.value) return;
+        clozeData.value.blanks.forEach((b) => {
+            checkResults[b.blankIndex] = isBlankCorrect(b.blankIndex, b.answer);
+        });
+        clozeChecked.value = true;
+    }
+
+    // Empty just the blanks that were wrong on the last check and return to the neutral (unchecked)
+    // state, so the learner can retype and check again. Correct answers keep their text.
+    function clearWrong() {
+        if (!clozeData.value) return;
+        clozeData.value.blanks.forEach((b) => {
+            if (checkResults[b.blankIndex] === false) delete clozeAnswers[b.blankIndex];
+        });
+        Object.keys(checkResults).forEach((k) => delete checkResults[Number(k)]);
+        clozeChecked.value = false;
+    }
+
+    const allBlanksCorrect = computed(() => {
+        if (!clozeData.value || !clozeChecked.value) return false;
+        return clozeData.value.blanks.every((b) => checkResults[b.blankIndex] === true);
+    });
+
+    const wrongCount = computed(() => {
+        if (!clozeData.value) return 0;
+        return clozeData.value.blanks.filter((b) => checkResults[b.blankIndex] === false).length;
+    });
+
+    // Reset everything when the card (sentence) changes.
+    watch(getSentence, () => {
+        clozeChecked.value = false;
+        Object.keys(clozeAnswers).forEach((k) => delete clozeAnswers[Number(k)]);
+        Object.keys(checkResults).forEach((k) => delete checkResults[Number(k)]);
+    });
+
+    return {
+        clozeData,
+        clozeAnswers,
+        clozeChecked,
+        checkResults,
+        isBlankCorrect,
+        checkCloze,
+        clearWrong,
+        allBlanksCorrect,
+        wrongCount,
+    };
+}

From 5b6202ee0ecad9fd9a90a4c9bf67b74719bf3d08 Mon Sep 17 00:00:00 2001
From: Navid Shad <navidshad72@gmail.com>
Date: Sun, 24 May 2026 21:28:48 +0300
Subject: [PATCH 3/5] refactor(flashcard): dispatcher with :phrase API +
 extracted cards

Finish the modularization: FlashCard becomes a thin dispatcher and the
recognition presentation moves out, so each mode is its own piece.

- Extract widget/flashcard/RecognitionCard.vue (normal + linguistic).
- FlashCard now derives front/back/context/chunks/etc. from a single
  :phrase prop (+ :leitner-level), resolves cloze-vs-recognition, and
  renders the right child under the shared flip toggle. Drops the dead
  unknown-type fallback branch.
- Collapse callers: LeitnerReviewSession and flashcards-[id] go from three
  per-type <WidgetFlashCard> blocks to one `:phrase`/`:leitner-level`,
  removing the cardChunk/cardSentence/isNormalType/isLinguisticType
  plumbing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../practice/LeitnerReviewSession.vue         |  35 +--
 frontend/components/widget/FlashCard.vue      | 225 +++---------------
 .../widget/flashcard/RecognitionCard.vue      | 143 +++++++++++
 frontend/pages/practice/flashcards-[id].vue   |  47 +---
 4 files changed, 189 insertions(+), 261 deletions(-)
 create mode 100644 frontend/components/widget/flashcard/RecognitionCard.vue

diff --git a/frontend/components/practice/LeitnerReviewSession.vue b/frontend/components/practice/LeitnerReviewSession.vue
index 3e772ff..ecaa2db 100644
--- a/frontend/components/practice/LeitnerReviewSession.vue
+++ b/frontend/components/practice/LeitnerReviewSession.vue
@@ -17,24 +17,9 @@
 			     front/back; long content scrolls inside the card instead of growing the page. -->
 			<div
 				:class="['h-[58vh] w-full transition-all duration-300 ease-in-out', 'md:max-w-[80%]', 'lg:max-w-[65%]']">
-				<!-- Use WidgetFlashCard based on phrase type -->
 				<Transition name="fade-slide" mode="out-in">
-					<WidgetFlashCard v-if="currentPhrase && currentPhrase.type === 'normal'"
-						:key="`normal-${currentIndex}`" ref="flashCardRef" :phrase-type="'normal'"
-						:front="currentPhrase.phrase" :back="currentPhrase.translation" :context="currentPhrase.context"
-						:translation-language="currentPhrase.translation_language" :chunks="currentPhrase.chunks"
-						:leitner-level="cardLevel" :confirmed-chunk="cardChunk" :source-sentence="cardSentence" />
-
-					<WidgetFlashCard v-else-if="currentPhrase && currentPhrase.type === 'linguistic'"
-						:key="`linguistic-${currentIndex}`" ref="flashCardRef" :phrase-type="'linguistic'"
-						:front="currentPhrase.phrase" :back="currentPhrase.translation || currentPhrase.phrase"
-						:context="currentPhrase.context" :direction="currentPhrase.direction"
-						:language-info="currentPhrase.language_info" :linguistic-data="currentPhrase.linguistic_data"
-						:chunks="currentPhrase.chunks" :leitner-level="cardLevel" :confirmed-chunk="cardChunk"
-						:source-sentence="cardSentence" />
-
-					<WidgetFlashCard v-else-if="currentPhrase" :key="`fallback-${currentIndex}`" ref="flashCardRef"
-						:front="currentPhrase.phrase" :back="currentPhrase.translation || 'No translation'" />
+					<WidgetFlashCard v-if="currentPhrase" :key="currentIndex" ref="flashCardRef"
+						:phrase="currentPhrase" :leitner-level="cardLevel" />
 				</Transition>
 			</div>
 
@@ -97,24 +82,12 @@ const currentItem = computed(() => props.items[currentIndex.value]);
 const currentPhrase = computed(() => currentItem.value?.phrase as PhraseType);
 const totalItems = computed(() => props.items.length);
 
-// L3+ fill-in cloze inputs (level from the Leitner item, chunk + sentence from the phrase).
-// get-review-session returns raw Mongoose docs, so schema fields like boxLevel sit under `_doc`
-// rather than at the top level — read both so the level is found either way.
+// Leitner level drives the L3+ cloze. get-review-session returns raw Mongoose docs, so schema fields
+// like boxLevel sit under `_doc` rather than at the top level — read both so the level is found either way.
 const cardLevel = computed<number | undefined>(() => {
 	const item = currentItem.value as any;
 	return item?.boxLevel ?? item?._doc?.boxLevel;
 });
-const cardSentence = computed<string | null>(() => currentPhrase.value?.context ?? null);
-// Prefer the first confirmed chunk that actually appears in the source sentence. Chunk text and the
-// stored context can differ slightly (hyphenation, spacing), so blindly taking chunks[0] would drop to
-// recognition even when another chunk is a clean match. Falls back to chunks[0], then null.
-const cardChunk = computed<string | null>(() => {
-	const chunks = currentPhrase.value?.chunks || [];
-	if (!chunks.length) return null;
-	const sentence = (cardSentence.value || '').toLowerCase();
-	const matched = sentence ? chunks.find((c) => c.text && sentence.includes(c.text.toLowerCase())) : undefined;
-	return (matched || chunks[0])?.text ?? null;
-});
 
 onMounted(() => {
 	window.addEventListener('keydown', handleKeyDown);
diff --git a/frontend/components/widget/FlashCard.vue b/frontend/components/widget/FlashCard.vue
index 2b4c8dd..b139cf4 100644
--- a/frontend/components/widget/FlashCard.vue
+++ b/frontend/components/widget/FlashCard.vue
@@ -6,159 +6,12 @@
             <FlashcardFlipToggle :is-flipped="isFlipped" @flip="flipCard" />
 
             <div class="flex min-h-0 flex-1 items-center justify-center overflow-auto p-6">
-                <!-- ========== L3+ FILL-IN CLOZE PRESENTATION ========== -->
-                <ClozeCard v-if="isClozeMode" :source-sentence="props.sourceSentence" :context="props.context"
-                    :chunks="props.chunks" :direction="props.direction" :back="props.back" :is-flipped="isFlipped" />
-
-                <!-- ========== NORMAL TYPE PHRASE PRESENTATION ========== -->
-            <template v-else-if="phraseType === 'normal'">
-                <div class="flex h-full flex-col">
-                    <!-- Top row: (empty left), lang code badge right -->
-                    <div class="flex w-full items-start justify-between px-6 pt-4">
-                        <div></div>
-                        <div v-if="isFlipped" class="flex flex-col items-end gap-1">
-                            <div class="mb-0.5 pr-0.5 text-[10px] text-gray-400">Language</div>
-                            <span
-                                class="rounded-full border border-gray-300 bg-gray-100 px-3 py-1 text-xs font-bold uppercase text-gray-700">
-                                {{ props.translationLanguage || 'LANG' }}
-                            </span>
-                        </div>
-                    </div>
-                    <!-- Top empty div for spacing -->
-                    <div class="flex-1"></div>
-                    <!-- Center content div -->
-                    <div class="flex flex-1 flex-col justify-center text-center">
-                        <div :class="isFlipped ? 'mb-3 text-2xl font-medium' : 'mb-6 text-5xl font-medium'">
-                            <span v-if="!isFlipped">{{ props.front || 'Front' }}</span>
-                            <span v-else>{{ props.back || 'Back' }}</span>
-                        </div>
-                        <div v-if="!isFlipped" class="text-lg text-gray-500">
-                            <span>{{ props.context || '' }}</span>
-                        </div>
-                    </div>
-                    <!-- Bottom empty div for spacing -->
-                    <div class="flex-1"></div>
-                </div>
-            </template>
-
-            <!-- ========== LINGUISTIC TYPE PHRASE PRESENTATION ========== -->
-            <template v-else-if="phraseType === 'linguistic'">
-                <div class="relative h-full w-full max-w-4xl">
-                    <!-- Front Side: Source phrase with phonetic -->
-                    <template v-if="!isFlipped">
-                        <div class="flex h-full flex-col">
-                            <!-- Top row: (empty left), lang code badge right -->
-                            <div class="flex w-full items-start justify-between px-6 pt-4">
-                                <div></div>
-                                <div class="flex flex-col items-end gap-1">
-                                    <div class="mb-0.5 pr-0.5 text-[10px] text-gray-400">Language</div>
-                                    <span
-                                        class="rounded-full border border-gray-300 bg-gray-100 px-3 py-1 text-xs font-bold uppercase text-gray-700">
-                                        {{ props.languageInfo?.source || 'SRC' }}
-                                    </span>
-                                </div>
-                            </div>
-                            <!-- Top empty div for spacing -->
-                            <div class="flex-1"></div>
-                            <!-- Center content div -->
-                            <div class="flex flex-1 flex-col justify-center text-center">
-                                <div class="mb-6 text-5xl font-medium" :dir="props.direction?.source || 'ltr'">
-                                    {{ props.front || 'Front' }}
-                                </div>
-                                <!-- Phonetic (transliteration only) -->
-                                <div v-if="props.linguisticData?.phonetic?.transliteration"
-                                    class="flex items-center justify-center text-gray-600">
-                                    <div class="text-lg font-medium" :dir="props.direction?.target || 'ltr'">
-                                        {{ props.linguisticData.phonetic.transliteration }}
-                                    </div>
-                                </div>
-                            </div>
-                            <!-- Context div at bottom -->
-                            <div class="flex flex-1 items-end justify-center pb-8">
-                                <div v-if="props.context" class="max-w-2xl text-center text-sm italic text-gray-500"
-                                    :dir="props.direction?.source || 'ltr'">
-                                    {{ props.context }}
-                                </div>
-                            </div>
-                        </div>
-                    </template>
-
-                    <!-- Back Side: Comprehensive linguistic information -->
-                    <template v-else>
-                        <div class="relative flex h-full w-full flex-col items-center justify-center">
-                            <!-- Top row: badges (left, only for linguistic), lang code (right, always) -->
-                            <div class="flex w-full items-start justify-between px-6 pt-4">
-                                <div class="flex min-w-0 flex-col items-start gap-1">
-                                    <template
-                                        v-if="phraseType === 'linguistic' && (props.linguisticData?.type || props.linguisticData?.formality_level)">
-                                        <div class="mb-0.5 pl-0.5 text-[10px] text-gray-400">Attributes</div>
-                                        <div class="flex flex-wrap gap-2">
-                                            <span v-if="props.linguisticData?.type"
-                                                class="truncate rounded-full bg-blue-100 px-3 py-1 text-xs font-bold uppercase text-blue-800">
-                                                {{ props.linguisticData.type }}
-                                            </span>
-                                            <span v-if="props.linguisticData?.formality_level"
-                                                class="truncate rounded-full bg-orange-100 px-3 py-1 text-xs font-bold uppercase text-orange-800">
-                                                {{ props.linguisticData.formality_level }}
-                                            </span>
-                                        </div>
-                                    </template>
-                                </div>
-                                <div class="flex flex-col items-end gap-1">
-                                    <div class="mb-0.5 pr-0.5 text-[10px] text-gray-400">Language</div>
-                                    <span
-                                        class="rounded-full border border-gray-300 bg-gray-100 px-3 py-1 text-xs font-bold uppercase text-gray-700">
-                                        {{ phraseType === 'linguistic' ? props.languageInfo?.target || 'TRG' :
-                                            props.translationLanguage || 'LANG' }}
-                                    </span>
-                                </div>
-                            </div>
-
-                            <!-- Main Content (translation + per-chunk definitions, mirrors the extension) -->
-                            <!-- Scroll-safe: the inner wrapper uses my-auto so it centers when it fits and -->
-                            <!-- scrolls from the top (no clipping) when chunks/definitions overflow. -->
-                            <div class="flex h-full w-full justify-center overflow-auto py-6">
-                                <div class="my-auto flex w-full flex-col items-center gap-6">
-                                    <!-- Translation -->
-                                    <div class="text-center text-2xl font-medium" :dir="props.direction?.target || 'ltr'">
-                                        {{ props.back || 'Translation' }}
-                                    </div>
-
-                                        <!-- Definition: one block per confirmed chunk -->
-                                    <div v-if="props.chunks?.length" class="w-full max-w-2xl space-y-3">
-                                        <div class="mb-1 text-center text-xs uppercase tracking-wide text-gray-400">
-                                            Definition</div>
-                                        <div v-for="(chunk, index) in props.chunks" :key="index"
-                                            class="rounded-lg border-l-4 border-blue-200 bg-gray-50 p-3 text-left">
-                                            <div class="flex items-baseline justify-between gap-3">
-                                                <span class="font-medium" :dir="props.direction?.source || 'ltr'">
-                                                    {{ chunk.text }}
-                                                </span>
-                                                <span v-if="chunk.transliteration" class="shrink-0 text-xs text-gray-400"
-                                                    :dir="props.direction?.target || 'ltr'">
-                                                    {{ chunk.transliteration }}
-                                                </span>
-                                            </div>
-                                            <div v-if="chunk.definition" class="mt-1 text-sm text-gray-600"
-                                                :dir="props.direction?.target || 'ltr'">
-                                                {{ chunk.definition }}
-                                            </div>
-                                        </div>
-                                    </div>
-                                </div>
-                            </div>
-                        </div>
-                    </template>
-                </div>
-            </template>
-
-            <!-- ========== FALLBACK FOR UNKNOWN TYPE ========== -->
-                <template v-else>
-                    <div class="text-center text-xl text-gray-500">
-                        <span v-if="!isFlipped">{{ props.front || 'Front' }}</span>
-                        <span v-else>{{ props.back || 'Back' }}</span>
-                    </div>
-                </template>
+                <!-- L3+ fill-in cloze, else the recognition card -->
+                <ClozeCard v-if="isClozeMode" :context="context" :chunks="chunks" :direction="direction" :back="back"
+                    :is-flipped="isFlipped" />
+                <RecognitionCard v-else :phrase-type="phraseType" :front="front" :back="back" :context="context"
+                    :translation-language="translationLanguage" :direction="direction" :language-info="languageInfo"
+                    :linguistic-data="linguisticData" :chunks="chunks" :is-flipped="isFlipped" />
             </div>
         </Card>
     </div>
@@ -171,50 +24,46 @@ import type { LinguisticData, Chunk } from '~/types/database.type';
 import { useCardFlip } from '~/composables/useCardFlip';
 import { buildClozeData } from '~/composables/useClozeBlanks';
 import ClozeCard from './flashcard/ClozeCard.vue';
+import RecognitionCard from './flashcard/RecognitionCard.vue';
 import FlashcardFlipToggle from './flashcard/FlashcardFlipToggle.vue';
 
-// Define the props interface for better type safety
-interface FlashCardProps {
-    // Common props for both types
-    front?: string;
-    back?: string;
-    phraseType?: 'normal' | 'linguistic';
+/** The fields FlashCard reads off a phrase document. Kept loose so callers can pass a PhraseType. */
+interface FlashcardPhrase {
+    type?: 'normal' | 'linguistic';
+    phrase?: string;
+    translation?: string;
+    translation_language?: string;
     context?: string;
-
-    // Normal type specific props
-    translationLanguage?: string;
-
-    // Linguistic type specific props
-    direction?: {
-        source: 'ltr' | 'rtl';
-        target: 'ltr' | 'rtl';
-    };
-    languageInfo?: {
-        source: string;
-        target: string;
-    };
-    linguisticData?: LinguisticData;
-    /** Confirmed reusable patterns; rendered as per-chunk definitions on the linguistic back. */
+    direction?: { source: 'ltr' | 'rtl'; target: 'ltr' | 'rtl' };
+    language_info?: { source: string; target: string };
+    linguistic_data?: LinguisticData;
     chunks?: Chunk[];
-
-    // Leitner L3+ fill-in cloze
-    leitnerLevel?: number;
-    confirmedChunk?: string | null;
-    sourceSentence?: string | null;
 }
 
-const props = withDefaults(defineProps<FlashCardProps>(), {
-    phraseType: 'normal',
-    front: 'Front',
-    back: 'Back',
-});
+const props = defineProps<{
+    /** The phrase to show. FlashCard derives the front/back/context/etc. from it. */
+    phrase?: FlashcardPhrase | null;
+    /** Leitner box level — at 3+ (with a usable chunk) the card becomes a fill-in cloze. */
+    leitnerLevel?: number;
+}>();
+
+// Derived view of the phrase.
+const phraseType = computed(() => props.phrase?.type ?? 'normal');
+const front = computed(() => props.phrase?.phrase ?? '');
+const back = computed(() => props.phrase?.translation || props.phrase?.phrase || '');
+const context = computed(() => props.phrase?.context ?? '');
+const translationLanguage = computed(() => props.phrase?.translation_language);
+const direction = computed(() => props.phrase?.direction);
+const languageInfo = computed(() => props.phrase?.language_info);
+const linguisticData = computed(() => props.phrase?.linguistic_data);
+const chunks = computed(() => props.phrase?.chunks ?? []);
 
 // Flip state (resets to the front whenever the card changes).
-const { isFlipped, flipCard } = useCardFlip(() => [props.front, props.sourceSentence]);
+const { isFlipped, flipCard } = useCardFlip(() => [front.value, context.value]);
 
-// L3+ fill-in card when the level is 3+ and at least one confirmed chunk lands in the sentence;
-// otherwise fall back to the recognition card. The cloze exercise state lives inside ClozeCard.
-const isClozeMode = computed(() => (props.leitnerLevel ?? 0) >= 3 && !!buildClozeData(props.sourceSentence || props.context, props.chunks));
+// L3+ fill-in card when the level is 3+ and at least one confirmed chunk lands in the source
+// sentence; otherwise the recognition card. The cloze exercise state lives inside ClozeCard.
+const isClozeMode = computed(() => (props.leitnerLevel ?? 0) >= 3 && !!buildClozeData(context.value, chunks.value));
 
 defineExpose({
     flipCard,
diff --git a/frontend/components/widget/flashcard/RecognitionCard.vue b/frontend/components/widget/flashcard/RecognitionCard.vue
new file mode 100644
index 0000000..9200015
--- /dev/null
+++ b/frontend/components/widget/flashcard/RecognitionCard.vue
@@ -0,0 +1,143 @@
+<template>
+    <!-- ========== NORMAL TYPE ========== -->
+    <div v-if="props.phraseType === 'normal'" class="flex h-full flex-col">
+        <!-- Top row: (empty left), lang code badge right -->
+        <div class="flex w-full items-start justify-between px-6 pt-4">
+            <div></div>
+            <div v-if="isFlipped" class="flex flex-col items-end gap-1">
+                <div class="mb-0.5 pr-0.5 text-[10px] text-gray-400">Language</div>
+                <span
+                    class="rounded-full border border-gray-300 bg-gray-100 px-3 py-1 text-xs font-bold uppercase text-gray-700">
+                    {{ props.translationLanguage || 'LANG' }}
+                </span>
+            </div>
+        </div>
+        <div class="flex-1"></div>
+        <!-- Center content -->
+        <div class="flex flex-1 flex-col justify-center text-center">
+            <div :class="isFlipped ? 'mb-3 text-2xl font-medium' : 'mb-6 text-5xl font-medium'">
+                <span v-if="!isFlipped">{{ props.front || 'Front' }}</span>
+                <span v-else>{{ props.back || 'Back' }}</span>
+            </div>
+            <div v-if="!isFlipped" class="text-lg text-gray-500">
+                <span>{{ props.context || '' }}</span>
+            </div>
+        </div>
+        <div class="flex-1"></div>
+    </div>
+
+    <!-- ========== LINGUISTIC TYPE ========== -->
+    <div v-else class="relative h-full w-full max-w-4xl">
+        <!-- Front: source phrase with phonetic -->
+        <template v-if="!isFlipped">
+            <div class="flex h-full flex-col">
+                <div class="flex w-full items-start justify-between px-6 pt-4">
+                    <div></div>
+                    <div class="flex flex-col items-end gap-1">
+                        <div class="mb-0.5 pr-0.5 text-[10px] text-gray-400">Language</div>
+                        <span
+                            class="rounded-full border border-gray-300 bg-gray-100 px-3 py-1 text-xs font-bold uppercase text-gray-700">
+                            {{ props.languageInfo?.source || 'SRC' }}
+                        </span>
+                    </div>
+                </div>
+                <div class="flex-1"></div>
+                <div class="flex flex-1 flex-col justify-center text-center">
+                    <div class="mb-6 text-5xl font-medium" :dir="props.direction?.source || 'ltr'">
+                        {{ props.front || 'Front' }}
+                    </div>
+                    <!-- Phonetic (transliteration only) -->
+                    <div v-if="props.linguisticData?.phonetic?.transliteration"
+                        class="flex items-center justify-center text-gray-600">
+                        <div class="text-lg font-medium" :dir="props.direction?.target || 'ltr'">
+                            {{ props.linguisticData.phonetic.transliteration }}
+                        </div>
+                    </div>
+                </div>
+                <!-- Context at bottom -->
+                <div class="flex flex-1 items-end justify-center pb-8">
+                    <div v-if="props.context" class="max-w-2xl text-center text-sm italic text-gray-500"
+                        :dir="props.direction?.source || 'ltr'">
+                        {{ props.context }}
+                    </div>
+                </div>
+            </div>
+        </template>
+
+        <!-- Back: translation + per-chunk definitions -->
+        <template v-else>
+            <div class="relative flex h-full w-full flex-col items-center justify-center">
+                <div class="flex w-full items-start justify-between px-6 pt-4">
+                    <div class="flex min-w-0 flex-col items-start gap-1">
+                        <template v-if="props.linguisticData?.type || props.linguisticData?.formality_level">
+                            <div class="mb-0.5 pl-0.5 text-[10px] text-gray-400">Attributes</div>
+                            <div class="flex flex-wrap gap-2">
+                                <span v-if="props.linguisticData?.type"
+                                    class="truncate rounded-full bg-blue-100 px-3 py-1 text-xs font-bold uppercase text-blue-800">
+                                    {{ props.linguisticData.type }}
+                                </span>
+                                <span v-if="props.linguisticData?.formality_level"
+                                    class="truncate rounded-full bg-orange-100 px-3 py-1 text-xs font-bold uppercase text-orange-800">
+                                    {{ props.linguisticData.formality_level }}
+                                </span>
+                            </div>
+                        </template>
+                    </div>
+                    <div class="flex flex-col items-end gap-1">
+                        <div class="mb-0.5 pr-0.5 text-[10px] text-gray-400">Language</div>
+                        <span
+                            class="rounded-full border border-gray-300 bg-gray-100 px-3 py-1 text-xs font-bold uppercase text-gray-700">
+                            {{ props.languageInfo?.target || 'TRG' }}
+                        </span>
+                    </div>
+                </div>
+
+                <!-- Main content: translation + per-chunk definitions. Scroll-safe via my-auto. -->
+                <div class="flex h-full w-full justify-center overflow-auto py-6">
+                    <div class="my-auto flex w-full flex-col items-center gap-6">
+                        <div class="text-center text-2xl font-medium" :dir="props.direction?.target || 'ltr'">
+                            {{ props.back || 'Translation' }}
+                        </div>
+
+                        <div v-if="props.chunks?.length" class="w-full max-w-2xl space-y-3">
+                            <div class="mb-1 text-center text-xs uppercase tracking-wide text-gray-400">Definition</div>
+                            <div v-for="(chunk, index) in props.chunks" :key="index"
+                                class="rounded-lg border-l-4 border-blue-200 bg-gray-50 p-3 text-left">
+                                <div class="flex items-baseline justify-between gap-3">
+                                    <span class="font-medium" :dir="props.direction?.source || 'ltr'">
+                                        {{ chunk.text }}
+                                    </span>
+                                    <span v-if="chunk.transliteration" class="shrink-0 text-xs text-gray-400"
+                                        :dir="props.direction?.target || 'ltr'">
+                                        {{ chunk.transliteration }}
+                                    </span>
+                                </div>
+                                <div v-if="chunk.definition" class="mt-1 text-sm text-gray-600"
+                                    :dir="props.direction?.target || 'ltr'">
+                                    {{ chunk.definition }}
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </template>
+    </div>
+</template>
+
+<script setup lang="ts">
+import type { LinguisticData, Chunk } from '~/types/database.type';
+
+const props = defineProps<{
+    phraseType?: 'normal' | 'linguistic';
+    front?: string;
+    back?: string;
+    context?: string;
+    translationLanguage?: string;
+    direction?: { source: 'ltr' | 'rtl'; target: 'ltr' | 'rtl' };
+    languageInfo?: { source: string; target: string };
+    linguisticData?: LinguisticData;
+    chunks?: Chunk[];
+    isFlipped?: boolean;
+}>();
+</script>
diff --git a/frontend/pages/practice/flashcards-[id].vue b/frontend/pages/practice/flashcards-[id].vue
index 505514c..72ca67c 100644
--- a/frontend/pages/practice/flashcards-[id].vue
+++ b/frontend/pages/practice/flashcards-[id].vue
@@ -3,23 +3,7 @@
         :totalPhrases="totalPhrases" :bundleId="id.toString()" @end-session="endFlashcardSession">
         <div :class="['flex h-full w-full flex-col items-center p-5', 'md:px-16 md:py-14']">
             <div :class="['w-full flex-1 ', 'md:max-h-[80%] md:max-w-[80%]', 'lg:max-h-[65%] lg:max-w-[65%]']">
-                <!-- ========== NORMAL TYPE FLASHCARD ========== -->
-                <WidgetFlashCard v-if="phrase && isNormalType" :key="`normal-${phraseIndex}`" :phrase-type="'normal'"
-                    :front="phrase.phrase" :back="phrase.translation" :context="phrase.context"
-                    :translation-language="phrase.translation_language" :leitner-level="cardLevel"
-                    :confirmed-chunk="cardChunk" :source-sentence="cardSentence" />
-
-                <!-- ========== LINGUISTIC TYPE FLASHCARD ========== -->
-                <WidgetFlashCard v-else-if="phrase && isLinguisticType" :key="`linguistic-${phraseIndex}`"
-                    :phrase-type="'linguistic'" :front="phrase.phrase"
-                    :back="phrase.translation || phrase.phrase" :context="phrase.context"
-                    :direction="phrase.direction" :language-info="phrase.language_info"
-                    :linguistic-data="phrase.linguistic_data" :chunks="phrase.chunks" :leitner-level="cardLevel"
-                    :confirmed-chunk="cardChunk" :source-sentence="cardSentence" />
-
-                <!-- ========== FALLBACK FOR UNKNOWN TYPE ========== -->
-                <WidgetFlashCard v-else-if="phrase" :key="`fallback-${phraseIndex}`" :front="phrase.phrase"
-                    :back="phrase.translation || 'No translation available'" />
+                <WidgetFlashCard v-if="phrase" :key="phraseIndex" :phrase="phrase" :leitner-level="cardLevel" />
             </div>
 
             <selection class="my-6 flex max-h-[65%] w-full max-w-[65%] items-center justify-between">
@@ -96,27 +80,9 @@ const isNextAvailable = computed(() => {
     return phraseIndex.value < totalPhrases.value - 1;
 });
 
-// L3+ fill-in cloze data, carried on the enriched phrase in Leitner mode (undefined otherwise → recognition card).
+// Leitner level drives the L3+ cloze; carried on the enriched phrase in Leitner mode
+// (undefined otherwise → recognition card). FlashCard derives everything else from the phrase.
 const cardLevel = computed<number | undefined>(() => (phrase.value as any)?._leitnerLevel);
-const cardChunk = computed<string | null>(() => (phrase.value as any)?._confirmedChunk ?? null);
-const cardSentence = computed<string | null>(() => (phrase.value as any)?._sourceSentence ?? null);
-
-// ========== PHRASE TYPE DETECTION LOGIC ==========
-/**
- * Determines if the current phrase is of "normal" type
- * Normal type phrases have: phrase, translation, translation_language
- */
-const isNormalType = computed(() => {
-    return phrase.value?.type === 'normal';
-});
-
-/**
- * Determines if the current phrase is of "linguistic" type
- * Linguistic type phrases have: phrase, context, direction, language_info, linguistic_data
- */
-const isLinguisticType = computed(() => {
-    return phrase.value?.type === 'linguistic';
-});
 
 onMounted(() => {
     fetchFlashcard();
@@ -143,13 +109,10 @@ function fetchFlashcard() {
                 bundle.value = { title: 'Daily Review', phrases: [], refId: authUser.value?.id } as any;
                 return;
             }
-            // Map items to phrases, carrying through the Leitner level + confirmed chunk
-            // so the L3+ fill-in cloze can render (falls back to phrase fields until the RPC exposes them).
+            // Map items to phrases, carrying the Leitner level through so the L3+ cloze can render.
             const phrases = res.items.map((i: any) => ({
                 ...i.phrase,
-                _leitnerLevel: i.boxLevel,
-                _confirmedChunk: i.confirmed_chunk ?? i.phrase?.chunks?.[0]?.text ?? null,
-                _sourceSentence: i.source_sentence ?? i.phrase?.context ?? null,
+                _leitnerLevel: i.boxLevel ?? i._doc?.boxLevel,
             }));
             bundle.value = {
                 _id: res._id,

From c0bb1e00b14ab817258779e47e4b6f72138b2809 Mon Sep 17 00:00:00 2001
From: Navid Shad <navidshad72@gmail.com>
Date: Sun, 24 May 2026 21:28:57 +0300
Subject: [PATCH 4/5] test(flashcard): unit tests for cloze logic + card
 components

- buildClozeData: empty/no-chunk/no-match cases, single + multi blank,
  overlap handling, case-insensitive matching.
- FlashcardFlipToggle, RecognitionCard, ClozeCard, and the FlashCard
  dispatcher (cloze vs recognition selection, no-match fallback).

Per-file `vi.mock('vue', actual)` restores real Vue reactivity, which the
global test setup otherwise stubs out.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../tests/unit/components/ClozeCard.test.ts   | 65 +++++++++++++++++++
 .../tests/unit/components/FlashCard.test.ts   | 53 +++++++++++++++
 .../components/FlashcardFlipToggle.test.ts    | 37 +++++++++++
 .../unit/components/RecognitionCard.test.ts   | 59 +++++++++++++++++
 .../unit/composables/useClozeBlanks.test.ts   | 64 ++++++++++++++++++
 5 files changed, 278 insertions(+)
 create mode 100644 frontend/tests/unit/components/ClozeCard.test.ts
 create mode 100644 frontend/tests/unit/components/FlashCard.test.ts
 create mode 100644 frontend/tests/unit/components/FlashcardFlipToggle.test.ts
 create mode 100644 frontend/tests/unit/components/RecognitionCard.test.ts
 create mode 100644 frontend/tests/unit/composables/useClozeBlanks.test.ts

diff --git a/frontend/tests/unit/components/ClozeCard.test.ts b/frontend/tests/unit/components/ClozeCard.test.ts
new file mode 100644
index 0000000..7d0e1b5
--- /dev/null
+++ b/frontend/tests/unit/components/ClozeCard.test.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect, vi } from 'vitest';
+vi.mock('vue', async () => await vi.importActual('vue'));
+import { mount } from '@vue/test-utils';
+import ClozeCard from '~/components/widget/flashcard/ClozeCard.vue';
+
+const props = {
+    context: 'we had to decide quickly, right?',
+    chunks: [
+        { text: 'had to', type: 'collocation', confidence: 0.9, definition: 'obligation', transliteration: 'هَد تو' },
+        { text: 'right?', type: 'discourse_marker', confidence: 0.8, definition: 'seeking agreement' },
+    ],
+    direction: { source: 'ltr' as const, target: 'ltr' as const },
+    back: 'the meaning',
+};
+
+const checkButton = (w: ReturnType<typeof mount>) => w.findAll('button').find((b) => /Check|Recheck/.test(b.text()))!;
+
+describe('ClozeCard', () => {
+    it('renders one blank input per chunk found in the sentence', () => {
+        const w = mount(ClozeCard, { props: { ...props, isFlipped: false } });
+        expect(w.text()).toContain('Fill in the blanks');
+        expect(w.findAll('input')).toHaveLength(2);
+    });
+
+    it('marks blanks correct/incorrect only after Check and reports the count', async () => {
+        const w = mount(ClozeCard, { props: { ...props, isFlipped: false } });
+        const inputs = w.findAll('input');
+        await inputs[0].setValue('had to'); // correct
+        await inputs[1].setValue('nope'); // wrong
+
+        // No colouring before Check.
+        expect(inputs[0].classes()).toContain('border-blue-500');
+
+        await checkButton(w).trigger('click');
+
+        expect(inputs[0].classes()).toContain('border-green-500');
+        expect(inputs[1].classes()).toContain('border-red-500');
+        expect(w.text()).toContain('1 to fix');
+    });
+
+    it('Clear wrong empties only the incorrect blanks and resets to a neutral state', async () => {
+        const w = mount(ClozeCard, { props: { ...props, isFlipped: false } });
+        const inputs = w.findAll('input');
+        await inputs[0].setValue('had to');
+        await inputs[1].setValue('nope');
+        await checkButton(w).trigger('click');
+
+        const clear = w.findAll('button').find((b) => b.text() === 'Clear wrong')!;
+        await clear.trigger('click');
+
+        expect((inputs[0].element as HTMLInputElement).value).toBe('had to'); // correct kept
+        expect((inputs[1].element as HTMLInputElement).value).toBe(''); // wrong cleared
+        expect(inputs[1].classes()).toContain('border-blue-500'); // back to neutral
+        expect(checkButton(w).text()).toBe('Check'); // not "Recheck"
+    });
+
+    it('back side reveals the filled sentence and chunk definitions', () => {
+        const w = mount(ClozeCard, { props: { ...props, isFlipped: true } });
+        expect(w.text()).toContain('had to');
+        expect(w.text()).toContain('Definition');
+        expect(w.text()).toContain('obligation');
+        expect(w.text()).toContain('the meaning');
+        expect(w.findAll('input')).toHaveLength(0); // no inputs on the back
+    });
+});
diff --git a/frontend/tests/unit/components/FlashCard.test.ts b/frontend/tests/unit/components/FlashCard.test.ts
new file mode 100644
index 0000000..af892d1
--- /dev/null
+++ b/frontend/tests/unit/components/FlashCard.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect, vi } from 'vitest';
+vi.mock('vue', async () => await vi.importActual('vue'));
+// Avoid importing the real pilotui Card in jsdom; the stub below renders the slot.
+vi.mock('pilotui/elements', () => ({ Card: { name: 'Card', template: '<div><slot /></div>' } }));
+import { mount } from '@vue/test-utils';
+import FlashCard from '~/components/widget/FlashCard.vue';
+
+const mountCard = (props: Record<string, unknown>) =>
+    mount(FlashCard, {
+        props,
+        global: {
+            stubs: {
+                Card: { template: '<div><slot /></div>' },
+                FlashcardFlipToggle: true,
+                ClozeCard: { template: '<div class="cloze-stub" />' },
+                RecognitionCard: { template: '<div class="recognition-stub" />' },
+            },
+        },
+    });
+
+const linguisticPhrase = {
+    type: 'linguistic' as const,
+    phrase: 'we had to go',
+    translation: 'مجبور بودیم برویم',
+    context: 'we had to go quickly',
+    chunks: [{ text: 'had to', type: 'collocation', confidence: 0.9 }],
+};
+
+describe('FlashCard dispatcher', () => {
+    it('renders the recognition card below level 3', () => {
+        const w = mountCard({ phrase: linguisticPhrase, leitnerLevel: 1 });
+        expect(w.find('.recognition-stub').exists()).toBe(true);
+        expect(w.find('.cloze-stub').exists()).toBe(false);
+    });
+
+    it('renders the cloze card at level 3 when a chunk lands in the sentence', () => {
+        const w = mountCard({ phrase: linguisticPhrase, leitnerLevel: 3 });
+        expect(w.find('.cloze-stub').exists()).toBe(true);
+        expect(w.find('.recognition-stub').exists()).toBe(false);
+    });
+
+    it('falls back to recognition at level 3 when no chunk matches the sentence', () => {
+        const noMatch = { ...linguisticPhrase, chunks: [{ text: 'not present here', type: 'other', confidence: 0.9 }] };
+        const w = mountCard({ phrase: noMatch, leitnerLevel: 3 });
+        expect(w.find('.recognition-stub').exists()).toBe(true);
+        expect(w.find('.cloze-stub').exists()).toBe(false);
+    });
+
+    it('always renders the shared flip toggle', () => {
+        const w = mountCard({ phrase: linguisticPhrase, leitnerLevel: 1 });
+        expect(w.findComponent({ name: 'FlashcardFlipToggle' }).exists()).toBe(true);
+    });
+});
diff --git a/frontend/tests/unit/components/FlashcardFlipToggle.test.ts b/frontend/tests/unit/components/FlashcardFlipToggle.test.ts
new file mode 100644
index 0000000..70b485c
--- /dev/null
+++ b/frontend/tests/unit/components/FlashcardFlipToggle.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+// The global setup mocks `vue`; restore the real implementation so SFC reactivity works.
+vi.mock('vue', async () => await vi.importActual('vue'));
+import { mount } from '@vue/test-utils';
+import FlashcardFlipToggle from '~/components/widget/flashcard/FlashcardFlipToggle.vue';
+
+describe('FlashcardFlipToggle', () => {
+    it('renders the default Question / Answer labels', () => {
+        const w = mount(FlashcardFlipToggle, { props: { isFlipped: false } });
+        expect(w.text()).toContain('Question');
+        expect(w.text()).toContain('Answer');
+    });
+
+    it('marks the active side and not the other', () => {
+        const w = mount(FlashcardFlipToggle, { props: { isFlipped: false } });
+        const [question, answer] = w.findAll('button');
+        expect(question.classes()).toContain('bg-blue-100');
+        expect(answer.classes()).not.toContain('bg-blue-100');
+    });
+
+    it('emits flip only when clicking the inactive side', async () => {
+        const w = mount(FlashcardFlipToggle, { props: { isFlipped: false } });
+        const [question, answer] = w.findAll('button');
+
+        await question.trigger('click'); // already active → no flip
+        expect(w.emitted('flip')).toBeFalsy();
+
+        await answer.trigger('click'); // inactive → flip
+        expect(w.emitted('flip')).toHaveLength(1);
+    });
+
+    it('supports custom labels', () => {
+        const w = mount(FlashcardFlipToggle, { props: { frontLabel: 'Exercise', backLabel: 'Solution' } });
+        expect(w.text()).toContain('Exercise');
+        expect(w.text()).toContain('Solution');
+    });
+});
diff --git a/frontend/tests/unit/components/RecognitionCard.test.ts b/frontend/tests/unit/components/RecognitionCard.test.ts
new file mode 100644
index 0000000..053d946
--- /dev/null
+++ b/frontend/tests/unit/components/RecognitionCard.test.ts
@@ -0,0 +1,59 @@
+import { describe, it, expect, vi } from 'vitest';
+vi.mock('vue', async () => await vi.importActual('vue'));
+import { mount } from '@vue/test-utils';
+import RecognitionCard from '~/components/widget/flashcard/RecognitionCard.vue';
+
+describe('RecognitionCard — normal', () => {
+    const base = {
+        phraseType: 'normal' as const,
+        front: 'hello',
+        back: 'سلام',
+        context: 'a common greeting',
+        translationLanguage: 'fa',
+    };
+
+    it('shows the front phrase and context, not the translation, when not flipped', () => {
+        const w = mount(RecognitionCard, { props: { ...base, isFlipped: false } });
+        expect(w.text()).toContain('hello');
+        expect(w.text()).toContain('a common greeting');
+        expect(w.text()).not.toContain('سلام');
+    });
+
+    it('shows the translation when flipped', async () => {
+        const w = mount(RecognitionCard, { props: { ...base, isFlipped: true } });
+        expect(w.text()).toContain('سلام');
+    });
+});
+
+describe('RecognitionCard — linguistic', () => {
+    const base = {
+        phraseType: 'linguistic' as const,
+        front: 'had to',
+        back: 'مجبور بودن',
+        context: 'we had to go',
+        direction: { source: 'ltr' as const, target: 'rtl' as const },
+        languageInfo: { source: 'en', target: 'fa' },
+        linguisticData: {
+            isValid: true,
+            type: 'idiom',
+            definition: '',
+            phonetic: { transliteration: 'هَد تو' },
+            formality_level: 'neutral' as const,
+        },
+        chunks: [{ text: 'had to', type: 'idiom', confidence: 0.9, definition: 'obligation', transliteration: 'هَد تو' }],
+    };
+
+    it('front shows phrase + transliteration + context', () => {
+        const w = mount(RecognitionCard, { props: { ...base, isFlipped: false } });
+        expect(w.text()).toContain('had to');
+        expect(w.text()).toContain('هَد تو');
+        expect(w.text()).toContain('we had to go');
+    });
+
+    it('back shows the translation and per-chunk definitions, not the linguistic_data.definition', async () => {
+        const w = mount(RecognitionCard, { props: { ...base, isFlipped: true } });
+        expect(w.text()).toContain('مجبور بودن'); // translation
+        expect(w.text()).toContain('Definition');
+        expect(w.text()).toContain('obligation'); // chunk definition
+    });
+});
diff --git a/frontend/tests/unit/composables/useClozeBlanks.test.ts b/frontend/tests/unit/composables/useClozeBlanks.test.ts
new file mode 100644
index 0000000..1960f55
--- /dev/null
+++ b/frontend/tests/unit/composables/useClozeBlanks.test.ts
@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { buildClozeData } from '~/composables/useClozeBlanks';
+import type { Chunk } from '~/types/database.type';
+
+const chunk = (text: string, extra: Partial<Chunk> = {}): Chunk => ({
+    text,
+    type: 'other',
+    confidence: 0.9,
+    ...extra,
+});
+
+describe('buildClozeData', () => {
+    it('returns null when there is no sentence', () => {
+        expect(buildClozeData('', [chunk('had to')])).toBeNull();
+        expect(buildClozeData(null, [chunk('had to')])).toBeNull();
+    });
+
+    it('returns null when there are no chunks', () => {
+        expect(buildClozeData('we had to decide quickly', [])).toBeNull();
+        expect(buildClozeData('we had to decide quickly', null)).toBeNull();
+    });
+
+    it('returns null when no chunk appears in the sentence', () => {
+        // Hyphenation mismatch: chunk "Multi step tasks" not found in "Multi-step tasks ...".
+        expect(buildClozeData('Multi-step tasks are great', [chunk('Multi step tasks')])).toBeNull();
+    });
+
+    it('blanks a single chunk and splits the sentence around it', () => {
+        const data = buildClozeData('we had to decide quickly', [chunk('had to')]);
+        expect(data).not.toBeNull();
+        expect(data!.blanks).toHaveLength(1);
+        expect(data!.blanks[0].answer).toBe('had to');
+        expect(data!.segments).toEqual([
+            { type: 'text', value: 'we ' },
+            { type: 'blank', blankIndex: 0, answer: 'had to', chunk: expect.objectContaining({ text: 'had to' }) },
+            { type: 'text', value: ' decide quickly' },
+        ]);
+    });
+
+    it('preserves the original casing of the matched answer (case-insensitive match)', () => {
+        const data = buildClozeData('Had To run', [chunk('had to')]);
+        expect(data!.blanks[0].answer).toBe('Had To');
+    });
+
+    it('blanks multiple chunks ordered by their position in the sentence', () => {
+        const data = buildClozeData('we had to decide quickly, right?', [chunk('right?'), chunk('had to')]);
+        expect(data!.blanks.map((b) => b.answer)).toEqual(['had to', 'right?']);
+        const blankSegs = data!.segments.filter((s) => s.type === 'blank');
+        expect(blankSegs).toHaveLength(2);
+    });
+
+    it('drops overlapping chunks, keeping the earliest', () => {
+        // "no match" and "no match for" overlap — only the earliest-starting, then non-overlapping, survive.
+        const data = buildClozeData('they are no match for us', [chunk('no match for'), chunk('match')]);
+        expect(data!.blanks).toHaveLength(1);
+        expect(data!.blanks[0].answer).toBe('no match for');
+    });
+
+    it('skips chunks not present but keeps the ones that are', () => {
+        const data = buildClozeData('we had to decide', [chunk('missing'), chunk('had to')]);
+        expect(data!.blanks).toHaveLength(1);
+        expect(data!.blanks[0].answer).toBe('had to');
+    });
+});

From c3168859ec071753ed3fe2786c33870527b51286 Mon Sep 17 00:00:00 2001
From: Navid Shad <navidshad72@gmail.com>
Date: Sun, 24 May 2026 21:39:09 +0300
Subject: [PATCH 5/5] docs(commits): add semver commit-title convention to
 CLAUDE.md

Document the Conventional Commits -> semver bump mapping so commit and PR
titles move the intended version part. Mirrors the convention already
enforced by semantic-release in the sibling subturtle-extension-apps repo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 1bd61af..095c464 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -125,6 +125,19 @@ Modules are discovered dynamically by the modular-rest framework. Entry point: [
 - **i18n**: strings in [frontend/locales/en.json](frontend/locales/en.json) — only English is wired up today.
 - **UI components**: prefer **pilotui** (in-house Vue 3 + Tailwind library) before hand-rolling. Components are organized by category path (`pilotui/elements`, `pilotui/form`, `pilotui/shell`, etc.), use the `CL` prefix (e.g. `<CLButton>`), and require wrapping the app in `AppRoot` for theming. Registered in [frontend/plugins/component-library.ts](frontend/plugins/component-library.ts). **LLM-friendly docs**: <https://codebridger.github.io/lib-vue-components/llm.md> — fetch when adding or editing UI to see component APIs.
 
+## Commits & versioning
+
+This repo uses **semantic versioning**, and commit titles follow **Conventional Commits** so the type prefix maps to the intended `vMAJOR.MINOR.PATCH` bump. Pick the type by the change's real impact, not by habit:
+
+- `feat:` → **minor** (`0.X.0`) — new user-facing capability
+- `fix:` / `perf:` → **patch** (`0.0.X`) — bug fix or performance
+- `feat!:` / `fix!:` / a `BREAKING CHANGE:` footer → **major** (`X.0.0`)
+- `refactor:` / `chore:` / `docs:` / `test:` / `style:` / `ci:` / `build:` → **no bump**
+
+Don't dress a real feature as `refactor`/`chore` (it would skip a release) or inflate a refactor into `feat` (it over-bumps). If you squash-merge a PR, the **PR title** becomes the commit message, so it must follow the same convention.
+
+> Release automation is **not** wired up in this repo yet (no `semantic-release`, no tags, `server/package.json` is `0.0.0`) — the convention currently records the *intended* bump. The sibling **subturtle-extension-apps** repo enforces the identical mapping automatically via `semantic-release`.
+
 ## Gotchas
 
 - **Gemini, not OpenAI**, for new live-session work.