mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-06-06 10:33:32 +00:00
313e35a98f
* feat(testing): add cross-size/cross-screen plugin safety harness Render every plugin across all supported matrix sizes (64x32, 128x32, 128x64, 256x32) and every declared screen, failing on crashes, content drawn past the panel edge, or visual drift vs committed golden images. - BoundsCheckingDisplayManager: oversized-canvas overflow detection - harness.py: multi-size/multi-screen render engine + golden compare - scripts/check_plugin.py: CLI (functional+bounds, --out-dir, --update-golden, --freeze-time); render_plugin.py refactored onto shared loading helpers - test/plugins/test_harness.py + test_plugin_matrix.py (parametrized, honors per-plugin test/harness.json; skips when no plugins present) - MockCacheManager.cache_dir so cache-dir-using plugins load headlessly - .github/workflows/test.yml + docs/plugin-safety-harness.md Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(testing): address PR review feedback on plugin safety harness - check_plugin: friendly error for non-numeric --sizes; reject non-object --config / --mock-data JSON; sanitize plugin mode before using as a filename; stop --update-golden from masking crash/overflow failures - bounds_display_manager: pad the canvas out to the largest supported panel (not a fixed 16px) so far-overshoot coordinates are caught, not clipped - harness: merge config_schema defaults inside render_plugin_matrix; surface update() failures as a non-fatal warning + result field instead of a debug log; sanitize mode in golden_path - loading: fail fast when harness.json references a missing mock_data fixture - mocks: clean up the per-instance temp cache dir via weakref.finalize - test_plugin_matrix: add a discovery guard that fails when LEDMATRIX_REQUIRE_PLUGINS=1 but none found (still skips locally); type hints - bound test deps with upper version pins for deterministic CI Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(testing): render plugins across arbitrary panel sizes, not a fixed list Addresses maintainer feedback that there is no canonical set of supported panel sizes — a build can be any size/configuration (square, 2x2, 4x4, 8x2, long strips, tall stacks). - sizes.py: SUPPORTED_SIZES -> DEFAULT_TEST_SIZES (back-compat alias kept), reframed as a representative SAMPLE of real panel-grid arrangements rather than an authoritative list; add parse_size_token / coerce_sizes / resolve_test_sizes helpers - sizes are now fully overridable: LEDMATRIX_TEST_SIZES env (global, e.g. test on your exact hardware) > per-plugin harness.json "sizes" > default sample; CLI --sizes unchanged - bounds_display_manager: pad the canvas to the largest panel IN THE CURRENT RUN (via overflow_extent) instead of a hardcoded max, so cross-size overflow detection scales to whatever sizes a run uses - harness: compute per-run extent and thread it into the bounds manager - tests: arbitrary-shape + size-parsing/precedence coverage - docs: rewrite "Supported sizes" -> "Sizes: a sample, not a fixed list" Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(testing): fail the harness on non-connectivity update() errors Addresses the remaining review thread: recording every update() exception as a non-fatal warning still let a real update() regression pass green as long as display() survived. Now update() failures are classified — a tolerated set of connectivity errors (ConnectionError/TimeoutError/socket/ssl/urllib/http/ requests) is recorded non-fatally (expected with no network in CI), while any other exception is treated as a genuine bug and fails that render. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * ci(security): pin actions to SHAs and disable checkout credential persistence Addresses the CodeRabbit/zizmor workflow-hardening finding: pin actions/checkout and actions/setup-python to full commit SHAs and set persist-credentials: false on checkout to reduce supply-chain and token-exposure risk. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * fix(testing): validate positive sizes; narrow requests import except Two review findings: - sizes.py: parse_size_token / coerce_sizes now reject non-positive dimensions (0x32, -64x32) with a clear message instead of passing invalid sizes downstream (CodeRabbit). - harness.py: the optional `requests` import now catches ImportError specifically and logs instead of `except Exception: pass`, clearing the Codacy medium "Try, Except, Pass" (harness.py L52) and Ruff S110/BLE001. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
LEDMatrix Documentation
This directory contains guides, references, and architectural notes for the LEDMatrix project. If you are setting up a Pi for the first time, start with the project root README — it covers hardware, OS imaging, and the one-shot installer. The pages here go deeper.
I'm a new user
- GETTING_STARTED.md — first-time setup walkthrough
- WEB_INTERFACE_GUIDE.md — using the web UI
- PLUGIN_STORE_GUIDE.md — installing and managing plugins
- WIFI_NETWORK_SETUP.md — WiFi and AP-mode setup
- TROUBLESHOOTING.md — common issues and fixes
- SSH_UNAVAILABLE_AFTER_INSTALL.md — recovering SSH after install
- CONFIG_DEBUGGING.md — diagnosing config problems
I want to write a plugin
Start here:
- PLUGIN_DEVELOPMENT_GUIDE.md — end-to-end workflow
- PLUGIN_QUICK_REFERENCE.md — cheat sheet
- PLUGIN_API_REFERENCE.md — display, cache, and plugin-manager APIs
- PLUGIN_ERROR_HANDLING.md — error-handling patterns
- DEV_PREVIEW.md — preview plugins on your dev machine without a Pi
- EMULATOR_SETUP_GUIDE.md — running the matrix emulator
Going deeper:
- ADVANCED_PLUGIN_DEVELOPMENT.md — advanced patterns
- PLUGIN_ARCHITECTURE_SPEC.md — full plugin-system spec
- PLUGIN_DEPENDENCY_GUIDE.md / PLUGIN_DEPENDENCY_TROUBLESHOOTING.md
- PLUGIN_WEB_UI_ACTIONS.md (+ example JSON)
- PLUGIN_CUSTOM_ICONS.md / PLUGIN_CUSTOM_ICONS_FEATURE.md
- PLUGIN_REGISTRY_SETUP_GUIDE.md (+ registry template)
- STARLARK_APPS_GUIDE.md — Starlark-based mini-apps
- widget-guide.md — widget development
Configuring plugins
- PLUGIN_CONFIG_QUICK_START.md — minimal config you need
- PLUGIN_CONFIGURATION_GUIDE.md — schema design
- PLUGIN_CONFIGURATION_TABS.md — multi-tab UI configs
- PLUGIN_CONFIG_ARCHITECTURE.md — how the config system works
- PLUGIN_CONFIG_CORE_PROPERTIES.md — properties every plugin honors
Advanced features
- ADVANCED_FEATURES.md — Vegas scroll, on-demand display, cache management, background services, permissions
- FONT_MANAGER.md — font system
Reference
- REST_API_REFERENCE.md — all web-interface HTTP endpoints
- PLUGIN_API_REFERENCE.md — Python APIs available to plugins
- DEVELOPER_QUICK_REFERENCE.md — common dev tasks
- PLUGIN_IMPLEMENTATION_SUMMARY.md — what the plugin system actually does
Contributing to LEDMatrix itself
- DEVELOPMENT.md — environment setup
- HOW_TO_RUN_TESTS.md — running the test suite
- MULTI_ROOT_WORKSPACE_SETUP.md — multi-repo workspace
- MIGRATION_GUIDE.md — breaking changes between releases
Archive
docs/archive/ holds older guides that have been superseded or describe
features that have been removed. They are kept for historical context and
git history but should not be relied on.
Contributing to the docs
- Markdown only, professional tone, minimal emoji.
- Prefer adding to an existing page over creating a new one. If you add a new page, link it from this index in the section it belongs to.
- If a page becomes obsolete, move it to
docs/archive/rather than deleting it, so links don't rot. - Keep examples runnable — paths, commands, and config keys here should match what's actually in the repo.