xnano.components.image

@classmethod
def from_bytes(cls, data: bytes) -> ImageData:
    """Decode xnano's compact, Pillow-free animation container.

    Args:
        data: Bytes produced by ``scripts/precompute_demo_image.py``.

    Returns:
        Decoded full-resolution RGB image data.
    """
    if data[:4] != b"XNI1":
        raise ValueError("Image data does not have an XNI1 header.")
    try:
        width, height, frame_count = struct.unpack_from(">HHH", data, 4)
        offset = 10
        frames: list[ImageFrame] = []
        pixel_count = width * height
        for _ in range(frame_count):
            duration_ms, color_count, compressed_size = struct.unpack_from(
                ">HHI", data, offset
            )
            offset += 8
            palette_size = color_count * 3
            palette = data[offset : offset + palette_size]
            offset += palette_size
            compressed = data[offset : offset + compressed_size]
            offset += compressed_size
            indexes = zlib.decompress(compressed)
            if len(indexes) != pixel_count:
                raise ValueError("Image frame has an invalid pixel count.")
            pixels = bytearray(pixel_count * 3)
            for pixel_index, color_index in enumerate(indexes):
                palette_offset = color_index * 3
                pixel_offset = pixel_index * 3
                pixels[pixel_offset : pixel_offset + 3] = palette[
                    palette_offset : palette_offset + 3
                ]
            frames.append(ImageFrame(bytes(pixels), max(10, duration_ms)))
    except (struct.error, zlib.error) as error:
        raise ValueError("Image data is truncated or corrupt.") from error
    if offset != len(data):
        raise ValueError("Image data contains unexpected trailing bytes.")
    return cls(width=width, height=height, frames=tuple(frames))

def component_post_init(self) -> None:
    """Validate configuration and decode the initial source."""
    self._validate_configuration()
    self._decode_source()

def play(self) -> None:
    """Resume animation from the current playback position."""
    if self.playing:
        return
    self.playing = True
    # Preserve paused position across resume.
    self._started_at_ns = time.monotonic_ns() - round(
        self._paused_elapsed_ms * 1_000_000
    )

def pause(self) -> None:
    """Freeze animation at the current playback position."""
    if not self.playing:
        return
    self._paused_elapsed_ms = self._get_elapsed_ms()
    self.playing = False

def restart(self) -> None:
    """Restart animation timing at the next render."""
    self._started_at_ns = None
    self._paused_elapsed_ms = 0.0
    self.position_ms = None

def seek(self, position_ms: float) -> None:
    """Move playback to a source timestamp without delaying a render.

    Args:
        position_ms: Source animation timestamp in milliseconds.
    """
    wall_elapsed_ms = max(0.0, position_ms) / self.speed
    self._paused_elapsed_ms = wall_elapsed_ms
    self.position_ms = None
    if self.playing:
        self._started_at_ns = time.monotonic_ns() - round(
            wall_elapsed_ms * 1_000_000
        )
    else:
        self._started_at_ns = None

def get_frame_index(self, elapsed_ms: float) -> int:
    """Return the source frame active at an elapsed playback time.

    Args:
        elapsed_ms: Playback time in milliseconds.

    Returns:
        The zero-based active frame index.
    """
    self._ensure_decoded()
    if len(self._frames) == 1:
        return 0
    position = max(0, int(elapsed_ms * self.speed))
    if self.loop:
        position %= self._duration_ms
    else:
        position = min(position, self._duration_ms - 1)
    for frame_index, frame_end in enumerate(self._frame_ends_ms):
        if position < frame_end:
            return frame_index
    return len(self._frames) - 1

def get_size(self, ctx: ComponentRenderContext) -> Size:
    """Return the native terminal cell dimensions of the source."""
    self._ensure_decoded()
    frame = self._frames[0]
    if self.correct_terminal_aspect:
        width = frame.width
    else:
        width = math.ceil(frame.width / self.horizontal_pixels_per_cell)
    return Size(
        width=width,
        height=math.ceil(frame.height / 2),
    )

def compose(self, ctx: ComponentRenderContext) -> CellCanvas:
    """Compose the current timed frame for the target terminal area."""
    self._ensure_decoded()
    elapsed_ms = self._get_elapsed_ms()
    if self.playing:
        self._paused_elapsed_ms = elapsed_ms
    frame_index = self.get_frame_index(elapsed_ms)
    source = self._frames[frame_index]
    if self.correct_terminal_aspect:
        native_width = source.width
    else:
        native_width = math.ceil(
            source.width / self.horizontal_pixels_per_cell
        )
    width = max(1, ctx.area.width or native_width)
    height = max(1, ctx.area.height or math.ceil(source.height / 2))
    cache_key = (
        frame_index,
        width,
        height,
        self.fit,
        self.horizontal_pixels_per_cell,
        self.correct_terminal_aspect,
    )
    if cache_key == self._cached_key and self._cached_canvas is not None:
        return self._cached_canvas
    fitted_width = width
    if not self.correct_terminal_aspect:
        fitted_width *= self.horizontal_pixels_per_cell
    fitted = _fit_frame(
        source,
        fitted_width,
        height * 2,
        self.fit,
        self.background,
    )
    if (
        self.correct_terminal_aspect
        and self.horizontal_pixels_per_cell == 2
    ):
        fitted = _resize_frame(
            fitted,
            fitted.width * 2,
            fitted.height,
        )
    canvas = _get_frame_as_canvas(
        fitted,
        self.horizontal_pixels_per_cell,
    )
    result = CellCanvas(
        width=canvas.width,
        height=canvas.height,
        rows=canvas.rows,
        z=self.z,
        visible=self.visible,
    )
    self._cached_key = cache_key
    self._cached_canvas = result
    return result

def get_frame(self) -> Any | None:
    """Optional frame/panel chrome around composed content."""
    return None

def before_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> "Area":
    """Called before rendering; returns the effective render area."""
    return area

def after_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> None:
    """Called after rendering for optional post-paint work."""
    return None

@responsive_noop
def compose_extra_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`compose`. When
    overridden, it is used *instead of* ``compose`` while the window
    is in this size tier. Overriding any ``compose_*`` variant opts the
    component into breakpoint dispatch; a component that overrides none
    pays no per-frame cost.
    """
    return None

@responsive_noop
def compose_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is small (40–79 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_medium(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is medium (80–119 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is large (120–159 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_extra_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra large (>= 160 cols).

    See :meth:`compose_extra_small`.
    """
    return None

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Optional keyboard handler while focused.

    Returns:
        ``True`` when the event was consumed.
    """
    return False

def handle_paste(self, text: str) -> bool:
    """Optional paste handler while focused.

    Returns:
        ``True`` when the paste was consumed.
    """
    return False