feat(sports): opt-in celebration and rotation capabilities

Phase B2 of the sports unification. Both features exist in only some of
the nine scoreboards, so they ship as capabilities the plugin composes,
never as `if self.<feature>_enabled` branches inside the base classes: a
sport that does not opt in has none of this code in its MRO.

CelebrationMixin (afl, nrl, soccer, football)
The two lineages spelled this differently -- _check_for_goal /
celebrate_opponent_goals vs _check_for_score / celebrate_opponent_scores
-- but the bodies were identical apart from three things, each now a
seam rather than a branch:
  - wording -> score_phrase() / win_phrase() hooks
  - follow-up suppression -> COALESCE_SCORING_SEQUENCE, on for football
    where a touchdown lands as +6 then +1, off where two increments are
    two real goals
  - team identity -> _favorite_key, so nrl matches on team id without
    core learning why its abbreviations are ambiguous
Both config spellings are read, so a plugin adopting the mixin keeps
working with the keys already in its published schema.

Rotation strategies
The three "dialects" turned out to be one algorithm (SWRR) in two
shapes: an incremental picker holding state across calls, and a
precomputed per-cycle list. They agree within a cycle and differ only at
the boundary, so core ships both behind a name registry rather than
declaring a winner. weight_for is supplied by the host, so rotation.py
never learns what a favorite is; an unknown name degrades to "simple"
because it arrives from user config.

Each strategy is checked against a verbatim transcription of the plugin
code it replaces, over every live-game shape up to four games -- the
differential B5 will delete the bundled copies on the strength of.

185 new tests. Gates: 648 core unit, 60 plugin safety.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FgbA8SMutQQpXkMG8LMmC4

.github/workflows/test.yml

@@ -5,6 +5,10 @@ on:
   push:
     branches: [main]
 
+# Both jobs only check out the repo and run pytest.
+permissions:
+  contents: read
+
 jobs:
   plugin-safety:
     name: Plugin safety harness + unit tests
@@ -31,3 +35,44 @@ jobs:
             test/plugins/test_harness.py \
             test/plugins/test_visual_rendering.py \
             test/plugins/test_plugin_matrix.py
+
+  unit-tests:
+    name: Core unit tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt -r requirements-test.txt
+          pip install RGBMatrixEmulator
+
+      # Safety net for the shared sports/scroll/style infrastructure. These
+      # suites existed but were not enrolled in CI, so a refactor of
+      # src/base_classes or src/common could regress them silently. Enrolled
+      # explicitly (not `pytest test/`) so known hardware-only suites don't
+      # break CI; grow this list as more suites are made headless.
+      - name: Run core unit suites
+        run: |
+          pytest --no-cov \
+            test/test_skin_system.py \
+            test/test_font_manager.py \
+            test/test_data_sources.py \
+            test/test_api_extractors.py \
+            test/test_scroll_helper.py \
+            test/test_scroll_helper_continuous.py \
+            test/test_adaptive_layout.py \
+            test/test_loader_compat_warning.py \
+            test/test_sports_base_characterization.py \
+            test/test_element_style.py \
+            test/test_sports_core_promotions.py \
+            test/test_sports_modes_promotions.py \
+            test/test_sports_capabilities.py

CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+Notable changes to the LEDMatrix core. The version below is the value of
+`src.__version__`, which the plugin loader reports to compatibility checks and
+which plugin manifests reference via `ledmatrix_min_version`.
+
+**Why this file exists:** the plugin monorepo bundles fallback copies of several
+core modules (see `docs/plugin-development/08-shared-sports-code.md` in
+[ledmatrix-plugins](https://github.com/ChuckBuilds/ledmatrix-plugins)). A plugin
+may delete its bundled copy only when its manifest floors on the first core
+release that ships the module — which requires module additions to be recorded
+here, against a version number. When you add a module plugins will import via
+`src.*`, note it in the Unreleased section and bump `src/__init__.py` in the
+release that ships it.
+
+## Unreleased
+
+### Added
+- `src/element_style.py` — per-element style resolver backing the
+  `x-style-elements` config-schema extension. Already consumed (behind guarded
+  imports with classic fallbacks) by the `of-the-day`, `ledmatrix-music`, and
+  `football-scoreboard` plugins.
+- Core unit-test CI job enrolling the previously unenrolled suites (skin
+  system, data sources, API extractors, scroll helper, adaptive layout, loader
+  compatibility warning) plus new characterization tests for
+  `src/base_classes/sports.py` ahead of the shared sports-code unification.
+
+- `src/base_classes/sports/` — `sports.py` is now a package (`core.py` +
+  `modes.py`). The import path is unchanged: `from src.base_classes.sports
+  import SportsCore` still works.
+- Nine methods promoted onto the sports base classes from the plugins'
+  bundled copies, plus the override points `_favorite_key`,
+  `_config_schema_path` and `_font_root` and the class attributes
+  `FINAL_PERIOD` / `CLOCK_COUNTS_DOWN`. See `docs/SPORTS_UNIFICATION.md`.
+  A plugin may start calling these once its manifest floors
+  `ledmatrix_min_version` at the release that ships them.
+
+- `src/base_classes/sports/capabilities/` — opt-in capabilities for the sports
+  scoreboards, composed by inheritance rather than gated by config branches
+  inside the base classes:
+  - `CelebrationMixin` — the score/win takeover, merging the goal and score
+    dialects behind the `score_phrase()` / `win_phrase()` hooks, the
+    `COALESCE_SCORING_SEQUENCE` class attribute and the `_favorite_key` seam.
+    Reads both the `celebrate_opponent_goals` and `celebrate_opponent_scores`
+    config spellings. Sports that do not mix it in have none of this code in
+    their MRO.
+  - `RotationStrategy` + a name registry (`swrr`, `weighted`, `simple`,
+    plus `register_rotation_strategy` for plugin-supplied orderings). Each
+    built-in is verified against a verbatim transcription of the plugin
+    implementation it replaces. An unknown name degrades to `simple`.
+
+### Changed
+- **Live games are no longer dropped when the feed omits a game clock.**
+  `SportsLive._is_game_really_over` previously (in the baseball and UFC
+  plugin lineages) coerced a missing or non-string clock to the literal
+  `"0:00"` and then treated the game as finished once `period >= 4`. Baseball
+  has no game clock and `period` is the inning, so live MLB games disappeared
+  from the scoreboard from the 5th inning onward; UFC was affected the same
+  way. The clock check is now skipped when the clock is unusable, and the
+  period threshold is the per-sport `FINAL_PERIOD` (hockey ends in P3).
+  Sports whose clocks count up — soccer, AFL, NRL — set
+  `CLOCK_COUNTS_DOWN = False` and never run the check at all, since `0:00`
+  there means kickoff rather than expiry.
+
+### Fixed
+- `FontManager` resolves `assets/fonts` against the core install root instead
+  of the process working directory, so font loading works when the process
+  starts elsewhere (e.g. the plugin safety harness on CI).
+- Hockey events whose competitors carry no `statistics` array are no longer
+  discarded. The extractor read `competitor["statistics"]` unguarded, so a
+  `KeyError` inside the generator dropped the entire event despite valid
+  scores and status; shot counts now fall back to `0`.
+- Live baseball events that populate status only at the competition level are
+  no longer discarded. The extractor read the event top-level
+  `game_event["status"]` for the inning; real ESPN events duplicate it, but
+  MiLB events synthesized from the MLB Stats API do not, so the lookup raised
+  a bare `KeyError`. It now reads the already-validated competition-level
+  status.
+- `SportsLive._is_game_really_over` no longer crashes the live-update pass when
+  a feed sends an explicit null `period`. `None >= FINAL_PERIOD` raised
+  `TypeError`, and the only caller (`_detect_stale_games`) has no `try/except`
+  — the same failure shape as the already-fixed null `period_text`.
+- An expired clock spelled `"00:00"` now ends the game. The check compared the
+  colon-stripped clock against a hand-listed set of literals, which `"0000"` is
+  not a member of, so a finished game with a two-digit-minute clock stayed on
+  the scoreboard indefinitely. The comparison is now numeric.
+- `SportsCore._load_fonts` resolves `assets/fonts` through the `_font_root()`
+  seam instead of the process working directory. Started outside the install
+  root, every scoreboard font silently degraded to PIL's default bitmap face.
+- `SportsCore._should_log` no longer raises `AttributeError` on the first
+  warning of a run; `_last_warning_time` is initialized in `__init__` rather
+  than lazily by an unrelated method.
+- `SportsCore._resolve_project_path` resolved relative logo directories
+  against `<root>/src` instead of the repo root after `sports.py` became a
+  package — the class bodies moved byte-identically but `__file__` gained a
+  directory. Both it and `_font_root` now derive from one `_INSTALL_ROOT`
+  constant.
+
+## 3.1.0
+
+Baseline for this changelog. Highlights already shipped at this version:
+skin system for sports scoreboards (#419), Vegas continuous-scroll overhaul
+(#423), plugin update surfacing (#421).

docs/SPORTS_UNIFICATION.md

@@ -0,0 +1,196 @@
+# Sports Code Unification — Architecture
+
+How the nine sports scoreboard plugins converge onto shared core code **without**
+becoming nine clients of a god class.
+
+## The problem
+
+Nine plugins (`afl`, `baseball`, `basketball`, `football`, `hockey`, `lacrosse`,
+`nrl`, `soccer`, `ufc`) each ship a ~3,000-line `sports.py` descended from this
+repo's `src/base_classes/sports.py`. They have drifted into three lineages, and
+only 28 of the 66 methods appearing across them are present in all nine. One
+logical fix (the UTC start-time bug) cost 75 files.
+
+Merging everything into one base class would fix the duplication and create a
+worse problem: a single 2,500-line class that all nine plugins inherit, where any
+change has a nine-plugin blast radius and per-sport behavior survives only as
+`if self.sport == "hockey"` branches.
+
+## Three properties, three mechanisms
+
+These are independent concerns. Conflating them is what produces god classes.
+
+### Upgradability — a plugin keeps working across core versions
+
+| Rule | Mechanism |
+|---|---|
+| Plugin loads on a core that predates a module | Guarded import with a bundled fallback (`try: from src.X import Y / except ModuleNotFoundError: from y import Y`) |
+| Plugin loads on a core that predates a *method* | Capability probing — `hasattr(SportsCore, "_detect_stale_games")` — never a version comparison. The loader's compat check is advisory-only (it logs and continues), so probing is the real protection. |
+| Core changes never break a plugin's rendering | The **view-model contract**: `_extract_game_details_common` returns a dict whose `GUARANTEED_KEYS` are frozen by `test/test_skin_system.py::TestViewModelContract`. Keys may be added, never renamed or removed. |
+| A plugin can drop its bundled copy safely | The **sunset rule**: only when its manifest floors `ledmatrix_min_version` at the first core release shipping the module (recorded in `CHANGELOG.md`). |
+
+The core API is **additive-only**. A method the plugins call is never removed or
+given a new required parameter; new behavior arrives as new methods with
+defaults, or as capabilities they opt into.
+
+### Reusability — write once, nine plugins benefit
+
+Only code that is **identical in intent across all nine** moves into the base
+class. That set is small and knowable — it is exactly the methods present in every
+copy today (phase B1 below). Everything else stays where it is until it earns
+promotion.
+
+### Modularity — a change to one feature cannot reach a plugin that doesn't use it
+
+This is the property the naive merge destroys, and it is enforced structurally:
+
+1. **Capabilities are separate modules composed by inheritance, not config
+   branches inside the base class.** Hockey has no celebrations, so
+   `HockeyLive` does not inherit `CelebrationMixin` — the celebration code is not
+   merely disabled for hockey, it is *not in hockey's MRO at all*. No shared
+   state, no dead branches, no risk. Contrast with
+   `if self.celebrations_enabled:` inside `SportsLive`, where a bug in
+   celebration code can still crash a plugin that never wanted the feature.
+
+2. **Variant behavior is a strategy object chosen by name, not a branch.**
+   Live rotation exists in three dialects across the lineages; core ships all
+   three behind `rotation_strategy: "swrr" | "weighted" | "simple"` and a plugin
+   may register its own. Core never learns sport names.
+
+3. **Sport-specific behavior is a documented override point.** The base class
+   declares the seam; the plugin fills it. Basketball's tournament-round parsing
+   and baseball's BDF sizing stay in their plugins forever — they are not
+   candidates for promotion, and core must never grow a branch for them.
+
+4. **Files bound the blast radius.** Capabilities live in their own modules so a
+   diff shows at a glance which plugins a change can reach.
+
+## Layering
+
+```
+src/base_classes/sports/
+  __init__.py            re-exports the public API (import path unchanged)
+  core.py                SportsCore — fetch, cache, config, logos, fonts, odds,
+                         view-model extraction, the skin seam
+  modes.py               SportsUpcoming / SportsRecent / SportsLive
+  capabilities/
+    celebrations.py      CelebrationMixin        (opt-in: 4 of 9 plugins)
+    rotation.py          RotationStrategy + registry
+```
+
+`from src.base_classes.sports import SportsCore` keeps working — the package
+`__init__` re-exports, so the conversion is invisible to every existing importer.
+
+## Override points (the plugin-facing seam)
+
+The base class calls these; plugins implement or override them. This table is the
+contract — additions require a default implementation, removals require a
+deprecation cycle.
+
+| Hook | Purpose | Default |
+|---|---|---|
+| `_fetch_data()` | Sport's schedule source | abstract |
+| `_extract_game_details(event)` | Sport-specific view-model fields on top of the common ones | delegates to `_extract_game_details_common` |
+| `_draw_scorebug_layout(game, force_clear)` | Sport's card rendering | base layout |
+| `_custom_scorebug_layout(game, draw)` | Per-sport overlay on the base layout | no-op |
+| `render_skin_card(game, size)` | Skin-system entry point | built-in fallback |
+| `score_phrase(points, team_abbr)` | Celebration wording (`"GOOOOAAALLL!"` vs `"TOUCHDOWN!"`). `points` is the score delta, which sports with variable-value scores use to name the play | `"<abbr> SCORES!"` — only consulted when `CelebrationMixin` is present |
+| `win_phrase(team_abbr)` | Win-celebration wording | `"<abbr> WINS!"` — mixin only |
+| `_favorite_key(game, side)` | Which view-model field identifies a team for favorites matching | `game["<side>_abbr"]` |
+| `_config_schema_path()` | Plugin's `config_schema.json` — returning it routes `_get_layout_offset` through the `src.element_style` resolver (and gives it the defaults to compare against) | `None`, i.e. the classic inline `customization.layout` read |
+| `_font_root()` | Directory to resolve `assets/fonts` against | core install root |
+
+Two class attributes serve the same purpose for values that are per-sport
+constants rather than behavior:
+
+| Attribute | Meaning | Default |
+|---|---|---|
+| `FINAL_PERIOD` | Period at/after which a zero clock can mean "over" | `4` (hockey overrides to `3`) |
+| `CLOCK_COUNTS_DOWN` | Whether `0:00` means "expired" | `True` (soccer/afl/nrl override to `False` — their clocks count up, so `0:00` is kickoff) |
+| `COALESCE_SCORING_SEQUENCE` | Fold score increments arriving during an active celebration into that one celebration | `False` (football overrides to `True` — a touchdown lands as +6, then +1 for the extra point) |
+
+### Why these are seams and not branches
+
+`_favorite_key` exists because NRL abbreviations are **not unique** — "NEW" is both
+Newcastle Knights and New Zealand Warriors, "CAN" both Canberra and Canterbury —
+so NRL matches favorites on team ID. Flattening every plugin to abbreviations
+would silently select the wrong club for NRL users. The base declares the seam,
+NRL fills it, and core never learns the string `"nrl"`.
+
+`CLOCK_COUNTS_DOWN` exists for the same reason in the opposite direction: a
+soccer clock reading `0:00` means the match has not kicked off, so running the
+clock-expiry branch there would evict live games.
+
+`COALESCE_SCORING_SEQUENCE` is the third of the same kind. In football one
+scoring play arrives as two score updates, so the follow-up must be folded into
+the first celebration; in soccer two increments a few seconds apart are two real
+goals, and folding them would swallow one. Neither default is "right" — which is
+precisely why it is a declared per-sport constant rather than a hidden
+assumption baked into the shared body.
+
+## Capabilities
+
+```
+capabilities/
+  celebrations.py   CelebrationMixin        opt-in: afl, nrl, soccer, football
+  rotation.py       RotationStrategy + registry
+```
+
+**`CelebrationMixin`** merges the two dialects the lineages grew
+(`_check_for_goal`/`celebrate_opponent_goals` vs
+`_check_for_score`/`celebrate_opponent_scores`). Their bodies were identical
+apart from three things, each now a seam: wording (`score_phrase`), follow-up
+suppression (`COALESCE_SCORING_SEQUENCE`), and team identity (`_favorite_key`,
+so NRL matches on id). Both config spellings are read, so a plugin adopting the
+mixin keeps working with the keys already in its published schema.
+
+Mix it in **before** the mode class — `class SoccerLive(CelebrationMixin,
+SportsLive)` — so the celebration `display()` runs first and falls through to
+the scorebug via `super()`.
+
+**Rotation strategies.** The three "dialects" turned out to be one algorithm
+(Smooth Weighted Round-Robin) in two shapes: an incremental picker holding state
+across calls (afl/nrl/soccer) and a precomputed per-cycle list
+(football/baseball/basketball, and hockey with a different loop shape). They
+agree within a cycle and differ only at the boundary — the incremental form has
+no restart seam — so core ships both rather than declaring a winner:
+
+```python
+self.rotation = get_rotation_strategy("swrr", weight_for=self._live_weight)
+```
+
+`weight_for` is supplied by the host, so the *favorites* policy stays with the
+plugin and `rotation.py` never learns what a favorite is. An unknown strategy
+name degrades to `simple` rather than raising: the name comes from user config,
+and a typo should cost the boost, not the scoreboard. A plugin needing an
+ordering core does not ship calls `register_rotation_strategy` instead of core
+growing a branch.
+
+`test_sports_capabilities.py` checks each strategy against a **verbatim
+transcription** of the plugin code it replaces, over every live-game shape up to
+four games. That differential is what B5 deletes the bundled copies on the
+strength of.
+
+## Phases
+
+| Phase | Scope | Risk control |
+|---|---|---|
+| **B0** ✅ | Characterization tests, CI unit job, `element_style`, font cwd fix, CHANGELOG discipline | — |
+| **B1** ✅ | Promote the nine universal methods; convert `sports.py` → package | Characterization suite must stay green; no behavior change intended |
+| **B2** ✅ | `CelebrationMixin` + rotation strategies as opt-in capabilities | Plugins that don't opt in have zero new code in their MRO; strategies checked against verbatim plugin transcriptions |
+| **B3** | Upstream `ScrollDisplay` as `src/common/sports_scroll.py`, reading `global_config['target_fps']` natively | Plugin copies remain until sunset |
+| **B4** | Bump to 3.2.0, record modules in CHANGELOG, migrate `ledmatrix_min` → `ledmatrix_min_version` | Gives plugins a version to floor on |
+| **B5** | Pilot one plugin per lineage (hockey, soccer, football) on guarded core imports; then the remaining six; then delete bundled copies | Pilot soaks before rollout; harness + golden suites gate each |
+
+## Rules for contributors
+
+- **Promote on evidence, not intuition.** A method moves to core when every copy
+  has it and they agree on intent. Otherwise it stays in the plugins.
+- **Never add a sport name to core.** If core needs to know which sport it is,
+  the design is wrong — add an override point instead.
+- **A capability that is not opted into must not execute.** If you find yourself
+  writing `if self.<capability>_enabled` inside a base class, it belongs in a
+  mixin.
+- **Touch the view-model keys only additively.** Published skins depend on them.
+- **Every promotion lands with the characterization suite green**, and every
+  pilot adoption lands with that plugin's harness and golden suites green.

src/base_classes/baseball.py

@@ -164,7 +164,13 @@ class Baseball(SportsCore):
             # Get game state information
             if status_state == "in":
                 # For live games, get detailed state
-                inning = game_event["status"].get(
+                # Use the competition-level `status` already validated by
+                # _extract_game_details_common. Real ESPN events duplicate
+                # status at the event top level, but MiLB events (synthesized
+                # from the MLB Stats API into an ESPN-like shape) populate
+                # only the competition-level one, so the top-level lookup
+                # raised a bare KeyError and dropped the event.
+                inning = status.get(
                     "period", 1
                 )  # Get inning from status period
 
@@ -187,7 +193,7 @@ class Baseball(SportsCore):
                 if "end" in status_detail or "end" in status_short:
                     inning_half = "top"
                     inning = (
-                        game_event["status"].get("period", 1) + 1
+                        status.get("period", 1) + 1
                     )  # Use period and increment for next inning
                     if is_favorite_game:
                         self.logger.debug(

src/base_classes/hockey.py

@@ -38,10 +38,17 @@ class Hockey(SportsCore):
             status = competition["status"]
             powerplay = False
             penalties = ""
+            # A competitor may legitimately arrive without a "statistics"
+            # array (pre-game feeds, and some in-progress ones). Reading it
+            # unguarded raised KeyError inside the generator and dropped the
+            # WHOLE event, discarding valid scores and status. Default to an
+            # empty list so the saves/shots figures fall back to 0 instead.
+            home_stats = home_team.get("statistics", [])
+            away_stats = away_team.get("statistics", [])
             home_team_saves = next(
                 (
                     int(c["displayValue"])
-                    for c in home_team["statistics"]
+                    for c in home_stats
                     if c.get("name") == "saves"
                 ),
                 0,
@@ -49,7 +56,7 @@ class Hockey(SportsCore):
             home_team_saves_per = next(
                 (
                     float(c["displayValue"])
-                    for c in home_team["statistics"]
+                    for c in home_stats
                     if c.get("name") == "savePct"
                 ),
                 0.0,
@@ -57,7 +64,7 @@ class Hockey(SportsCore):
             away_team_saves = next(
                 (
                     int(c["displayValue"])
-                    for c in away_team["statistics"]
+                    for c in away_stats
                     if c.get("name") == "saves"
                 ),
                 0,
@@ -65,7 +72,7 @@ class Hockey(SportsCore):
             away_team_saves_per = next(
                 (
                     float(c["displayValue"])
-                    for c in away_team["statistics"]
+                    for c in away_stats
                     if c.get("name") == "savePct"
                 ),
                 0.0,

src/base_classes/sports/__init__.py

@@ -0,0 +1,17 @@
+"""Sports scoreboard base classes.
+
+Formerly the single module ``src/base_classes/sports.py``; now a package so
+capabilities can be composed instead of accumulating in one class. See
+docs/SPORTS_UNIFICATION.md for the architecture. The import path is
+unchanged: ``from src.base_classes.sports import SportsCore`` still works.
+"""
+
+from .core import SportsCore
+from .modes import SportsLive, SportsRecent, SportsUpcoming
+
+__all__ = [
+    "SportsCore",
+    "SportsUpcoming",
+    "SportsRecent",
+    "SportsLive",
+]

src/base_classes/sports/capabilities/__init__.py

@@ -0,0 +1,32 @@
+"""Opt-in capabilities for the sports scoreboards.
+
+Each module here is a feature that only *some* sports want. They are composed
+by inheritance (mixins) or selected by name (strategies) — never enabled by an
+``if self.<feature>_enabled:`` branch inside the base classes.
+
+The distinction matters: hockey has no celebrations, so ``HockeyLive`` does not
+inherit :class:`~.celebrations.CelebrationMixin` and the celebration code is not
+in hockey's MRO at all. A bug in it cannot reach a plugin that never opted in.
+
+See ``docs/SPORTS_UNIFICATION.md`` for the full rationale.
+"""
+
+from .celebrations import CelebrationMixin
+from .rotation import (
+    RotationStrategy,
+    SimpleRotation,
+    SmoothWeightedRotation,
+    WeightedCycleRotation,
+    get_rotation_strategy,
+    register_rotation_strategy,
+)
+
+__all__ = [
+    "CelebrationMixin",
+    "RotationStrategy",
+    "SimpleRotation",
+    "SmoothWeightedRotation",
+    "WeightedCycleRotation",
+    "get_rotation_strategy",
+    "register_rotation_strategy",
+]

src/base_classes/sports/capabilities/celebrations.py

@@ -0,0 +1,379 @@
+"""Score / win celebration takeover — an opt-in capability.
+
+Four of the nine scoreboards celebrate (afl, nrl, soccer, football); the other
+five do not. This is a **mixin** rather than a flag inside ``SportsLive`` so the
+five that do not opt in have none of this code in their MRO: a bug here cannot
+reach hockey, and hockey's config never grows keys it ignores.
+
+Usage — mix in *before* the mode class so its ``display`` runs first::
+
+    class SoccerLive(CelebrationMixin, SportsLive):
+        def score_phrase(self, points, team_abbr):
+            return secrets.choice(("GOOOOAAALLL!", f"{team_abbr} SCORES!"))
+
+The two lineages spelled this differently (``_check_for_goal`` /
+``celebrate_opponent_goals`` in the soccer lineage, ``_check_for_score`` /
+``celebrate_opponent_scores`` in football) but the bodies were identical apart
+from three things, each of which is a seam here rather than a branch:
+
+* **wording** — :meth:`score_phrase`, the hook football uses to say "TOUCHDOWN"
+  from the points delta and soccer uses to say "GOOOOAAALLL";
+* **follow-up suppression** — :attr:`COALESCE_SCORING_SEQUENCE`, on for football
+  where a touchdown lands as +6 then +1 a few seconds later, off elsewhere where
+  two quick goals are two real events;
+* **team identity** — matching goes through ``_favorite_key``, so nrl can match
+  on team id (its abbreviations are ambiguous) without core knowing why.
+
+The config keys are read under both spellings, so a plugin adopting the mixin
+keeps working with the ``*_goals`` keys already in its published schema.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from typing import Any, Dict, List, Optional
+
+from PIL import Image, ImageDraw
+
+
+class CelebrationMixin:
+    """Full-screen takeover when a tracked team scores or wins."""
+
+    #: Collapse increments that land while a celebration is already on screen
+    #: into that one celebration. True for sports where a single scoring play
+    #: arrives as more than one score update (football: touchdown +6, then the
+    #: extra point +1). False where consecutive increments are distinct events —
+    #: suppressing there would swallow a real goal.
+    COALESCE_SCORING_SEQUENCE = False
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        mode_config = getattr(self, "mode_config", {}) or {}
+        self.celebration_enabled = mode_config.get("celebration_enabled", True)
+        self.celebration_duration = mode_config.get("celebration_duration", 8)
+        # Both spellings: the soccer lineage ships `celebrate_opponent_goals`,
+        # football ships `celebrate_opponent_scores`. Whichever the plugin's
+        # schema declares is the one its users have set.
+        self.celebrate_opponent_scores = mode_config.get(
+            "celebrate_opponent_scores",
+            mode_config.get("celebrate_opponent_goals", False),
+        )
+        # Per-game score baselines: {game_id: {"away": int, "home": int}}
+        self._score_baselines: Dict[str, Dict[str, int]] = {}
+        # The active celebration (a game *snapshot*, so a win survives the game
+        # leaving live_games) or None. See _start_celebration for the shape.
+        self.active_celebration: Optional[Dict[str, Any]] = None
+
+    # ------------------------------------------------------------------
+    # Override points
+    # ------------------------------------------------------------------
+
+    def score_phrase(self, points: int, team_abbr: str) -> str:
+        """The wording for a score celebration.
+
+        ``points`` is the score delta that triggered it, which sports with
+        variable-value scores use to name the play. The default is deliberately
+        sport-neutral; every celebrating plugin overrides it.
+        """
+        return f"{team_abbr} SCORES!"
+
+    def win_phrase(self, team_abbr: str) -> str:
+        """The wording for a win celebration."""
+        return f"{team_abbr} WINS!"
+
+    def _is_favorite(self, key: Optional[str]) -> bool:
+        """Whether ``key`` (whatever ``_favorite_key`` returns) is a favorite."""
+        return bool(self.favorite_teams) and key in self.favorite_teams
+
+    # ------------------------------------------------------------------
+    # Detection
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _score_to_int(score) -> Optional[int]:
+        """Coerce an ESPN score value (str / int / dict) to an int, or None."""
+        try:
+            if score is None:
+                return None
+            if isinstance(score, str):
+                s = score.strip()
+                if not s:
+                    return None
+                try:
+                    return int(float(s))
+                except ValueError:
+                    numbers = re.findall(r"\d+", s)
+                    return int(numbers[0]) if numbers else None
+            if isinstance(score, dict):
+                return int(float(score.get("value", score.get("displayValue", 0))))
+            return int(float(score))
+        except (ValueError, TypeError):
+            return None
+
+    def _should_celebrate_for(self, game: Dict, side: str) -> bool:
+        """Whether a score by ``side`` in ``game`` should trigger a celebration."""
+        if self._is_favorite(self._favorite_key(game, side)):
+            return True
+        if not self.favorite_teams:
+            # No favorites configured: the user opted to show this game, so
+            # celebrate any score in it.
+            return True
+        # Favorites exist but this team isn't one -> it's the opponent.
+        return self.celebrate_opponent_scores
+
+    def has_active_celebration(self) -> bool:
+        """True while a celebration is within its display window."""
+        celebration = self.active_celebration
+        return bool(celebration) and (
+            time.time() - celebration["started_at"] < self.celebration_duration
+        )
+
+    def _check_for_score(self, game: Dict) -> None:
+        """Compare a live game's score against its baseline and arm a
+        celebration when a celebratable team's score increases."""
+        if not self.celebration_enabled:
+            return
+        game_id = game.get("id")
+        if not game_id:
+            return
+        away = self._score_to_int(game.get("away_score"))
+        home = self._score_to_int(game.get("home_score"))
+        if away is None or home is None:
+            return
+
+        baseline = self._score_baselines.get(game_id)
+        # Always refresh the baseline: a first sighting must never celebrate (a
+        # game already in progress at boot would false-fire), and a decrement
+        # (VAR, a correction) just re-bases silently.
+        self._score_baselines[game_id] = {"away": away, "home": home}
+        if baseline is None:
+            return
+
+        away_delta = away - baseline["away"]
+        home_delta = home - baseline["home"]
+        if away_delta <= 0 and home_delta <= 0:
+            return
+
+        # One takeover per scoring sequence, where the sport has such a thing.
+        # The baseline is already advanced above, so nothing re-fires later.
+        if self.COALESCE_SCORING_SEQUENCE and self.has_active_celebration():
+            return
+
+        scored_side = None
+        points = 0
+        if away_delta > 0 and self._should_celebrate_for(game, "away"):
+            scored_side, points = "away", away_delta
+        if scored_side is None and home_delta > 0 and self._should_celebrate_for(
+            game, "home"
+        ):
+            scored_side, points = "home", home_delta
+        if scored_side is None:
+            return
+
+        self._start_celebration(
+            game,
+            "score",
+            scored_side=scored_side,
+            team_abbr=game.get(f"{scored_side}_abbr", ""),
+            away_score=away,
+            home_score=home,
+            points=points,
+        )
+
+    def _check_for_win(self, game: Dict) -> None:
+        """When a game we were tracking live goes final, arm a win celebration
+        if a favorite won. Fires at most once per game."""
+        if not self.celebration_enabled:
+            return
+        game_id = game.get("id")
+        if not game_id:
+            return
+        # Only celebrate wins for games we actually watched go live: one seen
+        # for the first time already-final (the board started after full time)
+        # has no baseline and must not fire.
+        if game_id not in self._score_baselines:
+            return
+        # Consume the baseline so this can only fire once.
+        self._score_baselines.pop(game_id, None)
+
+        away = self._score_to_int(game.get("away_score"))
+        home = self._score_to_int(game.get("home_score"))
+        if away is None or home is None:
+            return
+
+        if away > home:
+            winner_side = "away"
+        elif home > away:
+            winner_side = "home"
+        else:
+            return  # draw -> no win celebration
+
+        # Wins are gated strictly on favorites: every game ends, so the
+        # "no favorites -> celebrate all" score fallback would be far too noisy.
+        if not self._is_favorite(self._favorite_key(game, winner_side)):
+            return
+
+        self._start_celebration(
+            game,
+            "win",
+            scored_side=winner_side,
+            team_abbr=game.get(f"{winner_side}_abbr", ""),
+            away_score=away,
+            home_score=home,
+        )
+
+    def _start_celebration(
+        self,
+        game: Dict,
+        kind: str,
+        scored_side: str,
+        team_abbr: str,
+        away_score: int,
+        home_score: int,
+        points: int = 0,
+    ) -> None:
+        """Arm a celebration. ``scored_side`` ('away'/'home') is the side whose
+        score digit gets highlighted."""
+        phrase = (
+            self.win_phrase(team_abbr)
+            if kind == "win"
+            else self.score_phrase(points, team_abbr)
+        )
+
+        self.active_celebration = {
+            "kind": kind,
+            "game": dict(game),  # snapshot: survives the game leaving live_games
+            "scored_side": scored_side,
+            "team_abbr": team_abbr,
+            "away_score": away_score,
+            "home_score": home_score,
+            "started_at": time.time(),
+            "phrase": phrase,
+        }
+        # Pin focus to the involved game so the post-celebration scorebug
+        # resumes on it.
+        self.current_game = dict(game)
+        self.logger.info(
+            f"Celebration ({kind}) armed: {phrase} "
+            f"[{game.get('away_abbr')} {away_score}-{home_score} {game.get('home_abbr')}]"
+        )
+
+    # ------------------------------------------------------------------
+    # Rendering
+    # ------------------------------------------------------------------
+
+    def _fit_font(self, draw, text: str, max_width: int, fonts: List):
+        """The first font whose rendered ``text`` fits ``max_width``, falling
+        back to the last (smallest) font."""
+        for font in fonts:
+            if draw.textlength(text, font=font) <= max_width - 2:
+                return font
+        return fonts[-1]
+
+    def _draw_celebration_layout(
+        self, celebration: Dict, force_clear: bool = False
+    ) -> None:
+        """Render the full-screen score/win takeover."""
+        if force_clear:
+            self.display_manager.clear()
+
+        display_width = (
+            self.display_manager.matrix.width
+            if hasattr(self.display_manager, "matrix") and self.display_manager.matrix
+            else self.display_width
+        )
+        display_height = (
+            self.display_manager.matrix.height
+            if hasattr(self.display_manager, "matrix") and self.display_manager.matrix
+            else self.display_height
+        )
+
+        elapsed = time.time() - celebration["started_at"]
+        game = celebration["game"]
+
+        # Background: a brief color flash for the first ~1.2s, then black.
+        bg = (0, 0, 0, 255)
+        if elapsed < 1.2 and int(elapsed / 0.2) % 2 == 0:
+            bg = (12, 12, 48, 255)
+        main_img = Image.new("RGBA", (display_width, display_height), bg)
+        overlay = Image.new("RGBA", (display_width, display_height), (0, 0, 0, 0))
+        draw = ImageDraw.Draw(overlay)
+
+        # Logos at the edges (best-effort: a logo failure must not blank the
+        # celebration).
+        try:
+            center_y = display_height // 2
+            home_logo = self._load_and_resize_logo(
+                game.get("home_id"), game.get("home_abbr"),
+                game.get("home_logo_path"), game.get("home_logo_url"),
+            )
+            away_logo = self._load_and_resize_logo(
+                game.get("away_id"), game.get("away_abbr"),
+                game.get("away_logo_path"), game.get("away_logo_url"),
+            )
+            if home_logo:
+                main_img.paste(
+                    home_logo,
+                    (display_width - home_logo.width + 2, center_y - home_logo.height // 2),
+                    home_logo,
+                )
+            if away_logo:
+                main_img.paste(
+                    away_logo, (-2, center_y - away_logo.height // 2), away_logo
+                )
+        except Exception as e:
+            self.logger.debug(f"Celebration logo load failed: {e}")
+
+        # Phrase across the top, shrunk to fit the panel width.
+        phrase = celebration["phrase"]
+        phrase_font = self._fit_font(
+            draw, phrase, display_width, [self.fonts["time"], self.fonts["status"]]
+        )
+        phrase_width = draw.textlength(phrase, font=phrase_font)
+        self._draw_text_with_outline(
+            draw, phrase, ((display_width - phrase_width) // 2, 1), phrase_font
+        )
+
+        # Score centered low, with the scoring/winning side's digit pulsing in a
+        # highlight color so the change reads at a glance.
+        away_text = str(celebration["away_score"])
+        home_text = str(celebration["home_score"])
+        score_font = self.fonts["score"]
+        segments = [
+            (away_text, celebration["scored_side"] == "away"),
+            ("-", False),
+            (home_text, celebration["scored_side"] == "home"),
+        ]
+        total_width = sum(draw.textlength(seg, font=score_font) for seg, _ in segments)
+        highlight = (255, 255, 0) if int(elapsed * 4) % 2 == 0 else (255, 170, 0)
+        x = (display_width - total_width) // 2
+        y = display_height - 14
+        for seg, is_highlight in segments:
+            color = highlight if is_highlight else (255, 255, 255)
+            self._draw_text_with_outline(draw, seg, (int(x), y), score_font, fill=color)
+            x += draw.textlength(seg, font=score_font)
+
+        main_img = Image.alpha_composite(main_img, overlay).convert("RGB")
+        self.display_manager.image = main_img
+        self.display_manager.update_display()
+
+    def display(self, force_clear: bool = False) -> bool:
+        """Render an active celebration as a full-screen takeover; otherwise
+        defer to the normal live scorebug."""
+        if not self.is_enabled:
+            return False
+        celebration = self.active_celebration
+        if celebration:
+            if time.time() - celebration["started_at"] < self.celebration_duration:
+                try:
+                    self._draw_celebration_layout(celebration, force_clear)
+                    return True
+                except Exception as e:
+                    self.logger.error(f"Error drawing celebration: {e}", exc_info=True)
+            else:
+                self.active_celebration = None
+                # Reset the dwell so the scorebug resumes on the scoring/winning
+                # game for a full duration before rotation can move on.
+                self.last_game_switch = time.time()
+        return super().display(force_clear)

src/base_classes/sports/capabilities/rotation.py

@@ -0,0 +1,228 @@
+"""Live-rotation strategies — which live game to show next.
+
+The nine plugin copies grew three spellings of this, and the survey behind
+``docs/SPORTS_UNIFICATION.md`` found they are all the *same* Smooth Weighted
+Round-Robin algorithm in two shapes:
+
+* an **incremental picker** that holds weight state across calls and answers
+  "what next?" one game at a time (afl / nrl / soccer's ``_swrr_advance``), and
+* a **precomputed cycle** that returns a full list of game ids up front
+  (football / baseball / basketball's ``_build_weighted_schedule`` and hockey's
+  ``_build_rotation_schedule``, which differ only in loop shape).
+
+They agree *within* a cycle — SWRR is deterministic — and differ only at cycle
+boundaries, where the incremental form has no seam and the precomputed form
+restarts. That is a real behavioral difference, so core ships both rather than
+declaring a winner, and a plugin picks one by name:
+
+    self.rotation = get_rotation_strategy("swrr", weight_for=self._live_weight)
+
+Core never learns which sport is asking. A plugin with a genuinely novel
+ordering registers its own strategy instead of core growing a branch::
+
+    register_rotation_strategy("my-order", MyRotation)
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, List, Optional, Type
+
+
+def _game_id(game: Dict) -> Optional[str]:
+    """The rotation key for a game, or None if it has no usable id."""
+    return game.get("id")
+
+
+class RotationStrategy:
+    """Base class for live-rotation ordering.
+
+    Subclasses implement :meth:`schedule`; :meth:`next_game` has a working
+    default derived from it. Strategies whose natural shape is incremental
+    override :meth:`next_game` instead and derive :meth:`schedule`.
+
+    :param weight_for: callable mapping a game dict to a positive integer
+        weight — how many turns it gets per turn of a weight-1 game. Supplied by
+        the host so the *favorites* policy stays with the plugin and this module
+        stays free of any notion of what a favorite is. Defaults to equal
+        weights, which makes every strategy a plain round robin.
+    """
+
+    #: Name this strategy is registered under. Set by :func:`register_rotation_strategy`.
+    name: str = ""
+
+    def __init__(self, weight_for: Optional[Callable[[Dict], int]] = None):
+        self._weight_for = weight_for or (lambda game: 1)
+
+    def weights(self, games: List[Dict]) -> Dict[str, int]:
+        """``{game_id: weight}`` for games that have an id, in ``games`` order.
+
+        A weight below 1 is clamped up: a zero or negative weight would starve
+        a game out of the rotation entirely, which no caller means to express
+        and which would make ``total_weight`` collapse.
+        """
+        weights: Dict[str, int] = {}
+        for game in games:
+            gid = _game_id(game)
+            if gid is None:
+                continue
+            try:
+                weight = int(self._weight_for(game))
+            except (TypeError, ValueError):
+                weight = 1
+            weights[gid] = max(1, weight)
+        return weights
+
+    def schedule(self, games: List[Dict]) -> List[str]:
+        """Game ids in display order for one cycle. Ids may repeat."""
+        raise NotImplementedError
+
+    def next_game(self, games: List[Dict]) -> Optional[Dict]:
+        """The next game to display, or None when there is nothing to show."""
+        order = self.schedule(games)
+        if not order:
+            return None
+        by_id = {gid: g for g in games if (gid := _game_id(g)) is not None}
+        return by_id.get(order[0])
+
+    def reset(self) -> None:
+        """Drop any accumulated state. Stateless strategies need do nothing."""
+
+
+class SimpleRotation(RotationStrategy):
+    """Plain round robin: every live game once per cycle, weights ignored.
+
+    The fallback for a plugin that wants strictly even rotation regardless of
+    favorites.
+    """
+
+    def schedule(self, games: List[Dict]) -> List[str]:
+        return [gid for g in games if (gid := _game_id(g)) is not None]
+
+
+class WeightedCycleRotation(RotationStrategy):
+    """Precomputed SWRR cycle — the football / baseball / basketball / hockey shape.
+
+    Returns a full cycle of ``sum(weights)`` ids with repeats spaced evenly
+    rather than clumped, highest weight scheduled first. When no game carries a
+    boost the cycle degenerates to a single pass in ``games`` order, which is
+    exactly the plain round robin it replaced.
+    """
+
+    def schedule(self, games: List[Dict]) -> List[str]:
+        weights = self.weights(games)
+        if not weights:
+            return []
+        total_weight = sum(weights.values())
+        if total_weight <= len(weights):
+            # No boost in effect — plain order, one pass. (Also the guard that
+            # keeps the loop below from being O(total_weight) for nothing.)
+            return list(weights)
+
+        current = {gid: 0 for gid in weights}
+        order: List[str] = []
+        for _ in range(total_weight):
+            for gid, weight in weights.items():
+                current[gid] += weight
+            picked = max(current, key=lambda gid: current[gid])
+            current[picked] -= total_weight
+            order.append(picked)
+        return order
+
+
+class SmoothWeightedRotation(RotationStrategy):
+    """Incremental SWRR — the afl / nrl / soccer shape.
+
+    Weight state persists across calls, so there is no fixed-length cycle and
+    therefore no clustering seam at a cycle boundary. A game seen for the first
+    time starts at weight 0 and receives its full weight on the next call, so a
+    favorite's game that has just gone live naturally wins the first pick after
+    it appears — "queued first on refresh" without a special-cased branch.
+
+    State for games no longer live is dropped on each call, so a long-running
+    board does not accumulate entries for finished games.
+    """
+
+    def __init__(self, weight_for: Optional[Callable[[Dict], int]] = None):
+        super().__init__(weight_for)
+        self._current: Dict[str, int] = {}
+
+    def reset(self) -> None:
+        self._current = {}
+
+    def next_game(self, games: List[Dict]) -> Optional[Dict]:
+        if not games:
+            return None
+        weights = self.weights(games)
+        if not weights:
+            return None
+
+        # Keep state only for games still live.
+        self._current = {
+            gid: value for gid, value in self._current.items() if gid in weights
+        }
+        for gid, weight in weights.items():
+            self._current[gid] = self._current.get(gid, 0) + weight
+
+        total_weight = sum(weights.values())
+        # Iterate in `games` order so ties break toward the feed's ordering,
+        # which is what the plugin copies did and what makes the no-boost case
+        # identical to a plain round robin.
+        ids_in_order = [gid for g in games if (gid := _game_id(g)) in weights]
+        best = max(ids_in_order, key=lambda gid: self._current[gid])
+        self._current[best] -= total_weight
+        return next(g for g in games if _game_id(g) == best)
+
+    def schedule(self, games: List[Dict]) -> List[str]:
+        """One cycle's worth of picks, without disturbing live state.
+
+        Derived by running the picker forward on a copy, so the returned order
+        is exactly what repeated :meth:`next_game` calls would produce from the
+        current state — callers can use it to preview or log the rotation
+        without perturbing it.
+        """
+        weights = self.weights(games)
+        if not weights:
+            return []
+        preview = SmoothWeightedRotation(self._weight_for)
+        preview._current = dict(self._current)
+        order: List[str] = []
+        for _ in range(sum(weights.values())):
+            picked = preview.next_game(games)
+            if picked is None:
+                break
+            order.append(_game_id(picked))
+        return order
+
+
+_REGISTRY: Dict[str, Type[RotationStrategy]] = {}
+
+
+def register_rotation_strategy(name: str, factory: Type[RotationStrategy]) -> None:
+    """Register a rotation strategy under ``name``.
+
+    A plugin needing an ordering core does not ship registers it here rather
+    than core growing a sport-specific branch. Re-registering a name replaces
+    it, so a plugin may also override a built-in for itself.
+    """
+    if not name:
+        raise ValueError("rotation strategy name must be a non-empty string")
+    factory.name = name
+    _REGISTRY[name] = factory
+
+
+def get_rotation_strategy(
+    name: str, weight_for: Optional[Callable[[Dict], int]] = None
+) -> RotationStrategy:
+    """Build the strategy registered under ``name``.
+
+    Falls back to ``"simple"`` for an unknown name rather than raising: the name
+    arrives from user config, and a typo should cost the boost, not the
+    scoreboard.
+    """
+    factory = _REGISTRY.get(name) or _REGISTRY["simple"]
+    return factory(weight_for=weight_for)
+
+
+register_rotation_strategy("simple", SimpleRotation)
+register_rotation_strategy("weighted", WeightedCycleRotation)
+register_rotation_strategy("swrr", SmoothWeightedRotation)

src/element_style.py

@@ -0,0 +1,621 @@
+"""
+Shared per-element style resolution for plugins (the x-style-elements system).
+
+Plugins expose user-customizable text styling — font, size, color, and x/y
+pixel offsets per named element — through their ``config_schema.json``. Two
+declaration forms exist in the plugin ecosystem:
+
+- The compact ``x-style-elements`` map on the ``customization`` object
+  (of-the-day is the reference). ``expand_style_elements()`` turns it into
+  the full per-element property blocks the web-UI config form renders.
+- The manual ``customization`` block: hand-written per-element objects with
+  ``font`` / ``font_size`` / ``text_color`` defaults (the scoreboards,
+  ledmatrix-music). No expansion needed — the defaults are read as-is.
+
+At render time a plugin builds an ``ElementStyleResolver`` from its config
+and the schema-file defaults, then asks for each element's resolved style::
+
+    from src.element_style import ElementStyleResolver, defaults_from_schema_file
+
+    resolver = ElementStyleResolver(config, defaults_from_schema_file(schema_path))
+    title = resolver.style('title_text', classic_font='PressStart2P-Regular.ttf',
+                           classic_size=8, classic_color=(255, 255, 255))
+    # title.font (PIL font / freetype.Face), title.color (RGB tuple),
+    # title.offset ((dx, dy)), title.user_forced, title.user_forced_color
+
+The central subtlety is what "the user set it" means. The web UI's save flow
+(``schema_manager.merge_with_defaults``) writes the FULL schema-default
+object into ``config.json`` on every save, whether or not the user touched
+the styling section — so a value merely being *present* in config is not an
+override. A value only counts as user-forced when it genuinely differs from
+the schema default for that element. When nothing is forced, ``style()``
+returns exactly the ``classic_*`` values the caller passes (the plugin's
+pre-customization styling), so an untouched config renders byte-identically
+to the classic code path. Note the classic values and the schema defaults
+may legitimately differ (e.g. football's status_text: schema declares 4x6,
+the classic loader fell back to PressStart) — the schema default is the
+override *reference*, the classic values are the *fallback*.
+
+``style()`` never raises: any malformed config value degrades to the classic
+style with a logged warning. Font faces are cached module-wide by
+(resolved path, size), and font files resolve independently of the caller's
+cwd (cwd ``assets/fonts/`` first for compatibility, then the core install
+root derived from this module's own location).
+"""
+
+import copy
+import json
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple, Union
+
+from PIL import ImageFont
+
+try:
+    import freetype
+except ImportError:  # pragma: no cover - freetype ships with the core
+    freetype = None
+
+logger = logging.getLogger(__name__)
+
+# Core install root (the directory that contains src/ and assets/fonts/),
+# derived from this file so fonts resolve regardless of the caller's cwd.
+_CORE_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+_FONTS_SUBDIR = os.path.join('assets', 'fonts')
+
+# Last-resort font when a requested file can't be found or loaded.
+_FALLBACK_FONT_NAME = 'PressStart2P-Regular.ttf'
+
+# (resolved absolute path, size) -> loaded font face. BDF faces are stateful
+# in principle, but the core's own FontManager shares faces the same way.
+_font_cache: Dict[Tuple[str, int], Any] = {}
+
+# Config keys a style element block carries, in schema/UI order.
+_STYLE_KEYS = ('font', 'font_size', 'text_color')
+
+
+@dataclass(frozen=True)
+class ElementStyle:
+    """A fully resolved style for one named element."""
+
+    font: Any                       # PIL ImageFont or freetype.Face
+    color: Tuple[int, int, int]     # resolved RGB
+    offset: Tuple[int, int]         # user layout (x, y) offset, default (0, 0)
+    font_name: str                  # resolved font filename
+    font_size: int                  # resolved pixel size
+    user_forced: bool               # font or size genuinely overridden
+    user_forced_color: bool         # color genuinely overridden
+
+
+# ---------------------------------------------------------------------------
+# Font loading (cwd-independent, cached)
+# ---------------------------------------------------------------------------
+
+def resolve_font_path(font_name: str) -> Optional[str]:
+    """Locate a font file by name, independent of the caller's cwd.
+
+    Tries, in order: an absolute path as given; ``assets/fonts/<name>``
+    relative to the cwd (the classic loaders' behavior, kept first so a
+    process running from a different checkout keeps its own fonts); then
+    ``assets/fonts/<name>`` under the core install root. Returns an
+    absolute path, or None when the file doesn't exist anywhere.
+    """
+    if not font_name or not isinstance(font_name, str):
+        return None
+    if os.path.isabs(font_name):
+        return font_name if os.path.isfile(font_name) else None
+    candidates = (
+        os.path.join(os.getcwd(), _FONTS_SUBDIR, font_name),
+        os.path.join(_CORE_ROOT, _FONTS_SUBDIR, font_name),
+    )
+    for candidate in candidates:
+        if os.path.isfile(candidate):
+            return os.path.abspath(candidate)
+    return None
+
+
+def load_font(font_name: str, size: int) -> Any:
+    """Load a font by filename at a pixel size, with caching and fallback.
+
+    ``.bdf`` files load as ``freetype.Face`` (matching FontManager), other
+    files through ``PIL.ImageFont.truetype``. A missing or unloadable font
+    degrades to ``PressStart2P-Regular.ttf`` at the requested size, then to
+    PIL's built-in default — this function never raises.
+    """
+    try:
+        size = max(1, int(size))
+    except (TypeError, ValueError):
+        size = 8
+
+    path = resolve_font_path(font_name)
+    if path is None:
+        logger.warning("Font file not found: %s, using fallback", font_name)
+        return _load_fallback_font(size)
+
+    cache_key = (path, size)
+    cached = _font_cache.get(cache_key)
+    if cached is not None:
+        return cached
+
+    try:
+        if path.lower().endswith('.bdf'):
+            if freetype is None:
+                raise RuntimeError("freetype not available for BDF fonts")
+            face = freetype.Face(path)
+            # Character size in 1/64th points at 72dpi == pixel size.
+            face.set_char_size(size * 64, size * 64, 72, 72)
+            font: Any = face
+        else:
+            font = ImageFont.truetype(path, size)
+    except Exception as e:
+        logger.warning("Error loading font %s at %spx: %s, using fallback",
+                       path, size, e)
+        return _load_fallback_font(size)
+
+    _font_cache[cache_key] = font
+    return font
+
+
+def _load_fallback_font(size: int) -> Any:
+    """PressStart2P at the requested size, else PIL's built-in default."""
+    path = resolve_font_path(_FALLBACK_FONT_NAME)
+    if path is not None:
+        cache_key = (path, size)
+        cached = _font_cache.get(cache_key)
+        if cached is not None:
+            return cached
+        try:
+            font = ImageFont.truetype(path, size)
+            _font_cache[cache_key] = font
+            return font
+        except Exception as e:
+            logger.error("Error loading fallback font: %s", e)
+    return ImageFont.load_default()
+
+
+# ---------------------------------------------------------------------------
+# Schema parsing
+# ---------------------------------------------------------------------------
+
+def expand_style_elements(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Expand a ``customization.x-style-elements`` declaration into the full
+    per-element property blocks the web-UI config form renders.
+
+    Each declared element becomes an object with ``font`` / ``font_size`` /
+    ``text_color`` properties (only the sub-fields the declaration carries),
+    tagged ``x-style-managed: true``; elements declaring ``offsets: true``
+    additionally get an entry under ``customization.layout`` with
+    ``x_offset`` / ``y_offset`` integers defaulting to 0. Hand-written
+    element blocks with the same key are left untouched.
+
+    Returns the schema unchanged (same object) when there is nothing to
+    expand; otherwise returns an expanded deep copy. Never raises.
+    """
+    try:
+        customization = schema.get('properties', {}).get('customization')
+        if not isinstance(customization, dict):
+            return schema
+        declaration = customization.get('x-style-elements')
+        if not isinstance(declaration, dict) or not declaration:
+            return schema
+
+        expanded = copy.deepcopy(schema)
+        customization = expanded['properties']['customization']
+        customization.setdefault('type', 'object')
+        props = customization.setdefault('properties', {})
+        layout_props: Dict[str, Any] = {}
+
+        for element_key, spec in declaration.items():
+            if not isinstance(spec, dict):
+                continue
+            if element_key not in props:
+                props[element_key] = _element_block_from_spec(element_key, spec)
+            if spec.get('offsets'):
+                layout_props[element_key] = _offset_block_from_spec(
+                    element_key, spec)
+
+        if layout_props:
+            layout = props.setdefault('layout', {
+                'type': 'object',
+                'title': 'Layout Offsets',
+                'description': 'Pixel offsets applied to each element '
+                               '(positive x moves right, positive y moves down)',
+                'x-advanced': True,
+                'properties': {},
+                'additionalProperties': False,
+            })
+            layout.setdefault('properties', {})
+            for element_key, block in layout_props.items():
+                layout['properties'].setdefault(element_key, block)
+
+        return expanded
+    except Exception as e:
+        logger.warning("Error expanding x-style-elements: %s", e)
+        return schema
+
+
+def _element_block_from_spec(element_key: str,
+                             spec: Dict[str, Any]) -> Dict[str, Any]:
+    """Build one expanded per-element schema block from its declaration."""
+    properties: Dict[str, Any] = {}
+    order = []
+
+    font_spec = spec.get('font')
+    if isinstance(font_spec, dict):
+        font_prop: Dict[str, Any] = {
+            'type': 'string',
+            'title': 'Font Family',
+            'x-advanced': True,
+        }
+        if 'default' in font_spec:
+            font_prop['default'] = font_spec['default']
+        if isinstance(font_spec.get('enum'), list):
+            font_prop['enum'] = list(font_spec['enum'])
+        properties['font'] = font_prop
+        order.append('font')
+
+    size_spec = spec.get('size')
+    if isinstance(size_spec, dict):
+        size_prop: Dict[str, Any] = {
+            'type': 'integer',
+            'title': 'Font Size',
+            'description': 'Font size in pixels',
+            'x-advanced': True,
+        }
+        if 'default' in size_spec:
+            size_prop['default'] = size_spec['default']
+        if 'min' in size_spec:
+            size_prop['minimum'] = size_spec['min']
+        if 'max' in size_spec:
+            size_prop['maximum'] = size_spec['max']
+        properties['font_size'] = size_prop
+        order.append('font_size')
+
+    color_spec = spec.get('color')
+    if isinstance(color_spec, dict):
+        color_prop: Dict[str, Any] = {
+            'type': 'array',
+            'title': 'Text Color',
+            'items': {'type': 'integer', 'minimum': 0, 'maximum': 255},
+            'minItems': 3,
+            'maxItems': 3,
+            'x-widget': 'color-picker',
+        }
+        if 'default' in color_spec:
+            color_prop['default'] = list(color_spec['default'])
+        properties['text_color'] = color_prop
+        order.append('text_color')
+
+    return {
+        'type': 'object',
+        'title': spec.get('title', element_key),
+        'x-style-managed': True,
+        'x-propertyOrder': order,
+        'additionalProperties': False,
+        'properties': properties,
+    }
+
+
+def _offset_block_from_spec(element_key: str,
+                            spec: Dict[str, Any]) -> Dict[str, Any]:
+    """Build one layout.<element> offset block (x/y, default 0)."""
+    axis = {
+        'type': 'integer',
+        'default': 0,
+        'x-advanced': True,
+    }
+    return {
+        'type': 'object',
+        'title': spec.get('title', element_key),
+        'x-style-managed': True,
+        'additionalProperties': False,
+        'properties': {
+            'x_offset': dict(axis, title='X Offset'),
+            'y_offset': dict(axis, title='Y Offset'),
+        },
+    }
+
+
+def defaults_from_schema(schema: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract per-element style defaults from a config schema dict.
+
+    Understands both declaration forms: the compact ``x-style-elements``
+    map, and hand-written per-element blocks under
+    ``customization.properties`` (their ``font`` / ``font_size`` /
+    ``text_color`` property defaults). Returns a config-shaped dict::
+
+        {"customization": {"<element>": {"font": ..., "font_size": ...,
+                                         "text_color": [...]}, ...}}
+
+    Elements with no declared defaults are omitted. Never raises.
+    """
+    elements: Dict[str, Dict[str, Any]] = {}
+    try:
+        customization = schema.get('properties', {}).get('customization')
+        if not isinstance(customization, dict):
+            return {'customization': elements}
+
+        declaration = customization.get('x-style-elements')
+        if isinstance(declaration, dict):
+            for element_key, spec in declaration.items():
+                if not isinstance(spec, dict):
+                    continue
+                defaults: Dict[str, Any] = {}
+                font_spec = spec.get('font')
+                if isinstance(font_spec, dict) and 'default' in font_spec:
+                    defaults['font'] = font_spec['default']
+                size_spec = spec.get('size')
+                if isinstance(size_spec, dict) and 'default' in size_spec:
+                    defaults['font_size'] = size_spec['default']
+                color_spec = spec.get('color')
+                if isinstance(color_spec, dict) and 'default' in color_spec:
+                    defaults['text_color'] = list(color_spec['default'])
+                if defaults:
+                    elements[element_key] = defaults
+
+        properties = customization.get('properties')
+        if isinstance(properties, dict):
+            for element_key, block in properties.items():
+                if element_key == 'layout' or element_key in elements:
+                    continue
+                if not isinstance(block, dict):
+                    continue
+                block_props = block.get('properties')
+                if not isinstance(block_props, dict):
+                    continue
+                defaults = {}
+                for style_key in _STYLE_KEYS:
+                    prop = block_props.get(style_key)
+                    if isinstance(prop, dict) and 'default' in prop:
+                        defaults[style_key] = prop['default']
+                if defaults:
+                    elements[element_key] = defaults
+    except Exception as e:
+        logger.warning("Error extracting style defaults from schema: %s", e)
+    return {'customization': elements}
+
+
+def defaults_from_schema_file(schema_path: Union[str, os.PathLike]) -> Dict[str, Any]:
+    """``defaults_from_schema`` for a schema file on disk. A missing or
+    malformed file yields empty defaults (with a logged warning) — every
+    configured value then counts as a user override, which is the safe
+    degradation. Never raises."""
+    try:
+        with open(schema_path, 'r', encoding='utf-8') as f:
+            schema = json.load(f)
+        if not isinstance(schema, dict):
+            raise ValueError("schema is not a JSON object")
+    except Exception as e:
+        logger.warning("Could not read style defaults from %s: %s",
+                       schema_path, e)
+        return {'customization': {}}
+    return defaults_from_schema(schema)
+
+
+# ---------------------------------------------------------------------------
+# Resolver
+# ---------------------------------------------------------------------------
+
+def _normalize_color(value: Any) -> Optional[Tuple[int, int, int]]:
+    """An (r, g, b) tuple of ints in 0..255, or None for anything else."""
+    if isinstance(value, (list, tuple)) and len(value) == 3:
+        try:
+            rgb = tuple(int(c) for c in value)
+        except (TypeError, ValueError):
+            return None
+        if all(0 <= c <= 255 for c in rgb):
+            return rgb  # type: ignore[return-value]
+    return None
+
+
+class ElementStyleResolver:
+    """Resolves per-element user styling against schema defaults.
+
+    Built from a plugin's live config dict and the defaults extracted from
+    its own ``config_schema.json`` (``defaults_from_schema_file``). The
+    config dict is held by reference as ``_config`` — consumers compare
+    identity (``resolver._config is not self.config``) to decide when a
+    resolver must be rebuilt after ``on_config_change`` swaps the dict.
+
+    A configured font/size/color counts as user-forced only when it differs
+    from the schema default (see module docstring); otherwise ``style()``
+    returns the caller's classic values verbatim, keeping untouched configs
+    byte-identical to pre-customization rendering.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]],
+                 defaults: Optional[Dict[str, Any]] = None):
+        # Keep the exact object for identity-based invalidation, even if the
+        # caller hands us something odd; reads are guarded.
+        self._config = config
+        if isinstance(defaults, dict):
+            element_defaults = defaults.get('customization', {})
+        else:
+            element_defaults = {}
+        self._defaults: Dict[str, Any] = (
+            element_defaults if isinstance(element_defaults, dict) else {})
+        self._memo: Dict[Any, ElementStyle] = {}
+
+    # -- internal accessors -------------------------------------------------
+
+    def _customization(self) -> Dict[str, Any]:
+        config = self._config if isinstance(self._config, dict) else {}
+        customization = config.get('customization', {})
+        return customization if isinstance(customization, dict) else {}
+
+    def _element_config(self, element_key: str) -> Dict[str, Any]:
+        element = self._customization().get(element_key, {})
+        return element if isinstance(element, dict) else {}
+
+    def _element_defaults(self, element_key: str) -> Dict[str, Any]:
+        defaults = self._defaults.get(element_key, {})
+        return defaults if isinstance(defaults, dict) else {}
+
+    # -- public API ---------------------------------------------------------
+
+    def style(self, element_key: str,
+              classic_font: str = _FALLBACK_FONT_NAME,
+              classic_size: int = 8,
+              classic_color: Optional[Tuple[int, int, int]] = None) -> ElementStyle:
+        """Resolve one element's style. Never raises.
+
+        Args:
+            element_key: Key under ``config['customization']`` (e.g.
+                ``'title_text'``).
+            classic_font: Font filename the plugin's classic (pre-
+                customization) code used for this element.
+            classic_size: Classic pixel size.
+            classic_color: Classic RGB color, or None when the caller only
+                cares about the font (``.color`` then falls back to the
+                schema default color, else white).
+
+        Returns:
+            ElementStyle with the loaded font face, RGB color, (x, y)
+            offset, and the ``user_forced`` / ``user_forced_color`` flags.
+        """
+        try:
+            memo_key = (element_key, classic_font, classic_size,
+                        _normalize_color(classic_color) or classic_color)
+            memoized = self._memo.get(memo_key)
+            if memoized is not None:
+                return memoized
+        except Exception:
+            memo_key = None
+
+        try:
+            resolved = self._resolve(element_key, classic_font,
+                                     classic_size, classic_color)
+        except Exception as e:
+            logger.warning("Error resolving style for element '%s': %s — "
+                           "using classic style", element_key, e)
+            resolved = self._classic_style(classic_font, classic_size,
+                                           classic_color)
+        if memo_key is not None:
+            self._memo[memo_key] = resolved
+        return resolved
+
+    def offset(self, element_key: str) -> Tuple[int, int]:
+        """The user's ``customization.layout.<element>`` (x, y) pixel
+        offset, defaulting to (0, 0). Never raises."""
+        return (self.offset_value(element_key, 'x_offset', 0),
+                self.offset_value(element_key, 'y_offset', 0))
+
+    def offset_value(self, element_key: str, axis: str, default: int = 0) -> int:
+        """One ``customization.layout.<element>.<axis>`` value as an int.
+
+        ``axis`` is usually ``'x_offset'`` / ``'y_offset'`` but any key is
+        honored (e.g. the scoreboards' ``'away_x_offset'``). Numeric
+        strings are coerced; anything else degrades to ``default``. Never
+        raises.
+        """
+        try:
+            layout = self._customization().get('layout', {})
+            if not isinstance(layout, dict):
+                return int(default)
+            element = layout.get(element_key, {})
+            if not isinstance(element, dict):
+                return int(default)
+            value = element.get(axis, default)
+            if isinstance(value, bool):
+                return int(default)
+            if isinstance(value, (int, float)):
+                return int(value)
+            if isinstance(value, str):
+                try:
+                    return int(float(value))
+                except (TypeError, ValueError):
+                    logger.warning(
+                        "Invalid layout offset for %s.%s: %r, using %s",
+                        element_key, axis, value, default)
+                    return int(default)
+            return int(default)
+        except Exception as e:
+            logger.warning("Error reading layout offset %s.%s: %s",
+                           element_key, axis, e)
+            try:
+                return int(default)
+            except (TypeError, ValueError):
+                return 0
+
+    # -- resolution internals -----------------------------------------------
+
+    def _resolve(self, element_key: str, classic_font: str,
+                 classic_size: int,
+                 classic_color: Optional[Tuple[int, int, int]]) -> ElementStyle:
+        element_config = self._element_config(element_key)
+        element_defaults = self._element_defaults(element_key)
+
+        # Font family: forced only when it differs from the schema default
+        # (falling back to the classic font as the reference when the
+        # schema declares none).
+        default_font = element_defaults.get('font', classic_font)
+        configured_font = element_config.get('font')
+        font_forced = (isinstance(configured_font, str) and configured_font
+                       and configured_font != default_font)
+
+        # Font size: same rule, with defensive int coercion.
+        default_size = self._coerce_size(
+            element_defaults.get('font_size'), None)
+        if default_size is None:
+            default_size = self._coerce_size(classic_size, 8)
+        configured_size = self._coerce_size(element_config.get('font_size'),
+                                            None)
+        size_forced = (configured_size is not None
+                       and configured_size != default_size)
+
+        font_name = configured_font if font_forced else classic_font
+        font_size = configured_size if size_forced else self._coerce_size(
+            classic_size, 8)
+        user_forced = bool(font_forced or size_forced)
+
+        # Color: forced only when it differs from the schema default (or,
+        # absent one, from the classic color).
+        default_color = _normalize_color(element_defaults.get('text_color'))
+        configured_color = _normalize_color(element_config.get('text_color'))
+        reference_color = (default_color if default_color is not None
+                           else _normalize_color(classic_color))
+        color_forced = (configured_color is not None
+                        and configured_color != reference_color)
+        if color_forced:
+            color = configured_color
+        else:
+            color = (_normalize_color(classic_color) or default_color
+                     or (255, 255, 255))
+
+        return ElementStyle(
+            font=load_font(font_name, font_size),
+            color=color,
+            offset=self.offset(element_key),
+            font_name=font_name,
+            font_size=font_size,
+            user_forced=user_forced,
+            user_forced_color=bool(color_forced),
+        )
+
+    def _classic_style(self, classic_font: str, classic_size: int,
+                       classic_color: Optional[Tuple[int, int, int]]) -> ElementStyle:
+        """The untouched fallback style — used when resolution itself
+        fails, so ``style()`` can keep its never-raises promise."""
+        size = self._coerce_size(classic_size, 8)
+        return ElementStyle(
+            font=load_font(classic_font, size),
+            color=_normalize_color(classic_color) or (255, 255, 255),
+            offset=(0, 0),
+            font_name=classic_font,
+            font_size=size,
+            user_forced=False,
+            user_forced_color=False,
+        )
+
+    @staticmethod
+    def _coerce_size(value: Any, default: Optional[int]) -> Optional[int]:
+        """An int pixel size, or ``default`` for None/garbage."""
+        if value is None or isinstance(value, bool):
+            return default
+        try:
+            size = int(value)
+        except (TypeError, ValueError):
+            return default
+        return size if size > 0 else default

src/font_manager.py

@@ -659,6 +659,25 @@ class FontManager:
 
     # ==================== Font Discovery ====================
 
+    @staticmethod
+    def _resolve_asset_path(relative_path: str) -> str:
+        """Resolve a repo-relative asset path independently of the process cwd.
+
+        Prefers the working directory (preserving behavior when the process
+        runs from the install root), then falls back to the install root
+        derived from this module's own location. Without the fallback, any
+        process started outside the install root (e.g. the plugin safety
+        harness on CI) silently loses every font and degrades to PIL's
+        default face.
+        """
+        if os.path.exists(relative_path):
+            return relative_path
+        install_root = Path(__file__).resolve().parent.parent
+        candidate = install_root / relative_path
+        if candidate.exists():
+            return str(candidate)
+        return relative_path
+
     def _initialize_fonts(self):
         """Initialize font catalog and validate configuration."""
         self._scan_fonts_directory()
@@ -667,7 +686,7 @@ class FontManager:
 
     def _scan_fonts_directory(self):
         """Scan assets/fonts directory for available fonts."""
-        fonts_dir = "assets/fonts"
+        fonts_dir = self._resolve_asset_path("assets/fonts")
         if not os.path.exists(fonts_dir):
             logger.warning(f"Fonts directory not found: {fonts_dir}")
             return
@@ -683,6 +702,7 @@ class FontManager:
     def _register_common_fonts(self):
         """Register common font aliases from common_fonts dictionary."""
         for family_name, font_path in self.common_fonts.items():
+            font_path = self._resolve_asset_path(font_path)
             # Check if font file exists
             if os.path.exists(font_path):
                 # Register the common font name (overrides auto-generated name if exists)

src/plugin_system/schema_manager.py

@@ -115,7 +115,17 @@ class SchemaManager:
             if not isinstance(schema, dict):
                 self.logger.error(f"Invalid schema format for {plugin_id}: not a dictionary")
                 return None
-            
+
+            # Expand any customization.x-style-elements declaration into the
+            # full per-element style blocks (font/size/color + layout
+            # offsets) the web-UI config form renders. No-op for schemas
+            # without the declaration; never raises.
+            try:
+                from src.element_style import expand_style_elements
+                schema = expand_style_elements(schema)
+            except ImportError:
+                pass
+
             # Cache the schema
             self._schema_cache[plugin_id] = schema
             

test/test_element_style.py

@@ -0,0 +1,396 @@
+"""
+Tests for src.element_style — the shared per-element style resolver behind
+the x-style-elements system.
+
+The contract under test (defined by the plugin consumers: of-the-day,
+ledmatrix-music, football-scoreboard):
+
+- defaults_from_schema_file parses BOTH declaration forms — the compact
+  x-style-elements map and hand-written customization blocks.
+- expand_style_elements turns an x-style-elements declaration into the full
+  per-element blocks (plus layout offsets) the web-UI form renders.
+- A config value counts as user-forced only when it genuinely differs from
+  the schema default; untouched (or schema-default-populated) configs
+  resolve to EXACTLY the classic font/size/color, keeping rendering
+  byte-identical.
+- style() never raises; malformed input degrades to the classic style.
+"""
+
+import json
+import os
+
+import pytest
+from PIL import ImageFont
+
+from src.element_style import (
+    ElementStyleResolver,
+    defaults_from_schema,
+    defaults_from_schema_file,
+    expand_style_elements,
+    load_font,
+    resolve_font_path,
+)
+
+# ---------------------------------------------------------------------------
+# Schema fixtures
+# ---------------------------------------------------------------------------
+
+# Compact declaration form (of-the-day's shape).
+STYLE_ELEMENTS_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "enabled": {"type": "boolean", "default": False},
+        "customization": {
+            "type": "object",
+            "x-style-elements": {
+                "title_text": {
+                    "title": "Title",
+                    "font": {"default": "PressStart2P-Regular.ttf"},
+                    "size": {"default": 8, "min": 4, "max": 16},
+                    "color": {"default": [255, 255, 255]},
+                    "offsets": True,
+                },
+                "body_text": {
+                    "title": "Body Text",
+                    "font": {"default": "4x6-font.ttf"},
+                    "size": {"default": 6, "min": 4, "max": 12},
+                    "color": {"default": [200, 200, 200]},
+                    "offsets": True,
+                },
+            },
+        },
+    },
+}
+
+# Manual declaration form (the scoreboards' / music's shape).
+MANUAL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "customization": {
+            "type": "object",
+            "properties": {
+                "status_text": {
+                    "type": "object",
+                    "properties": {
+                        "font": {"type": "string",
+                                 "default": "4x6-font.ttf"},
+                        "font_size": {"type": "integer", "default": 6},
+                    },
+                },
+                "score_text": {
+                    "type": "object",
+                    "properties": {
+                        "font": {"type": "string",
+                                 "default": "PressStart2P-Regular.ttf"},
+                        "font_size": {"type": "integer", "default": 10},
+                        "text_color": {"type": "array",
+                                       "default": [255, 255, 0]},
+                    },
+                },
+                "layout": {"type": "object", "properties": {}},
+            },
+        },
+    },
+}
+
+
+@pytest.fixture
+def style_schema_path(tmp_path):
+    path = tmp_path / "config_schema.json"
+    path.write_text(json.dumps(STYLE_ELEMENTS_SCHEMA))
+    return str(path)
+
+
+@pytest.fixture
+def manual_schema_path(tmp_path):
+    path = tmp_path / "config_schema.json"
+    path.write_text(json.dumps(MANUAL_SCHEMA))
+    return str(path)
+
+
+def _resolver(config, schema_path):
+    return ElementStyleResolver(config, defaults_from_schema_file(schema_path))
+
+
+# ---------------------------------------------------------------------------
+# Schema parsing
+# ---------------------------------------------------------------------------
+
+class TestDefaultsFromSchema:
+    def test_x_style_elements_defaults(self, style_schema_path):
+        defaults = defaults_from_schema_file(style_schema_path)
+        cust = defaults["customization"]
+        assert cust["title_text"] == {"font": "PressStart2P-Regular.ttf",
+                                      "font_size": 8,
+                                      "text_color": [255, 255, 255]}
+        assert cust["body_text"]["font_size"] == 6
+        assert cust["body_text"]["text_color"] == [200, 200, 200]
+
+    def test_manual_block_defaults(self, manual_schema_path):
+        defaults = defaults_from_schema_file(manual_schema_path)
+        cust = defaults["customization"]
+        assert cust["status_text"] == {"font": "4x6-font.ttf", "font_size": 6}
+        assert cust["score_text"]["text_color"] == [255, 255, 0]
+        assert "layout" not in cust
+
+    def test_missing_file_degrades_to_empty(self, tmp_path):
+        defaults = defaults_from_schema_file(str(tmp_path / "nope.json"))
+        assert defaults == {"customization": {}}
+
+    def test_malformed_file_degrades_to_empty(self, tmp_path):
+        path = tmp_path / "bad.json"
+        path.write_text("{not json")
+        assert defaults_from_schema_file(str(path)) == {"customization": {}}
+
+    def test_schema_without_customization(self):
+        assert defaults_from_schema({"properties": {}}) == {"customization": {}}
+
+
+class TestExpandStyleElements:
+    def test_expansion_generates_blocks(self):
+        expanded = expand_style_elements(STYLE_ELEMENTS_SCHEMA)
+        cust = expanded["properties"]["customization"]["properties"]
+        title = cust["title_text"]
+        assert title["x-style-managed"] is True
+        assert title["properties"]["font"]["default"] == \
+            "PressStart2P-Regular.ttf"
+        assert title["properties"]["font_size"]["default"] == 8
+        assert title["properties"]["font_size"]["minimum"] == 4
+        assert title["properties"]["font_size"]["maximum"] == 16
+        assert cust["body_text"]["properties"]["text_color"]["default"] == \
+            [200, 200, 200]
+
+    def test_expansion_generates_layout_offsets(self):
+        expanded = expand_style_elements(STYLE_ELEMENTS_SCHEMA)
+        layout = expanded["properties"]["customization"]["properties"]["layout"]
+        assert "title_text" in layout["properties"]
+        offsets = layout["properties"]["body_text"]["properties"]
+        assert offsets["x_offset"]["default"] == 0
+        assert offsets["y_offset"]["default"] == 0
+
+    def test_input_schema_not_mutated(self):
+        before = json.dumps(STYLE_ELEMENTS_SCHEMA, sort_keys=True)
+        expand_style_elements(STYLE_ELEMENTS_SCHEMA)
+        assert json.dumps(STYLE_ELEMENTS_SCHEMA, sort_keys=True) == before
+
+    def test_no_declaration_returns_same_object(self):
+        assert expand_style_elements(MANUAL_SCHEMA) is MANUAL_SCHEMA
+        empty = {"properties": {}}
+        assert expand_style_elements(empty) is empty
+
+    def test_garbage_input_never_raises(self):
+        bad = {"properties": {"customization": {"x-style-elements": "nope"}}}
+        assert expand_style_elements(bad) is bad
+
+
+# ---------------------------------------------------------------------------
+# Classic identity: untouched configs resolve to the classic style
+# ---------------------------------------------------------------------------
+
+class TestClassicIdentity:
+    def test_bare_config_resolves_classic(self, style_schema_path):
+        r = _resolver({}, style_schema_path)
+        style = r.style("title_text", classic_font="PressStart2P-Regular.ttf",
+                        classic_size=8, classic_color=(255, 255, 255))
+        assert style.font_name == "PressStart2P-Regular.ttf"
+        assert style.font_size == 8
+        assert style.color == (255, 255, 255)
+        assert style.offset == (0, 0)
+        assert not style.user_forced
+        assert not style.user_forced_color
+        assert isinstance(style.font, ImageFont.FreeTypeFont)
+        assert style.font.size == 8
+
+    def test_schema_populated_config_is_not_an_override(self, style_schema_path):
+        # The web UI's save flow writes the full schema defaults into config
+        # on every save — that must not count as a user override.
+        config = {"customization": {
+            "title_text": {"font": "PressStart2P-Regular.ttf", "font_size": 8,
+                           "text_color": [255, 255, 255]},
+            "layout": {"title_text": {"x_offset": 0, "y_offset": 0}},
+        }}
+        style = _resolver(config, style_schema_path).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8, classic_color=(255, 255, 255))
+        assert not style.user_forced
+        assert not style.user_forced_color
+        assert style.font_size == 8
+        assert style.color == (255, 255, 255)
+        assert style.offset == (0, 0)
+
+    def test_schema_default_falls_back_to_classic_not_schema_font(
+            self, manual_schema_path):
+        # Classic values and schema defaults can legitimately differ
+        # (football's status_text: schema says 4x6, classic loader used
+        # PressStart). A schema-default config value must yield the CLASSIC
+        # font, byte-identical to the old loader.
+        config = {"customization": {"status_text": {"font": "4x6-font.ttf",
+                                                    "font_size": 6}}}
+        style = _resolver(config, manual_schema_path).style(
+            "status_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=6)
+        assert not style.user_forced
+        assert style.font_name == "PressStart2P-Regular.ttf"
+        assert style.font_size == 6
+
+    def test_same_font_object_from_cache(self, style_schema_path):
+        r = _resolver({}, style_schema_path)
+        s1 = r.style("title_text", classic_font="PressStart2P-Regular.ttf",
+                     classic_size=8)
+        s2 = ElementStyleResolver({}, {}).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8)
+        assert s1.font is s2.font
+
+
+# ---------------------------------------------------------------------------
+# User overrides engage
+# ---------------------------------------------------------------------------
+
+class TestUserOverrides:
+    def test_font_override(self, style_schema_path):
+        config = {"customization": {"title_text": {"font": "4x6-font.ttf"}}}
+        style = _resolver(config, style_schema_path).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8)
+        assert style.user_forced
+        assert style.font_name == "4x6-font.ttf"
+        assert style.font_size == 8  # size untouched -> classic
+
+    def test_size_override(self, style_schema_path):
+        config = {"customization": {"title_text": {
+            "font": "PressStart2P-Regular.ttf", "font_size": 16}}}
+        style = _resolver(config, style_schema_path).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8)
+        assert style.user_forced
+        assert style.font_name == "PressStart2P-Regular.ttf"
+        assert style.font_size == 16
+        assert style.font.size == 16
+
+    def test_size_override_detected_vs_schema_default(self, manual_schema_path):
+        # font_size 8 differs from the schema default 6 -> forced.
+        config = {"customization": {"status_text": {"font": "4x6-font.ttf",
+                                                    "font_size": 8}}}
+        style = _resolver(config, manual_schema_path).style(
+            "status_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=6)
+        assert style.user_forced
+        assert style.font_size == 8
+
+    def test_color_override(self, style_schema_path):
+        config = {"customization": {"title_text": {"text_color": [255, 0, 0]}}}
+        style = _resolver(config, style_schema_path).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8, classic_color=(255, 255, 255))
+        assert style.user_forced_color
+        assert not style.user_forced
+        assert style.color == (255, 0, 0)
+
+    def test_offsets(self, style_schema_path):
+        config = {"customization": {"layout": {
+            "title_text": {"x_offset": 4, "y_offset": -2}}}}
+        r = _resolver(config, style_schema_path)
+        assert r.offset("title_text") == (4, -2)
+        assert r.offset("body_text") == (0, 0)
+        style = r.style("title_text", classic_font="PressStart2P-Regular.ttf",
+                        classic_size=8)
+        assert style.offset == (4, -2)
+
+    def test_offset_value_arbitrary_axis_and_strings(self, style_schema_path):
+        # The scoreboards read non-standard axes (away_x_offset) and configs
+        # can carry numeric strings/floats.
+        config = {"customization": {"layout": {"records": {
+            "away_x_offset": "3", "home_x_offset": 2.7}}}}
+        r = _resolver(config, style_schema_path)
+        assert r.offset_value("records", "away_x_offset", 0) == 3
+        assert r.offset_value("records", "home_x_offset", 0) == 2
+        assert r.offset_value("records", "missing_axis", 5) == 5
+
+
+# ---------------------------------------------------------------------------
+# Defensive degradation
+# ---------------------------------------------------------------------------
+
+class TestDegradation:
+    @pytest.mark.parametrize("config", [
+        None,
+        {"customization": "not a dict"},
+        {"customization": {"title_text": "not a dict"}},
+        {"customization": {"title_text": {"font": 42, "font_size": "huge",
+                                          "text_color": "red"}}},
+        {"customization": {"layout": {"title_text": {"x_offset": "junk"}}}},
+    ])
+    def test_bad_config_degrades_to_classic(self, config, style_schema_path):
+        style = _resolver(config, style_schema_path).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8, classic_color=(10, 20, 30))
+        assert not style.user_forced
+        assert not style.user_forced_color
+        assert style.font_name == "PressStart2P-Regular.ttf"
+        assert style.font_size == 8
+        assert style.color == (10, 20, 30)
+        assert style.offset == (0, 0)
+
+    def test_unknown_font_falls_back(self, style_schema_path):
+        config = {"customization": {"title_text": {"font": "no-such.ttf"}}}
+        style = _resolver(config, style_schema_path).style(
+            "title_text", classic_font="PressStart2P-Regular.ttf",
+            classic_size=8)
+        # The override IS honored as forced, but the face degrades safely.
+        assert style.user_forced
+        assert style.font is not None
+
+    def test_empty_defaults_treats_config_as_reference_to_classic(self):
+        # No schema defaults at all: a config value equal to the classic
+        # value is not forced; a different one is.
+        r = ElementStyleResolver(
+            {"customization": {"e": {"font": "4x6-font.ttf"}}}, {})
+        assert not r.style("e", classic_font="4x6-font.ttf",
+                           classic_size=6).user_forced
+        assert r.style("e", classic_font="PressStart2P-Regular.ttf",
+                       classic_size=6).user_forced
+
+
+# ---------------------------------------------------------------------------
+# Resolver plumbing the consumers rely on
+# ---------------------------------------------------------------------------
+
+class TestResolverPlumbing:
+    def test_config_identity_exposed(self, style_schema_path):
+        # Consumers rebuild the resolver when the config dict is swapped:
+        # `resolver._config is not self.config`.
+        config = {"customization": {}}
+        r = _resolver(config, style_schema_path)
+        assert r._config is config
+
+    def test_font_path_resolution_is_cwd_independent(self, tmp_path,
+                                                     monkeypatch):
+        monkeypatch.chdir(tmp_path)  # no assets/fonts under cwd
+        path = resolve_font_path("PressStart2P-Regular.ttf")
+        assert path is not None and os.path.isfile(path)
+        font = load_font("PressStart2P-Regular.ttf", 8)
+        assert isinstance(font, ImageFont.FreeTypeFont)
+
+    def test_bdf_font_loads_as_freetype_face(self):
+        import freetype
+        font = load_font("5x7.bdf", 7)
+        assert isinstance(font, freetype.Face)
+
+    def test_schema_manager_expands_on_load(self, tmp_path):
+        # The web-UI form path: SchemaManager.load_schema serves the
+        # expanded schema so the style blocks actually appear in the UI.
+        from src.plugin_system.schema_manager import SchemaManager
+        plugin_dir = tmp_path / "plugins" / "styled"
+        plugin_dir.mkdir(parents=True)
+        (plugin_dir / "config_schema.json").write_text(
+            json.dumps(STYLE_ELEMENTS_SCHEMA))
+        (plugin_dir / "manifest.json").write_text(json.dumps({
+            "id": "styled", "config_schema": "config_schema.json"}))
+        manager = SchemaManager(plugins_dir=tmp_path / "plugins",
+                                project_root=tmp_path)
+        schema = manager.load_schema("styled")
+        assert schema is not None
+        cust = schema["properties"]["customization"]["properties"]
+        assert cust["title_text"]["x-style-managed"] is True
+        assert "title_text" in cust["layout"]["properties"]

test/test_sports_base_characterization.py

@@ -0,0 +1,634 @@
+"""Characterization tests for src/base_classes/sports.py.
+
+These tests PIN the current behavior of SportsCore / SportsUpcoming /
+SportsRecent / SportsLive ahead of the sports-unification merge (features
+from nine drifted plugin copies are about to be folded in). They assert
+what the code DOES today, not what it should do — a few pinned behaviors
+look like bugs and are flagged inline with "PINNED AS-IS".
+
+Coverage:
+- `_extract_game_details_common` + the four sport extractors
+  (football/hockey/baseball/basketball) against realistic ESPN scoreboard
+  events (adapted from the ledmatrix-plugins monorepo test fixtures).
+  The output must remain a superset of the frozen skin view-model
+  contract (GUARANTEED_KEYS, imported from test_skin_system).
+- update() flow for concrete SportsUpcoming/SportsRecent/SportsLive
+  subclasses: population, favorite-team filtering, empty/failed-fetch
+  tolerance. All offline: `_fetch_data` reads a pre-seeded mocked cache
+  and every instance's requests session raises ConnectionError.
+- Rendering smoke: one `display()` per mode class at 128x32 draws
+  non-zero ink onto a real PIL image.
+- Guard rails: the skin-system seam methods on SportsCore must survive
+  the merge.
+"""
+
+import logging
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+import pytz
+import requests
+from freezegun import freeze_time
+from PIL import Image
+
+# src.base_classes.sports transitively imports the hardware matrix driver;
+# stub it so these tests can import the sports base classes off-device.
+sys.modules.setdefault("rgbmatrix", MagicMock())
+
+from src.base_classes.baseball import Baseball
+from src.base_classes.basketball import Basketball
+from src.base_classes.football import Football
+from src.base_classes.hockey import Hockey, HockeyLive
+from src.base_classes.sports import (
+    SportsCore,
+    SportsLive,
+    SportsRecent,
+    SportsUpcoming,
+)
+
+# Reuse the frozen v1.0 skin view-model contract rather than redeclaring it.
+from test.test_skin_system import GUARANTEED_KEYS
+
+SPORT_CLASSES = [Football, Hockey, Baseball, Basketball]
+SPORT_IDS = ["football", "hockey", "baseball", "basketball"]
+
+# All update()-flow tests run at this frozen instant so the 21-day
+# SportsRecent window and time.time() interval gates are deterministic.
+FROZEN_NOW = "2026-01-20 12:00:00"
+
+
+# ---------------------------------------------------------------------------
+# ESPN scoreboard event builders (shape adapted from the monorepo fixtures,
+# e.g. ledmatrix-plugins/plugins/hockey-scoreboard/test/fixtures/mock.json:
+# team-shaped competitors with status/score/records).
+# ---------------------------------------------------------------------------
+
+def _competitor(abbr, team_id, score, home_away, record="30-10-5"):
+    return {
+        "homeAway": home_away,
+        "id": team_id,
+        "score": score,
+        "team": {
+            "id": team_id,
+            "abbreviation": abbr,
+            "name": abbr.title(),
+            "displayName": abbr.title(),
+            "logo": None,
+        },
+        "records": [{"summary": record}],
+        # The hockey extractor iterates competitor["statistics"] and
+        # returns None for the whole event when the key is absent (see
+        # test_hockey_event_without_statistics_returns_none).
+        "statistics": [],
+    }
+
+
+def make_event(event_id, state, date, home=("TB", "20", "3"),
+               away=("DAL", "9", "2"), period=2, clock="12:45",
+               name=None, short_detail=None, situation=None,
+               home_record="30-10-5", away_record="25-14-6"):
+    """Build a realistic ESPN scoreboard event in the given state
+    ('in' / 'post' / 'pre')."""
+    defaults = {
+        "in": ("STATUS_IN_PROGRESS", f"P{period} {clock}"),
+        "post": ("STATUS_FINAL", "Final"),
+        "pre": ("STATUS_SCHEDULED", "1/15 - 6:30 PM"),
+    }
+    default_name, default_detail = defaults[state]
+    status = {
+        "clock": 0.0,
+        "displayClock": clock,
+        "period": period,
+        "type": {
+            "id": "2",
+            "name": name or default_name,
+            "state": state,
+            "completed": state == "post",
+            "description": short_detail or default_detail,
+            "detail": short_detail or default_detail,
+            "shortDetail": short_detail or default_detail,
+        },
+    }
+    competition = {
+        "id": event_id,
+        "date": date,
+        "status": status,
+        "competitors": [
+            _competitor(home[0], home[1], home[2], "home", home_record),
+            _competitor(away[0], away[1], away[2], "away", away_record),
+        ],
+    }
+    if situation is not None:
+        competition["situation"] = situation
+    return {
+        "id": event_id,
+        "date": date,
+        "name": f"{away[0]} at {home[0]}",
+        "shortName": f"{away[0]} @ {home[0]}",
+        "competitions": [competition],
+        # Real ESPN payloads duplicate status at the event top level; the
+        # baseball extractor reads it there for live innings.
+        "status": status,
+    }
+
+
+def make_probe(favorites=None):
+    """Bare-bones SportsCore stand-in for exercising the real extractors
+    unbound (same pattern as TestViewModelContract in test_skin_system)."""
+    probe = MagicMock()
+    probe.logger = logging.getLogger("test_sports_base_characterization")
+    probe.favorite_teams = list(favorites or [])
+    probe.config = {}
+    probe.logo_dir = Path("assets/logos")
+    probe._get_timezone.return_value = pytz.utc
+    probe.display_manager.format_date_with_ordinal.return_value = "Jan 15th"
+    # The sport extractors call self._extract_game_details_common — route
+    # it to the real implementation instead of a MagicMock.
+    probe._extract_game_details_common = (
+        lambda event: SportsCore._extract_game_details_common(probe, event))
+    return probe
+
+
+def extract(sport_cls, event, favorites=None):
+    return sport_cls._extract_game_details(make_probe(favorites), event)
+
+
+# ---------------------------------------------------------------------------
+# 1. _extract_game_details_common contract, per wired sport
+# ---------------------------------------------------------------------------
+
+class TestExtractGameDetailsContract:
+    @pytest.mark.parametrize("sport_cls", SPORT_CLASSES, ids=SPORT_IDS)
+    def test_live_event_guaranteed_keys_and_values(self, sport_cls):
+        event = make_event("401", "in", "2026-01-15T18:30:00Z")
+        details = extract(sport_cls, event)
+        assert details is not None
+        missing = [k for k in GUARANTEED_KEYS if k not in details]
+        assert not missing, (
+            f"{sport_cls.__name__} extractor no longer emits {missing} — "
+            "these keys are the frozen skin view-model contract.")
+        assert details["id"] == "401"
+        assert details["home_abbr"] == "TB"
+        assert details["away_abbr"] == "DAL"
+        assert details["home_id"] == "20"
+        assert details["away_id"] == "9"
+        assert details["home_score"] == "3"
+        assert details["away_score"] == "2"
+        assert details["home_record"] == "30-10-5"
+        assert details["away_record"] == "25-14-6"
+        assert details["is_live"] is True
+        assert details["is_final"] is False
+        assert details["is_upcoming"] is False
+        assert details["status_text"] == "P2 12:45"
+        assert details["start_time_utc"] == datetime(
+            2026, 1, 15, 18, 30, tzinfo=timezone.utc)
+        # Sport-specific formatting of the same event:
+        if sport_cls in (Football, Basketball):
+            assert details["period_text"] == "Q2"
+            assert details["clock"] == "12:45"
+        elif sport_cls is Hockey:
+            assert details["period_text"] == "P2"
+            assert details["clock"] == "12:45"
+        else:  # Baseball keys inning/status instead of period_text
+            assert details["inning"] == 2
+            assert details["status_state"] == "in"
+
+    @pytest.mark.parametrize("sport_cls", SPORT_CLASSES, ids=SPORT_IDS)
+    def test_final_event_classification(self, sport_cls):
+        event = make_event("402", "post", "2026-01-14T00:00:00Z",
+                           home=("BOS", "1", "4"), away=("TOR", "21", "2"),
+                           period=3, clock="0:00")
+        details = extract(sport_cls, event)
+        assert details is not None
+        assert details["is_final"] is True
+        assert details["is_live"] is False
+        assert details["is_upcoming"] is False
+        assert details["home_score"] == "4"
+        assert details["away_score"] == "2"
+        if sport_cls in (Football, Hockey, Basketball):
+            assert details["period_text"] == "Final"
+
+    @pytest.mark.parametrize("sport_cls", SPORT_CLASSES, ids=SPORT_IDS)
+    def test_upcoming_event_classification(self, sport_cls):
+        event = make_event("403", "pre", "2026-01-15T18:30:00Z",
+                           home=("NYR", "13", "0"), away=("PIT", "16", "0"),
+                           period=0, clock="0:00")
+        details = extract(sport_cls, event)
+        assert details is not None
+        assert details["is_upcoming"] is True
+        assert details["is_live"] is False
+        assert details["is_final"] is False
+        # Local time formatting (probe timezone is UTC): 18:30Z -> 6:30PM,
+        # date rendered through display_manager.format_date_with_ordinal.
+        assert details["game_time"] == "6:30PM"
+        assert details["game_date"] == "Jan 15th"
+
+    def test_halftime_state_flags(self):
+        # is_halftime keys off name STATUS_HALFTIME (or state "halftime")
+        # while state "in" still counts as live.
+        event = make_event("404", "in", "2026-01-15T18:30:00Z",
+                           name="STATUS_HALFTIME", short_detail="Halftime")
+        details, *_ = SportsCore._extract_game_details_common(
+            make_probe(), event)
+        assert details["is_live"] is True
+        assert details["is_halftime"] is True
+
+    def test_state_name_conflict_is_both_final_and_upcoming(self):
+        # PINNED AS-IS (looks like a bug): is_upcoming also matches on
+        # status.type.name ('scheduled'/'pre-game'/'status_scheduled'), so
+        # an event with state="post" but name="Scheduled" reports BOTH
+        # is_final and is_upcoming True.
+        event = make_event("405", "post", "2026-01-14T00:00:00Z",
+                           name="Scheduled")
+        details, *_ = SportsCore._extract_game_details_common(
+            make_probe(), event)
+        assert details["is_final"] is True
+        assert details["is_upcoming"] is True
+
+    def test_zero_zero_record_blanked(self):
+        event = make_event("406", "pre", "2026-01-15T18:30:00Z",
+                           home_record="0-0", away_record="0-0-0")
+        details, *_ = SportsCore._extract_game_details_common(
+            make_probe(), event)
+        assert details["home_record"] == ""
+        assert details["away_record"] == ""
+
+    def test_missing_abbreviation_uses_name_prefix(self):
+        event = make_event("407", "pre", "2026-01-15T18:30:00Z")
+        for comp in event["competitions"][0]["competitors"]:
+            del comp["team"]["abbreviation"]
+            comp["team"]["name"] = "Sharks" if comp["homeAway"] == "home" \
+                else "Penguins"
+        details, *_ = SportsCore._extract_game_details_common(
+            make_probe(), event)
+        assert details["home_abbr"] == "Sha"
+        assert details["away_abbr"] == "Pen"
+
+    def test_empty_or_malformed_event_returns_none_tuple(self):
+        probe = make_probe()
+        assert SportsCore._extract_game_details_common(probe, {}) == \
+            (None, None, None, None, None)
+        assert SportsCore._extract_game_details_common(probe, None) == \
+            (None, None, None, None, None)
+        # Malformed event (no competitions) is swallowed, not raised.
+        assert SportsCore._extract_game_details_common(
+            probe, {"id": "999"}) == (None, None, None, None, None)
+
+    def test_football_live_situation_fields(self):
+        event = make_event(
+            "408", "in", "2026-01-15T18:30:00Z",
+            situation={
+                "shortDownDistanceText": "3rd & 4",
+                "downDistanceText": "3rd & 4 at TB 30",
+                "isRedZone": False,
+                "possession": "20",
+                "homeTimeouts": 2,
+                "awayTimeouts": 3,
+            })
+        details = extract(Football, event)
+        assert details["down_distance_text"] == "3rd & 4"
+        assert details["down_distance_text_long"] == "3rd & 4 at TB 30"
+        assert details["possession"] == "20"
+        assert details["possession_indicator"] == "home"  # matches home id
+        assert details["home_timeouts"] == 2
+        assert details["away_timeouts"] == 3
+
+    def test_hockey_live_power_play_and_default_shots(self):
+        event = make_event("409", "in", "2026-01-15T18:30:00Z",
+                           situation={"isPowerPlay": True, "penalties": ""})
+        details = extract(Hockey, event)
+        assert details["power_play"] is True
+        # Empty statistics arrays -> save-percentage math yields 0 shots.
+        assert details["home_shots"] == 0
+        assert details["away_shots"] == 0
+
+    def test_hockey_event_without_statistics_still_extracts(self):
+        # FIXED (was pinned as returning None): the hockey extractor used to
+        # iterate competitor["statistics"] unguarded, so a competitor without
+        # the key raised KeyError internally and the WHOLE event was dropped
+        # despite valid scores and status. It now defaults to an empty list,
+        # matching the behaviour already shipped in the hockey plugin, so the
+        # event survives with zeroed shot counts -- the same values
+        # test_hockey_live_power_play_and_default_shots already expects for an
+        # EMPTY statistics array.
+        event = make_event("410", "in", "2026-01-15T18:30:00Z")
+        for comp in event["competitions"][0]["competitors"]:
+            del comp["statistics"]
+        details = extract(Hockey, event)
+        assert details is not None
+        assert details["home_abbr"] == "TB"
+        assert details["away_abbr"] == "DAL"
+        assert details["home_score"] == "3"
+        assert details["home_shots"] == 0
+        assert details["away_shots"] == 0
+
+    def test_baseball_live_inning_and_count(self):
+        event = make_event(
+            "411", "in", "2026-07-16T23:05:00Z",
+            home=("LAD", "19", "5"), away=("SF", "26", "3"),
+            period=7, short_detail="Bot 7th",
+            situation={
+                "count": {"balls": 2, "strikes": 1},
+                "outs": 2,
+                "onFirst": True,
+                "onSecond": False,
+                "onThird": True,
+            })
+        details = extract(Baseball, event)
+        assert details["inning"] == 7          # from top-level status period
+        assert details["inning_half"] == "bottom"
+        assert details["balls"] == 2
+        assert details["strikes"] == 1
+        assert details["outs"] == 2
+        assert details["bases_occupied"] == [True, False, True]
+        assert details["status"] == "status_in_progress"
+        assert details["series_summary"] == ""
+
+    def test_baseball_live_without_top_level_status_still_extracts(self):
+        # FIXED (was pinned as returning None): the baseball extractor read
+        # game_event["status"] -- the event TOP-LEVEL status -- for the
+        # inning, so an otherwise-valid live event lacking that duplicate key
+        # was dropped entirely. Real ESPN events carry status in both places,
+        # but MiLB events (synthesized from the MLB Stats API into an
+        # ESPN-like shape) populate only the competition-level one. It now
+        # reads the competition-level `status` that
+        # _extract_game_details_common has already validated, so it can never
+        # be missing at that point.
+        event = make_event("412", "in", "2026-07-16T23:05:00Z", period=7)
+        del event["status"]
+        details = extract(Baseball, event)
+        assert details is not None
+        assert details["inning"] == 7
+
+
+# ---------------------------------------------------------------------------
+# 2. update() flow on concrete subclasses (offline, cache-fed)
+# ---------------------------------------------------------------------------
+
+class _UpcomingHarness(Hockey, SportsUpcoming):
+    """Cheapest concrete SportsUpcoming: hockey extractor + cache-fed data."""
+
+    def _fetch_data(self):
+        return self.cache_manager.get(f"{self.sport_key}_schedule")
+
+
+class _RecentHarness(Hockey, SportsRecent):
+    def _fetch_data(self):
+        return self.cache_manager.get(f"{self.sport_key}_schedule")
+
+
+class _LiveHarness(HockeyLive):
+    def _fetch_data(self):
+        return self.cache_manager.get(f"{self.sport_key}_schedule")
+
+
+def make_schedule():
+    """A mixed schedule around the frozen 'now' of 2026-01-20."""
+    return {"events": [
+        # Final 6 days ago — inside the recent 21-day window.
+        make_event("9001", "post", "2026-01-14T00:00:00Z",
+                   home=("BOS", "1", "4"), away=("TOR", "21", "2"),
+                   period=3, clock="0:00"),
+        # Live game.
+        make_event("9002", "in", "2026-01-15T00:30:00Z",
+                   home=("TB", "20", "3"), away=("DAL", "9", "2")),
+        # Two scheduled games.
+        make_event("9003", "pre", "2026-01-16T00:00:00Z",
+                   home=("NYR", "13", "0"), away=("PIT", "16", "0"),
+                   period=0),
+        make_event("9004", "pre", "2026-01-17T00:00:00Z",
+                   home=("BOS", "1", "0"), away=("MTL", "10", "0"),
+                   period=0),
+        # Final from November — outside the recent 21-day window.
+        make_event("9005", "post", "2025-11-01T00:00:00Z",
+                   home=("SEA", "124292", "1"), away=("VAN", "22", "5"),
+                   period=3, clock="0:00"),
+    ]}
+
+
+@pytest.fixture
+def build_manager(monkeypatch, tmp_path):
+    """Factory for concrete sports managers: mocked display/cache managers,
+    logo dir redirected to tmp, background service stubbed, and the
+    requests session rigged to prove nothing hits the network."""
+    monkeypatch.setattr(
+        SportsCore, "_initialize_logo_dir", lambda self, configured: tmp_path)
+    monkeypatch.setattr(
+        "src.base_classes.sports.core.get_background_service",
+        lambda *args, **kwargs: MagicMock())
+
+    def build(cls, schedule, **mode_cfg):
+        config = {
+            "timezone": "UTC",
+            "display": {},
+            "nhl_scoreboard": {"enabled": True, **mode_cfg},
+        }
+        display_manager = MagicMock()
+        display_manager.matrix.width = 128
+        display_manager.matrix.height = 32
+        display_manager.width = 128
+        display_manager.height = 32
+        display_manager.image = Image.new("RGB", (128, 32))
+        display_manager.format_date_with_ordinal.side_effect = (
+            lambda dt: dt.strftime("%b %d"))
+        cache_manager = MagicMock()
+        cache_manager.get.return_value = schedule
+        cache_manager.cache_dir = str(tmp_path)
+        manager = cls(config, display_manager, cache_manager,
+                      logging.getLogger("test_sports_base_characterization"),
+                      "nhl")
+        # Safety net: any accidental network fetch must fail loudly.
+        manager.session = MagicMock()
+        manager.session.get.side_effect = requests.exceptions.ConnectionError(
+            "characterization tests are offline")
+        return manager
+
+    return build
+
+
+def _ids(games):
+    return [g["id"] for g in games]
+
+
+@freeze_time(FROZEN_NOW)
+class TestUpcomingUpdateFlow:
+    def test_populates_games_list_sorted_by_start_time(self, build_manager):
+        manager = build_manager(_UpcomingHarness, make_schedule())
+        manager.update()
+        # PINNED AS-IS: SportsUpcoming filters purely on is_upcoming
+        # (state 'pre') — there is NO date filter, so 'pre' games whose
+        # start time is already in the past (9003/9004 vs frozen 1/20)
+        # are still shown.
+        assert _ids(manager.games_list) == ["9003", "9004"]
+        assert manager.current_game["id"] == "9003"
+
+    def test_filters_by_favorite_teams(self, build_manager):
+        manager = build_manager(_UpcomingHarness, make_schedule(),
+                                show_favorite_teams_only=True,
+                                favorite_teams=["BOS"])
+        manager.update()
+        assert _ids(manager.games_list) == ["9004"]
+        assert manager.current_game["id"] == "9004"
+
+    def test_favorites_only_with_no_favorites_shows_nothing(
+            self, build_manager):
+        # PINNED AS-IS: show_favorite_teams_only=True with an empty
+        # favorite_teams list drops every game rather than falling back
+        # to showing all games.
+        manager = build_manager(_UpcomingHarness, make_schedule(),
+                                show_favorite_teams_only=True,
+                                favorite_teams=[])
+        manager.update()
+        assert manager.games_list == []
+        assert manager.current_game is None
+
+    def test_caps_at_upcoming_games_to_show(self, build_manager):
+        manager = build_manager(_UpcomingHarness, make_schedule(),
+                                upcoming_games_to_show=1)
+        manager.update()
+        assert _ids(manager.games_list) == ["9003"]
+
+    def test_tolerates_empty_events_list(self, build_manager):
+        manager = build_manager(_UpcomingHarness, {"events": []})
+        manager.update()  # must not raise
+        assert manager.games_list == []
+        assert manager.current_game is None
+
+    def test_tolerates_fetch_returning_none(self, build_manager):
+        manager = build_manager(_UpcomingHarness, None)
+        manager.update()  # must not raise
+        assert manager.games_list == []
+        assert manager.current_game is None
+
+    def test_disabled_manager_update_is_noop(self, build_manager):
+        manager = build_manager(_UpcomingHarness, make_schedule(),
+                                enabled=False)
+        manager.update()
+        assert manager.games_list == []
+        manager.cache_manager.get.assert_not_called()
+
+
+@freeze_time(FROZEN_NOW)
+class TestRecentUpdateFlow:
+    def test_populates_only_finals_within_21_day_window(self, build_manager):
+        manager = build_manager(_RecentHarness, make_schedule())
+        manager.update()
+        # 9001 (final, 6 days old) kept; 9005 (final, ~80 days old)
+        # excluded by the 21-day cutoff; live/pre games excluded.
+        assert _ids(manager.games_list) == ["9001"]
+        assert manager.current_game["id"] == "9001"
+        assert manager.current_game["is_final"] is True
+
+    def test_filters_by_favorite_teams(self, build_manager):
+        manager = build_manager(_RecentHarness, make_schedule(),
+                                show_favorite_teams_only=True,
+                                favorite_teams=["TOR"])
+        manager.update()
+        assert _ids(manager.games_list) == ["9001"]
+
+        stranger = build_manager(_RecentHarness, make_schedule(),
+                                 show_favorite_teams_only=True,
+                                 favorite_teams=["XXX"])
+        stranger.update()
+        assert stranger.games_list == []
+        assert stranger.current_game is None
+
+    def test_tolerates_empty_events_list(self, build_manager):
+        manager = build_manager(_RecentHarness, {"events": []})
+        manager.update()  # must not raise
+        assert manager.games_list == []
+        assert manager.current_game is None
+
+
+@freeze_time(FROZEN_NOW)
+class TestLiveUpdateFlow:
+    def test_selects_only_live_games(self, build_manager):
+        manager = build_manager(_LiveHarness, make_schedule())
+        manager.update()
+        assert _ids(manager.live_games) == ["9002"]
+        assert manager.current_game["id"] == "9002"
+        assert manager.current_game["is_live"] is True
+
+    def test_no_live_games_clears_current_game(self, build_manager):
+        schedule = {"events": [
+            make_event("9001", "post", "2026-01-14T00:00:00Z"),
+            make_event("9003", "pre", "2026-01-16T00:00:00Z", period=0),
+        ]}
+        manager = build_manager(_LiveHarness, schedule)
+        manager.update()
+        assert manager.live_games == []
+        assert manager.current_game is None
+
+
+# ---------------------------------------------------------------------------
+# 3. Rendering smoke — one display() per mode class at 128x32
+# ---------------------------------------------------------------------------
+
+def _fake_logo(*args, **kwargs):
+    return Image.new("RGBA", (24, 24), (180, 30, 30, 255))
+
+
+@freeze_time(FROZEN_NOW)
+class TestRenderingSmoke:
+    def _assert_rendered(self, manager):
+        manager.display_manager.update_display.assert_called()
+        assert manager.display_manager.image.convert("L").getbbox() is not None
+
+    def test_upcoming_display_draws_ink(self, build_manager):
+        manager = build_manager(_UpcomingHarness, make_schedule())
+        manager.update()
+        manager._load_and_resize_logo = _fake_logo
+        assert manager.display(force_clear=True) is True
+        self._assert_rendered(manager)
+
+    def test_recent_display_draws_ink(self, build_manager):
+        manager = build_manager(_RecentHarness, make_schedule())
+        manager.update()
+        manager._load_and_resize_logo = _fake_logo
+        assert manager.display(force_clear=True) is True
+        self._assert_rendered(manager)
+
+    def test_live_display_draws_ink(self, build_manager):
+        manager = build_manager(_LiveHarness, make_schedule())
+        manager.update()
+        manager._load_and_resize_logo = _fake_logo
+        assert manager.display(force_clear=True) is True
+        self._assert_rendered(manager)
+
+    def test_draw_scorebug_layout_direct_call_does_not_raise(
+            self, build_manager):
+        # The base-class placeholder renderer must also stay callable.
+        manager = build_manager(_UpcomingHarness, make_schedule())
+        game = manager._extract_game_details(make_schedule()["events"][2])
+        manager._load_and_resize_logo = _fake_logo
+        SportsCore._draw_scorebug_layout(manager, game)
+        assert manager.display_manager.image.convert("L").getbbox() is not None
+
+
+# ---------------------------------------------------------------------------
+# 4. Guard rails — seams the merge must not silently drop
+# ---------------------------------------------------------------------------
+
+class TestGuardRails:
+    def test_skin_seam_methods_survive(self):
+        for name in ("_resolve_skin_id", "_get_skin", "_render_game",
+                     "render_skin_card"):
+            assert callable(getattr(SportsCore, name, None)), (
+                f"SportsCore.{name} is part of the skin-system seam "
+                "(src/skin_system) — the sports-unification merge must "
+                "keep it.")
+
+    def test_skin_mode_per_class(self):
+        assert SportsCore.SKIN_MODE == "live"
+        assert SportsUpcoming.SKIN_MODE == "upcoming"
+        assert SportsRecent.SKIN_MODE == "recent"
+        assert SportsLive.SKIN_MODE == "live"  # inherits the default
+
+    def test_core_display_and_extractor_seams_survive(self):
+        for name in ("display", "_draw_scorebug_layout",
+                     "_extract_game_details_common", "update"):
+            owner = SportsCore if name != "update" else SportsUpcoming
+            assert callable(getattr(owner, name, None)), name

test/test_sports_capabilities.py

@@ -0,0 +1,764 @@
+"""Tests for the opt-in sports capabilities (phase B2).
+
+Two properties matter beyond "the code works":
+
+1. **Opting out is structural.** A mode class that does not mix in
+   ``CelebrationMixin`` must have none of its attributes or methods — not
+   merely a disabled flag. ``TestOptOutIsStructural`` asserts that directly,
+   because it is the property the whole mixin design exists to buy.
+
+2. **The promoted behavior matches the plugin copies.** These bodies came from
+   afl/soccer/nrl (goal dialect) and football (score dialect); the tests pin
+   the reconciled behavior of both, including the three seams where the
+   lineages genuinely disagreed.
+
+See docs/SPORTS_UNIFICATION.md.
+"""
+
+import sys
+from unittest.mock import MagicMock
+
+import pytest
+
+sys.modules.setdefault("rgbmatrix", MagicMock())
+
+from src.base_classes.sports.capabilities import (  # noqa: E402
+    CelebrationMixin,
+    RotationStrategy,
+    SimpleRotation,
+    SmoothWeightedRotation,
+    WeightedCycleRotation,
+    get_rotation_strategy,
+    register_rotation_strategy,
+)
+
+
+def game(gid, home="HOM", away="AWY", home_score=0, away_score=0, **extra):
+    g = {
+        "id": gid,
+        "home_abbr": home,
+        "away_abbr": away,
+        "home_id": f"{gid}-h",
+        "away_id": f"{gid}-a",
+        "home_score": home_score,
+        "away_score": away_score,
+    }
+    g.update(extra)
+    return g
+
+
+# ---------------------------------------------------------------------------
+# Rotation strategies
+# ---------------------------------------------------------------------------
+
+def boost(favorites, factor=3):
+    """A weight_for callable of the shape the plugins supply."""
+    return lambda g: factor if g.get("home_abbr") in favorites else 1
+
+
+class TestRegistry:
+    @pytest.mark.parametrize("name,cls", [
+        ("simple", SimpleRotation),
+        ("weighted", WeightedCycleRotation),
+        ("swrr", SmoothWeightedRotation),
+    ])
+    def test_builtin_names_resolve(self, name, cls):
+        assert isinstance(get_rotation_strategy(name), cls)
+
+    def test_unknown_name_falls_back_to_simple(self):
+        """The name comes from user config; a typo should cost the boost, not
+        the scoreboard."""
+        assert isinstance(get_rotation_strategy("typo"), SimpleRotation)
+
+    def test_a_plugin_can_register_its_own(self):
+        class MyRotation(SimpleRotation):
+            pass
+
+        register_rotation_strategy("test-only", MyRotation)
+        try:
+            assert isinstance(get_rotation_strategy("test-only"), MyRotation)
+            assert MyRotation.name == "test-only"
+        finally:
+            from src.base_classes.sports.capabilities import rotation
+            rotation._REGISTRY.pop("test-only", None)
+
+    def test_empty_name_is_rejected(self):
+        with pytest.raises(ValueError):
+            register_rotation_strategy("", SimpleRotation)
+
+    def test_weight_for_is_optional(self):
+        """Default weights are equal, so every strategy degenerates to a plain
+        round robin — the pre-boost behavior."""
+        games = [game("a"), game("b"), game("c")]
+        for name in ("simple", "weighted", "swrr"):
+            assert get_rotation_strategy(name).schedule(games) == ["a", "b", "c"]
+
+
+class TestWeights:
+    def test_games_without_an_id_are_skipped(self):
+        strategy = get_rotation_strategy("weighted")
+        assert strategy.weights([game("a"), {"home_abbr": "X"}]) == {"a": 1}
+
+    @pytest.mark.parametrize("bad", [0, -5])
+    def test_non_positive_weights_are_clamped_to_one(self, bad):
+        """A zero weight would starve the game out of the rotation entirely and
+        collapse total_weight — no caller means that."""
+        strategy = get_rotation_strategy("weighted", weight_for=lambda g: bad)
+        assert strategy.weights([game("a")]) == {"a": 1}
+
+    @pytest.mark.parametrize("bad", [None, "three", object()])
+    def test_unusable_weights_fall_back_to_one(self, bad):
+        strategy = get_rotation_strategy("weighted", weight_for=lambda g: bad)
+        assert strategy.weights([game("a")]) == {"a": 1}
+
+
+class TestSimpleRotation:
+    def test_one_pass_in_feed_order(self):
+        games = [game("a"), game("b"), game("c")]
+        assert SimpleRotation().schedule(games) == ["a", "b", "c"]
+
+    def test_weights_are_ignored(self):
+        games = [game("a", home="FAV"), game("b")]
+        strategy = SimpleRotation(weight_for=boost({"FAV"}, 5))
+        assert strategy.schedule(games) == ["a", "b"]
+
+    def test_empty(self):
+        assert SimpleRotation().schedule([]) == []
+        assert SimpleRotation().next_game([]) is None
+
+
+class TestWeightedCycleRotation:
+    def test_no_boost_is_a_single_pass(self):
+        games = [game("a"), game("b"), game("c")]
+        strategy = WeightedCycleRotation(weight_for=boost({"NONE"}))
+        assert strategy.schedule(games) == ["a", "b", "c"]
+
+    def test_favorite_gets_boost_many_slots(self):
+        games = [game("a", home="FAV"), game("b")]
+        order = WeightedCycleRotation(weight_for=boost({"FAV"}, 3)).schedule(games)
+        assert len(order) == 4
+        assert order.count("a") == 3
+        assert order.count("b") == 1
+
+    def test_repeats_are_spaced_not_clumped(self):
+        """The point of SWRR over naive repetition: 'aaab' is what we must NOT
+        produce."""
+        games = [game("a", home="FAV"), game("b")]
+        order = WeightedCycleRotation(weight_for=boost({"FAV"}, 3)).schedule(games)
+        assert order != ["a", "a", "a", "b"]
+        assert order[0] == "a", "highest weight is scheduled first"
+
+    def test_is_stateless_across_calls(self):
+        games = [game("a", home="FAV"), game("b")]
+        strategy = WeightedCycleRotation(weight_for=boost({"FAV"}, 3))
+        assert strategy.schedule(games) == strategy.schedule(games)
+
+    def test_next_game_returns_the_first_of_the_cycle(self):
+        games = [game("a"), game("b", home="FAV")]
+        strategy = WeightedCycleRotation(weight_for=boost({"FAV"}, 4))
+        assert strategy.next_game(games)["id"] == "b"
+
+    def test_empty(self):
+        assert WeightedCycleRotation().schedule([]) == []
+
+
+class TestSmoothWeightedRotation:
+    def test_no_boost_is_plain_round_robin(self):
+        games = [game("a"), game("b"), game("c")]
+        strategy = SmoothWeightedRotation()
+        assert [strategy.next_game(games)["id"] for _ in range(6)] == [
+            "a", "b", "c", "a", "b", "c"]
+
+    def test_favorite_wins_the_share_over_a_long_run(self):
+        games = [game("a", home="FAV"), game("b")]
+        strategy = SmoothWeightedRotation(weight_for=boost({"FAV"}, 3))
+        picks = [strategy.next_game(games)["id"] for _ in range(40)]
+        assert picks.count("a") == 30
+        assert picks.count("b") == 10
+
+    def test_no_clustering_seam_across_cycle_boundaries(self):
+        """The property that motivates keeping this strategy separate from the
+        precomputed one: state persists, so there is no restart every N picks
+        and therefore no place where repeats bunch up."""
+        games = [game("a", home="FAV"), game("b")]
+        strategy = SmoothWeightedRotation(weight_for=boost({"FAV"}, 3))
+        picks = [strategy.next_game(games)["id"] for _ in range(40)]
+        assert "aaaa" not in "".join(picks)
+
+    def test_a_new_favorite_is_queued_first(self):
+        """A favorite's game that has just gone live starts at weight 0, gets
+        its full weight on the next call, and so wins the first pick after it
+        appears — without a special-cased branch."""
+        games = [game("a"), game("b")]
+        strategy = SmoothWeightedRotation(weight_for=boost({"FAV"}, 5))
+        for _ in range(3):
+            strategy.next_game(games)
+        games.append(game("c", home="FAV"))
+        assert strategy.next_game(games)["id"] == "c"
+
+    def test_state_for_games_no_longer_live_is_dropped(self):
+        games = [game("a"), game("b")]
+        strategy = SmoothWeightedRotation()
+        strategy.next_game(games)
+        strategy.next_game([game("a")])
+        assert set(strategy._current) == {"a"}
+
+    def test_reset_clears_state(self):
+        games = [game("a"), game("b")]
+        strategy = SmoothWeightedRotation()
+        strategy.next_game(games)
+        strategy.reset()
+        assert strategy._current == {}
+        assert strategy.next_game(games)["id"] == "a"
+
+    def test_schedule_previews_without_perturbing_state(self):
+        games = [game("a", home="FAV"), game("b")]
+        strategy = SmoothWeightedRotation(weight_for=boost({"FAV"}, 3))
+        preview = strategy.schedule(games)
+        actual = [strategy.next_game(games)["id"] for _ in range(len(preview))]
+        assert preview == actual
+
+    def test_empty(self):
+        assert SmoothWeightedRotation().next_game([]) is None
+        assert SmoothWeightedRotation().schedule([]) == []
+
+    def test_games_without_ids_are_ignored(self):
+        assert SmoothWeightedRotation().next_game([{"home_abbr": "X"}]) is None
+
+
+class TestStrategiesAgreeWithinACycle:
+    """The survey's core finding: the 'three dialects' are one algorithm. They
+    must produce the same order within a cycle; they differ only at the
+    boundary, which is why both shapes survive."""
+
+    @pytest.mark.parametrize("factor", [2, 3, 5])
+    def test_first_cycle_matches(self, factor):
+        games = [game("a", home="FAV"), game("b"), game("c")]
+        weight_for = boost({"FAV"}, factor)
+        assert (SmoothWeightedRotation(weight_for=weight_for).schedule(games)
+                == WeightedCycleRotation(weight_for=weight_for).schedule(games))
+
+
+# ---------------------------------------------------------------------------
+# Differential: core strategies vs. the plugin implementations they replace
+# ---------------------------------------------------------------------------
+
+BOOST = 3
+
+
+def _is_fav(g):
+    return g.get("home_abbr") == "FAV"
+
+
+def _weight_for(g):
+    return BOOST if _is_fav(g) else 1
+
+
+class _PluginSwrr:
+    """afl / nrl / soccer ``_swrr_advance``, transcribed verbatim."""
+
+    favorite_live_boost = BOOST
+
+    def _is_favorite_game(self, g):
+        return _is_fav(g)
+
+    def advance(self, games):
+        if not games:
+            return None
+        weights = {}
+        for g in games:
+            gid = g.get("id")
+            if gid is None:
+                continue
+            weights[gid] = self.favorite_live_boost if self._is_favorite_game(g) else 1
+        if not weights:
+            return None
+        if not hasattr(self, "_swrr_weights"):
+            self._swrr_weights = {}
+        self._swrr_weights = {
+            gid: w for gid, w in self._swrr_weights.items() if gid in weights}
+        for gid, w in weights.items():
+            self._swrr_weights[gid] = self._swrr_weights.get(gid, 0) + w
+        total_weight = sum(weights.values())
+        ids_in_order = [g.get("id") for g in games if g.get("id") in weights]
+        best_gid = max(ids_in_order, key=lambda gid: self._swrr_weights[gid])
+        self._swrr_weights[best_gid] -= total_weight
+        return next(g for g in games if g.get("id") == best_gid)
+
+
+def _plugin_weighted_schedule(games):
+    """football / baseball / basketball ``_build_weighted_schedule``, verbatim."""
+    if not games:
+        return []
+    weights = {g["id"]: (BOOST if _is_fav(g) else 1) for g in games}
+    total_weight = sum(weights.values())
+    if total_weight <= len(games):
+        return [g["id"] for g in games]
+    current_weight = {gid: 0 for gid in weights}
+    schedule = []
+    for _ in range(total_weight):
+        for gid in weights:
+            current_weight[gid] += weights[gid]
+        picked = max(current_weight, key=lambda gid: current_weight[gid])
+        current_weight[picked] -= total_weight
+        schedule.append(picked)
+    return schedule
+
+
+def _plugin_rotation_schedule(games):
+    """hockey ``_build_rotation_schedule``, transcribed verbatim."""
+    weights = [(g["id"], BOOST if _is_fav(g) else 1) for g in games]
+    total_weight = sum(w for _, w in weights)
+    if not weights or total_weight <= 0:
+        return [g["id"] for g in games]
+    current_weights = {gid: 0 for gid, _ in weights}
+    schedule = []
+    for _ in range(total_weight):
+        best_id, best_current = None, None
+        for gid, w in weights:
+            current_weights[gid] += w
+            if best_current is None or current_weights[gid] > best_current:
+                best_id, best_current = gid, current_weights[gid]
+        current_weights[best_id] -= total_weight
+        schedule.append(best_id)
+    return schedule
+
+
+def _cases():
+    """Every live-game shape up to 4 games: each either a favorite or not.
+
+    Exhaustive rather than random so the gate is deterministic — a rotation
+    regression must fail the same way on every run.
+    """
+    import itertools
+    for size in range(1, 5):
+        for flags in itertools.product(("FAV", "OTH"), repeat=size):
+            yield [game(f"g{i}", home=abbr) for i, abbr in enumerate(flags)]
+
+
+class TestMatchesThePluginImplementations:
+    """The promotion is only safe if these reproduce the plugin copies exactly.
+
+    B5 deletes the bundled copies on the strength of this: each core strategy is
+    checked against the verbatim source it replaces, over every live-game shape
+    up to four games.
+    """
+
+    @pytest.mark.parametrize("games", list(_cases()))
+    def test_swrr_matches_the_incremental_plugin_picker(self, games):
+        plugin = _PluginSwrr()
+        core = SmoothWeightedRotation(weight_for=_weight_for)
+        # 60 picks: long enough to cross many cycle boundaries, where a
+        # state-handling divergence would show up.
+        assert ([plugin.advance(games)["id"] for _ in range(60)]
+                == [core.next_game(games)["id"] for _ in range(60)])
+
+    @pytest.mark.parametrize("games", list(_cases()))
+    def test_weighted_matches_the_football_lineage(self, games):
+        assert (_plugin_weighted_schedule(games)
+                == WeightedCycleRotation(weight_for=_weight_for).schedule(games))
+
+    @pytest.mark.parametrize("games", list(_cases()))
+    def test_weighted_matches_hockeys_loop_shape(self, games):
+        assert (_plugin_rotation_schedule(games)
+                == WeightedCycleRotation(weight_for=_weight_for).schedule(games))
+
+
+# ---------------------------------------------------------------------------
+# Celebrations
+# ---------------------------------------------------------------------------
+
+class _FakeLive:
+    """Stand-in for SportsLive: just the surface the mixin touches."""
+
+    def __init__(self, mode_config=None, favorite_teams=None):
+        self.mode_config = mode_config or {}
+        self.favorite_teams = favorite_teams or []
+        self.logger = MagicMock()
+        self.display_manager = MagicMock()
+        self.is_enabled = True
+        self.current_game = None
+        self.last_game_switch = 0
+        self.display_calls = []
+
+    def _favorite_key(self, game, side):
+        return game.get(f"{side}_abbr")
+
+    def display(self, force_clear=False):
+        self.display_calls.append(force_clear)
+        return True
+
+
+class _Celebrating(CelebrationMixin, _FakeLive):
+    pass
+
+
+class _Coalescing(CelebrationMixin, _FakeLive):
+    COALESCE_SCORING_SEQUENCE = True
+
+    def score_phrase(self, points, team_abbr):
+        return "TOUCHDOWN!" if points >= 6 else f"{team_abbr} FIELD GOAL!"
+
+
+class _ById(CelebrationMixin, _FakeLive):
+    """The nrl shape: ambiguous abbreviations, so favorites match on team id."""
+
+    def _favorite_key(self, game, side):
+        return game.get(f"{side}_id")
+
+
+@pytest.fixture
+def celebrating():
+    def _build(cls=_Celebrating, mode_config=None, favorites=None):
+        return cls(mode_config=mode_config, favorite_teams=favorites)
+    return _build
+
+
+class TestOptOutIsStructural:
+    """The property the mixin design exists to buy: a class that does not opt in
+    has none of this code — not a disabled flag, not an unused attribute."""
+
+    def test_a_non_celebrating_class_has_no_celebration_surface(self):
+        plain = _FakeLive()
+        for attribute in ("active_celebration", "_score_baselines",
+                          "celebration_enabled", "celebration_duration",
+                          "_check_for_score", "_check_for_win",
+                          "has_active_celebration", "_draw_celebration_layout"):
+            assert not hasattr(plain, attribute), (
+                f"{attribute} leaked onto a class that never opted in")
+
+    def test_the_mixin_is_absent_from_a_non_celebrating_mro(self):
+        assert CelebrationMixin not in _FakeLive.__mro__
+        assert CelebrationMixin in _Celebrating.__mro__
+
+    def test_mixin_does_not_require_the_base_to_know_about_it(self):
+        """SportsLive must carry no celebration hooks — that would be the
+        god-class shape the mixin replaces."""
+        from src.base_classes.sports import SportsLive
+        source = __import__("inspect").getsource(SportsLive)
+        assert "celebration" not in source.lower()
+
+
+class TestCelebrationConfig:
+    def test_defaults(self, celebrating):
+        manager = celebrating()
+        assert manager.celebration_enabled is True
+        assert manager.celebration_duration == 8
+        assert manager.celebrate_opponent_scores is False
+        assert manager.active_celebration is None
+
+    def test_reads_the_goal_spelling_of_the_opponent_key(self, celebrating):
+        """The soccer lineage's published schema says `celebrate_opponent_goals`;
+        adopting the mixin must not silently reset users' setting."""
+        manager = celebrating(mode_config={"celebrate_opponent_goals": True})
+        assert manager.celebrate_opponent_scores is True
+
+    def test_reads_the_score_spelling_of_the_opponent_key(self, celebrating):
+        manager = celebrating(mode_config={"celebrate_opponent_scores": True})
+        assert manager.celebrate_opponent_scores is True
+
+    def test_score_spelling_wins_when_both_are_present(self, celebrating):
+        manager = celebrating(mode_config={"celebrate_opponent_scores": False,
+                                           "celebrate_opponent_goals": True})
+        assert manager.celebrate_opponent_scores is False
+
+
+class TestScoreDetection:
+    def test_first_sighting_never_celebrates(self, celebrating):
+        """A game already in progress at boot must not false-fire."""
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=3, away_score=1))
+        assert manager.active_celebration is None
+        assert manager._score_baselines["g1"] == {"away": 1, "home": 3}
+
+    def test_increment_arms_a_celebration(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=0, away_score=0))
+        manager._check_for_score(game("g1", home_score=1, away_score=0))
+        assert manager.active_celebration["kind"] == "score"
+        assert manager.active_celebration["scored_side"] == "home"
+
+    def test_no_change_does_not_fire(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=2))
+        manager._check_for_score(game("g1", home_score=2))
+        assert manager.active_celebration is None
+
+    def test_decrement_rebases_silently(self, celebrating):
+        """A disallowed goal / correction must not celebrate, and must not leave
+        a stale baseline that fires on the way back up."""
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=2))
+        manager._check_for_score(game("g1", home_score=1))
+        assert manager.active_celebration is None
+        assert manager._score_baselines["g1"]["home"] == 1
+
+    def test_disabled_never_fires(self, celebrating):
+        manager = celebrating(mode_config={"celebration_enabled": False})
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        assert manager.active_celebration is None
+
+    def test_game_without_an_id_is_ignored(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score({"home_score": 1, "away_score": 0})
+        assert manager.active_celebration is None
+
+    @pytest.mark.parametrize("score", [None, "", "not-a-number-at-all"])
+    def test_unusable_scores_are_ignored(self, celebrating, score):
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=score))
+        assert manager._score_baselines == {}
+
+    @pytest.mark.parametrize("raw,expected", [
+        ("7", 7), (7, 7), (7.0, 7), ("  7 ", 7), ("7 (SO)", 7),
+        ({"value": 7}, 7), ({"displayValue": "7"}, 7),
+    ])
+    def test_score_coercion(self, raw, expected):
+        assert CelebrationMixin._score_to_int(raw) == expected
+
+    def test_away_side_is_detected(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score(game("g1", away_score=0))
+        manager._check_for_score(game("g1", away_score=1))
+        assert manager.active_celebration["scored_side"] == "away"
+
+
+class TestWhoGetsCelebrated:
+    def test_no_favorites_celebrates_everyone(self, celebrating):
+        """The user opted to show this game at all, so any score in it counts."""
+        manager = celebrating(favorites=[])
+        manager._check_for_score(game("g1", home="XXX", home_score=0))
+        manager._check_for_score(game("g1", home="XXX", home_score=1))
+        assert manager.active_celebration is not None
+
+    def test_favorite_scores(self, celebrating):
+        manager = celebrating(favorites=["FAV"])
+        manager._check_for_score(game("g1", home="FAV", home_score=0))
+        manager._check_for_score(game("g1", home="FAV", home_score=1))
+        assert manager.active_celebration is not None
+
+    def test_opponent_suppressed_by_default(self, celebrating):
+        manager = celebrating(favorites=["FAV"])
+        manager._check_for_score(game("g1", home="OPP", away="FAV", home_score=0))
+        manager._check_for_score(game("g1", home="OPP", away="FAV", home_score=1))
+        assert manager.active_celebration is None
+
+    def test_opponent_celebrated_when_opted_in(self, celebrating):
+        manager = celebrating(mode_config={"celebrate_opponent_scores": True},
+                              favorites=["FAV"])
+        manager._check_for_score(game("g1", home="OPP", away="FAV", home_score=0))
+        manager._check_for_score(game("g1", home="OPP", away="FAV", home_score=1))
+        assert manager.active_celebration is not None
+
+    def test_matching_goes_through_the_favorite_key_seam(self, celebrating):
+        """nrl matches on team id because its abbreviations are ambiguous
+        ('NEW' is both Newcastle and New Zealand). Core must not care why."""
+        manager = celebrating(_ById, favorites=["g1-h"])
+        manager._check_for_score(game("g1", home="NEW", home_score=0))
+        manager._check_for_score(game("g1", home="NEW", home_score=1))
+        assert manager.active_celebration is not None
+
+    def test_favorite_key_seam_also_excludes(self, celebrating):
+        manager = celebrating(_ById, favorites=["someone-else"])
+        manager._check_for_score(game("g1", home="NEW", home_score=0))
+        manager._check_for_score(game("g1", home="NEW", home_score=1))
+        assert manager.active_celebration is None
+
+
+class TestPhrasing:
+    def test_default_phrase_is_sport_neutral(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score(game("g1", home="HOM", home_score=0))
+        manager._check_for_score(game("g1", home="HOM", home_score=1))
+        assert manager.active_celebration["phrase"] == "HOM SCORES!"
+
+    def test_score_phrase_hook_sees_the_points_delta(self, celebrating):
+        manager = celebrating(_Coalescing)
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=6))
+        assert manager.active_celebration["phrase"] == "TOUCHDOWN!"
+
+    def test_score_phrase_hook_distinguishes_smaller_plays(self, celebrating):
+        manager = celebrating(_Coalescing)
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=3))
+        assert manager.active_celebration["phrase"] == "HOM FIELD GOAL!"
+
+    def test_win_phrase(self, celebrating):
+        manager = celebrating(favorites=["HOM"])
+        manager._check_for_score(game("g1", home_score=1))
+        manager._check_for_win(game("g1", home_score=2, away_score=1))
+        assert manager.active_celebration["phrase"] == "HOM WINS!"
+
+
+class TestCoalescing:
+    def test_off_by_default_two_goals_are_two_celebrations(self, celebrating):
+        """Soccer/afl/nrl: consecutive increments are distinct events, so
+        suppressing the second would swallow a real goal."""
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        first = manager.active_celebration["started_at"]
+        manager._check_for_score(game("g1", home_score=2))
+        assert manager.active_celebration["started_at"] != first
+        assert manager.active_celebration["home_score"] == 2
+
+    def test_on_suppresses_the_extra_point_follow_up(self, celebrating):
+        """Football: a touchdown lands as +6, then +1 seconds later. One
+        takeover per scoring sequence."""
+        manager = celebrating(_Coalescing)
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=6))
+        armed = manager.active_celebration
+        manager._check_for_score(game("g1", home_score=7))
+        assert manager.active_celebration is armed
+
+    def test_suppression_still_advances_the_baseline(self, celebrating):
+        """Nothing may re-fire once the window closes."""
+        manager = celebrating(_Coalescing)
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=6))
+        manager._check_for_score(game("g1", home_score=7))
+        assert manager._score_baselines["g1"]["home"] == 7
+
+
+class TestWinDetection:
+    def test_win_requires_a_baseline(self, celebrating):
+        """A game seen for the first time already-final (board started after
+        full time) must not fire."""
+        manager = celebrating(favorites=["HOM"])
+        manager._check_for_win(game("g1", home_score=3, away_score=1))
+        assert manager.active_celebration is None
+
+    def test_win_fires_once_only(self, celebrating):
+        manager = celebrating(favorites=["HOM"])
+        manager._check_for_score(game("g1", home_score=1))
+        manager._check_for_win(game("g1", home_score=3, away_score=1))
+        manager.active_celebration = None
+        manager._check_for_win(game("g1", home_score=3, away_score=1))
+        assert manager.active_celebration is None
+
+    def test_draw_does_not_celebrate(self, celebrating):
+        manager = celebrating(favorites=["HOM"])
+        manager._check_for_score(game("g1", home_score=1))
+        manager._check_for_win(game("g1", home_score=2, away_score=2))
+        assert manager.active_celebration is None
+
+    def test_win_is_gated_strictly_on_favorites(self, celebrating):
+        """Unlike scores, a win with no favorites configured does NOT celebrate:
+        every game ends, so the fallback would be constant noise."""
+        manager = celebrating(favorites=[])
+        manager._check_for_score(game("g1", home_score=1))
+        manager._check_for_win(game("g1", home_score=3, away_score=1))
+        assert manager.active_celebration is None
+
+    def test_losing_favorite_does_not_celebrate(self, celebrating):
+        manager = celebrating(favorites=["HOM"])
+        manager._check_for_score(game("g1", home_score=1))
+        manager._check_for_win(game("g1", home_score=1, away_score=4))
+        assert manager.active_celebration is None
+
+    def test_away_favorite_wins(self, celebrating):
+        manager = celebrating(favorites=["AWY"])
+        manager._check_for_score(game("g1", away_score=1))
+        manager._check_for_win(game("g1", home_score=1, away_score=4))
+        assert manager.active_celebration["scored_side"] == "away"
+
+
+class TestCelebrationSnapshot:
+    def test_the_game_is_snapshotted_not_referenced(self, celebrating):
+        """A win must survive the game leaving live_games."""
+        manager = celebrating()
+        live = game("g1", home_score=0)
+        manager._check_for_score(live)
+        live = game("g1", home_score=1)
+        manager._check_for_score(live)
+        live["home_abbr"] = "MUTATED"
+        assert manager.active_celebration["game"]["home_abbr"] == "HOM"
+
+    def test_focus_is_pinned_to_the_involved_game(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        assert manager.current_game["id"] == "g1"
+
+
+class TestDisplayTakeover:
+    def test_no_celebration_defers_to_the_scorebug(self, celebrating):
+        manager = celebrating()
+        assert manager.display(force_clear=True) is True
+        assert manager.display_calls == [True]
+
+    def test_active_celebration_takes_over(self, celebrating):
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        manager._draw_celebration_layout = MagicMock()
+        assert manager.display() is True
+        assert manager.display_calls == [], "the scorebug must not also render"
+        manager._draw_celebration_layout.assert_called_once()
+
+    def test_expired_celebration_clears_and_defers(self, celebrating):
+        manager = celebrating(mode_config={"celebration_duration": 0})
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        assert manager.display() is True
+        assert manager.active_celebration is None
+        assert manager.display_calls == [False]
+
+    def test_expiry_resets_the_dwell_clock(self, celebrating):
+        """So the scorebug resumes on the scoring game for a full duration
+        before rotation can move on."""
+        manager = celebrating(mode_config={"celebration_duration": 0})
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        manager.display()
+        assert manager.last_game_switch > 0
+
+    def test_a_render_failure_falls_through_to_the_scorebug(self, celebrating):
+        """A broken celebration must never blank the display."""
+        manager = celebrating()
+        manager._check_for_score(game("g1", home_score=0))
+        manager._check_for_score(game("g1", home_score=1))
+        manager._draw_celebration_layout = MagicMock(side_effect=RuntimeError("boom"))
+        assert manager.display() is True
+        assert manager.display_calls == [False]
+
+    def test_disabled_manager_renders_nothing(self, celebrating):
+        manager = celebrating()
+        manager.is_enabled = False
+        assert manager.display() is False
+
+
+class TestFitFont:
+    def test_returns_the_first_font_that_fits(self, celebrating):
+        manager = celebrating()
+        draw = MagicMock()
+        draw.textlength.side_effect = [100, 20]
+        big, small = MagicMock(), MagicMock()
+        assert manager._fit_font(draw, "GOAL", 50, [big, small]) is small
+
+    def test_falls_back_to_the_smallest(self, celebrating):
+        manager = celebrating()
+        draw = MagicMock()
+        draw.textlength.return_value = 999
+        big, small = MagicMock(), MagicMock()
+        assert manager._fit_font(draw, "GOAL", 50, [big, small]) is small
+
+
+class TestCapabilityExports:
+    @pytest.mark.parametrize("name", [
+        "CelebrationMixin", "RotationStrategy", "SimpleRotation",
+        "SmoothWeightedRotation", "WeightedCycleRotation",
+        "get_rotation_strategy", "register_rotation_strategy",
+    ])
+    def test_public_name_is_importable(self, name):
+        """Plugins import these behind a guarded fallback; the names are the
+        contract."""
+        import src.base_classes.sports.capabilities as capabilities
+        assert hasattr(capabilities, name)
+
+    def test_rotation_strategy_base_requires_a_schedule(self):
+        with pytest.raises(NotImplementedError):
+            RotationStrategy().schedule([game("a")])

test/test_sports_core_promotions.py

@@ -0,0 +1,590 @@
+"""Tests for the methods promoted onto SportsCore from the nine bundled
+plugin copies of ``sports.py`` (phase B1 of docs/SPORTS_UNIFICATION.md).
+
+Three methods and their seams land here:
+
+- ``cleanup()`` — byte-identical in all nine copies. The tests pin the
+  ordering (session close, then caches, then the completion log) and the
+  deliberate *omission*: the process-wide background service must never be
+  shut down by one unloading plugin.
+- ``_get_layout_offset()`` — football's resolver-backed variant, with the
+  classic inline config read as the fallback used by every plugin that
+  doesn't hand core a ``_config_schema_path()``.
+- ``_load_custom_font_from_element_config()`` — baseball's body (the only
+  copy that handles BDF strikes correctly) under hockey's wider signature,
+  resolving font files through the ``_font_root()`` seam instead of the
+  process cwd.
+"""
+
+import ast
+import json
+import logging
+import os
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from PIL import Image, ImageFont
+
+# src.base_classes.sports transitively imports the hardware matrix driver;
+# stub it so these tests can import the sports base classes off-device.
+sys.modules.setdefault("rgbmatrix", MagicMock())
+
+from src.base_classes.sports import SportsCore
+
+LOGGER = logging.getLogger("test_sports_core_promotions")
+
+CORE_ROOT = Path(__file__).resolve().parents[1]
+FONTS_DIR = CORE_ROOT / "assets" / "fonts"
+TTF_NAME = "PressStart2P-Regular.ttf"
+BDF_NAME = "5x7.bdf"          # a BDF whose only valid strike is 7px
+BDF_NATIVE_SIZE = 7
+
+
+class _StubSports(SportsCore):
+    """Minimal concrete SportsCore — the abstract methods are never called
+    by anything under test here."""
+
+    def _fetch_data(self):
+        return None
+
+    def _extract_game_details(self, game_event):
+        return None
+
+
+@pytest.fixture
+def build(monkeypatch, tmp_path):
+    """Factory for real SportsCore instances: logo dir redirected to tmp and
+    the process-wide background service replaced with a MagicMock so the
+    tests can assert nothing ever calls it."""
+    monkeypatch.setattr(
+        SportsCore, "_initialize_logo_dir", lambda self, configured: tmp_path)
+    monkeypatch.setattr(
+        "src.base_classes.sports.core.get_background_service",
+        lambda *args, **kwargs: MagicMock())
+
+    def _build(config=None, cls=_StubSports):
+        display_manager = MagicMock()
+        display_manager.matrix.width = 128
+        display_manager.matrix.height = 32
+        display_manager.width = 128
+        display_manager.height = 32
+        display_manager.image = Image.new("RGB", (128, 32))
+        cache_manager = MagicMock()
+        cache_manager.cache_dir = str(tmp_path)
+        return cls(config if config is not None else {"timezone": "UTC"},
+                   display_manager, cache_manager, LOGGER, "nhl")
+
+    return _build
+
+
+def probe(config=None):
+    """Unbound-call stand-in for hosts we don't need a full instance for
+    (same pattern as make_probe in test_sports_base_characterization)."""
+    host = MagicMock()
+    host.logger = LOGGER
+    host.config = config if config is not None else {}
+    host._font_cache = {}
+    host._bdf_native_size_cache = {}
+    host._config_schema_path.return_value = None
+    host._font_root.side_effect = lambda: SportsCore._font_root(host)
+    host._resolve_font_path.side_effect = (
+        lambda name: SportsCore._resolve_font_path(host, name))
+    return host
+
+
+def offset(host, element, axis, default=0):
+    return SportsCore._get_layout_offset(host, element, axis, default)
+
+
+def load_font(host, *args, **kwargs):
+    return SportsCore._load_custom_font_from_element_config(host, *args, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# 1. cleanup()
+# ---------------------------------------------------------------------------
+
+class TestCleanup:
+    def test_closes_session_and_clears_all_caches(self, build):
+        manager = build()
+        session = MagicMock()
+        manager.session = session
+        manager._logo_cache["TB"] = object()
+        manager._font_cache[("PressStart2P-Regular.ttf", 8)] = object()
+        manager._bdf_native_size_cache["assets/fonts/5x7.bdf"] = 7
+
+        manager.cleanup()
+
+        session.close.assert_called_once_with()
+        assert manager._logo_cache == {}
+        # Promoted alongside the font loader: these hold PIL faces and are
+        # an unbounded leak across enable/disable cycles if never released.
+        assert manager._font_cache == {}
+        assert manager._bdf_native_size_cache == {}
+
+    def test_second_cleanup_is_a_noop(self, build):
+        manager = build()
+        manager.session = MagicMock()
+        manager._logo_cache["TB"] = object()
+        manager._font_cache[("x", 8)] = object()
+
+        manager.cleanup()
+        manager.cleanup()  # must not raise on already-released state
+
+        assert manager._logo_cache == {}
+        assert manager._font_cache == {}
+        assert manager._bdf_native_size_cache == {}
+        assert manager.session.close.call_count == 2
+
+    def test_does_not_shut_down_the_shared_background_service(self, build):
+        # get_background_service() hands out a PROCESS-WIDE singleton shared
+        # by every scoreboard. One plugin unloading must not stop background
+        # fetching for the other eight — cleanup() touches it not at all.
+        manager = build()
+        service = manager.background_service
+        manager.session = MagicMock()
+
+        manager.cleanup()
+
+        assert service.shutdown.called is False
+        assert service.stop.called is False
+        assert service.method_calls == [], (
+            "cleanup() called into the shared background service: "
+            f"{service.method_calls}")
+
+    def test_completion_is_logged_even_when_session_close_raises(self, build, caplog):
+        manager = build()
+        manager.session = MagicMock()
+        manager.session.close.side_effect = RuntimeError("socket already gone")
+        manager._logo_cache["TB"] = object()
+
+        with caplog.at_level(logging.DEBUG, logger=LOGGER.name):
+            manager.cleanup()
+
+        messages = [r.message for r in caplog.records]
+        assert any("Error closing session" in m for m in messages)
+        # Ordering is load-bearing: the caches still get cleared and the
+        # completion log still fires after a failed close.
+        assert manager._logo_cache == {}
+        assert any("cleanup completed" in m for m in messages)
+
+    def test_tolerates_missing_attributes(self):
+        # The hasattr guards exist so a partially constructed instance (an
+        # __init__ that raised) can still be cleaned up.
+        host = MagicMock(spec=["logger"])
+        host.logger = LOGGER
+        SportsCore.cleanup(host)
+
+
+# ---------------------------------------------------------------------------
+# 2. _get_layout_offset() + the _config_schema_path() seam
+# ---------------------------------------------------------------------------
+
+def layout_config(element, axis, value):
+    return {"customization": {"layout": {element: {axis: value}}}}
+
+
+class TestLayoutOffsetClassicPath:
+    """The default path: _config_schema_path() returns None, so offsets come
+    from the inline customization.layout read every plugin ships today."""
+
+    def test_config_schema_path_defaults_to_none(self, build):
+        manager = build()
+        assert manager._config_schema_path() is None
+
+    def test_reads_configured_int(self):
+        host = probe(layout_config("home_logo", "x_offset", 5))
+        assert offset(host, "home_logo", "x_offset") == 5
+
+    def test_float_is_truncated_to_int(self):
+        host = probe(layout_config("score", "y_offset", 2.9))
+        result = offset(host, "score", "y_offset")
+        assert result == 2 and isinstance(result, int)
+
+    def test_numeric_string_is_coerced(self):
+        host = probe(layout_config("score", "x_offset", "-3.5"))
+        assert offset(host, "score", "x_offset") == -3
+
+    def test_unconfigured_element_and_axis_use_default(self):
+        host = probe(layout_config("score", "x_offset", 5))
+        assert offset(host, "status_text", "x_offset", 7) == 7
+        assert offset(host, "score", "y_offset", -1) == -1
+        assert offset(probe(), "score", "x_offset", 4) == 4
+
+    def test_non_numeric_string_degrades_to_default(self):
+        host = probe(layout_config("score", "x_offset", "left"))
+        assert offset(host, "score", "x_offset", 3) == 3
+
+    def test_unsupported_type_degrades_to_default(self):
+        host = probe(layout_config("score", "x_offset", {"nested": 1}))
+        assert offset(host, "score", "x_offset", 2) == 2
+        host = probe(layout_config("score", "x_offset", None))
+        assert offset(host, "score", "x_offset", 2) == 2
+
+    def test_broken_config_object_degrades_to_default(self):
+        host = probe()
+        host.config = "not a dict"
+        assert offset(host, "score", "x_offset", 6) == 6
+
+    def test_boolean_counts_as_one(self):
+        # PINNED AS-IS: the classic read predates the resolver and treats a
+        # bool as its int value (True -> 1). See the resolver test below for
+        # the stricter, more correct handling.
+        host = probe(layout_config("score", "x_offset", True))
+        assert offset(host, "score", "x_offset", 4) == 1
+
+
+class TestLayoutOffsetResolverPath:
+    """When a plugin supplies its config_schema.json, offsets resolve through
+    src.element_style instead."""
+
+    @pytest.fixture
+    def schema_path(self, tmp_path):
+        path = tmp_path / "config_schema.json"
+        path.write_text(json.dumps({
+            "type": "object",
+            "properties": {
+                "customization": {
+                    "type": "object",
+                    "properties": {
+                        "layout": {"type": "object", "properties": {}},
+                    },
+                },
+            },
+        }))
+        return str(path)
+
+    def host(self, schema_path, config):
+        host = probe(config)
+        host._config_schema_path.return_value = schema_path
+        del host._style_resolver_cached  # MagicMock auto-attrs otherwise
+        host._style_resolver_cached = None
+        return host
+
+    def test_reads_configured_offsets(self, schema_path):
+        host = self.host(schema_path, layout_config("home_logo", "x_offset", 5))
+        assert offset(host, "home_logo", "x_offset") == 5
+
+    def test_numeric_string_is_coerced(self, schema_path):
+        host = self.host(schema_path, layout_config("score", "x_offset", "-3.5"))
+        assert offset(host, "score", "x_offset") == -3
+
+    def test_missing_value_uses_default(self, schema_path):
+        host = self.host(schema_path, layout_config("score", "x_offset", 5))
+        assert offset(host, "score", "y_offset", 9) == 9
+
+    def test_bad_input_degrades_to_default(self, schema_path):
+        host = self.host(schema_path, layout_config("score", "x_offset", "left"))
+        assert offset(host, "score", "x_offset", 3) == 3
+        host = self.host(schema_path, {"customization": {"layout": "nope"}})
+        assert offset(host, "score", "x_offset", 3) == 3
+
+    def test_boolean_is_rejected_unlike_the_classic_path(self, schema_path):
+        # The intended behavior difference: a bool is not a pixel offset, so
+        # the resolver returns the default where the classic read returns 1.
+        host = self.host(schema_path, layout_config("score", "x_offset", True))
+        assert offset(host, "score", "x_offset", 4) == 4
+
+    def test_resolver_is_cached_and_rebuilt_when_config_is_swapped(self, schema_path):
+        host = self.host(schema_path, layout_config("score", "x_offset", 5))
+        assert offset(host, "score", "x_offset") == 5
+        first = host._style_resolver_cached
+        assert offset(host, "score", "x_offset") == 5
+        assert host._style_resolver_cached is first
+
+        # on_config_change swaps the dict object; the resolver must follow.
+        host.config = layout_config("score", "x_offset", 11)
+        assert offset(host, "score", "x_offset") == 11
+        assert host._style_resolver_cached is not first
+
+    def test_missing_schema_file_still_resolves_offsets(self, tmp_path):
+        # Offsets don't depend on schema defaults, so an unreadable schema
+        # must not cost the plugin its layout customization.
+        host = self.host(str(tmp_path / "absent.json"),
+                         layout_config("score", "x_offset", 5))
+        assert offset(host, "score", "x_offset") == 5
+
+
+# ---------------------------------------------------------------------------
+# 3. _load_custom_font_from_element_config() + the _font_root() seam
+# ---------------------------------------------------------------------------
+
+class TestFontRootSeam:
+    def test_default_font_root_is_the_core_install_root(self, build):
+        manager = build()
+        assert Path(manager._font_root()) == CORE_ROOT
+        assert (Path(manager._font_root()) / "assets" / "fonts").is_dir()
+
+    def test_resolve_font_path_honors_an_overridden_root(self, tmp_path):
+        fonts = tmp_path / "assets" / "fonts"
+        fonts.mkdir(parents=True)
+        (fonts / "Bundled.ttf").write_bytes(b"not really a font")
+        host = probe()
+        host._font_root.side_effect = lambda: str(tmp_path)
+        assert SportsCore._resolve_font_path(host, "Bundled.ttf") == str(
+            fonts / "Bundled.ttf")
+
+    def test_unknown_font_returns_the_familiar_relative_path(self):
+        host = probe()
+        assert SportsCore._resolve_font_path(host, "Nope.ttf") == os.path.join(
+            "assets", "fonts", "Nope.ttf")
+
+
+class TestFontLoaderSignature:
+    """Hockey's signature is the only safe superset: basketball's positional
+    ``default_font: str`` blows up on an explicit None."""
+
+    def test_two_arg_call(self):
+        font = load_font(probe(), {"font": TTF_NAME, "font_size": 10})
+        assert isinstance(font, ImageFont.FreeTypeFont)
+        assert font.size == 10
+
+    def test_default_size_is_used_when_config_omits_it(self):
+        assert load_font(probe(), {}, 12).size == 12
+
+    def test_three_positional_args(self):
+        font = load_font(probe(), {}, 6, "4x6-font.ttf")
+        assert isinstance(font, ImageFont.FreeTypeFont)
+        assert font.size == 6
+        assert font.path.endswith("4x6-font.ttf")
+
+    def test_explicit_default_font_none(self):
+        # The regression this signature guards: os.path.join(..., None).
+        font = load_font(probe(), {"font_size": 9}, default_font=None)
+        assert isinstance(font, ImageFont.FreeTypeFont)
+        assert font.path.endswith(TTF_NAME)
+
+    def test_config_font_wins_over_default_font(self):
+        font = load_font(probe(), {"font": TTF_NAME}, 8, "4x6-font.ttf")
+        assert font.path.endswith(TTF_NAME)
+
+    def test_string_font_size_is_coerced(self):
+        assert load_font(probe(), {"font": TTF_NAME, "font_size": "11"}).size == 11
+
+
+class TestFontLoaderBehavior:
+    def test_family_alias_resolves_through_the_font_manager_catalog(self):
+        # "press_start" is a FontManager catalog family, not a filename; the
+        # promoted loader must not carry its own duplicate alias table.
+        host = probe()
+        font = load_font(host, {"font": "press_start", "font_size": 8})
+        assert font.path.endswith(TTF_NAME)
+        assert ("PressStart2P-Regular.ttf", 8) in host._font_cache
+
+    def test_memo_cache_returns_the_same_face(self):
+        host = probe()
+        first = load_font(host, {"font": TTF_NAME, "font_size": 8})
+        second = load_font(host, {"font": TTF_NAME, "font_size": 8})
+        assert first is second
+        assert len(host._font_cache) == 1
+        # A different size is a different face.
+        assert load_font(host, {"font": TTF_NAME, "font_size": 9}) is not first
+        assert len(host._font_cache) == 2
+
+    def test_bdf_loads_at_its_native_strike_when_the_request_misses(self):
+        # BDF is a fixed-size bitmap format: FreeType raises "invalid pixel
+        # size" for anything but the file's own strike. Baseball's retry is
+        # the only copy that gets this right.
+        host = probe()
+        font = load_font(host, {"font": BDF_NAME, "font_size": 8})
+        assert isinstance(font, ImageFont.FreeTypeFont)
+        assert font.size == BDF_NATIVE_SIZE
+        assert font.path.endswith(BDF_NAME)
+        assert set(host._bdf_native_size_cache.values()) == {BDF_NATIVE_SIZE}
+        # The retried face is memoized under the REQUESTED size.
+        assert host._font_cache[(BDF_NAME, 8)] is font
+
+    def test_bdf_at_its_native_size_needs_no_retry(self):
+        host = probe()
+        font = load_font(host, {"font": BDF_NAME, "font_size": BDF_NATIVE_SIZE})
+        assert font.size == BDF_NATIVE_SIZE
+        assert host._bdf_native_size_cache == {}
+
+    def test_bdf_strike_lookup_is_memoized(self, monkeypatch):
+        calls = []
+        real = SportsCore.__module__
+
+        def counting(path):
+            calls.append(path)
+            from src.font_manager import FontManager
+            return FontManager._read_bdf_native_size(path)
+
+        monkeypatch.setattr(f"{real}._read_bdf_native_size", counting)
+        host = probe()
+        load_font(host, {"font": BDF_NAME, "font_size": 8})
+        host._font_cache.clear()  # force the load path again
+        load_font(host, {"font": BDF_NAME, "font_size": 8})
+        assert len(calls) == 1
+
+    def test_missing_font_falls_back_and_caches_the_fallback(self, caplog):
+        host = probe()
+        with caplog.at_level(logging.WARNING, logger=LOGGER.name):
+            font = load_font(host, {"font": "DoesNotExist.ttf", "font_size": 8})
+        assert isinstance(font, ImageFont.FreeTypeFont)
+        assert font.path.endswith(TTF_NAME)
+        assert any("Font file not found" in r.message for r in caplog.records)
+        # Cached under the requested name so a misconfiguration costs one
+        # disk probe, not one per frame.
+        assert host._font_cache[("DoesNotExist.ttf", 8)] is font
+
+    def test_unknown_extension_falls_back(self):
+        host = probe()
+        font = load_font(host, {"font": "AUTHORS", "font_size": 8})
+        assert font.path.endswith(TTF_NAME)
+
+    def test_fallback_honors_the_supplied_default_font(self):
+        host = probe()
+        font = load_font(host, {"font": "DoesNotExist.ttf"}, 6, "4x6-font.ttf")
+        assert font.path.endswith("4x6-font.ttf")
+
+
+class TestFontLoaderCwdIndependence:
+    """The bug the _font_root() seam exists to prevent: every plugin copy
+    joins 'assets/fonts' onto the process cwd, so a process started anywhere
+    else silently degrades to PIL's default bitmap face (the same defect
+    already fixed in FontManager — see CHANGELOG Unreleased/Fixed)."""
+
+    @pytest.mark.parametrize("font_name,expected_size",
+                             [(TTF_NAME, 8), (BDF_NAME, BDF_NATIVE_SIZE)])
+    def test_fonts_load_from_an_unrelated_cwd(self, monkeypatch, font_name,
+                                              expected_size):
+        monkeypatch.chdir("/")
+        host = probe()
+        font = load_font(host, {"font": font_name, "font_size": 8})
+        assert isinstance(font, ImageFont.FreeTypeFont), (
+            f"{font_name} degraded to PIL's default face when the process "
+            "runs outside the install root")
+        assert font.size == expected_size
+        assert Path(font.path) == FONTS_DIR / font_name
+
+    def test_fallback_font_also_survives_an_unrelated_cwd(self, monkeypatch):
+        monkeypatch.chdir("/")
+        font = load_font(probe(), {"font": "DoesNotExist.ttf", "font_size": 8})
+        assert isinstance(font, ImageFont.FreeTypeFont)
+        assert Path(font.path) == FONTS_DIR / TTF_NAME
+
+    @pytest.mark.parametrize("key", ["score", "time", "team", "status",
+                                     "detail", "rank"])
+    def test_load_fonts_survives_an_unrelated_cwd(self, monkeypatch, key):
+        """`_load_fonts` had the same cwd-relative literals the seam exists to
+        remove; every scoreboard font silently became PIL's default bitmap face
+        when the process started outside the install root."""
+        monkeypatch.chdir("/")
+        fonts = SportsCore._load_fonts(probe())
+        assert isinstance(fonts[key], ImageFont.FreeTypeFont), (
+            f"fonts['{key}'] degraded to PIL's default face outside the "
+            "install root")
+
+
+class TestShouldLogCooldown:
+    """`_should_log` reads `self._last_warning_time` unguarded, so it must be
+    initialized in __init__ — otherwise the first warning of a run raises
+    AttributeError instead of logging."""
+
+    def test_cooldown_clock_is_initialized(self, build):
+        assert build()._last_warning_time == 0
+
+    def test_first_call_logs_then_cools_down(self, build):
+        manager = build()
+        assert manager._should_log("api", cooldown=60) is True
+        assert manager._should_log("api", cooldown=60) is False
+
+    def test_cooldown_expires(self, build):
+        manager = build()
+        assert manager._should_log("api", cooldown=60) is True
+        manager._last_warning_time -= 61
+        assert manager._should_log("api", cooldown=60) is True
+
+
+# ---------------------------------------------------------------------------
+# 4. Seam guard rails
+# ---------------------------------------------------------------------------
+
+class TestPromotedSeamsExist:
+    @pytest.mark.parametrize("name", [
+        "cleanup", "_get_layout_offset", "_load_custom_font_from_element_config",
+        "_config_schema_path", "_font_root", "_resolve_font_path",
+    ])
+    def test_method_is_callable_on_the_base_class(self, name):
+        assert callable(getattr(SportsCore, name, None)), (
+            f"SportsCore.{name} is part of the promoted plugin-facing seam "
+            "(docs/SPORTS_UNIFICATION.md) — plugins probe for it with "
+            "hasattr before delegating.")
+
+    def test_no_sport_names_leaked_into_core(self):
+        """core.py must never branch on which sport it is (prose and skin-id
+        examples in docstrings are fine — executable code is not)."""
+        tree = ast.parse((CORE_ROOT / "src" / "base_classes" / "sports"
+                          / "core.py").read_text())
+        docstrings = set()
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef,
+                                 ast.AsyncFunctionDef)):
+                first = node.body[0] if node.body else None
+                if (isinstance(first, ast.Expr)
+                        and isinstance(first.value, ast.Constant)
+                        and isinstance(first.value.value, str)):
+                    docstrings.add(id(first.value))
+
+        tokens = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                if id(node) not in docstrings:
+                    tokens.append(node.value)
+            elif isinstance(node, ast.Name):
+                tokens.append(node.id)
+            elif isinstance(node, ast.Attribute):
+                tokens.append(node.attr)
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef,
+                                   ast.ClassDef)):
+                tokens.append(node.name)
+
+        haystack = " ".join(tokens).lower()
+        for sport in ("afl", "nrl", "hockey", "baseball", "basketball",
+                      "football", "lacrosse", "soccer", "ufc"):
+            assert sport not in haystack, (
+                f"core.py code mentions '{sport}' — core must never learn "
+                "sport names; add an override point instead.")
+
+
+class TestInstallRootResolution:
+    """Guards the depth bug the sports.py -> package move introduced.
+
+    The move was byte-identical in every class body, but `__file__` gained a
+    directory, so `Path(__file__).resolve().parents[2]` silently changed from
+    the repo root to `<root>/src`. Textual identity is not semantic identity
+    when code measures its own location: these tests assert the resolved
+    values, not the index.
+    """
+
+    def test_install_root_is_the_repo_root(self):
+        from src.base_classes.sports.core import _INSTALL_ROOT
+
+        # The repo root is the directory that actually holds src/ and assets/.
+        assert (_INSTALL_ROOT / "src").is_dir()
+        assert (_INSTALL_ROOT / "src" / "base_classes" / "sports").is_dir()
+        assert _INSTALL_ROOT.name != "src", (
+            "_INSTALL_ROOT resolved to src/ — the parents[] depth is off by "
+            "one, which is exactly the regression the package move caused.")
+
+    def test_resolve_project_path_roots_at_repo_not_src(self):
+        from src.base_classes.sports.core import SportsCore, _INSTALL_ROOT
+
+        resolved = SportsCore._resolve_project_path(None, Path("assets/fonts"))
+        assert resolved == _INSTALL_ROOT / "assets" / "fonts"
+        assert "src" not in resolved.relative_to(_INSTALL_ROOT).parts
+
+    def test_absolute_paths_pass_through_unchanged(self):
+        from src.base_classes.sports.core import SportsCore
+
+        absolute = Path("/tmp/some/logo/dir")
+        assert SportsCore._resolve_project_path(None, absolute) == absolute
+
+    def test_font_root_and_project_path_share_one_anchor(self):
+        """Both consumers must derive from the same constant, so a future
+        move needs exactly one line changed rather than two."""
+        from src.base_classes.sports.core import SportsCore, _INSTALL_ROOT
+
+        assert SportsCore._font_root(None) == str(_INSTALL_ROOT)

