spritegen-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/.gitignore

@@ -217,3 +217,9 @@ __marimo__/
 # Streamlit
 .streamlit/secrets.toml
 assets/
+
+# CodeGraph index — never committed
+.codegraph/
+
+# ai-jail sandbox configuration, local to a checkout
+.ai-jail

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spritegen-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Sprite generation CLI — a few AI-generated images into a game-ready character sheet
 Requires-Python: >=3.13
 Requires-Dist: av>=12.0

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/docs/adr/0003-append-only-jsonl-ledger.md

@@ -1,5 +1,6 @@
 ---
-status: accepted
+status: superseded
+superseded-by: 0015-record-the-call-before-the-files-it-writes
 ---
 
 # The record of a paid call is append-only JSONL

spritegen_cli-0.3.0/docs/adr/0015-record-the-call-before-the-files-it-writes.md

@@ -0,0 +1,53 @@
+---
+status: accepted
+---
+
+# The ledger records a call before the files it writes
+
+## Context
+
+`adr:0003-append-only-jsonl-ledger` puts one line per paid call in `ledger.jsonl`,
+carrying the endpoint, the payload, the URLs returned and the sha256 of every file
+written. A line can only carry those digests once the files exist, so the write had to
+wait for them.
+
+What sits between the endpoint answering and the files landing is a download, a decode
+and a pack. Any of it can fail — a dropped transfer, a clip `av` will not open, a full
+disk — and the money is already spent when it does. The ledger is the only record that
+a call happened, and in exactly that case it recorded nothing at all: the failure it
+exists to survive was the one it did not.
+
+Appending is what makes the file safe to write from a run that dies, and it is also
+what stops the line being completed later. A record cannot be both written early and
+filled in afterwards.
+
+## Decision
+
+A paid call is **two lines joined by a `call` id**, not one.
+
+The first is written the moment the endpoint answers, before anything is downloaded:
+`kind: "call"`, with the endpoint, the redacted payload and the URLs. The second is
+written when the files land: `kind: "files"`, with the sha256 of each. A stage whose
+whole output is what the call returned, with nothing to download, still writes one
+line.
+
+`summarise` counts a call where `kind` is not `"files"`, so the two lines fold to one
+call and one set of files.
+
+## Consequences
+
+A run that dies mid-download leaves a `call` line with no `files` line. That is the
+point: the asset's ledger says the money went, and the absent second line says nothing
+landed. `cost` reports the call.
+
+A line written before this decision has no `kind`, and is read as a whole call on its
+own — old ledgers keep totalling to what they always did, and the format stays
+append-only, so nothing on disk is rewritten.
+
+The cost is that a reader can no longer assume one line is one call, and that the two
+lines of a call are adjacent only in practice — a concurrent run against one asset
+would interleave them, and the `call` id is what makes that legible rather than the
+line order.
+
+This supersedes `adr:0003-append-only-jsonl-ledger` on the shape of a line only. Its
+other decisions — append-only, upload URLs redacted, one file per asset — stand.

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/docs/codewiki/spending-money.md

@@ -6,7 +6,7 @@ goes wrong rather than because of a way it works.
 
 ## A URL an endpoint returned is still a URL somebody could have chosen
 
-[src/spritegen/fal.py:24-86]()
+[src/spritegen/fal.py:24-88]()
 
 The allowed hosts are a fixed tuple plus whatever `SPRITEGEN_ALLOWED_HOSTS` adds. The
 scheme must be https, and an authority carrying userinfo is refused outright — `https://
@@ -16,7 +16,7 @@ check.
 
 ## The redirect chain is walked here, not by the client
 
-[src/spritegen/fal.py:88-156]()
+[src/spritegen/fal.py:153-218]()
 
 This is the reason `httpx` is a dependency at all. A client following redirects itself
 would apply the host check to the URL that was handed in and to nothing after it, so one
@@ -25,7 +25,7 @@ hop out of the allowed set is enough to fetch from anywhere. Every hop is checke
 
 ## One door, and two refusals before anything is spent
 
-[src/spritegen/fal.py:166-211]()
+[src/spritegen/fal.py:220-241]()
 
 `require_key` and the `dry_run` branch live in `call` rather than in each stage, so no
 stage can forget one. `_subscribe` is the only function that touches `fal_client`, and it
@@ -34,7 +34,7 @@ without an HTTP client and what lets a test stand in for the endpoint without on
 
 ## The record redacts what would otherwise be a key
 
-[src/spritegen/ledger.py:23-59]()
+[src/spritegen/ledger.py:30-65]()
 
 `fal_client.upload_file` returns standing access to the uploaded file for anyone holding
 the link. Writing those into the ledger verbatim would turn a per-asset record into a way
@@ -44,7 +44,7 @@ named explicitly.
 
 ## One line, appended, never rewritten
 
-[src/spritegen/ledger.py:75-125]()
+[src/spritegen/ledger.py:81-141]()
 
 JSONL and `append` rather than a document re-serialised whole, because a run that dies
 halfway has still spent the money. A format that rewrites the file to add a line can lose

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/docs/codewiki/the-stage-registry.md

@@ -5,9 +5,14 @@ builds its sub-commands from it, `workspace` checks order against it, and `skill
 generates the published tables out of it. Reading the file tells you what it holds;
 this page is why it holds it there rather than in the stages.
 
