"""Helpers for 16x16 serpentine NeoPixel panel animations.

Mapping matches the simulator's 16x16 mode:
- first LED at top-right
- row 0 goes right -> left
- row 1 goes left -> right
"""

from __future__ import annotations


PANEL_W = 16
PANEL_H = 16


def xy_to_index(x: int, y: int, width: int = PANEL_W) -> int:
    """Map panel coordinate (x, y) to LED index."""
    x = int(x)
    y = int(y)
    if y % 2 == 0:
        return y * width + (width - 1 - x)
    return y * width + x


def clamp8(v: int) -> int:
    return max(0, min(255, int(v)))