spritegen-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/.github/workflows/ci.yml

@@ -117,3 +117,32 @@ jobs:
         # is added to the command, and that is the assertion — a wheel that needs a
         # hand-passed git URL to start is a wheel nobody can install.
         run: uv run --isolated --no-project --with dist/*.whl spritegen --version
+
+  page:
+    name: page
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: editor-ui/package-lock.json
+
+      - name: Install
+        working-directory: editor-ui
+        run: npm ci
+
+      - name: Build
+        working-directory: editor-ui
+        run: npm run build
+
+      - name: The committed page is the one this source builds
+        # `src/spritegen/editor/static` is committed because the wheel has to carry the
+        # page — a machine that installed the extra has no node. That makes it the one
+        # generated thing in this repository that can go stale silently, so the build
+        # runs here and the diff has to be empty.
+        run: git diff --exit-code -- src/spritegen/editor/static

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/.gitignore

@@ -226,3 +226,12 @@ assets/
 
 # the spritegen workspace's own settings, and its key
 .spritegen.json
+
+# The frontend build inputs. `editor-ui/dist` never exists: vite writes into the
+# package, at src/spritegen/editor/static, and that directory is committed on purpose.
+editor-ui/node_modules/
+
+# `assets/` above (Streamlit's block) matches every directory of that name, including
+# the one vite builds into. The built page is committed on purpose — the wheel carries
+# it, and `adr:0018` says why — so it is exempted here rather than renamed.
+!src/spritegen/editor/static/assets/

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: spritegen-cli
-Version: 0.4.0
+Version: 0.5.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
@@ -10,6 +10,9 @@ Requires-Dist: numpy>=1.26
 Requires-Dist: opencv-python>=5.0.0.93
 Requires-Dist: pillow>=10.0
 Requires-Dist: pydantic-settings>=2.0
+Provides-Extra: editor
+Requires-Dist: fastapi>=0.115; extra == 'editor'
+Requires-Dist: uvicorn>=0.30; extra == 'editor'
 Provides-Extra: matte
 Requires-Dist: rembg[cpu]>=2.0; extra == 'matte'
 Provides-Extra: upscale

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/README.md

@@ -12,7 +12,7 @@ the rest:
 
 ```
 pip install "spritegen-cli[upscale]"   # Real-ESRGAN locally, so a paid call need not buy resolution
-pip install "spritegen-cli[matte]"     # BiRefNet locally, so cutting a background costs nothing
+pip install "spritegen-cli[matte]"     # BiRefNet locally; the matte goes through the endpoint without it
 pip install "rembg[gpu]"               # ...and on the GPU, if this machine has the CUDA for it
 pip install "pixelfixer @ git+https://github.com/Retro-Diffusion/pixel-art-fixer.git#subdirectory=python"
                                        # the pixel-art direction, which recovers a native grid
@@ -27,11 +27,12 @@ spritegen anchor <character>     # the character, one image
 spritegen pose   <character>     # where an animation starts, when the anchor is not it
 spritegen motion <character>     # movement from a driving clip
 spritegen video  <character>     # or animate the anchor directly
-spritegen matte  <character>     # cut the background
+spritegen matte  <character>     # cut the background (paid; --backend local once the extra is in)
 spritegen board  <character>     # close it into a sheet row, 166 px cells
 spritegen upscale <character>    # enlarge an artifact locally, for nothing
 spritegen show   <character>     # every version it holds, and what comes next
 spritegen choose <character> <artifact> <version>   # which version everything else reads
+spritegen edit   <character>     # a local page: pick a version, fix a row (needs the [editor] extra)
 spritegen status
 spritegen cost
 spritegen init                   # write the Claude skill for all of this
@@ -45,6 +46,12 @@ Every run of a stage is kept: `anchor/v1`, `anchor/v2`, nothing overwritten. Gen
 several, then `choose` the one the rest of the pipeline reads — which is how the anchor
 `motion` deforms from gets picked.
 
+`edit` is the same two jobs with the sprite in front of you: it opens a page on
+`127.0.0.1`, draws every version side by side so choosing one is a click, and cuts a
+board by its grid so a frame can be dropped, reordered or nudged and the row saved as a
+new version. It spends nothing, and it closes the row through the same code `board`
+does.
+
 `motion` is the one that answers the problem the rest of this exists for. Generating a
 walk frame by frame moves the character instead of animating it — measured on the purple
 warrior sheet, the head-and-torso region shifts 0.25 between steps against the
@@ -73,9 +80,22 @@ written; `--dry-run` prints the payload and spends nothing.
 
 ## Running it
 
-Needs [uv](https://docs.astral.sh/uv/) and `FAL_KEY`. Export it, or copy
-`.env.template` to `.env` and put it there — the CLI reads a `.env` from the working
-directory on start-up, and an exported variable wins over the file.
+Needs [uv](https://docs.astral.sh/uv/) and a fal key.
+
+`spritegen init` opens a workspace in the directory it is run in and writes
+`.spritegen.json` there with `fal_key` empty; put the key in that file. It is added to a
+`.gitignore` that exists, and `init` warns when git is already tracking it.
+
+Passing the key on a command line — `FAL_KEY=... spritegen anchor` — works and is worth
+avoiding: it lands in the shell's history file and stays there.
+
+The file is plaintext at rest and is not safe merely for being a file: `init` narrows
+its permissions where the platform has them, adds it to a `.gitignore` that exists, and
+warns when the repository has none or when git already tracks it. What it buys over the
+history is that it can be deleted, ignored, and given permissions at all.
+
+An exported variable and a `.env` are still read, and both still win over the file,
+which is what makes a one-off override and a CI runner work.
 
 One dependency is not on PyPI: `pixelfixer`, from
 [Retro-Diffusion/pixel-art-fixer](https://github.com/Retro-Diffusion/pixel-art-fixer),

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/adr/0008-local-backends-are-the-default.md

@@ -1,5 +1,6 @@
 ---
-status: accepted
+status: superseded
+superseded-by: 0017-the-matte-goes-through-the-endpoint-by-default
 ---
 
 # Where a job can be done on this machine, local is the default and paid is the fallback

spritegen_cli-0.5.0/docs/adr/0017-the-matte-goes-through-the-endpoint-by-default.md

@@ -0,0 +1,49 @@
+---
+status: accepted
+---
+
+# The matte goes through the endpoint by default
+
+## Context
+
+`adr:0008-local-backends-are-the-default` made `matte --backend local` the default, on
+the reasoning that `rembg` runs the same family of model the endpoint does, costs
+nothing, and is no slower on a GPU. That reasoning still holds — for a machine that has
+the extra installed and a GPU worth using.
+
+What it does not describe is a machine that has just installed the tool. `rembg` is an
+optional extra of `adr:0007-heavy-dependencies-are-optional-extras`, so the default
+refused with an install line on every machine that had not run `uv sync --extra matte`,
+and the first thing a new workspace met at this stage was a setup errand rather than a
+cut frame. The extra also pulls `onnxruntime`, whose GPU build depends on the machine's
+CUDA — a choice this project deliberately does not make for anybody
+(`adr:0007`'s consequence, and why `rembg[cpu]` is what the extra names).
+
+## Decision
+
+`matte_backend` defaults to `fal`. `--backend local` and `"matte_backend": "local"` in
+the workspace's `.spritegen.json` both select the local one, and a machine set up for it
+should say so once in the file rather than passing the flag every time.
+
+This supersedes `adr:0008-local-backends-are-the-default` **on the matte default only**.
+`upscale` stays local, and is still local-only.
+
+## Consequences
+
+**This stage now spends without being asked to**, which nothing else here does. It is
+declared paid, so `--dry-run` prints the payload and spends nothing, every call lands in
+the asset's `ledger.jsonl`, and `cost` reports it — the guards the always-paid stages
+have, applied to a stage that used to be free by default. That is the trade: the tool
+works on a fresh machine, and the invoice is where somebody has to look to notice.
+
+The paid backend joins frames into one image, so a board is one charge rather than six.
+The default is therefore cheaper per run than it looks, and `--no-join` is six times the
+price.
+
+A machine with the extra and a GPU now pays for what it could do for free until somebody
+sets `matte_backend`. The skill and the README say so where the backend is described,
+which is the only place it can be said before the first charge.
+
+The refusal naming the install line does not disappear — it moves to `--backend local`
+on a machine without the extra, which is where it belongs: asked for by name, refused by
+name.

spritegen_cli-0.5.0/docs/adr/0018-ship-the-editor-frontend-built.md

@@ -0,0 +1,47 @@
+---
+status: accepted
+---
+
+# Ship the editor's frontend built
+
+## Context
+
+`spritegen edit` serves a page, and a page written in React has to be built before a
+browser can run it. The build needs node; the people who install this tool install a
+Python wheel with `pip` or `uv`, and nothing in that path has node in it.
+
+Three ways to bridge that, and each puts the cost somewhere different:
+
+- **Load React from a CDN.** No build at all, and the editor stops working on a laptop
+  with no network — which is most of what this tool is for, since every local stage was
+  written so the machine could work for nothing.
+- **Build at install time.** `pip install` would need node present and would run npm on
+  a machine that asked for a sprite tool. It also makes the install fail for a reason
+  that has nothing to do with what was installed.
+- **Build here and commit the result.** The wheel carries the page, the install stays a
+  Python install, and node is a tool of this repository rather than of its users.
+
+## Decision
+
+`editor-ui/` holds the source and `npm run build` writes into
+`src/spritegen/editor/static`, which is committed and shipped in the wheel. Node is a
+development dependency of this repository and appears in no install path.
+
+A CI job builds the page and fails when `git diff` over that directory is not empty, so
+the committed page and the source that produced it cannot drift apart.
+
+## Consequences
+
+Built JavaScript is in the history, and a diff of it is unreadable. That is accepted:
+the file is generated, the source beside it is what gets reviewed, and the CI job is
+what says the two agree. Vite is configured to emit fixed filenames rather than hashed
+ones for the same reason — a rebuild shows up as a diff, not as a rename plus a delete.
+
+Anyone changing the page has to run the build before committing, and CI tells them so
+in one line if they forget.
+
+The alternative that stays open is dropping the build entirely — a page written in
+plain JavaScript needs no node and no committed artifact. That trade was not taken
+because the editor's state is a handful of interdependent values that change together,
+which is what a component tree is good at, but it is the obvious escape hatch if the
+build ever costs more than the page is worth.

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/glossary.md

@@ -36,4 +36,5 @@ use elsewhere, and listing it would report every correct use as a finding. Add a
 - **version** — one run of a stage, kept whole in a directory of its own under the artifact: `anchor/v1`, `anchor/v2`. Numbered from 1, never overwritten, and the unit a candidate is kept as.
 - **chosen version** — the version of an artifact that every later stage reads, recorded in `state.json` and moved by `choose`. The first one recorded is chosen; after that it never follows the newest.
 - **candidate** — a version that was generated and not chosen. Kept, because it was paid for.
+- **edit** — a change made in the editor to a board's grid, its frame order or a frame's offset inside its cell, saved as a new version of the row it produces and recorded with `stage: "edit"`. Not a stage: nothing in `stages.STAGES` is called this, and `stages` in the state file never mentions it.
 - **layout** — the on-disk shape of an asset directory, numbered. Layout 1 was a directory per stage; layout 2 is a directory per artifact kind, and `migrate` is the only thing that moves between them.

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/notes.md

@@ -45,3 +45,8 @@ over this file answers with the example above as well as with the notes. -->
 - 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
 - n-0007 2026-08-29 #gotcha @src/spritegen/__init__.py — the CLI version came from a hand-written __version__ in spritegen/__init__.py, a second copy of what pyproject.toml declares — it read 0.1.0 through three releases; it is importlib.metadata now and a test pins the two together
+- n-0008 2026-08-29 #gotcha @src/spritegen/skill/files/SKILL.md — the generated skill told an agent to export FAL_KEY, and an exported key lands in the shell history file where it outlives the session - the skill sends it to .spritegen.json now, and a test refuses the export wording
+- n-0009 2026-08-30 #gotcha @tests/conftest.py — the editor's route tests hand httpx.Client.send back to itself, because conftest's no_network closes the same call the ASGI test client goes through
+- n-0010 2026-08-30 #gotcha @src/spritegen/editor/edits.py — edits.apply normalises every cell to the first one's size, because cut_cells leaves the division remainder in the last cell and a repack must not
+- n-0011 2026-08-30 #gotcha @tests/test_edits.py — pasting an RGBA frame through itself as its own mask squares partial alpha; the identity-edit parity row is what caught it
+- n-0012 2026-08-30 #gotcha @src/spritegen/editor/static — the repository-wide 'assets/' ignore also matched the editor's built page; it is exempted in .gitignore rather than renamed

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/stack.md

@@ -39,6 +39,11 @@ inference from the import sites, it says so.
   own runtime extras is chosen, and it refuses by calling `sys.exit()`. A GPU build is
   `pip install "rembg[gpu]"` over the top, because which onnxruntime-gpu works depends
   on the machine's CUDA.
+- **fastapi** (`[editor]`) — the routes `spritegen edit` serves. It is an extra and not a
+  dependency because it is the only command that serves anything: `status`, `cost` and
+  every stage answer on a machine that never installed it. Small enough that the dev
+  group installs it too, so CI runs the editor's routes rather than skipping them.
+- **uvicorn** (`[editor]`) — the ASGI server behind that app, bound to 127.0.0.1 only.
 
 ## Not on a registry
 
@@ -49,6 +54,21 @@ inference from the import sites, it says so.
   everyone else. `imaging.require_pixelfixer` names the command when it is missing.
   Pinned in `uv.lock` to commit `ef376e5` of `Retro-Diffusion/pixel-art-fixer`.
 
+## The editor's page
+
+Built by hand here and never on the machine that installs the tool: `npm run build` in
+`editor-ui/` writes into `src/spritegen/editor/static`, that directory is committed, and
+the wheel carries it. See `adr:0018-ship-the-editor-frontend-built`.
+
+- **React** — the page `spritegen edit` serves. It is a handful of pieces of state that
+  all change together — the grid, the frames kept, the offsets, the preview — which is
+  the shape a component tree is for and the shape hand-written DOM updates get wrong.
+- **Vite** — the build, and the dev server that proxies `/api` at the running editor.
+  It emits one script and one stylesheet under fixed names rather than hashed ones, so a
+  rebuild is a diff and not a rename.
+- **Node** — a development tool of this repository and never an install-time one. CI
+  builds the page and fails when what is committed is behind the source.
+
 ## Development
 
 - **uv** — the resolver, the lock and the runner. `uv sync --frozen` in every CI job,

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/wiki/changelog.md

@@ -3,6 +3,7 @@
 What changed in the wiki, and when. Newest first, one line per change, naming the pages
 it touched.
 
+- 2026-08-30 — `spritegen edit` opens a local page to pick between versions and correct a sheet row, in [[the-editor]]
 - 2026-08-28 — frames are read off the driving cycle's phase, the seed is recorded, clips and uploads are kept, and the duration and resolution defaults came down, in [[motion-transfer]]
 - 2026-08-28 — layout 3: every run of a stage is a version and the state names the chosen one, in [[the-asset-directory]]
 - 2026-08-28 — first pass, reconstructed from the code rather than remembered: added [[the-pipeline]], [[the-asset-directory]], [[paid-calls-and-the-ledger]], [[motion-transfer]], [[grid-and-palette-recovery]], [[local-instead-of-paid]], [[configuration]] and [[the-generated-skill]]

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/wiki/index.md

@@ -15,4 +15,5 @@ character sheet, one named stage at a time. Start with [[the-pipeline]].
 - [[grid-and-palette-recovery]] — closing a board into a sheet row without making the animation flicker or stand still
 - [[local-instead-of-paid]] — the three jobs done on this machine for nothing, and the import discipline that keeps them optional
 - [[configuration]] — one settings class, and the upward search that has a ceiling for a reason
+- [[the-editor]] — the one command that shows you the sprite: picking between candidates, correcting a row, and the two rules that keep it from being a second record
 - [[the-generated-skill]] — what `init` writes, and why half of it is generated from the registry

{spritegen_cli-0.4.0 → spritegen_cli-0.5.0}/docs/wiki/pages/local-instead-of-paid.md

@@ -19,9 +19,14 @@ resolution — the one thing a model like this puts back.
 
 The local matte is not a lesser substitute either. `rembg` runs BiRefNet, the same family
 of model the paid endpoint's `Matting` variant is; on a machine with CUDA the difference
-is seconds and no invoice, and on one without it still runs on the CPU. It is the
-**default**, and everything downstream is identical: the same files land in the same
-directory with the same names, and `board` cannot tell which backend ran.
+is seconds and no invoice, and on one without it still runs on the CPU.
+
+**It is no longer the default** — `adr:0017-the-matte-goes-through-the-endpoint-by-default`
+reversed that, because the extra it needs is optional and the default refused with an
+install line on every machine that had not installed it. A machine set up for local says
+so once, with `"matte_backend": "local"` in its `.spritegen.json`. Everything downstream
+is identical either way: the same files land in the same directory with the same names,
+and `board` cannot tell which backend ran.
 
 ## The joining trade, and why only the paid backend makes it
 
@@ -81,4 +86,4 @@ on its own.
 
 ## Records
 
-`adr:0007-heavy-dependencies-are-optional-extras` · `adr:0008-local-backends-are-the-default` · `adr:0011-keep-pixelfixer-out-of-the-distribution`
+`adr:0007-heavy-dependencies-are-optional-extras` · `adr:0008-local-backends-are-the-default` · `adr:0017-the-matte-goes-through-the-endpoint-by-default` · `adr:0011-keep-pixelfixer-out-of-the-distribution`

spritegen_cli-0.5.0/docs/wiki/pages/the-editor.md

@@ -0,0 +1,56 @@
+# The editor
+
+`spritegen edit <asset>` opens a page on the machine it is typed on. It is the only
+command that shows you the sprite instead of describing it, and it is free: every paid
+stage stays on the command line.
+
+## What it is for
+
+Two jobs the pipeline is bad at, and both are looking jobs.
+
+**Picking between candidates.** Every run of a stage is kept, and choosing between them
+from a terminal means reading `spritegen show`, opening files by hand, and typing
+`spritegen choose anchor 3`. The page draws every version of every artifact side by
+side, marks the chosen one, and moves the pointer on a click — see
+[[the-asset-directory]] for what a version is and what choosing one means.
+
+**Correcting a row.** A generated board comes back with a frame that is a smear, frames
+in the wrong order, or a figure that sits three pixels off in one cell. Regenerating it
+is a paid call for a problem that is three pixels wide. The page cuts the board by its
+grid, drops, reorders and nudges frames, previews the row, and saves it — closing the
+row through the same `sheet.board_to_row` the `board` stage uses, so an edited row and a
+generated one come out of one function ([[grid-and-palette-recovery]]).
+
+## What it never does
+
+It holds no record of its own. Every read is `report.inspect` and every write is
+`workspace.State` plus `save`, so the page and `spritegen show` cannot disagree about
+what an asset holds.
+
+It writes versions and never overwrites one: an edit lands as `sheet/sharp/v3`, recorded
+under the artifact with `stage: "edit"` and the edit that produced it. It is not written
+into `stages` — that map is the pipeline's completion record, and no stage called `edit`
+exists.
+
+It never chooses on your behalf when somebody already chose. A first version is chosen
+because there was nothing to decide; after that the pointer stays where it was put.
+
+It reaches no host and appends no line to the ledger ([[paid-calls-and-the-ledger]]).
+
+## How it is put together
+
+The server is fastapi and uvicorn, an optional `[editor]` extra resolved inside the
+command that needs it — the same shape `torch` and `rembg` have
+([[local-instead-of-paid]]). It binds `127.0.0.1` on a port the operating system picks.
+
+Six routes: the asset, one file, choose, preview, save, and the page itself. Every path
+the browser asks for goes through `workspace.inside`, which is the guard every path out
+of `state.json` already goes through — the query string is the one input here that
+something other than this tool writes.
+
+Every write carries the token its page was drawn from, built from `state.json`'s
+modification time and size. A stale one is a 409 telling the browser to read again. It
+is not a lock: it turns a silent overwrite into a re-read, which is the whole ambition.
+
+The page itself is React, built by vite into the Python package and committed there,
+because the wheel has to carry it — `adr:0018-ship-the-editor-frontend-built`.

spritegen_cli-0.5.0/editor-ui/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>spritegen</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>