feat(vegas): one declared participation per plugin (scroll | pause | exclude) (#682)

A plugin takes part in Vegas mode in one declared way: 'scroll', 'pause'
or 'exclude', resolved from the user's vegas_participation setting, the
manifest field, then the legacy hooks, so no plugin changes behaviour.
The stream manager decides inclusion and pauses through it; the installed
plugins API and the Vegas plugin-order list report it. Deprecates
get_supported_vegas_modes, get_vegas_segment_width and vegas_panel_count
for removal in 3.9.0, and regenerates docs/DEPRECATIONS_3.8.md to include
them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/ADVANCED_FEATURES.md

@@ -10,22 +10,27 @@ This guide covers advanced LEDMatrix features for users and developers, includin
 
 Vegas scroll mode displays content from multiple plugins in a continuous horizontal scroll, similar to news tickers seen in Las Vegas casinos. Plugins contribute content segments that flow across the display in a seamless ticker-style presentation.
 
-### Display Modes
+### How a Plugin Takes Part
 
-**SCROLL (Continuous Scrolling):**
-- Content scrolls continuously left
-- Smooth, fluid motion
-- Best for news-ticker style displays
+Each plugin has a *Vegas participation*:
 
-**FIXED_SEGMENT (Fixed-Width Block):**
-- Plugin gets fixed-width block on display
-- Content doesn't scroll out of its segment
-- Multiple plugins can share the display simultaneously
+**`scroll` (the default):**
+- The plugin's content scrolls by with everyone else's
+- Best for news-ticker style content: scores, headlines, prices, the time
 
-**STATIC (Scroll Pauses):**
-- Scrolling pauses when content is fully visible
-- Displays for specified duration, then resumes scrolling
-- Best for content that needs to be fully read
+**`pause`:**
+- The scroll stops when the plugin's turn comes round
+- The plugin draws the whole panel for its display duration, then the
+  scroll resumes
+- Best for content that needs to be read in full, or alerts
+
+**`exclude`:**
+- The plugin is left out of Vegas mode
+
+A plugin declares its default; set `vegas_participation` in a plugin's
+config to override it (see [Per-Plugin Configuration](#per-plugin-configuration)).
+Older documentation also describes a *fixed segment* mode; Vegas never
+implemented one, and it has always behaved exactly like `scroll`.
 
 ### Configuration
 
@@ -164,8 +169,7 @@ Override Vegas behavior for specific plugins:
 {
   "my_plugin": {
     "enabled": true,
-    "vegas_mode": "scroll",
-    "vegas_panel_count": 2,
+    "vegas_participation": "pause",
     "display_duration": 10
   }
 }
@@ -175,19 +179,30 @@ Override Vegas behavior for specific plugins:
 
 | Setting | Values | Description |
 |---------|--------|-------------|
-| `vegas_mode` | `scroll`, `fixed`, `static` | Display mode for this plugin |
-| `vegas_panel_count` | any positive integer | Width in panels (1 panel = display width) |
-| `display_duration` | seconds | Pause duration for STATIC mode |
+| `vegas_participation` | `scroll`, `pause`, `exclude` | How this plugin takes part: its content scrolls by, the scroll pauses for its turn and shows it full screen, or it is left out. Unset uses the plugin's own default |
+| `display_duration` | seconds | How long a `pause` plugin holds the screen |
+| `vegas_width_pct` | 10–100 | Width of this plugin's card, as a percentage of the panel |
+| `vegas_overflow` | `rotate`, `truncate` | What to do when its content is wider than its allowance |
+| `vegas_max_width_screens` | number of screens | The widest its card may be |
 
-Plugins may also set `vegas_overflow` and `vegas_max_width_screens` in
-their config section to control how oversized content is handled (see
-`PluginManager` in `src/plugin_system/plugin_manager.py`).
+These are core-owned settings (see
+[PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md)): every
+plugin accepts them whether or not its own schema lists them. Set them in
+the plugin's section of config.json, in the web UI's **Config Editor**
+tab.
+
+Some plugins also offer a `vegas_mode` setting of their own (`scroll`,
+`fixed` or `static`). It still works — `static` pauses, the other two scroll
+— but `vegas_participation` takes precedence, and `fixed` has never done
+anything different from `scroll`. The old `vegas_panel_count` setting never
+had an effect and is deprecated (removed in 3.9.0).
 
 ### Plugin Integration (Developer Guide)
 
 All of these have defaults in
 [`BasePlugin`](../src/plugin_system/base_plugin.py); override only what you
-need.
+need. The reference is
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-scroll-hooks).
 
 **1. Implement Content Method:**
 
@@ -203,43 +218,41 @@ If it returns `None` (the default), Vegas falls back to the plugin's
 (`PluginAdapter.get_content()` in
 [`src/vegas_mode/plugin_adapter.py`](../src/vegas_mode/plugin_adapter.py)).
 
-**2. Specify Content Type:**
+**2. Declare how the plugin takes part:**
 
-```python
-def get_vegas_content_type(self):
-    # 'multi' | 'static' | 'none'  -- default is 'static'
-    return 'multi'
+Most plugins need nothing: the default is `scroll`. A plugin that should
+pause the scroll, or stay out of Vegas, says so in `manifest.json`:
+
+```json
+{
+  "vegas_participation": "pause"
+}
 ```
 
-`'none'` excludes the plugin from Vegas mode.
-
-**3. Optionally Specify Display Mode:**
-
-These return `VegasDisplayMode` members, not strings:
+The user's own `vegas_participation` setting overrides the manifest. When
+the answer depends on state, override the method instead:
 
 ```python
-from src.plugin_system.base_plugin import VegasDisplayMode
-
-def get_vegas_display_mode(self):
-    return VegasDisplayMode.SCROLL
-
-def get_supported_vegas_modes(self):
-    return [VegasDisplayMode.SCROLL, VegasDisplayMode.STATIC]
+def get_vegas_participation(self):
+    # 'scroll' | 'pause' | 'exclude'
+    return 'pause' if self._alert_is_live() else 'scroll'
 ```
 
-`VegasDisplayMode` has `SCROLL` (`"scroll"`), `FIXED_SEGMENT` (`"fixed"`) and
-`STATIC` (`"static"`). The default `get_vegas_display_mode()` uses the
-plugin's `vegas_mode` config value if set, otherwise maps the content type
-(`multi` to `SCROLL`, anything else to `FIXED_SEGMENT`).
+A plugin written for an older core that declares nothing keeps its
+behaviour: `get_vegas_display_mode()` returning `VegasDisplayMode.STATIC`
+pauses, `get_vegas_content_type()` returning `'none'` excludes, and
+everything else scrolls. `get_supported_vegas_modes()`,
+`get_vegas_segment_width()` and the SCROLL / FIXED_SEGMENT distinction are
+deprecated (removed in 3.9.0): Vegas never read them.
 
 ### Content Rendering Guidelines
 
 **Image Dimensions:**
 - **Height:** Must match display height (typically 32 pixels)
-- **Width:** Varies by mode:
-  - SCROLL: Any width (recommended 64-512 pixels)
-  - FIXED_SEGMENT: `panel_count * display_width`
-  - STATIC: Any width, optimized for readability
+- **Width:** Any width for `scroll` (recommended 64-512 pixels);
+  `get_vegas_render_width()` is the width Vegas would like, and it narrows
+  `display_manager` to match while it asks. A `pause` plugin draws the
+  whole panel in `display()`.
 
 **Color Mode:**
 - Use RGB color mode
@@ -289,17 +302,10 @@ class WeatherPlugin(BasePlugin):
     def get_vegas_content(self):
         """Return cached Vegas image"""
         return self.vegas_image
-
-    def get_vegas_content_type(self):
-        return 'multi'
-
-    def get_vegas_display_mode(self):
-        return 'scroll'
-
-    def get_supported_vegas_modes(self):
-        return ['scroll', 'static']
 ```
 
+It scrolls, the default participation, so it declares nothing else.
+
 ### System Architecture
 
 Vegas mode consists of four core components working together to provide smooth 125 FPS continuous scrolling:
@@ -382,7 +388,8 @@ Vegas mode consists of four core components working together to provide smooth 1
 
 **Responsibilities:**
 - Convert plugin content to scrollable images
-- Handle different Vegas display modes (SCROLL, FIXED, STATIC)
+- Fetch the content of `scroll` plugins (a `pause` plugin is drawn by
+  its own `display()` when the scroll pauses; see StreamManager)
 - Manage fallback for plugins without Vegas support
 - Cache plugin content for performance
 
@@ -391,21 +398,16 @@ Vegas mode consists of four core components working together to provide smooth 1
    - Calls `get_vegas_content()` if available
    - Falls back to `display()` method if not
 
-2. **Handle display mode:**
-   - SCROLL: Returns image as-is for continuous scrolling
-   - FIXED_SEGMENT: Creates fixed-width block (panel_count * display_width)
-   - STATIC: Marks content for pause-when-visible behavior
-
-3. **Content type handling:**
-   - `multi`: Multiple segments (list of images)
-   - `static`: Single static image
-   - `none`: Skip this plugin in current cycle
+2. **Participation** is decided by the StreamManager, not here
+   (`resolve_vegas_participation()` in
+   [`base_plugin.py`](../src/plugin_system/base_plugin.py)): `exclude`
+   plugins never reach the adapter, and `pause` plugins are not fetched.
 
 **Fallback Behavior:**
 - If plugin doesn't implement Vegas methods:
   - Calls plugin's `display()` method
   - Captures rendered display as static image
-  - Treats as fixed segment
+  - Scrolls it by as one block
 - Ensures all plugins work in Vegas mode without explicit support
 
 #### 4. RenderPipeline
@@ -508,7 +510,7 @@ All components use thread-safe patterns:
 If a plugin doesn't implement Vegas methods:
 - System calls the plugin's `display()` method
 - Captures the rendered display as a static image
-- Treats it as a fixed segment
+- Scrolls it by as one block
 
 This ensures all plugins work in Vegas mode, even without explicit support.
 

docs/DEPRECATIONS_3.8.md

@@ -2,11 +2,11 @@
 
 Generated by `scripts/plugin_api_usage.py` — do not edit by hand; re-run it (see [How to re-run](#how-to-re-run)).
 
-- Scanned: 2026-09-29, core 3.7.0
+- Scanned: 2026-09-30, core 3.7.0
 - Monorepo: [ChuckBuilds/ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins) (main @ 4327c2e4), 46 plugins
 - Third-party plugins: 8 with their own repo in `plugins.json` (f1-live, gif-player, pga-tour-leaderboard, plex-marquee, ledmatrix-dresden-departures, tidbyt-baseball-scoreboard, sleeper-fantasy, ledmatrix-nascar)
 
-**35 deprecated methods: 35 unused, 0 still used, 0 need review.**
+**37 deprecated methods: 36 unused, 1 still used, 0 need review.**
 
 Counted per plugin: a *call* is `<receiver>.method` on an object named like the owner (`cache_manager`, `display_manager`, `font_manager`, `plugin_manager`), or on `self`/`super()` in a subclass; an *override* is `def method` in a subclass of the owner. *Review* hits are `.method` on a receiver whose type the scan cannot tell. *Internal* hits sit inside another deprecated core method and go with it. *Unrelated* hits are a different class's own method with the same name (a name collision), and never block removal; neither do hits in test files.
 
@@ -46,11 +46,17 @@ Counted per plugin: a *call* is `<receiver>.method` on an object named like the
 | `FontManager.add_font` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
 | `FontManager.remove_font` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
 | `FontManager.validate_font` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
+| `BasePlugin.get_supported_vegas_modes` | 3.9.0 | core tests (2 test reviews) | blackjack (1 call, 1 override); calendar (1 override); olympics (1 override) | — | still used by blackjack, calendar, olympics — keep or migrate first |
+| `BasePlugin.get_vegas_segment_width` | 3.9.0 | core tests (1 test review) | — | — | unused — safe to remove in 3.9.0 |
 | `PluginManager.get_enabled_plugins` | 3.8.0 | — | — | — | unused — safe to remove in 3.8.0 |
 
-## Unused — safe to remove (35)
+## Unused — safe to remove (36)
 
-`CacheManager.has_data_changed`, `CacheManager.update_cache`, `CacheManager.setup_persistent_cache`, `CacheManager.get_sport_live_interval`, `CacheManager.get_sport_key_from_cache_key`, `CacheManager.get_background_cached_data`, `CacheManager.is_background_data_available`, `CacheManager.record_cache_hit`, `CacheManager.record_cache_miss`, `CacheManager.record_fetch_time`, `CacheManager.get_cache_metrics`, `CacheManager.log_cache_metrics`, `CacheManager.get_memory_cache_stats`, `DisplayManager.draw_sun`, `DisplayManager.draw_cloud`, `DisplayManager.draw_rain`, `DisplayManager.draw_snow`, `DisplayManager.draw_weather_icon`, `DisplayManager.draw_text_with_icons`, `DisplayManager.get_scrolling_stats`, `FontManager.get_manager_fonts`, `FontManager.get_detected_fonts`, `FontManager.unregister_plugin_fonts`, `FontManager.get_plugin_fonts`, `FontManager.set_override`, `FontManager.remove_override`, `FontManager.get_overrides`, `FontManager.get_available_fonts`, `FontManager.get_size_tokens`, `FontManager.get_performance_stats`, `FontManager.get_font_catalog`, `FontManager.add_font`, `FontManager.remove_font`, `FontManager.validate_font`, `PluginManager.get_enabled_plugins`
+`CacheManager.has_data_changed`, `CacheManager.update_cache`, `CacheManager.setup_persistent_cache`, `CacheManager.get_sport_live_interval`, `CacheManager.get_sport_key_from_cache_key`, `CacheManager.get_background_cached_data`, `CacheManager.is_background_data_available`, `CacheManager.record_cache_hit`, `CacheManager.record_cache_miss`, `CacheManager.record_fetch_time`, `CacheManager.get_cache_metrics`, `CacheManager.log_cache_metrics`, `CacheManager.get_memory_cache_stats`, `DisplayManager.draw_sun`, `DisplayManager.draw_cloud`, `DisplayManager.draw_rain`, `DisplayManager.draw_snow`, `DisplayManager.draw_weather_icon`, `DisplayManager.draw_text_with_icons`, `DisplayManager.get_scrolling_stats`, `FontManager.get_manager_fonts`, `FontManager.get_detected_fonts`, `FontManager.unregister_plugin_fonts`, `FontManager.get_plugin_fonts`, `FontManager.set_override`, `FontManager.remove_override`, `FontManager.get_overrides`, `FontManager.get_available_fonts`, `FontManager.get_size_tokens`, `FontManager.get_performance_stats`, `FontManager.get_font_catalog`, `FontManager.add_font`, `FontManager.remove_font`, `FontManager.validate_font`, `BasePlugin.get_vegas_segment_width`, `PluginManager.get_enabled_plugins`
+
+## Still used — keep or migrate first (1)
+
+`BasePlugin.get_supported_vegas_modes`
 
 ## Every hit
 
@@ -87,21 +93,28 @@ File paths are relative to the plugin's directory (core: the repo root).
 | `DisplayManager.draw_weather_icon` | ledmatrix-weather | manager.py:1635 | unrelated | `WeatherIcons.draw_weather_icon(img, forecast['icon'], icon_x, icon_y, icon_size)` |
 | `DisplayManager.draw_weather_icon` | ledmatrix-weather | weather_icons.py:168 | unrelated | `def draw_weather_icon(image: Image.Image, icon_code: str, x: int, y: int, size: int = DEFAULT_SIZE):` |
 | `DisplayManager.draw_text_with_icons` | core | src/plugin_system/testing/visual_display_manager.py:526 | unrelated | `def draw_text_with_icons(self, text: str, icons: List[tuple] = None,` |
-| `FontManager.get_font_catalog` | core tests | test/test_deprecation.py:217 | test call | `assert fm.get_font_catalog() == fm.font_catalog` |
+| `FontManager.get_font_catalog` | core tests | test/test_deprecation.py:229 | test call | `assert fm.get_font_catalog() == fm.font_catalog` |
+| `BasePlugin.get_supported_vegas_modes` | core tests | test/test_vegas_participation.py:356 | test review | `assert plugin.get_supported_vegas_modes() == [` |
+| `BasePlugin.get_supported_vegas_modes` | core tests | test/test_vegas_participation.py:358 | test review | `assert plugin.get_supported_vegas_modes()` |
+| `BasePlugin.get_supported_vegas_modes` | blackjack | manager.py:732 | override | `def get_supported_vegas_modes(self):` |
+| `BasePlugin.get_supported_vegas_modes` | blackjack | manager.py:695 | call | `if mode in self.get_supported_vegas_modes():` |
+| `BasePlugin.get_supported_vegas_modes` | calendar | manager.py:875 | override | `def get_supported_vegas_modes(self) -> List[VegasDisplayMode]:` |
+| `BasePlugin.get_supported_vegas_modes` | olympics | manager.py:624 | override | `def get_supported_vegas_modes(self) -> List[VegasDisplayMode]:` |
+| `BasePlugin.get_vegas_segment_width` | core tests | test/test_vegas_participation.py:359 | test review | `assert plugin.get_vegas_segment_width() == 2` |
 
 ## Sources scanned
 
 | Source | Group | Python files | Hits |
 |---|---|---|---|
-| core | core | 158 | 20 |
-| core tests | core-tests | 316 | 14 |
+| core | core | 164 | 20 |
+| core tests | core-tests | 323 | 17 |
 | 7-segment-clock | monorepo | 3 | 0 |
 | afl-scoreboard | monorepo | 34 | 0 |
 | baseball-scoreboard | monorepo | 60 | 0 |
 | basketball-scoreboard | monorepo | 48 | 0 |
 | birdnet-go | monorepo | 2 | 0 |
-| blackjack | monorepo | 7 | 0 |
-| calendar | monorepo | 5 | 0 |
+| blackjack | monorepo | 7 | 2 |
+| calendar | monorepo | 5 | 1 |
 | christmas-countdown | monorepo | 3 | 0 |
 | clock-simple | monorepo | 2 | 0 |
 | countdown | monorepo | 5 | 0 |
@@ -130,7 +143,7 @@ File paths are relative to the plugin's directory (core: the repo root).
 | nrl-scoreboard | monorepo | 29 | 0 |
 | odds-ticker | monorepo | 9 | 0 |
 | of-the-day | monorepo | 14 | 0 |
-| olympics | monorepo | 16 | 0 |
+| olympics | monorepo | 16 | 1 |
 | on-air | monorepo | 2 | 0 |
 | pomodoro-timer | monorepo | 3 | 0 |
 | soccer-scoreboard | monorepo | 46 | 0 |

docs/PLUGIN_API_REFERENCE.md

@@ -314,6 +314,58 @@ rotating one at a time. Plugins control how their content appears via
 these hooks. See [ADVANCED_FEATURES.md](ADVANCED_FEATURES.md) for the user
 side of Vegas mode.
 
+#### Vegas participation
+
+Each plugin takes part in Vegas mode in one of three ways:
+
+| Participation | What Vegas does |
+|---|---|
+| `'scroll'` | The plugin's content (`get_vegas_content()`) scrolls by with everything else |
+| `'pause'` | The scroll stops when the plugin's turn comes round; its `display()` draws it full screen for `get_display_duration()` seconds, then the scroll resumes |
+| `'exclude'` | The plugin is left out of Vegas mode |
+
+Declare the plugin's default in `manifest.json`:
+
+```json
+{
+  "id": "my-alerts",
+  "vegas_participation": "pause"
+}
+```
+
+The user can override it per plugin with `vegas_participation` in that
+plugin's config section (it is one of the core-owned properties, see
+[PLUGIN_CONFIG_CORE_PROPERTIES.md](PLUGIN_CONFIG_CORE_PROPERTIES.md)).
+Vegas resolves it in this order:
+
+1. the user's `vegas_participation` config value;
+2. the plugin's `get_vegas_participation()` — the default implementation
+   reads the manifest's `vegas_participation`, then derives a value from
+   the legacy hooks below;
+3. derived from the legacy hooks: `get_vegas_display_mode()` returning
+   `VegasDisplayMode.STATIC` → `'pause'`; otherwise
+   `get_vegas_content_type()` returning `'none'` → `'exclude'`; everything
+   else → `'scroll'`.
+
+Step 3 is exactly what Vegas did before participation existed, so a plugin
+that declares nothing behaves as it always has. Manifest
+`vegas_participation` is new in core 3.8.0; older cores ignore it and use
+the legacy hooks.
+
+#### `get_vegas_participation() -> str`
+
+Returns `'scroll'`, `'pause'` or `'exclude'`. Override it only when the
+answer depends on state — pause only while an alert is live, exclude while
+there is nothing to show; for a fixed answer use the manifest. Vegas applies
+the user's config value before calling an override, so an override does not
+need to check it. A value that is not one of the three is ignored with a log
+line and the legacy hooks decide.
+
+```python
+def get_vegas_participation(self):
+    return 'pause' if self._alert_is_live() else 'scroll'
+```
+
 #### `get_vegas_content() -> Optional[PIL.Image | List[PIL.Image] | None]`
 
 Return content to inject into the scroll. Multi-item plugins (sports,
@@ -321,26 +373,40 @@ odds, news) should return a *list* of PIL Images so each item scrolls
 independently. Static plugins (clock, weather) can return a single image.
 Returning `None` falls back to capturing whatever `display()` produces.
 
-#### `get_vegas_content_type() -> str`
+#### `get_vegas_render_width() -> int`
 
-`'multi'`, `'static'`, or `'none'`. Affects how Vegas mode treats the
-plugin. Default `'static'`.
+The width Vegas wants this plugin's content to occupy, from the plugin's
+`vegas_width_pct` config value or the global
+`display.vegas_scroll.render_width_pct`. Vegas also narrows
+`display_manager` while it asks for content, so a plugin that sizes itself
+from `display_manager.width` does not need to read this.
 
-#### `get_vegas_display_mode() -> VegasDisplayMode`
+#### Legacy: `get_vegas_content_type()` and `get_vegas_display_mode()`
 
-Returns one of `VegasDisplayMode.SCROLL`, `FIXED_SEGMENT`, or `STATIC`.
-Read from `config["vegas_mode"]` or override directly.
+Superseded by participation, and still read to derive it when neither the
+user nor the manifest declares one (step 3 above). Only two answers ever
+mattered: `get_vegas_content_type()` returning `'none'`, and
+`get_vegas_display_mode()` returning `VegasDisplayMode.STATIC`.
 
-#### `get_supported_vegas_modes() -> List[VegasDisplayMode]`
+- `get_vegas_content_type()` returns `'multi'`, `'static'` or `'none'`
+  (default `'static'`).
+- `get_vegas_display_mode()` returns a `VegasDisplayMode` member (not a
+  string — the string `'static'` never paused anything). The default reads
+  the plugin's `vegas_mode` config value (`"scroll"`, `"fixed"` or
+  `"static"`), else maps content type `'multi'` to `SCROLL` and anything
+  else to `FIXED_SEGMENT`.
 
-The set of Vegas modes this plugin can render. Used by the UI to populate
-the mode selector for this plugin.
+`SCROLL` and `FIXED_SEGMENT` (and `vegas_mode` `"scroll"` and `"fixed"`)
+have always behaved identically: both scroll. The distinction is deprecated
+and goes away in 3.9.0 — see [Deprecated APIs](#deprecated-apis).
 
-#### `get_vegas_segment_width() -> Optional[int]`
+#### Deprecated: `get_supported_vegas_modes()` and `get_vegas_segment_width()`
 
-For `FIXED_SEGMENT` plugins, the number of *panels* the segment
-occupies in the scroll (pixel width = panels × `single_panel_width`,
-from `display.hardware.cols`). `None` uses the default of 1 panel.
+Never read by core, and removed in 3.9.0: calling the `BasePlugin`
+implementation logs a deprecation warning. A plugin's own override keeps
+working for the plugin itself. `get_vegas_segment_width()` read the
+`vegas_panel_count` config value, which has never affected Vegas — a card's
+width comes from `get_vegas_content()` and `vegas_width_pct`.
 
 > The full source for `BasePlugin` lives in
 > `src/plugin_system/base_plugin.py`. If a method here disagrees with the
@@ -1095,3 +1161,17 @@ are removed in 3.8.0; the rest stay until their callers migrate.
 | `font_manager` | `set_override`, `remove_override`, `get_overrides`, `add_font`, `remove_font`, `validate_font`, `get_size_tokens`, `get_performance_stats`, `get_manager_fonts`, `get_detected_fonts`, `get_plugin_fonts`, `unregister_plugin_fonts` | no replacement |
 | `plugin_manager` | `get_enabled_plugins` | check `enabled` on the entries in `plugin_manager.plugins` |
 
+### Removed in 3.9.0
+
+The Vegas APIs that described a fixed-width segment, which Vegas never
+implemented. Vegas participation (`'scroll'`, `'pause'`, `'exclude'`, see
+[Vegas scroll hooks](#vegas-scroll-hooks)) replaces them. Calling one of the
+methods, or setting `vegas_panel_count`, logs a warning once per process.
+No official plugin calls them; calendar, olympics and blackjack override
+`get_supported_vegas_modes()`, which keeps working for the plugin itself.
+
+| What | Instead |
+|---|---|
+| `BasePlugin.get_supported_vegas_modes()` | declare `vegas_participation` in the manifest |
+| `BasePlugin.get_vegas_segment_width()` and the `vegas_panel_count` config key | nothing: a card's width comes from `get_vegas_content()` and `vegas_width_pct` |
+| `VegasDisplayMode.SCROLL` vs `FIXED_SEGMENT` (`vegas_mode` `"scroll"` vs `"fixed"`) | `'scroll'` participation; the two always behaved the same |

docs/PLUGIN_CONFIG_CORE_PROPERTIES.md

@@ -33,6 +33,20 @@ is `CORE_PLUGIN_PROPERTIES` in `src/plugin_system/schema_manager.py`):
    - Read by `src/vegas_mode/plugin_adapter.py` and `BasePlugin`, which
      validate the values themselves and ignore a bad one with a log line
 
+5. **`vegas_participation`** (string enum: `"scroll"`, `"pause"`,
+   `"exclude"`; no default)
+   - Description: how this plugin takes part in Vegas mode — its content
+     scrolls by, the scroll pauses for its turn and shows it full screen, or
+     it is left out
+   - Overrides the plugin's own default (its manifest's
+     `vegas_participation`, else what its legacy Vegas hooks say); unset
+     means "use the plugin's default"
+   - Deliberately has no default: one would be written into every plugin's
+     config and override what each plugin declares
+   - Read by `resolve_vegas_participation()` in
+     `src/plugin_system/base_plugin.py`; see
+     [PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-participation)
+
 `skin` and `skin_options` were core properties until the skin system was
 removed. A plugin config saved with them still loads and saves; the keys are
 dropped on the next save (see `RETIRED_PLUGIN_KEYS` in `schema_manager.py`).

docs/REST_API_REFERENCE.md

@@ -511,13 +511,21 @@ List all installed plugins with their status and metadata.
         "branch": "main",
         "web_ui_actions": [],
         "vegas_mode": null,
-        "vegas_content_type": null
+        "vegas_content_type": null,
+        "vegas_participation": "scroll"
       }
     ]
   }
 }
 ```
 
+`vegas_participation` is what Vegas mode does with the plugin: `"scroll"`,
+`"pause"` or `"exclude"` (see
+[PLUGIN_API_REFERENCE.md](PLUGIN_API_REFERENCE.md#vegas-participation)).
+For a plugin that is not loaded it is only the user's own
+`vegas_participation` setting, or `null`. `vegas_mode` and
+`vegas_content_type` are the legacy hooks' raw answers.
+
 ### Get Plugin Configuration
 
 **GET** `/api/v3/plugins/config?plugin_id=<plugin_id>`