Skip to content

notque/vexjoy-agent / skills/game/game-dev

game-dev

Flagged

Game development: design, asset pipelines, Phaser, Unity CLI and builds, vanilla JS frontend, GM mode, match booking.

FileKindSize
SKILL.mdskill md14.7 KB
references/anchor-alignment.mdmarkdown16.0 KB
references/animate-scaffolds.mdmarkdown2.0 KB
references/arcade-physics.mdmarkdown7.4 KB
references/artifacts-and-prototyping.mdmarkdown1.5 KB
references/asset-sources.mdmarkdown7.9 KB
references/audit-and-red-team.mdmarkdown795 B
references/autonomous-improvement.mdmarkdown10.3 KB
references/backend-chain.mdmarkdown10.4 KB
references/bg-removal-local.mdmarkdown22.7 KB
references/build-scaffolds.mdmarkdown2.0 KB
references/capabilities/01-design-red-team-audit.mdmarkdown3.9 KB
references/capabilities/02-emotional-canvas-moodboard.mdmarkdown3.7 KB
references/capabilities/03-game-design-attribution-audit.mdmarkdown3.6 KB
references/capabilities/04-game-design-bartle-archetype-audit.mdmarkdown3.7 KB
references/capabilities/05-game-design-big-five-personality-audit.mdmarkdown3.6 KB
references/capabilities/06-game-design-brainstorm-methods.mdmarkdown3.9 KB
references/capabilities/07-game-design-core-loop-extractor.mdmarkdown3.7 KB
references/capabilities/08-game-design-craft-critique.mdmarkdown3.5 KB
references/capabilities/09-game-design-creative-unblocker.mdmarkdown3.5 KB
references/capabilities/10-game-design-design-pillars-extractor.mdmarkdown3.5 KB
references/capabilities/11-game-design-emotional-canvas.mdmarkdown3.6 KB
references/capabilities/12-game-design-failure-loop-audit.mdmarkdown3.8 KB
references/capabilities/13-game-design-fairness-frustration-audit.mdmarkdown3.6 KB
references/capabilities/14-game-design-fantasy-extractor.mdmarkdown3.6 KB
references/capabilities/15-game-design-feature-prioritization.mdmarkdown3.6 KB
references/capabilities/16-game-design-five-options.mdmarkdown3.5 KB
references/capabilities/17-game-design-flow-audit.mdmarkdown3.6 KB
references/capabilities/18-game-design-fogg-behavior-audit.mdmarkdown3.6 KB
references/capabilities/19-game-design-friction-journey-audit.mdmarkdown3.8 KB
references/capabilities/20-game-design-ftue-hero-journey-audit.mdmarkdown3.7 KB
references/capabilities/21-game-design-goal-density-and-immediacy-audit.mdmarkdown3.5 KB
references/capabilities/22-game-design-goal-framing.mdmarkdown3.5 KB
references/capabilities/23-game-design-granular-player-motivation-audit.mdmarkdown4.0 KB
references/capabilities/24-game-design-grow-design.mdmarkdown3.5 KB
references/capabilities/25-game-design-ideal-outcome-backcasting.mdmarkdown3.4 KB
references/capabilities/26-game-design-kpi-coverage-audit.mdmarkdown3.8 KB
references/capabilities/27-game-design-leaderboard-audit.mdmarkdown3.9 KB
references/capabilities/28-game-design-leaderboard-builder.mdmarkdown3.8 KB
references/capabilities/29-game-design-molyneux-lens.mdmarkdown3.5 KB
references/capabilities/30-game-design-multiplayer-feature-audit.mdmarkdown3.8 KB
references/capabilities/31-game-design-novelty-spectrum-audit.mdmarkdown3.6 KB
references/capabilities/32-game-design-one-page-design-doc.mdmarkdown3.8 KB
references/capabilities/33-game-design-one-thing-to-remove.mdmarkdown3.6 KB
references/capabilities/34-game-design-option-generation.mdmarkdown3.5 KB
references/capabilities/35-game-design-peak-end-audit.mdmarkdown3.6 KB
references/capabilities/36-game-design-perceived-randomness-audit.mdmarkdown3.7 KB
references/capabilities/37-game-design-pitch-deck-audit.mdmarkdown3.8 KB
references/capabilities/38-game-design-player-motivation-audit.mdmarkdown3.5 KB
references/capabilities/39-game-design-player-need-satisfaction-audit.mdmarkdown3.6 KB
references/capabilities/40-game-design-player-persona-extractor.mdmarkdown4.2 KB
references/capabilities/41-game-design-player-perspective-reframe.mdmarkdown3.7 KB
references/capabilities/42-game-design-player-segment-perception-audit.mdmarkdown3.6 KB
references/capabilities/43-game-design-player-values-mapper.mdmarkdown3.8 KB
references/capabilities/44-game-design-premium-pass-audit.mdmarkdown3.8 KB
references/capabilities/45-game-design-prosocial-session-chapters.mdmarkdown3.7 KB
references/capabilities/46-game-design-prototype-intent-audit.mdmarkdown3.7 KB
references/capabilities/47-game-design-prototyping-companion.mdmarkdown3.6 KB
references/capabilities/48-game-design-roadblock-reframing.mdmarkdown3.5 KB
references/capabilities/49-game-design-smart-goal-audit.mdmarkdown3.6 KB
references/capabilities/50-game-design-social-satisfaction-matrix.mdmarkdown3.7 KB
references/capabilities/51-game-design-systematizing-empathizing-audit.mdmarkdown3.6 KB
references/capabilities/52-game-design-thinking-fast-and-slow-audit.mdmarkdown3.6 KB
references/capabilities/53-game-design-transformative-reuse.mdmarkdown3.6 KB
references/capabilities/54-game-design-unknown-unknowns-prototyping.mdmarkdown3.6 KB
references/capabilities/55-game-design-zeigarnik-effect-audit.mdmarkdown3.6 KB
references/capabilities/56-game-dev-budget-estimator.mdmarkdown3.8 KB
references/capabilities/57-game-dev-first-steps.mdmarkdown3.6 KB
references/capabilities/58-game-dev-team-gap.mdmarkdown3.6 KB
references/capabilities/59-game-dev-time-estimator.mdmarkdown3.8 KB
references/capabilities/60-moodboard-generator.mdmarkdown4.0 KB
references/capabilities/61-software-team-conflict-patterns.mdmarkdown3.8 KB
references/capability-catalog.mdmarkdown18.4 KB
references/capability-map.mdmarkdown1.7 KB
references/capability-matrix.mdmarkdown12.5 KB
references/capacitor-ios.mdmarkdown7.3 KB
references/cognition-and-choice.mdmarkdown1.2 KB
references/cognitive-and-behavioral-lenses.mdmarkdown1.2 KB
references/combat-effects-upgrade.mdmarkdown13.3 KB
references/combat-effects-upgrade/css-3d-card-transforms.mdmarkdown10.1 KB
references/combat-effects-upgrade/css-particle-migration.mdmarkdown13.3 KB
references/combat-effects-upgrade/framer-motion-combat-juice.mdmarkdown11.9 KB
references/concept-and-loop.mdmarkdown1.5 KB
references/core-loop-and-pillars.mdmarkdown835 B
references/core-patterns.mdmarkdown8.2 KB
references/cpu-systems-harmony.mdmarkdown3.4 KB
references/creative-and-options.mdmarkdown2.0 KB
references/creative-direction.mdmarkdown1.3 KB
references/deploy.mdmarkdown5.3 KB
references/design-artifacts.mdmarkdown1.0 KB
references/emotion-and-presentation.mdmarkdown1.1 KB
references/error-catalog.mdmarkdown22.6 KB
references/fairness-and-failure.mdmarkdown1.2 KB
references/fairness-and-learning.mdmarkdown1.3 KB
references/fal-ai-image.mdmarkdown7.1 KB
references/frame-detection.mdmarkdown20.0 KB
references/full-diagnostic.mdmarkdown4.2 KB
references/game-asset-generator.mdmarkdown9.5 KB
references/game-audio.mdmarkdown7.5 KB
references/game-feel-patterns.mdmarkdown12.2 KB
references/game-pipeline.mdmarkdown11.5 KB
references/game-qa.mdmarkdown6.7 KB
references/game-sprite-pipeline.mdmarkdown33.4 KB
references/gm-brilliant-implementation.mdmarkdown13.4 KB
references/grid-shapes.mdmarkdown8.0 KB
references/meshyai.mdmarkdown7.3 KB
references/motion-pipeline.mdmarkdown7.6 KB
references/output-formats.mdmarkdown9.4 KB
references/pacing-and-return.mdmarkdown1.6 KB
references/performance.mdmarkdown7.8 KB
references/phaser-gamedev.mdmarkdown7.5 KB
references/pipeline-spec.jsonconfig23.5 KB
references/pixel-art-sprites.mdmarkdown8.7 KB
references/pixijs-combat-renderer.mdmarkdown12.1 KB
references/pixijs-combat-renderer/combat-visual-effects.mdmarkdown7.8 KB
references/pixijs-combat-renderer/pixi-2d-lighting.mdmarkdown6.6 KB
references/pixijs-combat-renderer/pixi-particle-systems.mdmarkdown9.2 KB
references/pixijs-combat-renderer/pixi-performance.mdmarkdown4.8 KB
references/pixijs-combat-renderer/pixi-post-processing.mdmarkdown6.3 KB
references/pixijs-combat-renderer/pixi-react-integration.mdmarkdown5.2 KB
references/planning-and-communication.mdmarkdown1.6 KB
references/planning-and-production.mdmarkdown1.8 KB
references/player-and-social.mdmarkdown2.3 KB
references/polish-scaffolds.mdmarkdown1.9 KB
references/progression-and-economy.mdmarkdown1.0 KB
references/promo-video.mdmarkdown6.6 KB
references/prompt-rules.mdmarkdown15.2 KB
references/quality-gates.mdmarkdown6.4 KB
references/rive-skeletal-animator.mdmarkdown7.6 KB
references/rive-skeletal-animator/rive-animation-library.mdmarkdown8.1 KB
references/rive-skeletal-animator/rive-async-patterns.mdmarkdown5.6 KB
references/rive-skeletal-animator/rive-character-pipeline.mdmarkdown5.6 KB
references/rive-skeletal-animator/rive-performance.mdmarkdown5.4 KB
references/rive-skeletal-animator/rive-react-setup.mdmarkdown9.9 KB
references/rive-skeletal-animator/rive-vs-spine-decision.mdmarkdown6.0 KB
references/road-to-aew-integration.mdmarkdown7.8 KB
references/social-and-competitive-design.mdmarkdown1.1 KB
references/social-and-competitive.mdmarkdown1.5 KB
references/spritesheets.mdmarkdown6.2 KB
references/stage-contracts.mdmarkdown11.1 KB
references/style-presets.mdmarkdown5.1 KB
references/subagent-delegation.mdmarkdown2.2 KB
references/tilemaps-and-physics.mdmarkdown13.6 KB
references/tilemaps.mdmarkdown7.0 KB
references/unity-batchmode-builds.mdmarkdown9.2 KB
references/unity-cli.mdmarkdown10.9 KB
references/unity-licensing.mdmarkdown5.0 KB
references/vfx-containment.mdmarkdown3.1 KB
references/workflow-dag.mdmarkdown4.1 KB
references/worldlabs.mdmarkdown7.9 KB
references/wrestler-archetypes.mdmarkdown7.2 KB
scripts/deterministic_idle.pyscript7.8 KB
scripts/fal_queue_image_run.pyscript9.4 KB
scripts/imgdiff.pyscript5.0 KB
scripts/meshy-generate.mjsscript11.1 KB
scripts/optimize-glb.mjsscript3.8 KB
scripts/portrait_pipeline.pyscript31.2 KB
scripts/qa_artifacts.pyscript14.4 KB
scripts/road_to_aew_integration.pyscript6.6 KB
scripts/row_job_status.pyscript8.6 KB
scripts/sprite_anchor.pyscript30.1 KB
scripts/sprite_assemble.pyscript16.0 KB
scripts/sprite_bg.pyscript28.5 KB
scripts/sprite_canvas.pyscript11.9 KB
scripts/sprite_generate.pyscript13.9 KB
scripts/sprite_pipeline.pyscript54.9 KB
scripts/sprite_process.pyscript13.5 KB
scripts/sprite_prompt.pyscript41.8 KB
scripts/sprite_slicing.pyscript38.7 KB
scripts/sprite_verify.pyscript58.5 KB
scripts/test_content_aware_extraction.pyscript13.4 KB
scripts/test_no_status_laundering.pyscript6.9 KB
scripts/test_phases_4_5_7_8.pyscript16.4 KB
scripts/test_pipeline_glue.pyscript20.9 KB
scripts/test_pipeline_patterns.pyscript10.9 KB
scripts/test_rc3_frames_distinct_threshold.pyscript14.2 KB
scripts/test_rc4_mass_centroid_default.pyscript8.3 KB
scripts/test_rc5_despill_pre_upscale.pyscript7.9 KB
scripts/test_slice_grid_cells.pyscript6.4 KB
scripts/test_slicer_strict_pitch_default.pyscript11.6 KB
scripts/test_verifier_cell_parity.pyscript9.0 KB
scripts/test_verify_gates.pyscript23.2 KB
scripts/tests/test_fal_queue_image_run.pyscript908 B
scripts/video_extract_frames.pyscript4.3 KB
scripts/video_process_frames.pyscript7.6 KB
scripts/video_select_frames.pyscript6.4 KB
scripts/with_server.pyscript5.8 KB

