Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

27.6 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""The pixel grid `pixel-draw` asks a model for: its two answer formats, the canonical `grid.txt`,
the palette rules, row repair splicing and the renders.

A grid is a palette (one key per colour, `.` transparent) and per frame `height` rows of `width`
keys. The model answers it as a character grid (a ```pixels block: `PALETTE`, `FRAME <name>`,
rows, `END`) or as JSON (`{"palette": ["transparent", "#RRGGBB", ...], "frames": {name:
[[index, ...], ...]}}`). Either way the truth written to disk is `grid.txt`, the character grid
without its fence: a person can edit it, diff it and render it again (`pixel-draw --grid`).

Parsing is strict and says what it found (`Issue`):

- structural issues (no block, a broken palette, a frame missing or extra, more rows than the
  canvas) leave nothing a row can fix — that answer is drawn again;
- row issues (a row one key too long or short, a key not in the palette, rows missing at the end)
  are what the row repair asks for, one row at a time, and `splice` puts the answers in;
- recovered issues are code-recoverable and recorded, never silent: the fence tagged otherwise or
  missing, a fence never closed, a single frame written without its `FRAME` line or under another
  name, frames in another order, no `END` line, an answer that wrote its block more than once (the
  last block that reads whole is read), and — for a later answer of a set drawn over several, which
  is given the first answer's palette (`hold_palette`) — a colour it added or changed.

`png_bytes` writes a frame as a PNG whose bytes depend only on its pixels — stored deflate
blocks, no compressor in the loop — so the same grid gives the same file on any machine and any
zlib (Pillow's encoder output follows the zlib build it links). Previews, the 3x3 tiling and the
GIF are views for the eye and go through Pillow.
"""
from __future__ import annotations

import json
import re
import string
import struct
import zlib
from collections import Counter
from dataclasses import dataclass, replace
from pathlib import Path
from typing import Sequence

from PIL import Image

from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.util.hexcolor import parse_hex

from .base import PNG_MAGIC

FORMATS = ("chargrid", "json")
KEYS = string.ascii_lowercase + string.ascii_uppercase + string.digits
TRANSPARENT_KEY = "."
HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
PREVIEW_COLUMNS = 8  # frames a preview row holds before the next row

# PICO-8's 16 colours (lexaloffle.com/pico-8.php, the fixed palette of the console).
PICO8 = ("#000000", "#1D2B53", "#7E2553", "#008751", "#AB5236", "#5F574F", "#C2C3C7", "#FFF1E8",
         "#FF004D", "#FFA300", "#FFEC27", "#00E436", "#29ADFF", "#83769C", "#FF77A8", "#FFCCAA")
FREE_DEFAULT_LIMIT = 16

STRUCTURAL = frozenset({
    "no_block", "json_invalid", "json_shape", "bad_palette_line", "palette_key_duplicate", "dot_redefined",
    "extra_transparent_key", "palette0_not_transparent", "palette_too_large", "frame_missing", "frame_extra",
    "frame_duplicate", "row_count_over", "stray_line",
})
ROW_CODES = frozenset({"row_width", "unknown_symbol", "row_missing"})
RECOVERED = frozenset({"block_tag", "block_unclosed", "block_many", "frame_header_missing", "frame_renamed",
                       "frame_order", "no_end", "palette_added", "palette_changed"})

_PALETTE_LINE = re.compile(r"^(\S)\s+(transparent|#[0-9A-Fa-f]{6})$")
_ROW_ANSWER = re.compile(r"^\s*`?\s*ROW\s+(\S+)\s+(\d+)\s*:\s*(.*?)\s*`?\s*$", re.M)
_FRAME_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$")

Pixel = tuple[int, int, int, int]
TRANSPARENT: Pixel = (0, 0, 0, 0)


def frame_name_ok(name: str) -> bool:
    return bool(_FRAME_NAME.fullmatch(name))


# ----------------------------------------------------------------------------- palette rules

@dataclass(frozen=True)
class PaletteRule:
    """What a request allows: at most `limit` colours (free), or only `colors` (fixed)."""

    name: str  # "free:<n>" | "pico8" | "fixed"
    limit: int
    colors: tuple[str, ...] = ()  # "#RRGGBB" upper case; empty for a free palette

    @property
    def fixed(self) -> bool:
        return bool(self.colors)

    def to_dict(self) -> dict:
        return {"name": self.name, "limit": self.limit, "colors": list(self.colors)}


def _fixed(colors: Sequence[str], name: str, where: str) -> PaletteRule:
    normalized = []
    for raw in colors:
        value = raw.strip()
        if not value.startswith("#"):
            value = "#" + value
        if not HEX.fullmatch(value):
            raise ValueError(f"{where}: {raw!r} is not a #RRGGBB colour")
        normalized.append(value.upper())
    if not normalized:
        raise ValueError(f"{where}: no colours")
    duplicates = sorted({c for c in normalized if normalized.count(c) > 1})
    if duplicates:
        raise ValueError(f"{where}: colours listed twice: {', '.join(duplicates)}")
    if len(normalized) > len(KEYS):
        raise ValueError(f"{where}: at most {len(KEYS)} colours (one key each), got {len(normalized)}")
    return PaletteRule(name=name, limit=len(normalized), colors=tuple(normalized))


def palette_rule(value: str) -> PaletteRule:
    """`--palette`: `free` / `free:N`, `pico8`, `#hex,#hex,...`, or a file of colours.

    A file is JSON (a list of colours, or `{"colors": [...]}`) or text with one `#RRGGBB` /
    `RRGGBB` per line (blank lines and lines starting `;` skipped — Lospec's .hex is this)."""
    text = value.strip()
    if text == "free" or text.startswith("free:"):
        number = text.partition(":")[2] or str(FREE_DEFAULT_LIMIT)
        if not number.isdigit() or not 1 <= int(number) <= len(KEYS):
            raise ValueError(f"--palette {value!r}: free:N takes 1..{len(KEYS)} colours")
        return PaletteRule(name=f"free:{int(number)}", limit=int(number))
    if text == "pico8":
        return PaletteRule(name="pico8", limit=len(PICO8), colors=PICO8)
    if text.startswith("#"):
        return _fixed(text.split(","), "fixed", f"--palette {value!r}")
    path = Path(text).expanduser()
    if not path.is_file():
        raise ValueError(f"--palette {value!r}: not free[:N], pico8, a #RRGGBB list or a palette file that exists")
    raw = path.read_text(encoding="utf-8")
    if path.suffix.lower() == ".json":
        try:
            data = json.loads(raw)
        except json.JSONDecodeError as exc:
            raise ValueError(f"--palette {path}: not JSON ({exc.msg})") from exc
        colors = data.get("colors") if isinstance(data, dict) else data
        if not isinstance(colors, list) or not all(isinstance(c, str) for c in colors):
            raise ValueError(f"--palette {path}: expected a list of colours or {{\"colors\": [...]}}")
    else:
        colors = [line for line in (l.strip() for l in raw.splitlines()) if line and not line.startswith(";")]
    return _fixed(colors, "fixed", f"--palette {path}")


# ----------------------------------------------------------------------------- the grid

@dataclass(frozen=True)
class Issue:
    code: str
    frame: str | None = None
    row: int | None = None  # 1-based
    detail: str = ""

    def to_dict(self) -> dict:
        return {k: v for k, v in (("code", self.code), ("frame", self.frame), ("row", self.row),
                                  ("detail", self.detail)) if v not in (None, "")}


@dataclass(frozen=True)
class Grid:
    """A palette and frames of rows of keys, as written (keys of a JSON answer are its indices)."""

    fmt: str
    width: int
    height: int
    palette: dict[str, str | None]  # key -> "#RRGGBB" as written, None for transparent
    frames: dict[str, list[list[str]]]

    def key_map(self) -> dict[str, str]:
        """The character each key is written with in grid.txt."""
        if self.fmt == "chargrid":
            return {key: key for key in self.palette}
        mapping = {}
        for key, color in self.palette.items():
            index = int(key)
            mapping[key] = TRANSPARENT_KEY if color is None else KEYS[index - 1]
        return mapping


def structural(issues: Sequence[Issue]) -> list[Issue]:
    return [i for i in issues if i.code in STRUCTURAL]


def row_issues(issues: Sequence[Issue]) -> list[Issue]:
    return [i for i in issues if i.code in ROW_CODES]


def recovered(issues: Sequence[Issue]) -> list[Issue]:
    return [i for i in issues if i.code in RECOVERED]


def check_rows(grid: Grid) -> list[Issue]:
    """Every row issue of `grid`: a row of the wrong length, a key not in the palette, rows missing."""
    issues: list[Issue] = []
    for name, rows in grid.frames.items():
        for number, row in enumerate(rows, 1):
            if len(row) != grid.width:
                issues.append(Issue("row_width", name, number, f"{len(row)} values, needs {grid.width}"))
            unknown = sorted({token for token in row if token not in grid.palette})
            if unknown:
                issues.append(Issue("unknown_symbol", name, number, "not in the palette: " + " ".join(map(repr, unknown))))
        for number in range(len(rows) + 1, grid.height + 1):
            issues.append(Issue("row_missing", name, number))
    return issues


def _fenced(text: str, tag: str) -> tuple[str | None, str | None]:
    """The body of the ```<tag> block and how it was found: as asked (None), in a fence tagged
    otherwise or in no fence at all (`block_tag`), or in a fence never closed (`block_unclosed` —
    an answer cut off keeps the rows it wrote)."""
    match = re.search(r"```" + re.escape(tag) + r"[ \t]*\r?\n(.*?)```", text, re.S)
    if match:
        return match.group(1), None
    opener = r"PALETTE" if tag == "pixels" else r"\{"
    match = re.search(r"```[A-Za-z0-9_-]*[ \t]*\r?\n(\s*" + opener + r".*?)```", text, re.S)
    if match:
        return match.group(1), "block_tag"
    match = re.search(r"```" + re.escape(tag) + r"[ \t]*\r?\n(.*)\Z", text, re.S)
    if match:
        return match.group(1), "block_unclosed"
    if tag == "pixels":
        match = re.search(r"(?m)^PALETTE[ \t]*$.*", text, re.S)
        if match:
            return match.group(0), "block_tag"
    return None, None


def _settle_frames(written: dict[str, list[list[str]]], order: list[str], frames: Sequence[str],
                   issues: list[Issue]) -> dict[str, list[list[str]]]:
    """The requested frames out of what was written; one frame under another name is recovered."""
    if len(frames) == 1 and frames[0] not in written and len(written) == 1:
        (other,) = written
        issues.append(Issue("frame_renamed", frames[0], None, f"written as FRAME {other}"))
        written = {frames[0]: written[other]}
        order = [frames[0]]
    settled = {}
    for name in frames:
        if name not in written:
            issues.append(Issue("frame_missing", name))
        else:
            settled[name] = written[name]
    for name in order:
        if name not in frames:
            issues.append(Issue("frame_extra", name))
    if [n for n in order if n in frames] != [n for n in frames if n in order]:
        issues.append(Issue("frame_order", None, None, "written as " + ", ".join(order)))
    return settled


def _parse_chargrid_body(body: str, width: int, height: int, frames: Sequence[str],
                         issues: list[Issue]) -> Grid | None:
    lines = [line.rstrip() for line in body.splitlines()]
    palette: dict[str, str | None] = {}
    written: dict[str, list[list[str]]] = {}
    order: list[str] = []
    section = None
    current = None
    saw_end = False
    header_may_be_missing = len(frames) == 1 and not any(_frame_header(l.strip()) is not None for l in lines)
    for line in lines:
        stripped = line.strip()
        if not stripped:
            continue
        if stripped == "PALETTE" and section is None:
            section = "palette"
            continue
        name = _frame_header(stripped)
        if name is not None and section in ("palette", "frame"):
            if name in written:
                issues.append(Issue("frame_duplicate", name))
            written[name] = []
            order.append(name)
            current, section = name, "frame"
            continue
        if stripped == "END" and section in ("palette", "frame"):
            saw_end, section = True, "after"
            continue
        if section == "palette":
            match = _PALETTE_LINE.fullmatch(stripped)
            if match:
                key, value = match.group(1), match.group(2)
                if key in palette:
                    issues.append(Issue("palette_key_duplicate", None, None, key))
                elif key == TRANSPARENT_KEY and value != "transparent":
                    issues.append(Issue("dot_redefined", None, None, value))
                elif value == "transparent" and key != TRANSPARENT_KEY:
                    issues.append(Issue("extra_transparent_key", None, None, key))
                else:
                    palette[key] = None if value == "transparent" else value
                continue
            if header_may_be_missing and not written:
                issues.append(Issue("frame_header_missing", frames[0], None, "rows follow the palette"))
                current, section = frames[0], "frame"
                written[current] = []
                order.append(current)
            else:
                issues.append(Issue("bad_palette_line", None, None, stripped[:80]))
                continue
        if section == "frame":
            written[current].append(list(line))
        else:
            issues.append(Issue("stray_line", None, None, stripped[:80]))
    if section is None and not palette:
        issues.append(Issue("no_block", None, None, "no PALETTE line"))
        return None
    palette.setdefault(TRANSPARENT_KEY, None)
    palette = {TRANSPARENT_KEY: None, **{k: v for k, v in palette.items() if k != TRANSPARENT_KEY}}
    if not saw_end:
        issues.append(Issue("no_end"))
    settled = _settle_frames(written, order, frames, issues)
    for name, rows in settled.items():
        if len(rows) > height:
            issues.append(Issue("row_count_over", name, None, f"{len(rows)} rows, needs {height}"))
    return Grid("chargrid", width, height, palette, settled)


def _frame_header(stripped: str) -> str | None:
    if stripped == "FRAME":
        return ""
    if stripped.startswith(("FRAME ", "FRAME\t")):
        return stripped[5:].strip()
    return None


def _parse_json_body(body: str, width: int, height: int, frames: Sequence[str], issues: list[Issue]) -> Grid | None:
    try:
        data = json.loads(body)
    except json.JSONDecodeError as exc:
        issues.append(Issue("json_invalid", None, None, f"{exc.msg} at line {exc.lineno} column {exc.colno}"))
        return None
    raw_palette = data.get("palette") if isinstance(data, dict) else None
    raw_frames = data.get("frames") if isinstance(data, dict) else None
    if not isinstance(raw_palette, list) or not isinstance(raw_frames, dict) \
            or not all(isinstance(rows, list) for rows in raw_frames.values()):
        issues.append(Issue("json_shape", None, None, 'expected {"palette": [...], "frames": {name: [[...]]}}'))
        return None
    palette: dict[str, str | None] = {}
    for index, value in enumerate(raw_palette):
        if index == 0:
            if value != "transparent":
                issues.append(Issue("palette0_not_transparent", None, None, repr(value)[:40]))
            palette["0"] = None
        elif value == "transparent":
            issues.append(Issue("extra_transparent_key", None, None, str(index)))
        elif isinstance(value, str) and HEX.fullmatch(value):
            palette[str(index)] = value
        else:
            issues.append(Issue("bad_palette_line", None, None, f"palette[{index}] = {value!r}"[:80]))
    if len(raw_palette) - 1 > len(KEYS):
        issues.append(Issue("palette_too_large", None, None, f"{len(raw_palette) - 1} colours, at most {len(KEYS)}"))
    written = {name: [_json_row(row) for row in rows] for name, rows in raw_frames.items()}
    settled = _settle_frames(written, list(raw_frames), frames, issues)
    for name, rows in settled.items():
        if len(rows) > height:
            issues.append(Issue("row_count_over", name, None, f"{len(rows)} rows, needs {height}"))
    return Grid("json", width, height, palette, settled)


def _json_token(value: object) -> str:
    if isinstance(value, int) and not isinstance(value, bool):
        return str(value)
    return json.dumps(value)  # never a palette key: an unknown symbol


def _json_row(row: object) -> list[str]:
    return [_json_token(v) for v in row] if isinstance(row, list) else []


def _blocks(text: str, tag: str) -> list[tuple[str, str | None]]:
    """Every ```<tag> block of an answer, in order, and how each was found: as asked (None), or never
    closed before the next block or the end of the answer (`block_unclosed`)."""
    openers = list(re.finditer(r"```" + re.escape(tag) + r"[ \t]*\r?\n", text))
    out: list[tuple[str, str | None]] = []
    for number, opener in enumerate(openers):
        end = openers[number + 1].start() if number + 1 < len(openers) else len(text)
        close = text.find("```", opener.end(), end)
        out.append((text[opener.end():close], None) if close >= 0 else (text[opener.end():end], "block_unclosed"))
    return out


def _read_body(body: str, found: str | None, fmt: str, width: int, height: int,
               frames: Sequence[str]) -> tuple[Grid | None, list[Issue]]:
    issues = [Issue(found)] if found else []
    parse = _parse_chargrid_body if fmt == "chargrid" else _parse_json_body
    grid = parse(body, width, height, frames, issues)
    if grid is not None and not structural(issues):
        issues.extend(check_rows(grid))
    return grid, issues


def _last_whole(blocks: list[tuple[str, str | None]], fmt: str, width: int, height: int,
                frames: Sequence[str]) -> tuple[Grid | None, list[Issue]]:
    """An answer that wrote its block more than once — a first try, then "Corrected:" and the block
    again: the last block that reads whole is the answer; when none does, the last whose rows the
    row repair can fix; when none can, the last. Which one was read is recorded (`block_many`)."""
    read = [_read_body(body, found, fmt, width, height, frames) for body, found in blocks]
    numbers = range(len(read) - 1, -1, -1)
    chosen = next((n for n in numbers if read[n][0] is not None and not structural(read[n][1])
                   and not row_issues(read[n][1])), None)
    if chosen is None:
        chosen = next((n for n in numbers if read[n][0] is not None and not structural(read[n][1])), len(read) - 1)
    grid, issues = read[chosen]
    return grid, [Issue("block_many", None, None, f"{len(read)} blocks, read block {chosen + 1}"), *issues]


def parse_answer(text: str, fmt: str, width: int, height: int, frames: Sequence[str]) -> tuple[Grid | None, list[Issue]]:
    """Read a model's answer. Returns the grid (None when nothing could be read) and every issue."""
    if fmt not in FORMATS:
        raise ValueError(f"unknown format {fmt!r}")
    tag = "pixels" if fmt == "chargrid" else "json"
    blocks = _blocks(text, tag)
    if len(blocks) > 1:
        return _last_whole(blocks, fmt, width, height, frames)
    body, found = _fenced(text, tag)
    if body is None and fmt == "json":
        start, end = text.find("{"), text.rfind("}")
        body, found = (text[start:end + 1], "block_tag") if 0 <= start < end else (None, None)
    if body is None:
        return None, [Issue("no_block", None, None, f"no ```{tag} block")]
    return _read_body(body, found, fmt, width, height, frames)


def hold_palette(grid: Grid, issues: list[Issue], palette: dict[str, str | None]) -> tuple[Grid, list[Issue]]:
    """`grid` under the palette it was given — a later answer of a set drawn over several, which writes
    the first answer's palette again. A key it added is refused, so its rows become row issues for the
    row repair; a colour it changed is put back. Both are recorded."""
    found = []
    for key, color in grid.palette.items():
        if key not in palette:
            found.append(Issue("palette_added", None, None, f"{key} {color}"))
        elif (color or "").lower() != (palette[key] or "").lower():
            found.append(Issue("palette_changed", None, None, f"{key} {color}, kept {palette[key]}"))
    held = replace(grid, palette=dict(palette))
    return held, [i for i in issues if i.code not in ROW_CODES] + found + check_rows(held)


def joined(grids: Sequence[Grid]) -> Grid:
    """The frames of several answers, in order, under the first answer's palette (`hold_palette`)."""
    frames = {name: rows for grid in grids for name, rows in grid.frames.items()}
    return replace(grids[0], frames=frames)


def read_grid_text(text: str) -> tuple[Grid | None, list[Issue]]:
    """Read a `grid.txt` (the character grid with or without its fence); the frames and the canvas
    size are what it holds — the commonest row length is the width, the commonest row count the
    height, so one row broken by an edit is reported as that row."""
    body, _ = _fenced(text, "pixels")
    body = text if body is None else body
    rows: dict[str, list[str]] = {}
    names: list[str] = []
    for line in body.splitlines():
        stripped = line.strip()
        name = _frame_header(stripped)
        if name is not None:
            names.append(name)
            rows.setdefault(name, [])
        elif stripped == "END":
            break
        elif names and stripped:
            rows[names[-1]].append(line.rstrip())
    if not names:
        return None, [Issue("frame_missing", None, None, "no FRAME line")]
    bad = [n for n in names if not frame_name_ok(n)]
    if bad:
        return None, [Issue("frame_missing", None, None, "frame names are letters, digits, '_' or '-': "
                            + ", ".join(map(repr, bad)))]
    lengths = Counter(len(row) for frame in rows.values() for row in frame)
    counts = Counter(len(frame) for frame in rows.values())
    width = lengths.most_common(1)[0][0] if lengths else 0
    height = counts.most_common(1)[0][0]
    issues: list[Issue] = []
    grid = _parse_chargrid_body(body, width, height, list(dict.fromkeys(names)), issues)
    if grid is not None and not structural(issues):
        issues.extend(check_rows(grid))
    return grid, issues


# ----------------------------------------------------------------------------- repair splicing

def row_text(grid: Grid, row: Sequence[str]) -> str:
    """A row as the model wrote it: keys for a character grid, a JSON list for a JSON answer."""
    if grid.fmt == "chargrid":
        return "".join(row)
    return "[" + ", ".join(row) + "]"


def parse_row_answers(text: str, grid: Grid, wanted: set[tuple[str, int]]) -> tuple[dict[tuple[str, int], list[str]], list[str]]:
    """`ROW <frame> <n>: <row>` lines of a repair answer: the rows asked for, and what was ignored."""
    fixes: dict[tuple[str, int], list[str]] = {}
    ignored: list[str] = []
    for match in _ROW_ANSWER.finditer(text):
        frame, number, value = match.group(1), int(match.group(2)), match.group(3).strip().strip("`").strip()
        if (frame, number) not in wanted:
            ignored.append(f"{frame} {number}")
            continue
        if grid.fmt == "chargrid":
            fixes[(frame, number)] = list(value)
        else:
            try:
                parsed = json.loads(value)
            except json.JSONDecodeError:
                parsed = None
            fixes[(frame, number)] = _json_row(parsed)
    return fixes, ignored


def splice(grid: Grid, fixes: dict[tuple[str, int], list[str]]) -> Grid:
    """`grid` with each fixed row put in its place; a missing row is added where it belongs."""
    frames = {name: [list(row) for row in rows] for name, rows in grid.frames.items()}
    for (name, number), row in sorted(fixes.items(), key=lambda item: (item[0][0], item[0][1])):
        rows = frames[name]
        while len(rows) < number:
            rows.append([])
        rows[number - 1] = list(row)
    return replace(grid, frames=frames)


# ----------------------------------------------------------------------------- grid.txt and renders

def to_text(grid: Grid) -> str:
    """The canonical grid.txt of a grid with no row issues: the character grid, unfenced."""
    keys = grid.key_map()
    lines = ["PALETTE", f"{TRANSPARENT_KEY} transparent"]
    lines += [f"{keys[key]} {color}" for key, color in grid.palette.items() if color is not None]
    for name, rows in grid.frames.items():
        lines.append(f"FRAME {name}")
        lines += ["".join(keys[token] for token in row) for row in rows]
    lines.append("END")
    return "\n".join(lines) + "\n"


def hex_pixel(color: str | None) -> Pixel:
    if color is None:
        return TRANSPARENT
    return (*parse_hex(color), 255)


def frame_pixels(grid: Grid, name: str) -> list[list[Pixel]]:
    colors = {key: hex_pixel(color) for key, color in grid.palette.items()}
    return [[colors[token] for token in row] for row in grid.frames[name]]


def _chunk(tag: bytes, data: bytes) -> bytes:
    return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF)


def _stored_zlib(data: bytes) -> bytes:
    """A zlib stream of stored (uncompressed) deflate blocks: its bytes are a function of `data` alone."""
    out = bytearray(b"\x78\x01")
    blocks = [data[i:i + 0xFFFF] for i in range(0, len(data), 0xFFFF)] or [b""]
    for index, block in enumerate(blocks):
        out.append(1 if index == len(blocks) - 1 else 0)
        out += struct.pack("<HH", len(block), len(block) ^ 0xFFFF)
        out += block
    out += struct.pack(">I", zlib.adler32(data) & 0xFFFFFFFF)
    return bytes(out)


def png_bytes(pixels: Sequence[Sequence[Pixel]]) -> bytes:
    """An 8-bit RGBA PNG of `pixels`, byte for byte the same for the same pixels."""
    height, width = len(pixels), len(pixels[0])
    raw = b"".join(b"\x00" + bytes(channel for pixel in row for channel in pixel) for row in pixels)
    header = struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0)
    return PNG_MAGIC + _chunk(b"IHDR", header) + _chunk(b"IDAT", _stored_zlib(raw)) + _chunk(b"IEND", b"")