+It is three files. `registry.py` is the two dataclasses a stage is described with,
+`catalog.py` is the table itself — four fifths of the whole by line count and none of
+its behaviour — and `__init__.py` is the lookup, which is what a reader of the registry
+came for.
+
 ## An option is declared by the registry, not by the stage that takes it
 
-[src/spritegen/stages/__init__.py:21-35]()
+[src/spritegen/stages/registry.py:12-26]()
 
 The obvious place for `--size` is inside `anchor`. It is here instead because `--help`
 has to be complete, and building help from the stages would mean importing five modules
@@ -16,7 +21,7 @@ value off the parsed namespace and knows nothing about how it was parsed.
 
 ## `requires` is any-one-of, because the pipeline forks
 
-[src/spritegen/stages/__init__.py:38-43]()
+[src/spritegen/stages/registry.py:29-54]()
 
 `motion` and `video` produce the same artifact by different routes, and `matte` takes
 whichever ran. A field meaning *all of these* would have no way to express that, and the
@@ -24,7 +29,7 @@ fork is the shape of the tool rather than an exception in it.
 
 ## Kind and variant, once the stage stopped being the artifact
 
-[src/spritegen/stages/__init__.py:44-67]()
+[src/spritegen/stages/registry.py:29-59]()
 
 `produces` was the stage's name for as long as a stage made one thing. `anchor` makes an
 anchor, box art or an icon; `board` closes one set of frames into as many art directions
@@ -38,7 +43,7 @@ Both name an option this stage already declares, and neither is turned into a pa
 
 ## Order is derived, and there is no list of it
 
-[src/spritegen/stages/__init__.py:440-473]()
+[src/spritegen/stages/__init__.py:43-63]()
 
 `order` walks the table rather than reading a sequence somebody maintained beside it. A
 second record of the pipeline's shape would be the one that goes stale the first time a
@@ -46,7 +51,7 @@ stage is added.
 
 ## The module is resolved only when the command has been chosen
 
-[src/spritegen/stages/__init__.py:476-490]()
+[src/spritegen/stages/__init__.py:66-80]()
 
 This is the reason the registry can describe the whole pipeline without importing Pillow,
 numpy or `fal_client`. It also decides the blast radius of a broken stage: an import

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/docs/codewiki/the-workspace.md

@@ -6,7 +6,7 @@ refusing things.
 
 ## Every upward search stops, and the stop is the security control
 
-[src/spritegen/workspace.py:72-103]()
+[src/spritegen/workspace.py:70-101]()
 
 A command is typed from wherever is convenient, so searching upward for the project is
 right. Searching upward without a ceiling reaches the filesystem root, and everything
@@ -16,7 +16,7 @@ directory nobody chose to configure this tool.
 
 ## Where the assets are, and why the order is the design
 
-[src/spritegen/workspace.py:105-140]()
+[src/spritegen/workspace.py:103-138]()
 
 The explicit variable wins first, which is what lets a test and a second collection of
 characters exist at all. The nearest existing `spritegen/assets/` comes next because that
@@ -25,9 +25,9 @@ else's, so the images belong to that project rather than to the tool.
 
 ## A name off a command line becomes a directory
 
-[src/spritegen/workspace.py:51-70]()
+[src/spritegen/workspace.py:49-68]()
 
-[src/spritegen/workspace.py:142-170]()
+[src/spritegen/workspace.py:140-168]()
 
 The forbidden set and the reserved names are Windows', and they are checked on every
 platform. An asset name arrives from an argument or from a state file written earlier,