scripts/sprite_pipeline.py

View on GitHub
#!/usr/bin/env python3
"""
Spritesheet-mode end-to-end orchestrator (Phases A-H).

Chains:
    A: reference character generation
    B: canvas template
    C: spritesheet generation
    D: connected-components frame extraction
    E: per-frame bg removal
    F: shared-scale + bottom-anchor normalization
    G: deterministic auto-curation (when --variants > 1)
    H: PNG sheet + GIF + WebP + Phaser atlas + per-direction strips

Per-row mode (--per-row, typically with --preset):
    A: canonical base character generation (identity lock)
    For each row in preset:
        B': layout guide generation
        C': per-row strip generation with identity lock + VFX containment
        D': per-strip slice (pitch = strip_width / expected_frames)
        E': per-frame bg removal on individually sliced frames
    F: normalize all frames together (consistent anchoring)
    H: assemble into final sheet with correct row/col mapping

Usage:
    python3 sprite_pipeline.py \\
        --prompt "wrestler walk cycle, 4 frames" \\
        --grid 4x1 --cell-size 256 --action walking \\
        --style slay-the-spire-painted

    python3 sprite_pipeline.py \\
        --preset fighter --per-row --dry-run --output-dir /tmp/test

--dry-run skips Phase A and C backend calls; uses a synthetic fixture
spritesheet for Phase D-H validation. Useful for CI smoke tests.
"""

from __future__ import annotations

import argparse
import hashlib
import json
import logging
import os
import shutil
import sys
import tempfile
import time
from datetime import datetime, timezone
from pathlib import Path

logger = logging.getLogger("sprite-pipeline.sprite_pipeline")

try:
    from PIL import Image, ImageDraw
except ImportError as e:
    logger.error("Pillow not installed: %s", e)
    sys.exit(1)

SCRIPT_DIR = Path(__file__).resolve().parent
sys.path.insert(0, str(SCRIPT_DIR))

import qa_artifacts
import sprite_bg
import sprite_canvas
import sprite_generate
import sprite_process
import sprite_prompt
from sprite_verify import (
    verifier_verdict_from_passed,
    verify_anchor_consistency,
    verify_frames_distinct,
    verify_frames_have_content,
    verify_grid_alignment,
    verify_no_magenta,
    verify_padding,
    verify_pixel_preservation,
    verify_raw_vs_final_cell_parity,
    write_manifest_record,
)

# Exit code emitted by run_pipeline / run_portrait_loop when --verify is on
# and at least one gate fails. Distinct from the generic pipeline-error rc=1
# so road-to-aew CI can branch on "verifier said no" vs "the pipeline blew
# up". Locked by ADR-199 ("Exit code: 0 when passed: true, 2 when any gate
# fails").
VERIFIER_EXIT_CODE = 2

# ADR-207 Rule 4: spritesheet-mode --no-verify returns a distinct non-zero
# exit code so orchestrators cannot silently mask spritesheet failures with
# the same exit status as success. Portrait and portrait-loop modes retain
# --no-verify -> exit 0 because their verifier surface is small enough
# (verify_no_magenta only) that an explicit skip is plausibly intentional.
VERIFIER_SKIPPED_EXIT_CODE = 3


def _sha256_file(path: Path) -> str:
    """Compute SHA256 hex digest of a file.

    Args:
        path: File path to hash.

    Returns:
        Lowercase hex digest string.
    """
    digest = hashlib.sha256()
    with path.open("rb") as fh:
        for block in iter(lambda: fh.read(1024 * 1024), b""):
            digest.update(block)
    return digest.hexdigest()


