ophtml 0.3.0__tar.gz

ophtml-0.3.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: ophtml
+Version: 0.3.0
+Summary: Bakes the ps2ui intermediate representation into .uib blobs for the PlayStation 2 runtime
+License: MIT
+Project-URL: Repository, https://github.com/coffeedevsolutions/OPHTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=9
+
+# ophtml
+
+The Python half of the OPHTML toolchain, published to PyPI as
+`ophtml`. It provides the `ps2ui`, `ps2ui-bake`, `ps2ui-check` and
+`ps2ui-fontgen` commands. OPHTML is the product, ps2ui is the format
+and the tools that speak it.
+
+Second stage of the [ps2ui toolchain](https://github.com/coffeedevsolutions/OPHTML/blob/main/README.md): turns the
+`ui.json` IR produced by `@ophtml/layout` into a `.uib` blob the C99
+runtime replays on the PlayStation 2, plus PNG previews rendered by
+replaying that same blob.
+
+```sh
+PYTHONPATH=. python3 -m ps2ui_bake ui.json -o ui.uib --preview out.png
+```
+
+`ps2ui serve` puts that same replay behind a localhost page with
+arrow-key navigation, screen and theme switching, four aspect modes and
+click-to-inspect over the command list. `--uib blob.uib` serves any
+`.uib` with no project and no Node. It renders through the previewer
+rather than in the browser, so it shows what the console draws; it is
+not a substitute for running on one. See the repository README.
+
+`pip install -e .` from this directory puts `ps2ui`, `ps2ui-bake`,
+`ps2ui-check` and `ps2ui-fontgen` on `PATH` as bare commands, pointed at
+the checkout, so the `PYTHONPATH=` prefix is only needed when nothing is
+installed, which is the case CI runs in.
+
+See `docs/format-uib.md` at the repository root for the file format,
+and `ps2ui_bake/rounding.py` for the numeric rules shared with the
+layout stage.

ophtml-0.3.0/README.md

@@ -0,0 +1,31 @@
+# ophtml
+
+The Python half of the OPHTML toolchain, published to PyPI as
+`ophtml`. It provides the `ps2ui`, `ps2ui-bake`, `ps2ui-check` and
+`ps2ui-fontgen` commands. OPHTML is the product, ps2ui is the format
+and the tools that speak it.
+
+Second stage of the [ps2ui toolchain](https://github.com/coffeedevsolutions/OPHTML/blob/main/README.md): turns the
+`ui.json` IR produced by `@ophtml/layout` into a `.uib` blob the C99
+runtime replays on the PlayStation 2, plus PNG previews rendered by
+replaying that same blob.
+
+```sh
+PYTHONPATH=. python3 -m ps2ui_bake ui.json -o ui.uib --preview out.png
+```
+
+`ps2ui serve` puts that same replay behind a localhost page with
+arrow-key navigation, screen and theme switching, four aspect modes and
+click-to-inspect over the command list. `--uib blob.uib` serves any
+`.uib` with no project and no Node. It renders through the previewer
+rather than in the browser, so it shows what the console draws; it is
+not a substitute for running on one. See the repository README.
+
+`pip install -e .` from this directory puts `ps2ui`, `ps2ui-bake`,
+`ps2ui-check` and `ps2ui-fontgen` on `PATH` as bare commands, pointed at
+the checkout, so the `PYTHONPATH=` prefix is only needed when nothing is
+installed, which is the case CI runs in.
+
+See `docs/format-uib.md` at the repository root for the file format,
+and `ps2ui_bake/rounding.py` for the numeric rules shared with the
+layout stage.

ophtml-0.3.0/ophtml.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: ophtml
+Version: 0.3.0
+Summary: Bakes the ps2ui intermediate representation into .uib blobs for the PlayStation 2 runtime
+License: MIT
+Project-URL: Repository, https://github.com/coffeedevsolutions/OPHTML
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: Pillow>=9
+
+# ophtml
+
+The Python half of the OPHTML toolchain, published to PyPI as
+`ophtml`. It provides the `ps2ui`, `ps2ui-bake`, `ps2ui-check` and
+`ps2ui-fontgen` commands. OPHTML is the product, ps2ui is the format
+and the tools that speak it.
+
+Second stage of the [ps2ui toolchain](https://github.com/coffeedevsolutions/OPHTML/blob/main/README.md): turns the
+`ui.json` IR produced by `@ophtml/layout` into a `.uib` blob the C99
+runtime replays on the PlayStation 2, plus PNG previews rendered by
+replaying that same blob.
+
+```sh
+PYTHONPATH=. python3 -m ps2ui_bake ui.json -o ui.uib --preview out.png
+```
+
+`ps2ui serve` puts that same replay behind a localhost page with
+arrow-key navigation, screen and theme switching, four aspect modes and
+click-to-inspect over the command list. `--uib blob.uib` serves any
+`.uib` with no project and no Node. It renders through the previewer
+rather than in the browser, so it shows what the console draws; it is
+not a substitute for running on one. See the repository README.
+
+`pip install -e .` from this directory puts `ps2ui`, `ps2ui-bake`,
+`ps2ui-check` and `ps2ui-fontgen` on `PATH` as bare commands, pointed at
+the checkout, so the `PYTHONPATH=` prefix is only needed when nothing is
+installed, which is the case CI runs in.
+
+See `docs/format-uib.md` at the repository root for the file format,
+and `ps2ui_bake/rounding.py` for the numeric rules shared with the
+layout stage.

ophtml-0.3.0/ophtml.egg-info/SOURCES.txt

@@ -0,0 +1,31 @@
+README.md
+pyproject.toml
+ophtml.egg-info/PKG-INFO
+ophtml.egg-info/SOURCES.txt
+ophtml.egg-info/dependency_links.txt
+ophtml.egg-info/entry_points.txt
+ophtml.egg-info/requires.txt
+ophtml.egg-info/top_level.txt
+ps2ui_bake/__init__.py
+ps2ui_bake/__main__.py
+ps2ui_bake/arena.py
+ps2ui_bake/atlas.py
+ps2ui_bake/caps.py
+ps2ui_bake/check.py
+ps2ui_bake/cli.py
+ps2ui_bake/clip.py
+ps2ui_bake/fontgen.py
+ps2ui_bake/gs.py
+ps2ui_bake/ninepatch.py
+ps2ui_bake/pen.py
+ps2ui_bake/preview.py
+ps2ui_bake/project.py
+ps2ui_bake/ps2ui.py
+ps2ui_bake/quads.py
+ps2ui_bake/rounding.py
+ps2ui_bake/serve.py
+ps2ui_bake/serve_page.html
+ps2ui_bake/uib.py
+ps2ui_bake/vram.py
+tests/test_baker.py
+tests/test_serve.py

ophtml-0.3.0/ophtml.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ophtml-0.3.0/ophtml.egg-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+ps2ui = ps2ui_bake.ps2ui:main
+ps2ui-bake = ps2ui_bake.cli:main
+ps2ui-check = ps2ui_bake.check:main
+ps2ui-fontgen = ps2ui_bake.fontgen:main

ophtml-0.3.0/ophtml.egg-info/requires.txt

@@ -0,0 +1 @@
+Pillow>=9

ophtml-0.3.0/ophtml.egg-info/top_level.txt

@@ -0,0 +1 @@
+ps2ui_bake

ophtml-0.3.0/ps2ui_bake/__init__.py

@@ -0,0 +1,31 @@
+"""ps2ui-bake: turns the ui.json IR into a .uib blob the PS2 runtime replays.
+
+Stages inside this package:
+
+    fontgen   TTF -> metrics JSON (the seam shared with @ophtml/layout)
+    atlas     glyph atlases per (weight, size), 8-bit coverage + CLUT
+    ninepatch rounded-rect chrome -> 9-sliced RGBA patches
+    quads     IR commands -> flat GS quad records
+    uib       binary .uib writer / reader
+    preview   replays a baked blob to PNG, montages focus states
+
+The one rule: everything the console would otherwise compute happens here.
+"""
+
+# THE ONE PLACE THIS PACKAGE'S VERSION IS WRITTEN. pyproject.toml reads
+# it (`dynamic = ["version"]`), because from the 0.2.0 release onward
+# this file said 0.1.0 while pyproject said 0.2.0 -- two numbers for one
+# package, neither read by anything, so neither could be wrong out loud.
+#
+# 0.3.0 is a release and names the tag `v0.3.0`. It carried `.dev0`
+# until that tag existed, because there is no 0.2.0 tag and never was:
+# the tree was past that release by four format moves (v4-v7) and was
+# not yet the next one. What a prerelease does and does NOT protect
+# against is in docs/releasing.md -- pip's exclusion of prereleases
+# lapses when no stable version exists, which is why the first PyPI
+# upload has to be a real release rather than a reserved name.
+# tools/check-versions.py holds all of it together, and its rule 8
+# fails this line the moment it names a release nothing has tagged.
+__version__ = "0.3.0"
+
+from .rounding import round_half_up, css_alpha_to_gs, gs_alpha_to_css  # noqa: F401

ophtml-0.3.0/ps2ui_bake/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

ophtml-0.3.0/ps2ui_bake/arena.py

@@ -0,0 +1,77 @@
+"""The v6 arena requirement, computed from a baked blob.
+
+`ps2ui_load` no longer sizes itself from PS2UI_MAX_* ceilings: it carves
+one caller-provided block, and the caller has to know how big it is
+before running anything. This is the host-side mirror of `arena_compute`
+in runtime/ps2ui.c, so `ps2ui-bake` and `ps2ui-check` can print the
+number an integrator needs to declare a static buffer.
+
+THE NUMBER IS TARGET-DEPENDENT, which is the only subtle thing here.
+The arena holds an array of gsKit's GSTEXTURE, and that struct contains
+two pointers (`u32 *Mem`, `u32 *Clut`). On the EE they are 4 bytes; on a
+64-bit host they are 8, so the same blob needs a different arena in the
+sample ELF than in the host test suite. Reporting one number without
+saying which target it belongs to would be wrong roughly half the time,
+so both are computed and the console one is the headline -- that is
+where the static buffer actually lives.
+
+test_arena_matches_runtime proves this file agrees with the C: two
+implementations that agree is evidence, one restating the other's
+comments is not.
+"""
+
+# GSTEXTURE, from runtime/vendor/gsKit/gsInit.h (u32 Width, u32 Height,
+# u8 PSM, u8 ClutPSM, u32 TBW, u32 *Mem, u32 *Clut, u32 Vram,
+# u32 VramClut, u32 Filter, u8 ClutStorageMode, u8 Delayed), laid out by
+# the ordinary C rules rather than by a remembered total.
+_GSTEXTURE_FIELDS = [
+    (4, 4), (4, 4),          # Width, Height
+    (1, 1), (1, 1),          # PSM, ClutPSM
+    (4, 4),                  # TBW
+    ("ptr", "ptr"), ("ptr", "ptr"),   # Mem, Clut
+    (4, 4), (4, 4), (4, 4),  # Vram, VramClut, Filter
+    (1, 1), (1, 1),          # ClutStorageMode, Delayed
+]
+
+EE_PTR = 4     # mips64r5900el-ps2-elf: 32-bit pointers
+HOST64_PTR = 8
+
+
+def sizeof_gstexture(ptr_size: int = EE_PTR) -> int:
+    off = 0
+    align_max = 1
+    for size, align in _GSTEXTURE_FIELDS:
+        if size == "ptr":
+            size = align = ptr_size
+        off = (off + align - 1) // align * align
+        off += size
+        align_max = max(align_max, align)
+    return (off + align_max - 1) // align_max * align_max
+
+
+def arena_size(uib, ptr_size: int = EE_PTR) -> int:
+    """Bytes ps2ui_load needs for `uib`, for a target with this pointer
+    size. Mirrors arena_compute's regions in the same order."""
+    total = 0
+    total += len(uib.cluts) * 256 * 4                  # permuted CLUTs
+    total += len(uib.textures) * sizeof_gstexture(ptr_size)
+    total += len(uib.slots) * 4                        # slot_off[]
+    total += ((len(uib.focus) + 31) // 32) * 4         # hidden bits
+    total += len(uib.screens) * 2                      # screen_focus[]
+    for sl in uib.slots:
+        total += sl["capacity"] + 1                    # slot text
+    total += len(uib.slots)                            # slot_is_set
+    return total
+
+
+def breakdown(uib, ptr_size: int = EE_PTR) -> list:
+    """(region, bytes) pairs, for a report that says where it went."""
+    return [
+        ("permuted CLUTs", len(uib.cluts) * 256 * 4),
+        ("texture handles", len(uib.textures) * sizeof_gstexture(ptr_size)),
+        ("slot text", sum(sl["capacity"] + 1 for sl in uib.slots)),
+        ("slot offsets", len(uib.slots) * 4),
+        ("visibility bits", ((len(uib.focus) + 31) // 32) * 4),
+        ("screen focus", len(uib.screens) * 2),
+        ("slot set flags", len(uib.slots)),
+    ]

ophtml-0.3.0/ps2ui_bake/atlas.py

@@ -0,0 +1,154 @@
+"""Glyph atlas baking.
+
+One atlas per (weight, size) pair used by the document. Glyphs are
+rasterized by FreeType (via Pillow) at the exact pixel size the layout
+measured — never scaled on the GS, where bilinear filtering would turn
+14px text into soup.
+
+The atlas is PSMT8: each texel is a coverage value 0..255 indexing a
+CLUT of white-with-alpha-ramp, and the runtime tints by vertex color
+modulation. One atlas therefore serves every text color in the UI.
+
+Glyph advances are re-derived from the *metrics JSON*, not from what
+FreeType reports at this size — layout already positioned every line
+using metrics advances, and the bitmap must follow the measurement, not
+the other way around. The bitmap's own bearing places ink within the
+advance box.
+"""
+
+import json
+from dataclasses import dataclass, field
+
+from PIL import Image, ImageDraw, ImageFont
+
+from .rounding import glyph_advance_px, kern_px
+
+ATLAS_WIDTH = 256  # GS-friendly; height grows in shelf packing
+
+
+@dataclass
+class Glyph:
+    codepoint: int
+    u: int
+    v: int
+    w: int
+    h: int
+    bearing_x: int  # ink offset from pen x
+    bearing_y: int  # ink offset from the line-box top, measured via the
+                    # METRICS ascent — see AtlasBuilder.add (backlog B2)
+    advance: int    # px, from metrics — matches layout exactly
+
+
+@dataclass
+class Atlas:
+    weight: int
+    size: int
+    image: "Image.Image"
+    glyphs: dict = field(default_factory=dict)  # codepoint -> Glyph
+    line_ascent: int = 0
+    line_descent: int = 0
+
+
+class AtlasBuilder:
+    """Shelf-packs glyphs for one (weight, size)."""
+
+    def __init__(self, ttf_path: str, metrics_path: str, weight: int, size: int):
+        self.weight = weight
+        self.size = size
+        self.font = ImageFont.truetype(ttf_path, size)
+        with open(metrics_path, encoding="utf-8") as fh:
+            self.metrics = json.load(fh)
+        self.image = Image.new("L", (ATLAS_WIDTH, 64), 0)
+        self.draw = ImageDraw.Draw(self.image)
+        self.glyphs = {}
+        self.shelf_x = 1
+        self.shelf_y = 1
+        self.shelf_h = 0
+        ascent, descent = self.font.getmetrics()
+        self.ascent = ascent
+        self.descent = descent
+        # The layout stage positioned every line box using the METRICS
+        # ascent (units -> px via the shared rounding rule). Pillow's
+        # per-size ascent can differ by a pixel, so ink placement must
+        # go through the metrics value or text drifts off its measured
+        # box (backlog B2).
+        self.metrics_ascent_px = glyph_advance_px(self.metrics["ascent"], size)
+        self.kerning = self.metrics.get("kerning", {})
+
+    def kern(self, prev_cp, cp: int) -> int:
+        """Pixel kern applied before `cp` because `prev_cp` precedes it.
+
+        Mirrors layout's Font.kernPx, including that the first glyph of
+        a run is never kerned."""
+        if prev_cp is None:
+            return 0
+        return kern_px(self.kerning.get(f"{prev_cp},{cp}", 0), self.size)
+
+    def _grow(self, needed_h: int):
+        if needed_h <= self.image.height:
+            return
+        h = self.image.height
+        while h < needed_h:
+            h *= 2
+        grown = Image.new("L", (ATLAS_WIDTH, h), 0)
+        grown.paste(self.image, (0, 0))
+        self.image = grown
+        self.draw = ImageDraw.Draw(self.image)
+
+    def add(self, ch: str) -> Glyph:
+        cp = ord(ch)
+        if cp in self.glyphs:
+            return self.glyphs[cp]
+
+        adv_units = self.metrics["advances"].get(str(cp), self.metrics["missing"])
+        advance = glyph_advance_px(adv_units, self.size)
+
+        # Rasterize into a scratch tile and crop to ink.
+        pad = 2
+        tile_w = advance + self.size + 2 * pad
+        tile_h = self.ascent + self.descent + 2 * pad
+        tile = Image.new("L", (tile_w, tile_h), 0)
+        ImageDraw.Draw(tile).text((pad, pad), ch, font=self.font, fill=255)
+        bbox = tile.getbbox()
+        if bbox is None:  # space & friends: advance with no ink
+            g = Glyph(cp, 0, 0, 0, 0, 0, 0, advance)
+            self.glyphs[cp] = g
+            return g
+        x0, y0, x1, y1 = bbox
+        ink = tile.crop(bbox)
+        w, h = ink.size
+
+        if self.shelf_x + w + 1 > ATLAS_WIDTH:
+            self.shelf_y += self.shelf_h + 1
+            self.shelf_x = 1
+            self.shelf_h = 0
+        self._grow(self.shelf_y + h + 1)
+        self.image.paste(ink, (self.shelf_x, self.shelf_y))
+
+        # Pillow's default anchor puts the FreeType ascender at y=pad,
+        # so (y0 - pad) is ink-below-PIL-ascender. Re-express it as
+        # ink-below-baseline, then hang it from the metrics ascent that
+        # layout actually measured with.
+        ink_from_baseline = (y0 - pad) - self.ascent
+        g = Glyph(
+            codepoint=cp,
+            u=self.shelf_x, v=self.shelf_y, w=w, h=h,
+            bearing_x=x0 - pad,
+            bearing_y=self.metrics_ascent_px + ink_from_baseline,
+            advance=advance,
+        )
+        self.shelf_x += w + 1
+        self.shelf_h = max(self.shelf_h, h)
+        self.glyphs[cp] = g
+        return g
+
+    def build(self) -> Atlas:
+        # Snap height up to the next multiple of 8 lest odd heights upset
+        # GS transfer alignment.
+        h = (self.image.height + 7) & ~7
+        if h != self.image.height:
+            self._grow(h)
+        atlas = Atlas(self.weight, self.size, self.image, dict(self.glyphs))
+        atlas.line_ascent = self.ascent
+        atlas.line_descent = self.descent
+        return atlas

ophtml-0.3.0/ps2ui_bake/caps.py

@@ -0,0 +1,139 @@
+"""Runtime limits the bake has to know about (backlog B10).
+
+Originally four table-count ceilings that ps2ui_load() rejected with
+PS2UI_ERR_TOO_MANY. Three of them -- textures, slots, screens -- no
+longer exist: once the v6 arena made the context size itself from the
+blob, those numbers bounded nothing the blob's own size did not
+already bound, and 16 slots was a real obstacle to a real UI (the UC-3
+scoping fixture measures 28 on one OPL-class screen). The runtime now
+refuses on arithmetic it cannot do rather than on a number ps2ui.h
+picked; see arena_compute.
+
+What remains is PS2UI_MAX_SCISSOR_DEPTH, which is genuine fixed
+storage: ps2ui_render keeps a scissor stack that deep, and a blob
+nesting `overflow: hidden` past it draws the inner subtree under the
+outer clip. It fails soft, on a television, so the bake refuses it
+here instead.
+
+The value is parsed out of runtime/ps2ui.h when it is reachable, so
+raising it in the header raises it here too. FALLBACK covers the
+pip-installed case where the runtime source is absent;
+test_caps_match_header proves the two agree.
+"""
+
+import os
+import re
+
+FALLBACK = {
+    # The last one. It bounds how deep `overflow: hidden` may nest
+    # before ps2ui_render runs out of scissor stack -- real storage,
+    # unlike the table counts that used to sit beside it. The regex
+    # already matched it; without the key here, caps.update silently
+    # dropped it and nothing checked the depth at all.
+    "PS2UI_MAX_SCISSOR_DEPTH": 8,
+}
+
+_DEFINE = re.compile(r"^#define\s+(PS2UI_MAX_\w+)\s+(\d+)", re.M)
+
+
+def header_path() -> str:
+    here = os.path.dirname(os.path.abspath(__file__))
+    return os.path.normpath(os.path.join(here, "..", "..", "..", "runtime", "ps2ui.h"))
+
+
+def parse_header(path: str = None) -> dict:
+    """Caps from ps2ui.h, or FALLBACK when the header is not reachable."""
+    path = path or header_path()
+    try:
+        with open(path, encoding="utf-8") as fh:
+            src = fh.read()
+    except OSError:
+        return dict(FALLBACK)
+    found = {m.group(1): int(m.group(2)) for m in _DEFINE.finditer(src)}
+    caps = dict(FALLBACK)
+    caps.update({k: v for k, v in found.items() if k in FALLBACK})
+    return caps
+
+
+def max_scissor_depth(records) -> int:
+    """Deepest SCISSOR_PUSH nesting in a command list.
+
+    The runtime keeps a fixed stack and cannot report an overflow. It
+    fails soft — the too-deep subtree draws under the enclosing clip —
+    but "your dialog is not clipped" is a poor thing to discover on a
+    television, so the bake refuses it instead.
+    """
+    from .quads import OP_SCISSOR_POP, OP_SCISSOR_PUSH
+    depth = peak = 0
+    for rec in records:
+        if rec.op == OP_SCISSOR_PUSH:
+            depth += 1
+            peak = max(peak, depth)
+        elif rec.op == OP_SCISSOR_POP and depth > 0:
+            depth -= 1
+    return peak
+
+
+def check(textures, cluts, slots, screens, caps: dict = None, records=None):
+    """Returns (errors, caps). Each error names the cap, the value, and
+    the header constant to raise if the limit is the wrong one."""
+    caps = caps or parse_header()
+    errors = []
+
+    if records is not None:
+        # >= because the runtime's guard is `depth + 1 >= MAX`, so the
+        # last usable slot is MAX - 1.
+        peak = max_scissor_depth(records)
+        limit = caps["PS2UI_MAX_SCISSOR_DEPTH"]
+        if peak >= limit:
+            errors.append(
+                f"scissor nesting: {peak} levels reaches "
+                f"PS2UI_MAX_SCISSOR_DEPTH = {limit}. ps2ui_render has a "
+                f"fixed stack and cannot report an overflow, so the "
+                f"deepest subtree would draw under its parent's clip "
+                f"instead of its own. Flatten the nesting or raise "
+                f"PS2UI_MAX_SCISSOR_DEPTH in runtime/ps2ui.h."
+            )
+
+    # Textures, slots and screens used to be checked against ceilings
+    # here. They are not bounded by a number any more -- only by the
+    # format's own uint16 count fields, which the writer below cannot
+    # exceed without failing to pack the header at all. What replaced
+    # the ceilings is an arena the runtime refuses to carve if it does
+    # not fit the target's address space, and the bake already reports
+    # that arena in bytes, which is the number an integrator can act on.
+    for what, count in (("textures", len(textures)), ("slots", len(slots)),
+                        ("screens", len(screens)), ("cluts", len(cluts))):
+        if count > 0xFFFF:
+            errors.append(
+                f"{what}: {count} does not fit the format's uint16 count "
+                f"field. This is the format's own limit, not a runtime one."
+            )
+
+    # Capacity used to be checked against PS2UI_SLOT_BUFSZ, the
+    # runtime's fixed per-slot buffer. There is no such buffer any more
+    # (v6 resource model): the runtime sizes each slot's storage from
+    # the capacity declared here, so a large capacity costs arena bytes
+    # rather than being unloadable. The remaining bound is the format's
+    # own -- capacity is a uint16 field.
+    for sl in slots:
+        if sl["capacity"] > 0xFFFF:
+            errors.append(
+                f"slot {sl['name']!r}: capacity {sl['capacity']} does not fit "
+                f"the format's uint16 capacity field."
+            )
+
+    return errors, caps
+
+
+def summary(textures, cluts, slots, screens, caps: dict) -> str:
+    # Counts, not fractions. "15/16 slots" was a useful line while the
+    # denominator was a wall you could hit; printing a fraction of
+    # 65535 would just be a number with a decorative second half, and
+    # the figure that actually constrains a UI now -- the arena -- is
+    # printed on its own line by cli.py.
+    del caps
+    return (
+        f"  runtime tables: {len(textures)} textures, {len(cluts)} CLUTs, "
+        f"{len(slots)} slots, {len(screens)} screens"
+    )