@@ -36,7 +36,7 @@ on Windows — which is why CI runs the suite on three operating systems rather
 
 ## Kind, variant and version become a path in exactly one place
 
-[src/spritegen/workspace.py:440-469]()
+[src/spritegen/workspace.py:476-505]()
 
 Every stage writes through this. That is what let layout 1 become layout 2 without each
 stage learning about the move, layout 2 become layout 3 the same way, and it is what
@@ -44,9 +44,9 @@ stage learning about the move, layout 2 become layout 3 the same way, and it is
 
 ## Which version a run writes, and which one it reads
 
-[src/spritegen/workspace.py:491-505]()
+[src/spritegen/workspace.py:527-541]()
 
-[src/spritegen/workspace.py:650-692]()
+[src/spritegen/workspace.py:667-684]()
 
 Two records go into picking a number and neither is trusted over the other: what the
 state file recorded, and what is on disk. They disagree when a run died between writing
@@ -64,7 +64,7 @@ has none, so a re-run cannot re-aim the paid stages that follow it — that is
 
 ## A recorded path is not trusted
 
-[src/spritegen/workspace.py:511-534]()
+[src/spritegen/workspace.py:547-570]()
 
 The state file holds relative paths, and it is a file on disk that something else may
 have written. `inside` is the check that a recorded path still resolves within the asset
@@ -73,7 +73,7 @@ another asset's output because the state said so.
 
 ## What "ready" means when `requires` forks
 
-[src/spritegen/workspace.py:378-418]()
+[src/spritegen/workspace.py:414-454]()
 
 `satisfied` is where the registry's any-one-of semantics turn into a decision, and
 `next_stages` is what `status` prints. Both read the registry; neither keeps a copy of

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/docs/notes.md

@@ -41,3 +41,6 @@ over this file answers with the example above as well as with the notes. -->
 - n-0001 2026-08-28 #gotcha @src/spritegen/workspace.py — Context.version is resolved on the first ask for out and kept, so a stage that opens its output twice in one run writes both halves to the same version
 - n-0002 2026-08-28 #gotcha @tests/conftest.py — settings.DEFAULT_CACHE is built from Path.home() at import, so conftest moving home afterwards does not move the cache; the suite points SPRITEGEN_CACHE at a temporary directory instead
 - n-0003 2026-08-28 #gotcha @pyproject.toml — the assets root spritegen/ in the repo root shadows the package name, so coverage source=[spritegen] resolves to the empty assets directory and collects nothing — source_pkgs is the unambiguous form
+- n-0004 2026-08-28 #gotcha @src/spritegen/sheet.py — the GIF preview writes one global palette plus one shared local palette whatever the frames were quantised with — Pillow unifies on save, so quantising per frame and quantising the strip produce the same file
+- n-0005 2026-08-28 #gotcha @src/spritegen/upscale.py — the weight cache sidecar must stay a content hash — size and mtime are forgeable with the same write access a swap needs, so a stat-based fast path silently disables the check
+- n-0006 2026-08-28 #gotcha @docs/codewiki/the-workspace.md — a codewiki citation that still resolves after a refactor is not still correct — the range shifts onto a neighbouring function and validate cannot tell, so check what each range opens on

spritegen_cli-0.3.0/plans/code-health.md

