feat: unify overlay preview appearance

Place platform icons before nicknames and use white, checker, scene, and dark preview backdrops.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: strider2038

CHANGELOG.md

@@ -6,28 +6,19 @@
 
 ## [Unreleased]
 
-### Исправлено
-
-- Остров пресета на вкладке **Внешний вид** OBS: пресет, URL и статус в одной строке; URL укорочен с многоточием, копирование — иконкой (полный адрес в подсказке).
-- В окне OBS на вкладке **Внешний вид** поля и превью больше не обрезаются нижней панелью: список настроек прокручищается, кнопки «Закрыть» / «Сохранить» остаются на месте.
-- На вкладке **Внешний вид** выровнены поля при длинных подписях, поправлены отступы в блоке «Поверхность», кнопка «Убрать картинку» не выходит за границу, цвет и число в строках идут в одном порядке.
-- В теме **Default** маркеры платформы **Иконка** и **Полоска и иконка** снова показывают SVG-иконки в overlay и в превью.
-- Повторный выбор картинки панели в OBS-настройках снова срабатывает (поле файла сбрасывается после загрузки).
-- При отклонении картинки панели (формат, размер, HEIC/AVIF) админка показывает понятную ошибку вместо тихого сбоя.
-
 ### Добавлено
 
-- OBS-диалог: на **Подключении** в карточке Overlay снова поле URL (как у dock) и выбор пресета; на **Внешний вид** — остров пресета (селект + иконки новый / переименовать / дублировать / удалить, имя в отдельном окне), тема и очередь в одной колонке настроек.
-- В блоке **Поверхность** OBS-настроек: масштаб картинки панели (**заполнить / вписать / растянуть / плитка**) и привязка (**к сообщению / на колонку чата**; колонка — в теме Default); масштаб выбирается иконками с подсказкой при наведении.
-- В OBS-диалоге появились **пресеты внешнего вида** и URL overlay с `?preset=` для отдельного вида в каждой сцене.
+- **Пресеты внешнего вида** OBS overlay и URL с `?preset=` для отдельного вида в каждой сцене. На **Подключении** в карточке Overlay — поле URL и выбор пресета (как у dock); на **Внешний вид** — остров пресета (список, новый / переименовать / дублировать / удалить), тема и очередь в одной колонке.
+- В блоке **Поверхность**: картинка панели, масштаб (**заполнить / вписать / растянуть / плитка**) и привязка (**к сообщению / на колонку чата**; колонка — в теме Default); при отказе файла (формат, размер, HEIC/AVIF) показывается ошибка.
 
-### Удалено
+### Изменено
 
-- Вкладка **Выделения** в OBS-настройках: подсветка слов и список «своих» людей с иконками (будет переделано отдельно).
+- Превью OBS overlay: фоны **белый**, шахматка, **игровой кадр** и **чёрный** (вместо «загруженной сцены» и «тёмного»); в темах MW5 и G-Rebels фон заполняет весь прямоугольник. Старый адрес с `preview_background=busy` показывает игровой кадр.
+- Иконка платформы во всех темах стоит сразу перед ником; у новых пресетов **G-Rebels** она включена вместе с полоской (в уже сохранённых пресетах — «Сбросить группу к теме»).
 
 ### Миграция
 
-- Старый `config.json` без `overlay.presets` при запуске превращается в пресет **Default** из текущих полей темы, лимита и TTL. Поля `overlay.highlights` и `overlay.people` игнорируются.
+- Старый `config.json` без `overlay.presets` при запуске превращается в пресет **Default** из текущих полей темы, лимита и TTL.
 
 ## [0.4.0] - 2026-08-22
 

docs/FAQ.en.md

@@ -58,6 +58,8 @@ Quick renderer check without live chat:
 http://127.0.0.1:17877/overlay?preview=sample&preview_background=checker
 ```
 
+In the admin preview (**OBS → Appearance**) you can switch the backdrop: white, checkerboard, game footage, or black, to check contrast on bright and dark scenes. The legacy query `preview_background=busy` is treated as game footage.
+
 To pin a look to an OBS scene, use a preset URL (copied on the **OBS → Setup** tab):
 
 ```
@@ -73,7 +75,7 @@ Sample messages should appear. The same mode exists in the admin panel: **OBS 
 ### Messages in admin but not in overlay (browser and OBS)
 
 1. **Message TTL** — in **OBS → Appearance** set **0**, click **Save settings**. By default messages disappear after 20 seconds; old entries are not shown when opening the overlay.
