refactor(display): run() stage 1 - golden traces and extracted helpers, no behaviour change (#704)

Adds golden trace tests for DisplayController.run() (test/test_run_loop_golden.py on a fake clock with fake plugins, 15 scenarios, fixtures in test/fixtures/run_loop_golden/) and moves twelve blocks of run() into named helpers (_dispatch_first_frame, _resolve_durations, _resolve_active_mode, _needs_high_fps, _advance_after_screen and others) with the traces identical before and after. docs/RUN_LOOP_REDESIGN.md describes the target structure. Hardware-checked on hdpi: Vegas late-frame rate unchanged in an ABBA A/B.

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

test/fixtures/run_loop_golden/all_empty.json

@@ -0,0 +1,14 @@
+{
+  "screens": [
+    [0.0, "a", 0.0, "empty", 1, false],
+    [0.0, "b", 0.0, "empty", 1, true],
+    [0.0, "c", 1.0, "empty", 1, true],
+    [1.0, "a", 1.0, "empty", 1, true],
+    [2.0, "b", 1.0, "empty", 1, true],
+    [3.0, "c", 1.0, "empty", 1, true],
+    [4.0, "a", 1.0, "empty", 1, true],
+    [5.0, "b", 1.0, "empty", 1, true],
+    [6.0, "c", 6.0, "horizon", 6, true]
+  ],
+  "events": []
+}

test/fixtures/run_loop_golden/dynamic_duration.json

@@ -0,0 +1,24 @@
+{
+  "screens": [
+    [0.0, "scroller", 20.008, "cycle-complete", 2502, false],
+    [20.008, "news", 40.0, "duration", 40, true],
+    [60.008, "board", 11.0, "cycle-complete", 12, true],
+    [71.008, "clock", 10.0, "duration", 10, true],
+    [81.008, "scroller", 20.007, "cycle-complete", 2502, true],
+    [101.015, "news", 40.0, "duration", 40, true],
+    [141.015, "board", 11.0, "cycle-complete", 12, true],
+    [152.015, "clock", 10.0, "duration", 10, true],
+    [162.015, "scroller", 20.008, "cycle-complete", 2502, true],
+    [182.023, "news", 37.977, "horizon", 38, true]
+  ],
+  "events": [
+    [0.0, "cycle-reset", "scroller"],
+    [20.008, "cycle-reset", "news"],
+    [60.008, "cycle-reset", "board"],
+    [81.008, "cycle-reset", "scroller"],
+    [101.015, "cycle-reset", "news"],
+    [141.015, "cycle-reset", "board"],
+    [162.015, "cycle-reset", "scroller"],
+    [182.023, "cycle-reset", "news"]
+  ]
+}

test/fixtures/run_loop_golden/empty_modes.json

@@ -0,0 +1,22 @@
+{
+  "screens": [
+    [0.0, "clock", 10.0, "duration", 10, false],
+    [10.0, "empty", 0.0, "empty", 1, true],
+    [10.0, "ghost", 0.0, "no-plugin", 0, null],
+    [10.0, "flaky", 12.0, "display-false", 2, true],
+    [22.0, "clock", 10.0, "duration", 10, true],
+    [32.0, "empty", 0.0, "empty", 1, true],
+    [32.0, "ghost", 0.0, "no-plugin", 0, null],
+    [32.0, "flaky", 12.0, "display-false", 2, true],
+    [44.0, "clock", 10.0, "duration", 10, true],
+    [54.0, "empty", 0.0, "empty", 1, true],
+    [54.0, "ghost", 0.0, "no-plugin", 0, null],
+    [54.0, "flaky", 12.0, "display-false", 2, true],
+    [66.0, "clock", 10.0, "duration", 10, true],
+    [76.0, "empty", 0.0, "empty", 1, true],
+    [76.0, "ghost", 0.0, "no-plugin", 0, null],
+    [76.0, "flaky", 12.0, "display-false", 2, true],
+    [88.0, "clock", 2.0, "horizon", 2, true]
+  ],
+  "events": []
+}

test/fixtures/run_loop_golden/follower.json

@@ -0,0 +1,10 @@
+{
+  "screens": [
+    [0.0, "clock", 20.0, "duration", 20, false],
+    [20.0, "weather", 20.0, "duration", 20, true],
+    [40.0, "<follower>", 10.017, "duration", 601, null],
+    [50.017, "clock", 20.0, "duration", 20, true],
+    [70.017, "weather", 9.983, "horizon", 10, true]
+  ],
+  "events": []
+}

test/fixtures/run_loop_golden/live_priority.json

@@ -0,0 +1,19 @@
+{
+  "screens": [
+    [0.0, "clock", 20.0, "duration", 20, false],
+    [20.0, "weather", 20.0, "duration", 20, true],
+    [40.0, "sports_recent", 20.0, "live", 20, true],
+    [60.0, "sports_live", 20.0, "duration", 20, true],
+    [80.0, "sports_live", 20.0, "duration", 20, false],
+    [100.0, "sports_live", 20.0, "display-false", 11, false],
+    [120.0, "sports_recent", 20.0, "duration", 20, true],
+    [140.0, "sports_live", 0.0, "empty", 1, true],
+    [140.0, "clock", 20.0, "duration", 20, true],
+    [160.0, "weather", 20.0, "duration", 20, true],
+    [180.0, "sports_recent", 20.0, "horizon", 20, true]
+  ],
+  "events": [
+    [60.0, "live", "sports_live"],
+    [120.0, "live-ended", "sports_recent"]
+  ]
+}

test/fixtures/run_loop_golden/live_round_robin.json

@@ -0,0 +1,20 @@
+{
+  "screens": [
+    [0.0, "nfl_live", 15.0, "duration", 15, true],
+    [15.0, "nfl_live", 15.0, "live", 15, false],
+    [30.0, "nhl_live", 15.0, "live", 15, true],
+    [45.0, "nfl_live", 15.0, "live", 15, true],
+    [60.0, "nhl_live", 15.0, "duration", 15, true],
+    [75.0, "nhl_live", 15.0, "duration", 15, false],
+    [90.0, "nhl_live", 15.0, "duration", 15, false],
+    [105.0, "clock", 15.0, "duration", 15, true],
+    [120.0, "nfl_live", 15.0, "duration", 15, true],
+    [135.0, "nhl_live", 15.0, "horizon", 15, true]
+  ],
+  "events": [
+    [0.0, "live", "nfl_live"],
+    [30.0, "live", "nhl_live"],
+    [45.0, "live", "nfl_live"],
+    [60.0, "live", "nhl_live"]
+  ]
+}

test/fixtures/run_loop_golden/on_demand.json

@@ -0,0 +1,30 @@
+{
+  "screens": [
+    [0.0, "clock", 20.0, "duration", 20, false],
+    [20.0, "weather", 5.0, "on-demand-start", 6, true],
+    [25.0, "sports_recent", 15.0, "duration", 15, true],
+    [40.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [55.0, "sports_recent", 15.0, "duration", 15, true],
+    [70.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [85.0, "sports_recent", 10.0, "on-demand-requested-stop", 11, true],
+    [95.0, "weather", 20.0, "duration", 20, true],
+    [115.0, "sports_recent", 15.0, "duration", 15, true],
+    [130.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [145.0, "clock", 5.0, "on-demand-start", 6, true],
+    [150.0, "weather", 20.0, "duration", 20, true],
+    [170.0, "weather", 10.0, "on-demand-expired", 10, true],
+    [180.0, "clock", 20.0, "duration", 20, true],
+    [200.0, "weather", 20.0, "duration", 20, true],
+    [220.0, "sports_recent", 15.0, "duration", 15, true],
+    [235.0, "sports_upcoming", 5.0, "horizon", 5, true]
+  ],
+  "events": [
+    [25.0, "request", "start:r1"],
+    [25.0, "on-demand-start", "sports"],
+    [95.0, "request", "stop:r2"],
+    [95.0, "on-demand-requested-stop"],
+    [150.0, "request", "start:r3"],
+    [150.0, "on-demand-start", "weather"],
+    [180.0, "on-demand-expired"]
+  ]
+}

test/fixtures/run_loop_golden/on_demand_pinned.json

@@ -0,0 +1,29 @@
+{
+  "screens": [
+    [0.0, "clock", 12.0, "on-demand-start", 13, false],
+    [12.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [27.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [42.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [57.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [72.0, "sports_upcoming", 8.0, "on-demand-start", 9, true],
+    [80.0, "app_a", 0.0, "empty", 1, true],
+    [80.0, "app_b", 10.0, "duration", 10, true],
+    [90.0, "app_a", 0.0, "empty", 1, true],
+    [90.0, "app_b", 10.0, "duration", 10, true],
+    [100.0, "app_a", 0.0, "empty", 1, true],
+    [100.0, "app_b", 10.0, "duration", 10, true],
+    [110.0, "app_a", 0.0, "empty", 1, true],
+    [110.0, "app_b", 10.0, "on-demand-requested-stop", 10, true],
+    [120.0, "clock", 20.0, "duration", 20, true],
+    [140.0, "sports_recent", 15.0, "duration", 15, true],
+    [155.0, "sports_upcoming", 5.0, "horizon", 5, true]
+  ],
+  "events": [
+    [12.0, "request", "start:p1"],
+    [12.0, "on-demand-start", "sports"],
+    [80.0, "request", "start:p2"],
+    [80.0, "on-demand-start", "starlark"],
+    [120.0, "request", "stop:p3"],
+    [120.0, "on-demand-requested-stop"]
+  ]
+}

test/fixtures/run_loop_golden/on_demand_restored.json

@@ -0,0 +1,14 @@
+{
+  "screens": [
+    [0.0, "sports_upcoming", 15.0, "duration", 15, true],
+    [15.0, "sports_recent", 15.0, "duration", 15, true],
+    [30.0, "sports_upcoming", 10.0, "on-demand-expired", 10, true],
+    [40.0, "clock", 20.0, "duration", 20, true],
+    [60.0, "weather", 20.0, "duration", 20, true],
+    [80.0, "sports_recent", 15.0, "duration", 15, true],
+    [95.0, "sports_upcoming", 5.0, "horizon", 5, true]
+  ],
+  "events": [
+    [40.0, "on-demand-expired"]
+  ]
+}

test/fixtures/run_loop_golden/plain_rotation.json

@@ -0,0 +1,17 @@
+{
+  "screens": [
+    [0.0, "clock", 15.0, "duration", 15, false],
+    [15.0, "weather_now", 20.0, "duration", 20, true],
+    [35.0, "weather_forecast", 20.0, "duration", 20, true],
+    [55.0, "ticker", 10.008, "duration", 1252, true],
+    [65.008, "legacy", 5.0, "duration", 5, true],
+    [70.008, "clock", 15.0, "duration", 15, true],
+    [85.008, "weather_now", 20.0, "duration", 20, true],
+    [105.008, "weather_forecast", 20.0, "duration", 20, true],
+    [125.008, "ticker", 10.008, "duration", 1252, true],
+    [135.016, "legacy", 5.0, "duration", 5, true],
+    [140.016, "clock", 15.0, "duration", 15, true],
+    [155.016, "weather_now", 4.984, "horizon", 5, true]
+  ],
+  "events": []
+}

test/fixtures/run_loop_golden/plugin_error.json

@@ -0,0 +1,27 @@
+{
+  "screens": [
+    [0.0, "clock", 10.0, "duration", 10, false],
+    [10.0, "broken_a", 0.0, "error", 0, null],
+    [10.0, "weather", 10.0, "duration", 10, true],
+    [20.0, "crashy", 0.0, "raised", 1, true],
+    [20.0, "clock", 10.0, "duration", 10, true],
+    [30.0, "broken_a", 0.0, "error", 0, null],
+    [30.0, "weather", 10.0, "duration", 10, true],
+    [40.0, "crashy", 0.0, "raised", 1, true],
+    [40.0, "clock", 10.0, "duration", 10, true],
+    [50.0, "broken_a", 0.0, "breaker", 0, null],
+    [50.0, "broken_b", 0.0, "breaker", 0, null],
+    [50.0, "weather", 10.0, "duration", 10, true],
+    [60.0, "crashy", 0.0, "raised", 1, true],
+    [60.0, "clock", 10.0, "duration", 10, true],
+    [70.0, "broken_a", 0.0, "breaker", 0, null],
+    [70.0, "broken_b", 0.0, "breaker", 0, null],
+    [70.0, "weather", 10.0, "duration", 10, true],
+    [80.0, "crashy", 0.0, "raised", 1, true],
+    [80.0, "clock", 10.0, "horizon", 10, true]
+  ],
+  "events": [
+    [10.0, "health-failure", "broken"],
+    [30.0, "health-failure", "broken"]
+  ]
+}

test/fixtures/run_loop_golden/schedule.json

@@ -0,0 +1,31 @@
+{
+  "screens": [
+    [0.0, "clock", 20.0, "duration", 20, false],
+    [20.0, "weather", 20.0, "duration", 20, true],
+    [40.0, "clock", 20.0, "duration", 20, true],
+    [60.0, "weather", 20.0, "duration", 20, true],
+    [80.0, "clock", 20.0, "duration", 20, true],
+    [100.0, "weather", 20.0, "duration", 20, true],
+    [120.0, "clock", 20.0, "duration", 20, true],
+    [140.0, "weather", 10.0, "schedule-off", 11, true],
+    [150.0, "<off>", 20.0, "on-demand-start", 2, null],
+    [170.0, "weather", 20.0, "on-demand-expired", 20, true],
+    [190.0, "weather", 20.0, "schedule-off", 20, true],
+    [210.0, "<off>", 120.0, "schedule-on", 2, null],
+    [330.0, "clock", 20.0, "duration", 20, true],
+    [350.0, "weather", 20.0, "duration", 20, true],
+    [370.0, "clock", 20.0, "duration", 20, true],
+    [390.0, "weather", 10.0, "horizon", 10, true]
+  ],
+  "events": [
+    [30.0, "brightness", 30],
+    [150.0, "schedule-off"],
+    [170.0, "request", "start:s1"],
+    [170.0, "on-demand-start", "weather"],
+    [170.0, "schedule-on"],
+    [170.0, "brightness", 90],
+    [190.0, "on-demand-expired"],
+    [210.0, "schedule-off"],
+    [330.0, "schedule-on"]
+  ]
+}

test/fixtures/run_loop_golden/vegas.json

@@ -0,0 +1,26 @@
+{
+  "screens": [
+    [0.0, "<vegas>", 30.008, "duration", 3751, null],
+    [30.008, "<vegas>", 30.007, "duration", 3751, null],
+    [60.015, "<vegas>", 10.24, "vegas-live", 1280, null],
+    [70.255, "clock", 20.0, "duration", 20, false],
+    [90.255, "sports_live", 20.0, "display-false", 11, true],
+    [110.255, "<vegas>", 30.008, "duration", 3751, null],
+    [140.263, "<vegas>", 10.0, "on-demand-start", 1250, null],
+    [150.263, "clock", 20.0, "duration", 20, true],
+    [170.263, "clock", 5.0, "on-demand-expired", 5, true],
+    [175.263, "<vegas>", 24.959, "vegas-interrupt", 3120, null],
+    [200.222, "clock", 20.0, "duration", 20, true],
+    [220.222, "<vegas>", 30.008, "duration", 3751, null],
+    [250.23, "<vegas>", 9.77, "horizon", 1222, null]
+  ],
+  "events": [
+    [70.255, "vegas-live"],
+    [150.0, "request", "start:v1"],
+    [150.263, "on-demand-start", "clock"],
+    [150.263, "vegas-interrupt"],
+    [175.263, "on-demand-expired"],
+    [200.0, "wifi-file", "Connected to HomeNet"],
+    [200.222, "vegas-interrupt"]
+  ]
+}

test/fixtures/run_loop_golden/vegas_live_in_ticker.json

@@ -0,0 +1,9 @@
+{
+  "screens": [
+    [0.0, "<vegas>", 30.008, "duration", 3751, null],
+    [30.008, "<vegas>", 30.007, "duration", 3751, null],
+    [60.015, "<vegas>", 30.008, "duration", 3751, null],
+    [90.023, "<vegas>", 9.977, "horizon", 1248, null]
+  ],
+  "events": []
+}

test/fixtures/run_loop_golden/wifi_notice.json

@@ -0,0 +1,19 @@
+{
+  "screens": [
+    [0.0, "clock", 20.0, "duration", 20, false],
+    [20.0, "weather", 20.0, "duration", 20, true],
+    [40.0, "clock", 20.0, "on-demand-start", 20, true],
+    [60.0, "clock", 20.0, "on-demand-expired", 20, true],
+    [80.0, "<wifi>", 15.0, "duration", 30, null],
+    [95.0, "weather", 20.0, "duration", 20, true],
+    [115.0, "clock", 20.0, "duration", 20, true],
+    [135.0, "weather", 15.0, "horizon", 15, true]
+  ],
+  "events": [
+    [25.0, "wifi-file", "Connected to HomeNet"],
+    [60.0, "request", "start:w1"],
+    [60.0, "on-demand-start", "clock"],
+    [65.0, "wifi-file", "AP mode on"],
+    [80.0, "on-demand-expired"]
+  ]
+}