myYouTube/analytics/2026-09-18-local-player-double-tap.md

# Перемотка ±10 сек в плеере: кнопки на обеих ветках + двойной тап в локальном плеере

## Задача

В локальном плеере (ветка `<video controls>` в `frontend/src/components/Player.tsx`) реализовать перемотку двойным тапом: тап по правой половине видео → +10 сек, по левой → −10 сек (как в YouTube), с кратким визуальным индикатором «+10 сек»/«−10 сек» на стороне тапа. Двойной тап в YouTube-embed (iframe) не трогаем: там это встроенное поведение плеера YouTube на мобильных, события внутри кросс-доменного iframe перехватить нельзя, оверлей поверх iframe = костыль.

Расширение скоупа (уточнение пользователя): под плеером для **обеих** веток — кнопки «−10 сек» / «+10 сек». Причина: на iPad в мобильном браузере встроенный двойной тап YouTube-embed нестабилен, поэтому для YouTube-ветки нужен штатный способ перемотки. Штатный способ есть — официальный YouTube IFrame Player API: YouTube-ветка переходит с plain-iframe на `new YT.Player(...)` (скрипт `https://www.youtube.com/iframe_api`, `playerVars: { playsinline: 1 }`), кнопки вызывают `player.seekTo(player.getCurrentTime() ± 10, true)`; фолбэк при недоступности API — plain-iframe как сейчас, кнопки скрыты/disabled. Локальная ветка — кнопки работают напрямую с `video.currentTime` ± 10 и клампингом [0, duration]. Двойной тап остаётся только в локальной ветке.

## Контекст

- `Player.tsx` (59 строк): компонент без refs/effect, только `useState` для `localFailed`. Ветка `useLocal` (строки 24–40) рендерит `<div className="player-wrapper"><video controls src={…} onError={…} /></div>` + `.video-page-source`; ветка YouTube (строки 42–56) — `<iframe …>` в том же `.player-wrapper`. Ранний `return` по `useLocal` → хуки добавлять безусловно до этого return.
- `Player` используется ровно в `VideoPage.tsx` (строка 24) с `key={video.youtube_video_id}` — компонент ремоунтится при смене видео; состояние и обработчики живут не дольше одного видео, но cleanup на unmount обязателен.
- `App.css`: `.player-wrapper` (строка 184, `position: relative; overflow: hidden; aspect-ratio: 16/9`), `.player-wrapper iframe, .player-wrapper video` (строка 185, absolute/inset 0). Media ≤620px (строка 292) меняет только геометрию wrapper. Глобальное `@media (prefers-reduced-motion: reduce)` (строка 314) укорачивает все анимации до .01ms — анимация индикатора у таких пользователей станет мгновенной, сам индикатор останется. Существующие keyframes: `spin` (строка 76), `shimmer` (строка 130).
- `frontend/index.html` (строка 6): viewport `width=device-width, initial-scale=1.0` — **без** `user-scalable=no`/`maximum-scale`, т.е. double-tap-zoom у браузера включён. Viewport менять нельзя (доступность): зум на плеере гасим точечно через `touch-action`.
- Нативные контролы `<video controls>` живут в UA shadow DOM: тап по кнопкам контролов снаружи ретаргетится на host-элемент `video` — событие приходит, как будто тап был по видео. Поэтому факт «тап по контрол-бару» определяется не по `e.target`, а по Y-координате относительно нижней кромки видео.
- Сборка: `npm run build` = `tsc -b && vite build` (`noUnusedLocals: true`, tsconfig.app.json строка 20), `npm run lint` = oxlint. Тестовой инфраструктуры у frontend нет — проверки ручные + lint/build.
- **Причина кнопок для YouTube-ветки**: на iPad в мобильном браузере встроенный двойной тап embed-плеера работает ненадёжно, а перехватить жесты внутри кросс-доменного iframe нельзя — единственный штатный способ управлять embed-плеером извне это IFrame Player API (официальный, документированный).
- Текущий iframe YouTube-ветки: `src="https://www.youtube-nocookie.com/embed/{id}"` — **nocookie**-хост, параметра `playsinline` сейчас **нет** (уточнение к исходной формулировке задачи). IFrame Player API поддерживает опцию `host: 'https://www.youtube-nocookie.com'` (сохраняет текущую приватность без cookie) и `playerVars: { playsinline: 1 }` (инлайн-воспроизведение на iOS).
- Ссылки «Открыть на YouTube» на странице видео нет (grep по `frontend/src` — 0 вхождений) — ломать нечего; `title`/`allow`/`allowFullScreen` у plain-iframe сохраняются в фолбэке, у API-плеера iframe создаёт сам API (см. Решения).
- CSP-заголовков в backend нет (grep по `backend/` — пусто) — динамическая загрузка внешнего скрипта API не будет заблокирована.
- Класса `.video-page-youtube-actions` в CSS нет; есть `.video-page-source` (строка 186) и media-правило для него (строка 293). Ряд кнопок добавляем новым классом под плеером рядом с подписью источника. Правило `.player-wrapper iframe, .player-wrapper video` (строка 185, absolute/inset 0) стилизует **любой** iframe внутри wrapper, включая iframe, создаваемый `YT.Player`.

## Затронутые подсистемы и файлы

Только frontend. Backend, тесты, миграции, README — не трогаем.

- `frontend/src/components/Player.tsx` — refs/state/effect для детекции двойного тапа и индикатора (только в локальной ветке); кнопки «−10 сек»/«+10 сек» под плеером на обеих ветках; YouTube-ветка: динамический загрузчик IFrame Player API, создание/уничтожение `YT.Player` с фолбэком на plain-iframe; контейнер-хост для YT.Player (div с ref внутри `.player-wrapper`).
- `frontend/src/App.css` — стили `.tap-indicator` + keyframes, `touch-action: manipulation` на видео плеера; стили ряда кнопок перемотки под плеером (новый класс `.video-page-actions`) и host-контейнера YT.Player; при необходимости media ≤620px / pointer:coarse для кнопок.
- `frontend/index.html`, `frontend/src/pages/VideoPage.tsx` — без изменений.

## Решения (зафиксированы)

1. **Pointer-события на `video`, двойной тап по `pointerup`.** Слушатели `pointerup` вешаются на элемент `video` локальной ветки (не на wrapper: в локальной ветке wrapper содержит только video, но rect-вычисления и fullscreen-логика естественнее на самом элементе). Требования к тапу: `e.isPrimary === true` (игнор мультитача), `e.button === 0`; двойной тап = два `pointerup` с интервалом ≤ 300 мс и расстоянием между точками < 40 px (отсекает свайпы; вертикальный свайп со скроллом страницы вообще даёт `pointercancel`, а не `pointerup`). Сторона определяется по `clientX` относительно `getBoundingClientRect()` видео: левее середины → −10, правее → +10. Константы 300/40/10 — локальные const в компоненте.
2. **Контрол-бар не считается.** Тап игнорируется, если `clientY > rect.bottom − 80` (константа-запас под высоту нативных контролов 40–80 px в разных браузерах/fullscreen). Без этого тапы по кнопкам контролов (ретаргет на host) давали бы ложные перемотки.
3. **Seek:** `video.currentTime = clamp(currentTime ± 10, 0, duration)`. При недогруженных метаданных `duration` может быть NaN — тогда гарантируем только нижнюю границу 0 (верхнюю браузер клампит сам). После успешного срабатывания сбрасывать состояние «первого тапа», чтобы третий быстрый тап не вызвал повторный seek.
4. **Индикатор:** локальный state `{ delta: +10 | −10, side: 'left' | 'right', id: number }` (id — счётчик для рестарта анимации при повторных тапах). Текст «+10 сек»/«−10 сек» (минус типографский «−»). Позиция — на стороне тапа (CSS-классы `.left`/`.right`, ~25–30% от края, центр по вертикали). `pointer-events: none` — не мешает ни видео, ни контролам. Таймер ~750 мс в ref: по истечении индикатор убирается из DOM, при новом тапе таймер перезапускается. Анимация — появление + затухание через `@keyframes`.
5. **`touch-action: manipulation` на видео** (правило `.player-wrapper video`): отключает double-tap-zoom браузера на всей поверхности плеера (включая область нативных контролов — они в shadow DOM video), сохраняет панорамирование (скролл страницы свайпом по видео) и pinch-zoom. Viewport в `index.html` не меняем. Для iframe-ветки правило безвредно (на iframe `touch-action` не вешаем, поведение YouTube не трогаем).
6. **Одиночный тап и контролы не ломаются:** обработчики **не** вызывают `preventDefault`/`stopPropagation` по пути, не мешающему нативному toggle play/pause и кликам по контролам; seek происходит только при распознанном двойном тапе.
7. **Десктоп (мышь):** фильтр по `pointerType` НЕ добавляем — двойной клик мышью тоже даёт ±10 сек. Обоснование: это в точности повторяет поведение YouTube на десктопе (двойной клик по видео = перемотка); нативный `<video>` не имеет собственного действия на double-click, конфликта нет; Y-защита отсекает клики по контролам; одиночный клик (pause/play) не затрагивается, т.к. seek только на втором клике в окне 300 мс. Отсечение мыши усложнило бы код без выигрыша.
8. **YouTube-ветка: перемотка только кнопками, двойной тап не трогаем.** Двойной тап в embed — встроенное поведение плеера YouTube, кросс-доменные события недоступны, оверлей = костыль. Надёжный штатный путь (в т.ч. для iPad, где встроенный двойной тап нестабилен) — кнопки «−10 сек»/«+10 сек» под плеером, работающие через IFrame Player API (п. 10–12).
9. **Cleanup:** `useEffect` при `useLocal === true` вешает слушатели на `videoRef.current`; возвращаемая cleanup-функция снимает их, чистит таймер индикатора и сбрасывает состояние последнего тапа. Хуки объявляются до раннего return (структура компонента сейчас не позволяет хуки после `if (useLocal)`). При ветке iframe effect no-op (video отсутствует), при ремоунте по `key` всё подчищается.
10. **YouTube IFrame Player API.** В YouTube-ветке вместо статичного `<iframe>` — хост `<div ref={ytHostRef}>` внутри `.player-wrapper`, в который `new YT.Player(host, { videoId, host: 'https://www.youtube-nocookie.com', playerVars: { playsinline: 1 }, events: { onReady } })` встраивает свой iframe. `host: youtube-nocookie.com` сохраняет текущую приватность, `playsinline: 1` — инлайн на iOS. Стили: iframe от API попадает под существующее правило `.player-wrapper iframe` (строка 185); самому host-div задать заполнение wrapper (`position: absolute; inset: 0` — отдельный класс/расширение селектора). Скрипт `https://www.youtube.com/iframe_api` загружается динамически и идемпотентно (один script-тег на страницу, проверка `window.YT?.Player`/`onYouTubeIframeAPIReady`), только при рендере YouTube-ветки — на локальных видео API не грузится. Загрузчик оформляется промисом (resolve по onload скрипта + готовности `YT.Player`), чтобы не перезаписывать глобальную `onYouTubeIframeAPIReady` наивно.
11. **Фолбэк без API.** Если `YT.Player` не появился за таймаут ~5–8 с (youtube.com недоступен, блокировщик, медленная сеть), рендерим plain-iframe как сейчас (`https://www.youtube-nocookie.com/embed/{id}` с `title`/`allow`/`allowFullScreen`), кнопки перемотки скрываем (или `disabled` + aria). Состояние «loading → ready | timeout» — локальный state; таймер сбрасывается при unmount. В фолбэке поведение не хуже текущего.
12. **Кнопки перемотки.** Ряд (новый класс, напр. `.video-page-actions`) под плеером рядом с `.video-page-source`, на обеих ветках: `<button className="button-secondary" aria-label="Назад на 10 секунд">−10 сек</button>` и `aria-label="Вперёд на 10 секунд">+10 сек</button>`. Локальная ветка: `video.currentTime = clamp(currentTime ± 10, 0, duration)` (NaN-duration — только нижняя граница 0). YouTube-ветка: `player.seekTo(clamp(player.getCurrentTime() ± 10, 0, player.getDuration()), true)`; при незагруженных метаданных `getDuration()` может вернуть 0/NaN — нижнюю границу держим 0, верхнюю не ограничиваем (seekTo обработает). Локально кнопки активны всегда; в YouTube-ветке — после `onReady`, до этого `disabled` (в фолбэке — скрыты/disabled). Стиль `button-secondary` уже есть (App.css строки 59/63); при необходимости — min-height в media ≤620px/pointer:coarse по аналогии с существующими правилами.
13. **Cleanup YouTube-ветки:** при unmount или переключении ветки (local→YouTube при `onError`, смена видео по `key`) — `player.destroy()`, снятие таймеров загрузки/фолбэка, сброс состояния. Ремоунт по `key={video.youtube_video_id}` в `VideoPage` пересоздаёт плеер под новое видео — ожидаемо и корректно.
14. **Типизация YT.** Пакета `@types/youtube` нет; tsconfig без `strict`, но с `verbatimModuleSyntax` и `noUnusedLocals`. Добавить минимальный локальный `declare global { interface Window { YT?: { Player: ... }; onYouTubeIframeAPIReady?: () => void } }` (отдельный `frontend/src/types/youtube.d.ts` или в компоненте): `YT.Player` (ctor, `seekTo`, `getCurrentTime`, `getDuration`, `destroy`, `getIframe`). Импорты типов — только `import type`.

## Критерии приёмки

1. На мобильном (тач): двойной тап по правой половине локального видео → +10 сек, по левой → −10 сек; у краёв диапазона значение клампится в [0, duration]; каждый сработавший жест показывает индикатор «+10 сек»/«−10 сек» на соответствующей стороне, исчезающий через ~0,7–0,9 с.
2. Одиночный тап по видео — play/pause как раньше; тапы по нативным контролам (play, полоса перемотки, громкость, fullscreen) не вызывают перемотку и работают как раньше.
3. Браузер не приближает плеер double-tap-zoom (touch-action), при этом pinch-zoom и скролл страницы работают.
4. Десктоп не сломан: одиночный клик — play/pause; двойной клик — ±10 сек (осознанное решение, п. 7).
5. Кнопки «−10 сек»/«+10 сек» под плеером есть на обеих ветках: локальная — перемотка с клампингом [0, duration]; YouTube — через `seekTo(getCurrentTime() ± 10, true)`, работает в том числе в браузере iPad.
6. YouTube-ветка работает через IFrame Player API (nocookie-хост, playsinline): воспроизведение, встроенные контролы, fullscreen — как раньше; двойной тап по embed не перехватывается, никаких оверлеев поверх iframe.
7. Фолбэк: при недоступности API за ~5–8 с рендерится plain-iframe как сейчас, кнопки скрыты/disabled; страница и подпись источника не ломаются, ошибок в консоли нет (кроме ожидаемых сетевых к youtube.com).
8. Кнопки доступны (aria-label), стиль `button-secondary`, не ломают подпись источника и DownloadButton на странице видео.
9. Нет утечек: при размонтировании (уход со страницы видео, смена видео по key, переход local→YouTube при `onError`) сняты pointer-слушатели, таймер индикатора и таймер фолбэка; `YT.Player` уничтожен через `destroy()`.
10. `npm run lint` и `npm run build` в `frontend/` чистые.
11. Backend не тронут: `git status` — изменения только в `frontend/` и `analytics/`; `pytest` не требуется.
12. Деплой по правилу: `docker compose up -d --build`, `curl http://localhost:8080/api/health` → OK.

