art(review): local review app -- persistent verdicts + notes, multi-session (serve_review.py)

[PipFoweraker]

What

Turns the good art-review UX into a stateful, multi-session local app that covers all the art in one place -- the pixellab art_source/ track and the gpt-image art_generated/ track (game_icons, ui_icons, hero_banners, screen_backgrounds, terminal_textures, plus any new category dirs). Closes the "build.py doesn't read art_generated/" glue gap flagged in docs/art/ASSET_PIPELINE.md.

Adds one file: tools/art_review/serve_review.py (Python stdlib only -- http.server, no Flask/deps).

Why this instead of a static HTML

The static build.py -> style_review.html tool only saw the pixellab sweep and persisted to browser localStorage (fragile across sittings). This is a real local app you can CI/pipeline: verdicts + notes persist to a real file on disk.

How to run

python tools/art_review/serve_review.py            # serves http://127.0.0.1:8777, opens a browser
python tools/art_review/serve_review.py --port 9000
python tools/art_review/serve_review.py --art-root <dir>   # if art lives elsewhere (e.g. a worktree)

Run it from the checkout that has art_generated/ (the main checkout). It auto-opens a browser; --no-browser to skip.

What you get

• Every asset rendered on a checkered alpha backdrop, grouped by category, with a sticky section nav (jump chips with counts).
• Per asset: clickable keep / maybe / reroll verdict, a free-text note field, and comma-separated tags.
• Keyboard nav kept: arrows move focus, K/M/R stamp verdicts, N jumps to the note.
• Auto-persist: every edit POSTs to /api/state and is written to tools/art_review/review_state.json on disk (debounced for typing). Reload any time, across sessions -- your review is still there.

The pipeline contract

review_state.json is shaped for promote/reroll tooling to consume:

{
  "gen:game_icons:icon_doom:v2": {
    "verdict": "keep",
    "note": "love the grille",
    "tags": ["hero", "doom"],
    "updated_at": "2026-07-19T10:11:12.345678+00:00"
  }
}

asset_id is stable + pipeline-friendly: gen:<category>:<base_id>:<variant> for generated art (maps to manifest id + variant), px:<relpath> for pixellab. It's gitignored (per-reviewer local state).

No copies, no bloat

PNGs stream live from disk via /img?p=<relpath> (path-sandboxed to the art-root, .png only). The 1.1 GB gitignored art_generated/ tree is never copied or committed. One representative size per asset-variant (prefers 512px).

Verification

Smoke-tested end to end against the main checkout's real art:

• GET / -> 200, 909 cells across 25 sections (518 generated + 391 pixellab).
• GET /img?... -> 200 image/png; path traversal -> 403; non-png -> 404.
• POST verdict/note/tags -> written to review_state.json; reload re-embeds state (multi-session confirmed); toggling a verdict off and clearing note/tags prunes the empty entry.
• py_compile clean; pre-commit (black/isort/ruff, ASCII enforce) green.

Deferred (follow-up)

Verdict/tag filtering (show only un-reviewed / keep / reroll), side-by-side variant compare widget, and wiring review_state.json into promote_assets.py / a reroll generator.

Does NOT modify build.py (still the pixellab static-export tool) or commit any PNG / style_review.html / review_state.json.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.