mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 13:02:59 +00:00

Files

Chuck 23f0176c18 feat: add dev preview server and CLI render script (#264 )

* fix(web): wire up "Check & Update All" plugins button

window.updateAllPlugins was never assigned, so the button always showed
"Bulk update handler unavailable." Wire it to PluginInstallManager.updateAll(),
add per-plugin progress feedback in the button text, show a summary
notification on completion, and skip redundant plugin list reloads.

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

* feat: add dev preview server, CLI render script, and visual test display manager

Adds local development tools for rapid plugin iteration without deploying to RPi:

- VisualTestDisplayManager: renders real pixels via PIL (same fonts/interface as production)
- Dev preview server (Flask): interactive web UI with plugin picker, auto-generated config
  forms, zoom/grid controls, and mock data support for API-dependent plugins
- CLI render script: render any plugin to PNG for AI-assisted visual feedback loops
- Updated test runner and conftest to auto-detect plugin-repos/ directory

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

* fix(dev-preview): address code review issues

- Use get_logger() from src.logging_config instead of logging.getLogger()
  in visual_display_manager.py to match project logging conventions
- Eliminate duplicate public/private weather draw methods — public draw_sun/
  draw_cloud/draw_rain/draw_snow now delegate to the private _draw_* variants
  so plugins get consistent pixel output in tests vs production
- Default install_deps=False in dev_server.py and render_plugin.py — dev
  scripts don't need to run pip install; developers are expected to have
  plugin deps installed in their venv already
- Guard plugins_dir fixture against PermissionError during directory iteration
- Fix PluginInstallManager.updateAll() to fall back to window.installedPlugins
  when PluginStateManager.installedPlugins is empty (plugins_manager.js
  populates window.installedPlugins independently of PluginStateManager)
- Remove 5 debug console.log statements from plugins_manager.js button setup
  and initialization code

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(scroll): fix scroll completion to prevent multi-pass wrapping

Change required_total_distance from total_scroll_width + display_width to
total_scroll_width alone. The scrolling image already contains display_width
pixels of blank initial padding, so reaching total_scroll_width means all
content has scrolled off-screen. The extra display_width term was causing
1-2+ unnecessary wrap-arounds, making the same games appear multiple times
and producing a black flicker between passes.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(dev-preview): address PR #264 code review findings

- docs/DEV_PREVIEW.md: add bash language tag to fenced code block
- scripts/dev_server.py: add MAX/MIN_WIDTH/HEIGHT constants and validate
  width/height in render endpoint; add structured logger calls to
  discover_plugins (missing dirs, hidden entries, missing manifest,
  JSON/OS errors, duplicate ids); add type annotations to all helpers
- scripts/render_plugin.py: add MIN/MAX_DIMENSION validation after
  parse_args; replace prints with get_logger() calls; narrow broad
  Exception catches to ImportError/OSError/ValueError in plugin load
  block; add type annotations to all helpers and main(); rename unused
  module binding to _module
- scripts/run_plugin_tests.py: wrap plugins_path.iterdir() in
  try/except PermissionError with fallback to plugin-repos/
- scripts/templates/dev_preview.html: replace non-focusable div toggles
  with button role="switch" + aria-checked; add keyboard handlers
  (Enter/Space); sync aria-checked in toggleGrid/toggleAutoRefresh
- src/common/scroll_helper.py: early-guard zero total_scroll_width to
  keep scroll_position at 0 and skip completion/wrap logic
- src/plugin_system/testing/visual_display_manager.py: forward color
  arg in draw_cloud -> _draw_cloud; add color param to _draw_cloud;
  restore _scrolling_state in reset(); narrow broad Exception catches in
  _load_fonts to FileNotFoundError/OSError/ImportError; add explicit
  type annotations to draw_text
- test/plugins/test_visual_rendering.py: use context manager for
  Image.open in test_save_snapshot
- test/plugins/conftest.py: add return type hints to all fixtures

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* chore: add bandit and gitleaks pre-commit hooks

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Chuck <chuck@example.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-24 17:57:42 -05:00

README.md

LEDMatrix Documentation

Welcome to the LEDMatrix documentation! This directory contains comprehensive guides, specifications, and reference materials for the LEDMatrix project.

📚 Documentation Overview

This documentation has been recently consolidated (January 2026) to reduce redundancy while maintaining comprehensive coverage. We've reduced from 51 main documents to 16-17 well-organized files (~68% reduction) by merging duplicates, archiving ephemeral content, and unifying writing styles.

📖 Quick Start

For New Users

Installation: Follow the main README.md in the project root
First Setup: See GETTING_STARTED.md for first-time setup guide
Web Interface: Use WEB_INTERFACE_GUIDE.md to learn the control panel
Troubleshooting: Check TROUBLESHOOTING.md for common issues

For Developers

Plugin Development: See PLUGIN_DEVELOPMENT_GUIDE.md for complete guide
Advanced Patterns: Read ADVANCED_PLUGIN_DEVELOPMENT.md for advanced techniques
API Reference: Check PLUGIN_API_REFERENCE.md for available methods
Configuration: See PLUGIN_CONFIGURATION_GUIDE.md for config schemas

For API Integration

REST API: See REST_API_REFERENCE.md for all web interface endpoints
Plugin API: See PLUGIN_API_REFERENCE.md for plugin developer APIs
Developer Reference: See DEVELOPER_QUICK_REFERENCE.md for common tasks

📋 Documentation Categories

🚀 Getting Started & User Guides

GETTING_STARTED.md - First-time setup and quick start guide
WEB_INTERFACE_GUIDE.md - Complete web interface user guide
WIFI_NETWORK_SETUP.md - WiFi configuration and AP mode setup
PLUGIN_STORE_GUIDE.md - Installing and managing plugins
TROUBLESHOOTING.md - Common issues and solutions

⚡ Advanced Features

ADVANCED_FEATURES.md - Vegas scroll mode, on-demand display, cache management, background services, permissions

🔌 Plugin Development

PLUGIN_DEVELOPMENT_GUIDE.md - Complete plugin development workflow
PLUGIN_QUICK_REFERENCE.md - Plugin development quick reference
ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns and examples
PLUGIN_CONFIGURATION_GUIDE.md - Configuration schema design
PLUGIN_CONFIGURATION_TABS.md - Configuration tabs feature
PLUGIN_CONFIG_QUICK_START.md - Quick configuration guide
PLUGIN_DEPENDENCY_GUIDE.md - Managing plugin dependencies
PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency troubleshooting

🏗️ Plugin Features & Extensions

PLUGIN_CUSTOM_ICONS.md - Custom plugin icons
PLUGIN_CUSTOM_ICONS_FEATURE.md - Custom icons implementation
PLUGIN_IMPLEMENTATION_SUMMARY.md - Plugin system implementation
PLUGIN_REGISTRY_SETUP_GUIDE.md - Setting up plugin registry
PLUGIN_WEB_UI_ACTIONS.md - Web UI actions for plugins

📡 API Reference

REST_API_REFERENCE.md - Complete REST API documentation (71+ endpoints)
PLUGIN_API_REFERENCE.md - Plugin developer API (Display Manager, Cache Manager, Plugin Manager)
DEVELOPER_QUICK_REFERENCE.md - Quick reference for common developer tasks

🏛️ Architecture & Design

PLUGIN_ARCHITECTURE_SPEC.md - Complete plugin system specification
PLUGIN_CONFIG_ARCHITECTURE.md - Configuration system architecture
PLUGIN_CONFIG_CORE_PROPERTIES.md - Core configuration properties

🛠️ Development & Tools

DEVELOPMENT.md - Development environment setup
EMULATOR_SETUP_GUIDE.md - Set up development environment with emulator
HOW_TO_RUN_TESTS.md - Testing documentation
MULTI_ROOT_WORKSPACE_SETUP.md - Multi-workspace development
FONT_MANAGER.md - Font management system

🔄 Migration & Updates

MIGRATION_GUIDE.md - Breaking changes and migration instructions
SSH_UNAVAILABLE_AFTER_INSTALL.md - SSH troubleshooting after install

📚 Miscellaneous

widget-guide.md - Widget development guide
Template files:
- plugin_registry_template.json - Plugin registry template
- PLUGIN_WEB_UI_ACTIONS_EXAMPLE.json - Web UI actions example

🎯 Key Resources by Use Case

I'm new to LEDMatrix

GETTING_STARTED.md - Start here for first-time setup
WEB_INTERFACE_GUIDE.md - Learn the control panel
PLUGIN_STORE_GUIDE.md - Install plugins

I want to create a plugin

PLUGIN_DEVELOPMENT_GUIDE.md - Complete development guide
PLUGIN_API_REFERENCE.md - Available methods and APIs
ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns
PLUGIN_CONFIGURATION_GUIDE.md - Configuration setup
PLUGIN_ARCHITECTURE_SPEC.md - Complete specification

I need to troubleshoot an issue

TROUBLESHOOTING.md - Comprehensive troubleshooting guide
WIFI_NETWORK_SETUP.md - WiFi/network issues
PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency issues

I want to use advanced features

ADVANCED_FEATURES.md - Vegas scroll, on-demand display, background services
FONT_MANAGER.md - Font management
REST_API_REFERENCE.md - API integration

I want to understand the architecture

PLUGIN_ARCHITECTURE_SPEC.md - System architecture
PLUGIN_CONFIG_ARCHITECTURE.md - Configuration architecture
PLUGIN_IMPLEMENTATION_SUMMARY.md - Implementation details

🔄 Recent Consolidations (January 2026)

Major Consolidation Effort

Before: 51 main documentation files
After: 16-17 well-organized files
Reduction: ~68% fewer files
Archived: 33 files (consolidated sources + ephemeral docs)

New Consolidated Guides

GETTING_STARTED.md - New first-time user guide
WEB_INTERFACE_GUIDE.md - Consolidated web interface documentation
WIFI_NETWORK_SETUP.md - Consolidated WiFi setup (5 files → 1)
PLUGIN_STORE_GUIDE.md - Consolidated plugin store guides (2 files → 1)
TROUBLESHOOTING.md - Consolidated troubleshooting (4 files → 1)
ADVANCED_FEATURES.md - Consolidated advanced features (6 files → 1)

What Was Archived

Ephemeral debug documents (DEBUG_WEB_ISSUE.md, BROWSER_ERRORS_EXPLANATION.md, etc.)
Implementation summaries (PLUGIN_CONFIG_TABS_SUMMARY.md, STARTUP_OPTIMIZATION_SUMMARY.md, etc.)
Consolidated source files (WIFI_SETUP.md, V3_INTERFACE_README.md, etc.)
Testing documentation (CAPTIVE_PORTAL_TESTING.md, etc.)

All archived files are preserved in docs/archive/ with full git history.

Benefits

✅ Easier to find information (fewer files to search)
✅ No duplicate content
✅ Consistent writing style (professional technical)
✅ Updated outdated references
✅ Fixed broken internal links
✅ Better organization for users vs developers

📝 Contributing to Documentation

Documentation Standards

Use Markdown format with consistent headers
Professional technical writing style
Minimal emojis (1-2 per major section for navigation)
Include code examples where helpful
Provide both quick start and detailed reference sections
Cross-reference related documentation

Adding New Documentation

Consider if content should be added to existing docs first
Place in appropriate category (see sections above)
Update this README.md with the new document
Follow naming conventions (FEATURE_NAME.md)
Use consistent formatting and voice

Consolidation Guidelines

User Guides: Consolidate by topic (WiFi, troubleshooting, etc.)
Developer Guides: Keep development vs reference vs architecture separate
Debug Documents: Archive after issues are resolved
Implementation Summaries: Archive completed implementation details
Ephemeral Content: Archive, don't keep in main docs

Main Project README - Installation and basic usage
Web Interface README - Web interface details
GitHub Issues - Bug reports and feature requests
GitHub Discussions - Community support

📊 Documentation Statistics

Main Documents: 16-17 files (after consolidation)
Archived Documents: 33 files (in docs/archive/)
Categories: 9 major sections
Primary Language: English
Format: Markdown (.md)
Last Major Update: January 2026
Coverage: Installation, user guides, development, troubleshooting, architecture, API references

Documentation Highlights

✅ Comprehensive user guides for first-time setup
✅ Complete REST API documentation (71+ endpoints)
✅ Complete Plugin API reference (Display Manager, Cache Manager, Plugin Manager)
✅ Advanced plugin development guide with examples
✅ Consolidated configuration documentation
✅ Professional technical writing throughout
✅ ~68% reduction in file count while maintaining coverage

This documentation index was last updated: January 2026

For questions or suggestions about the documentation, please open an issue or start a discussion on GitHub.