feat(room): закрепление участника и слежение основного окна за говорящим

Правила выбора фокуса сцены (`pickStageFocus`) дополнены двумя входами: - `pinnedKey` — участник, закреплённый булавкой на плитке. Держит фокус вопреки говорящим, но уступает любой активной демонстрации экрана; как только демонстрация закончилась, фокус возвращается именно на закреплённого (правило стоит выше удержания предыдущего фокуса). Состояние — в `RoomStage`, повторное нажатие снимает, выход закреплённого из комнаты тоже. Закреплённая плитка помечена рамкой и подсвеченной булавкой; на тач-устройствах булавка видна без наведения. - `holdScreenShare` — живая демонстрация в фокусе не уступает заговорившему (основное окно). PiP не затронут: там по-прежнему всегда виден говорящий. Основное окно теперь следует за говорящим (`followSpeaker`) поверх `useSpeakingParticipants()` вместо дребезжащего `participant.isSpeaking`, с удержанием состава в 1.2 с (`useSteadySpeakers`) — короткие реплики фокус не уводят. Среди одновременно говорящих предпочитается тот, у кого включена камера (`cameraKeysWithVideo`). `stageTrackKey` переехал в `stageFocus.ts` — ключ плитки нужен и сцене, и самой плитке (в карусели/гриде она рендерится шаблоном, без пропсов).
2026-07-27 01:31:42 +03:00
parent 28b87a8c95
commit 5daff3b7af
4 changed files with 336 additions and 78 deletions
--- a/frontend/src/components/room/RoomParticipantTile.tsx
+++ b/frontend/src/components/room/RoomParticipantTile.tsx
@@ -1,4 +1,4 @@
-import { ScreenShare } from 'lucide-react'
+import { Pin, PinOff, ScreenShare } from 'lucide-react'
 import { Track } from 'livekit-client'
 import {
  AudioTrack,
@@ -19,6 +19,7 @@ import {
  type TrackReferenceOrPlaceholder,
 } from '@livekit/components-react'
 import { Avatar } from '@/components/ui/Avatar'
+import { stageTrackKey } from '@/components/room/stageFocus'

 /** Метаданные участника из LiveKit access-токена (см. `AccessToken.with_metadata` на backend) — JSON `{"avatar_url": "..."}`; у гостей отсутствуют. */
 interface ParticipantMetadata {
@@ -43,7 +44,7 @@ function parseAvatarUrl(metadata: string | undefined): string | null {
 * разметке (см. `node_modules/@livekit/components-react/src/components/participant/ParticipantTile.tsx`,
 * версия 2.9.23 — источник этой копии).
 */
-function TileBody({ onStopSharing }: { onStopSharing?: () => void }) {
+function TileBody({ onStopSharing, pinnedKey, onTogglePin }: TileControlsProps) {
  const trackReference = useEnsureTrackRef()
  const isEncrypted = useIsEncrypted(trackReference.participant)
  const autoManageSubscription = useFeatureContext()?.autoSubscription
@@ -60,6 +61,12 @@ function TileBody({ onStopSharing }: { onStopSharing?: () => void }) {
  const showSharingChip = Boolean(
    onStopSharing && trackReference.source === Track.Source.ScreenShare && trackReference.participant.isLocal,
  )
+  // Кнопка закрепления — только там, где сцена умеет закрепление (основное
+  // окно передаёт `onTogglePin`; в мини-плеере плитка одна, закреплять нечего).
+  // Ключ плитки берём из её собственного трека: в карусели/гриде плитки
+  // рендерятся шаблоном без пропсов, снаружи «какая это плитка» не передать.
+  const tileKey = stageTrackKey(trackReference)
+  const isPinned = pinnedKey === tileKey

  return (
    <>
@@ -106,6 +113,25 @@ function TileBody({ onStopSharing }: { onStopSharing?: () => void }) {
        <ConnectionQualityIndicator className="lk-participant-metadata-item" />
      </div>
      <FocusToggle trackRef={trackReference} />
+      {onTogglePin && (
+        <button
+          type="button"
+          className={`room-pin-toggle${isPinned ? ' is-pinned' : ''}`}
+          aria-pressed={isPinned}
+          title={isPinned ? 'Открепить' : 'Закрепить в основном окне'}
+          aria-label={
+            isPinned ? `Открепить: ${displayName}` : `Закрепить в основном окне: ${displayName}`
+          }
+          onClick={(e) => {
+            // Иначе клик долетит до самой плитки (`onParticipantClick`
+            // у `ParticipantTile`) — булавка не должна означать «клик по плитке».
+            e.stopPropagation()
+            onTogglePin(tileKey)
+          }}
+        >
+          {isPinned ? <PinOff aria-hidden="true" /> : <Pin aria-hidden="true" />}
+        </button>
+      )}
      {showSharingChip && (
        <div className="stage-sharing-chip">
          <ScreenShare className="lucide" aria-hidden="true" />
@@ -119,10 +145,8 @@ function TileBody({ onStopSharing }: { onStopSharing?: () => void }) {
  )
 }

-interface RoomParticipantTileProps {
-  trackRef?: TrackReferenceOrPlaceholder
-  disableSpeakingIndicator?: boolean
-  onParticipantClick?: (event: ParticipantClickEvent) => void
+/** Управляющие элементы поверх плитки — общие для обёртки и её `TileBody`. */
+interface TileControlsProps {
  /**
   * Остановить демонстрацию экрана — если передано, при рендере СВОЕЙ активной
   * демонстрации (Track.Source.ScreenShare + `participant.isLocal`) поверх
@@ -131,6 +155,23 @@ interface RoomParticipantTileProps {
   * в этом приложении не появляется (см. `RoomStage.tsx`).
   */
  onStopSharing?: () => void
+  /**
+   * Ключ закреплённой сейчас плитки (`identity:source`, см. `stageTrackKey`) —
+   * плитка сравнивает его со своим и подсвечивает булавку/рамку.
+   */
+  pinnedKey?: string | null
+  /**
+   * Закрепить/открепить эту плитку в основном окне. Передаёт свой ключ
+   * (плитки в карусели/гриде рендерятся шаблоном, снаружи их не различить).
+   * Не передан — кнопки-булавки на плитке нет (мини-плеер: плитка одна).
+   */
+  onTogglePin?: (key: string) => void
+}
+
+interface RoomParticipantTileProps extends TileControlsProps {
+  trackRef?: TrackReferenceOrPlaceholder
+  disableSpeakingIndicator?: boolean
+  onParticipantClick?: (event: ParticipantClickEvent) => void
 }

 /**
@@ -142,15 +183,20 @@ interface RoomParticipantTileProps {
 * собственного токена), и для удалённых.
 *
 * Пин-логика оригинала (`handleSubscribe`/сброс пина при отписке от трека)
- * сознательно опущена — приложение пока нигде не создаёт `LayoutContext`
- * (пиннинг плиток не реализован), поэтому в оригинале эта ветка и так была
- * мёртвым кодом без провайдера контекста.
+ * сознательно опущена — приложение нигде не создаёт `LayoutContext`, поэтому
+ * в оригинале эта ветка и так была мёртвым кодом без провайдера контекста (по
+ * той же причине ничего не рисует и штатный `FocusToggle` ниже). Своё
+ * закрепление участника (задача 3.1) сделано мимо `LayoutContext`: состояние —
+ * в `RoomStage`, кнопка — `.room-pin-toggle` здесь, выбор фокуса —
+ * `pickStageFocus`.
 */
 export function RoomParticipantTile({
  trackRef,
  disableSpeakingIndicator,
  onParticipantClick,
  onStopSharing,
+  pinnedKey,
+  onTogglePin,
 }: RoomParticipantTileProps) {
  return (
    <ParticipantTile
@@ -158,7 +204,7 @@ export function RoomParticipantTile({
      disableSpeakingIndicator={disableSpeakingIndicator}
      onParticipantClick={onParticipantClick}
    >
-      <TileBody onStopSharing={onStopSharing} />
+      <TileBody onStopSharing={onStopSharing} pinnedKey={pinnedKey} onTogglePin={onTogglePin} />
    </ParticipantTile>
  )
 }
--- a/frontend/src/components/room/RoomStage.tsx
+++ b/frontend/src/components/room/RoomStage.tsx
@@ -1,5 +1,5 @@
-import { useState } from 'react'
-import { Track } from 'livekit-client'
+import { useEffect, useState } from 'react'
+import { Track, type Participant } from 'livekit-client'
 import {
  CarouselLayout,
  FocusLayoutContainer,
@@ -12,7 +12,7 @@ import {
  type TrackReferenceOrPlaceholder,
 } from '@livekit/components-react'
 import { RoomParticipantTile } from '@/components/room/RoomParticipantTile'
-import { pickStageFocus } from '@/components/room/stageFocus'
+import { pickStageFocus, stageTrackKey } from '@/components/room/stageFocus'

 /**
 * Стабильная (модульная, не пересоздаётся на каждый рендер) ссылка на
@@ -39,9 +39,45 @@ const STAGE_TRACK_SOURCES = [
  { source: Track.Source.ScreenShare, withPlaceholder: false },
 ]

-/** Ключ трека для `pickStageFocus` — см. обоснование в `stageFocus.ts`. */
-function stageTrackKey(t: TrackReferenceOrPlaceholder): string {
-  return `${t.participant.identity}:${t.source}`
+/**
+ * Удержание фокуса основного окна при смене говорящего, мс.
+ *
+ * Основное окно следует за спикером (`followSpeaker`, задача 3.2), и без
+ * удержания короткие реплики («ага», «угу») уводили бы большую плитку на
+ * секунду и возвращали обратно. Источник говорящих (`useSpeakingParticipants`
+ * поверх `RoomEvent.ActiveSpeakersChanged`) сам по себе не дребезжит, но
+ * реплику длиной в полсекунды он честно отдаёт как смену состава.
+ *
+ * Значение подобрано от периода самого события: LiveKit пересчитывает активных
+ * спикеров примерно раз в 0.5 с, то есть короткая реплика — это 1–2 обновления.
+ * 1.2 с ≈ 2–3 обновления: блик до 1.2 с не проходит вовсе (значение успевает
+ * вернуться обратно, таймер перезапускается), а осмысленная фраза переключает
+ * фокус с задержкой, которая на глаз читается как плавность, а не как тормоз.
+ * Меньше (~0.6 с) — короткие «ага» всё ещё пролезают, больше (~2 с) — заметно
+ * запаздывает переход на нового докладчика.
+ */
+const SPEAKER_HOLD_MS = 1200
+
+/**
+ * Возвращает состав говорящих, «успокоенный» удержанием: новое значение
+ * применяется, только если оно продержалось `holdMs` без изменений. Короткая
+ * реплика меняет состав и возвращает его обратно раньше таймера — тогда
+ * применять уже нечего (cleanup эффекта гасит таймер, а новое значение
+ * сравнивается по ссылке с текущим).
+ *
+ * `holdMs <= 0` — удержания нет, значение отдаётся как есть (режим PiP: там
+ * фокус обязан следовать за говорящим мгновенно, поведение не менялось).
+ */
+function useSteadySpeakers(speakers: Participant[], holdMs: number): Participant[] {
+  const [steady, setSteady] = useState(speakers)
+
+  useEffect(() => {
+    if (holdMs <= 0 || speakers === steady) return
+    const timer = setTimeout(() => setSteady(speakers), holdMs)
+    return () => clearTimeout(timer)
+  }, [speakers, steady, holdMs])
+
+  return holdMs <= 0 ? speakers : steady
 }

 /**
@@ -75,23 +111,27 @@ function stageTrackKey(t: TrackReferenceOrPlaceholder): string {
 *
 * Проп `variant="pip"` — для рендера
 * ВНУТРИ мини-плеера (Document PiP, портал в `RoomPage.tsx`). В этом режиме
- * показываем ТОЛЬКО одну крупную плитку активного окна — без карусели/грида
- * — и фокус ЖИВО следует за активным спикером (см. `followSpeaker` у
- * `pickStageFocus`), а не удерживается, как в основном окне. Основной рендер
- * (`variant="full"`, дефолт) не меняется вовсе.
+ * показываем ТОЛЬКО одну крупную плитку активного окна — без карусели/грида.
+ *
+ * Фокус следует за активным спикером в ОБОИХ вариантах (`followSpeaker` у
+ * `pickStageFocus`; для основного окна — с 0.0.6, задача 3.2), но по-разному:
+ * PiP переключается мгновенно и всегда показывает говорящего, а основное окно
+ * ждёт `SPEAKER_HOLD_MS` (не дёргается на коротких репликах), не уводит из
+ * фокуса живую демонстрацию экрана (`holdScreenShare`) и умеет закрепление
+ * участника (`pinnedKey`, задача 3.1) — кнопка-булавка на плитке.
 */
 export function RoomStage({ variant = 'full' }: { variant?: 'full' | 'pip' }) {
  const room = useRoomContext()
  const tracks = useTracks(STAGE_TRACK_SOURCES, {
    onlySubscribed: false,
  })
-  // Только для PiP (см. followSpeaker ниже) — активные спикеры уже
-  // отсортированы SDK по громкости (`Room.activeSpeakers`, обновляются по
-  // `RoomEvent.ActiveSpeakersChanged`, событие шлётся лишь при РЕАЛЬНОЙ смене
-  // состава/порядка говорящих — не дребезжит на каждый чих, в отличие от
-  // сырого `participant.isSpeaking`). Хук вызывается безусловно (Rules of
-  // Hooks) — для `variant="full"` его результат просто не используется.
-  const speakingParticipants = useSpeakingParticipants()
+  // Активные спикеры уже отсортированы SDK по громкости
+  // (`Room.activeSpeakers`, обновляются по `RoomEvent.ActiveSpeakersChanged`,
+  // событие шлётся лишь при РЕАЛЬНОЙ смене состава/порядка говорящих — не
+  // дребезжит на каждый чих, в отличие от сырого `participant.isSpeaking`).
+  // Основное окно поверх этого ещё и удерживает состав (см. `useSteadySpeakers`
+  // и `SPEAKER_HOLD_MS`), PiP берёт значение как есть.
+  const speakingParticipants = useSteadySpeakers(useSpeakingParticipants(), variant === 'pip' ? 0 : SPEAKER_HOLD_MS)

  const cameraTracks = tracks.filter((t) => t.source === Track.Source.Camera)
  const screenShareTracks = tracks.filter((t) => isTrackReference(t) && t.source === Track.Source.ScreenShare)
@@ -121,47 +161,66 @@ export function RoomStage({ variant = 'full' }: { variant?: 'full' | 'pip' }) {
  // новый массив только когда реально что-то изменилось (см. комментарий у
  // `STAGE_TRACK_SOURCES` про стабильность ссылки).
  //
-  // Для PiP (`variant="pip"`) пересчёт триггерится ЕЩЁ и сменой
-  // `speakingParticipants` (тоже сравнение по ссылке — хук отдаёт новый
-  // массив только при реальном изменении состава/порядка говорящих), и
-  // передаётся `followSpeaker: true` — фокус живо переключается на нового
-  // спикера, а не удерживает прежний (см. правило 2 в `pickStageFocus`). Для
-  // основного окна (`variant="full"`) `speakingChanged` всегда `false` —
-  // поведение байт-в-байт то же, что было до этой правки.
+  // Пересчёт триггерится ещё и сменой `speakingParticipants` (тоже сравнение
+  // по ссылке — хук отдаёт новый массив только при реальном изменении состава/
+  // порядка говорящих), и сменой закрепления (`pinnedKey`) — оба входа
+  // `pickStageFocus` меняют результат без изменения самих треков.
  const [prevTracks, setPrevTracks] = useState(tracks)
  const [prevSpeakingParticipants, setPrevSpeakingParticipants] = useState(speakingParticipants)
  const [focusKey, setFocusKey] = useState<string | null>(null)
+  // Закрепление живёт в состоянии сцены (задача 3.1): ключ `identity:source`
+  // плитки, которую пользователь закрепил булавкой; `null` — закрепления нет.
+  // Только для основного окна — в PiP плитка одна и закреплять нечего.
+  const [pinnedKey, setPinnedKey] = useState<string | null>(null)
+  const [prevPinnedKey, setPrevPinnedKey] = useState<string | null>(null)
+
+  const cameraKeys = cameraTracks.map(stageTrackKey)
+  const screenShareKeys = screenShareTracks.map(stageTrackKey)
+  // Закреплённый участник вышел из комнаты (его ключа нет ни среди камер — а
+  // камера есть у КАЖДОГО участника хотя бы плейсхолдером, — ни среди
+  // демонстраций) — закрепление снимаем, чтобы сцена не осталась в подвешенном
+  // состоянии и булавка не «висела» на исчезнувшем ключе.
+  const pinnedAlive = pinnedKey !== null && (cameraKeys.includes(pinnedKey) || screenShareKeys.includes(pinnedKey))

  const tracksChanged = tracks !== prevTracks
-  const speakingChanged = variant === 'pip' && speakingParticipants !== prevSpeakingParticipants
+  const speakingChanged = speakingParticipants !== prevSpeakingParticipants
+  const pinnedChanged = pinnedKey !== prevPinnedKey

-  if (tracksChanged || speakingChanged) {
+  if (pinnedKey !== null && !pinnedAlive) {
+    setPinnedKey(null)
+  }
+
+  if (tracksChanged || speakingChanged || pinnedChanged) {
    const prevKeys = prevTracks.map(stageTrackKey)
    if (tracksChanged) setPrevTracks(tracks)
    if (speakingChanged) setPrevSpeakingParticipants(speakingParticipants)
-    // Источник «говорящих» — РАЗНЫЙ для основного окна и PiP, намеренно:
-    // здесь строго тот же расчёт, что был в основном окне ДО этой правки
-    // (`participant.isSpeaking`, без сортировки — фолбэк только на первый
-    // рендер, дребезг неважен, см. JSDoc правила 3/4 в stageFocus.ts), а для
-    // PiP — упорядоченный по громкости `speakingParticipants` (нужен именно
-    // порядок, чтобы взять самого громкого, и именно throttled-источник SDK,
-    // чтобы followSpeaker не дёргался на каждый чих).
-    const speakingCameraKeys =
-      variant === 'pip'
-        ? speakingParticipants
-            .map((p) => cameraTracks.find((t) => t.participant.identity === p.identity))
-            .filter((t): t is TrackReferenceOrPlaceholder => Boolean(t))
-            .map(stageTrackKey)
-        : cameraTracks.filter((t) => t.participant.isSpeaking).map(stageTrackKey)
+    if (pinnedChanged) setPrevPinnedKey(pinnedKey)
+    // Говорящие — упорядоченные по громкости камера-ключи: нужен именно
+    // порядок (взять самого громкого) и именно throttled-источник SDK
+    // (`useSpeakingParticipants`, в основном окне ещё и с удержанием), чтобы
+    // followSpeaker не дёргался на каждый чих. Сырой `participant.isSpeaking`,
+    // на котором основное окно жило до 0.0.6, дребезжит и для слежения за
+    // спикером не годится.
+    const speakingCameraKeys = speakingParticipants
+      .map((p) => cameraTracks.find((t) => t.participant.identity === p.identity))
+      .filter((t): t is TrackReferenceOrPlaceholder => Boolean(t))
+      .map(stageTrackKey)
    const result = pickStageFocus({
-      cameraKeys: cameraTracks.map(stageTrackKey),
-      screenShareKeys: screenShareTracks.map(stageTrackKey),
+      cameraKeys,
+      screenShareKeys,
      speakingCameraKeys,
+      // Приоритет «говорящий с камерой выше говорящего без камеры» — только
+      // основному окну: PiP по договорённости ведёт себя ровно как раньше.
+      cameraKeysWithVideo:
+        variant === 'pip'
+          ? []
+          : cameraTracks.filter((t) => isTrackReference(t) && !t.publication.isMuted).map(stageTrackKey),
      prevKeys,
      prevFocusKey: focusKey,
-      followSpeaker: variant === 'pip',
-      // Только для PiP — в основном окне фолбэк на «первый трек» не менялся
-      // (см. JSDoc про speakingChanged выше: поведение full-варианта не трогаем).
+      pinnedKey: pinnedAlive ? pinnedKey : null,
+      followSpeaker: true,
+      holdScreenShare: variant !== 'pip',
+      // Только для PiP — в основном окне фолбэк на «первый трек» не менялся.
      localKey: variant === 'pip' ? `${room.localParticipant.identity}:${Track.Source.Camera}` : null,
    })
    if (result.focusKey !== focusKey) {
@@ -192,6 +251,15 @@ export function RoomStage({ variant = 'full' }: { variant?: 'full' | 'pip' }) {
    void room.localParticipant.setScreenShareEnabled(false)
  }

+  /**
+   * Закрепить/открепить плитку: повторное нажатие на уже закреплённой снимает
+   * закрепление. Ключ приходит из самой плитки (она знает свой трек из
+   * контекста — в карусели/гриде плитки рендерятся шаблоном, без пропсов).
+   */
+  function handleTogglePin(key: string) {
+    setPinnedKey((prev) => (prev === key ? null : key))
+  }
+
  // Мини-плеер показывает ТОЛЬКО активное окно — без карусели/
  // грида, одна плитка на весь контейнер (см. `.room-single-tile`,
  // `styles/room.css`). `focusTrack` уже вычислен выше тем же `pickStageFocus`
@@ -209,17 +277,24 @@ export function RoomStage({ variant = 'full' }: { variant?: 'full' | 'pip' }) {
    <section className="stage">
      {!hasScreenShare && (!focusTrack || carouselTracks.length === 0) ? (
        <GridLayout tracks={tracks} className="stage-tiles">
-          <RoomParticipantTile />
+          <RoomParticipantTile pinnedKey={pinnedKey} onTogglePin={handleTogglePin} />
        </GridLayout>
      ) : (
        <FocusLayoutContainer className="stage-tiles">
          <CarouselLayout tracks={carouselTracks}>
-            <RoomParticipantTile />
+            <RoomParticipantTile pinnedKey={pinnedKey} onTogglePin={handleTogglePin} />
          </CarouselLayout>
          {/* FocusLayout оригинала — лёгкая обёртка ровно над ParticipantTile
              (см. её исходник), поэтому вместо неё используем свою обёртку
              напрямую с тем же trackRef (аватар в фокус-плитке). */}
-          {focusTrack && <RoomParticipantTile trackRef={focusTrack} onStopSharing={handleStopSharing} />}
+          {focusTrack && (
+            <RoomParticipantTile
+              trackRef={focusTrack}
+              onStopSharing={handleStopSharing}
+              pinnedKey={pinnedKey}
+              onTogglePin={handleTogglePin}
+            />
+          )}
        </FocusLayoutContainer>
      )}
      <RoomAudioRenderer />
--- a/frontend/src/components/room/stageFocus.ts
+++ b/frontend/src/components/room/stageFocus.ts
@@ -1,9 +1,11 @@
 /**
 * Чистая функция выбора «сцены в фокусе» (демонстрация экрана).
 *
- * Никаких зависимостей от React/DOM/LiveKit SDK — на вход только примитивы,
- * на выход тоже примитивы; можно покрыть unit-тестом при появлении раннера
- * (vitest в проект сознательно не вводим, тестируем вручную).
+ * Никаких зависимостей от React/DOM/LiveKit SDK в РАНТАЙМЕ — на вход только
+ * примитивы, на выход тоже примитивы; можно покрыть unit-тестом при появлении
+ * раннера (vitest в проект сознательно не вводим, тестируем вручную).
+ * Единственный импорт из SDK — `import type` у `stageTrackKey` (тип стирается
+ * при компиляции, рантайм-зависимости не добавляет).
 *
 * Ключ трека — НЕ sid публикации и НЕ голая identity участника, а составной
 * `${identity}:${source}` (см. `RoomStage.tsx`, функция `stageTrackKey`):
@@ -20,9 +22,21 @@
 *   однозначность (camera и screen_share одного участника — разные ключи).
 */

+import type { TrackReferenceOrPlaceholder } from '@livekit/components-react'
+
 /** Вид источника трека на сцене. */
 export type StageFocusKind = 'camera' | 'screen_share'

+/**
+ * Ключ трека для `pickStageFocus` — см. обоснование схемы в начале файла.
+ * Живёт здесь (а не в `RoomStage.tsx`), потому что нужен обеим сторонам:
+ * сцене — чтобы считать фокус, плитке (`RoomParticipantTile`) — чтобы понять,
+ * закреплена ли именно она, и каким ключом сообщить о нажатии на «закрепить».
+ */
+export function stageTrackKey(t: TrackReferenceOrPlaceholder): string {
+  return `${t.participant.identity}:${t.source}`
+}
+
 export interface PickStageFocusInput {
  /** Ключи текущих камера-треков (один на участника — трек либо его плейсхолдер). */
  cameraKeys: readonly string[]
@@ -35,19 +49,51 @@ export interface PickStageFocusInput {
   * `followSpeaker`, для живого переключения фокуса.
   */
  speakingCameraKeys: readonly string[]
+  /**
+   * Подмножество `cameraKeys` с ЖИВЫМ видео (камера включена и не в мьюте) —
+   * среди нескольких одновременно говорящих такой участник выигрывает у
+   * говорящего с выключенной камерой: показывать крупно аватар-заглушку, когда
+   * рядом говорит человек с картинкой, бессмысленно. Не указан — приоритета
+   * нет, берётся первый (самый громкий) говорящий, как было раньше.
+   */
+  cameraKeysWithVideo?: readonly string[]
  /** Объединённый набор ключей (camera+screenshare) с ПРЕДЫДУЩЕГО рендера — определяет, какие screenshare-ключи «новые». */
  prevKeys: readonly string[]
  /** Ключ, что был в фокусе на предыдущем рендере; `null` — фокус ещё не выбирался. */
  prevFocusKey: string | null
  /**
-   * Режим мини-плеера (PiP): фокус должен ЖИВО следовать за
-   * активным спикером (переключаться сразу, а не удерживать текущий), в
-   * отличие от основного окна сцены — там держим фокус, даже если заговорил
-   * кто-то другой (см. правило 2 ниже и обоснование в `RoomStage.tsx` про
-   * дребезг `isSpeaking` у фейковых медиапотоков). По умолчанию `false` —
-   * поведение основного окна не меняется.
+   * Ключ трека, ЗАКРЕПЛЁННОГО пользователем в основном окне (кнопка-булавка на
+   * плитке, состояние живёт в `RoomStage.tsx`); `null` — закрепления нет.
+   * Закрепление держит фокус вопреки говорящим, но уступает ЛЮБОЙ активной
+   * демонстрации экрана (формулировка оператора: «перебивается только чьей-либо
+   * демонстрацией экрана») — а когда демонстрация закончилась, фокус
+   * возвращается именно на закреплённого, а не на того, кто был до неё:
+   * правило закрепления стоит ВЫШЕ удержания предыдущего фокуса.
+   * Ключ закреплённого участника, покинувшего комнату, игнорируется (его нет
+   * ни в `cameraKeys`, ни в `screenShareKeys`) — снимает закрепление вызывающая
+   * сторона.
+   */
+  pinnedKey?: string | null
+  /**
+   * Фокус должен ЖИВО следовать за активным спикером (переключаться сразу, а
+   * не удерживать текущий). С 0.0.6 включено и для мини-плеера (PiP), и для
+   * основного окна — решение оператора (этап 3, задача 3.2). Защита от
+   * дребезга — на стороне вызывающего: источник «говорящих» — throttled
+   * `useSpeakingParticipants()` поверх `RoomEvent.ActiveSpeakersChanged`, а в
+   * основном окне ещё и удержание в ~1.2 с (см. `useSteadySpeakers` в
+   * `RoomStage.tsx`), не сырой дребезжащий `participant.isSpeaking`.
+   * По умолчанию `false` — фокус удерживается (см. правило 5).
   */
  followSpeaker?: boolean
+  /**
+   * Живая демонстрация экрана в фокусе НЕ уступает заговорившему участнику
+   * (правило 3). Нужно основному окну: там демонстрация — это содержательный
+   * центр разговора, и уводить её из большого окна на каждую реплику нельзя.
+   * Мини-плеер (PiP) показывает ровно одну плитку и намеренно ведёт себя иначе
+   * — всегда показывает того, кто говорит, поэтому там `false` (поведение
+   * PiP не менялось с 0.0.4).
+   */
+  holdScreenShare?: boolean
  /**
   * Ключ локального участника (та же схема `identity:source`) — предпоследний
   * фолбэк, ПЕРЕД чисто первым элементом набора: если фокуса ещё не было и
@@ -64,6 +110,20 @@ export interface PickStageFocusResult {
  kind: StageFocusKind | null
 }

+/**
+ * Выбирает говорящего, которого стоит показать крупно: среди живых говорящих
+ * (упорядоченных по громкости) сначала ищем того, у кого включена камера, и
+ * только если такого нет — берём самого громкого как есть.
+ */
+function pickSpeakerKey(
+  speakingCameraKeys: readonly string[],
+  cameraKeys: readonly string[],
+  cameraKeysWithVideo: readonly string[],
+): string | null {
+  const liveSpeakers = speakingCameraKeys.filter((key) => cameraKeys.includes(key))
+  return liveSpeakers.find((key) => cameraKeysWithVideo.includes(key)) ?? liveSpeakers[0] ?? null
+}
+
 /**
 * Выбирает, какой трек показать крупно (в `FocusLayoutContainer`).
 *
@@ -72,24 +132,38 @@ export interface PickStageFocusResult {
 *    фокус безусловно переходит на него (последний из новых, если появилось
 *    сразу несколько), даже если до этого в фокусе была камера или другая
 *    демонстрация. Так же ведут себя типовые UI конференций (Google Meet).
- * 2. `followSpeaker` (только PiP): если сейчас есть говорящий — фокус СРАЗУ
- *    переходит на него, даже если текущий фокус ещё жив. В основном окне
- *    (`followSpeaker: false`) этот шаг пропускается — см. правило 3.
- * 3. Иначе, если текущий фокус жив (остался среди camera/screenshare-ключей) —
+ * 2. Закрепление (`pinnedKey`, только основное окно): закреплённый участник
+ *    забирает фокус у говорящих и у удержания предыдущего фокуса, но уступает
+ *    ЛЮБОЙ активной демонстрации экрана. Поэтому правило и стоит выше
+ *    удержания (правило 5): как только демонстрация закончилась и
+ *    `screenShareKeys` опустел, фокус возвращается на закреплённого, а не
+ *    остаётся на том, кто был в фокусе до демонстрации.
+ * 3. `holdScreenShare` (только основное окно): демонстрация, уже стоящая в
+ *    фокусе, не уступает заговорившему — иначе большое окно уводило бы шэр на
+ *    каждую реплику. В PiP шаг пропускается (там одна плитка и она всегда
+ *    показывает говорящего).
+ * 4. `followSpeaker`: если сейчас есть говорящий — фокус СРАЗУ переходит на
+ *    него, даже если текущий фокус ещё жив; среди одновременно говорящих
+ *    предпочитаем того, у кого включена камера (`cameraKeysWithVideo`).
+ *    При `followSpeaker: false` этот шаг пропускается — см. правило 5.
+ * 5. Иначе, если текущий фокус жив (остался среди camera/screenshare-ключей) —
 *    держим его: НЕ дёргаем фокус на каждый ре-рендер (изменение состава
- *    участников, дребезг isSpeaking и т.п.). Это и есть «стабильный фолбэк»
- *    для PiP, когда никто не говорит — держим предыдущего активного.
- * 4. Иначе (фокуса не было или он пропал) — приоритет активной демонстрации
- *    над камерой; среди камер — активный спикер, иначе `localKey` (если
- *    указан и жив), иначе первая по порядку.
+ *    участников, дребезг isSpeaking и т.п.). Это и есть «стабильный фолбэк»,
+ *    когда никто не говорит — держим предыдущего активного.
+ * 6. Иначе (фокуса не было или он пропал) — приоритет активной демонстрации
+ *    над камерой; среди камер — активный спикер (снова с приоритетом камеры),
+ *    иначе `localKey` (если указан и жив), иначе первая по порядку.
 */
 export function pickStageFocus({
  cameraKeys,
  screenShareKeys,
  speakingCameraKeys,
+  cameraKeysWithVideo = [],
  prevKeys,
  prevFocusKey,
+  pinnedKey = null,
  followSpeaker = false,
+  holdScreenShare = false,
  localKey = null,
 }: PickStageFocusInput): PickStageFocusResult {
  if (cameraKeys.length === 0 && screenShareKeys.length === 0) {
@@ -102,8 +176,25 @@ export function pickStageFocus({
    return { focusKey: newScreenShareKeys[newScreenShareKeys.length - 1], kind: 'screen_share' }
  }

+  if (pinnedKey) {
+    // Закреплена сама демонстрация — она и есть «активная демонстрация»,
+    // уступать нечему (UI позволяет закрепить любую плитку, включая шэр).
+    if (screenShareKeys.includes(pinnedKey)) {
+      return { focusKey: pinnedKey, kind: 'screen_share' }
+    }
+    // Закреплена камера: пока в комнате идёт чья-то демонстрация, она
+    // перебивает закрепление (правило оператора) — идём дальше по списку.
+    if (cameraKeys.includes(pinnedKey) && screenShareKeys.length === 0) {
+      return { focusKey: pinnedKey, kind: 'camera' }
+    }
+  }
+
+  if (holdScreenShare && prevFocusKey && screenShareKeys.includes(prevFocusKey)) {
+    return { focusKey: prevFocusKey, kind: 'screen_share' }
+  }
+
  if (followSpeaker) {
-    const liveSpeaker = speakingCameraKeys.find((key) => cameraKeys.includes(key))
+    const liveSpeaker = pickSpeakerKey(speakingCameraKeys, cameraKeys, cameraKeysWithVideo)
    if (liveSpeaker) {
      return { focusKey: liveSpeaker, kind: 'camera' }
    }
@@ -120,7 +211,7 @@ export function pickStageFocus({
    return { focusKey: screenShareKeys[screenShareKeys.length - 1], kind: 'screen_share' }
  }

-  const speaking = speakingCameraKeys.find((key) => cameraKeys.includes(key))
+  const speaking = pickSpeakerKey(speakingCameraKeys, cameraKeys, cameraKeysWithVideo)
  if (speaking) {
    return { focusKey: speaking, kind: 'camera' }
  }