@@ -0,0 +1,119 @@
+---
+autonomy: auto
+ci: wait
+status: approved
+pr: per-group
+merge: auto
+checksum: a381e0be7b8276b7d56f6be879477d27acc6bab7600bae8957b6bee7d8d0b577
+---
+
+# Code health
+
+Clear what a full read of `src/` and `tests/` turned up: ten defects, seven places
+that repeat work already done, four modules that carry more than one job, and a test
+suite that pays for video encoding no assertion reads.
+
+## Why
+
+None of this was found by a failure — the suite is green and has been. It is what a
+deliberate read found sitting under green tests, which is why it is worth landing as
+one piece of work rather than waiting for each item to announce itself. Three of the
+defects lose something a user cannot get back: a paid call whose ledger line is never
+written, a re-fetch that deletes the good file it was going to replace, and a weight
+file that stops being checked the moment its digest sidecar goes missing. The rest is
+waste that compounds — a 64 MB model re-read per image, a colour count that allocates
+one tuple per pixel of an upscaled frame, twenty-five tests re-encoding the same clip
+at the slowest x264 preset. Done when the defects are fixed with tests that would have
+caught them, the repeated work happens once, the four oversized modules are split
+along the seams the survey mapped, and the suite is faster with no coverage lost.
+
+## Paths
+
+- `src/spritegen/` — `workspace.py`, `fal.py`, `upscale.py`, `imaging.py`, `clip.py`,
+  `drive.py`, `matting.py`, `sheet.py`, `cli.py`, `atlas.py`, `ledger.py`
+- `src/spritegen/stages/` — `__init__.py`, `motion.py`, `pose.py`, `video.py`,
+  `anchor.py`, `matte.py`, `board.py`
+- `src/spritegen/skill/__init__.py`
+- `tests/` — `conftest.py`, `helpers.py`, `test_motion.py`, `test_video.py`
+
+## References
+
+- `adr:0003-append-only-jsonl-ledger` — one line per paid call, carrying the sha256 of
+  every file written. Task 1.1 cannot hold to both halves at once and supersedes it.
+- `adr:0006-centralise-configuration-and-never-cache-it` — nothing is cached and
+  `load()` builds a new object every call. Task 3.5 resolves once per command and
+  passes it down, which is the shape that ADR permits; a module-level cache is not.
+- `adr:0004-allow-list-every-downloaded-host` — the host check task 1.9 walks results
+  for.
+- `adr:0007-heavy-dependencies-are-optional-extras` — why `available()` exists at all,
+  which task 4.7 decides the fate of.
+
+## Out of scope
+
+- The unbounded recursion in `fal.seed_in` and `fal.urls_in`: a hostile response nested
+  a thousand levels deep raises `RecursionError` after billing. Hosts are allow-listed
+  and the impact is one denied run; it is filed on PR #17 and belongs with a review of
+  what else trusts endpoint JSON shape.
+- Introducing `ruff format`. No formatter is configured here and adding one rewrites
+  the tree in a commit nobody can read.
+- Raising the coverage floor. The real number is 91.36% against a floor of 86, but it
+  has been there for one day.
+
+## Tasks
+
+- [x] 1.1 (TDD) Record the paid call in the ledger before the files it writes, and supersede `adr:0003` with the two-line shape
+- [x] 1.2 (TDD) Download to a partial file and rename on success, so a failed re-fetch cannot delete the good file
+  _Depends 1.1_
+- [x] 1.3 (TDD) Write the weight digest when the sidecar is missing, and stop the `finally` arm deleting a completed download
+- [x] 1.4 (Unit) Default `--device` to `None` so the setting is reachable and a dry run names the device the real run will use
+- [x] 1.5 (Unit) Make `matte --mask` on the local backend either write the mask or say it cannot
+- [ ] 1.6 (Unit) Quantise the GIF preview once over the strip instead of a palette per
+      frame
+  _Status removed_
+  _Reason measured against the parity fixture: Pillow already writes one global palette plus one shared local palette whatever the frames were quantised with, so the per-frame ADAPTIVE call produces the same two palettes the strip does — the change grew the file by 800 bytes, altered no palette, and broke a documented parity baseline_
+- [x] 1.7 (Unit) Map transport, codec and OS errors to exit codes, and narrow the catch that turns an internal bug into a user message
+- [x] 1.8 (Unit) Name the file when `state.json` does not parse
+- [x] 1.9 (Unit) Keep walking under a `url` key whose value is not a string
+- [x] 1.10 (Unit) Generate the skill's free-command table from the parser instead of maintaining a second copy
+- [x] 2.1 (Unit) Build the upscale network once per command and pass it to each file
+- [x] 2.2 (Unit) Count colours before the upscale and without a tuple per pixel
+- [x] 2.3 (TDD) Choose the wanted frame indices before decoding, and keep only those
+- [ ] 2.4 (Unit) Re-hash a cached weight only when its size or mtime changed
+  _Status removed_
+  _Reason the win it chased was already delivered by 2.1 — with the network built once per command the weight is hashed once per command either way — and the mechanism defeated the integrity check beside it: size and mtime are forgeable with the same write access the attack needs, so a matching stamp let a swapped weight through unhashed and silent_
+- [x] 2.5 (Unit) Resolve settings once per command and pass them down, adding no cache
+  _Depends 1.4_
+- [x] 2.6 (Unit) Measure alpha in memory, read the sheet once per build, and skip the crops a run without a GIF throws away
+- [x] 2.7 (Unit) Compare found against recorded with sets, not lists
+- [x] 3.1 (Unit) Move the stage catalogue out of `stages/__init__.py` into its own module
+- [ ] 3.2 (Unit) Declare the chroma, prompt, reference and frame-extraction options once
+      and splice them into each stage
+  _Depends 3.1_
+  _Status removed_
+  _Reason only the chroma and despill cluster was duplicated verbatim, and that is done. The prompt, reference and frame-extraction options share flags, kinds and defaults but not their help text: motion explains that the driving cycle caps --frames and video explains that an image-to-video clip opens on a still input image, which is the part of an option worth having. Replaced by 3.8_
+- [x] 3.3 (Unit) Give `Context` the anchor lookup the three stages copy, and drop the cross-stage import
+- [x] 3.4 (Unit) Extract the reference-file check, the missing-URL guard and the chroma finish that each exist three or four times
+  _Depends 3.3_
+- [x] 3.5 (Unit) Extract the layout refusal and the artifact-key composition to one place each
+- [x] 3.6 (Unit) Have the two grid packers share their arithmetic
+- [x] 3.7 (Unit) Split `workspace.py` along the seams the survey mapped, presentation first
+  _Depends 3.3, 3.5_
+- [x] 4.1 (Unit) Delete what nothing calls, and decide whether the availability helpers get a caller or go
+- [x] 5.1 (Unit) Stop the motion tests encoding at 720 and the slowest preset
+- [ ] 5.2 (Unit) Share the cache across the session so the same driving clip encodes
+      once
+  _Depends 5.1_
+  _Status removed_
+  _Reason measured after 5.1: an encode is 20ms at the cell size the tests now use, so sharing the cache across the session saves about 1s of a 20.8s suite, bought with mutable state shared across 799 tests against the one fixture whose purpose is isolating them_
+- [x] 5.3 (Unit) Move the fixtures copied across eleven files into `conftest.py`
+  _Depends 5.1_
+- [x] 3.8 (Unit) Declare the chroma and despill options once and splice them into the
+      three stages that cut
+  _Reason 3.2 asked for four option groups and only one of them was duplication; this is what was actually built_
+
+## Done when
+
+- `uv run pytest -q --cov` passes with coverage no lower than 91.36%.
+- `uv run ruff check src tests` and `scc validate` both exit 0.
+- Every task above is ticked or struck out with a reason.
+- The suite's wall-clock time is lower than the 34 s it takes now, measured the same way.

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spritegen-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Sprite generation CLI — a few AI-generated images into a game-ready character sheet"
 requires-python = ">=3.13"
 

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/src/spritegen/atlas.py