## План

1. `Player.tsx`, локальная ветка: добавить `videoRef`, `lastTapRef` (`{ time, x, y } | null`), `tapIndicator` state (`{ delta, side, id } | null`), `indicatorTimerRef`; `useEffect([useLocal])` — при локальной ветке `pointerup`-обработчик на видео (детектор двойного тапа по п. 1–3, `isPrimary`, `button === 0`, окно 300 мс, порог 40 px, Y-защита 80 px, определение стороны, seek с клампингом, сброс lastTap после срабатывания, показ индикатора + перезапуск таймера); cleanup (п. 9). В разметке локальной ветки — `ref={videoRef}` на `<video>` и условный `<div className={"tap-indicator " + side} key={id}>±10 сек</div>` внутри `.player-wrapper`.
2. `Player.tsx`, кнопки и API: хук-структура до раннего return (`useLocal`): `ytHostRef`, `playerRef`, state API (`'loading' | 'ready' | 'timeout'`), загрузчик скрипта IFrame API (промис, идемпотентный, только для YouTube-ветки). `useEffect` YouTube-ветки: загрузка API → `new YT.Player(ytHostRef.current, { videoId, host: youtube-nocookie, playerVars: { playsinline: 1 }, events: { onReady } })`; таймаут ~5–8 с → state `timeout` (рендер plain-iframe как сейчас); cleanup — `destroy()`, сброс таймера. Рендер YouTube-ветки: хост-div (до ready — пустой/спиннер не обязателен) или фолбэк-iframe; ряд `.video-page-actions` с двумя кнопками на обеих ветках (YouTube: `disabled` до `onReady`, скрыты/disabled в фолбэке; локальная: активны, seek через `videoRef`).
3. `App.css`: `.tap-indicator` (absolute, `top: 50%`, `translateY(-50%)`, `.left`/`.right` по стороне, `pointer-events: none`, полупрозрачная плашка в духе существующих цветов var(--text)/var(--bg), текст) + `@keyframes` появления/затухания (длительность ≈ таймеру, `forwards`); в правило `.player-wrapper video` добавить `touch-action: manipulation`; host-контейнер YT.Player — заполнение wrapper (`position: absolute; inset: 0`); ряд `.video-page-actions` (gap, размещение рядом с `.video-page-source`), при необходимости min-height кнопок в media ≤620px/pointer:coarse.
4. Типизация: `declare global` для `window.YT`/`onYouTubeIframeAPIReady` (минимальные типы, `import type`).
5. Проверки: `npm run lint`, `npm run build`; ручная — DevTools-эмуляция тача (двойной тап обеих сторон, одиночный тап, контролы, зум) и десктоп (клик/двойной клик); кнопки на обеих ветках (локальная и YouTube с API), фолбэк при недоступности API (DevTools offline/блокировка youtube.com), iPad-браузер по возможности; деплой + health.

