feat(vegas): keep live games in the ticker by default (#699)

* perf(timing): say which render-thread work a late frame followed

The soak already says how often a moving frame reached the panel late, but
not what the render thread was doing just before it. Vegas does two kinds of
work there between frames -- building its strip (compose, extend) and, with
live elements, patching changed pixels into it -- and deciding whether either
is affordable needs their own numbers.

- FrameTimingRecorder.note_op(kind, nbytes) tags the next presented frame.
  Totals gain op_frames, late_op_frames, op_freezes and op_bytes per kind;
  aggregate() still takes frames without ops. The file schema is unchanged.
- Vegas tags compose and every strip extension (with the bytes it copied).
- frame_soak prints an "after work" table: frames, late %, freezes and MB
  moved per kind, only when something tagged its work.
- render_bench gains --strip-screens (Vegas-sized strips), --patch-bytes /
  --patch-every / --patch-where (in-place column writes, as a live element
  update does) and --extend-every-screens / --extend-width (append + trim on
  a fixed cadence that holds the strip's width).

No runtime behaviour changes: this is the measurement gate for live Vegas
elements.

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

* docs(changelog): note the frame-op attribution and bench modes

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

* perf(scroll): build the strip's PIL image only when something reads it

Every Vegas strip extension rebuilt ScrollHelper.cached_image from
cached_array in full, twice (append, then trim), on the render thread:
Image.fromarray is 1.7ms for an 8,000px strip and 3.8ms for 20,000px on a
Pi 4 (measured on ledpi), about two thirds of an extension's render-thread
cost. Nothing on the frame path reads the image's pixels; every frame is cut
from the array.

cached_image is now a property. append_content and drop_scrolled_prefix
defer it; the first read builds it from the array it started with and keeps
it only if the strip has not changed meanwhile, so a sync push racing an
extension cannot leave a stale image cached. Assigning cached_image stores
exactly what was assigned, as before. has_strip() says whether there is a
strip without building its image; the helper's frame path, Vegas and the
adapter's scroll-cache invalidation use it. The strip is also no longer held
in memory twice.

In Vegas the image is now built only by a multi-display sync push.

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

* feat(vegas): live elements -- a plugin API for content that changes while it scrolls

Vegas bakes each plugin's pictures into one strip, so a card already on its
way across the panel keeps what it showed when it was drawn. This adds the
API and bookkeeping for content that can be updated in place; the worker
that redraws and swaps it follows separately. No shipped plugin implements
the hook yet, so nothing changes for users.

Plugin API (core 3.8.0), all no-ops by default:
- BasePlugin.get_vegas_elements() -> [VegasElement(key, image, version,
  live, refresh_hz)]: named, fixed-width pieces of Vegas content.
- BasePlugin.redraw_vegas_element(key, width, height, at): a lock-free
  redraw for content that changes with time.
- BasePlugin.notify_vegas_data_changed(): data that lands outside update().
- src/plugin_system/vegas_elements.py (VegasElement, re-exported from
  base_plugin).

Core:
- PluginAdapter asks a plugin that implements the hook for elements on the
  background fetch only (under its lock, on its own canvas); every other
  path keeps get_vegas_content(). Live elements are pinned (padded with
  content_padding, never trimmed), tagged with their key, digest and data
  epoch in Image.info so the existing cache and group plumbing carry them
  unchanged, and untagged if a width budget crops them.
- RenderPipeline records where each live element lands (ElementRecord), in
  absolute strip columns a trim does not move; the block-start arithmetic
  is shared with the STATIC markers.
- PluginManager update listeners (add/remove_update_listener,
  notify_data_changed): told the moment update() completes, not at the
  next ~4s Vegas poll. The coordinator uses one to move each plugin's data
  epoch on.
- vegas_scroll.live_refresh (kill switch), live_max_hz, live_min_interval,
  live_lead_screens; per-plugin core-owned vegas_live. Live elements are
  off under multi-display sync, in swap mode and with offscreen_prefetch off.
- scripts/check_plugin.py checks the element contract
  (src/plugin_system/testing/vegas.py); test/fixtures/plugins/vegas-live-stub
  is a working example.

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

* feat(vegas): live elements update in place while they scroll

One background worker (src/vegas_mode/live_worker.py) redraws a plugin's
live elements when its data epoch moves on (update listener) or on their
refresh_hz, nearest the screen first, and hands changed pixels lock-free to
the render thread, which copies them into the strip between frames
(RenderPipeline.apply_live_patches, ScrollHelper.patch_columns): at most
four patches or two screens of bytes a frame, no drawing or locks there.
The worker takes over group prefetch once a live element is placed, runs
inside the render gate, and is supervised. Update tick 1s while live
elements exist. Web UI switch for live_refresh. OFFSCREEN_RENDERING.md
describes what was built and why SegmentStrip was not needed.

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

* feat(sports): live Vegas cards for the scoreboards (shared layer)

One live element per game, drawn only when what the card shows changes, so
a score changes on a card already crossing the panel. The shared part, so
each scoreboard adopts it in a few lines:

- src/common/sports_vegas.py: game_key, game_fingerprint (the whole game
  dict, frozen: no drawn field can be missed), dedupe_games, VegasCardCache,
  StickyOdds (odds a live poll left out stay drawn), finished_games /
  with_finished_games (a game that just went final keeps its card, after its
  league's live games; one a heuristic only judged over keeps its live
  state, so a tied end of regulation never shows FINAL early).
- SportsScrollDisplay.make_vegas_renderer() is the override point;
  build_vegas_elements() and SportsScrollDisplayManager
  .get_vegas_elements_for() do the rest. A card's version includes its
  teams' ranks, which the renderer draws from the rankings cache.
- SportsLiveSharedMixin._record_finished_game() / finished_games_snapshot():
  held for FINISHED_GAME_TTL after it leaves the live list.

A sport that does not implement make_vegas_renderer keeps its ordinary Vegas
content, so no scoreboard changes until it opts in.

scripts/render_plugin.py --vegas renders a plugin's Vegas block as the
ticker lays it out, and --timeline stacks it at successive moments as
the ticker would update it in place; the join is now
render_pipeline.join_plugin_rows().

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

* feat(vegas): keep live games in the ticker by default

display.vegas_scroll.live_in_ticker now defaults to true: through a live
game the marquee keeps running and the live scoreboard takes extra turns in
it -- its cards updating in place while they scroll -- instead of the ticker
giving way to the full-screen scoreboard.

The new default would reach nobody on its own: every existing config holds
an explicit false copied from the template (there was no control for it),
and the template merge only adds missing keys. ConfigManager therefore turns
a stored false on once, with a backup, and records live_in_ticker_migrated
so a false chosen afterwards stays. The marker is never in the template.

A "Keep live games in the ticker" checkbox under Vegas mode sets it. Tests
that pin the full-screen takeover now say live_in_ticker=false.

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

* refactor(sports): a default _determine_game_type on SportsScrollDisplay

render_vegas_card looked the method up with getattr and a None default, which
static analysis (Codacy) reports as calling something that may not be
callable. The base class now has the default -- the card type from the game's
state -- and the plugins that define their own override it as before.

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

* fix: review follow-ups on the shared live-card layer

- The reused Vegas renderer always gets the current rankings, empty
  included, so ranks cleared since are not kept drawn.
- render_plugin.py: --timeline refuses --no-live (a timeline shows live
  elements changing), --timeline/--no-live need --vegas, and the Vegas
  paths create the output's directory like the display path does.

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

src/config_manager.py

@@ -451,8 +451,10 @@ class ConfigManager:
                 template_config = json.load(f)
             
             # Check if migration is needed
-            if self._config_needs_migration(self.config, template_config):
-                self.logger.info("Config migration needed - adding new configuration items with defaults")
+            needs_merge = self._config_needs_migration(self.config, template_config)
+            if needs_merge or self._live_in_ticker_needs_migration():
+                if needs_merge:
+                    self.logger.info("Config migration needed - adding new configuration items with defaults")
                 
                 # Create backup of current config
                 backup_path = f"{self.config_path}.backup"
@@ -461,7 +463,9 @@ class ConfigManager:
                 self.logger.info(f"Created backup of current config at {os.path.abspath(backup_path)}")
                 
                 # Merge template defaults into current config
-                self._merge_template_defaults(self.config, template_config)
+                if needs_merge:
+                    self._merge_template_defaults(self.config, template_config)
+                self._migrate_live_in_ticker_default()
                 
                 # save_config_atomic strips the merged secrets back out and
                 # keeps the file's owner and mode.
@@ -482,6 +486,44 @@ class ConfigManager:
             self.logger.error(f"Error during config migration: {e}")
             # Don't raise - continue with current config
 
+    #: Set in display.vegas_scroll once _migrate_live_in_ticker_default() has
+    #: run. Never in the template: the template merge would add it first, and
+    #: the flip would then never run.
+    LIVE_IN_TICKER_MARKER = 'live_in_ticker_migrated'
+
+    def _vegas_scroll_section(self) -> Optional[Dict[str, Any]]:
+        display = self.config.get('display')
+        vegas = display.get('vegas_scroll') if isinstance(display, dict) else None
+        return vegas if isinstance(vegas, dict) else None
+
+    def _live_in_ticker_needs_migration(self) -> bool:
+        vegas = self._vegas_scroll_section()
+        return vegas is not None and not vegas.get(self.LIVE_IN_TICKER_MARKER)
+
+    def _migrate_live_in_ticker_default(self) -> None:
+        """Turn on live_in_ticker for a config that only ever had the old default. Once.
+
+        LEDMatrix 3.8.0 makes ``display.vegas_scroll.live_in_ticker`` true:
+        live games stay in the Vegas ticker, their cards updating while they
+        scroll, instead of the ticker giving way to the full-screen
+        scoreboard. Every existing config holds an explicit ``false`` copied
+        from the template -- there was no control for it -- and the template
+        merge only adds missing keys, so the new default would reach nobody.
+        This rewrites that ``false`` once and marks the config, so a
+        ``false`` chosen afterwards (the Vegas checkbox, or by hand) stays.
+        """
+        vegas = self._vegas_scroll_section()
+        if vegas is None or vegas.get(self.LIVE_IN_TICKER_MARKER):
+            return
+        vegas[self.LIVE_IN_TICKER_MARKER] = True
+        if vegas.get('live_in_ticker') is False:
+            vegas['live_in_ticker'] = True
+            self.logger.info(
+                "Vegas mode now keeps live games in the ticker (the new default): "
+                "display.vegas_scroll.live_in_ticker turned on, once. Untick "
+                "\"Keep live games in the ticker\" under Vegas mode for the "
+                "full-screen scoreboard.")
+
     def _config_needs_migration(self, current_config: Dict[str, Any], template_config: Dict[str, Any]) -> bool:
         """Check if config needs migration by comparing with template."""
         return self._has_new_keys(current_config, template_config)

src/display_controller.py

@@ -2206,7 +2206,7 @@ class DisplayController:
         """Whether live content should stay in the ticker instead of preempting it."""
         coordinator = self.vegas_coordinator
         config = getattr(coordinator, 'vegas_config', None)
-        return bool(getattr(config, 'live_in_ticker', False))
+        return bool(getattr(config, 'live_in_ticker', True))
 
     def _check_live_priority(self, advance=False):
         """Return the live-priority mode to display, or None if nothing is live.

src/vegas_mode/config.py

@@ -180,10 +180,13 @@ class VegasModeConfig:
 
     # --- Live content in the ticker -------------------------------------
     #
-    # By default a live game preempts Vegas entirely: the display controller
-    # refuses to run the ticker while any plugin reports live priority, and you
-    # get the full-screen scoreboard instead. Set live_in_ticker to keep the
-    # marquee running and let live content take extra turns within it.
+    # By default live content stays in the marquee and takes extra turns
+    # within it, its cards updating while they scroll (live elements, below).
+    # With live_in_ticker false a live game preempts Vegas entirely: the
+    # display controller refuses to run the ticker while any plugin reports
+    # live priority, and you get the full-screen scoreboard instead. (False
+    # was the default until 3.8.0; ConfigManager turns it on once for configs
+    # that still hold the old default.)
     #
     # The rotation is otherwise a strict round robin -- every plugin appears
     # exactly once per cycle -- so with a dozen plugins enabled a live score
@@ -193,7 +196,7 @@ class VegasModeConfig:
     # Weights are per plugin, not per game: a scoreboard showing four live
     # games still occupies one slot at a time, and rotates its own games within
     # that slot using its own favorite_live_boost.
-    live_in_ticker: bool = False
+    live_in_ticker: bool = True
 
     # Slots per cycle for a plugin reporting live content. 1 disables the boost
     # and restores the plain round robin.