-2. **Text only theme** — light text on a transparent background is almost invisible in a normal browser. For testing choose **Default** or open `?preview_background=dark`.
+2. **Text only theme** — light text on a transparent background is almost invisible in a normal browser. For testing choose **Default** or open `?preview_background=dark` (dark scene) or `?preview_background=white` (bright scene).
 3. **WebSocket** — at the bottom of the admin panel the **WS:** counter should be **2 or more** with `/overlay` open. In DevTools (F12) on the overlay tab check `ws://127.0.0.1:17877/ws`.
 4. **OBS cache** — after changing overlay settings: right-click the source → **Refresh cache of current page**.
 5. **URL and port** — copy the URL from **OBS → Setup**; if you changed the port in settings, update the Browser Source.

docs/FAQ.md

@@ -57,6 +57,8 @@ http://127.0.0.1:17877/overlay
 http://127.0.0.1:17877/overlay?preview=sample&preview_background=checker
 ```
 
+В превью админки (**OBS → Внешний вид**) фон можно сменить: белый, шахматка, игровой кадр или чёрный — так проверяют читаемость на ярком и тёмном кадре. Старый параметр `preview_background=busy` означает игровой кадр.
+
 Чтобы закрепить вид за сценой OBS, используйте URL с пресетом (копируется на вкладке **OBS → Настройка**):
 
 ```
@@ -70,7 +72,7 @@ http://127.0.0.1:17877/overlay?preset=default
 ### Сообщения есть в админке, но не в overlay (браузер и OBS)
 
 1. **TTL сообщения** (Message TTL) — в **OBS → Внешний вид** (Appearance) выставьте **0**, нажмите **Сохранить настройки** (Save settings). По умолчанию сообщения исчезают через 20 секунд; старые записи при открытии overlay не показываются.
-2. **Тема Text only (без фона)** — светлый текст на прозрачном фоне в обычном браузере почти не виден. Для проверки выберите **Default** или откройте `?preview_background=dark`.
+2. **Тема Text only (без фона)** — светлый текст на прозрачном фоне в обычном браузере почти не виден. Для проверки выберите **Default** или откройте `?preview_background=dark` (тёмный кадр) либо `?preview_background=white` (яркий).
 3. **WebSocket** — внизу админки счётчик **WS:** при открытой вкладке `/overlay` должен быть **2 или больше**. В DevTools (F12) на вкладке overlay проверьте соединение `ws://127.0.0.1:17877/ws`.
 4. **Кэш OBS** — после смены настроек overlay: правый клик по источнику → **Refresh cache of current page**.
 5. **URL и порт** — копируйте URL из **OBS → Настройка** (Setup); при смене порта в настройках обновите Browser Source.

internal/config/overlay_config_test.go

@@ -106,6 +106,14 @@ func TestLoad_WhenLegacyOverlayJSON_ExpectMigratedPreset(t *testing.T) {
 	require.Equal(t, OverlayPlatformMarkerIcon, cfg.Overlay.Presets[0].Style.PlatformMarker)
 }
 
+func TestDefaultOverlayStyleForTheme_WhenGRebelsPopups_ExpectBothPlatformMarker(t *testing.T) {
+	t.Parallel()
+
+	style := defaultOverlayStyleForTheme(OverlayThemeGRebelsPopups)
+	require.Equal(t, OverlayPlatformMarkerBoth, style.PlatformMarker)
+	require.InDelta(t, 0.0, style.PanelOpacity, 0.001)
+}
+
 func TestDefault_WhenCalled_ExpectPresetMirrorsFlatFields(t *testing.T) {
 	t.Parallel()
 

internal/config/overlay_style.go

@@ -92,9 +92,9 @@ func defaultOverlayStyleForTheme(theme string) OverlayStyleConfig {
 		style.PlatformMarker = OverlayPlatformMarkerIcon
 		style.PanelOpacity = 0
 		style.TextEdge = OverlayTextEdgeOutline
-	case OverlayThemeCockpitPanel, OverlayThemeGRebelsPopups:
+	case OverlayThemeCockpitPanel:
 		style.PanelOpacity = 0
-	case OverlayThemeCockpitPopups:
+	case OverlayThemeCockpitPopups, OverlayThemeGRebelsPopups:
 		style.PlatformMarker = OverlayPlatformMarkerBoth
 		style.PanelOpacity = 0
 	}

openspec/changes/archive/2026-08-25-unify-overlay-preview-appearance/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-25

openspec/changes/archive/2026-08-25-unify-overlay-preview-appearance/design.md

@@ -0,0 +1,61 @@
+## Context
+
+See proposal.md for motivation. Overlay messages already have `.message__identity` (flex) and a `.message__platform` sibling. HUD themes use CSS grid without a platform area, so the icon auto-places under the avatar. Preview backdrops are body classes `overlay-preview--busy|checker|dark`. Admin already imports `web/overlay/overlay-settings.js`.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- One identity slot for the platform icon across themes
+- Shared preview backdrop vocabulary and query values
+- Theme defaults that match G-Rebels platform-identity need (`both`)
+
+**Non-Goals:**
+
+- Uploading a real OBS scene screenshot
+- Gray fifth backdrop
+- Migrating existing G-Rebels presets that already saved `stripe`
+- Changing platform-marker semantics (stripe vs author rail)
+- Making cockpit-panel glass transparent in preview so footage always shows through
+
+## Decisions
+
+### Identity owns the icon
+
+**Choice:** Append `.message__platform` inside `.message__identity` before `.message__user`.
+
+**Rationale:** Identity already has `grid-area: user` in HUD themes and `inline-flex` + gap. Moving the node fixes placement without a new grid track.
+
+**Alternatives:** Avatar-corner badge (clips on G-Rebels chamfer); extra grid column (duplicates identity).
+
+### Canonical preview values
+
+**Choice:** Canonical values `white`, `checker`, `scene`, `dark`. Alias `busy` → `scene`. Default `scene`. Shared `normalizePreviewBackground` in `overlay-settings.js`.
+
+**Rationale:** `dark` stays as the query value (FAQ already uses it); labels become Black / Чёрный. Keep `scene` as the honest name instead of `busy`.
+
+**Alternatives:** Rename `dark` to `black` (breaks FAQ URLs); keep `busy` as canonical (labels stay confusing).
+
+### Backdrop lives on overlay `body`
+
+**Choice:** Continue painting preview CSS on overlay `body`. Themes that cover the rectangle with HUD glass still hide footage there — that matches OBS.
+
+**Alternatives:** Letterbox the scene around the iframe in admin chrome (preview-only lie); force HUD panel transparent in preview (dishonest).
+
+### G-Rebels default `both`
+
+**Choice:** `defaultOverlayStyleForTheme` / `defaultStyleForTheme` for `g_rebels_popups` use `both`, like `cockpit_popups`. No rewrite of stored preset style.
+
+**Rationale:** G-Rebels nicknames are gold, so the icon is the platform signal. Existing saved `stripe` remains an explicit operator choice.
+
+## Risks / Trade-offs
+
+- [Existing G-Rebels presets stay without icons] → Changelog points at "Reset group to theme"
+- [Cockpit panel name column is `fit-content(18ch)`] → Icon is `flex-shrink: 0`; name keeps ellipsis
+- [Cached overlay CSS/JS] → Bump `?v=` on overlay assets
+
+## Migration Plan
+
+- New installs and new G-Rebels presets get `both`
+- `preview_background=busy` and localStorage `busy` map to `scene`
+- Rollback: revert overlay DOM/CSS and restore the three-value select; alias keeps old URLs working during the change only

openspec/changes/archive/2026-08-25-unify-overlay-preview-appearance/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+OBS overlay preview appearance is inconsistent across themes: platform icons in HUD themes fall under the avatar instead of sitting with the nickname, G-Rebels hides platform identity by default, and preview backgrounds mix a mistranslated "busy/loaded scene" with an incomplete contrast set (no white). Streamers cannot compare themes or judge readability against bright gameplay.
+
+## What Changes
+
+- Place the platform icon inside the message identity, immediately before the display name, in every theme when the platform marker is `icon` or `both`.
+- Default G-Rebels Cockpit popups to `both` (author rail + platform icon), matching MW5 Cockpit popups. Cockpit panel stays `stripe`.
+- Unify preview backgrounds to four options, same CSS on `body` for every theme: white, checkerboard, game footage (`scene`, replacing `busy`), black (`dark`).
+- Accept legacy `preview_background=busy` as `scene`. Preview still only paints transparent regions; HUD glass may cover the footage.
+- Rename admin labels: "Загруженная сцена" / "Busy scene" → "Игровой кадр" / "Game footage"; "Тёмный" / "Dark" → "Чёрный" / "Black".
+
+## Capabilities
+
+### New Capabilities
+
+- None
+
+### Modified Capabilities
+
+- `obs-overlay`: platform icon placement; G-Rebels default marker; preview background query values
+- `admin-and-dock`: appearance preview background control and labels
+
+## Impact
+
+- Overlay DOM/CSS (`web/overlay`), admin preview select (`web/admin`), i18n catalogs, overlay-settings defaults (JS + Go `defaultOverlayStyleForTheme`)
+- Query param `preview_background`; localStorage preview preference maps `busy` → `scene`
+- FAQ overlay test URLs; CHANGELOG `[Unreleased]`
+- Existing G-Rebels presets that already saved `stripe` keep that value until the operator resets the marker group to the theme default

openspec/changes/archive/2026-08-25-unify-overlay-preview-appearance/specs/admin-and-dock/spec.md

@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: Appearance preview offers a shared backdrop set
+The OBS Appearance preview SHALL let the operator choose a backdrop from white, checkerboard, game footage, and black. Labels MUST describe contrast purpose (not an uploaded OBS scene). The preview iframe MUST pass the matching `preview_background` query value. Stored preference `busy` MUST map to game footage.
+
+#### Scenario: Backdrop options
+- **WHEN** the operator opens the overlay appearance preview background control
+- **THEN** the options are white, checkerboard, game footage, and black, in that order
+
+#### Scenario: Restored busy preference
+- **WHEN** a previously stored preview background value is `busy`
+- **THEN** the control shows game footage and the iframe uses `preview_background=scene`

openspec/changes/archive/2026-08-25-unify-overlay-preview-appearance/specs/obs-overlay/spec.md

@@ -0,0 +1,38 @@
+## ADDED Requirements
+
+### Requirement: Platform icon sits with the display name
+When the platform marker is `icon` or `both`, the overlay SHALL render the platform icon immediately before the display name inside the message identity, in every supported theme. The icon MUST NOT occupy a leftover grid cell (for example under the avatar) in HUD themes.
+
+#### Scenario: HUD popup with icon marker
+- **WHEN** the theme is `cockpit_popups` or `g_rebels_popups` and the platform marker is `icon` or `both`
+- **THEN** the platform icon appears on the same row as the display name, immediately before it
+
+#### Scenario: Stripe hides the icon
+- **WHEN** the platform marker is `stripe` or `none`
+- **THEN** the platform icon is not shown
+
+### Requirement: G-Rebels default platform marker includes the icon
+New presets and theme-default style for `g_rebels_popups` SHALL use platform marker `both`. Existing presets that already stored a marker MUST keep that stored value.
+
+#### Scenario: New G-Rebels preset
+- **WHEN** the operator creates a preset with theme `g_rebels_popups` without overriding the platform marker
+- **THEN** the marker is `both`
+
+### Requirement: Preview backgrounds are a shared contrast set
+When `/overlay` is loaded with a preview query, `preview_background` SHALL apply the same page backdrop for every theme: `white`, `checker`, `scene`, or `dark`. Legacy value `busy` SHALL be treated as `scene`. Missing or invalid values SHALL use `scene`. Outside preview, `html` and `body` backgrounds MUST remain transparent. Theme chrome MAY still cover parts of the backdrop.
+
+#### Scenario: White preview backdrop
+- **WHEN** the overlay URL includes a preview flag and `preview_background=white`
+- **THEN** the page backdrop is solid white behind transparent overlay regions
+
+#### Scenario: Legacy busy query
+- **WHEN** the overlay URL includes a preview flag and `preview_background=busy`
+- **THEN** the page backdrop is the same game-footage pattern as `scene`
+
+#### Scenario: HUD theme preview fills the rectangle
+- **WHEN** the theme is `cockpit_popups` or `g_rebels_popups` and preview uses `preview_background=scene`
+- **THEN** the game-footage backdrop fills the Browser Source rectangle behind transparent HUD regions rather than the browser default white page
+
+#### Scenario: Live OBS overlay
+- **WHEN** `/overlay` loads without a preview query
+- **THEN** the page background stays transparent