Resolve pending commit links of MIL-006

Review record RC-028 (Go, autonomous mode, not independent).

Task: MIL-006#1
Task: MIL-006#2
Task: MIL-006#3
Task: MIL-006#4
Task: MIL-006#5

.gitattributes

@@ -0,0 +1,5 @@
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.csv text eol=lf
+*.png binary

docs/artifact-registry.md

@@ -25,7 +25,7 @@ document of a type. `Primary File` may contain a glob (e.g.
 | DCD | Design Class Diagram | docs/dcd.md | 002 |
 | DICT | Domain Dictionary | docs/dictionary.md | 002 |
 | ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0004 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 026 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 029 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
 
 ## Languages

docs/sqa/reviews/rc-026-py-mil-004.md

@@ -0,0 +1,64 @@
+# RC-026: Review of PY-MIL-004
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-026 |
+| CrossReference | [PY-MIL-004], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [02e0c2c] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [PY-MIL-004]
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | PEP 8 casing holds; ruff rule set N passes. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names are the assignment's (`flip_card`, `flip_timer`, `next_card`) and the IT terms of the dictionary; `Side` states its purpose. |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` and `ruff format --check` pass with no suppressions. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every signature is annotated; `mypy --strict` passes on 31 source files. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | No exception handling was added; none is bare. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults, no builtin shadowed. |
+| 7 | Files, locks and connections are managed with context managers | Pass | No file or connection is opened in this change. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | New and changed members have Doxygen docstrings; `doxygen Doxyfile` ends with 0 warnings. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | No `print`; no logging needed. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | Pass | `Side`, `flip_card`, `flip_timer` and the view's timer follow DCD-001 and SD-001 (`flip_card` row of Method Traceability, timer step of SSD-001). |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 76 tests: view model sides, finished state, flip rules; e2e front and back state, recording scheduler, real 50 ms timer; no network, no order dependency (state reset in each test). |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | `mypy --strict` reports no issue; no `Any`. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | `dependencies` stays empty. |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | The side rule exists once in the view model; image and colour names come from `constants.py`; `_show_card` is the only place that draws a card. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `lint-imports` reports `Layers point inward` kept; the view model imports no Tkinter. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | The view model holds the side rule and the view only draws; a new side would extend `Side` and `_show_card`. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | Files stay in `presentation/features/flash_card/`; tests in `unit` and `e2e`. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | Names follow the rule; no new file contains a space. |
+
+## Overall Verdict
+
+Go — every Mandatory criterion passes. Reviewed by AI as stand-in for S01; not independent of the author.
+
+Milestone MIL-004 Go criteria: 1 `flip_card` changes side, language name and text (unit test); 2 `next_card` returns to the front (unit test); 3 `after(3000, flip_card)` is scheduled and the earlier id is cancelled first (recording scheduler e2e test); 4 back image and white text, front image and black text (e2e); 5 `PhotoImage` objects are attributes created in `__init__`, none in a callback (grep); 6 this record, `pytest` 76 passed. A manual run with a 100 ms delay showed `Danish` and white text. All Go.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| none | - | - |
+
+---
+
+[PY-MIL-004]: ../../../src/flash_card/presentation
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[02e0c2c]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/02e0c2c55e2a62ca13e2dec9dbf3aa823cf16242

docs/sqa/reviews/rc-027-py-mil-005.md

@@ -0,0 +1,64 @@
+# RC-027: Review of PY-MIL-005
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-027 |
+| CrossReference | [PY-MIL-005], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [8dbaaa3] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [PY-MIL-005]
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | PEP 8 casing holds; ruff rule set N passes. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names are the dictionary's IT terms and the assignment's (`is_known`, `mark_known`, `ProgressRepository`). |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` and `ruff format --check` pass on 47 files with no suppressions; `[tool.ruff.format] line-ending = "lf"` and `.gitattributes` fix the line endings. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every signature is annotated; `mypy --strict` passes on 33 source files. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | A malformed progress file raises `VocabularyFormatError` and is never overwritten; the temporary file is removed when a write fails (re-raise, no swallow); no bare `except`. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults, no builtin shadowed. |
+| 7 | Files, locks and connections are managed with context managers | Pass | Reading uses `with`; the write goes through a temporary file that is replaced atomically. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | New and changed members have Doxygen docstrings; `doxygen Doxyfile` ends with 0 warnings. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | No `print`; no secret or personal data is logged. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | Pass | `ProgressRepository`, `CsvProgressRepository`, `StudySession.mark_known` and `is_known` are in DCD-001 and OC-001 (`markKnown`); `open_study_session` takes no speech port until MIL-006, as DCD-001 shows for the final design. |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 107 tests (6 consecutive full runs all green) include the assignment's 3 record example, restart, round trip, finished state and e2e on the real window over `tmp_path`; none uses the network. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | `mypy --strict` reports no issue; no `Any`. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | `dependencies` stays empty. |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | Reader and writer share `CSV_DELIMITER`, `CSV_ENCODING` and the row width in `csv_word_list.py`; the removal rule is only in `Deck.remove`. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `lint-imports` reports `Layers point inward` kept; the `ProgressRepository` Protocol is in `domain`, its adapter in `infrastructure`. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | The use case depends on the Protocol and receives the adapter; the view model sequences two session calls only. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | New files are in the layer folders of the clean-architecture skill; tests in `unit`, `integration`, `e2e`. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | File and folder names follow the rule. |
+
+## Overall Verdict
+
+Go — every Mandatory criterion passes. Reviewed by AI as stand-in for S01; not independent of the author.
+
+Milestone MIL-005 Go criteria: 1 the 3 record example leaves the other two cards in order with the header (integration test); 2 a start uses the progress file when it exists and the word list otherwise (integration test); 3 the wrong button never writes (unit and e2e); 4 the last card known gives a finished state (unit); 5 a malformed progress file raises `VocabularyFormatError` and stays untouched (unit); 6 round trip readable as a word list (integration); 7 this record, `pytest` 107 passed. A manual run on a copy of `ms-da.csv` removed the known word and wrote 999 cards. Defect found and fixed in this milestone: a flaky `TclError` caused by pytest's descriptor capture and Tcl file handles; the view now loads image bytes with `Path.read_bytes()` and `PhotoImage(data=...)`. All Go.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| none | - | - |
+
+---
+
+[PY-MIL-005]: ../../../src/flash_card
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[8dbaaa3]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/8dbaaa30595a3650bc85006a2188f81ab903125e

docs/sqa/reviews/rc-028-py-mil-006.md

@@ -0,0 +1,64 @@
+# RC-028: Review of PY-MIL-006
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-028 |
+| CrossReference | [PY-MIL-006], [QC-PY-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [b3c5116] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [PY-MIL-006]
+- Checklist used: [QC-PY-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Packages, modules, functions, variables, classes and constants follow PEP 8 casing (`snake_case`, `PascalCase`, `UPPER_SNAKE`) | Pass | PEP 8 casing holds; ruff rule set N passes. |
+| 2 | Names state purpose in the domain's language; no unexplained abbreviations, no single-letter names outside tiny scopes | Pass | Names are the DCD-001 IT terms (`SpeechPort`, `GttsSpeech`, `NullSpeech`, `build_speech`). |
+| 3 | Code is produced by the project's formatter and passes its linter with no unexplained suppressions | Pass | `ruff check` and `ruff format --check` pass on 55 files with no suppressions. |
+| 4 | Every function and method signature is type-annotated, including `-> None` | Pass | Every signature is annotated; `mypy --strict` passes on 38 source files; third-party modules are imported with `importlib.import_module`, so no `type: ignore` is needed. |
+| 5 | No bare `except:`, no swallowed exceptions; specific exceptions are raised and the cause is kept (`raise ... from`) | Pass | The one broad `except Exception` in `GttsSpeech` is at the thread boundary, is commented, and logs with `exc_info`; it is not silent. No bare `except`. |
+| 6 | No mutable default arguments and no shadowed builtins | Pass | No mutable defaults, no builtin shadowed. |
+| 7 | Files, locks and connections are managed with context managers | Pass | Audio is written to a `tempfile.TemporaryDirectory` used as a context manager, so the file is always removed. |
+| 8 | Public modules, classes and functions have docstrings that say what, not how | Pass | New members have Doxygen docstrings; `doxygen Doxyfile` ends with 0 warnings. |
+| 9 | Logging uses `logging`, not `print`; no secrets or personal data in log output | Pass | Failures are logged with `logging`, not printed; only the spoken text (a word) is in the log context, no personal data. |
+| 10 | Classes and operations trace to the Design Class Diagram they implement; deviations are recorded | Pass | `SpeechPort`, `GttsSpeech`, `NullSpeech`, `open_study_session(vocabulary_repository, progress_repository, speech, choose)` and `build_speech` match DCD-001 and SD-001 (the `speak` message of `startStudySession` and `markUnknown`). |
+| 11 | Tests exist for new behaviour, are named for the behaviour, and do not depend on order or the network | Pass | 124 tests (3 consecutive runs green) with fakes for the synthesiser and player; no test uses the network or plays a sound. |
+| 12 | Type checker runs in strict mode without errors; `Any` is justified in a comment | Pass | `mypy --strict` reports no issue; no `Any`. |
+| 13 | Dependencies are declared and pinned in the project's dependency file, none unused | Pass | `dependencies` is still empty; the extra `speech` pins `playsound==1.2.2` and `gTTS>=2.5`, and no module imports them outside `GttsSpeech`. |
+| 14 | Each piece of knowledge (a business rule, constant, format, validation or query) is defined in one place; code is merged only where it expresses the same knowledge, not where it merely looks alike | Pass | The speak rule is only in `StudySession.next_card`; the unused `SPEECH_LANGUAGE_CODE` constant was removed. |
+| 15 | Imports point inward: business-rule modules import no framework, database, UI or delivery-mechanism code, and there are no import cycles | Pass | `lint-imports` reports `Layers point inward` kept; the port is in `application`, the adapters in `infrastructure`, the choice in the composition root. |
+| 16 | SOLID holds: a class or module has one reason to change; new behaviour is added by extension, not by editing a type test in several places; subclasses honour the contract of their base; protocols are narrow; high-level code depends on protocols or abstract types and receives its implementations | Pass | `StudySession` depends on the `SpeechPort` Protocol and receives the adapter; `NullSpeech` honours the same contract (Null Object), so no `if speech` test exists. |
+| 17 | Source is laid out in the layers and folders of the clean architecture folder structure (`domain`, `application`, `infrastructure`, `presentation` packages under `src/`, and `unit`, `integration` and `e2e` under `tests/`), in `snake_case`, and imports between the layers point inward | Pass | `application/ports/` and `infrastructure/speech/` follow the folder structure of the clean-architecture skill. |
+| 18 | File and folder names are English, contain no space and no character outside letters, digits, `-`, `_` and `.`, and follow the casing of the language for files | Pass | File and folder names follow the rule. |
+
+## Overall Verdict
+
+Go — every Mandatory criterion passes. Reviewed by AI as stand-in for S01; not independent of the author.
+
+Milestone MIL-006 Go criteria: 1 `speak(text, front_code)` once per drawn card and never when empty (unit tests); 2 `gtts` and `playsound` imported only when speaking, temporary file removed (unit tests with fakes); 3 service or player failure is logged and not raised (unit tests with caplog); 4 `build_speech` returns `NullSpeech` when the extra is missing or `--no-speech` is given (unit tests); 5 `dependencies` empty, extra pins `playsound==1.2.2` (pyproject.toml); 6 `speak` returns before a blocked player is released (unit test with an Event); 7 this record, `pytest` 124 passed. A manual check with the extra installed synthesised an mp3 of `kata` in Malay (7872 bytes) and `build_speech(True)` returned `GttsSpeech`; the audio was not played on this machine. All Go.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| none | - | - |
+
+---
+
+[PY-MIL-006]: ../../../src/flash_card
+[QC-PY-001]: ../../../framework/qc/code/qc-programming-python.md
+[b3c5116]: https://git.tirsystem.com/Tirsvad-Udemy-100-days-of-code/031-flash-card/commit/b3c51161107b4cdcbc4c5334e28608423a299638

docs/sqa/traceability-matrix.md

@@ -48,6 +48,9 @@ updated whenever an artifact instance is created or reviewed.
 | PY-MIL-001 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-023] |
 | PY-MIL-002 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-024] |
 | PY-MIL-003 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-025] |
+| PY-MIL-004 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-026] |
+| PY-MIL-005 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-027] |
+| PY-MIL-006 | Python Source Code | - | - | DCD-001, ADR-0002 | - | [RC-028] |
 
 ## Coverage Notes
 
@@ -108,3 +111,9 @@ updated whenever an artifact instance is created or reviewed.
 [PY-MIL-002]: ../../src/flash_card
 [RC-025]: ./reviews/rc-025-py-mil-003.md
 [PY-MIL-003]: ../../src/flash_card
+[RC-026]: ./reviews/rc-026-py-mil-004.md
+[PY-MIL-004]: ../../src/flash_card
+[RC-027]: ./reviews/rc-027-py-mil-005.md
+[PY-MIL-005]: ../../src/flash_card
+[RC-028]: ./reviews/rc-028-py-mil-006.md
+[PY-MIL-006]: ../../src/flash_card

pyproject.toml

@@ -45,6 +45,9 @@ line-length = 88
 target-version = "py313"
 src = ["src", "tests"]
 
+[tool.ruff.format]
+line-ending = "lf"
+
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "N", "D"]
 ignore = ["D203", "D213"]

src/flash_card/application/ports/__init__.py

@@ -0,0 +1,5 @@
+"""Ports of the application layer.
+
+@file __init__.py
+@brief Holds the interfaces the use cases need from outside.
+"""

src/flash_card/application/ports/speech_port.py

@@ -0,0 +1,22 @@
+"""Port for spoken words.
+
+@file speech_port.py
+@brief The SpeechPort interface the study session uses to say a word aloud.
+"""
+
+from typing import Protocol
+
+
+class SpeechPort(Protocol):
+    """Speaks a text aloud in a language."""
+
+    def speak(self, text: str, language_code: str) -> None:
+        """Speak a text without blocking the caller for long.
+
+        An implementation does not raise: a failure is logged and ignored.
+
+        @param text The text to speak.
+        @param language_code Language of the text, for example "ms".
+        @return Nothing.
+        """
+        ...

src/flash_card/application/use_cases/open_study_session.py

@@ -6,22 +6,31 @@
 
 from collections.abc import Callable, Sequence
 
+from flash_card.application.ports.speech_port import SpeechPort
 from flash_card.application.use_cases.study_session import StudySession
 from flash_card.domain.entities.card import Card
 from flash_card.domain.entities.deck import Deck
+from flash_card.domain.repositories.progress_repository import ProgressRepository
 from flash_card.domain.repositories.vocabulary_repository import VocabularyRepository
 
 
 def open_study_session(
     vocabulary_repository: VocabularyRepository,
+    progress_repository: ProgressRepository,
+    speech: SpeechPort,
     choose: Callable[[Sequence[Card]], Card],
 ) -> StudySession:
-    """Load the word list and build a session over all its cards.
+    """Build a session over the saved words to learn, else the whole word list.
 
-    @param vocabulary_repository Source of the word list.
+    @param vocabulary_repository Source of the delivered word list.
+    @param progress_repository Store of the words still to learn.
+    @param speech Speaks the front text of each drawn card.
     @param choose Picks one card from a non-empty sequence.
     @return The new session.
-    @throws VocabularyError When the word list cannot be loaded.
+    @throws VocabularyError When the saved progress, or the word list when no
+        progress exists, cannot be loaded.
     """
+    deck = progress_repository.load()
+    if deck is None:
         deck = Deck.from_vocabulary(vocabulary_repository.load())
-    return StudySession(deck, choose)
+    return StudySession(deck, choose, progress_repository, speech)

src/flash_card/application/use_cases/study_session.py

@@ -7,19 +7,33 @@
 from collections.abc import Callable, Sequence
 
 from flash_card.application.dto.card_dto import CardDto
+from flash_card.application.ports.speech_port import SpeechPort
 from flash_card.domain.entities.card import Card
 from flash_card.domain.entities.deck import Deck
+from flash_card.domain.repositories.progress_repository import ProgressRepository
 
 
 class StudySession:
     """Draws cards from a deck, one after another."""
 
-    def __init__(self, deck: Deck, choose: Callable[[Sequence[Card]], Card]) -> None:
+    def __init__(
+        self,
+        deck: Deck,
+        choose: Callable[[Sequence[Card]], Card],
+        progress: ProgressRepository,
+        speech: SpeechPort,
+    ) -> None:
         """Create a session.
 
         @param deck The cards still to learn.
         @param choose Picks one card from a non-empty sequence.
+        @param progress Store of the words still to learn.
+        @param speech Speaks the front text of each drawn card.
         """
+        ## @brief Speaks the front text of each drawn card.
+        self._speech = speech
+        ## @brief Store of the words still to learn.
+        self._progress = progress
         ## @brief The cards still to learn.
         self._deck = deck
         ## @brief Picks one card from a non-empty sequence.
@@ -51,8 +65,23 @@ class StudySession:
         if self._deck.is_empty:
             self._current = None
             return None
-        self._current = self._deck.draw(self._choose, exclude=self._current)
+        card = self._deck.draw(self._choose, exclude=self._current)
-        return self._to_dto(self._current)
+        self._current = card
+        self._speech.speak(card.front, self._deck.language_pair.front_code)
+        return self._to_dto(card)
+
+    def mark_known(self) -> None:
+        """Remove the current card from the deck and save the remaining cards.
+
+        Does nothing and saves nothing when no card is shown.
+
+        @return Nothing.
+        """
+        if self._current is None:
+            return
+        self._deck.remove(self._current)
+        self._progress.save(self._deck)
+        self._current = None
 
     def _to_dto(self, card: Card | None) -> CardDto | None:
         """Map a card to its DTO.

src/flash_card/constants.py

@@ -51,8 +51,6 @@ CSV_ENCODING: Final[str] = "utf-8-sig"
 VOCABULARY_FILE_NAME: Final[str] = "ms-da.csv"
 ## @brief File name of the words still to learn.
 PROGRESS_FILE_NAME: Final[str] = "words_to_learn.csv"
-## @brief Language code used for speech.
-SPEECH_LANGUAGE_CODE: Final[str] = "ms"
 
 ## @brief Root folder of the project.
 PROJECT_ROOT: Final[Path] = Path(__file__).resolve().parents[2]

src/flash_card/domain/repositories/progress_repository.py

@@ -0,0 +1,29 @@
+"""Port to the words still to learn.
+
+@file progress_repository.py
+@brief The ProgressRepository interface.
+"""
+
+from typing import Protocol
+
+from flash_card.domain.entities.deck import Deck
+
+
+class ProgressRepository(Protocol):
+    """Store of the words still to learn."""
+
+    def load(self) -> Deck | None:
+        """Load the saved words to learn.
+
+        @return The deck, or None when no progress was saved.
+        @throws VocabularyError When the saved progress is unusable.
+        """
+        ...
+
+    def save(self, deck: Deck) -> None:
+        """Save the words still to learn.
+
+        @param deck The cards still to learn.
+        @return Nothing.
+        """
+        ...

src/flash_card/infrastructure/persistence/csv_progress_repository.py

@@ -0,0 +1,44 @@
+"""CSV implementation of the progress port.
+
+@file csv_progress_repository.py
+@brief The CsvProgressRepository adapter.
+"""
+
+from pathlib import Path
+
+from flash_card.domain.entities.deck import Deck
+from flash_card.infrastructure.persistence.csv_word_list import (
+    read_word_list,
+    write_word_list,
+)
+
+
+class CsvProgressRepository:
+    """Keeps the words still to learn in a CSV file."""
+
+    def __init__(self, path: Path) -> None:
+        """Create the repository.
+
+        @param path The words to learn file.
+        """
+        ## @brief The words to learn file.
+        self._path = path
+
+    def load(self) -> Deck | None:
+        """Load the saved words to learn.
+
+        @return The deck, possibly empty, or None when the file does not exist.
+        @throws VocabularyFormatError When the file is malformed; it is left as is.
+        """
+        if not self._path.exists():
+            return None
+        pair, cards = read_word_list(self._path)
+        return Deck(pair, cards)
+
+    def save(self, deck: Deck) -> None:
+        """Save the words still to learn.
+
+        @param deck The cards still to learn.
+        @return Nothing.
+        """
+        write_word_list(self._path, deck.language_pair, deck.cards)

src/flash_card/infrastructure/persistence/csv_word_list.py

@@ -1,10 +1,12 @@
-"""Reading of the word list CSV file.
+"""Reading and writing of the word list CSV file.
 
 @file csv_word_list.py
-@brief Reads a semicolon separated word list with a language code header.
+@brief Reads and writes a semicolon separated word list with a language code
+header; the format is defined once here.
 """
 
 import csv
+from collections.abc import Iterable
 from pathlib import Path
 
 from flash_card.constants import CSV_DELIMITER, CSV_ENCODING
@@ -84,3 +86,31 @@ def read_word_list(path: Path) -> tuple[LanguagePair, tuple[Card, ...]]:
     if pair is None:
         raise _format_error(path, 1, "file is empty")
     return pair, tuple(cards)
+
+
+def write_word_list(
+    path: Path, language_pair: LanguagePair, cards: Iterable[Card]
+) -> None:
+    """Write a word list file atomically.
+
+    The rows go to a temporary file in the same folder, which then replaces the
+    target, so a crash never leaves a half written file.
+
+    @param path The CSV file to create or replace.
+    @param language_pair The languages, written as the header row.
+    @param cards The cards, written one row each in the given order.
+    @return Nothing.
+    @throws OSError When the file cannot be written.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + ".tmp")
+    rows = [(language_pair.front_code, language_pair.back_code)]
+    rows.extend((card.front, card.back) for card in cards)
+    try:
+        with temporary.open("w", encoding=CSV_ENCODING, newline="") as file:
+            writer = csv.writer(file, delimiter=CSV_DELIMITER, lineterminator="\n")
+            writer.writerows(rows)
+        temporary.replace(path)
+    except BaseException:
+        temporary.unlink(missing_ok=True)
+        raise

src/flash_card/infrastructure/speech/__init__.py

@@ -0,0 +1,5 @@
+"""Speech adapters.
+
+@file __init__.py
+@brief Holds the implementations of the speech port.
+"""

src/flash_card/infrastructure/speech/gtts_speech.py

@@ -0,0 +1,108 @@
+"""Speech adapter over the gTTS service.
+
+@file gtts_speech.py
+@brief GttsSpeech, the SpeechPort that synthesises with gTTS and plays the file.
+The packages gtts and playsound are optional and imported only when used.
+"""
+
+import importlib
+import logging
+import tempfile
+import threading
+from collections.abc import Callable
+from pathlib import Path
+
+## @brief Logger of the speech adapter.
+_logger = logging.getLogger(__name__)
+
+## @brief File name of the synthesised speech inside the temporary folder.
+_SPEECH_FILE_NAME = "speech.mp3"
+
+## @brief Writes an mp3 of a text and language to a path.
+Synthesize = Callable[[str, str, Path], None]
+## @brief Plays an audio file.
+Play = Callable[[Path], None]
+
+
+def _default_synthesize(text: str, language_code: str, path: Path) -> None:
+    """Write an mp3 of the text with gTTS.
+
+    @param text The text to speak.
+    @param language_code Language of the text.
+    @param path File to write.
+    @return Nothing.
+    @throws ImportError When the gtts package is not installed.
+    """
+    # Imported by name so the program starts without the optional extra.
+    module = importlib.import_module("gtts")
+    module.gTTS(text=text, lang=language_code).save(str(path))
+
+
+def _default_play(path: Path) -> None:
+    """Play an audio file and wait until it has been played.
+
+    @param path File to play.
+    @return Nothing.
+    @throws ImportError When the playsound package is not installed.
+    """
+    # Imported by name so the program starts without the optional extra.
+    module = importlib.import_module("playsound")
+    module.playsound(str(path))
+
+
+class GttsSpeech:
+    """Speaks a text in a background thread; never raises."""
+
+    def __init__(
+        self,
+        synthesize: Synthesize | None = None,
+        play: Play | None = None,
+    ) -> None:
+        """Create the adapter.
+
+        @param synthesize Writes an mp3 of a text and language to a path, or
+            None for gTTS.
+        @param play Plays an audio file, or None for playsound.
+        """
+        ## @brief Writes the audio file.
+        self._synthesize = _default_synthesize if synthesize is None else synthesize
+        ## @brief Plays the audio file.
+        self._play = _default_play if play is None else play
+        ## @brief The thread of the latest speak call, or None.
+        self._thread: threading.Thread | None = None
+
+    def speak(self, text: str, language_code: str) -> None:
+        """Start speaking and return at once.
+
+        @param text The text to speak.
+        @param language_code Language of the text.
+        @return Nothing.
+        """
+        thread = threading.Thread(
+            target=self._run, args=(text, language_code), daemon=True
+        )
+        self._thread = thread
+        thread.start()
+
+    def wait(self) -> None:
+        """Block until the latest speech has ended.
+
+        @return Nothing.
+        """
+        if self._thread is not None:
+            self._thread.join()
+
+    def _run(self, text: str, language_code: str) -> None:
+        """Synthesise and play in a temporary folder, then remove the file.
+
+        @param text The text to speak.
+        @param language_code Language of the text.
+        @return Nothing.
+        """
+        try:
+            with tempfile.TemporaryDirectory() as folder:
+                path = Path(folder) / _SPEECH_FILE_NAME
+                self._synthesize(text, language_code, path)
+                self._play(path)
+        except Exception:  # thread boundary: speech must never crash the program
+            _logger.warning("Speech failed for %r", text, exc_info=True)

src/flash_card/infrastructure/speech/null_speech.py

@@ -0,0 +1,18 @@
+"""Silent speech adapter.
+
+@file null_speech.py
+@brief NullSpeech, the SpeechPort used when speech is off or unavailable.
+"""
+
+
+class NullSpeech:
+    """Speaks nothing."""
+
+    def speak(self, text: str, language_code: str) -> None:
+        """Do nothing.
+
+        @param text The text, ignored.
+        @param language_code The language, ignored.
+        @return Nothing.
+        """
+        return None

src/flash_card/presentation/app.py

@@ -5,6 +5,7 @@
 """
 
 import argparse
+import importlib.util
 import logging
 import random
 import tkinter as tk
@@ -12,12 +13,22 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import NoReturn
 
+from flash_card.application.ports.speech_port import SpeechPort
 from flash_card.application.use_cases.open_study_session import open_study_session
-from flash_card.constants import DEFAULT_DATA_DIR, VOCABULARY_FILE_NAME
+from flash_card.constants import (
+    DEFAULT_DATA_DIR,
+    PROGRESS_FILE_NAME,
+    VOCABULARY_FILE_NAME,
+)
 from flash_card.domain.errors.vocabulary_errors import VocabularyError
+from flash_card.infrastructure.persistence.csv_progress_repository import (
+    CsvProgressRepository,
+)
 from flash_card.infrastructure.persistence.csv_vocabulary_repository import (
     CsvVocabularyRepository,
 )
+from flash_card.infrastructure.speech.gtts_speech import GttsSpeech
+from flash_card.infrastructure.speech.null_speech import NullSpeech
 from flash_card.presentation.features.flash_card.flash_card_view import FlashCardView
 from flash_card.presentation.features.flash_card.flash_card_view_model import (
     FlashCardViewModel,
@@ -26,19 +37,40 @@ from flash_card.presentation.features.flash_card.flash_card_view_model import (
 ## @brief Logger of the entry point.
 _logger = logging.getLogger(__name__)
 
+## @brief Optional packages the spoken words need.
+_SPEECH_PACKAGES = ("gtts", "playsound")
+
+
+def build_speech(enabled: bool) -> SpeechPort:
+    """Choose the speech adapter.
+
+    @param enabled False when the user switched speech off.
+    @return GttsSpeech when enabled and gtts and playsound are installed,
+        else NullSpeech.
+    """
+    if enabled and all(
+        importlib.util.find_spec(name) is not None for name in _SPEECH_PACKAGES
+    ):
+        return GttsSpeech()
+    return NullSpeech()
+
 
 def create_application(
     data_dir: Path | None = None,
+    speech_enabled: bool = True,
 ) -> tuple[tk.Tk, FlashCardView]:
     """Create the root window and the flash card view.
 
     @param data_dir Folder of the data files, or None for the default folder.
+    @param speech_enabled False to run without spoken words.
     @return The root window and the view built on it.
-    @throws VocabularyError When the word list cannot be loaded.
+    @throws VocabularyError When the word list or saved progress is unusable.
     """
     folder = DEFAULT_DATA_DIR if data_dir is None else data_dir
     repository = CsvVocabularyRepository(folder / VOCABULARY_FILE_NAME)
-    session = open_study_session(repository, random.choice)
+    progress = CsvProgressRepository(folder / PROGRESS_FILE_NAME)
+    speech = build_speech(speech_enabled)
+    session = open_study_session(repository, progress, speech, random.choice)
     view_model = FlashCardViewModel(session)
     root = tk.Tk()
     view = FlashCardView(root, view_model)
@@ -58,9 +90,14 @@ def main(argv: Sequence[str] | None = None) -> int:
         default=DEFAULT_DATA_DIR,
         help="folder of the data files",
     )
+    parser.add_argument(
+        "--no-speech",
+        action="store_true",
+        help="do not speak the words",
+    )
     args = parser.parse_args(argv)
     try:
-        root, _view = create_application(args.data_dir)
+        root, _view = create_application(args.data_dir, not args.no_speech)
     except VocabularyError as error:
         _logger.error("%s", error)
         return 1

src/flash_card/presentation/features/flash_card/flash_card_view.py

@@ -8,11 +8,14 @@ import tkinter as tk
 
 from flash_card.constants import (
     ASSETS_DIR,
+    BACK_TEXT_COLOR,
     BACKGROUND_COLOR,
+    CARD_BACK_IMAGE_NAME,
     CARD_CENTER_X,
     CARD_FRONT_IMAGE_NAME,
     CARD_HEIGHT,
     CARD_WIDTH,
+    FLIP_DELAY_MS,
     FRONT_TEXT_COLOR,
     LANGUAGE_FONT,
     LANGUAGE_TEXT_Y,
@@ -25,9 +28,25 @@ from flash_card.constants import (
 )
 from flash_card.presentation.features.flash_card.flash_card_view_model import (
     FlashCardViewModel,
+    Side,
 )
 
 
+def _load_image(root: tk.Tk, name: str) -> tk.PhotoImage:
+    """Load an asset image.
+
+    The bytes are read here and handed to Tk as data, so the image does not
+    depend on Tcl opening the file: Tcl keeps the standard handles it saw at
+    start, and a process that swaps them (pytest fd capture) makes the first
+    Tcl file open fail with an empty error.
+
+    @param root The Tk root window that owns the image.
+    @param name The file name in the assets folder.
+    @return The image; the caller must keep a reference.
+    """
+    return tk.PhotoImage(master=root, data=(ASSETS_DIR / name).read_bytes())
+
+
 class FlashCardView:
     """The flash card window: a card and the wrong and right buttons."""
 
@@ -46,11 +65,13 @@ class FlashCardView:
 
         # Kept as attributes: Tkinter drops an image nothing refers to.
         ## @brief Card front image, kept so Tk does not drop it.
-        self._card_front_image = tk.PhotoImage(file=ASSETS_DIR / CARD_FRONT_IMAGE_NAME)
+        self._card_front_image = _load_image(root, CARD_FRONT_IMAGE_NAME)
+        ## @brief Card back image, kept so Tk does not drop it.
+        self._card_back_image = _load_image(root, CARD_BACK_IMAGE_NAME)
         ## @brief Wrong button image, kept so Tk does not drop it.
-        self._wrong_image = tk.PhotoImage(file=ASSETS_DIR / WRONG_IMAGE_NAME)
+        self._wrong_image = _load_image(root, WRONG_IMAGE_NAME)
         ## @brief Right button image, kept so Tk does not drop it.
-        self._right_image = tk.PhotoImage(file=ASSETS_DIR / RIGHT_IMAGE_NAME)
+        self._right_image = _load_image(root, RIGHT_IMAGE_NAME)
 
         ## @brief Canvas that draws the card.
         self.canvas = tk.Canvas(
@@ -97,17 +118,89 @@ class FlashCardView:
             image=self._right_image,
             highlightthickness=0,
             bd=0,
-            command=self.next_card,
+            command=self.is_known,
         )
         self.right_button.grid(row=1, column=1)
 
+        ## @brief Id of the pending flip timer, or None when none is pending.
+        self.flip_timer: str | None = None
+        self._start_flip_timer()
+
+    @property
+    def card_front_image(self) -> tk.PhotoImage:
+        """Return the card front image.
+
+        @return The image shown while the front side is up.
+        """
+        return self._card_front_image
+
+    @property
+    def card_back_image(self) -> tk.PhotoImage:
+        """Return the card back image.
+
+        @return The image shown while the back side is up.
+        """
+        return self._card_back_image
+
     def next_card(self) -> None:
-        """Show the next card.
+        """Show the next card front and restart the flip timer.
 
         @return Nothing.
         """
+        self._cancel_flip_timer()
         self._view_model.next_card()
+        self._show_card()
+        self._start_flip_timer()
+
+    def is_known(self) -> None:
+        """Mark the card as known, show the next card front, restart the timer.
+
+        @return Nothing.
+        """
+        self._cancel_flip_timer()
+        self._view_model.is_known()
+        self._show_card()
+        self._start_flip_timer()
+
+    def flip_card(self) -> None:
+        """Show the back of the current card.
+
+        @return Nothing.
+        """
+        self._cancel_flip_timer()
+        self._view_model.flip_card()
+        self._show_card()
+
+    def _cancel_flip_timer(self) -> None:
+        """Cancel the pending flip timer, if any.
+
+        @return Nothing.
+        """
+        if self.flip_timer is not None:
+            self._root.after_cancel(self.flip_timer)
+            self.flip_timer = None
+
+    def _start_flip_timer(self) -> None:
+        """Schedule the flip unless no card is left.
+
+        @return Nothing.
+        """
+        if not self._view_model.is_finished:
+            self.flip_timer = self._root.after(FLIP_DELAY_MS, self.flip_card)
+
+    def _show_card(self) -> None:
+        """Draw image and texts of the side the view model shows.
+
+        @return Nothing.
+        """
+        if self._view_model.side is Side.BACK:
+            image, color = self._card_back_image, BACK_TEXT_COLOR
+        else:
+            image, color = self._card_front_image, FRONT_TEXT_COLOR
+        self.canvas.itemconfig(self.image_id, image=image)
         self.canvas.itemconfig(
-            self.language_text_id, text=self._view_model.language_name
+            self.language_text_id, text=self._view_model.language_name, fill=color
+        )
+        self.canvas.itemconfig(
+            self.word_text_id, text=self._view_model.text, fill=color
         )
-        self.canvas.itemconfig(self.word_text_id, text=self._view_model.text)

src/flash_card/presentation/features/flash_card/flash_card_view_model.py

@@ -4,6 +4,7 @@
 @brief Exposes the texts shown on the card; free of any Tkinter import.
 """
 
+import enum
 from collections.abc import Mapping
 
 from flash_card.application.dto.card_dto import CardDto
@@ -11,6 +12,15 @@ from flash_card.application.use_cases.study_session import StudySession
 from flash_card.constants import FINISHED_MESSAGE, LANGUAGE_NAMES
 
 
+class Side(enum.Enum):
+    """The side of a card that is shown."""
+
+    ## @brief The front: the word to learn.
+    FRONT = enum.auto()
+    ## @brief The back: the translation.
+    BACK = enum.auto()
+
+
 class FlashCardViewModel:
     """Data the flash card view shows."""
 
@@ -30,6 +40,8 @@ class FlashCardViewModel:
         self._language_names = language_names
         ## @brief The card shown now, or None when none is left.
         self._card: CardDto | None = session.next_card()
+        ## @brief The side of the card shown.
+        self._side = Side.FRONT
 
     @property
     def is_finished(self) -> bool:
@@ -39,15 +51,26 @@ class FlashCardViewModel:
         """
         return self._card is None
 
+    @property
+    def side(self) -> Side:
+        """Return the side of the card shown.
+
+        @return FRONT or BACK; FRONT when no card is left.
+        """
+        return self._side
+
     @property
     def language_name(self) -> str:
         """Return the language name shown on the card.
 
-        @return The display name of the front language, upper case code when
+        @return The display name of the language of the side shown, upper case
-            unknown, or an empty string when no card is left.
+            code when unknown, or an empty string when no card is left.
         """
         if self._card is None:
             return ""
+        if self._side is Side.BACK:
+            code = self._card.back_language
+        else:
             code = self._card.front_language
         return self._language_names.get(code, code.upper())
 
@@ -55,15 +78,42 @@ class FlashCardViewModel:
     def text(self) -> str:
         """Return the word shown on the card.
 
-        @return The front text, or the finished message when no card is left.
+        @return The text of the side shown, or the finished message when no
+            card is left.
         """
         if self._card is None:
             return FINISHED_MESSAGE
+        if self._side is Side.BACK:
+            return self._card.back_text
         return self._card.front_text
 
     def next_card(self) -> None:
-        """Draw the next card.
+        """Draw the next card and show its front; does nothing when finished.
 
         @return Nothing.
         """
+        if self._card is None:
+            return
         self._card = self._session.next_card()
+        self._side = Side.FRONT
+
+    def is_known(self) -> None:
+        """Mark the card as known, save the progress and show the next card.
+
+        Does nothing when finished.
+
+        @return Nothing.
+        """
+        if self._card is None:
+            return
+        self._session.mark_known()
+        self._card = self._session.next_card()
+        self._side = Side.FRONT
+
+    def flip_card(self) -> None:
+        """Show the back of the card; does nothing when finished or flipped.
+
+        @return Nothing.
+        """
+        if self._card is not None:
+            self._side = Side.BACK

tests/e2e/test_flash_card_window.py

@@ -4,16 +4,22 @@
 @brief Builds the real window with Tk and checks it against the wireframe.
 """
 
+import time
 import tkinter as tk
-from collections.abc import Iterator, Sequence
+from collections.abc import Callable, Iterator, Sequence
+from pathlib import Path
 
 import pytest
 
+from flash_card.application.use_cases.open_study_session import open_study_session
 from flash_card.application.use_cases.study_session import StudySession
 from flash_card.constants import (
+    BACK_TEXT_COLOR,
     BACKGROUND_COLOR,
     CARD_HEIGHT,
     CARD_WIDTH,
+    FINISHED_MESSAGE,
+    FLIP_DELAY_MS,
     FRONT_TEXT_COLOR,
     LANGUAGE_FONT,
     WINDOW_PADDING,
@@ -23,6 +29,14 @@ from flash_card.constants import (
 from flash_card.domain.entities.card import Card
 from flash_card.domain.entities.deck import Deck
 from flash_card.domain.value_objects.language_pair import LanguagePair
+from flash_card.infrastructure.persistence.csv_progress_repository import (
+    CsvProgressRepository,
+)
+from flash_card.infrastructure.persistence.csv_vocabulary_repository import (
+    CsvVocabularyRepository,
+)
+from flash_card.infrastructure.speech.null_speech import NullSpeech
+from flash_card.presentation.features.flash_card import flash_card_view
 from flash_card.presentation.features.flash_card.flash_card_view import FlashCardView
 from flash_card.presentation.features.flash_card.flash_card_view_model import (
     FlashCardViewModel,
@@ -35,9 +49,33 @@ def _first(cards: Sequence[Card]) -> Card:
     return cards[0]
 
 
+class _MemoryProgress:
+    """Progress store that keeps nothing: the shared window never deletes cards."""
+
+    def load(self) -> Deck | None:
+        return None
+
+    def save(self, deck: Deck) -> None:
+        return None
+
+
+class _RecordingSpeech:
+    """Speech port that records what would have been spoken."""
+
+    def __init__(self) -> None:
+        self.spoken: list[tuple[str, str]] = []
+
+    def speak(self, text: str, language_code: str) -> None:
+        self.spoken.append((text, language_code))
+
+
+SPEECH = _RecordingSpeech()
+
+
 def _build_view(root: tk.Tk) -> FlashCardView:
     deck = Deck(LanguagePair("ms", "da"), CARDS)
-    return FlashCardView(root, FlashCardViewModel(StudySession(deck, _first)))
+    session = StudySession(deck, _first, _MemoryProgress(), SPEECH)
+    return FlashCardView(root, FlashCardViewModel(session))
 
 
 def _shown(view: FlashCardView) -> tuple[str, str]:
@@ -125,12 +163,194 @@ def test_buttons_sit_in_row_one_with_their_images(
     assert str(view.right_button.cget("command"))
 
 
-def test_each_button_press_shows_next_card(
+def test_wrong_button_press_shows_next_card(
     window: tuple[tk.Tk, FlashCardView],
 ) -> None:
     _root, view = window
     assert _shown(view) == ("Malay", "aku")
     view.wrong_button.invoke()
     assert _shown(view) == ("Malay", "kau")
-    view.right_button.invoke()
+    view.wrong_button.invoke()
     assert _shown(view) == ("Malay", "aku")
+
+
+def _word(view: FlashCardView) -> str:
+    return _shown(view)[1]
+
+
+def _image(view: FlashCardView) -> str:
+    return str(view.canvas.itemcget(view.image_id, "image"))
+
+
+def _fill(view: FlashCardView) -> tuple[str, str]:
+    return (
+        str(view.canvas.itemcget(view.language_text_id, "fill")),
+        str(view.canvas.itemcget(view.word_text_id, "fill")),
+    )
+
+
+def _reset(root: tk.Tk, view: FlashCardView) -> None:
+    """Show a fresh front with no pending timer."""
+    view.next_card()
+    if view.flip_timer is not None:
+        root.after_cancel(view.flip_timer)
+        view.flip_timer = None
+
+
+def test_front_state_uses_front_image_black_text_and_front_language(
+    window: tuple[tk.Tk, FlashCardView],
+) -> None:
+    root, view = window
+    _reset(root, view)
+    assert _image(view) == str(view.card_front_image)
+    assert _fill(view) == (FRONT_TEXT_COLOR, FRONT_TEXT_COLOR)
+    assert _shown(view)[0] == "Malay"
+    assert _word(view) in {card.front for card in CARDS}
+
+
+def test_flip_card_shows_back_image_white_text_and_translation(
+    window: tuple[tk.Tk, FlashCardView],
+) -> None:
+    root, view = window
+    _reset(root, view)
+    front = _word(view)
+    view.flip_card()
+    translations = {card.front: card.back for card in CARDS}
+    assert _image(view) == str(view.card_back_image)
+    assert _image(view) != str(view.card_front_image)
+    assert _fill(view) == (BACK_TEXT_COLOR, BACK_TEXT_COLOR)
+    assert _shown(view) == ("Danish", translations[front])
+    assert view.flip_timer is None
+
+
+def test_next_card_after_flip_shows_front_again(
+    window: tuple[tk.Tk, FlashCardView],
+) -> None:
+    root, view = window
+    _reset(root, view)
+    view.flip_card()
+    view.wrong_button.invoke()
+    assert _image(view) == str(view.card_front_image)
+    assert _fill(view) == (FRONT_TEXT_COLOR, FRONT_TEXT_COLOR)
+    assert _shown(view)[0] == "Malay"
+    _reset(root, view)
+
+
+def test_next_card_cancels_pending_timer_and_schedules_flip(
+    window: tuple[tk.Tk, FlashCardView],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    root, view = window
+    _reset(root, view)
+    calls: list[tuple[str, object]] = []
+
+    def fake_after(delay: int, callback: Callable[[], None]) -> str:
+        calls.append(("after", (delay, callback)))
+        return "timer-id"
+
+    def fake_cancel(timer_id: str) -> None:
+        calls.append(("cancel", timer_id))
+
+    monkeypatch.setattr(root, "after", fake_after, raising=False)
+    monkeypatch.setattr(root, "after_cancel", fake_cancel, raising=False)
+    view.flip_timer = "old-id"
+    view.next_card()
+    assert calls == [
+        ("cancel", "old-id"),
+        ("after", (FLIP_DELAY_MS, view.flip_card)),
+    ]
+    assert view.flip_timer == "timer-id"
+    view.flip_timer = None
+
+
+def test_real_timer_flips_card_after_delay(
+    window: tuple[tk.Tk, FlashCardView],
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    root, view = window
+    monkeypatch.setattr(flash_card_view, "FLIP_DELAY_MS", 50)
+    view.next_card()
+    assert _image(view) == str(view.card_front_image)
+    deadline = time.monotonic() + 2
+    while view.flip_timer is not None and time.monotonic() < deadline:
+        root.update()
+        time.sleep(0.005)
+    assert view.flip_timer is None
+    assert _image(view) == str(view.card_back_image)
+    assert _shown(view)[0] == "Danish"
+    _reset(root, view)
+
+
+HEADER_ONLY = "ms;da\n"
+
+
+@pytest.fixture
+def files_view(
+    window: tuple[tk.Tk, FlashCardView], tmp_path: Path
+) -> Iterator[tuple[FlashCardView, Path]]:
+    """A second view on the shared root, over real repositories in tmp_path."""
+    root, _shared = window
+    words = tmp_path / "words.csv"
+    words.write_text("ms;da\naku;mig\nkau;du\nini;denne\n", encoding="utf-8")
+    progress = tmp_path / "words_to_learn.csv"
+    session = open_study_session(
+        CsvVocabularyRepository(words),
+        CsvProgressRepository(progress),
+        NullSpeech(),
+        _first,
+    )
+    view = FlashCardView(root, FlashCardViewModel(session))
+    yield view, progress
+    if view.flip_timer is not None:
+        root.after_cancel(view.flip_timer)
+    for widget in (view.canvas, view.wrong_button, view.right_button):
+        widget.destroy()
+
+
+def _saved(progress: Path) -> str:
+    return progress.read_bytes().decode("utf-8-sig")
+
+
+def test_right_button_removes_card_and_writes_progress_file(
+    files_view: tuple[FlashCardView, Path],
+) -> None:
+    view, progress = files_view
+    assert _shown(view) == ("Malay", "aku")
+    view.right_button.invoke()
+    assert _shown(view) == ("Malay", "kau")
+    assert _saved(progress) == "ms;da\nkau;du\nini;denne\n"
+
+
+def test_wrong_button_shows_next_card_and_leaves_progress_file_absent(
+    files_view: tuple[FlashCardView, Path],
+) -> None:
+    view, progress = files_view
+    view.wrong_button.invoke()
+    assert _shown(view) == ("Malay", "kau")
+    assert not progress.exists()
+
+
+def test_buttons_do_nothing_visible_when_finished(
+    files_view: tuple[FlashCardView, Path],
+) -> None:
+    view, progress = files_view
+    for _ in range(3):
+        view.right_button.invoke()
+    assert _shown(view) == ("", FINISHED_MESSAGE)
+    assert view.flip_timer is None
+    assert _saved(progress) == HEADER_ONLY
+    view.right_button.invoke()
+    view.wrong_button.invoke()
+    assert _shown(view) == ("", FINISHED_MESSAGE)
+    assert view.flip_timer is None
+    assert _saved(progress) == HEADER_ONLY
+
+
+def test_button_press_speaks_the_malay_word_of_the_shown_card(
+    window: tuple[tk.Tk, FlashCardView],
+) -> None:
+    root, view = window
+    SPEECH.spoken.clear()
+    view.wrong_button.invoke()
+    assert SPEECH.spoken == [(_word(view), "ms")]
+    _reset(root, view)

tests/integration/test_progress_file.py

@@ -0,0 +1,98 @@
+"""Integration tests of saving and resuming progress over real CSV files."""
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from flash_card.application.use_cases.open_study_session import open_study_session
+from flash_card.application.use_cases.study_session import StudySession
+from flash_card.domain.entities.card import Card
+from flash_card.infrastructure.persistence.csv_progress_repository import (
+    CsvProgressRepository,
+)
+from flash_card.infrastructure.persistence.csv_vocabulary_repository import (
+    CsvVocabularyRepository,
+)
+from flash_card.infrastructure.speech.null_speech import NullSpeech
+
+WORDS = "fr;en\nchaque;each\nparlé;speak\narrivé;come\n"
+
+Choose = Callable[[Sequence[Card]], Card]
+
+
+def _first(cards: Sequence[Card]) -> Card:
+    return cards[0]
+
+
+def _choose_front(front: str) -> Choose:
+    def choose(cards: Sequence[Card]) -> Card:
+        return next(card for card in cards if card.front == front)
+
+    return choose
+
+
+def _open(folder: Path, choose: Choose = _first) -> StudySession:
+    return open_study_session(
+        CsvVocabularyRepository(folder / "words.csv"),
+        CsvProgressRepository(folder / "words_to_learn.csv"),
+        NullSpeech(),
+        choose,
+    )
+
+
+def _setup(folder: Path) -> Path:
+    (folder / "words.csv").write_text(WORDS, encoding="utf-8")
+    return folder / "words_to_learn.csv"
+
+
+def _text(path: Path) -> str:
+    return path.read_bytes().decode("utf-8-sig")
+
+
+def test_mark_known_writes_remaining_cards_in_order(tmp_path: Path) -> None:
+    progress = _setup(tmp_path)
+    session = _open(tmp_path, _choose_front("parlé"))
+    session.next_card()
+    session.mark_known()
+    assert _text(progress) == "fr;en\nchaque;each\narrivé;come\n"
+
+
+def test_restart_draws_only_from_progress_file(tmp_path: Path) -> None:
+    _setup(tmp_path)
+    first = _open(tmp_path, _choose_front("parlé"))
+    first.next_card()
+    first.mark_known()
+
+    second = _open(tmp_path)
+    fronts: set[str] = set()
+    for _ in range(6):
+        card = second.next_card()
+        assert card is not None
+        fronts.add(card.front_text)
+
+    assert second.remaining == 2
+    assert fronts == {"chaque", "arrivé"}
+
+
+def test_progress_file_is_readable_as_vocabulary(tmp_path: Path) -> None:
+    progress = _setup(tmp_path)
+    session = _open(tmp_path, _choose_front("chaque"))
+    session.next_card()
+    session.mark_known()
+    vocabulary = CsvVocabularyRepository(progress).load()
+    assert vocabulary.cards == (Card("parlé", "speak"), Card("arrivé", "come"))
+
+
+def test_header_only_progress_file_gives_finished_session(tmp_path: Path) -> None:
+    progress = _setup(tmp_path)
+    progress.write_text("fr;en\n", encoding="utf-8")
+    session = _open(tmp_path)
+    assert session.remaining == 0
+    assert session.next_card() is None
+
+
+def test_unknown_card_never_creates_progress_file(tmp_path: Path) -> None:
+    progress = _setup(tmp_path)
+    session = _open(tmp_path)
+    session.next_card()
+    session.next_card()
+    assert not progress.exists()

tests/integration/test_vocabulary_file.py

@@ -1,13 +1,23 @@
 """Integration tests of the word list reader on the delivered file."""
 
+from pathlib import Path
+
 from flash_card.application.use_cases.open_study_session import open_study_session
-from flash_card.constants import DEFAULT_DATA_DIR, VOCABULARY_FILE_NAME
+from flash_card.constants import (
+    DEFAULT_DATA_DIR,
+    PROGRESS_FILE_NAME,
+    VOCABULARY_FILE_NAME,
+)
 from flash_card.domain.entities.card import Card
 from flash_card.domain.value_objects.language_pair import LanguagePair
+from flash_card.infrastructure.persistence.csv_progress_repository import (
+    CsvProgressRepository,
+)
 from flash_card.infrastructure.persistence.csv_vocabulary_repository import (
     CsvVocabularyRepository,
 )
 from flash_card.infrastructure.persistence.csv_word_list import read_word_list
+from flash_card.infrastructure.speech.null_speech import NullSpeech
 
 PATH = DEFAULT_DATA_DIR / VOCABULARY_FILE_NAME
 
@@ -19,10 +29,13 @@ def test_read_word_list_reads_real_file() -> None:
     assert cards[0] == Card("aku", "mig")
 
 
-def test_open_study_session_yields_card_from_real_file() -> None:
+def test_open_study_session_yields_card_from_real_file(tmp_path: Path) -> None:
     repository = CsvVocabularyRepository(PATH)
     cards = repository.load().cards
-    session = open_study_session(repository, lambda candidates: candidates[0])
+    progress = CsvProgressRepository(tmp_path / PROGRESS_FILE_NAME)
+    session = open_study_session(
+        repository, progress, NullSpeech(), lambda candidates: candidates[0]
+    )
 
     card = session.next_card()
 

tests/unit/application/test_open_study_session.py

@@ -7,6 +7,7 @@ import pytest
 from flash_card.application.dto.card_dto import CardDto
 from flash_card.application.use_cases.open_study_session import open_study_session
 from flash_card.domain.entities.card import Card
+from flash_card.domain.entities.deck import Deck
 from flash_card.domain.entities.vocabulary import Vocabulary
 from flash_card.domain.errors.vocabulary_errors import VocabularyNotFoundError
 from flash_card.domain.value_objects.language_pair import LanguagePair
@@ -20,6 +21,23 @@ class _FakeRepository:
         return self._vocabulary
 
 
+class _RecordingProgress:
+    def __init__(self, stored: Deck | None = None) -> None:
+        self.stored = stored
+        self.saved: list[tuple[Card, ...]] = []
+
+    def load(self) -> Deck | None:
+        return self.stored
+
+    def save(self, deck: Deck) -> None:
+        self.saved.append(deck.cards)
+
+
+class _SilentSpeech:
+    def speak(self, text: str, language_code: str) -> None:
+        return None
+
+
 class _MissingRepository:
     def load(self) -> Vocabulary:
         raise VocabularyNotFoundError("missing")
@@ -33,7 +51,9 @@ def test_open_study_session_builds_session_over_all_cards() -> None:
     cards = (Card("aku", "mig"), Card("kau", "du"))
     repository = _FakeRepository(Vocabulary(LanguagePair("ms", "da"), cards))
 
-    session = open_study_session(repository, _first)
+    session = open_study_session(
+        repository, _RecordingProgress(), _SilentSpeech(), _first
+    )
 
     assert session.remaining == 2
     assert session.next_card() == CardDto("aku", "mig", "ms", "da")
@@ -41,4 +61,41 @@ def test_open_study_session_builds_session_over_all_cards() -> None:
 
 def test_open_study_session_propagates_repository_error() -> None:
     with pytest.raises(VocabularyNotFoundError):
-        open_study_session(_MissingRepository(), _first)
+        open_study_session(
+            _MissingRepository(), _RecordingProgress(), _SilentSpeech(), _first
+        )
+
+
+def test_open_study_session_prefers_saved_progress() -> None:
+    pair = LanguagePair("ms", "da")
+    vocabulary = Vocabulary(pair, (Card("aku", "mig"), Card("kau", "du")))
+    progress = _RecordingProgress(Deck(pair, [Card("kau", "du")]))
+
+    session = open_study_session(
+        _FakeRepository(vocabulary), progress, _SilentSpeech(), _first
+    )
+
+    assert session.remaining == 1
+    assert session.next_card() == CardDto("kau", "du", "ms", "da")
+
+
+def test_open_study_session_skips_vocabulary_when_progress_exists() -> None:
+    progress = _RecordingProgress(Deck(LanguagePair("ms", "da"), []))
+
+    session = open_study_session(
+        _MissingRepository(), progress, _SilentSpeech(), _first
+    )
+
+    assert session.remaining == 0
+
+
+def test_open_study_session_never_saves_on_start() -> None:
+    vocabulary = Vocabulary(LanguagePair("ms", "da"), (Card("aku", "mig"),))
+    progress = _RecordingProgress()
+
+    session = open_study_session(
+        _FakeRepository(vocabulary), progress, _SilentSpeech(), _first
+    )
+    session.next_card()
+
+    assert progress.saved == []

tests/unit/application/test_study_session.py

@@ -17,8 +17,33 @@ def _first(cards: Sequence[Card]) -> Card:
     return cards[0]
 
 
-def _session(*cards: Card) -> StudySession:
+class _RecordingProgress:
-    return StudySession(Deck(PAIR, cards), _first)
+    def __init__(self) -> None:
+        self.saved: list[tuple[Card, ...]] = []
+
+    def load(self) -> Deck | None:
+        return None
+
+    def save(self, deck: Deck) -> None:
+        self.saved.append(deck.cards)
+
+
+class _RecordingSpeech:
+    def __init__(self) -> None:
+        self.spoken: list[tuple[str, str]] = []
+
+    def speak(self, text: str, language_code: str) -> None:
+        self.spoken.append((text, language_code))
+
+
+def _session(
+    *cards: Card,
+    progress: _RecordingProgress | None = None,
+    speech: _RecordingSpeech | None = None,
+) -> StudySession:
+    store = _RecordingProgress() if progress is None else progress
+    voice = _RecordingSpeech() if speech is None else speech
+    return StudySession(Deck(PAIR, cards), _first, store, voice)
 
 
 def test_current_card_is_none_before_first_draw() -> None:
@@ -58,3 +83,70 @@ def test_remaining_counts_cards_in_deck() -> None:
     session = _session(A, B)
     session.next_card()
     assert session.remaining == 2
+
+
+def test_mark_known_removes_current_card_and_saves_remaining_once() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, B, progress=progress)
+    session.next_card()
+    session.mark_known()
+    assert session.remaining == 1
+    assert session.current_card is None
+    assert progress.saved == [(B,)]
+
+
+def test_mark_known_saves_nothing_when_no_current_card() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, progress=progress)
+    session.mark_known()
+    assert session.remaining == 1
+    assert progress.saved == []
+
+
+def test_mark_known_on_last_card_leaves_session_finished() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, progress=progress)
+    session.next_card()
+    session.mark_known()
+    assert progress.saved == [()]
+    assert session.next_card() is None
+
+
+def test_next_card_never_saves() -> None:
+    progress = _RecordingProgress()
+    session = _session(A, B, progress=progress)
+    session.next_card()
+    session.next_card()
+    assert progress.saved == []
+
+
+def test_next_card_speaks_front_text_once_in_front_language() -> None:
+    speech = _RecordingSpeech()
+    session = _session(A, B, speech=speech)
+    session.next_card()
+    assert speech.spoken == [("aku", "ms")]
+
+
+def test_next_card_does_not_speak_when_deck_is_empty() -> None:
+    speech = _RecordingSpeech()
+    session = _session(speech=speech)
+    session.next_card()
+    assert speech.spoken == []
+
+
+def test_next_card_speaks_again_on_every_draw() -> None:
+    speech = _RecordingSpeech()
+    session = _session(A, B, speech=speech)
+    session.next_card()
+    session.next_card()
+    assert speech.spoken == [("aku", "ms"), ("kau", "ms")]
+
+
+def test_mark_known_does_not_speak_but_following_draw_does() -> None:
+    speech = _RecordingSpeech()
+    session = _session(A, B, speech=speech)
+    session.next_card()
+    session.mark_known()
+    assert speech.spoken == [("aku", "ms")]
+    session.next_card()
+    assert speech.spoken == [("aku", "ms"), ("kau", "ms")]

tests/unit/infrastructure/test_csv_progress_repository.py

@@ -0,0 +1,112 @@
+"""Tests of write_word_list and CsvProgressRepository."""
+
+from pathlib import Path
+
+import pytest
+
+from flash_card.domain.entities.card import Card
+from flash_card.domain.entities.deck import Deck
+from flash_card.domain.errors.vocabulary_errors import VocabularyFormatError
+from flash_card.domain.value_objects.language_pair import LanguagePair
+from flash_card.infrastructure.persistence.csv_progress_repository import (
+    CsvProgressRepository,
+)
+from flash_card.infrastructure.persistence.csv_word_list import (
+    read_word_list,
+    write_word_list,
+)
+
+PAIR = LanguagePair("ms", "da")
+CARDS = (Card("aku", "mig"), Card("kau", "du"))
+
+
+def test_write_word_list_round_trips_through_read_word_list(tmp_path: Path) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    assert read_word_list(path) == (PAIR, CARDS)
+
+
+def test_write_word_list_writes_header_and_rows_with_semicolon(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    raw = path.read_bytes()
+    assert raw.decode("utf-8-sig") == "ms;da\naku;mig\nkau;du\n"
+    assert b"\r" not in raw
+
+
+def test_write_word_list_keeps_non_ascii_text(tmp_path: Path) -> None:
+    path = tmp_path / "w.csv"
+    cards = (Card("chaque", "each"), Card("parlé", "speak"))
+    write_word_list(path, LanguagePair("fr", "en"), cards)
+    assert read_word_list(path)[1] == cards
+
+
+def test_write_word_list_writes_header_only_for_no_cards(tmp_path: Path) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, ())
+    assert read_word_list(path) == (PAIR, ())
+
+
+def test_write_word_list_creates_parent_folder(tmp_path: Path) -> None:
+    path = tmp_path / "data" / "deep" / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    assert path.is_file()
+
+
+def test_write_word_list_replaces_file_and_leaves_no_temporary_file(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    write_word_list(path, PAIR, CARDS[:1])
+    assert read_word_list(path)[1] == CARDS[:1]
+    assert [item.name for item in tmp_path.iterdir()] == ["w.csv"]
+
+
+def test_write_word_list_keeps_old_file_and_no_temporary_when_write_fails(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "w.csv"
+    write_word_list(path, PAIR, CARDS)
+    unencodable = (Card("aku", "\ud800"),)
+    with pytest.raises(UnicodeEncodeError):
+        write_word_list(path, PAIR, unencodable)
+    assert read_word_list(path)[1] == CARDS
+    assert [item.name for item in tmp_path.iterdir()] == ["w.csv"]
+
+
+def test_progress_load_returns_none_when_file_is_missing(tmp_path: Path) -> None:
+    assert CsvProgressRepository(tmp_path / "p.csv").load() is None
+
+
+def test_progress_load_returns_empty_deck_for_header_only_file(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "p.csv"
+    path.write_text("ms;da\n", encoding="utf-8")
+    deck = CsvProgressRepository(path).load()
+    assert deck is not None
+    assert deck.is_empty
+    assert deck.language_pair == PAIR
+
+
+def test_progress_load_raises_format_error_and_keeps_malformed_file(
+    tmp_path: Path,
+) -> None:
+    path = tmp_path / "p.csv"
+    content = b"ms;da\naku;mig;extra\n"
+    path.write_bytes(content)
+    with pytest.raises(VocabularyFormatError):
+        CsvProgressRepository(path).load()
+    assert path.read_bytes() == content
+
+
+def test_progress_save_then_load_returns_same_cards(tmp_path: Path) -> None:
+    repository = CsvProgressRepository(tmp_path / "p.csv")
+    repository.save(Deck(PAIR, CARDS))
+    deck = repository.load()
+    assert deck is not None
+    assert deck.cards == CARDS
+    assert deck.language_pair == PAIR

tests/unit/infrastructure/test_gtts_speech.py

@@ -0,0 +1,107 @@
+"""Tests of the GttsSpeech adapter with fake synthesizer and player."""
+
+import threading
+from pathlib import Path
+
+import pytest
+
+from flash_card.infrastructure.speech import gtts_speech
+from flash_card.infrastructure.speech.gtts_speech import GttsSpeech
+
+
+class _Recorder:
+    def __init__(self) -> None:
+        self.synthesized: list[tuple[str, str]] = []
+        self.played: list[Path] = []
+        self.existed_when_played = False
+
+    def synthesize(self, text: str, language_code: str, path: Path) -> None:
+        self.synthesized.append((text, language_code))
+        path.write_bytes(b"mp3")
+
+    def play(self, path: Path) -> None:
+        self.played.append(path)
+        self.existed_when_played = path.exists()
+
+
+def test_speak_synthesizes_and_plays_then_removes_file() -> None:
+    recorder = _Recorder()
+    speech = GttsSpeech(recorder.synthesize, recorder.play)
+
+    speech.speak("aku", "ms")
+    speech.wait()
+
+    assert recorder.synthesized == [("aku", "ms")]
+    assert len(recorder.played) == 1
+    assert recorder.existed_when_played
+    assert not recorder.played[0].exists()
+
+
+def test_speak_returns_before_player_has_finished() -> None:
+    started = threading.Event()
+    release = threading.Event()
+
+    def blocked_play(path: Path) -> None:
+        started.set()
+        release.wait(timeout=5)
+
+    speech = GttsSpeech(lambda text, code, path: None, blocked_play)
+
+    speech.speak("aku", "ms")
+
+    assert started.wait(timeout=5)
+    assert speech._thread is not None
+    assert speech._thread.is_alive()
+    release.set()
+    speech.wait()
+
+
+def test_speak_logs_and_does_not_raise_when_synthesize_fails(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    played: list[Path] = []
+
+    def failing(text: str, language_code: str, path: Path) -> None:
+        raise OSError("no network")
+
+    speech = GttsSpeech(failing, played.append)
+
+    speech.speak("aku", "ms")
+    speech.wait()
+
+    assert played == []
+    assert "Speech failed" in caplog.text
+    assert "no network" in caplog.text
+
+
+def test_speak_logs_and_does_not_raise_when_play_fails(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    def failing(path: Path) -> None:
+        raise RuntimeError("no audio device")
+
+    speech = GttsSpeech(lambda text, code, path: None, failing)
+
+    speech.speak("aku", "ms")
+    speech.wait()
+
+    assert "no audio device" in caplog.text
+
+
+def test_speak_logs_missing_package_when_default_synthesizer_raises_import_error(
+    monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    def missing(name: str) -> object:
+        raise ImportError(f"No module named {name!r}")
+
+    monkeypatch.setattr(gtts_speech.importlib, "import_module", missing)
+    speech = GttsSpeech()
+
+    speech.speak("aku", "ms")
+    speech.wait()
+
+    assert "No module named 'gtts'" in caplog.text
+
+
+def test_wait_returns_when_nothing_was_spoken() -> None:
+    GttsSpeech().wait()

tests/unit/infrastructure/test_null_speech.py

@@ -0,0 +1,7 @@
+"""Tests of the NullSpeech adapter."""
+
+from flash_card.infrastructure.speech.null_speech import NullSpeech
+
+
+def test_speak_does_nothing_and_returns_none() -> None:
+    assert NullSpeech().speak("aku", "ms") is None

tests/unit/test_app.py

@@ -25,7 +25,9 @@ def test_main_runs_main_loop_and_returns_zero(
     root = _FakeRoot()
     seen: list[Path | None] = []
 
-    def fake_create(data_dir: Path | None = None) -> tuple[_FakeRoot, object]:
+    def fake_create(
+        data_dir: Path | None = None, speech_enabled: bool = True
+    ) -> tuple[_FakeRoot, object]:
         seen.append(data_dir)
         return root, object()
 

tests/unit/test_app_speech.py

@@ -0,0 +1,70 @@
+"""Tests of the speech wiring in the entry point."""
+
+import importlib.util
+from importlib.machinery import ModuleSpec
+from pathlib import Path
+
+import pytest
+
+from flash_card.infrastructure.speech.gtts_speech import GttsSpeech
+from flash_card.infrastructure.speech.null_speech import NullSpeech
+from flash_card.presentation import app
+
+
+class _FakeRoot:
+    def mainloop(self) -> None:
+        return None
+
+
+def _found(name: str) -> ModuleSpec:
+    return ModuleSpec(name, None)
+
+
+def test_build_speech_returns_null_speech_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(importlib.util, "find_spec", _found)
+    assert isinstance(app.build_speech(False), NullSpeech)
+
+
+def test_build_speech_returns_null_speech_when_packages_are_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
+    assert isinstance(app.build_speech(True), NullSpeech)
+
+
+def test_build_speech_returns_null_speech_when_one_package_is_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        importlib.util,
+        "find_spec",
+        lambda name: None if name == "playsound" else _found(name),
+    )
+    assert isinstance(app.build_speech(True), NullSpeech)
+
+
+def test_build_speech_returns_gtts_speech_when_both_packages_are_found(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(importlib.util, "find_spec", _found)
+    assert isinstance(app.build_speech(True), GttsSpeech)
+
+
+def test_main_passes_speech_disabled_with_no_speech_option(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    seen: list[bool] = []
+
+    def fake_create(
+        data_dir: Path | None = None, speech_enabled: bool = True
+    ) -> tuple[_FakeRoot, object]:
+        seen.append(speech_enabled)
+        return _FakeRoot(), object()
+
+    monkeypatch.setattr(app, "create_application", fake_create)
+
+    assert app.main(["--data-dir", str(tmp_path), "--no-speech"]) == 0
+    assert app.main(["--data-dir", str(tmp_path)]) == 0
+    assert seen == [False, True]

tests/unit/test_flash_card_view_model.py

@@ -9,6 +9,7 @@ from flash_card.domain.entities.deck import Deck
 from flash_card.domain.value_objects.language_pair import LanguagePair
 from flash_card.presentation.features.flash_card.flash_card_view_model import (
     FlashCardViewModel,
+    Side,
 )
 
 A = Card("aku", "mig")
@@ -19,8 +20,29 @@ def _first(cards: Sequence[Card]) -> Card:
     return cards[0]
 
 
-def _session(code: str, *cards: Card) -> StudySession:
+class _RecordingProgress:
-    return StudySession(Deck(LanguagePair(code, "da"), cards), _first)
+    def __init__(self) -> None:
+        self.saved: list[tuple[Card, ...]] = []
+
+    def load(self) -> Deck | None:
+        return None
+
+    def save(self, deck: Deck) -> None:
+        self.saved.append(deck.cards)
+
+
+class _SilentSpeech:
+    def speak(self, text: str, language_code: str) -> None:
+        return None
+
+
+def _session(
+    code: str, *cards: Card, progress: _RecordingProgress | None = None
+) -> StudySession:
+    store = _RecordingProgress() if progress is None else progress
+    return StudySession(
+        Deck(LanguagePair(code, "da"), cards), _first, store, _SilentSpeech()
+    )
 
 
 def test_view_model_draws_first_card_on_construction() -> None:
@@ -51,3 +73,83 @@ def test_view_model_shows_finished_message_when_no_card_is_left() -> None:
     assert view_model.is_finished
     assert view_model.language_name == ""
     assert view_model.text == FINISHED_MESSAGE
+
+
+def test_view_model_starts_on_front_side() -> None:
+    view_model = FlashCardViewModel(_session("ms", A))
+    assert view_model.side is Side.FRONT
+
+
+def test_flip_card_shows_back_language_and_translation() -> None:
+    view_model = FlashCardViewModel(_session("ms", A))
+    view_model.flip_card()
+    assert view_model.side is Side.BACK
+    assert view_model.language_name == "Danish"
+    assert view_model.text == "mig"
+
+
+def test_flip_card_twice_keeps_back_side() -> None:
+    view_model = FlashCardViewModel(_session("ms", A))
+    view_model.flip_card()
+    view_model.flip_card()
+    assert view_model.side is Side.BACK
+    assert view_model.text == "mig"
+
+
+def test_flip_card_does_nothing_when_finished() -> None:
+    view_model = FlashCardViewModel(_session("ms"))
+    view_model.flip_card()
+    assert view_model.side is Side.FRONT
+    assert view_model.language_name == ""
+    assert view_model.text == FINISHED_MESSAGE
+
+
+def test_next_card_resets_side_to_front() -> None:
+    view_model = FlashCardViewModel(_session("ms", A, B))
+    view_model.flip_card()
+    view_model.next_card()
+    assert view_model.side is Side.FRONT
+    assert view_model.language_name == "Malay"
+    assert view_model.text == "kau"
+
+
+def test_is_known_saves_remaining_and_shows_next_front() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", A, B, progress=progress))
+    view_model.flip_card()
+    view_model.is_known()
+    assert progress.saved == [(B,)]
+    assert view_model.side is Side.FRONT
+    assert view_model.text == "kau"
+    assert not view_model.is_finished
+
+
+def test_is_known_on_last_card_finishes() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", A, progress=progress))
+    view_model.is_known()
+    assert view_model.is_finished
+    assert view_model.text == FINISHED_MESSAGE
+    assert progress.saved == [()]
+
+
+def test_is_known_does_nothing_when_finished() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", progress=progress))
+    view_model.is_known()
+    assert view_model.is_finished
+    assert progress.saved == []
+
+
+def test_next_card_does_nothing_when_finished() -> None:
+    view_model = FlashCardViewModel(_session("ms"))
+    view_model.next_card()
+    assert view_model.is_finished
+    assert view_model.text == FINISHED_MESSAGE
+
+
+def test_next_card_never_saves() -> None:
+    progress = _RecordingProgress()
+    view_model = FlashCardViewModel(_session("ms", A, B, progress=progress))
+    view_model.next_card()
+    assert progress.saved == []