load_config_defaults ignores nested schema defaults — 2,386 defaults across 37 of 44 plugins never reach the render harness

[ChuckBuilds]

Summary

load_config_defaults only reads defaults from top-level schema properties. An object property ("type": "object" with its own properties) has no top-level "default" key, so it is skipped entirely — along with every default nested inside it.

Across the 44 first-party plugins installed here, that drops 2,386 schema defaults across 37 plugins. soccer-scoreboard loses 539 of its 565.

The consequence is that check_plugin.py — the visual regression tool, and what CI runs — renders most plugins with a config that does not resemble a real install, while render_plugin_matrix says it does:

# Start from config_schema.json defaults so the plugin behaves like a real
# install; explicit caller config still wins over a schema default.
config = {"enabled": True, **load_config_defaults(plugin_dir), **(config or {})}

The code

src/plugin_system/testing/loading.py:36-47:

def load_config_defaults(plugin_dir) -> Dict[str, Any]:
 """Extract default values from a plugin's config_schema.json (empty if none)."""
 ...
 defaults: Dict[str, Any] = {}
 for key, prop in schema.get('properties', {}).items():
 if isinstance(prop, dict) and 'default' in prop:
 defaults[key] = prop['default']
 return defaults

No recursion into prop['properties'].

Demonstration

hockey-scoreboard's schema defines nhl.enabled: true and nhl.display_modes.{live,recent,upcoming}: true. What the harness actually loads:

$ python3 -c "
from src.plugin_system.testing.loading import load_config_defaults
d = load_config_defaults('plugin-repos/hockey-scoreboard')
print('nhl.enabled =', d.get('nhl',{}).get('enabled'))
print('nhl.display_modes =', d.get('nhl',{}).get('display_modes'))"
nhl.enabled = None
nhl.display_modes = None

Same for lacrosse-scoreboard. The plugins then fall back to whatever their internal defaults happen to be, which is what the harness ends up testing.

Scale

Defaults kept (top-level) vs dropped (nested), first-party plugins only:

plugin	kept	dropped
soccer-scoreboard	26	539
baseball-scoreboard	9	251
basketball-scoreboard	9	246
hockey-scoreboard	6	207
lacrosse-scoreboard	6	155
football-scoreboard	10	152
afl-scoreboard	34	92
nrl-scoreboard	33	92
ufc-scoreboard	9	78
f1-scoreboard	6	64
ledmatrix-leaderboard	3	52
stock-news	1	50
ledmatrix-flights	51	44
masters-tournament	10	41
ledmatrix-stocks	2	39
odds-ticker	1	38
birdnet-go	2	37
news	1	29
cricket-scoreboard	22	28
… 18 more
total		2386 across 37 of 44 plugins

The plugins that lose the most are exactly the ones whose config is organised by league or by UI section — sports, customization.*, display_options.* — which is to say most of the fleet.

Why it matters beyond tidiness

1. Goldens encode the wrong baseline. Committed golden images were captured under this partial config, so they pin behaviour no user will see.
2. Whole features go untested. A plugin whose display_options.* all sit nested is rendered with those options unset at every size, in every CI run.
3. It produces misleading secondary signals. Comparing each plugin's manifest display_modes against what it exposes under harness defaults shows six sports plugins "missing" modes — baseball-scoreboard exposes 3 of 9, basketball-scoreboard 3 of 12, hockey-scoreboard 2 of 9. Those look like manifest bugs and are not; the league configs simply never arrived. I nearly filed them as plugin defects.

Suggested fix

Recurse, preserving nesting:

def _defaults(props):
 out = {}
 for key, prop in (props or {}).items():
 if not isinstance(prop, dict):
 continue
 if prop.get('type') == 'object' and 'properties' in prop:
 nested = _defaults(prop['properties'])
 if nested:
 out[key] = nested
 elif 'default' in prop:
 out[key] = prop['default']
 return out

with a merge that lets caller config override at leaf level rather than replacing whole subtrees — otherwise -c '{"nhl": {"enabled": true}}' would wipe the rest of the nhl defaults.

