Chess Outline

Bookmarklet для визуализации контроля полей, угроз и связок на chess.com.

Что делает

Анализирует позицию и показывает:

• Hanging pieces — ваши фигуры под угрозой
• Threats — вражеские фигуры, которые можно взять
• Контроль полей — кто контролирует какие клетки
• Связки (Pins) — абсолютные и относительные связки
• Вилки (Forks) — фигуры, атакующие несколько целей одновременно
• Шахи (Checks) — предсказание шахов и матов, клетки угроз
• Move Preview — безопасность возможных ходов

Цветовая индикация

Цвет рамки	Значение
Зелёный	Свободное взятие — незащищённая вражеская фигура
Красный	Ваша фигура под угрозой, или вражеская с SEE < 0 (невыгодный размен)
Жёлтый	Спорная ситуация — фигура атакована и защищена (SEE >= 0)

Число в углу показывает результат размена (SEE):

• +3 — вы выигрываете 3 очка материала при полном размене
• = — равный размен (SEE = 0)
• -2 — вы теряете 2 очка материала

Число отображается как для жёлтых (спорных), так и для красных (невыгодных) клеток.

Move Preview

При клике на фигуру подсвечивает возможные ходы цветами в зависимости от безопасности:

Примечание: При клике на фигуру подсветка контроля (зелёные/красные/жёлтые рамки) автоматически скрывается с клеток возможных ходов, чтобы не мешать анализу. Подсветка контроля восстанавливается после снятия выделения с фигуры.

Ходы без взятия:

Цвет	Значение
Зелёный	Безопасно — фигура не будет под атакой
Красный	Опасно — фигуру заберут с выгодой (число показывает потерю материала)
Жёлтый	Рискованно — под атакой, но защищена (число показывает результат размена)

Взятия:

Цвет	Значение
Зелёный	Свободное взятие — фигура не защищена ИЛИ защищена только королём, когда атакующая фигура будет под защитой (король не может взять защищённую фигуру)
Жёлтый	Выгодное взятие — фигура защищена реальными фигурами, но размен в вашу пользу
Красный	Невыгодное взятие — вы потеряете больше, чем получите (число показывает нетто-результат)

Piece-specific SEE: оценка взятия учитывает, какая именно фигура берёт первой. В отличие от карты контроля (где берёт самая дешёвая), при клике на конкретную фигуру SEE считается с учётом того, что именно она делает первое взятие. Поэтому одна и та же цель может показывать разные цвета в зависимости от выбранной фигуры (например, взятие ферзём — красное, а конём — жёлтое).

Дополнительные индикаторы:

• Треугольник в левом нижнем углу — после хода ваша фигура окажется под связкой
• Треугольник в правом верхнем углу — ход создаёт связку на вражескую фигуру
• Треугольник в правом нижнем углу — ход создаёт вилку
• Квадрат в левом верхнем углу — ход открывает угрозу (см. ниже)

Board Prediction (при наведении)

При наведении на любую клетку хода показывается предсказание позиции — полный анализ доски "как будто ход уже сделан":

• Текущий анализ скрывается, показывается только предсказание
• Отображается контроль полей, связки, вилки после хода для всех клеток
• На наведённой клетке (куда станет фигура) скрывается только контроль полей, но остаются связки, вилки, шахи и маты — позволяет видеть тактические последствия хода без визуального шума
• Автоматически скрываются значки превью ходов на клетках, где изменилось количество атакующих фигур — это помогает сфокусироваться на изменениях тактической ситуации после хода
• Видно какие угрозы появятся/исчезнут после хода
• Помогает оценить последствия хода до его выполнения

При уходе мыши с клетки — возвращается обычный анализ и все значки превью ходов восстанавливаются

Открытые угрозы (Opened Threats)

При анализе хода система проверяет побочные последствия:

Индикатор	Значение
Красный квадрат	Ваша фигура потеряет защиту и станет уязвимой
Зелёный квадрат	Свободное взятие — вражеская фигура не защищена
Жёлтый квадрат	Выгодное взятие — вражеская защищена, но размен в вашу пользу
Диагональный	Оба типа одновременно (красный/зелёный или красный/жёлтый)

Как работает:

• Exposed friendly — при уходе фигуры, другая ваша фигура может потерять защитника
• Discovered attack — уходящая фигура открывает линию атаки для слайдера позади (ладья, слон, ферзь)

Детали видны в Board Prediction при наведении на клетку хода

Связки (Pins) и Skewer

Тип	Описание	Стиль рамки
Absolute	Связка к королю (фигура не может двигаться)	Сплошная
Relative	Связка к ценной фигуре (невыгодно двигаться)	Пунктирная
Skewer	Сквозная атака через короля (король уходит → забираем фигуру за ним)	Сплошная

