From 5daff3b7af768bbcc05c8ee3e0c91c2a5271982c Mon Sep 17 00:00:00 2001
From: Max Ronzhin <m.ronzhin@ssphera.ru>
Date: Mon, 27 Jul 2026 01:31:42 +0300
Subject: [PATCH] =?UTF-8?q?feat(room):=20=D0=B7=D0=B0=D0=BA=D1=80=D0=B5?=
 =?UTF-8?q?=D0=BF=D0=BB=D0=B5=D0=BD=D0=B8=D0=B5=20=D1=83=D1=87=D0=B0=D1=81?=
 =?UTF-8?q?=D1=82=D0=BD=D0=B8=D0=BA=D0=B0=20=D0=B8=20=D1=81=D0=BB=D0=B5?=
 =?UTF-8?q?=D0=B6=D0=B5=D0=BD=D0=B8=D0=B5=20=D0=BE=D1=81=D0=BD=D0=BE=D0=B2?=
 =?UTF-8?q?=D0=BD=D0=BE=D0=B3=D0=BE=20=D0=BE=D0=BA=D0=BD=D0=B0=20=D0=B7?=
 =?UTF-8?q?=D0=B0=20=D0=B3=D0=BE=D0=B2=D0=BE=D1=80=D1=8F=D1=89=D0=B8=D0=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Правила выбора фокуса сцены (`pickStageFocus`) дополнены двумя входами:

- `pinnedKey` — участник, закреплённый булавкой на плитке. Держит фокус
  вопреки говорящим, но уступает любой активной демонстрации экрана; как
  только демонстрация закончилась, фокус возвращается именно на
  закреплённого (правило стоит выше удержания предыдущего фокуса).
  Состояние — в `RoomStage`, повторное нажатие снимает, выход закреплённого
  из комнаты тоже. Закреплённая плитка помечена рамкой и подсвеченной
  булавкой; на тач-устройствах булавка видна без наведения.
- `holdScreenShare` — живая демонстрация в фокусе не уступает заговорившему
  (основное окно). PiP не затронут: там по-прежнему всегда виден говорящий.

Основное окно теперь следует за говорящим (`followSpeaker`) поверх
`useSpeakingParticipants()` вместо дребезжащего `participant.isSpeaking`, с
удержанием состава в 1.2 с (`useSteadySpeakers`) — короткие реплики фокус не
уводят. Среди одновременно говорящих предпочитается тот, у кого включена
камера (`cameraKeysWithVideo`).

`stageTrackKey` переехал в `stageFocus.ts` — ключ плитки нужен и сцене, и
самой плитке (в карусели/гриде она рендерится шаблоном, без пропсов).
---
 .../components/room/RoomParticipantTile.tsx   |  66 ++++++-
 frontend/src/components/room/RoomStage.tsx    | 171 +++++++++++++-----
 frontend/src/components/room/stageFocus.ts    | 131 ++++++++++++--
 frontend/src/styles/room.css                  |  46 +++++
 4 files changed, 336 insertions(+), 78 deletions(-)

diff --git a/frontend/src/components/room/RoomParticipantTile.tsx b/frontend/src/components/room/RoomParticipantTile.tsx
index e9937b4..d08e07d 100644
--- 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>
   )
 }
diff --git a/frontend/src/components/room/RoomStage.tsx b/frontend/src/components/room/RoomStage.tsx
index b2cfcd2..b727d4a 100644
--- 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 />
diff --git a/frontend/src/components/room/stageFocus.ts b/frontend/src/components/room/stageFocus.ts
index 301733d..3149a8a 100644
--- 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' }
   }
diff --git a/frontend/src/styles/room.css b/frontend/src/styles/room.css
index b0cb4b8..0714b06 100644
--- a/frontend/src/styles/room.css
+++ b/frontend/src/styles/room.css
@@ -416,6 +416,52 @@ video[data-lk-source='screen_share'] { object-fit: contain; background: #000; }
 }
 .stage-sharing-chip button:hover { filter: brightness(0.95); }
 
+/*
+ * ---------- Кнопка закрепления участника (булавка) ----------
+ * Рендерится внутри `RoomParticipantTile` (см. её `TileBody`), т.е. внутри
+ * `.lk-participant-tile` — тот у @livekit/components-styles уже
+ * `position: relative`. Геометрия и логика появления повторяют штатную
+ * `.lk-focus-toggle-button` той же библиотеки (правый верхний угол, видна по
+ * наведению) — чтобы плитка выглядела цельно, а не «нашей кнопкой поверх
+ * чужой». Отличие: у закреплённой плитки булавка видна ВСЕГДА и подсвечена —
+ * закрепление должно читаться без наведения.
+ */
+.room-pin-toggle {
+  position: absolute;
+  top: 0.25rem;
+  right: 0.25rem;
+  z-index: 5;
+  display: flex;
+  padding: 0.25rem;
+  border: none;
+  border-radius: calc(var(--lk-border-radius, 0.5rem) / 2);
+  background: rgba(0, 0, 0, 0.5);
+  color: var(--color-room-text-primary);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.2s ease-in-out;
+  transition-delay: 0.2s;
+}
+.room-pin-toggle svg { width: 20px; height: 20px; }
+.lk-participant-tile:hover .room-pin-toggle,
+.lk-participant-tile:focus-within .room-pin-toggle,
+.room-pin-toggle.is-pinned { opacity: 1; transition-delay: 0s; }
+.room-pin-toggle.is-pinned { background: var(--color-room-mic-on); color: #10331f; }
+
+/* Тач-устройства (мобильный/планшет): hover нет вовсе — иначе булавка была бы
+   недоступна. Тулбар комнаты не задет: кнопка живёт на плитке. */
+@media (hover: none) {
+  .room-pin-toggle { opacity: 1; transition-delay: 0s; }
+}
+
+/* Метка закреплённой плитки — рамка по контуру. Класс закрепления висит на
+   кнопке (корневой div плитки рендерит библиотека, свой класс туда не
+   добавить), поэтому селектор идёт через `:has()`. */
+.lk-participant-tile:has(.room-pin-toggle.is-pinned) {
+  outline: 2px solid var(--color-room-mic-on);
+  outline-offset: -2px;
+}
+
 /* ---------- Заглушка «конференция в мини-окне» (Document PiP) ---------- */
 .room-pip-placeholder {
   flex: 1;