@yaneart/yaneplayer 0.0.0-stage → 0.1.1

package/GUIDE.md

@@ -0,0 +1,716 @@
+# Руководство yanePlayer
+
+Подключение, API и настройка плеера. Короткий пример — в [README](./README.md).
+
+- [Подключение](#подключение)
+- [Элемент и lifecycle](#элемент-и-lifecycle)
+- [Управление](#управление)
+- [Headless API](#headless-api)
+- [Host и timeline](#host-и-timeline)
+- [Transport и requests](#transport-и-requests)
+- [Субтитры и локальные файлы](#субтитры-и-локальные-файлы)
+- [Тема](#тема)
+- [Разработка](#разработка)
+
+## Подключение
+
+В приложении с ESM bundler:
+
+```sh
+npm install /path/to/yaneart-yaneplayer-0.1.0.tgz
+```
+
+Обычный HTML/JavaScript:
+
+```js
+import "@yaneart/yaneplayer";
+```
+
+```html
+<yane-player
+  src="/video.mp4"
+  poster="/poster.jpg"
+  label="Видео"
+  lang="ru"
+></yane-player>
+```
+
+Для браузера без bundler скопируйте содержимое `dist/` вместе с chunks на свой сервер
+и подключите `<script type="module" src="/vendor/yaneplayer/index.js"></script>`.
+Bare npm specifier в браузере требует bundler либо import map.
+
+React (JSX):
+
+```jsx
+import "@yaneart/yaneplayer";
+
+export default function App() {
+  return <yane-player src="/video.mp4" />;
+}
+```
+
+В React + TypeScript добавьте один type-only import — это JSX declarations, без wrapper/JS:
+
+```tsx
+import "@yaneart/yaneplayer";
+import type {} from "@yaneart/yaneplayer/react";
+
+export default function App() {
+  return (
+    <yane-player
+      src="/video.mp4"
+      onyp-statechange={(event) => console.log(event.detail.snapshot.playback)}
+    />
+  );
+}
+```
+
+Vue:
+
+```vue
+<script setup lang="ts">
+import "@yaneart/yaneplayer";
+</script>
+
+<template>
+  <yane-player src="/video.mp4"></yane-player>
+</template>
+```
+
+Однократно настройте Vue compiler в `vite.config.ts`:
+
+```ts
+vue({
+  template: {
+    compilerOptions: {
+      isCustomElement: (tag) => tag === "yane-player",
+    },
+  },
+});
+```
+
+Angular:
+
+```ts
+import "@yaneart/yaneplayer";
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+
+@Component({
+  selector: "app-player",
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: '<yane-player src="/video.mp4"></yane-player>',
+})
+export class PlayerExample {}
+```
+
+## Элемент и lifecycle
+
+| API                           | Назначение                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------- |
+| `src`                         | MP4 URL; pathname .m3u8 автоматически выбирает HLS                          |
+| `type`                        | video/mp4, application/vnd.apple.mpegurl или application/x-mpegurl          |
+| `poster`                      | URL обложки; изменение не перезагружает source/runtime                      |
+| `label`                       | Имя внутреннего region; default Video player                                |
+| `lang`                        | Язык controls: ru или en, default en                                        |
+| `theater`                     | Boolean property/attribute; host применяет layout по yp-theaterchange       |
+| `navigation` property         | PlayerNavigation: optional previous/next callbacks приложения               |
+| `preferences` property        | PreferencesAdapter приложения; смена отменяет старые load/save              |
+| `platform` property           | PlatformOptions: wakeLock/mediaSession и optional orientation               |
+| `thumbnail` property          | Async callback приложения для миниатюры absolute time                       |
+| `source` property             | Полный PlayerSource, имеет приоритет над shorthand; null очищает source/src |
+| `host` property               | HostAdapter; функции/объекты передаются properties, без JSON attributes     |
+| `initial` property            | SourceOptions: positionSeconds/intent/trackPreferences, default paused      |
+| `commandTimeoutMs` property   | Положительный media timeout, default 15000                                  |
+| `runtime`                     | Readonly PlayerRuntime или null вне document                                |
+| `setSource(source, options?)` | Явная async загрузка/retry после подключения элемента                       |
+
+Без источника — idle без media requests. Изменение src/type переключает на shorthand.
+Равный descriptor при rerender не перезапускает поток. Source/revision/transport replacement
+сохраняет один video. Смена host/timeout создаёт новый runtime с тем же video.
+Disconnect немедленно dispose/abort; reconnect создаёт runtime и загружает source с initial,
+без автоматического сохранения позиции. До подключения используйте properties, после — методы.
+
+Элемент делегирует play/pause/seek/selectAudio/selectText/selectQuality/setVolume/setMuted/
+setPlaybackRate/setPreservesPitch, enterFullscreen/exitFullscreen,
+requestPictureInPicture/exitPictureInPicture и navigate тому же runtime. Команды возвращают Promise.
+setPlatformOptions меняет настройки платформы синхронно; setPreferences(adapter?) позволяет
+дождаться загрузки профиля и обработать отказ. Изменение properties не требует пересоздания runtime.
+Для framework bindings: React `source={source}`, Vue `:source="source"`, Angular `[source]="source"`.
+
+`yp-ready` сообщает готовность runtime, не media; detail — PlayerRuntime.
+`yp-statechange`, `yp-positionchange`, `yp-trackchange`, `yp-qualitychange`, `yp-commandchange`,
+`yp-capabilitieschange`, `yp-ended`, `yp-error` содержат PlayerEvent в detail. События bubbles/composed.
+Подписывайтесь перед подключением, либо читайте runtime после mount. Progress — максимум раз
+в 5 секунд и дополнительно на pause/seeked/ended/source leave; это подтверждённая позиция.
+После disconnect событий нет. Ошибки source/media/host нормализованы, без provider URL/secrets.
+Blocked autoplay оставляет explicit play; fatal source/media error требует setSource retry.
+
+## Управление
+
+На компьютере плеер показывает нижнюю панель с воспроизведением, перемоткой, звуком,
+временем, скоростью, качеством, дорожками и полноэкранным режимом. Качество и озвучки
+берутся из источника; возможности зависят от формата и браузера.
+Списки озвучек и субтитров прокручиваются независимо, настройки субтитров всегда видны.
+
+На телефоне Play находится по центру, дополнительные параметры — в окне настроек.
+Одиночное касание кадра переключает воспроизведение, двойное слева или справа перематывает
+на 10 секунд. Блокировка в настройках отключает случайные касания; кнопка разблокировки
+появляется при касании кадра. Escape также снимает блокировку.
+
+Горячие клавиши работают, когда фокус находится внутри плеера:
+
+| Клавиши   | Действие                               |
+| --------- | -------------------------------------- |
+| Space / K | Воспроизведение и пауза                |
+| J / L     | Назад / вперёд на 10 секунд            |
+| ← / →     | Назад / вперёд на 5 секунд             |
+| M         | Включить / выключить звук              |
+| C         | Выключить / вернуть выбранные субтитры |
+| F         | Полный экран                           |
+| T         | Режим театра                           |
+
+Буквенные сочетания работают и в русской раскладке. В меню используются стрелки,
+Home/End, Enter и Escape; на ползунках стрелки меняют значение. В текстовых полях
+горячие клавиши плеера не перехватывают ввод. Анимации учитывают reduced motion.
+
+### Режим театра
+
+Плеер сообщает приложению о переключении режима; размер области видео задаёт приложение:
+
+```js
+player.addEventListener("yp-theaterchange", ({ detail }) => {
+  document.querySelector("main").classList.toggle("theater", detail.theater);
+});
+```
+
+Свойство `player.theater` отражается в HTML-атрибуте. Для React доступен
+`onyp-theaterchange`. При изменении layout учитывайте высоту окна и возврат scroll.
+
+### Переход между сериями
+
+Приложение задаёт порядок серий и callbacks. Если направления нет, соответствующая
+кнопка скрыта. Пока Promise выполняется, повторный переход заблокирован:
+
+```js
+player.navigation = {
+  previous: () => openEpisode(currentEpisode - 1),
+  next: () => openEpisode(currentEpisode + 1),
+};
+```
+
+`openEpisode` загружает новый источник через `player.setSource(...)` и обновляет navigation.
+Для перехода из ОС используется тот же callback. `player.navigate("next")` работает через runtime.
+`snapshot.navigation` содержит доступные направления, pending и безопасную ошибку; после отказа
+можно повторить переход. Автоматический переход выключен. Для явного разрешения задайте
+`autoAdvance: true`; next вызывается только после настоящего ended текущего видео.
+Приложение загружает новый source и само задаёт intent; плеер не предзагружает следующую серию.
+
+### Автосубтитры
+
+```js
+await player.setAutoCaptionMode("ru"); // Web Component, из действия пользователя
+const { mode, loading, progress, error, videoOnly } =
+  player.autoCaptionPresentation;
+player.addEventListener("yp-captionpresentationchange", (event) => {
+  console.log(event.detail); // readonly AutoCaptionPresentation; progress 0…100/null
+});
+await player.setAutoCaptionMode("original"); // сохраняет работающий ASR и playback
+await player.setAutoCaptionMode("off"); // отменяет загрузку, распознавание и перевод
+```
+
+Переводчик OPUS en→ru WASM q8 загружается отдельно (~118 МБ моделей) только при
+выборе русского режима. Это эксперимент: ошибки ASR переходят в перевод, смысл,
+отрицания и имена могут теряться. Перед Play дождитесь подготовки моделей:
+пропущенный во время загрузки звук не распознаётся задним числом.
+При ошибке перевода доступен оригинал и «Повторить»; «Выкл» отменяет подготовку.
+В PiP native video показывает оригинал, перевод остаётся в окне плеера.
+
+Опубликованные слова не переписываются: новые дополняют строку справа, заполненная
+строка поднимается вверх. Максимум две строки, подложка по словам строки или самой
+длинной строке карточки. Все три оформления доступны оригиналу и русскому.
+Стабилизация и подавление overlap — ограниченные текстовые эвристики, не гарантия
+смысла или полноты. Явная смена размера/оформления может переразложить текущий текст.
+
+Модель [Xenova/opus-mt-en-ru](https://huggingface.co/Xenova/opus-mt-en-ru) закреплена
+на revision `e050376e960175e8ddc5cff85025dc8436cddd68`; исходная
+[Helsinki-NLP модель](https://huggingface.co/Helsinki-NLP/opus-mt-en-ru) — Apache-2.0.
+Worker и WASM поставляются в пакете, веса скачиваются с Hugging Face в браузер.
+Для CSP нужны разрешения загрузки моделей с Hugging Face и его download/CDN origins,
+Worker и WASM так же, как для ASR. Аудио и текст остаются на устройстве.
+Использование translation pipeline и pinned revision соответствует
+[официальному API Transformers.js](https://huggingface.co/docs/transformers.js/pipelines).
+
+Headless `/core` сохраняет API распознавания ниже: режимы перевода и rolling DOM
+предоставляет Web Component. Существующий `setAutoCaptions(boolean)` совместим:
+включение из Off даёт оригинал; выключение останавливает также перевод.
+
+Если доступной готовой дорожки нет, раздел «Субтитры» предлагает «Выкл / Оригинал / Русский».
+Речь распознаётся на устройстве. Русский режим переводит только английскую речь;
+автоматического определения языка для перевода нет. Видео продолжает играть;
+текст появляется с задержкой и может содержать ошибки. Это экспериментальная функция:
+точность маленькой модели уступает подготовленным субтитрам, реальные телефоны ещё не проверены.
+
+```js
+await player.setAutoCaptions(true); // также runtime в /core; вызывать из действия пользователя
+const { available, reason, status, progress, error, backend, latencySeconds } =
+  player.runtime.getSnapshot().autoCaptions;
+await player.setAutoCaptions(false); // немедленная отмена загрузки/захвата/распознавания
+```
+
+Статусы: `off`, `loading`, `listening`, `error`; progress — 0…1 или null.
+Причины недоступности: `source` (нет готового source/anchor), `tracks` (есть готовые субтитры),
+`browser` (нет secure context/captureStream/AudioWorklet/Worker/WASM). Клавиша C также
+переключает распознавание, когда готовых субтитров нет. Ошибка допускает повтор и не останавливает видео.
+Source change сбрасывает автосубтитры в Off; профиль не сохраняет включение или распознанный текст.
+Seek, смена аудио/скорости очищают старый результат. Пауза сохраняет текущий текст по media clock.
+
+Загрузка только после явного включения: около 75–100 МБ при первом использовании, включая движок,
+модели Whisper tiny и Silero VAD; дальнейшие загрузки зависят от browser cache.
+При доступном GPU используется WebGPU encoder fp32 + WASM decoder q8 (`backend: "gpu"`),
+иначе — WASM q8 (`"cpu"`; до подготовки/после Off — null). Прогрев входит в подготовку.
+После ошибки GPU CPU запускается в новом worker; облачного fallback нет.
+Быстрый режим распознаёт растущий контекст до 6 с, обновляет предварительный текст и отправляет
+остаток после короткой паузы в речи. Следующая гипотеза уточняет строку без повторного вывода
+уже показанного префикса. CPU использует более редкие блоки, чтобы не накапливать работу.
+Задержка зависит от устройства, языка и речи; секунда после конца фразы не гарантируется.
+`latencySeconds` сохраняет возраст начала аудио в последней показанной гипотезе. Для растущего
+контекста это не задержка новых слов или конца фразы; UI не показывает это число в быстром режиме.
+Whisper и VAD закреплены на конкретных revisions. Одна операция распознавания и один ожидающий
+фрагмент; при отставании старый звук отбрасывается, длительное отставание показывает ошибку.
+Аудио/текст не отправляются с устройства; микрофон и захват экрана не используются.
+Необходим доступ браузера к звуку media, включая CORS; Safari без captureStream недоступен.
+
+Для прямого использования dist сохраните `auto-captions/` рядом с JS entries. Bundler находит
+worker/worklet/WASM через `auto-captions/assets.js`. CSP: `worker-src 'self'`,
+`script-src 'self' 'wasm-unsafe-eval'`; `connect-src` должен разрешать собственные assets,
+`https://huggingface.co`, его домены загрузки весов (например `https://cas-bridge.xethub.hf.co`)
+и `https://raw.githubusercontent.com` для VAD. Облачного fallback нет.
+Сгенерированные native cues используют существующие presets/delay и предупреждение video-only PiP/fullscreen.
+
+Focused lifecycle/UI проверка после сборки: `npm run check:auto-captions`.
+Она использует настоящий capture/worklet и контролируемый worker; результаты настоящей модели,
+качество и измерения на устройствах проверяются отдельно в локальном demo.
+
+### Платформа
+
+PiP доступен на панели desktop и в дополнительных настройках compact, если его поддерживает
+текущий media path. Fullscreen/PiP вызываются через публичные методы foundation Video.js;
+snapshot читает их фактическое состояние. Меню fullscreen остаются внутри плеера.
+Для headless задайте `container` в createPlayer, иначе используется родитель video.
+
+```js
+player.platform = {
+  wakeLock: true,
+  mediaSession: true,
+  orientation: "landscape",
+};
+// Вызывать из пользовательского действия после проверки capabilities:
+await player.enterFullscreen();
+await player.exitFullscreen();
+await player.requestPictureInPicture();
+await player.exitPictureInPicture();
+```
+
+Wake lock и Media Session включены по умолчанию. Landscape lock опционален и ограничен
+fullscreen; отказ не прерывает видео. Wake lock удерживается при видимом playback и освобождается
+при pause/ended/hidden/source replacement/dispose. Browser denial виден в `snapshot.platform.error`;
+новое Play или возвращение видимости разрешает новую попытку wake lock, без постоянных retries.
+
+Последний плеер, начавший playback, владеет Media Session. Title и `source.metadata`
+(artist/album/artwork) попадают в системный интерфейс; play/pause/stop/seek/previous/next
+используют runtime. Stop ставит на паузу. Seek и position state используют absolute timeline.
+`mediaSession: false` отключает эту интеграцию. Dispose старого владельца не очищает нового.
+
+`snapshot.platform` содержит fullscreen/pictureInPicture/wakeLock/orientationLocked/
+mediaSessionActive/pending/error; capability flags и причины доступны в `snapshot.capabilities`.
+Ошибки платформы не заменяют playback error. `snapshot.preservesPitch` отражает browser property;
+`setPreservesPitch(boolean)` и checkbox в настройках скорости/compact управляют высотой голоса.
+Rate/volume/mute обновляются по media events, включая изменения вне controls.
+
+PiP и системный video fullscreen могут не показывать DOM/canvas captions. Для styled ASS
+используйте inline или container fullscreen; отображается предупреждение. WebKit path использует
+публичную поддержку foundation. Native Safari, системный PiP, orientation и реальные устройства
+требуют отдельной проверки; Chromium doubles подтверждают lifecycle, а не работу системного UI.
+
+### Настройки приложения
+
+Библиотека не использует localStorage и не знает об аккаунтах. Приложение передаёт адаптер:
+
+```js
+const adapter = {
+  async load({ signal }) {
+    return profileStore.load({ signal }); // PlayerPreferences или null
+  },
+  async save(preferences, { signal }) {
+    await profileStore.save(preferences, { signal });
+  },
+};
+await player.setPreferences(adapter);
+```
+
+В React передавайте стабильный объект через `preferences={adapter}`; в headless —
+createPlayer({ media, preferences: adapter }). setSource ждёт начальную загрузку.
+`SourceOptions.trackPreferences` перекрывает languages/forced/SDH профиля для этого source. Выбор дорожки
+сохраняет language/forced/SDH или Off, без ID; local file и его содержимое не сохраняются.
+
+PlayerPreferences: volume 0…1, muted, playbackRate 0.1…4 (применяется только поддерживаемый),
+preservesPitch, tracks: TrackPreferences, captionStyle и captionDelaySeconds −60…60.
+Defaults нового профиля: volume 1, unmuted, 1×, pitch on, captions Off, исходный стиль и delay 0.
+Временное ограничение rates у source включает 1×; preferred rate возвращается на следующем
+поддерживаемом source. Весь загруженный record проверяется до применения; unknown keys запрещены.
+
+Записи объединяются и выполняются последовательно. `snapshot.preferences` сообщает
+idle/loading/ready/saving/error и безопасное сообщение. После load error повторите
+setPreferences(adapter); после save error новое изменение параметра повторяет запись.
+Смена адаптера или setPreferences() отменяет прежние load/save и сбрасывает профиль.
+Host обязан соблюдать AbortSignal и привязывать операции адаптера к конкретному аккаунту;
+серверные изменения, уже принятые до abort, разрешает приложение. Source/history меняет приложение.
+На dispose незавершённая запись отменяется; для гарантированного сохранения при закрытии host
+может наблюдать snapshot и реализовать собственный lifecycle. Телеметрии внутри библиотеки нет.
+
+### Главы и миниатюры
+
+`source.chapters` — до 500 глав с возрастающими absolute `startSeconds` и title (до 200 символов).
+Пункт «Главы» в desktop настройках скорости и раздел compact появляются только при наличии
+данных и позволяют переходить с keyboard/touch через обычный seek. Отдельной кнопки на панели нет.
+Локально недоступные главы disabled; host seek может открыть главу вне текущего окна.
+Главы передаёт приложение: библиотека не извлекает их из видео и не создаёт из torrent/magnet.
+При наличии глав в контейнере backend может извлечь их и передать через этот API.
+
+```js
+source.chapters = [
+  { startSeconds: 0, title: "Начало" },
+  { startSeconds: 120, title: "Глава 2" },
+];
+player.thumbnail = async ({ source, seconds, signal }) => {
+  return thumbnails.resolve(source.id, seconds, { signal }); // { src } или null
+};
+```
+
+UI запрашивает descriptor сразу при наведении/перемотке, в том числе во время движения; старый запрос
+отменяется при уходе указателя, source replacement, смене resolver или dispose. При отказе остаётся
+временная метка. URL должен быть http/https/blob без credentials. Источники картинок выбирает host;
+никакого автоматического сканирования видео или torrent нет. Headless использует
+getThumbnail(seconds, signal), `snapshot.chapters` и seek. Для headless callback задаётся через
+options.thumbnail или setThumbnailResolver; navigation — через options.navigation/setNavigation.
+Предыдущая миниатюра остаётся до декодирования новой; отменённый ответ не меняет картинку.
+Точность и скорость первого появления зависят от подготовленных host кадров и их доставки.
+
+Распознавание речи и автоматический перевод библиотека не выполняет. Автоматический выбор языка
+выбирает готовую дорожку. Chrome Live Caption/Live Translate — отдельные функции браузера с
+собственной панелью; их текст и оформление не управляются API субтитров плеера.
+
+## Headless API
+
+| Import                    | Содержимое                                                            |
+| ------------------------- | --------------------------------------------------------------------- |
+| @yaneart/yaneplayer       | Авто-регистрация элемента, YanePlayerElement, version, публичные типы |
+| @yaneart/yaneplayer/core  | createPlayer, version и типы; без UI registration                     |
+| @yaneart/yaneplayer/react | Только опциональные JSX declarations, type-only import                |
+
+Оба JS entry безопасно импортируются без DOM при SSR. Создание runtime/элемента — browser-only.
+SSR выводит custom tag; клиентский import выполняет upgrade. Повторные imports/HMR не
+регистрируют tag повторно; изменение самого класса при HMR требует reload страницы.
+
+```ts
+import { createPlayer, type PlayerSource } from "@yaneart/yaneplayer/core";
+
+const source: PlayerSource = {
+  id: "example",
+  revision: "1",
+  kind: "mp4",
+  src: "/video.mp4",
+};
+const player = createPlayer({ media: document.querySelector("video")! });
+await player.setSource(source);
+await player.play(); // из пользовательского действия
+await player.pause();
+player.dispose();
+```
+
+getSnapshot() возвращает стабильный readonly snapshot; subscribe(listener) возвращает unsubscribe.
+Независимы playback, pending с commandId и последний intent. positionSeconds/durationSeconds
+могут быть null. Не записывайте pending target в историю просмотра. dispose идемпотентен;
+отменённые/замещённые операции отклоняются с AbortError.
+
+## Host и timeline
+
+Начальный выбор дорожек задаётся без ID, действующих только внутри source/revision:
+
+```js
+await player.setSource(source, {
+  trackPreferences: {
+    audioLanguages: ["ru", "en"],
+    text: { languages: ["ru", "en"], forced: false, sdh: true },
+  },
+});
+```
+
+Для каждого языка по порядку выбирается точное совпадение без учёта регистра, затем
+основной язык (`en-GB` → `en`); DEFAULT разрешает равные варианты. Forced/SDH — строгие
+фильтры. Без совпадения остаются текущая озвучка и выключенные субтитры. Без `text` или
+с `text: null` субтитры выключены даже для DEFAULT/FORCED. Без `audioLanguages` сохраняется
+выбор транспорта. Передайте сохранённые языки при загрузке следующего источника;
+библиотека сама не читает и не записывает localStorage, cookies или аккаунт.
+
+Snapshot и оба вида меню показывают предоставленные channels/default/forced/SDH/description/
+codec/format. HLS получает метаданные из manifest, native media — только доступные browser
+данные. Host может объявить `available: false, unavailableReason: "…"`: пункт виден с причиной,
+но недоступен для UI и API. При отсутствии controller показывается отсутствие выбора.
+После сборки `npm run check:tracks` проверяет preferences, metadata, async host и recovery
+изолированно, без demo. Реальные HLS fixtures проверяются отдельно в локальном demo.
+
+`host: HostAdapter` реализует `execute(command, context)`. Source отдельно объявляет поддерживаемые
+controllers в `capabilities` и доступные `audioTracks`, `textTracks`, `qualities`.
+Сам callback не включает capability. Host не получает media engine, account DTO или route из библиотеки.
+
+| Значение         | Назначение                                                                        |
+| ---------------- | --------------------------------------------------------------------------------- |
+| `command.type`   | `seek`, `audio`, `text` или `quality`, с `seconds`/`id`                           |
+| `command.target` | Последняя совокупная цель: position/audio/text/quality                            |
+| `context`        | sourceId/revision/commandId/signal, подтверждённая positionSeconds; getter intent |
+| Результат        | `{source?, selection?}` после готовности и подтверждения host                     |
+
+Очередь сериализует mutations и объединяет быстрые изменения по полям `target`.
+Host обязан применять всю цель, соблюдать version/idempotency и доводить admission до ready.
+Abort отменяет ожидание клиента; host самостоятельно согласует принятые server mutations.
+Следующий `execute` ждёт завершения предыдущего Promise, даже после abort. Ограничивайте ожидание
+и выполняйте reconciliation внутри adapter. `commandTimeoutMs` (по умолчанию 15000) ограничивает
+ожидание **media**, а не серверную транзакцию. Автоматического повтора host mutations нет.
+
+Replacement сохраняет source id, меняет revision и содержит фактические timeline anchors:
+
+```ts
+const timeline = {
+  mode: "windowed-vod" as const,
+  absoluteAnchorSeconds: 599,
+  mediaAnchorSeconds: 0,
+  durationSeconds: 7200,
+};
+```
+
+Абсолютная позиция = `absoluteAnchorSeconds + media.currentTime - mediaAnchorSeconds`.
+После запроса 600 с anchor 599 означает фактический старт 599 с. Host возвращает actual anchors,
+а не requested offset. Seek внутри реальных local ranges остаётся local, за пределами требует
+объявленного `seek: "host"`. Неизвестные anchors (`null`) отключают точный absolute seek.
+`timeline.seekableRanges` может ограничить реальные local ranges; duration `null` не угадывается.
+Track ids принадлежат source revision; replacement selection должна ссылаться на новые metadata.
+При replacement без server seek runtime восстанавливает прежнюю confirmed position, если
+она входит в новый локальный seekable range; иначе фактический anchor остаётся авторитетным.
+Host подтверждает host-managed selections в `result.selection`; транспортные audio/text
+восстанавливаются по metadata. Последний play/pause intent, rate/volume/mute сохраняются.
+
+## Transport и requests
+
+HLS `hlsPlayback: "auto"` (default) предпочитает MSE/hls.js и использует native fallback;
+`"mse"`/`"native"` явно выбирают путь. Capabilities пересекают descriptor, transport и браузер.
+Auto quality появляется только для настоящей ABR ladder. Скорости ограничиваются
+`source.capabilities.playbackRates`; volume зависит от устройства.
+
+Для MSE можно задать `request: {allowedOrigins, credentials?, headers?}`.
+Проверяются manifests, segments, keys и subtitle requests. Redirects запрещены.
+Headers и credentials отправляются только исходному origin; другие разрешённые origins получают
+запросы без них. По умолчанию нет auth headers, credentials — same-origin, разрешены origin страницы
+и исходного manifest. Buffers ограничены; dispose/source change уничтожают transport и запросы.
+
+MP4/native HLS используют browser CORS/auth (`crossOrigin="anonymous"`) и не поддерживают
+произвольные JS headers или строгий контроль redirects/nested origins. Descriptor с `request`
+для native path отклоняется. Для такого playback host предоставляет browser-compatible URL/auth;
+не используйте `request`, если строгая проверка origin/redirect не нужна.
+
+С 0.1.1 `source.crossOrigin: "use-credentials"` включает browser cookies для native media
+и credentials только исходного HLS origin в MSE. Cross-origin сервер должен разрешить
+конкретный origin приложения и credentials; браузерная cookie policy продолжает действовать.
+Это browser-compatible auth без строгой `request` policy: native transport не контролирует
+redirect/nested origins. Для строгой политики используйте `request` и MSE.
+
+Preferences adapter и platform API описаны в разделе «Платформа» выше.
+
+## Субтитры и локальные файлы
+
+Меню дорожек → «Настройки субтитров» (на телефоне — раздел «Субтитры» общей панели) открывает
+единый раздел выбора дорожки/Off. Для активного native text доступны три пресета: «Контур»
+(белый текст с обводкой без фона, default), «Подложка» (белый текст на полупрозрачном тёмном фоне)
+и «YaneMedia» (Manrope SemiBold, светлый текст, скруглённая тёмная
+подложка с синими уголками). Цвет акцента и шрифт используют tokens темы плеера.
+Это UI-карточка поверх активных browser cues; timing и выбор дорожки остаются native.
+Авторские positioned/vertical/region cues, недостаток места и headless используют native fallback.
+ASS/SSA сохраняет авторское оформление, presets для него скрыты. «Синхронизация» свёрнута
+по умолчанию и позволяет менять задержку или сбросить её в 0; burn-in настраивает источник.
+
+Встроенный UI не содержит загрузки файлов, редактора оформления и переключателя тональности
+голоса. Тональность сохраняется по умолчанию; host может изменить это через публичный API.
+Загрузка локальных файлов и полная настройка остаются API библиотеки для приложений.
+Файлы остаются на устройстве: библиотека их не загружает на сервер.
+
+```ts
+await player.loadSubtitles(file); // File: .vtt, .srt, .ass или .ssa, UTF-8
+await player.setCaptionDelay(0.5); // положительное значение показывает позже
+await player.setCaptionStyle({
+  fontScale: 1.25,
+  color: "#ffff00",
+  background: "transparent",
+});
+await player.selectText(null); // Off; останавливает загрузку/renderer
+await player.removeLocalSubtitles();
+```
+
+Те же методы есть в headless runtime. Локальный файл заменяет предыдущий локальный файл;
+формат, размер и UTF-8 проверяются перед заменой. Новая `setSource` очищает файл, host replacement
+того же source сохраняет его вместе с confirmed position/intent/rate и caption settings.
+Дорожки источника описываются отдельно от host metadata:
+
+```ts
+const source: PlayerSource = {
+  id: "movie",
+  revision: "1",
+  kind: "mp4",
+  src: "/movie.mp4",
+  subtitles: [
+    {
+      id: "ru",
+      label: "Русский",
+      language: "ru",
+      format: "srt",
+      src: "/ru.srt",
+    },
+    {
+      id: "styled",
+      label: "ASS",
+      format: "ass",
+      src: "/styled.ass",
+      fonts: [{ src: "/fonts/allowed.woff2" }],
+    },
+  ],
+};
+await player.setSource(source); // captions Off по умолчанию
+await player.selectText("subtitle:ru");
+```
+
+Snapshot IDs для sidecar имеют префикс `subtitle:`; `subtitle:local` зарезервирован для файла.
+Transport/host IDs сохраняют прежний смысл. Если host управляет text selection, переход на
+sidecar сначала подтверждает host Off. Host-rendered/burn-in captions нельзя оформить или
+сдвинуть в браузере: интерфейс объясняет ограничение и предлагает текстовую дорожку/файл.
+Языковые preferences применяются к sidecar тем же способом, что и к транспортным дорожкам.
+
+Таймкоды sidecar/local абсолютные: `media cue = absolute cue − timeline offset + delay`.
+Встроенные transport cues уже находятся в media time, к ним применяется только delay.
+Неизвестный anchor делает sidecar/local недоступными с причиной. Delay — от −60 до +60 секунд;
+style: `fontScale` .75..2, `color` #RRGGBB, `background` #RRGGBB/#RRGGBBAA/`transparent`,
+`edge` `outline | shadow | none`. `snapshot.captions` содержит настройки, renderer, status и warning.
+Optional `presentation: "native" | "card"` включает rounded card в готовом UI (default native).
+В native video-only fullscreen/PiP остаётся стандартное ограничение DOM overlay.
+Оформление применяется к native text. ASS/SSA сохраняет авторские стили; native style
+предпочтение остаётся для следующей текстовой дорожки. Settings сохраняются в runtime, без storage.
+
+Text использует браузерный WebVTT parser/renderer; SRT преобразуется в VTT. Cue payload
+не вставляется в DOM как HTML. Сохраняются overlap и cue positioning. ASS/SSA лениво включает
+JASSUB 2.5.23, worker/WASM и Liberation Sans; online/local font queries выключены.
+Необходимы Workers, OffscreenCanvas, WASM и native video frame callbacks. Без них ASS помечается
+недоступным. PGS/VobSub — видимые disabled options: нужен host burn-in или текстовая альтернатива.
+Библиотека сама не выполняет OCR и не создаёт burn-in поток.
+
+Ресурсы ограничены: VTT/SRT ≤5 MiB/100000 cues, ASS ≤10 MiB/100000 events;
+до 8 явно заданных fonts, каждый ≤5 MiB (включая заявленный decoded WOFF размер), всего ≤20 MiB,
+плюс фиксированный fallback font. Поддерживаются TTF/OTF/WOFF/WOFF2; embedded ASS Fonts/Graphics
+отклоняются. Каждый subtitle/font resource может иметь собственный `request` с allowedOrigins,
+credentials и headers. Cookies по умолчанию только same-origin; redirects запрещены,
+загрузка ограничена streaming byte limit и `commandTimeoutMs`. HTTP(S) ресурсы требуют CORS.
+
+При прямом использовании `dist` сохраните дерево `subtitles/` рядом с JS entries.
+Для bundler статические URL в `subtitles/assets.js` позволяют перенести worker/WASM/font;
+проверены Vite dev и production. CSP для ASS дополнительно требует `worker-src 'self'`,
+`script-src 'self' 'wasm-unsafe-eval'` и разрешённый `connect-src`; для text — `media-src blob:`.
+`style-src 'self'` работает без unsafe-inline. COOP/COEP не обязательны; при isolation JASSUB
+использует ограниченный пул до 8 pthread workers, без isolation — один renderer worker.
+
+Container fullscreen сохраняет ASS canvas. Системные video fullscreen/PiP могут не показать
+DOM/canvas captions: интерфейс предупреждает об ограничении и предлагает inline/container
+fullscreen. Native text выводит браузер; Safari/реальные устройства/AT и system captions требуют
+ручной проверки. Незаметного ASS → plain text downgrade нет.
+
+После сборки `npm run check:subtitles` проверяет parsing/resources, реальные text/ASS pixels,
+absolute timing, host replacement, pending/error/retry и cleanup изолированно от demo.
+`node tests/subtitles.mjs --isolated` проверяет тот же путь под COOP/COEP.
+JASSUB/WASM и fallback font берутся из установленного npm-пакета `jassub`.
+Архивы сторонних исходников в пакет не включаются. Файлы лицензий npm-зависимостей
+сборка копирует в `dist/licenses/`.
+Состав и изменения стороннего кода перечислены в [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
+## Тема
+
+```css
+yane-player {
+  --yp-accent: #a6e3a1;
+  --yp-radius: 8px;
+  --yp-font-family: system-ui, sans-serif;
+}
+```
+
+Доступны также `--yp-text`, `--yp-surface`, `--yp-control-size` (default48px/minimum44px),
+`--yp-accent-text` и `--yp-pattern`. По умолчанию Manrope Variable, radius24px,
+accent#315fbd и accent-text#6f94df, графит#101112/#191a1b/#222325 и текст#f1f0ec.
+Стили controls изолированы в Shadow DOM. Reduced motion отключает переходы.
+Auto styles используют constructable stylesheets/adoptedStyleSheets в современных браузерах.
+Проверена CSP `style-src 'self'` без unsafe-inline; host задаёт разрешённые media/connect origins.
+
+`--yp-pattern: url('/brand-pattern.svg')` добавляет декоративную текстуру на подложки меню.
+Изображение предоставляет приложение; по умолчанию текстуры нет. Для небольшого знака
+поверх видео используйте слот `watermark`:
+
+```html
+<yane-player src="/video.mp4">
+  <img slot="watermark" src="/brand-mark.svg" alt="" />
+</yane-player>
+```
+
+## Разработка
+
+Node 24, npm 11. В Windows PowerShell используйте `npm.cmd`, если запуск `npm.ps1` запрещён.
+
+`npm run format` форматирует исходники, тесты, конфиги и README через Prettier 3.9.10;
+`npm run format:check` проверяет стиль без изменений. Используются стандартные настройки
+Prettier: 2 пробела, двойные кавычки, LF. Сборки, зависимости, lockfile и сторонние лицензии
+исключены. Локальный стенд имеет свои аналогичные команды и установку Prettier.
+
+```sh
+npm ci
+npm run build
+npm run check:runtime
+npm run check:package
+npm pack
+```
+
+`build` собирает ESM, declarations, embedded CSS и лицензии в `dist/`.
+`check:runtime` проверяет очередь mutations: coalescing, serialization, cancellation и late replies.
+`check:package` устанавливает tarball в изолированные consumers и проверяет core без DOM/React,
+SSR, публичные типы и production consumers HTML/React/Vue/Angular. Нужен Playwright Chromium;
+framework consumers устанавливают exact dependencies через npm (первый запуск требует сеть).
+Для focused проверки общего UI используйте `npm run check:package -- --frameworks=html`:
+production HTML consumer проверяет desktop controls, host seek и lifecycle под CSP;
+общие SSR/публичные типы/React JSX также проверяются, Vue/Angular не запускаются.
+`npm pack` повторно собирает библиотеку и создаёт tarball; публикация не выполняется.
+
+Для публикации версии `0.1.0` владелец пакета выполняет из корня проекта:
+
+```sh
+npm publish
+```
+
+В PowerShell — `npm.cmd publish`. Публичный доступ задан через `publishConfig.access`.
+После публикации yaneMedia подключает эту версию командой
+`npm install @yaneart/yaneplayer@0.1.0 --save-exact`.
+
+```text
+src/core/       TypeScript core
+src/element.ts  общий Web Component
+src/ui/         controls, локальные labels/icons, native VTT layout
+src/react.d.ts  опциональные JSX declarations
+src/styles.css  тема
+scripts/        подготовка файлов пакета
+tests/          проверки библиотеки и публичных exports
+```
+
+В npm-пакет входят `dist`, README, GUIDE и [MIT LICENSE](./LICENSE).
+Исходники, тесты и настройки сборки остаются в Git.