Цвета связок:

• Cyan — ваша связка на вражескую фигуру (хорошо)
• Красный/розовый — вражеская связка на вашу фигуру (плохо)
• Зелёный — ваш skewer (атака через вражеского короля)
• Тёмно-красный — вражеский skewer (атака через вашего короля)

Режимы отображения относительных связок (кнопка рядом с Pins):

• Off — только абсолютные связки и skewer
• Major — связки с ферзём/ладьёй как целью
• All — все связки включая слонов/коней

Вилки (Forks)

Вилка — это ход, при котором одна фигура атакует две или более вражеских фигур одновременно.

Цвет	Значение
Зелёный	Ваша вилка — можно забрать фигуру с выгодой
Красный	Вражеская вилка — угроза вашим фигурам
Жёлтый	Вилка с равным обменом

Линии показывают связь между атакующей фигурой и целями:

• Прямые линии — для ферзя, ладьи, слона, пешки
• L-образные линии — для коня (показывают траекторию атаки)

Типы вилок:

• Royal Fork — вилка с королём (вынуждает ход, нельзя игнорировать)
• Free Fork — есть незащищённая цель
• Profitable Fork — выгодный размен (вилка дешевле цели)

Шахи и маты (Checks)

Система предсказывает и отображает шахи:

Индикаторы в Move Preview:

Индикатор	Значение
Фиолетовый круг с +	Ход даёт шах
Фиолетовый круг с # (свечение, крупнее)	Ход даёт мат

Индикаторы на доске:

Индикатор	Значение	Toggle
Фиолетовый круг с зелёным # (пульсация + свечение, крупнее)	Клетка, куда вы можете походить и дать мат	Checks: All / Threats
Фиолетовый круг с зелёным +	Клетка, куда вы можете походить и дать шах	Checks: All
Светло-фиолетовый круг с красным +	Клетка, откуда враг может дать вам шах	Checks: All / Threats
Ярко-красный круг с красным # (пульсация + свечение, крупнее)	Клетка, откуда враг может дать вам мат	Checks: All / Threats

Оценка ходов с шахом:

• Ходы с шахом оцениваются с учетом "частичной заморозки" вражеских фигур
• Замороженные фигуры: те, которые НЕ могут захватить шахующую фигуру
• Незамороженные фигуры: могут захватить шахующую или это король
• Безопасность шахующей фигуры оценивается только на основе незамороженных фигур
• Цвет взятия (зелёный/жёлтый/красный) показывается на основе текущей позиции (до хода)

Цвета шахов:

• Фиолетовый (#8b5cf6) — наш шах (на карте контроля и в превью хода)
• Тёмно-фиолетовый (#7c3aed) — наш мат (на карте контроля, с пульсацией и свечением)
• Светло-фиолетовый (#c084fc) — вражеский шах
• Ярко-красный (#ef4444) — вражеский мат (с пульсацией и свечением)

Автоопределение стороны

По умолчанию сторона определяется автоматически по ориентации доски:

• Обычная доска (белые снизу) → White
• Перевёрнутая доска (flipped) → Black

При перевороте доски (кнопка flip на Chess.com) сторона переключается автоматически.

Режимы:

Кнопка	Действие
Auto (синяя)	Сторона следует за ориентацией доски
White / Black	Ручной выбор — отключает Auto

При ручном выборе кнопки White/Black автоматический режим отключается. Нажмите Auto, чтобы вернуть автоопределение.

Статистика в панели

Hanging: 2 | Threats: 1 | Material: +3 | Pins: 1/2 | Forks: 1/0

• Hanging — сколько ваших фигур под угрозой
• Threats — сколько вражеских фигур можно взять
• Material — материальный баланс
• Pins — ваши связки / связки на вас
• Forks — ваши вилки / вилки на вас

Ценность фигур

Фигура	Ценность
Пешка	1
Конь	3
Слон	3
Ладья	5
Ферзь	9
Король	100*

* Король имеет высокую ценность для SEE — это значит, что он используется в размене последним.

Установка

Способ 1: Chrome Extension (рекомендуется)

1. Соберите проект: npm run build:ext
2. Откройте chrome://extensions в Chrome
3. Включите Developer mode (правый верхний угол)
4. Нажмите Load unpacked и выберите папку extension/
5. Откройте chess.com — расширение активируется автоматически
6. Кликните на иконку расширения в тулбаре для настроек

Настройки сохраняются между сессиями.

Способ 2: Консоль браузера

1. Соберите проект: npm run build
2. Откройте игру на chess.com
3. Откройте консоль браузера (F12 → Console)
4. Скопируйте содержимое файла dist/chess-outline.js и вставьте в консоль
5. Нажмите Enter

Способ 3: Bookmarklet

1. Создайте новую закладку в браузере
2. В поле "Имя" введите: Chess Outline
3. В поле "URL" вставьте содержимое dist/chess-outline.js с префиксом javascript:

Разработка

Архитектура

Три слоя с чётким разделением ответственности:

┌─────────────────────────────────────────────────────────┐
│  UI Layer (src/ui/)                                     │
│  - Может импортировать: analysis/, core/, state.js      │
│  - Отвечает за: DOM, рендеринг, события                 │
└─────────────────────────────────────────────────────────┘
                          ↓ imports
┌─────────────────────────────────────────────────────────┐
│  Analysis Layer (src/analysis/)                         │
│  - Может импортировать: core/, state.js (только чтение) │
│  - НЕ импортирует: ui/                                  │
│  - Возвращает: чистые данные, без side effects          │
└─────────────────────────────────────────────────────────┘
                          ↓ imports
┌─────────────────────────────────────────────────────────┐
│  Core Layer (src/core/)                                 │
│  - Может импортировать: только constants.js             │
│  - НЕ импортирует: state.js, analysis/, ui/             │
│  - Чистые функции: одинаковый вход → одинаковый выход   │
└─────────────────────────────────────────────────────────┘

Правило: Analysis никогда не импортирует UI. Данные текут в одном направлении.

Data Flow

getBoardState() → buildAttackMap() → detectPins() → detectForks() →
evaluateSquareSafety() → getSquareHighlight() → renderControlMap()

Модули

Модуль	Назначение
src/core/board-parser.js	Парсинг DOM Chess.com в 8x8 состояние доски + симуляция ходов
src/core/attack-map.js	Двухпроходный расчёт атак (сначала не-короли, потом короли)
src/core/see.js	Static Exchange Evaluation с мемоизацией
src/core/selectors.js	Централизованные DOM-селекторы для Chess.com
src/analysis/pins.js	Детекция связок (absolute, relative) и skewer
src/analysis/forks.js	Детекция тактических вилок
src/analysis/checks.js	Детекция шахов и матов, предсказание угроз
src/analysis/evaluate.js	Общая логика оценки безопасности клеток
src/analysis/opened-threats.js	Анализ вскрытых угроз при перемещении (exposed friendly + discovered attacks)
src/analysis/position-stats.js	Подсчет статистики позиции (hanging, threats, material, pins, forks)
src/analysis/control.js	Анализ позиции и определение цвета подсветки
src/analysis/move-preview.js	Оценка безопасности ходов, opened threats, кеширование предсказаний
src/ui/control-renderer.js	Рендеринг карты контроля из данных анализа
src/ui/overlay.js	Низкоуровневый рендеринг (рамки, линии)
src/ui/panel.js	UI панели управления и обработчики событий
src/ui/observer.js	MutationObserver с 50ms debounce
src/state.js	Глобальное состояние с event system
src/index.js	Entry point для bookmarklet (IIFE)
src/content.js	Entry point для Chrome Extension (content script)

Сборка

# Установка зависимостей
npm install

# Bookmarklet (создаёт dist/chess-outline.js)
npm run build

# Chrome Extension (создаёт extension/content.js)
npm run build:ext

# Watch mode (пересборка при изменениях)
npm run watch

# Dev mode (watch + HTTPS сервер на localhost:8443)
npm run dev

Тестирование

Способ 1: Copy-paste (простой)

Копировать содержимое dist/chess-outline.js в консоль браузера на chess.com.

Способ 2: HTTPS сервер (для разработки)

npm run dev

При первом запуске:

1. Откройте https://localhost:8443 в браузере
2. Примите самоподписанный сертификат (Chrome: "Advanced" → "Proceed to localhost")
3. Затем в консоли chess.com:

fetch('https://localhost:8443/chess-outline.js').then(r=>r.text()).then(eval)

Сертификат генерируется автоматически через openssl и сохраняется в scripts/.certs/

Как работает

1. Парсинг доски: скрипт читает DOM chess.com и находит все фигуры по CSS классам (.piece, .square-XY)

2. Расчёт атак: для каждой фигуры вычисляются все клетки, которые она атакует:

   • Пешка: диагонали вперёд
   • Конь: L-образные ходы
   • Слон: диагонали до первой фигуры
   • Ладья: горизонтали/вертикали до первой фигуры
   • Ферзь: слон + ладья
   • Король: все соседние клетки

3. Карта контроля: для каждой из 64 клеток подсчитывается количество белых и чёрных атак

4. Анализ позиции:

   • Ваши фигуры: проверяется, атакованы ли они и достаточно ли защищены
   • Вражеские фигуры: проверяется, можете ли вы их взять с преимуществом
   • Связки: находятся все абсолютные и относительные связки
   • Вилки: находятся фигуры, атакующие 2+ вражеских фигур одновременно
   • Для спорных ситуаций используется SEE для расчёта результата размена

5. Визуализация: на фигуры под атакой накладываются цветные рамки, связки подсвечиваются линиями

Static Exchange Evaluation (SEE)

Для расчёта результата размена используется negamax-подобный алгоритм с условным "stand pat":

1. Сортируем атакующих/защитников по ценности (от дешёвых к дорогим)
2. Рекурсивно симулируем последовательность взятий
3. При каждом взятии проверяем X-ray атакующих (см. ниже)
4. Возвращаем итоговый баланс материала

Conditional Stand Pat (двухуровневая система):

Уровень	Условие	Описание
Первый уровень	attacker < pieceValue	Остановить размен можно только если дешёвая фигура бьёт дорогую
Рекурсивные уровни	Всегда разрешён	Обе стороны играют оптимально — могут отказаться от невыгодного продолжения

Первый уровень показывает реальные потери при невыгодном взятии (дорогая фигура бьёт дешёвую → нельзя остановиться). Рекурсивные уровни позволяют обеим сторонам оптимально решать, продолжать ли размен.

Режимы использования:

Контекст	Порядок атакующих	Stand Pat	Пример
Карта контроля «я атакую врага»	Самый дешёвый первый	Нет	Показывает оптимальный результат
Карта контроля «враг атакует меня»	Самый дешёвый первый	Да (условный)	Показывает худший случай для защитника
Move preview (клик на фигуру)	Кликнутая фигура первая	Да (условный → полный в рекурсии)	Показывает реальный результат для конкретной фигуры

X-Ray атаки: когда слайдер (ладья, слон, ферзь) делает взятие и уходит с линии, фигуры того же цвета позади него на этой линии "открываются" и становятся новыми атакующими.

Пример: белая ладья на e4 и белый ферзь на e1 атакуют чёрного ферзя на e5. При расчёте Rxe5:

• После взятия ладьёй (5) чёрного ферзя (9), ладья уходит с e4
• Белый ферзь на e1 теперь атакует e5 (x-ray)
• SEE учитывает ферзя как дополнительного атакующего

Правило короля: король не может инициировать взятие защищённой фигуры (он не участвует в SEE как первый атакующий).

Attack Map Algorithm

Трёхпроходный подход:

1. Вычисляем все атаки не-королей, чтобы определить какие клетки контролируются
2. Вычисляем X-ray атаки: для слайдеров (ладья, слон, ферзь) находим фигуры "за" первой блокирующей фигурой
3. Добавляем атаки королей только на клетки, не контролируемые вражеским королём (взаимное исключение)

Выход на клетку: взвешенные значения контроля, счётчики атак, ценности фигур, списки атакующих, X-ray карта.

King Exception Rules

Короли имеют особую обработку при оценке атак:

• Атаки короля вычисляются, но исключаются из SEE
• Король не может инициировать взятие защищённой фигуры
• SEE_VALUES.king = Infinity предотвращает "размен" короля
• Специальные флаги: enemyOnlyKingAttacks, myOnlyKingAttacks для крайних случаев, когда атакует только король

Fork Detection Algorithm

Детекция фигур, атакующих 2+ вражеских фигур одновременно (src/analysis/forks.js):

1. Для каждой фигуры собираем все атакованные вражеские фигуры
2. Оцениваем качество взятия для каждой цели: free, profitable, loss, royal
3. Вилка валидна, если 2+ цели имеют хорошее качество взятия (free, profitable, или royal)
4. Специальная обработка для коней (L-образные линии в визуализации)

Выход: forksMap = { square: forkInfo } где forkInfo содержит:

• targets[] — атакованные фигуры с качеством взятия
• totalValue — сумма ценностей целей (исключая короля)
• forkQuality — общая оценка вилки (free, profitable, trade)
• isRoyal — является ли король одной из целей

Chess.com DOM Selectors

• Доска: wc-chess-board, .board, или [class*="board"]
• Фигуры: .piece с классами типа wp (white pawn), bq (black queen)
• Клетки: square-XY где X=файл (1-8), Y=ряд (1-8)
• Подсказки ходов: .hint элементы для легальных ходов

Совместимость

• Safari
• Chrome
• Firefox
• Edge

Ограничения

• Работает только на chess.com
• Не учитывает рокировку и взятие на проходе
• Не учитывает очередь хода

Лицензия

MIT