# English
**English** is a tiny always-on-top desktop widget that teaches vocabulary one word at a time. It was built for a beginner (A0) who works in IT: a word pops up every 50 minutes, you tap *Know* or *Again*, and it gets out of the way.
Words come back on a **spaced-repetition** schedule (a check after 7 days), and phrasal verbs unlock only after you know their base verb.
A moon button gives you "do not disturb" in one click. Runs on **Windows** and **Mac**, fully **offline**: no account, no internet connection needed.
---
## How it's built
**Stack.** [Electron](https://www.electronjs.org/) 33 with plain JavaScript, HTML and CSS, no frameworks:
a widget with 200 words doesn't need them. Tests use Node's built-in runner (`node --test`). The apps are
packaged with [electron-builder](https://www.electron.build/) and built automatically by GitHub Actions.
**Spaced repetition.** A word goes through a simple cycle:
`new` → Know → `waits 7 days` → review → Know → `learned for good`. Again at any step
sends the word to a repeat queue and the cycle starts over. Scheduling rules:
- words whose week has passed are shown before new ones;
- a word from the repeat queue comes back after every 5 new words;
- phrases (`go on`, `come back`) unlock only after Know on their base verb (`go`, `come`),
a "base first, derived second" dependency.
All of this logic lives in a separate module, `learning.js`, which doesn't depend on Electron, so it can be
checked with fast automated tests (`npm test`, 13 tests) without opening any windows.
**Reliability in the details.** Progress is saved after every answer; a corrupted or old progress file is never
overwritten, it is set aside instead; a second copy of the app can't be started; the app launches together with
the computer; test settings live in a separate file that doesn't end up in the build.
**GitHub Actions builds for Mac and Windows.** A Mac app can't be built on Windows, so GitHub does it all:
one workflow ([`build.yml`](.github/workflows/build.yml)) builds a universal `.dmg` (Intel + Apple Silicon)
on `macos-latest` and a `.zip` for Windows on `windows-latest` for every version, runs the tests before building,
and on a `v*` tag publishes both files on the [Releases](https://github.com/aiiadu-ai/dad-english/releases) page.
**Made with Claude Code.** The author is not a programmer and is learning vibe coding: the project was built
in pair with [Claude Code](https://claude.com/claude-code), Anthropic's AI coding assistant.
The author set the requirements, made the decisions and checked the results; Claude Code wrote the code,
the tests and the build setup.
---
## Як це працює
1. Раз на 50 хвилин з'являється **англійське слово**.
2. Клік по слову показує **український переклад** (ще клік — повертає англійське).
3. Кнопки **Know** (знаю) і **Again** (ще раз). Після кліку віджет ховається до наступного слова.
4. **Know** → слово ховається на **7 днів**. Через тиждень воно повертається на перевірку:
- **Know** ще раз → слово вивчене назавжди;
- **Again** → слово йде в чергу повторів, і все починається спочатку.
5. **Again** у будь-який момент → слово повертається після кожних 5 нових слів.
Слова, в яких минув тиждень, показуються раніше за нові.
6. **Конструкції** (`go on`, `come back`, `make sure`…) з'являються лише після того, як на їхньому
базовому дієслові (`go`, `come`, `make`) хоч раз натиснули Know.
7. Іконка 🌙 внизу завжди на екрані: клік вмикає **«не турбувати»** (слова не з'являються 2 години),
ще клік — вимикає. Іконку можна перетягнути в зручне місце.
Програма відкривається сама разом із комп'ютером (автозапуск), а прогрес зберігається у файлі й не губиться.
### Коли з'являється наступне слово
Часи нижче — за замовчуванням, їх можна змінити в `config.json` (`intervalMs`, `dndMs`).
| Що сталося | Коли буде наступне слово |
|---|---|
| Програму щойно запустили (або ввімкнули комп'ютер, якщо працює автозапуск) | **одразу**: одне слово показується при старті |
| Натиснули **Know** або **Again** | через **50 хвилин** |
| Клікнули 🌙, щоб увімкнути «не турбувати» | слово ховається, наступне прийде **само рівно через 2 години** після кліку |
| Клікнули 🌙 ще раз, щоб вимкнути «не турбувати» | через **50 хвилин** після цього кліку, а не одразу |
| Клікнули 🌙, поки слово ще на екрані | слово ховається без відповіді (ні Know, ні Again), далі як у «не турбувати» |
| Усі слова вивчені або чекають перевірки | нічого не з'являється; програма перевіряє знову кожні 50 хвилин, і слово повернеться, коли мине 7 днів |
Поки комп'ютер вимкнений, слова не з'являються.
### Чи потрібен інтернет
**Ні, програма працює повністю без інтернету.** Усі слова, переклади й прогрес лежать на самому
комп'ютері (`words.json` і `progress.json`), а в коді програми немає жодних звернень до мережі:
вона нічого нікуди не надсилає й не потребує облікового запису. Інтернет потрібен лише один раз, щоб
завантажити файл програми зі сторінки Releases, а далі його можна вимкнути.
## Завантажити
Готові програми лежать на сторінці **[Releases](https://github.com/aiiadu-ai/dad-english/releases/latest)**.
Відкрий найновіший реліз і завантаж файл для своєї системи:
| Система | Файл |
|---|---|
| Windows 10/11 | `English-…-win-x64.zip` |
| Mac (Intel і Apple Silicon) | `English-…-universal.dmg` |
Програми не підписані, тому система при першому запуску попросить підтвердження — нижче описано, як.
## Встановлення на Windows
1. Завантаж `English-…-win-x64.zip`.
2. Клацни на ньому правою кнопкою → **«Видобути все»** (Extract all) у **постійну папку**
(наприклад, `C:\Programs\English` або на робочий стіл). Не запускай прямо з архіву й не переноси
папку потім: автозапуск запам'ятовує, де лежить програма.
3. Відкрий папку й двічі клікни **`English.exe`**.
4. Якщо Windows пише **«Windows protected your PC»**: натисни **«Докладніше»** → **«Все одно виконати»**.
Після першого запуску програма відкриватиметься сама разом із Windows. Вимкнути це можна, змінивши
`"autostart": true` на `false` у файлі `resources\app\config.json` і один раз запустивши програму.
## Встановлення на Mac
Для Mac. Програма не підписана Apple, тому macOS попросить дозволу при першому запуску.
1. Завантаж `English-….dmg` і відкрий його.
2. Перетягни **English** у папку **Applications** (Програми).
3. Відкрий English з Applications. macOS скаже, що не може перевірити програму, — натисни **«Готово»**.
4. Відкрий **Системні налаштування → Конфіденційність і безпека**, прокрути вниз до повідомлення про
English і натисни **«Все одно відкрити»**. Підтверди паролем Mac.
5. Далі програма запускатиметься без запитань.
Автозапуск разом із Mac закладений у програмі, але на справжньому Mac його ще не перевіряли.
**Якщо macOS пише, що програма «пошкоджена»** — відкрий Термінал і виконай:
```bash
xattr -cr /Applications/English.app
```
Після цього відкрий English ще раз.
## Запуск локально (для розробки)
Потрібен [Node.js](https://nodejs.org/) 20 або новіший.
```bash
npm install
npm start
```
На Windows у PowerShell команду `npm` може заблокувати політика скриптів — тоді використовуй
`npm.cmd start`.
Перевірка логіки вивчення:
```bash
npm test
```
### Тестовий режим
Щоб не чекати 50 хвилин і 7 днів, створи файл `config.local.json` (він не потрапляє в git):
```json
{ "testMode": true }
```
У тестовому режимі беруться слова з `words.test.json` (12 слів), слово з'являється кожні 5 секунд,
а «тиждень» триває 40 секунд. Прогрес тестового режиму пишеться в окремий `progress.test.json`.
Щоб побачити на віджеті підпис (NEW / REVIEW / AGAIN), додай `"showTestLabel": true`.
## Налаштування (`config.json`)
| Поле | Що означає | За замовчуванням |
|---|---|---|
| `intervalMs` | пауза між словами, мілісекунди | `3000000` (50 хв) |
| `dndMs` | скільки триває «не турбувати» | `7200000` (2 год) |
| `reviewDays` | через скільки днів перевірка після першого Know | `7` |
| `autostart` | відкривати апку разом із комп'ютером | `true` |
| `testMode` | тестовий режим (див. вище) | `false` |
| `testIntervalMs`, `testReviewSeconds` | швидкі інтервали тестового режиму | `5000`, `40` |
`config.local.json` перекриває окремі поля `config.json`.
## Як додати слова (`words.json`)
Файл — це масив слів. Приклад:
```json
[
{
"en": "deadline",
"uk": "дедлайн, кінцевий термін",
"type": "noun",
"examples": [{ "en": "The deadline is Friday.", "uk": "Дедлайн — у п'ятницю." }]
},
{
"en": "go on",
"uk": "продовжувати",
"type": "phrase",
"base": "go",
"examples": [{ "en": "Please, go on.", "uk": "Продовжуйте, будь ласка." }]
}
]
```
- `en` — слово англійською, `uk` — переклад.
- `type` — `noun` (іменник), `verb` (дієслово) або `phrase` (конструкція).
- `base` — **лише для `phrase`**: дієслово, після Know на якому відкриється конструкція
(наприклад, для `go on` це `go`). Таке дієслово (`type: "verb"`) має бути в списку.
- `examples` — приклади речень (поки не показуються, це наступний етап).
- Пара `en` + `type` має бути унікальною (`call` як іменник і `call` як дієслово — це різні слова).
Після зміни слів запусти `npm test`. У вже встановленій програмі `words.json` лежить:
- Windows: `resources\app\words.json` у папці програми;
- Mac: `English.app` → правою кнопкою «Показати вміст пакета» → `Contents/Resources/app/words.json`.
## Де зберігається прогрес
- Windows: `%APPDATA%\dad-english\progress.json`
- Mac: `~/Library/Application Support/dad-english/progress.json`
Щоб почати вивчення спочатку, закрий програму й видали цей файл.
## Як випустити нову версію
Збірки робить GitHub Actions (файл `.github/workflows/build.yml`), бо Mac-програму на Windows не зібрати.
- **Перевірка без публікації:** вкладка **Actions** → **Build** → **Run workflow**. Обидві збірки
з'являться внизу запуску в розділі **Artifacts**.
- **Публікація:** змінити `"version"` у `package.json`, закомітити, створити тег виду `v1.0.1`
й запушити його. Збірка запуститься сама, а за кілька хвилин на сторінці Releases з'являться обидва файли.
## Структура проєкту
| Файл | Призначення |
|---|---|
| `main.js` | вікна, таймери, збереження прогресу |
| `learning.js` | уся логіка вибору слів (тестується окремо) |
| `learning.test.js` | автотести логіки |
| `index.html`, `style.css`, `renderer.js`, `preload.js` | віджет зі словом |
| `moon.html` | іконка 🌙 |
| `words.json` | 200 слів |
| `words.test.json` | 12 слів для тестового режиму |
| `.github/workflows/build.yml` | автоматична збірка для Windows і Mac |
| `docs/widget.jpg` | скріншот віджета для README |