@@ -35,6 +35,31 @@ def grid_for(count: int) -> tuple[int, int]:
     return cols, rows
 
 
+def lay_out(images: list, cols: int) -> tuple:
+    """Paste images into a grid `cols` wide, and say where each one landed.
+
+    The cell is the largest image in the set, so every cell is the same size and the
+    grid can be read back by arithmetic alone — which is what both callers need and
+    what each of them used to compute for itself.
+    """
+    from PIL import Image
+
+    if not images:
+        raise ValueError("nothing to pack")
+
+    cell_w = max(image.width for image in images)
+    cell_h = max(image.height for image in images)
+    rows = math.ceil(len(images) / cols)
+
+    canvas = Image.new("RGBA", (cell_w * cols, cell_h * rows), (0, 0, 0, 0))
+    boxes = []
+    for index, image in enumerate(images):
+        left, top = (index % cols) * cell_w, (index // cols) * cell_h
+        canvas.paste(image.convert("RGBA"), (left, top))
+        boxes.append([left, top, left + image.width, top + image.height])
+    return canvas, boxes, (cell_w, cell_h), rows
+
+
 def pack(paths: list[Path], out: Path) -> dict:
     """Write one atlas holding every image, and return where each of them went."""
     from PIL import Image
@@ -43,18 +68,11 @@ def pack(paths: list[Path], out: Path) -> dict:
         raise ValueError("nothing to pack")
 
     images = [Image.open(path).convert("RGBA") for path in paths]
-    cell_w = max(image.width for image in images)
-    cell_h = max(image.height for image in images)
     cols, rows = grid_for(len(images))
-
-    atlas = Image.new("RGBA", (cell_w * cols, cell_h * rows), (0, 0, 0, 0))
-    placed = []
-    for index, (path, image) in enumerate(zip(paths, images, strict=True)):
-        left, top = (index % cols) * cell_w, (index // cols) * cell_h
-        atlas.paste(image, (left, top))
-        placed.append(
-            {"name": path.name, "box": [left, top, left + image.width, top + image.height]}
-        )
+    atlas, boxes, (cell_w, cell_h), rows = lay_out(images, cols)
+    placed = [
+        {"name": path.name, "box": box} for path, box in zip(paths, boxes, strict=True)
+    ]
 
     out.parent.mkdir(parents=True, exist_ok=True)
     atlas.save(out)

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/src/spritegen/cli.py

@@ -18,6 +18,7 @@ having to push it into the process first.
 from __future__ import annotations
 
 import argparse
+import os
 import sys
 from collections.abc import Sequence
 
@@ -61,7 +62,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--model", choices=("anime", "general"), help="which weights; default from settings"
     )
     upscale.add_argument(
-        "--device", choices=("auto", "cuda", "cpu"), default="auto", help="where it runs"
+        "--device", choices=("auto", "cuda", "cpu"), help="where it runs; default from settings"
     )
     upscale.add_argument("--dry-run", action="store_true", help="print the files and touch none")
 
@@ -148,11 +149,11 @@ def _free_commands() -> dict:
     the skill it writes. All of those modules are cheap to import, which is what makes a
     free command answer without loading Pillow, numpy or fal_client.
     """
-    from . import migrate, skill, upscale, workspace
+    from . import migrate, report, skill, upscale
 
     handlers = {}
     for module, commands in (
-        (workspace, ("new", "status", "show", "cost", "choose")),
+        (report, ("new", "status", "show", "cost", "choose")),
         (skill, ("init",)),
         (migrate, ("migrate",)),
         (upscale, ("upscale",)),
@@ -175,7 +176,16 @@ def main(argv: Sequence[str] | None = None) -> int:
     except NotImplementedError as exc:
         print(f"spritegen: {exc}", file=sys.stderr)
         return 3
-    except (KeyError, FileNotFoundError, FileExistsError, ValueError) as exc:
+    except (KeyError, OSError, ValueError) as exc:
+        # OSError covers the file errors this used to name one at a time, plus the ones
+        # it did not: a read-only asset directory, a locked state file, a full disk.
+        #
+        # KeyError and ValueError are how this project refuses — StageRefused, Untrusted,
+        # Transport and an unknown model are all one of the two — but they are also what
+        # an ordinary bug raises, and a bug printed as one tidy line is a bug nobody can
+        # report. SPRITEGEN_DEBUG asks for the traceback instead.
+        if os.getenv("SPRITEGEN_DEBUG"):
+            raise
         print(f"spritegen: {exc}", file=sys.stderr)
         return 1
 

{spritegen_cli-0.2.0 → spritegen_cli-0.3.0}/src/spritegen/clip.py

@@ -13,19 +13,88 @@ from __future__ import annotations
 from pathlib import Path
 
 
-def decode_frames(video: Path) -> list:
-    """Every frame of the clip, in order."""
+def decode_frames(video: Path, keep: list[int] | None = None) -> list:
+    """Every frame of the clip, in order.
+
+    A file the codec will not open is reported as this file being undecodable, not as an
+    `av` traceback: the clip was paid for and downloaded, and what the user needs to know
+    is which file to look at.
+
+    `keep` names the frames worth building an image for, in clip order. The rest are
+    decoded — a codec cannot skip to frame N without them — and dropped rather than held.
+    """
     import av
 
-    with av.open(str(video)) as container:
-        stream = container.streams.video[0]
-        stream.thread_type = "AUTO"
-        images = [frame.to_image() for frame in container.decode(stream)]
+    wanted = None if keep is None else set(keep)
+    try:
+        with av.open(str(video)) as container:
+            stream = container.streams.video[0]
+            stream.thread_type = "AUTO"
+            if wanted is None:
+                images = [frame.to_image() for frame in container.decode(stream)]
+            else:
+                # Kept by index and then read back in the order asked for, because
+                # `--pick 3,3` is a legitimate request for one frame twice.
+                held = {
+                    index: frame.to_image()
+                    for index, frame in enumerate(container.decode(stream))
+                    if index in wanted
+                }
+                images = [held[index] for index in keep if index in held]
+    except (av.FFmpegError, IndexError) as exc:
+        raise ValueError(f"{video} could not be decoded: {exc}") from exc
     if not images:
         raise ValueError(f"{video} has no frames in it")
     return images
 
 
+def frame_count(video: Path) -> int:
+    """How many frames the clip holds, without building an image for any of them.
+
+    The container usually knows, and where it does not the frames are decoded and thrown
+    away — still far cheaper than `to_image` on every one, which is what the caller is
+    avoiding by asking.
+    """
+    import av
+
+    try:
+        with av.open(str(video)) as container:
+            stream = container.streams.video[0]
+            if stream.frames:
+                return int(stream.frames)
+            stream.thread_type = "AUTO"
+            return sum(1 for _ in container.decode(stream))
+    except (av.FFmpegError, IndexError) as exc:
+        raise ValueError(f"{video} could not be decoded: {exc}") from exc
+
+
+def frame_indices(
+    *, total: int, count: int, start: float, end: float, pick: list[int] | None
+) -> list[int]:
+    """Which frames of a clip of `total` answer the board — the choice, without the images.
+
+    Separate from `choose_frames` so the decode can keep only what this returns: a 5
+    second clip at 30fps is 150 frames of which six are used, and holding all of them as
+    images to throw 144 away is hundreds of megabytes.
+    """
+    if pick:
+        bad = [index for index in pick if not 0 <= index < total]
+        if bad:
+            raise ValueError(f"frame indices outside the clip (0..{total - 1}): {bad}")
+        return list(pick)
+
+    low, high = round(start * (total - 1)), round(end * (total - 1))
+    if high - low < 1:
+        raise ValueError(f"start and end left fewer than 2 frames of {total}")
+    window = list(range(low, high + 1))
+    if count >= len(window):
+        return window
+    # The window's last frame repeats its first when the cycle closes, so it is left
+    # out: taking both would put a standing step at the seam.
+    span = len(window) - 1
+    return [window[round(index * span / count)] for index in range(count)]
+
+
 def parse_pick(text: str | None) -> list[int] | None:
     """`12,17,22` to `[12, 17, 22]`."""
     if not text:
@@ -46,23 +115,7 @@ def choose_frames(
     after it — so extracting from zero spends one of six frames on a pose that does not
     belong to the cycle. `start` cuts that entry off.
     """
-    total = len(images)
-    if pick:
-        bad = [index for index in pick if not 0 <= index < total]
-        if bad:
-            raise ValueError(f"frame indices outside the clip (0..{total - 1}): {bad}")
-        return [images[index] for index in pick], list(pick)
-
-    low, high = round(start * (total - 1)), round(end * (total - 1))
-    if high - low < 1:
-        raise ValueError(f"start and end left fewer than 2 frames of {total}")
-    window = list(range(low, high + 1))
-    if count >= len(window):
-        return [images[index] for index in window], window
-    # The window's last frame repeats its first when the cycle closes, so it is left
-    # out: taking both would put a standing step at the seam.
-    span = len(window) - 1
-    indices = [window[round(index * span / count)] for index in range(count)]
+    indices = frame_indices(total=len(images), count=count, start=start, end=end, pick=pick)
     return [images[index] for index in indices], indices
 
 
@@ -112,15 +165,14 @@ def phase_indices(
 
 
 def pack_board(frames: list, cols: int, out: Path) -> tuple[int, int]:
-    """Lay the chosen frames out in a grid, so `sheet` can read one grid over them all."""
-    from PIL import Image
-
-    rows = (len(frames) + cols - 1) // cols
-    width = max(frame.size[0] for frame in frames)
-    height = max(frame.size[1] for frame in frames)
-    board = Image.new("RGBA", (width * cols, height * rows), (0, 0, 0, 0))
-    for index, frame in enumerate(frames):
-        board.paste(frame.convert("RGBA"), ((index % cols) * width, (index // cols) * height))
+    """Lay the chosen frames out in a grid, so `sheet` can read one grid over them all.
+
+    The grid arithmetic is `atlas.lay_out`: a board and an atlas are the same uniform
+    grid, and the two had it written out separately.
+    """
+    from . import atlas
+
+    board, _, _, rows = atlas.lay_out(frames, cols)
     out.parent.mkdir(parents=True, exist_ok=True)
     board.save(out)
     return cols, rows