That is a behaviour change: goldens will shift for the 37 affected plugins, and some may start failing for real reasons. That is the point, but it wants a deliberate --update-golden pass and a look at what newly breaks rather than a quiet merge.

A regression test is easy: assert load_config_defaults on a schema with a nested object returns the nested defaults.

Environment

LEDMatrix v3.3.0-4-g0730d952, 256x64 rig, 44 first-party plugins installed. Found while auditing manifest display_modes against the modes plugins actually expose.

[ChuckBuilds]

Fixed on a local branch, with a measurement that came out differently from what I expected.

_defaults_from_properties() recurses into object properties, and merge_config() deep-merges the caller's config so an override lands at the leaf — a shallow merge would let -c '{"nhl": {"enabled": true}}' replace the whole nhl subtree and discard every other nhl default, which is the same class of bug.

The defaults are demonstrably arriving now:

plugin	defaults loaded, before → after
ufc-scoreboard	9 → 87
ledmatrix-flights	51 → 95
masters-tournament	10 → 51
cricket-scoreboard	22 → 50
tide-display	12 → 18

and hockey-scoreboard, which used to load nhl.enabled=None, now gets nhl.enabled=True with its full display_modes block.

But no render changed. I ran check_plugin across all 49 installed plugins before and after: identical PASS/FAIL counts, byte-identical output, no golden drift. I had expected goldens to shift for 37 plugins and was prepared to review the fallout plugin by plugin.

The reason appears to be that plugins already fall back to the same values internally via config.get(key, default), so supplying the schema default explicitly agrees with what they were doing anyway. That is good news for landing this — it is not the disruptive change the issue predicted.

One caveat I would not want lost. The eight plugins with the most nested config — soccer, baseball, basketball, hockey, lacrosse, football, afl, nrl, together 1,634 of the 2,386 dropped defaults (68%) — could not be measured. They import src.common.sports_shared, which my test rig's core branch predates, so they fail to load there identically before and after and contribute no signal either way.

Those are exactly the plugins whose renders should change most, since their config is organised per league. Worth re-running the same before/after against a core that has sports_shared before treating "nothing changed" as settled. Happy to do that if the rig goes back to a commit with it.

[ChuckBuilds]

The unmeasured 68% is now measured, and it agrees with the rest.

I set up a detached worktree of origin/main alongside the soak checkout so the eight sports plugins could actually load (the soak branch predates src/common/sports_shared), then ran the same before/after:

 BEFORE AFTER
afl-scoreboard PASS=24 FAIL=0 modes=3 PASS=24 FAIL=0 modes=3
baseball-scoreboard PASS=24 FAIL=0 modes=3 PASS=24 FAIL=0 modes=3
basketball-scoreboard PASS=24 FAIL=0 modes=3 PASS=24 FAIL=0 modes=3
football-scoreboard PASS=24 FAIL=0 modes=3 PASS=24 FAIL=0 modes=3
hockey-scoreboard PASS=16 FAIL=0 modes=2 PASS=16 FAIL=0 modes=2
lacrosse-scoreboard PASS=16 FAIL=0 modes=2 PASS=16 FAIL=0 modes=2
nrl-scoreboard PASS=24 FAIL=0 modes=3 PASS=24 FAIL=0 modes=3
soccer-scoreboard PASS=24 FAIL=0 modes=3 PASS=24 FAIL=0 modes=3

Identical — same pass counts, same mode counts, no golden drift. These eight carry 1,634 of the 2,386 previously-dropped defaults, so with them measured the conclusion now covers the whole fleet: the fix delivers the defaults and changes no rendering, because plugins were already falling back to the same values via config.get(key, default).

That closes the caveat I attached to the earlier comment. Nothing here needs a golden refresh.

One incidental observation, unchanged by the fix so not a regression: hockey and lacrosse expose 2 modes rather than 3 both before and after — their _live mode is not registered even with display_modes.live=True now loading. That looks like live modes being gated on actual live data, which is reasonable, but I mention it in case it is not intended.