feat(plugins): adaptive-lib discoverability + advisory version compat warning

Discoverability: re-export the adaptive layout/image API from src.common
(the blessed-helpers package plugin authors already know) — canonical
paths stay src.adaptive_layout / src.adaptive_images so nothing breaks.
Document it in src/common/README.md and cross-link ADAPTIVE_LAYOUT.md
from the developer docs authors actually read (quick reference, API
reference, advanced dev, font manager, dev preview, plugin dev guide);
ADAPTIVE_LAYOUT.md gains adaptive-images, composite-layouts and
preserving-user-customization sections.

Compat: PluginLoader now logs one advisory warning (never raises) when a
plugin's manifest declares a min LEDMatrix version newer than the running
core, checking the min_ledmatrix_version / requires.* / versions[]
spellings found in the wild. Guarded against stale core version numbers.

src/__init__.py __version__ bumped 1.0.0 -> 3.1.0 to match the latest
release tag (v3.1.0) — it had never been updated and the compat check
needs a truthful number. NOTE: verify this matches the intended release
numbering before the next tag.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/__init__.py

@@ -4,5 +4,5 @@ LEDMatrix Display System
 Core source package for the LED Matrix Display project.
 """
 
-__version__ = "1.0.0"
+__version__ = "3.1.0"
 

src/common/README.md

@@ -2,6 +2,28 @@
 
 This directory contains reusable utilities and helpers for LEDMatrix plugins and core modules.
 
+## Adaptive Layout & Images (`src/adaptive_layout.py`, `src/adaptive_images.py`)
+
+The recommended way to lay out plugins that render legibly on **any** panel
+size (64x32 through 256x128+) without hand-tuned coordinates. Re-exported
+from `src.common` for convenience; canonical import paths are
+`src.adaptive_layout` / `src.adaptive_images`.
+
+```python
+# Every BasePlugin already has self.layout and the draw helpers:
+regs = scoreboard_regions(self.layout.bounds, ctx=self.layout)
+self.draw_image(away_logo, regs.away_slot, mode="fill_height",
+                crop_to_ink=True, cache_key=f"logo:{abbr}")
+self.draw_fit(score_text, regs.score_area)     # largest crisp font that fits
+self.draw_fit(status, regs.status_band)
+```
+
+Key pieces: `Region` (rect algebra: bands/columns/splits/offset),
+font ladders (`LADDER_GRID`, `LADDER_ARCADE` — discrete crisp sizes, never
+fractional scaling), `LayoutContext` (`fit_text`, `fit_image`, `by_tier`,
+`px`), and composite carvers `scoreboard_regions()` / `media_row()`.
+Full guide: [docs/ADAPTIVE_LAYOUT.md](../../docs/ADAPTIVE_LAYOUT.md).
+
 ## Error Handling (`error_handler.py`)
 
 Common error handling patterns and utilities:

src/common/__init__.py

@@ -26,6 +26,31 @@ from src.common.scroll_helper import ScrollHelper
 from src.common.logo_helper import LogoHelper
 from src.common.text_helper import TextHelper
 
+# Adaptive layout & images (canonical homes: src.adaptive_layout /
+# src.adaptive_images — re-exported here so plugin authors find them in the
+# blessed-helpers package). See docs/ADAPTIVE_LAYOUT.md.
+from src.adaptive_layout import (
+    Region,
+    LayoutContext,
+    FontStep,
+    FontLadder,
+    LADDER_GRID,
+    LADDER_ARCADE,
+    FitResult,
+    draw_fitted_text,
+    ScoreboardRegions,
+    scoreboard_regions,
+    MediaRow,
+    media_row,
+)
+from src.adaptive_images import (
+    ImageFitResult,
+    fit_image,
+    draw_fitted_image,
+    RESAMPLE_LANCZOS,
+    RESAMPLE_NEAREST,
+)
+
 __all__ = [
     'handle_file_operation',
     'handle_json_operation',
@@ -37,4 +62,22 @@ __all__ = [
     'ScrollHelper',
     'LogoHelper',
     'TextHelper',
+    # adaptive layout & images
+    'Region',
+    'LayoutContext',
+    'FontStep',
+    'FontLadder',
+    'LADDER_GRID',
+    'LADDER_ARCADE',
+    'FitResult',
+    'draw_fitted_text',
+    'ScoreboardRegions',
+    'scoreboard_regions',
+    'MediaRow',
+    'media_row',
+    'ImageFitResult',
+    'fit_image',
+    'draw_fitted_image',
+    'RESAMPLE_LANCZOS',
+    'RESAMPLE_NEAREST',
 ]

src/plugin_system/plugin_loader.py

@@ -683,6 +683,55 @@ class PluginLoader:
             self.logger.error(error_msg, exc_info=True)
             raise PluginError(error_msg, plugin_id=plugin_id) from e
     
+    @staticmethod
+    def _parse_semver(value: Any) -> Optional[Tuple[int, int, int]]:
+        """Parse 'X.Y.Z' (extra parts/suffixes ignored) into a comparable
+        3-tuple, or None when unparseable."""
+        if not isinstance(value, str):
+            return None
+        parts = value.strip().lstrip('v').split('.')
+        try:
+            nums = [int(''.join(ch for ch in p if ch.isdigit()) or 0) for p in parts[:3]]
+        except ValueError:
+            return None
+        while len(nums) < 3:
+            nums.append(0)
+        return tuple(nums)  # type: ignore[return-value]
+
+    def _warn_if_incompatible(self, plugin_id: str, manifest: Dict[str, Any]) -> None:
+        """Log one warning when a plugin declares a minimum LEDMatrix version
+        newer than the running core. Advisory only — never raises — so a
+        plugin that guards optional features with try/except keeps working.
+        """
+        declared = (
+            manifest.get('min_ledmatrix_version')
+            or manifest.get('requires', {}).get('min_ledmatrix_version')
+        )
+        if not declared:
+            versions = manifest.get('versions') or []
+            if versions and isinstance(versions[0], dict):
+                declared = (versions[0].get('ledmatrix_min_version')
+                            or versions[0].get('ledmatrix_min'))
+        needed = self._parse_semver(declared)
+        if needed is None:
+            return
+
+        from src import __version__ as core_version
+        current = self._parse_semver(core_version)
+        # Anti-spam guard: if the core's own version number is stale (below
+        # the ecosystem floor every shipped plugin declares), comparing would
+        # warn on nearly everything — skip with a debug note instead.
+        if current is None or current < (2, 0, 0):
+            self.logger.debug(
+                "Skipping version compatibility check for %s: core __version__ "
+                "(%s) is below the ecosystem floor", plugin_id, core_version)
+            return
+        if needed > current:
+            self.logger.warning(
+                "Plugin %s declares min LEDMatrix version %s but this core is %s — "
+                "features it relies on may be missing; update the core or expect "
+                "degraded fallbacks", plugin_id, declared, core_version)
+
     def load_plugin(
         self,
         plugin_id: str,
@@ -715,6 +764,8 @@ class PluginLoader:
         Raises:
             PluginError: If loading fails
         """
+        self._warn_if_incompatible(plugin_id, manifest)
+
         # Install dependencies if needed
         if install_deps:
             if plugins_dir is None: