From dfd67c7c8b8b01ae776616e17d2e103e01e8c33a Mon Sep 17 00:00:00 2001 From: Chuck <33324927+ChuckBuilds@users.noreply.github.com> Date: Thu, 1 Oct 2026 08:37:15 -0400 Subject: [PATCH] feat(dev): preview a plugin's Vegas strip in the dev server (#700) * perf(timing): say which render-thread work a late frame followed The soak already says how often a moving frame reached the panel late, but not what the render thread was doing just before it. Vegas does two kinds of work there between frames -- building its strip (compose, extend) and, with live elements, patching changed pixels into it -- and deciding whether either is affordable needs their own numbers. - FrameTimingRecorder.note_op(kind, nbytes) tags the next presented frame. Totals gain op_frames, late_op_frames, op_freezes and op_bytes per kind; aggregate() still takes frames without ops. The file schema is unchanged. - Vegas tags compose and every strip extension (with the bytes it copied). - frame_soak prints an "after work" table: frames, late %, freezes and MB moved per kind, only when something tagged its work. - render_bench gains --strip-screens (Vegas-sized strips), --patch-bytes / --patch-every / --patch-where (in-place column writes, as a live element update does) and --extend-every-screens / --extend-width (append + trim on a fixed cadence that holds the strip's width). No runtime behaviour changes: this is the measurement gate for live Vegas elements. Co-Authored-By: Claude Opus 5.5 * docs(changelog): note the frame-op attribution and bench modes Co-Authored-By: Claude Opus 5.5 * perf(scroll): build the strip's PIL image only when something reads it Every Vegas strip extension rebuilt ScrollHelper.cached_image from cached_array in full, twice (append, then trim), on the render thread: Image.fromarray is 1.7ms for an 8,000px strip and 3.8ms for 20,000px on a Pi 4 (measured on ledpi), about two thirds of an extension's render-thread cost. Nothing on the frame path reads the image's pixels; every frame is cut from the array. cached_image is now a property. append_content and drop_scrolled_prefix defer it; the first read builds it from the array it started with and keeps it only if the strip has not changed meanwhile, so a sync push racing an extension cannot leave a stale image cached. Assigning cached_image stores exactly what was assigned, as before. has_strip() says whether there is a strip without building its image; the helper's frame path, Vegas and the adapter's scroll-cache invalidation use it. The strip is also no longer held in memory twice. In Vegas the image is now built only by a multi-display sync push. Co-Authored-By: Claude Opus 5.5 * feat(vegas): live elements -- a plugin API for content that changes while it scrolls Vegas bakes each plugin's pictures into one strip, so a card already on its way across the panel keeps what it showed when it was drawn. This adds the API and bookkeeping for content that can be updated in place; the worker that redraws and swaps it follows separately. No shipped plugin implements the hook yet, so nothing changes for users. Plugin API (core 3.8.0), all no-ops by default: - BasePlugin.get_vegas_elements() -> [VegasElement(key, image, version, live, refresh_hz)]: named, fixed-width pieces of Vegas content. - BasePlugin.redraw_vegas_element(key, width, height, at): a lock-free redraw for content that changes with time. - BasePlugin.notify_vegas_data_changed(): data that lands outside update(). - src/plugin_system/vegas_elements.py (VegasElement, re-exported from base_plugin). Core: - PluginAdapter asks a plugin that implements the hook for elements on the background fetch only (under its lock, on its own canvas); every other path keeps get_vegas_content(). Live elements are pinned (padded with content_padding, never trimmed), tagged with their key, digest and data epoch in Image.info so the existing cache and group plumbing carry them unchanged, and untagged if a width budget crops them. - RenderPipeline records where each live element lands (ElementRecord), in absolute strip columns a trim does not move; the block-start arithmetic is shared with the STATIC markers. - PluginManager update listeners (add/remove_update_listener, notify_data_changed): told the moment update() completes, not at the next ~4s Vegas poll. The coordinator uses one to move each plugin's data epoch on. - vegas_scroll.live_refresh (kill switch), live_max_hz, live_min_interval, live_lead_screens; per-plugin core-owned vegas_live. Live elements are off under multi-display sync, in swap mode and with offscreen_prefetch off. - scripts/check_plugin.py checks the element contract (src/plugin_system/testing/vegas.py); test/fixtures/plugins/vegas-live-stub is a working example. Co-Authored-By: Claude Opus 5.5 * feat(vegas): live elements update in place while they scroll One background worker (src/vegas_mode/live_worker.py) redraws a plugin's live elements when its data epoch moves on (update listener) or on their refresh_hz, nearest the screen first, and hands changed pixels lock-free to the render thread, which copies them into the strip between frames (RenderPipeline.apply_live_patches, ScrollHelper.patch_columns): at most four patches or two screens of bytes a frame, no drawing or locks there. The worker takes over group prefetch once a live element is placed, runs inside the render gate, and is supervised. Update tick 1s while live elements exist. Web UI switch for live_refresh. OFFSCREEN_RENDERING.md describes what was built and why SegmentStrip was not needed. Co-Authored-By: Claude Opus 5.5 * feat(sports): live Vegas cards for the scoreboards (shared layer) One live element per game, drawn only when what the card shows changes, so a score changes on a card already crossing the panel. The shared part, so each scoreboard adopts it in a few lines: - src/common/sports_vegas.py: game_key, game_fingerprint (the whole game dict, frozen: no drawn field can be missed), dedupe_games, VegasCardCache, StickyOdds (odds a live poll left out stay drawn), finished_games / with_finished_games (a game that just went final keeps its card, after its league's live games; one a heuristic only judged over keeps its live state, so a tied end of regulation never shows FINAL early). - SportsScrollDisplay.make_vegas_renderer() is the override point; build_vegas_elements() and SportsScrollDisplayManager .get_vegas_elements_for() do the rest. A card's version includes its teams' ranks, which the renderer draws from the rankings cache. - SportsLiveSharedMixin._record_finished_game() / finished_games_snapshot(): held for FINISHED_GAME_TTL after it leaves the live list. A sport that does not implement make_vegas_renderer keeps its ordinary Vegas content, so no scoreboard changes until it opts in. scripts/render_plugin.py --vegas renders a plugin's Vegas block as the ticker lays it out, and --timeline stacks it at successive moments as the ticker would update it in place; the join is now render_pipeline.join_plugin_rows(). Co-Authored-By: Claude Opus 5.5 * feat(vegas): keep live games in the ticker by default display.vegas_scroll.live_in_ticker now defaults to true: through a live game the marquee keeps running and the live scoreboard takes extra turns in it -- its cards updating in place while they scroll -- instead of the ticker giving way to the full-screen scoreboard. The new default would reach nobody on its own: every existing config holds an explicit false copied from the template (there was no control for it), and the template merge only adds missing keys. ConfigManager therefore turns a stored false on once, with a backup, and records live_in_ticker_migrated so a false chosen afterwards stays. The marker is never in the template. A "Keep live games in the ticker" checkbox under Vegas mode sets it. Tests that pin the full-screen takeover now say live_in_ticker=false. Co-Authored-By: Claude Opus 5.5 * feat(dev): preview a plugin's Vegas strip in the dev server The dev server's View selector gains "Vegas strip (live elements)" and "Vegas strip (plain Vegas content)": the plugin's block of the Vegas ticker, laid out by the ticker's own code (render_vegas_strip, as render_plugin.py --vegas uses), with its live elements listed. /api/render takes "vegas": "live" | "plain"; the display view is unchanged. Co-Authored-By: Claude Opus 5.5 * refactor(sports): a default _determine_game_type on SportsScrollDisplay render_vegas_card looked the method up with getattr and a None default, which static analysis (Codacy) reports as calling something that may not be callable. The base class now has the default -- the card type from the game's state -- and the plugins that define their own override it as before. Co-Authored-By: Claude Opus 5.5 * fix: review follow-ups on the shared live-card layer - The reused Vegas renderer always gets the current rankings, empty included, so ranks cleared since are not kept drawn. - render_plugin.py: --timeline refuses --no-live (a timeline shows live elements changing), --timeline/--no-live need --vegas, and the Vegas paths create the output's directory like the display path does. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- scripts/dev_server.py | 57 ++++++++++++++++++++++++++++-- scripts/templates/dev_preview.html | 19 +++++++++- test/test_dev_server_vegas.py | 49 +++++++++++++++++++++++++ 3 files changed, 121 insertions(+), 4 deletions(-) create mode 100644 test/test_dev_server_vegas.py diff --git a/scripts/dev_server.py b/scripts/dev_server.py index dc4a836a..638017cd 100644 --- a/scripts/dev_server.py +++ b/scripts/dev_server.py @@ -200,12 +200,21 @@ def api_plugin_defaults(plugin_id): return jsonify({'defaults': defaults}) +#: /api/render "vegas" values: the plugin's block of the Vegas strip, built +#: from its live elements (falling back to its Vegas content, as the ticker +#: does) or from its ordinary Vegas content only. +VEGAS_VIEWS = ('live', 'plain') + + def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, height, - skip_update): + skip_update, vegas=None): """Render one plugin at one size. Returns the /api/render response dict. A fresh plugin instance per call, mirroring the safety harness, so sizes - never share state. + never share state. With ``vegas`` set ('live' or 'plain') the image is the + plugin's block of the Vegas strip instead of its display(), laid out by + the ticker's own code (src/plugin_system/testing/vegas.py), and the + response lists where each live element sits in it. """ from src.plugin_system.testing import VisualTestDisplayManager, MockCacheManager, MockPluginManager from src.plugin_system.plugin_loader import PluginLoader @@ -243,6 +252,10 @@ def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, heig logger.warning("update() raised for plugin %s", plugin_id, exc_info=True) warnings.append(f"update() raised: {type(e).__name__} — see server log") + if vegas: + return _vegas_response(plugin_id, plugin_instance, display_manager, vegas, + start_time, errors, warnings) + # Run display() try: plugin_instance.display(force_clear=True) @@ -262,6 +275,40 @@ def _render_once(plugin_id, plugin_dir, manifest, config, mock_data, width, heig } +def _vegas_response(plugin_id, plugin_instance, display_manager, vegas, start_time, + errors, warnings): + """The /api/render response for the Vegas strip view.""" + import base64 + import io + + from src.plugin_system.testing.vegas import render_vegas_strip + + block, layout = None, [] + try: + block, layout = render_vegas_strip(plugin_instance, plugin_id, display_manager, + live=(vegas == 'live')) + except Exception as e: + logger.warning("Vegas render raised for plugin %s", plugin_id, exc_info=True) + errors.append(f"Vegas render raised: {type(e).__name__} — see server log") + if block is None: + if not errors: + errors.append("The plugin has no Vegas content") + block = display_manager.image + elif vegas == 'live' and not layout: + warnings.append("No live elements: this is the plugin's ordinary Vegas content") + buffer = io.BytesIO() + block.convert('RGB').save(buffer, format='PNG') + return { + 'image': 'data:image/png;base64,' + base64.b64encode(buffer.getvalue()).decode('ascii'), + 'width': block.width, + 'height': block.height, + 'render_time_ms': round((time.time() - start_time) * 1000, 1), + 'errors': errors, + 'warnings': warnings, + 'live_elements': [{'key': key, 'x': x, 'width': width} for x, key, width in layout], + } + + def _trusted_plugin_dir(plugin_dir: Path) -> Optional[Path]: """Re-derive a plugin directory from the search dirs' own listings. @@ -333,6 +380,10 @@ def api_render(): if not (MIN_HEIGHT <= height <= MAX_HEIGHT): return jsonify({'error': f'height must be between {MIN_HEIGHT} and {MAX_HEIGHT}'}), 400 + vegas = data.get('vegas') or None + if vegas is not None and vegas not in VEGAS_VIEWS: + return jsonify({'error': f'vegas must be one of {", ".join(VEGAS_VIEWS)}'}), 400 + try: plugin_dir, manifest, config, mock_data, skip_update = _parse_render_request(data) except LookupError: @@ -345,7 +396,7 @@ def api_render(): try: result = _render_once(data['plugin_id'], plugin_dir, manifest, config, - mock_data, width, height, skip_update) + mock_data, width, height, skip_update, vegas=vegas) except Exception: app.logger.exception('plugin load failed during render') return jsonify({'error': 'Failed to load plugin; see server log'}), 500 diff --git a/scripts/templates/dev_preview.html b/scripts/templates/dev_preview.html index 4e308013..8151e185 100644 --- a/scripts/templates/dev_preview.html +++ b/scripts/templates/dev_preview.html @@ -247,6 +247,19 @@ + +
+ + +
+