def image_of(pixels: Sequence[Sequence[Pixel]]) -> Image.Image:
    image = Image.new("RGBA", (len(pixels[0]), len(pixels)))
    image.putdata([pixel for row in pixels for pixel in row])
    return image


def preview_scale(size: int) -> int:
    """The nearest-neighbour enlargement that makes a frame about 256 px."""
    return max(1, 256 // size)


def preview_strip(frames: Sequence[Sequence[Sequence[Pixel]]], scale: int,
                  columns: int = PREVIEW_COLUMNS) -> Image.Image:
    """The frames side by side, each enlarged `scale` times, two enlarged pixels apart; past `columns`
    frames they go on in rows, left to right and top to bottom, so a long set stays readable."""
    images = [image_of(f).resize((len(f[0]) * scale, len(f) * scale), Image.NEAREST) for f in frames]
    gap = 2 * scale
    across = min(columns, len(images))
    down = -(-len(images) // across)
    width, height = max(i.width for i in images), max(i.height for i in images)
    strip = Image.new("RGBA", (width * across + gap * (across - 1), height * down + gap * (down - 1)))
    for number, image in enumerate(images):
        strip.paste(image, ((number % across) * (width + gap), (number // across) * (height + gap)))
    return strip


def tiled_3x3(pixels: Sequence[Sequence[Pixel]], scale: int) -> Image.Image:
    tile = image_of(pixels)
    tiled = Image.new("RGBA", (tile.width * 3, tile.height * 3))
    for ty in range(3):
        for tx in range(3):
            tiled.paste(tile, (tx * tile.width, ty * tile.height))
    return tiled.resize((tiled.width * scale, tiled.height * scale), Image.NEAREST)


def save_gif(frames: Sequence[Sequence[Sequence[Pixel]]], scale: int, path: Path, duration_ms: int, *, loop: int | None = 0) -> None:
    images = [image_of(f).resize((len(f[0]) * scale, len(f) * scale), Image.NEAREST) for f in frames]
    save_clean_gif(images, path, duration_ms=duration_ms, loop=loop)