test/test_sports_modes_promotions.py

@@ -0,0 +1,585 @@
+"""Tests for the methods promoted onto SportsUpcoming / SportsRecent /
+SportsLive from the nine plugin copies (phase B1 of the sports unification;
+see docs/SPORTS_UNIFICATION.md).
+
+Covered promotions:
+- SportsRecent: `_get_zero_clock_duration` / `_clear_zero_clock_tracking`
+  (+ the `_zero_clock_timestamps` initializer).
+- SportsLive: `_is_game_really_over` / `_detect_stale_games`
+  (+ `game_update_timestamps` / `stale_game_timeout`, and the
+  `FINAL_PERIOD` / `CLOCK_COUNTS_DOWN` class attributes).
+- SportsUpcoming: `_select_games_for_display`.
+- SportsRecent: `_select_recent_games_for_display`.
+
+The live pair is the risk centre: `_detect_stale_games` is the only caller
+that *removes* games, so `_is_game_really_over` returning a false positive
+silently drops a live game from the display. The canonical form deliberately
+declines to treat a missing clock as 0:00 — the plugin variant that did so
+dropped clockless sports (baseball) from the FINAL_PERIOD-th period onward.
+That regression is pinned by
+`test_missing_clock_at_late_period_is_not_over`.
+"""
+
+import logging
+import sys
+import time
+from datetime import datetime, timezone
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+from freezegun import freeze_time
+from PIL import Image
+
+# src.base_classes.sports transitively imports the hardware matrix driver;
+# stub it so these tests can import the sports base classes off-device.
+sys.modules.setdefault("rgbmatrix", MagicMock())
+
+from src.base_classes.hockey import Hockey, HockeyLive
+from src.base_classes.sports import (
+    SportsCore,
+    SportsLive,
+    SportsRecent,
+    SportsUpcoming,
+)
+
+
+# ---------------------------------------------------------------------------
+# Harnesses
+# ---------------------------------------------------------------------------
+
+class _UpcomingHarness(Hockey, SportsUpcoming):
+    """Cheapest concrete SportsUpcoming: hockey extractor + cache-fed data.
+
+    `_favorite_key` is inherited from SportsCore — these harnesses
+    deliberately do NOT define it, so the selection tests exercise the real
+    seam rather than a local stand-in.
+    """
+
+    def _fetch_data(self):
+        return None
+
+
+class _RecentHarness(Hockey, SportsRecent):
+    def _fetch_data(self):
+        return None
+
+
+class _LiveHarness(HockeyLive):
+    def _fetch_data(self):
+        return None
+
+
+class _ThreePeriodLiveHarness(_LiveHarness):
+    """Hockey-shaped: regulation ends after period 3."""
+
+    FINAL_PERIOD = 3
+
+
+class _CountUpLiveHarness(_LiveHarness):
+    """Soccer/AFL/NRL-shaped: the clock counts up, so 0:00 is kickoff."""
+
+    CLOCK_COUNTS_DOWN = False
+
+
+class _IdFavoriteUpcomingHarness(_UpcomingHarness):
+    """NRL-shaped: abbreviations are ambiguous, so favorites match on team id."""
+
+    def _favorite_key(self, game, side):
+        team_id = game.get(f"{side}_id")
+        return str(team_id) if team_id is not None else None
+
+
+class _IdFavoriteRecentHarness(_RecentHarness):
+    def _favorite_key(self, game, side):
+        team_id = game.get(f"{side}_id")
+        return str(team_id) if team_id is not None else None
+
+
+@pytest.fixture
+def build_manager(monkeypatch, tmp_path):
+    """Factory for concrete sports managers: mocked display/cache managers,
+    logo dir redirected to tmp, background service stubbed, and the requests
+    session rigged to prove nothing hits the network."""
+    monkeypatch.setattr(
+        SportsCore, "_initialize_logo_dir", lambda self, configured: tmp_path)
+    monkeypatch.setattr(
+        "src.base_classes.sports.core.get_background_service",
+        lambda *args, **kwargs: MagicMock())
+
+    def build(cls, **mode_cfg):
+        config = {
+            "timezone": "UTC",
+            "display": {},
+            "nhl_scoreboard": {"enabled": True, **mode_cfg},
+        }
+        display_manager = MagicMock()
+        display_manager.matrix.width = 128
+        display_manager.matrix.height = 32
+        display_manager.width = 128
+        display_manager.height = 32
+        display_manager.image = Image.new("RGB", (128, 32))
+        cache_manager = MagicMock()
+        cache_manager.get.return_value = None
+        cache_manager.cache_dir = str(tmp_path)
+        manager = cls(config, display_manager, cache_manager,
+                      logging.getLogger("test_sports_modes_promotions"),
+                      "nhl")
+        manager.session = MagicMock()
+        manager.session.get.side_effect = requests.exceptions.ConnectionError(
+            "promotion tests are offline")
+        return manager
+
+    return build
+
+
+def game(game_id="1", home="BOS", away="TOR", start=None, home_id=None,
+         away_id=None, **extra):
+    g = {
+        "id": game_id,
+        "home_abbr": home,
+        "away_abbr": away,
+        "home_id": home_id,
+        "away_id": away_id,
+        "start_time_utc": start,
+    }
+    g.update(extra)
+    return g
+
+
+def at(day, hour=12):
+    return datetime(2026, 1, day, hour, tzinfo=timezone.utc)
+
+
+def _ids(games):
+    return [g["id"] for g in games]
+
+
+# ---------------------------------------------------------------------------
+# Tier 1 — zero-clock tracking (SportsRecent)
+# ---------------------------------------------------------------------------
+
+class TestZeroClockTracking:
+    def test_initializer_present_and_empty(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        assert manager._zero_clock_timestamps == {}
+
+    def test_first_call_returns_zero_and_starts_tracking(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        assert manager._get_zero_clock_duration("g1") == 0.0
+        assert "g1" in manager._zero_clock_timestamps
+
+    def test_subsequent_call_returns_elapsed_seconds(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        with freeze_time("2026-01-20 12:00:00") as frozen:
+            assert manager._get_zero_clock_duration("g1") == 0.0
+            frozen.tick(45)
+            assert manager._get_zero_clock_duration("g1") == pytest.approx(45.0)
+            frozen.tick(15)
+            assert manager._get_zero_clock_duration("g1") == pytest.approx(60.0)
+
+    def test_tracking_is_per_game(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        with freeze_time("2026-01-20 12:00:00") as frozen:
+            manager._get_zero_clock_duration("g1")
+            frozen.tick(30)
+            assert manager._get_zero_clock_duration("g2") == 0.0
+            assert manager._get_zero_clock_duration("g1") == pytest.approx(30.0)
+
+    def test_clear_resets_tracking(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        with freeze_time("2026-01-20 12:00:00") as frozen:
+            manager._get_zero_clock_duration("g1")
+            frozen.tick(30)
+            manager._clear_zero_clock_tracking("g1")
+            assert "g1" not in manager._zero_clock_timestamps
+            # Restarts from zero after clearing.
+            assert manager._get_zero_clock_duration("g1") == 0.0
+
+    def test_clear_unknown_game_is_a_noop(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        manager._clear_zero_clock_tracking("never-seen")  # must not raise
+        assert manager._zero_clock_timestamps == {}
+
+
+# ---------------------------------------------------------------------------
+# Tier 2a — _is_game_really_over (SportsLive)
+# ---------------------------------------------------------------------------
+
+class TestIsGameReallyOver:
+    def test_missing_clock_at_late_period_is_not_over(self, build_manager):
+        """THE baseball regression: no `clock` key at all, period 7.
+
+        The rejected variant coerced a missing clock to the literal "0:00" and
+        declared the game over — dropping every MLB game from the 5th inning
+        onward, since baseball has no game clock and `period` is the inning.
+        A missing clock must fail safe.
+        """
+        manager = build_manager(_LiveHarness)
+        g = game(period=7, period_text="Top 7th")
+        assert "clock" not in g
+        assert manager._is_game_really_over(g) is False
+
+    def test_none_clock_at_late_period_is_not_over(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock=None, period=7, period_text="Top 7th")) is False
+
+    def test_non_string_clock_at_late_period_is_not_over(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock=0, period=9, period_text="Bot 9th")) is False
+
+    def test_blank_clock_at_late_period_is_not_over(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="   ", period=5, period_text="5th")) is False
+
+    @pytest.mark.parametrize("period_text", ["Final", "final", "Final/OT",
+                                             "FINAL", "Final - SO"])
+    def test_final_period_text_is_over(self, build_manager, period_text):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="12:00", period=2, period_text=period_text)) is True
+
+    def test_none_period_text_does_not_raise(self, build_manager):
+        """All nine plugin copies called `.lower()` on `game.get("period_text", "")`,
+        which is None when the key is present-but-None; `_detect_stale_games`
+        has no try/except around the call."""
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="12:00", period=2, period_text=None)) is False
+
+    def test_missing_period_text_does_not_raise(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(game(clock="12:00", period=2)) is False
+
+    @pytest.mark.parametrize(
+        "clock", ["0:00", ":00", "00", "000", " 0:00 ", "00:00", "0", "0000"])
+    def test_expired_clock_at_final_period_is_over(self, build_manager, clock):
+        """Every spelling of a zeroed clock counts, not a hand-listed few.
+
+        "00:00" is the one that motivated comparing numerically: it normalizes
+        to "0000", which matched none of the literals the plugin copies listed,
+        so a two-digit-minute expired clock kept the game on screen forever.
+        """
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock=clock, period=4, period_text="Q4")) is True
+
+    def test_none_period_at_expired_clock_does_not_raise(self, build_manager):
+        """`period` present-but-None: `None >= FINAL_PERIOD` is a TypeError, and
+        `_detect_stale_games` has no try/except — the same failure shape as the
+        `period_text` case above."""
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="0:00", period=None, period_text="Q4")) is False
+
+    def test_none_period_with_running_clock_does_not_raise(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="8:12", period=None, period_text="Q2")) is False
+
+    def test_expired_clock_after_final_period_is_over(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="0:00", period=5, period_text="OT")) is True
+
+    def test_expired_clock_before_final_period_is_not_over(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="0:00", period=3, period_text="Q3")) is False
+
+    @pytest.mark.parametrize("clock", [":40", "0:40", "1:00"])
+    def test_running_clock_is_not_over(self, build_manager, clock):
+        """Sub-minute clocks like ':40' are legitimate, not expired."""
+        manager = build_manager(_LiveHarness)
+        assert manager._is_game_really_over(
+            game(clock=clock, period=4, period_text="Q4")) is False
+
+    def test_defaults_are_four_period_countdown(self):
+        assert SportsLive.FINAL_PERIOD == 4
+        assert SportsLive.CLOCK_COUNTS_DOWN is True
+
+    def test_final_period_override_three(self, build_manager):
+        """Hockey-shaped subclass: regulation ends after period 3."""
+        manager = build_manager(_ThreePeriodLiveHarness)
+        assert manager.FINAL_PERIOD == 3
+        assert manager._is_game_really_over(
+            game(clock="0:00", period=3, period_text="P3")) is True
+        assert manager._is_game_really_over(
+            game(clock="0:00", period=2, period_text="P2")) is False
+        # And the unmodified default still requires period 4.
+        assert build_manager(_LiveHarness)._is_game_really_over(
+            game(clock="0:00", period=3, period_text="P3")) is False
+
+    def test_count_up_clock_never_expires(self, build_manager):
+        """Soccer/AFL/NRL: 0:00 means kickoff, so the clock branch must not run."""
+        manager = build_manager(_CountUpLiveHarness)
+        assert manager.CLOCK_COUNTS_DOWN is False
+        for period in (1, 2, 4, 9):
+            assert manager._is_game_really_over(
+                game(clock="0:00", period=period, period_text="1st Half")) is False
+
+    def test_count_up_clock_still_honors_final_text(self, build_manager):
+        manager = build_manager(_CountUpLiveHarness)
+        assert manager._is_game_really_over(
+            game(clock="0:00", period=2, period_text="Final")) is True
+
+
+# ---------------------------------------------------------------------------
+# Tier 2b — _detect_stale_games (SportsLive)
+# ---------------------------------------------------------------------------
+
+class TestDetectStaleGames:
+    def test_initializer_defaults(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        assert manager.game_update_timestamps == {}
+        assert manager.stale_game_timeout == 300
+
+    def test_stale_timeout_is_configurable(self, build_manager):
+        manager = build_manager(_LiveHarness, stale_game_timeout=42)
+        assert manager.stale_game_timeout == 42
+
+    def test_mutates_caller_list_in_place_and_returns_none(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        fresh = game("1", period_text="P2", clock="10:00", period=2)
+        over = game("2", period_text="Final", clock="0:00", period=3)
+        games = [fresh, over]
+        original = games
+
+        result = manager._detect_stale_games(games)
+
+        assert result is None
+        assert games is original  # same object, mutated in place
+        assert _ids(games) == ["1"]
+
+    def test_evicts_only_past_timeout_games(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        with freeze_time("2026-01-20 12:00:00"):
+            now = time.time()
+            manager.game_update_timestamps = {
+                "1": {"last_seen": now - 10},    # fresh
+                "2": {"last_seen": now - 299},   # just inside the timeout
+                "3": {"last_seen": now - 301},   # past the timeout
+            }
+            games = [game("1", period_text="P1", clock="10:00", period=1),
+                     game("2", period_text="P1", clock="10:00", period=1),
+                     game("3", period_text="P1", clock="10:00", period=1)]
+            manager._detect_stale_games(games)
+
+        assert _ids(games) == ["1", "2"]
+        assert "3" not in manager.game_update_timestamps
+        assert set(manager.game_update_timestamps) == {"1", "2"}
+
+    def test_unknown_last_seen_is_never_stale(self, build_manager):
+        """last_seen == 0 (or no entry) means 'never recorded', not 'ancient'."""
+        manager = build_manager(_LiveHarness)
+        games = [game("1", period_text="P1", clock="10:00", period=1),
+                 game("2", period_text="P1", clock="10:00", period=1)]
+        manager.game_update_timestamps = {"1": {"last_seen": 0}}
+        manager._detect_stale_games(games)
+        assert _ids(games) == ["1", "2"]
+
+    def test_removes_games_that_are_really_over(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        manager.game_update_timestamps = {"2": {"last_seen": 0}}
+        games = [game("1", period_text="Q2", clock="5:00", period=2),
+                 game("2", period_text="Final", clock="0:00", period=4)]
+        manager._detect_stale_games(games)
+        assert _ids(games) == ["1"]
+        assert "2" not in manager.game_update_timestamps
+
+    def test_keeps_clockless_late_game(self, build_manager):
+        """The end-to-end form of the baseball regression: a clockless game in
+        the 7th must survive the removal path."""
+        manager = build_manager(_LiveHarness)
+        games = [game("mlb-1", period=7, period_text="Top 7th")]
+        manager._detect_stale_games(games)
+        assert _ids(games) == ["mlb-1"]
+
+    def test_games_without_id_are_skipped(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        no_id = {"home_abbr": "BOS", "away_abbr": "TOR",
+                 "period_text": "Final", "clock": "0:00", "period": 4}
+        games = [no_id]
+        manager._detect_stale_games(games)
+        # `continue` fires before the "really over" check, so it stays.
+        assert games == [no_id]
+
+    def test_empty_list_is_tolerated(self, build_manager):
+        manager = build_manager(_LiveHarness)
+        games = []
+        assert manager._detect_stale_games(games) is None
+        assert games == []
+
+    def test_removal_is_by_value_not_identity(self, build_manager):
+        """Sharp edge worth pinning: `list.remove` compares with `dict.__eq__`,
+        so two structurally-equal dicts drop the FIRST occurrence."""
+        manager = build_manager(_LiveHarness)
+        first = game("1", period_text="Final", clock="0:00", period=4)
+        twin = dict(first)
+        games = [first, twin]
+        manager._detect_stale_games(games)
+        # Both entries are removed here (two iterations, two removals), but the
+        # first removal deletes `first`, not the dict being iterated.
+        assert games == []
+
+
+# ---------------------------------------------------------------------------
+# Tier 3a — _select_games_for_display (SportsUpcoming)
+# ---------------------------------------------------------------------------
+
+class TestSelectGamesForDisplay:
+    def test_no_favorites_returns_all_sorted_ascending(self, build_manager):
+        manager = build_manager(_UpcomingHarness)
+        games = [game("late", start=at(20)), game("early", start=at(10)),
+                 game("mid", start=at(15))]
+        assert _ids(manager._select_games_for_display(games, [])) == [
+            "early", "mid", "late"]
+
+    def test_missing_start_time_sorts_last(self, build_manager):
+        manager = build_manager(_UpcomingHarness)
+        games = [game("none", start=None), game("early", start=at(10))]
+        assert _ids(manager._select_games_for_display(games, [])) == [
+            "early", "none"]
+
+    def test_filters_to_favorite_teams(self, build_manager):
+        manager = build_manager(_UpcomingHarness)
+        games = [game("1", home="BOS", away="TOR", start=at(10)),
+                 game("2", home="NYR", away="PIT", start=at(11)),
+                 game("3", home="MTL", away="BOS", start=at(12))]
+        assert _ids(manager._select_games_for_display(games, ["BOS"])) == ["1", "3"]
+
+    def test_respects_upcoming_games_to_show_per_team(self, build_manager):
+        manager = build_manager(_UpcomingHarness, upcoming_games_to_show=2)
+        games = [game(str(i), home="BOS", away="TOR", start=at(10 + i))
+                 for i in range(5)]
+        assert _ids(manager._select_games_for_display(games, ["BOS"])) == ["0", "1"]
+
+    def test_game_between_two_favorites_counts_for_both(self, build_manager):
+        manager = build_manager(_UpcomingHarness, upcoming_games_to_show=1)
+        games = [game("shared", home="BOS", away="TOR", start=at(10)),
+                 game("bos2", home="BOS", away="NYR", start=at(11)),
+                 game("tor2", home="TOR", away="PIT", start=at(12))]
+        # "shared" fills both BOS's and TOR's single slot, so nothing else fits.
+        assert _ids(manager._select_games_for_display(
+            games, ["BOS", "TOR"])) == ["shared"]
+
+    def test_deduplicates_by_game_id(self, build_manager):
+        manager = build_manager(_UpcomingHarness, upcoming_games_to_show=5)
+        g = game("dupe", home="BOS", away="TOR", start=at(10))
+        assert _ids(manager._select_games_for_display(
+            [g, dict(g)], ["BOS"])) == ["dupe"]
+
+    def test_non_favorite_games_excluded(self, build_manager):
+        manager = build_manager(_UpcomingHarness)
+        games = [game("1", home="NYR", away="PIT", start=at(10))]
+        assert manager._select_games_for_display(games, ["BOS"]) == []
+
+    def test_favorite_key_seam_supports_id_matching(self, build_manager):
+        """The NRL case: two clubs share the abbreviation 'NEW', so favorites
+        must be matched on team id. Only the seam changes — the promoted
+        method is identical."""
+        games = [
+            game("knights", home="NEW", away="SYD", home_id=1, away_id=2,
+                 start=at(10)),
+            game("warriors", home="NEW", away="SYD", home_id=99, away_id=2,
+                 start=at(11)),
+        ]
+        abbr_manager = build_manager(_UpcomingHarness)
+        # Abbreviation matching cannot tell the two "NEW" clubs apart.
+        assert _ids(abbr_manager._select_games_for_display(games, ["NEW"])) == [
+            "knights", "warriors"]
+
+        id_manager = build_manager(_IdFavoriteUpcomingHarness)
+        assert _ids(id_manager._select_games_for_display(games, ["99"])) == [
+            "warriors"]
+
+    def test_favorite_key_none_never_matches(self, build_manager):
+        """`_favorite_key` returning None (missing id) must not match, even
+        against a favorites list holding the string 'None'."""
+        manager = build_manager(_IdFavoriteUpcomingHarness)
+        games = [game("1", home="BOS", away="TOR", start=at(10))]  # no ids
+        assert manager._select_games_for_display(games, ["None"]) == []
+
+
+# ---------------------------------------------------------------------------
+# Tier 3b — _select_recent_games_for_display (SportsRecent)
+# ---------------------------------------------------------------------------
+
+class TestSelectRecentGamesForDisplay:
+    def test_no_favorites_returns_all_sorted_descending(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        games = [game("early", start=at(10)), game("late", start=at(20)),
+                 game("mid", start=at(15))]
+        assert _ids(manager._select_recent_games_for_display(games, [])) == [
+            "late", "mid", "early"]
+
+    def test_missing_start_time_sorts_last(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        games = [game("none", start=None), game("late", start=at(20))]
+        assert _ids(manager._select_recent_games_for_display(games, [])) == [
+            "late", "none"]
+
+    def test_respects_recent_games_to_show_per_team(self, build_manager):
+        manager = build_manager(_RecentHarness, recent_games_to_show=2)
+        games = [game(str(i), home="BOS", away="TOR", start=at(10 + i))
+                 for i in range(5)]
+        # Most recent first.
+        assert _ids(manager._select_recent_games_for_display(
+            games, ["BOS"])) == ["4", "3"]
+
+    def test_game_between_two_favorites_counts_for_both(self, build_manager):
+        manager = build_manager(_RecentHarness, recent_games_to_show=1)
+        games = [game("shared", home="BOS", away="TOR", start=at(20)),
+                 game("bos2", home="BOS", away="NYR", start=at(19)),
+                 game("tor2", home="TOR", away="PIT", start=at(18))]
+        assert _ids(manager._select_recent_games_for_display(
+            games, ["BOS", "TOR"])) == ["shared"]
+
+    def test_deduplicates_by_game_id(self, build_manager):
+        manager = build_manager(_RecentHarness, recent_games_to_show=5)
+        g = game("dupe", home="BOS", away="TOR", start=at(10))
+        assert _ids(manager._select_recent_games_for_display(
+            [g, dict(g)], ["BOS"])) == ["dupe"]
+
+    def test_non_favorite_games_excluded(self, build_manager):
+        manager = build_manager(_RecentHarness)
+        games = [game("1", home="NYR", away="PIT", start=at(10))]
+        assert manager._select_recent_games_for_display(games, ["BOS"]) == []
+
+    def test_favorite_key_seam_supports_id_matching(self, build_manager):
+        games = [
+            game("knights", home="NEW", away="SYD", home_id=1, away_id=2,
+                 start=at(10)),
+            game("warriors", home="NEW", away="SYD", home_id=99, away_id=2,
+                 start=at(11)),
+        ]
+        id_manager = build_manager(_IdFavoriteRecentHarness)
+        assert _ids(id_manager._select_recent_games_for_display(
+            games, ["99"])) == ["warriors"]
+
+
+# ---------------------------------------------------------------------------
+# Seam / inertness guards
+# ---------------------------------------------------------------------------
+
+class TestPromotionShape:
+    def test_promoted_methods_live_on_the_right_classes(self):
+        assert hasattr(SportsRecent, "_get_zero_clock_duration")
+        assert hasattr(SportsRecent, "_clear_zero_clock_tracking")
+        assert hasattr(SportsRecent, "_select_recent_games_for_display")
+        assert hasattr(SportsUpcoming, "_select_games_for_display")
+        assert hasattr(SportsLive, "_is_game_really_over")
+        assert hasattr(SportsLive, "_detect_stale_games")
+
+    def test_modes_does_not_define_the_favorite_key_seam(self):
+        """`_favorite_key` is a SportsCore override point. modes.py must call
+        it, never define it — this test fails if the seam is added in the
+        wrong file."""
+        import src.base_classes.sports.modes as modes
+
+        for cls in (SportsUpcoming, SportsRecent, SportsLive):
+            assert "_favorite_key" not in vars(cls)
+        assert "_favorite_key" not in modes.__dict__