def _sha256_text(text: str) -> str:
    """Compute SHA256 hex digest of a text string."""
    return hashlib.sha256(text.encode("utf-8")).hexdigest()


def _detect_backends_available() -> dict[str, bool]:
    """Best-effort backend availability for the verifier failure JSON."""
    nano_script = sprite_generate.find_nano_banana_script()
    return {
        "codex": shutil.which("codex") is not None,
        "nano_banana": nano_script is not None
        and bool(os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")),
    }


def _emit_verifier_result(
    gates_run: list[str],
    failures: list[dict],
    elapsed_seconds: float,
) -> int:
    """Print the structured verifier JSON to stdout and return the exit code."""
    passed = len(failures) == 0
    payload = {
        "passed": passed,
        "verifier_verdict": verifier_verdict_from_passed(passed),
        "gates_run": gates_run,
        "failures": failures,
        "backends_available": _detect_backends_available(),
        "elapsed_seconds": round(elapsed_seconds, 3),
    }
    print(json.dumps(payload, indent=2))
    return 0 if passed else VERIFIER_EXIT_CODE


def _run_spritesheet_verifiers(
    sheet_path: Path,
    raw_path: Path | None,
    cols: int,
    rows: int,
    cell_size: int,
    allow_frame_duplication: bool = False,
    expected_empty_cells: list[tuple[int, int]] | None = None,
) -> tuple[list[str], list[dict]]:
    """Run the spritesheet gate suite against a final sheet PNG.

    Args:
        expected_empty_cells: List of (row, col) tuples for cells that are
            intentionally empty (per-row mode padding). Forwarded to
            verify_frames_have_content and verify_frames_distinct so they
            skip these cells instead of flagging them.
    """
    gates_run: list[str] = []
    failures: list[dict] = []

    def _record_gate(name: str, result: dict) -> None:
        gates_run.append(name)
        if not result.get("passed", True):
            failures.append({"check": name, "file": str(sheet_path), "details": result})

    try:
        _record_gate("verify_no_magenta", verify_no_magenta(sheet_path))
    except Exception as e:  # pragma: no cover - defensive
        gates_run.append("verify_no_magenta")
        failures.append({"check": "verify_no_magenta", "file": str(sheet_path), "details": f"error: {e}"})

    try:
        _record_gate(
            "verify_grid_alignment",
            verify_grid_alignment(sheet_path, rows, cols, cell_size),
        )
    except Exception as e:  # pragma: no cover - defensive
        gates_run.append("verify_grid_alignment")
        failures.append({"check": "verify_grid_alignment", "file": str(sheet_path), "details": f"error: {e}"})

    try:
        _record_gate(
            "verify_anchor_consistency",
            verify_anchor_consistency(sheet_path, cols, rows, cell_size),
        )
    except Exception as e:  # pragma: no cover - defensive
        gates_run.append("verify_anchor_consistency")
        failures.append({"check": "verify_anchor_consistency", "file": str(sheet_path), "details": f"error: {e}"})

    try:
        _record_gate(
            "verify_frames_have_content",
            verify_frames_have_content(
                sheet_path,
                cols,
                rows,
                cell_size,
                expected_empty_cells=expected_empty_cells,
            ),
        )
    except Exception as e:  # pragma: no cover - defensive
        gates_run.append("verify_frames_have_content")
        failures.append({"check": "verify_frames_have_content", "file": str(sheet_path), "details": f"error: {e}"})

    try:
        _record_gate(
            "verify_padding",
            verify_padding(
                sheet_path,
                cols,
                rows,
                cell_size,
                expected_empty_cells=expected_empty_cells,
            ),
        )
    except Exception as e:  # pragma: no cover - defensive
        gates_run.append("verify_padding")
        failures.append({"check": "verify_padding", "file": str(sheet_path), "details": f"error: {e}"})

    try:
        dup_pct_max = 100.0 if allow_frame_duplication else 70.0
        _record_gate(
            "verify_frames_distinct",
            verify_frames_distinct(
                sheet_path,
                cols,
                rows,
                cell_size,
                max_duplicate_pct=dup_pct_max,
                expected_empty_cells=expected_empty_cells,
            ),
        )
    except Exception as e:  # pragma: no cover - defensive
        gates_run.append("verify_frames_distinct")
        failures.append({"check": "verify_frames_distinct", "file": str(sheet_path), "details": f"error: {e}"})

    if raw_path is not None and raw_path.exists():
        try:
            _record_gate(
                "verify_pixel_preservation",
                verify_pixel_preservation(raw_path, sheet_path, cols, rows, cell_size),
            )
        except Exception as e:  # pragma: no cover - defensive
            gates_run.append("verify_pixel_preservation")
            failures.append({"check": "verify_pixel_preservation", "file": str(sheet_path), "details": f"error: {e}"})

        try:
            _record_gate(
                "verify_raw_vs_final_cell_parity",
                verify_raw_vs_final_cell_parity(raw_path, sheet_path, cols, rows, cell_size),
            )
        except Exception as e:  # pragma: no cover - defensive
            gates_run.append("verify_raw_vs_final_cell_parity")
            failures.append(
                {"check": "verify_raw_vs_final_cell_parity", "file": str(sheet_path), "details": f"error: {e}"}
            )

    return gates_run, failures


FIXTURE_COLORS = [
    (220, 60, 60, 255),
    (60, 180, 60, 255),
    (60, 100, 220, 255),
    (220, 180, 40, 255),
    (180, 60, 220, 255),
    (60, 200, 200, 255),
    (240, 140, 60, 255),
    (140, 60, 200, 255),
]


def _make_fixture_sheet(output: Path, cols: int, rows: int, cell: int) -> None:
    """Synthesize a magenta-bg sheet with one colored figure per cell."""
    img = Image.new("RGBA", (cols * cell, rows * cell), (255, 0, 255, 255))
    draw = ImageDraw.Draw(img)
    idx = 0
    for r in range(rows):
        for c in range(cols):
            color = FIXTURE_COLORS[idx % len(FIXTURE_COLORS)]
            cx = c * cell + cell // 2
            cy_top = r * cell + cell // 5
            cy_bot = r * cell + (cell * 4) // 5
            # head
            head_r = cell // 8
            draw.ellipse(
                (cx - head_r, cy_top, cx + head_r, cy_top + 2 * head_r),
                fill=color,
                outline=(20, 20, 20, 255),
                width=3,
            )
            # body
            body_w = cell // 4
            draw.rectangle(
                (cx - body_w // 2, cy_top + 2 * head_r, cx + body_w // 2, cy_bot),
                fill=color,
                outline=(20, 20, 20, 255),
                width=3,
            )
            idx += 1
    output.parent.mkdir(parents=True, exist_ok=True)
    img.save(output, format="PNG")


def _make_fixture_strip(output: Path, frames: int, cell: int, row_idx: int) -> None:
    """Synthesize a magenta-bg horizontal strip fixture for dry-run per-row mode.

    Each frame gets a distinct color and slightly varied figure proportions
    to give downstream verifiers something to differentiate.
    """
    img = Image.new("RGBA", (frames * cell, cell), (255, 0, 255, 255))
    draw = ImageDraw.Draw(img)
    for f in range(frames):
        color = FIXTURE_COLORS[(row_idx * frames + f) % len(FIXTURE_COLORS)]
        cx = f * cell + cell // 2
        # Vary proportions per frame so verify_frames_distinct sees differences
        head_r = cell // 8 + (f % 3) * 2
        cy_top = cell // 5 + (f % 4) * 3
        cy_bot = (cell * 4) // 5 - (f % 3) * 2
        draw.ellipse(
            (cx - head_r, cy_top, cx + head_r, cy_top + 2 * head_r),
            fill=color,
            outline=(20, 20, 20, 255),
            width=3,
        )
        body_w = cell // 4 + (f % 3) * 4
        draw.rectangle(
            (cx - body_w // 2, cy_top + 2 * head_r, cx + body_w // 2, cy_bot),
            fill=color,
            outline=(20, 20, 20, 255),
            width=3,
        )
    output.parent.mkdir(parents=True, exist_ok=True)
    img.save(output, format="PNG")


def _make_fixture_canonical_base(output: Path, cell: int) -> None:
    """Synthesize a canonical base image fixture for dry-run mode."""
    img = Image.new("RGBA", (cell * 2, cell * 2), (255, 0, 255, 255))
    draw = ImageDraw.Draw(img)
    color = (100, 140, 220, 255)
    cx, cy_top, cy_bot = cell, cell // 3, cell * 2 - cell // 3
    head_r = cell // 4
    draw.ellipse(
        (cx - head_r, cy_top, cx + head_r, cy_top + 2 * head_r),
        fill=color,
        outline=(20, 20, 20, 255),
        width=4,
    )
    body_w = cell // 2
    draw.rectangle(
        (cx - body_w // 2, cy_top + 2 * head_r, cx + body_w // 2, cy_bot),
        fill=color,
        outline=(20, 20, 20, 255),
        width=4,
    )
    output.parent.mkdir(parents=True, exist_ok=True)
    img.save(output, format="PNG")


def _composite_strips(strip_paths: list[Path], output: Path, cell_size: int) -> None:
    """Composite row strip images into a single spritesheet.

    Each strip is a horizontal image of (frames_in_row * cell_size) x cell_size.
    The output is the widest strip width x (num_strips * cell_size), with
    narrower strips left-aligned and remaining space filled with magenta.
    """
    strips = [Image.open(p).convert("RGBA") for p in strip_paths]
    max_width = max(s.width for s in strips)
    total_height = sum(s.height for s in strips)

    sheet = Image.new("RGBA", (max_width, total_height), (255, 0, 255, 255))
    y_offset = 0
    for strip in strips:
        sheet.paste(strip, (0, y_offset))
        y_offset += strip.height

    output.parent.mkdir(parents=True, exist_ok=True)
    sheet.save(output, format="PNG")
    logger.info("[composite] %s written (%dx%d, %d strips)", output, max_width, total_height, len(strips))


def _process_row_strip(
    strip_path: Path,
    row_index: int,
    state: str,
    name: str,
    expected_frames: int,
    cell_size: int,
    work_dir: Path,
    bg_mode: str,
    chroma_threshold: int,
) -> list[Path]:
    """Slice a row strip into frames and remove backgrounds.

    Uses exact pitch (strip_width / expected_frames) instead of
    connected-components to avoid fragmenting Codex-generated strips.

    Args:
        strip_path: Path to the row strip PNG.
        row_index: Zero-based row index (for naming).
        state: Animation state name (e.g. "idle", "dash-right").
        name: Sprite name prefix.
        expected_frames: Number of frames this row should contain.
        cell_size: Target cell size in pixels.
        work_dir: Working directory for intermediate files.
        bg_mode: Background removal mode (chroma, gray-tolerance, etc.).
        chroma_threshold: Chroma-key threshold for bg removal.

    Returns:
        List of paths to bg-removed frame PNGs, ordered by frame index.
    """
    from sprite_slicing import _pre_despill_raw_for_upscale

    strip_img = Image.open(strip_path).convert("RGBA")

    # Pre-despill magenta before resize (prevents LANCZOS pink fringe)
    strip_img = _pre_despill_raw_for_upscale(strip_img, chroma_threshold=chroma_threshold)

    target_w = expected_frames * cell_size
    target_h = cell_size

    # Resize if dimensions don't match expected
    if strip_img.size != (target_w, target_h):
        logger.info(
            "[per-row] row %d (%s): resizing strip %dx%d -> %dx%d",
            row_index,
            state,
            strip_img.width,
            strip_img.height,
            target_w,
            target_h,
        )
        strip_img = strip_img.resize((target_w, target_h), Image.Resampling.LANCZOS)

    # Slice at exact pitch — no connected-components needed
    row_frames_dir = work_dir / f"row_{row_index:02d}_{state}" / "frames"
    row_frames_dir.mkdir(parents=True, exist_ok=True)

    frame_paths: list[Path] = []
    for f_idx in range(expected_frames):
        x0 = f_idx * cell_size
        frame_img = strip_img.crop((x0, 0, x0 + cell_size, cell_size))
        frame_path = row_frames_dir / f"{name}_row{row_index:02d}_{state}_frame_{f_idx:02d}.png"
        frame_img.save(frame_path, format="PNG")
        frame_paths.append(frame_path)

    # Per-frame background removal
    nobg_dir = work_dir / f"row_{row_index:02d}_{state}" / "frames_nobg"
    nobg_dir.mkdir(parents=True, exist_ok=True)

    processed_paths: list[Path] = []
    for fp in frame_paths:
        dst = nobg_dir / fp.name
        if bg_mode == "chroma":
            sprite_bg.remove_bg_chroma(fp, dst, chroma_threshold)
        elif bg_mode == "gray-tolerance":
            sprite_bg.remove_bg_gray_tolerance(fp, dst)
        elif bg_mode == "rembg":
            sprite_bg.remove_bg_rembg(fp, dst)
        elif bg_mode == "auto":
            sprite_bg.remove_bg_chroma(fp, dst, chroma_threshold)
            if sprite_bg._alpha_coverage_too_low(dst):
                logger.warning("[per-row] auto: chroma low-coverage on %s; falling back to rembg", fp.name)
                sprite_bg.remove_bg_rembg(fp, dst)
        else:
            # Fallback to chroma
            sprite_bg.remove_bg_chroma(fp, dst, chroma_threshold)
        processed_paths.append(dst)

    logger.info(
        "[per-row] row %d (%s): sliced %d frames, bg removed",
        row_index,
        state,
        len(processed_paths),
    )
    return processed_paths


def _run_per_row_pipeline(args: argparse.Namespace, work_dir: Path, name: str) -> int:
    """Per-row pipeline body (Phase 1 + Phase 2 + Phase 3).

    Generates each animation row as a separate strip, then composites into
    a final sheet and runs the standard D-H pipeline on it.
    """
    work_dir.mkdir(parents=True, exist_ok=True)
    started = datetime.now(timezone.utc)
    phases: list[dict] = []

    # Resolve preset
    try:
        preset = sprite_prompt.resolve_preset(args.preset)
    except ValueError as e:
        logger.error("%s", e)
        return 1
    row_defs = preset["rows"]

    # Phase A: canonical base generation (Phase 3 identity lock)
    canonical_base_path = work_dir / f"{name}_canonical_base.png"
    char_prompt_path = work_dir / f"{name}_char_prompt.txt"

    char_argv = [
        "build-character",
        "--style",
        args.style,
        "--description",
        args.description or args.prompt or "",
        "--seed",
        str(args.seed),
        "--output",
        str(char_prompt_path),
    ]
    if args.archetype:
        char_argv.extend(["--archetype", args.archetype])
    if args.gimmick:
        char_argv.extend(["--gimmick", args.gimmick])
    if args.style_string:
        char_argv.extend(["--style-string", args.style_string])
    rc = sprite_prompt.main(char_argv)
    if rc != 0:
        return rc

    if args.dry_run:
        _make_fixture_canonical_base(canonical_base_path, args.cell_size)
    else:
        rc = sprite_generate.main(
            [
                "generate-character",
                "--prompt-file",
                str(char_prompt_path),
                "--output",
                str(canonical_base_path),
                "--seed",
                str(args.seed),
            ]
        )
        if rc != 0:
            return rc
    phases.append({"phase": "A", "name": "canonical-base", "rc": 0, "dry_run": args.dry_run})
    logger.info("[per-row] Phase A: canonical base at %s", canonical_base_path)

    # Deterministic idle from canonical base
    if getattr(args, "deterministic_idle", False) and canonical_base_path.exists():
        import deterministic_idle

        idle_dir = work_dir / "idle"
        idle_frames = deterministic_idle.generate_idle_frames(
            Image.open(canonical_base_path).convert("RGBA"),
        )
        deterministic_idle.write_strip(idle_frames, idle_dir / "idle-strip.png")
        deterministic_idle.write_animation(idle_frames, idle_dir / "animation.gif", args.fps)
        deterministic_idle.write_animation(idle_frames, idle_dir / "animation.webp", args.fps)
        phases.append({"phase": "A-idle", "name": "deterministic-idle", "rc": 0})
        logger.info("[per-row] deterministic idle written to %s", idle_dir)

    # Per-row generation loop
    strip_paths: list[Path] = []
    max_frames = max(r["frames"] for r in row_defs)

    for row_idx, row_def in enumerate(row_defs):
        state = row_def["state"]
        frames = row_def["frames"]
        action = row_def["action"]

        row_dir = work_dir / f"row_{row_idx:02d}_{state}"
        row_dir.mkdir(parents=True, exist_ok=True)

        # Phase 2: layout guide
        guide_path = row_dir / "layout_guide.png"
        rc = sprite_canvas.main(
            [
                "make-layout-guide",
                "--state",
                state,
                "--frames",
                str(frames),
                "--cell-size",
                str(args.cell_size),
                "--output",
                str(guide_path),
            ]
        )
        if rc != 0:
            return rc

        # Row-strip prompt (Phase 1 + Phase 9 VFX containment)
        row_prompt_path = row_dir / "row_prompt.txt"
        prompt_argv = [
            "build-row-strip",
            "--style",
            args.style,
            "--description",
            args.description or args.prompt or "",
            "--seed",
            str(args.seed),
            "--output",
            str(row_prompt_path),
            "--state",
            state,
            "--frames",
            str(frames),
            "--action",
            action,
            "--canonical-base",
            str(canonical_base_path),
        ]
        if args.archetype:
            prompt_argv.extend(["--archetype", args.archetype])
        if args.gimmick:
            prompt_argv.extend(["--gimmick", args.gimmick])
        if args.style_string:
            prompt_argv.extend(["--style-string", args.style_string])
        rc = sprite_prompt.main(prompt_argv)
        if rc != 0:
            return rc

        # Generate strip
        strip_path = row_dir / f"{name}_row_{row_idx:02d}_{state}.png"
        if args.dry_run:
            _make_fixture_strip(strip_path, frames, args.cell_size, row_idx)
        else:
            # Pass both layout guide and canonical base as references
            rc = sprite_generate.main(
                [
                    "generate-spritesheet",
                    "--prompt-file",
                    str(row_prompt_path),
                    "--output",
                    str(strip_path),
                    "--canvas",
                    str(guide_path),
                    "--reference",
                    str(canonical_base_path),
                    "--seed",
                    str(args.seed + row_idx),
                ]
            )
            if rc != 0:
                return rc

        strip_paths.append(strip_path)
        phases.append(
            {
                "phase": f"C-row-{row_idx}",
                "name": f"row-strip-{state}",
                "rc": 0,
                "dry_run": args.dry_run,
                "frames": frames,
            }
        )
        logger.info("[per-row] row %d/%d (%s, %d frames) done", row_idx + 1, len(row_defs), state, frames)

    # Composite strips into raw sheet (reference only — slicing is per-strip)
    sheet_raw_path = work_dir / f"{name}_sheet_raw.png"
    _composite_strips(strip_paths, sheet_raw_path, args.cell_size)
    phases.append({"phase": "composite", "name": "composite-strips", "rc": 0})

    # Compute effective grid for downstream phases
    total_rows = len(row_defs)
    effective_cols = max_frames

    # Per-strip processing: slice each row strip individually and run bg
    # removal per frame. This avoids the dense-grid slicer which fragments
    # characters when Codex-generated strips don't align to cell boundaries.
    frames_nobg_dir = work_dir / "frames_nobg"
    frames_nobg_dir.mkdir(parents=True, exist_ok=True)

    # Track global frame index so normalize/assemble can map frames to
    # the correct row/col position in the final sheet.
    global_frame_idx = 0
    for row_idx, row_def in enumerate(row_defs):
        row_frame_paths = _process_row_strip(
            strip_path=strip_paths[row_idx],
            row_index=row_idx,
            state=row_def["state"],
            name=name,
            expected_frames=row_def["frames"],
            cell_size=args.cell_size,
            work_dir=work_dir,
            bg_mode=args.bg_mode,
            chroma_threshold=args.chroma_threshold,
        )
        # Copy/rename frames to the shared nobg dir with sequential global
        # indices so the normalize and assemble phases see them as a flat
        # list in the correct order (row-major: row0 frames, row1 frames, …).
        for fp in row_frame_paths:
            dst = frames_nobg_dir / f"{name}_frame_{global_frame_idx:02d}.png"
            # Use shutil.copy2 to avoid cross-device link issues
            shutil.copy2(fp, dst)
            global_frame_idx += 1
        # Pad shorter rows with None-sentinel empty cells up to effective_cols
        for _ in range(row_def["frames"], effective_cols):
            global_frame_idx += 1

    phases.append({"phase": "D+E", "name": "per-strip-slice-and-bg-removal", "rc": 0, "mode": args.bg_mode})

    # Phase F: normalize
    frames_norm_dir = work_dir / "frames_normalized"
    rc = sprite_process.main(
        [
            "normalize",
            "--mode",
            "spritesheet",
            "--input-dir",
            str(frames_nobg_dir),
            "--output-dir",
            str(frames_norm_dir),
            "--cell-size",
            str(args.cell_size),
            "--scale-percentile",
            str(args.scale_percentile),
            "--anchor-mode",
            args.anchor_mode,
        ]
    )
    if rc != 0:
        return rc
    phases.append({"phase": "F", "name": "normalize", "rc": rc})

    # Phase H: assembly with per-frame timing (Phase 8)
    # Extract timing from preset for assembly
    timing_dict: dict[str, list[int]] = {}
    state_name_list: list[str] = []
    for rd in row_defs:
        state_name_list.append(rd["state"])
        if "timing" in rd:
            timing_dict[rd["state"]] = rd["timing"]

    # Write timing JSON for assembly to consume
    timing_json_path: Path | None = None
    if timing_dict:
        timing_json_path = work_dir / f"{name}_timing_input.json"
        timing_json_path.write_text(json.dumps(timing_dict, indent=2), encoding="utf-8")

    # Also accept --timing-json override
    if getattr(args, "timing_json", None):
        timing_json_path = Path(args.timing_json)

    # Use direct assembly call instead of CLI to pass timing
    from sprite_assemble import assemble_outputs

    frame_paths = sorted((frames_norm_dir).glob("*_frame_*.png"))
    expected = effective_cols * total_rows
    by_idx: dict[int, Image.Image] = {}
    for p in frame_paths:
        idx_str = p.stem.split("_frame_")[-1]
        try:
            idx = int(idx_str)
        except ValueError:
            continue
        by_idx[idx] = Image.open(p).convert("RGBA")
    assembly_frames: list[Image.Image | None] = [by_idx.get(i) for i in range(expected)]

    emit_strips = effective_cols in (4, 8) and not args.no_strips
    try:
        assemble_outputs(
            frames=assembly_frames,
            output_dir=work_dir / "out",
            name=name,
            grid_cols=effective_cols,
            grid_rows=total_rows,
            cell_w=args.cell_size,
            cell_h=args.cell_size,
            fps=args.fps,
            emit_strips=emit_strips,
            timing=timing_dict if timing_dict else None,
            state_names=state_name_list if state_name_list else None,
        )
    finally:
        for img in by_idx.values():
            img.close()
    phases.append({"phase": "H", "name": "assemble", "rc": 0})

    # Phase 7: QA artifacts (when --qa-artifacts is set)
    if getattr(args, "qa_artifacts", False):
        sheet_for_qa = work_dir / "out" / f"{name}_sheet.png"
        if sheet_for_qa.exists():
            qa_dir = work_dir / "qa"
            qa_dir.mkdir(parents=True, exist_ok=True)
            qa_artifacts.make_contact_sheet(
                input_path=sheet_for_qa,
                output_path=qa_dir / "contact_sheet.png",
                cols=effective_cols,
                rows=total_rows,
                cell_size=args.cell_size,
                preset_name=args.preset,
            )
            qa_artifacts.render_preview_videos(
                input_path=sheet_for_qa,
                output_dir=qa_dir / "previews",
                cols=effective_cols,
                rows=total_rows,
                cell_size=args.cell_size,
                preset_name=args.preset,
                fps=args.fps,
            )
            qa_artifacts.generate_qa_report(
                input_path=sheet_for_qa,
                output_path=qa_dir / "review.json",
                cols=effective_cols,
                rows=total_rows,
                cell_size=args.cell_size,
                preset_name=args.preset,
            )
            phases.append({"phase": "QA", "name": "qa-artifacts", "rc": 0})
            logger.info("[per-row] QA artifacts written to %s", qa_dir)

    # Provenance tracking
    row_hashes: dict[str, str] = {}
    for row_idx, row_def in enumerate(row_defs):
        sp = strip_paths[row_idx]
        if sp.exists():
            row_hashes[row_def["state"]] = _sha256_file(sp)

    prompt_hashes: dict[str, str] = {}
    for row_idx, row_def in enumerate(row_defs):
        row_prompt_path = work_dir / f"row_{row_idx:02d}_{row_def['state']}" / "row_prompt.txt"
        if row_prompt_path.exists():
            prompt_hashes[row_def["state"]] = _sha256_text(row_prompt_path.read_text(encoding="utf-8"))

    pipeline_chain = [
        "codex-imagegen" if not args.dry_run else "dry-run-fixture",
        "per-strip-slice",
        f"bg-removal-{args.bg_mode}",
        "mass-centroid-anchor",
        "pillow-assemble",
    ]

    # Metadata
    sidecar = {
        "name": name,
        "mode": "per-row",
        "preset": args.preset,
        "grid": [effective_cols, total_rows],
        "cell_size": args.cell_size,
        "rows": [{"state": r["state"], "frames": r["frames"], "action": r["action"]} for r in row_defs],
        "style_preset": args.style,
        "archetype": args.archetype,
        "seed": args.seed,
        "dry_run": args.dry_run,
        "started_at": started.isoformat(),
        "completed_at": datetime.now(timezone.utc).isoformat(),
        "phases": phases,
        "output_dir": str(work_dir / "out"),
        "canonical_base": str(canonical_base_path),
        "canonical_base_hash": _sha256_file(canonical_base_path) if canonical_base_path.exists() else None,
        "prompt_hashes": prompt_hashes,
        "row_hashes": row_hashes,
        "pipeline_chain": pipeline_chain,
    }
    (work_dir / f"{name}_metadata.json").write_text(json.dumps(sidecar, indent=2), encoding="utf-8")

    logger.info(
        "[per-row] PASS: %s written to %s (%d rows, %d phases)",
        name,
        work_dir / "out",
        len(row_defs),
        len(phases),
    )

    # Verifier gates
    if not getattr(args, "verify", True):
        logger.warning(
            "--no-verify opted out; per-row output not validated. Returning exit code %d (ADR-207 Rule 4).",
            VERIFIER_SKIPPED_EXIT_CODE,
        )
        return VERIFIER_SKIPPED_EXIT_CODE

    sheet_path = work_dir / "out" / f"{name}_sheet.png"
    if not sheet_path.exists():
        return _emit_verifier_result(
            gates_run=[],
            failures=[{"check": "asset_exists", "file": str(sheet_path), "details": "missing"}],
            elapsed_seconds=0.0,
        )

    # Compute expected-empty cells: per-row mode pads shorter rows to
    # max_frames columns. Cells beyond a row's frame count are intentionally
    # blank and must not trigger verify_frames_have_content or
    # verify_frames_distinct failures.
    expected_empty_cells: list[tuple[int, int]] = []
    for row_idx, row_def in enumerate(row_defs):
        for col in range(row_def["frames"], effective_cols):
            expected_empty_cells.append((row_idx, col))

    # Per-row mode: do NOT pass raw_path to the verifier. The composite
    # raw sheet is a reference artifact, not the slicer input. The
    # verify_pixel_preservation and verify_raw_vs_final_cell_parity gates
    # compare raw-vs-final cell content; in per-row mode the final sheet
    # was assembled from per-strip slicing, so the composite raw has
    # different cell alignment and the parity check would false-positive.
    started_verify = time.perf_counter()
    gates_run, failures = _run_spritesheet_verifiers(
        sheet_path=sheet_path,
        raw_path=None,
        cols=effective_cols,
        rows=total_rows,
        cell_size=args.cell_size,
        allow_frame_duplication=getattr(args, "allow_frame_duplication", False),
        expected_empty_cells=expected_empty_cells,
    )
    elapsed = time.perf_counter() - started_verify

    sidecar_path = work_dir / f"{name}_metadata.json"
    if sidecar_path.exists():
        try:
            sidecar_data = json.loads(sidecar_path.read_text(encoding="utf-8"))
        except json.JSONDecodeError:  # pragma: no cover - defensive
            sidecar_data = {}
        sidecar_data["verifier_verdict"] = verifier_verdict_from_passed(len(failures) == 0)
        sidecar_data["verifier_failures"] = failures
        sidecar_data["verifier_gates_run"] = gates_run
        sidecar_data["verifier_elapsed_seconds"] = round(elapsed, 3)
        write_manifest_record(sidecar_path, sidecar_data)

    return _emit_verifier_result(gates_run=gates_run, failures=failures, elapsed_seconds=elapsed)


def _run_pipeline_body(args: argparse.Namespace, work_dir: Path, name: str) -> int:
    """Pipeline body. ``work_dir`` lifetime is bounded by the caller.

    When ``--output-dir`` is unset the caller wraps this in a
    ``tempfile.TemporaryDirectory`` and the directory is reaped on exit
    (success, exception, or KeyboardInterrupt). When ``--output-dir`` is
    set the user owns the directory and intermediates persist for
    inspection. See ADR-200.
    """
    work_dir.mkdir(parents=True, exist_ok=True)

    started = datetime.now(timezone.utc)
    phases: list[dict] = []

    if args.max_frames:
        try:
            r, c = sprite_canvas.compute_max_grid(args.cell_size, args.max_canvas)
        except ValueError as e:
            logger.error("%s", e)
            return 2
        cols, rows = c, r
        args.grid = f"{cols}x{rows}"
        logger.info(
            "[pipeline] --max-frames: auto-grid %dx%d = %d frames @ %dpx on %dx%d canvas",
            cols,
            rows,
            cols * rows,
            args.cell_size,
            args.max_canvas,
            args.max_canvas,
        )
    else:
        cols, rows = sprite_prompt.parse_grid(args.grid)

    # Density warning: image-gen models cannot reliably keep characters within
    # cells when the per-cell budget shrinks below ~128px and the grid is
    # dense. See references/frame-detection.md "Grid density limits".
    total_frames = cols * rows
    if total_frames > 64 and not args.confirm_dense_grid:
        logger.warning(
            "grid %dx%d=%d frames is dense; per-cell frame extraction may drift. "
            "Consider 8x8 or smaller. Set --confirm-dense-grid to suppress this warning.",
            cols,
            rows,
            total_frames,
        )

    # Phase A: reference character (skipped in dry-run, optional otherwise)
    char_prompt_path = work_dir / f"{name}_char_prompt.txt"
    char_ref_path = work_dir / f"{name}_reference.png"
    if not args.skip_reference:
        char_argv = [
            "build-character",
            "--style",
            args.style,
            "--description",
            args.description or args.prompt or "",
            "--seed",
            str(args.seed),
            "--output",
            str(char_prompt_path),
        ]
        if args.archetype:
            char_argv.extend(["--archetype", args.archetype])
        if args.gimmick:
            char_argv.extend(["--gimmick", args.gimmick])
        if args.style_string:
            char_argv.extend(["--style-string", args.style_string])
        rc = sprite_prompt.main(char_argv)
        if rc != 0:
            return rc
        if not args.dry_run:
            rc = sprite_generate.main(
                [
                    "generate-character",
                    "--prompt-file",
                    str(char_prompt_path),
                    "--output",
                    str(char_ref_path),
                    "--seed",
                    str(args.seed),
                ]
            )
            if rc != 0:
                return rc
        phases.append({"phase": "A", "name": "reference-character", "rc": 0, "dry_run": args.dry_run})

    # Phase B: canvas template
    canvas_path = work_dir / f"{name}_canvas.png"
    rc = sprite_canvas.main(
        [
            "make-template",
            "--rows",
            str(rows),
            "--cols",
            str(cols),
            "--cell-size",
            str(args.cell_size),
            "--pattern",
            args.pattern,
            "--output",
            str(canvas_path),
        ]
    )
    if rc != 0:
        return rc
    phases.append({"phase": "B", "name": "canvas", "rc": rc})

    # Phase C: spritesheet generation
    sheet_prompt_path = work_dir / f"{name}_sheet_prompt.txt"
    sheet_raw_path = work_dir / f"{name}_sheet_raw.png"
    sheet_argv = [
        "build-spritesheet",
        "--style",
        args.style,
        "--description",
        args.description or args.prompt or "",
        "--grid",
        args.grid,
        "--action",
        args.action,
        "--seed",
        str(args.seed),
        "--output",
        str(sheet_prompt_path),
    ]
    if args.archetype:
        sheet_argv.extend(["--archetype", args.archetype])
    if args.gimmick:
        sheet_argv.extend(["--gimmick", args.gimmick])
    if args.style_string:
        sheet_argv.extend(["--style-string", args.style_string])
    rc = sprite_prompt.main(sheet_argv)
    if rc != 0:
        return rc

    if args.dry_run:
        _make_fixture_sheet(sheet_raw_path, cols, rows, args.cell_size)
        phases.append({"phase": "C", "name": "generate-sheet", "rc": 0, "dry_run": True})
    else:
        rc = sprite_generate.main(
            [
                "generate-spritesheet",
                "--prompt-file",
                str(sheet_prompt_path),
                "--output",
                str(sheet_raw_path),
                "--canvas",
                str(canvas_path),
                "--reference",
                str(char_ref_path) if char_ref_path.exists() else str(canvas_path),
                "--seed",
                str(args.seed),
            ]
        )
        if rc != 0:
            return rc
        phases.append({"phase": "C", "name": "generate-sheet", "rc": rc})

    # Phase D: extract frames
    frames_raw_dir = work_dir / "frames_raw"
    extract_args = [
        "extract-frames",
        "--input",
        str(sheet_raw_path),
        "--grid",
        args.grid,
        "--output-dir",
        str(frames_raw_dir),
        "--name",
        name,
        "--chroma-threshold",
        str(args.chroma_threshold),
        "--min-pixels",
        str(args.min_pixels),
    ]
    # ADR-207 Rule 1: dense grids (>= 4x4 with >= 16 cells) ALWAYS use the
    # slicer dispatch path, never the legacy connected-components extractor.
    from sprite_slicing import is_dense_grid

    grid_is_dense = is_dense_grid(cols, rows)
    use_effects_asset = getattr(args, "effects_asset", False)
    legacy_content_aware = getattr(args, "content_aware_extraction", False)
    if grid_is_dense:
        extract_args.append("--content-aware")
        if use_effects_asset:
            extract_args.append("--effects-asset")
        if legacy_content_aware and not use_effects_asset:
            logger.warning(
                "[pipeline] --content-aware-extraction on dense grid %dx%d is "
                "deprecated per ADR-207 RC-1; the slicer dispatch will downgrade "
                "to strict-pitch. Pass --effects-asset to explicitly opt into "
                "content-aware (correct only for sparse-but-cross-boundary "
                "content like fire breath / plasma trails / auras).",
                cols,
                rows,
            )
    elif legacy_content_aware:
        extract_args.append("--content-aware")
        if use_effects_asset:
            extract_args.append("--effects-asset")
    rc = sprite_process.main(extract_args)
    if rc != 0:
        return rc
    phases.append({"phase": "D", "name": "extract-frames", "rc": rc})

    # Phase E: per-frame bg removal
    frames_nobg_dir = work_dir / "frames_nobg"
    raw_frames = sorted(frames_raw_dir.glob("*_frame_*.png"))
    if not raw_frames:
        logger.error("no frames extracted in Phase D")
        return 5
    rb_argv: list[str] = [
        "remove-bg",
        *(str(f) for f in raw_frames),
        "--output-dir",
        str(frames_nobg_dir),
        "--bg-mode",
        args.bg_mode,
        "--chroma-threshold",
        str(args.chroma_threshold),
    ]
    rc = sprite_process.main(rb_argv)
    if rc != 0:
        return rc
    phases.append({"phase": "E", "name": "remove-bg", "rc": rc, "mode": args.bg_mode})

    # Phase F: normalize
    frames_norm_dir = work_dir / "frames_normalized"
    rc = sprite_process.main(
        [
            "normalize",
            "--mode",
            "spritesheet",
            "--input-dir",
            str(frames_nobg_dir),
            "--output-dir",
            str(frames_norm_dir),
            "--cell-size",
            str(args.cell_size),
            "--scale-percentile",
            str(args.scale_percentile),
            "--anchor-mode",
            args.anchor_mode,
        ]
    )
    if rc != 0:
        return rc
    phases.append({"phase": "F", "name": "normalize", "rc": rc})

    # Phase G: skipped when variants == 1
    if args.variants > 1:
        phases.append({"phase": "G", "name": "auto-curate", "rc": 0, "note": "variants > 1 not yet wired in dry-run"})

    # Phase H: assembly (with timing support from --timing-json)
    timing_dict: dict[str, list[int]] | None = None
    state_name_list: list[str] | None = None
    timing_json_arg = getattr(args, "timing_json", None)
    if timing_json_arg:
        tjp = Path(timing_json_arg)
        if tjp.exists():
            timing_dict = json.loads(tjp.read_text(encoding="utf-8"))
            state_name_list = list(timing_dict.keys()) if timing_dict else None

    assemble_argv = [
        "assemble",
        "--frames-dir",
        str(frames_norm_dir),
        "--grid",
        args.grid,
        "--cell-size",
        str(args.cell_size),
        "--output-dir",
        str(work_dir / "out"),
        "--name",
        name,
        "--fps",
        str(args.fps),
    ]
    if args.no_strips:
        assemble_argv.append("--no-strips")
    if timing_json_arg:
        assemble_argv.extend(["--timing-json", timing_json_arg])
    rc = sprite_process.main(assemble_argv)
    if rc != 0:
        return rc
    phases.append({"phase": "H", "name": "assemble", "rc": rc})

    # Phase 7: QA artifacts (when --qa-artifacts is set)
    if getattr(args, "qa_artifacts", False):
        sheet_for_qa = work_dir / "out" / f"{name}_sheet.png"
        if sheet_for_qa.exists():
            qa_dir = work_dir / "qa"
            qa_dir.mkdir(parents=True, exist_ok=True)
            qa_artifacts.make_contact_sheet(
                input_path=sheet_for_qa,
                output_path=qa_dir / "contact_sheet.png",
                cols=cols,
                rows=rows,
                cell_size=args.cell_size,
            )
            qa_artifacts.render_preview_videos(
                input_path=sheet_for_qa,
                output_dir=qa_dir / "previews",
                cols=cols,
                rows=rows,
                cell_size=args.cell_size,
                fps=args.fps,
            )
            qa_artifacts.generate_qa_report(
                input_path=sheet_for_qa,
                output_path=qa_dir / "review.json",
                cols=cols,
                rows=rows,
                cell_size=args.cell_size,
            )
            phases.append({"phase": "QA", "name": "qa-artifacts", "rc": 0})
            logger.info("[spritesheet] QA artifacts written to %s", qa_dir)

    # Provenance tracking
    prompt_hash_val = None
    if sheet_prompt_path.exists():
        prompt_hash_val = _sha256_text(sheet_prompt_path.read_text(encoding="utf-8"))

    spritesheet_pipeline_chain = [
        "codex-imagegen" if not args.dry_run else "dry-run-fixture",
        "grid-slice",
        f"bg-removal-{args.bg_mode}",
        "mass-centroid-anchor",
        "pillow-assemble",
    ]

    # Metadata
    sidecar = {
        "name": name,
        "grid": [cols, rows],
        "cell_size": args.cell_size,
        "action": args.action,
        "style_preset": args.style,
        "archetype": args.archetype,
        "seed": args.seed,
        "dry_run": args.dry_run,
        "started_at": started.isoformat(),
        "completed_at": datetime.now(timezone.utc).isoformat(),
        "phases": phases,
        "output_dir": str(work_dir / "out"),
        "prompt_hash": prompt_hash_val,
        "pipeline_chain": spritesheet_pipeline_chain,
    }
    (work_dir / f"{name}_metadata.json").write_text(json.dumps(sidecar, indent=2), encoding="utf-8")

    logger.info(
        "[spritesheet] PASS: %s written to %s (phases: %d)",
        name,
        work_dir / "out",
        len(phases),
    )

    # Phase I: verifier gates (ADR-199).
    if not getattr(args, "verify", True):
        logger.warning(
            "--no-verify opted out; spritesheet output not validated. "
            "Returning exit code %d (ADR-207 Rule 4: distinct from success).",
            VERIFIER_SKIPPED_EXIT_CODE,
        )
        return VERIFIER_SKIPPED_EXIT_CODE

    sheet_path = work_dir / "out" / f"{name}_sheet.png"
    if not sheet_path.exists():
        return _emit_verifier_result(
            gates_run=[],
            failures=[{"check": "asset_exists", "file": str(sheet_path), "details": "missing"}],
            elapsed_seconds=0.0,
        )

    raw_path = work_dir / f"{name}_sheet_raw.png"
    started_verify = time.perf_counter()
    gates_run, failures = _run_spritesheet_verifiers(
        sheet_path=sheet_path,
        raw_path=raw_path if raw_path.exists() else None,
        cols=cols,
        rows=rows,
        cell_size=args.cell_size,
        allow_frame_duplication=getattr(args, "allow_frame_duplication", False),
    )
    elapsed = time.perf_counter() - started_verify

    sidecar_path = work_dir / f"{name}_metadata.json"
    if sidecar_path.exists():
        try:
            sidecar_data = json.loads(sidecar_path.read_text(encoding="utf-8"))
        except json.JSONDecodeError:  # pragma: no cover - defensive
            sidecar_data = {}
        sidecar_data["verifier_verdict"] = verifier_verdict_from_passed(len(failures) == 0)
        sidecar_data["verifier_failures"] = failures
        sidecar_data["verifier_gates_run"] = gates_run
        sidecar_data["verifier_elapsed_seconds"] = round(elapsed, 3)
        write_manifest_record(sidecar_path, sidecar_data)

    return _emit_verifier_result(gates_run=gates_run, failures=failures, elapsed_seconds=elapsed)


def run_pipeline(args: argparse.Namespace) -> int:
    """Spritesheet pipeline entry point.

    Routes to per-row mode when --per-row is set; otherwise classic monolithic.
    When ``--output-dir`` is set, the directory is preserved. When unset, a
    ``tempfile.TemporaryDirectory`` is created and reaped on exit (ADR-200).
    """
    name = args.name or "spritesheet"

    # Route to per-row pipeline when --per-row is set
    if getattr(args, "per_row", False):
        if not getattr(args, "preset", None):
            logger.error("--per-row requires --preset (e.g., --preset fighter)")
            return 1
        if args.output_dir:
            return _run_per_row_pipeline(args, Path(args.output_dir), name)
        with tempfile.TemporaryDirectory(prefix=f"sprite_{name}_") as td:
            return _run_per_row_pipeline(args, Path(td), name)

    if args.output_dir:
        return _run_pipeline_body(args, Path(args.output_dir), name)
    with tempfile.TemporaryDirectory(prefix=f"sprite_{name}_") as td:
        return _run_pipeline_body(args, Path(td), name)


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("--prompt", help="Free-form prompt; alternative to --description")
    parser.add_argument("--description", help="Character description text")
    parser.add_argument("--name", help="Sprite name prefix")
    parser.add_argument("--style", default="modern-hi-bit")
    parser.add_argument("--style-string", help="Free-form style fragment for --style custom")
    parser.add_argument("--archetype", help="Wrestler archetype")
    parser.add_argument("--gimmick", help="Wrestler gimmick")
    parser.add_argument("--grid", default="4x1", help="Grid CxR (default 4x1; ignored with --max-frames or --preset)")
    parser.add_argument("--cell-size", type=int, default=256, choices=[64, 128, 192, 256, 384, 512])
    parser.add_argument(
        "--max-frames",
        action="store_true",
        help=(
            "Auto-fill the canvas: pack the largest square grid that fits "
            "--max-canvas at --cell-size. Overrides --grid."
        ),
    )
    parser.add_argument(
        "--max-canvas",
        type=int,
        default=sprite_canvas.DEFAULT_MAX_CANVAS,
        help=f"Max canvas side in px when --max-frames is set (default {sprite_canvas.DEFAULT_MAX_CANVAS})",
    )
    parser.add_argument("--action", default="walking")
    parser.add_argument("--pattern", default="alternating", choices=["magenta-only", "alternating", "checkerboard"])
    parser.add_argument("--seed", type=int, default=0)
    parser.add_argument("--variants", type=int, default=1)
    parser.add_argument(
        "--bg-mode",
        choices=list(sprite_bg.BG_MODE_CHOICES),
        default="chroma",
        help=(
            "Background removal (ADR-204 unified vocabulary): "
            "chroma=two-pass magenta despill (default), "
            "gray-tolerance=road-to-aew #3a3a3a algorithm, "
            "rembg=opt-in ML, auto=chroma with rembg fallback."
        ),
    )
    parser.add_argument("--chroma-threshold", type=int, default=30)
    parser.add_argument(
        "--confirm-dense-grid",
        action="store_true",
        help=(
            "Suppress the dense-grid warning when rows*cols > 64. "
            "Image-gen models drop sprite quality at high density; "
            "see references/frame-detection.md."
        ),
    )
    parser.add_argument("--min-pixels", type=int, default=200)
    parser.add_argument("--scale-percentile", type=float, default=95)
    parser.add_argument(
        "--anchor-mode",
        choices=["bottom", "center", "auto", "ground-line", "per-frame-bottom", "mass-centroid"],
        default="mass-centroid",
        help=(
            "Anchor strategy. mass-centroid (ADR-208 RC-4 default): each "
            "frame's alpha-mass-centroid lands at a globally-stable Y; "
            "drift-free even on extended-limb frames (lunge, kick). "
            "ground-line: legacy global bbox-bottom anchor (correct for "
            "portrait-loop / fixed-camera modes; wobbles on action sheets "
            "where bbox-bottom is sometimes a fist or kicking leg). "
            "per-frame-bottom / bottom: per-frame bbox anchor (drifts). "
            "See references/anchor-alignment.md and ADR-208."
        ),
    )
    parser.add_argument("--fps", type=int, default=10)
    parser.add_argument("--no-strips", action="store_true")
    parser.add_argument("--skip-reference", action="store_true", help="Skip Phase A reference generation")
    parser.add_argument(
        "--output-dir",
        help=(
            "Working directory. When unset, a temporary directory is "
            "created and cleaned up automatically. When set, the "
            "directory is preserved (you own its lifecycle)."
        ),
    )
    parser.add_argument("--dry-run", action="store_true", help="Skip backend; synthetic fixture for D-H")
    parser.add_argument(
        "--verify",
        action=argparse.BooleanOptionalAction,
        default=True,
        help=("Run verifier gates as the last pipeline step (default ON). See ADR-199 for the contract."),
    )
    parser.add_argument(
        "--content-aware-extraction",
        action="store_true",
        help=(
            "Use slice_with_content_awareness instead of strict-pitch slicing. "
            "ADR-207 Rule 1: on dense grids this flag is downgraded. "
            "See ADR-207 RC-1."
        ),
    )
    parser.add_argument(
        "--effects-asset",
        action="store_true",
        help=("Opt INTO content-aware routing on a DENSE grid. Use ONLY for sparse-but-cross-boundary content."),
    )
    parser.add_argument(
        "--allow-frame-duplication",
        action="store_true",
        help=(
            "Opt OUT of the frames-distinct gate's tightened threshold (ADR-208 RC-3). "
            "Use for spec-known sheets with legitimate frame repetition."
        ),
    )
    # Per-row mode flags (Phase 1 + Phase 6)
    parser.add_argument(
        "--per-row",
        action="store_true",
        help=(
            "Generate each animation row as a separate strip, then composite. "
            "Requires --preset. Eliminates cross-row contamination."
        ),
    )
    parser.add_argument(
        "--preset",
        choices=["fighter", "rpg-character", "platformer", "pet", "custom"],
        help=(
            "Named animation preset defining rows, frame counts, and timing. "
            "Use with --per-row for row-strip generation mode."
        ),
    )
    # Deterministic idle
    parser.add_argument(
        "--deterministic-idle",
        action="store_true",
        help=(
            "After generating the canonical base (portrait mode / per-row Phase A), "
            "produce a deterministic breathing idle loop. Zero API calls -- pure Pillow."
        ),
    )
    # Phase 7: QA artifacts
    parser.add_argument(
        "--qa-artifacts",
        action="store_true",
        help=("Generate QA artifacts (contact sheet, preview GIFs, review JSON) after verifier gates. Default OFF."),
    )
    # Phase 8: Custom timing
    parser.add_argument(
        "--timing-json",
        help=(
            "Path to JSON file with per-state timing overrides. Format: "
            '{"state_name": [ms_per_frame, ...]}. Overrides preset timing.'
        ),
    )
    # Logging level controls (ADR-202). Mutually exclusive; default INFO.
    log_group = parser.add_mutually_exclusive_group()
    log_group.add_argument(
        "--quiet",
        "-q",
        action="store_true",
        help="Suppress INFO log records; only emit WARNING and above on stderr.",
    )
    log_group.add_argument(
        "--verbose",
        "-v",
        action="store_true",
        help="Emit DEBUG-level diagnostic log records on stderr.",
    )
    return parser


def configure_logging(quiet: bool, verbose: bool) -> None:
    """Configure the root logger for sprite-pipeline scripts (ADR-202)."""
    level = logging.WARNING if quiet else (logging.DEBUG if verbose else logging.INFO)
    logging.basicConfig(
        level=level,
        format="[%(name)s] %(levelname)s: %(message)s",
        stream=sys.stderr,
        force=True,
    )


def main(argv: list[str] | None = None) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    configure_logging(quiet=args.quiet, verbose=args.verbose)
    # portrait-loop mode delegates to portrait_pipeline.run_portrait_loop
    if getattr(args, "mode", None) == "portrait-loop":
        import portrait_pipeline as pp

        return pp.run_portrait_loop(args)
    return run_pipeline(args)


if __name__ == "__main__":
    sys.exit(main())
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall