scrollkit 0.8.3__py3-none-any.whl

scrollkit/app/memory.py

@@ -0,0 +1,70 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Realistic free-RAM estimate shared by the run loop and the dev harness.
+
+The run loop gates optional processes on free RAM (data updates need ~20-30 KB,
+the web server ~50 KB). On real CircuitPython that comes from ``gc.mem_free()``.
+On the desktop simulator there is no such limit, so historically these sites just
+pretended ~100 KB was free — which means an AI agent verifying an app on the
+simulator never sees the low-memory code paths a real MatrixPortal S3 would hit.
+
+``free_memory()`` keeps that generous desktop default UNLESS the hardware-realism
+simulation is active (``SimulatorDisplay(hardware_timing=True)`` /
+``SCROLLKIT_HW_SIM=1``), in which case it reports the modeled *device* budget
+minus the modeled live allocation. So the existing 20/30/50 KB ladder actually
+gates against the device's tiny RAM during a simulated run, and the feasibility
+report's "won't fit" warning lines up with what the loop decided.
+
+Default behavior is unchanged: on hardware it's the real number; on desktop with
+the sim OFF it's the same large constant as before.
+
+Device-safe: ``gc`` is the only hard import; the simulator lookup is wrapped so it
+never fails on CircuitPython (where the simulator package isn't present).
+"""
+
+import gc
+
+# Free RAM reported on desktop when the hardware sim is OFF. Matches the literal
+# previously hard-coded across app/base.py, so default behavior is unchanged.
+DESKTOP_FREE_BYTES = 100_000
+
+
+__all__ = ['free_memory', 'DESKTOP_FREE_BYTES']
+
+def free_memory():
+    """Best estimate of free RAM in bytes.
+
+    - CircuitPython hardware: the real ``gc.mem_free()``.
+    - Desktop + hardware sim ON: modeled device budget minus modeled usage.
+    - Desktop + hardware sim OFF: ``DESKTOP_FREE_BYTES`` (no behavior change).
+    """
+    if hasattr(gc, "mem_free"):
+        # Real hardware (or any build exposing mem_free) — trust the device.
+        try:
+            return gc.mem_free()
+        except Exception:
+            pass
+    modeled = _modeled_free_memory()
+    if modeled is not None:
+        return modeled
+    return DESKTOP_FREE_BYTES
+
+
+def _modeled_free_memory():
+    """Free RAM implied by the active hardware PerformanceManager, or None.
+
+    The import lives entirely inside the (desktop-only) simulator package; any
+    failure simply means "no hardware model active" and we fall back.
+    """
+    try:
+        from ..simulator.core.performance_manager import get_active
+    except Exception:
+        return None
+    manager = get_active()
+    if manager is None:
+        return None
+    try:
+        budget = manager.profile.usable_ram_bytes
+        used = manager.estimated_peak_ram_bytes()
+        return max(0, budget - used)
+    except Exception:
+        return None

scrollkit/config/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger

scrollkit/config/settings_manager.py

@@ -0,0 +1,215 @@
+"""
+Settings manager for handling user configuration.
+Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""
+import json
+
+from scrollkit.config.transition_names import TRANSITION_NAMES
+
+
+__all__ = ['SettingsManager']
+
+def _logger():
+    # Lazy: constructing ErrorHandler does a filesystem write-test, so it must
+    # not run merely from importing this module. Its own __new__ singleton
+    # guard makes repeat calls cheap.
+    from scrollkit.utils.error_handler import ErrorHandler
+    return ErrorHandler("error_log")
+
+
+class SettingsManager:
+    """
+    Manages application settings with persistence to a JSON file.
+
+    Applications can register their own defaults by calling
+    set_defaults({'key': value, ...}) after construction.
+    """
+
+    def __init__(self, filename, defaults=None, bool_keys=None):
+        """
+        Initialize the settings manager.
+
+        Args:
+            filename: The name of the settings file
+            defaults: Optional dict of default settings
+            bool_keys: Optional list of keys that should be treated as booleans
+                       (needed because CircuitPython's JSON parser may store them as strings)
+        """
+        self.filename = filename
+        self.settings = self.load_settings()
+        self.scroll_speed = {"Slow": 0.06, "Medium": 0.04, "Fast": 0.02}
+        self._bool_keys = bool_keys or []
+        self._schema = []
+
+        # Built-in library settings — always defined so the default web UI shows them.
+        self.define("brightness_scale", 0.5, label="Brightness", min=0.0, max=1.0, step=0.05)
+        self.define("scroll_speed", "Medium", label="Scroll Speed",
+                    options=["None", "Slow", "Medium", "Fast"])
+        self.define("default_color", 0xFFFFFF, label="Default Color", type="color")
+        # Choices derive from the single source of truth (config.transition_names),
+        # which the dispatch map in effects.transitions is tested to match — so a
+        # selectable name can never silently fail to dispatch. Plain "None" + list
+        # concatenation (no *-unpacking) for CircuitPython-parser safety.
+        self.define("transition_style", "None", label="Transition Style",
+                    options=["None"] + list(TRANSITION_NAMES))
+
+        # Apply application-provided defaults
+        if defaults:
+            self.set_defaults(defaults)
+
+    def define(self, key, default, label=None, type=None, options=None,
+               min=None, max=None, step=None):
+        """Declare a setting with display metadata for the auto-generating web UI.
+
+        The UI renders a form field for every defined setting in the order they
+        were declared. Type is inferred from the default value when not given:
+        bool -> checkbox, options list -> select, min/max -> range,
+        int/float -> number, else text.  Use type="color" explicitly for
+        colour pickers (stored as int 0xRRGGBB).
+
+        Args:
+            key: Settings key (used as the form field name)
+            default: Default value (only applied when no saved value exists)
+            label: Human-readable label; defaults to title-cased key name
+            type: Field type override ("text","number","range","color","select","checkbox")
+            options: List of string choices (implies type="select")
+            min: Numeric lower bound for range/number inputs
+            max: Numeric upper bound for range/number inputs
+            step: Numeric step for range/number inputs
+        """
+        if type is not None:
+            resolved_type = type
+        elif options:
+            resolved_type = "select"
+        elif min is not None or max is not None:
+            resolved_type = "range"
+        elif isinstance(default, bool):  # must check before int (bool subclasses int)
+            resolved_type = "checkbox"
+        elif isinstance(default, (int, float)):
+            resolved_type = "number"
+        else:
+            resolved_type = "text"
+
+        resolved_label = label if label is not None else SettingsManager.get_pretty_name(key)
+
+        self._schema.append({
+            "key": key,
+            "label": resolved_label,
+            "type": resolved_type,
+            "default": default,
+            "options": options,
+            "min": min,
+            "max": max,
+            "step": step,
+        })
+
+        if resolved_type == "checkbox":
+            self.add_bool_keys(key)
+
+        self.set_defaults({key: default})
+
+    def set_defaults(self, defaults):
+        """
+        Register application-specific defaults. Only sets values that
+        are not already present in settings.
+
+        Args:
+            defaults: Dict of {key: default_value}
+        """
+        for key, value in defaults.items():
+            if key not in self.settings:
+                self.settings[key] = value
+
+    def add_bool_keys(self, *keys):
+        """Register additional keys that should be treated as booleans."""
+        for key in keys:
+            if key not in self._bool_keys:
+                self._bool_keys.append(key)
+
+    def get_scroll_speed(self):
+        """Return scroll speed in seconds per pixel (for timing loops)."""
+        return self.scroll_speed.get(
+            self.settings.get("scroll_speed", "Medium"), 0.04
+        )
+
+    def get_scroll_speed_px(self):
+        """Return scroll speed in pixels per second (for ScrollingText speed= arg).
+
+        Returns 0 when scroll_speed is "None" — ScrollingText treats 0 as
+        static-display mode: text is shown centred for a fixed duration rather
+        than scrolling.
+        """
+        if self.settings.get("scroll_speed", "Medium") == "None":
+            return 0
+        secs = self.get_scroll_speed()
+        return int(round(1.0 / secs)) if secs > 0 else 25
+
+    @staticmethod
+    def get_pretty_name(settings_name):
+        """
+        Convert a settings key to a display-friendly name.
+
+        Args:
+            settings_name: The settings key
+
+        Returns:
+            A display-friendly name
+        """
+        new_name = settings_name.replace("_", " ")
+        return " ".join(word[0].upper() + word[1:] for word in new_name.split(' '))
+
+    def load_settings(self):
+        """
+        Load settings from the settings file.
+
+        Returns:
+            A dictionary of settings
+        """
+        _logger().info(f"Loading settings {self.filename}")
+        try:
+            with open(self.filename, 'r') as f:
+                return json.load(f)
+        except (OSError, ValueError):
+            # OSError: missing file. ValueError: corrupt JSON — CircuitPython's
+            # json.load raises ValueError (there is no JSONDecodeError), and a
+            # truncated flash write must not brick boot.
+            return {}
+
+    def save_settings(self):
+        """Save settings to the settings file"""
+        _logger().info(f"Saving settings {self.filename}")
+        try:
+            with open(self.filename, 'w') as f:
+                json.dump(self.settings, f)
+        except OSError as e:
+            _logger().error(e, f"Error saving settings to {self.filename}")
+
+    def get(self, key, default=None):
+        """
+        Get a setting by key with a default value.
+
+        Args:
+            key: The settings key
+            default: The default value if the key is not found
+
+        Returns:
+            The setting value, or the default if not found
+        """
+        value = self.settings.get(key, default)
+
+        # Special handling for boolean settings that might be stored as strings
+        # This can happen with CircuitPython's JSON parser
+        if key in self._bool_keys and isinstance(value, str):
+            return value.lower() == "true"
+
+        return value
+
+    def set(self, key, value):
+        """
+        Set a setting by key.
+
+        Args:
+            key: The settings key
+            value: The value to set
+        """
+        self.settings[key] = value

scrollkit/config/transition_names.py

@@ -0,0 +1,31 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Canonical list of built-in transition names — the single source of truth.
+
+This module is **literal-only**: it imports nothing, so it is safe to import on
+the device boot path (e.g. from ``settings_manager``) without dragging in the
+heavy ``scrollkit.effects`` package. The name -> class dispatch lives in
+``scrollkit.effects.transitions`` (``_TRANSITION_MAP`` / ``transition_factory``);
+``test_transition_registry`` asserts the two stay in lockstep, in this order.
+
+Order is UI-facing: the settings dropdown / web form render the choices in this
+order (with ``"None"`` prepended), so do not reorder casually.
+"""
+
+TRANSITION_NAMES = (
+    "Drop from Sky",
+    "Pixel Dissolve",
+    "Column Rain",
+    "Gradual Reveal",
+    "Scan Fold",
+    "Horizontal Wipe",
+    "Glitch Bars",
+    "Diagonal Wipe",
+    "Iris Snap",
+    "Venetian Shutters",
+    "Mosaic Resolve",
+    "CRT Collapse",
+    "Light Slit",
+)
+
+
+__all__ = ['TRANSITION_NAMES']

scrollkit/dev/__init__.py

@@ -0,0 +1,41 @@
+# Copyright (c) 2024-2026 Michael Winslow Czeiszperger
+"""Desktop-only developer / AI-agent affordances for ScrollKit.
+
+Everything here exists to help a human or an AI agent build and *verify* a
+ScrollKit app on the desktop simulator before flashing it to real hardware:
+a headless run harness, pixel metrics, and (via the simulator package) an honest
+estimate of how the app would perform on the slow, RAM-constrained MatrixPortal
+S3.
+
+This subpackage is **never** meant to run on the device. It pulls in numpy,
+pygame, and other desktop-only machinery that would waste scarce RAM (or simply
+not import) on CircuitPython. Importing it there raises ImportError immediately,
+on purpose, so device code can't accidentally depend on it. Nothing in
+``scrollkit`` core (``app/``, ``display/``, the top-level ``__init__``) imports
+this module.
+"""
+
+import sys
+
+# Hard stop on CircuitPython — these tools are desktop-only by design.
+if getattr(sys, "implementation", None) is not None \
+        and getattr(sys.implementation, "name", None) == "circuitpython":
+    raise ImportError(
+        "scrollkit.dev is a desktop-only development/verification toolkit and "
+        "cannot run on CircuitPython. Use it from the desktop simulator to "
+        "build and check apps before deploying to the device."
+    )
+
+from .harness import (  # noqa: E402
+    RunResult, run_headless, run_headless_async, record_gif, record_video)
+from .capabilities import capabilities, as_text  # noqa: E402
+from .validation import validate, ValidationReport, Issue  # noqa: E402
+from .performance import performance_guide, performance_text  # noqa: E402
+from . import metrics  # noqa: E402,F401
+
+__all__ = [
+    "RunResult", "run_headless", "run_headless_async", "record_gif",
+    "record_video", "metrics",
+    "capabilities", "as_text", "validate", "ValidationReport", "Issue",
+    "performance_guide", "performance_text",
+]