## Риски и ограничения

- **iOS Safari и `touch-action: manipulation`**: на старых iOS поддержка ограничена — double-tap-zoom на плеере может сохраниться; это приемлемый минорный риск, viewport и pinch-zoom не трогаем (доступность).
- **Константа 80 px для контрол-бара**: в полноэкранном режиме/других браузерах высота контролов может отличаться; тап чуть выше контролов может быть засчитан как видео — допустимо, важнее не ломать сами контролы.
- **`prefers-reduced-motion`**: глобальное правило укорачивает анимацию индикатора до .01ms — индикатор мгновенно появится/исчезнет; функциональность перемотки не страдает.
- **Двойной клик на десктопе**: быстрые два клика по видео дают перемотку вместе с двойным переключением play/pause — соответствует поведению YouTube, принято осознанно.
- **Хуки и ранний return**: эффект/refs должны быть объявлены до `if (useLocal)`; при рефакторинге не сломать ветку iframe (effect должен корректно no-op).
- **Не вызывать `preventDefault`** на pointerup — иначе сломается нативный toggle play/pause и контролы.
- **Загрузка внешнего скрипта API**: youtube.com может быть недоступен/заблокирован (сеть, блокировщики) — покрыто фолбэком на plain-iframe с таймаутом ~5–8 с; до `onReady` кнопки `disabled` (краткая неактивность допустима).
- **`host: youtube-nocookie.com` у YT.Player**: опция документирована в IFrame Player API; если в конкретном окружении поведение окажется некорректным — деградация до обычного `youtube.com`-хоста, некритично (проверить при реализации).
- **`getDuration()` до готовности метаданных**: может вернуть 0/NaN — клампить только нижнюю границу (0), верхнюю доверить `seekTo(..., true)`.
- **Стили host-div**: iframe, создаваемый `YT.Player`, должен попасть под правило `.player-wrapper iframe` (строка 185); самому host-div задать `position: absolute; inset: 0`, иначе плеер не заполнит wrapper (aspect-ratio 16/9 держит wrapper).
- **Типизация/линт**: `@types/youtube` не установлен — локальный `declare global` для `window.YT`; `verbatimModuleSyntax` требует `import type` для типов; `noUnusedLocals` — не оставлять мёртвые импорты после рефакторинга ветки iframe.

## Журнал изменений

- 2026-09-18: документ создан перед реализацией. Зафиксированы решения: pointer-события на `video` (pointerup, окно 300 мс, порог 40 px, isPrimary/button 0); Y-защита 80 px от контрол-бара (тапы по UA shadow-контролам ретаргетятся на host); seek ±10 с клампингом [0, duration]; индикатор в state + таймер ~750 мс, `pointer-events: none`, позиция по стороне тапа; `touch-action: manipulation` на видео, viewport не меняется; мышь не отсекается (совпадает с десктоп-поведением YouTube); YouTube-ветка не трогается; cleanup на unmount; README не трогаем; backend не трогаем.
- 2026-09-18 (расширение скоупа по уточнению пользователя): на iPad в мобильном браузере двойной тап YouTube-embed нестабилен → добавляются кнопки «−10 сек»/«+10 сек» под плеером на **обеих** ветках. YouTube-ветка переходит с plain-iframe на официальный YouTube IFrame Player API: скрипт `https://www.youtube.com/iframe_api` (динамически, идемпотентно, только для YouTube-ветки), `new YT.Player(host, { videoId, host: 'https://www.youtube-nocookie.com', playerVars: { playsinline: 1 }, events: { onReady } })`, кнопки — `player.seekTo(player.getCurrentTime() ± 10, true)`; фолбэк при таймауте ~5–8 с — plain-iframe как сейчас, кнопки скрыты/disabled. Локальная ветка — кнопки напрямую через `video.currentTime` с клампингом [0, duration]; двойной тап остаётся только локально. Факты по коду (проверено): текущий src — `youtube-nocookie.com/embed/{id}` **без** `playsinline`; ссылки «Открыть на YouTube» в коде нет; CSP в backend нет (внешний скрипт не блокируется); правило `.player-wrapper iframe` (App.css:185) покроет iframe от API, host-div нужен `absolute; inset: 0`; класса `.video-page-youtube-actions` нет — вводим новый ряд кнопок. Cleanup YouTube-ветки: `player.destroy()`, сброс таймеров. README не трогаем; backend не трогаем.