sprout-toolkit 0.1.0__py3-none-any.whl

sprout/__init__.py

@@ -0,0 +1,3 @@
+"""sprout — toolchain determinista de assets 2D procedurales para Expo + react-native-skia."""
+
+__version__ = "0.1.0"

sprout/assets/fonts/DejaVuSansMono-Bold.LICENSE.txt

@@ -0,0 +1,78 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: DejaVu fonts
+Upstream-Author: Stepan Roh <src@users.sourceforge.net> (original author),
+                  see /usr/share/doc/fonts-dejavu-core/AUTHORS for full list
+Source: https://dejavu-fonts.github.io/
+
+Files: *
+Copyright: Copyright (c) 2003 by Bitstream, Inc. All Rights Reserved. 
+ Bitstream Vera is a trademark of Bitstream, Inc.
+ DejaVu changes are in public domain.
+License: bitstream-vera
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of the fonts accompanying this license ("Fonts") and associated
+ documentation files (the "Font Software"), to reproduce and distribute the
+ Font Software, including without limitation the rights to use, copy, merge,
+ publish, distribute, and/or sell copies of the Font Software, and to permit
+ persons to whom the Font Software is furnished to do so, subject to the
+ following conditions:
+ .
+ The above copyright and trademark notices and this permission notice shall
+ be included in all copies of one or more of the Font Software typefaces.
+ .
+ The Font Software may be modified, altered, or added to, and in particular
+ the designs of glyphs or characters in the Fonts may be modified and
+ additional glyphs or characters may be added to the Fonts, only if the fonts
+ are renamed to names not containing either the words "Bitstream" or the word
+ "Vera".
+ .
+ This License becomes null and void to the extent applicable to Fonts or Font
+ Software that has been modified and is distributed under the "Bitstream
+ Vera" names.
+ .
+ The Font Software may be sold as part of a larger software package but no
+ copy of one or more of the Font Software typefaces may be sold by itself.
+ .
+ THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF COPYRIGHT, PATENT,
+ TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL BITSTREAM OR THE GNOME
+ FOUNDATION BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING
+ ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES,
+ WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+ THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER DEALINGS IN THE
+ FONT SOFTWARE.
+ .
+ Except as contained in this notice, the names of Gnome, the Gnome
+ Foundation, and Bitstream Inc., shall not be used in advertising or
+ otherwise to promote the sale, use or other dealings in this Font Software
+ without prior written authorization from the Gnome Foundation or Bitstream
+ Inc., respectively. For further information, contact: fonts at gnome dot
+ org.
+
+Files: debian/*
+Copyright: (C) 2005-2006 Peter Cernak <pce@users.sourceforge.net> 
+           (C) 2006-2011 Davide Viti <zinosat@tiscali.it>
+           (C) 2011-2013 Christian Perrier <bubulle@debian.org>
+           (C) 2013 Fabian Greffrath <fabian+debian@greffrath.com>
+License: GPL-2+
+ This program is free software; you can redistribute it
+ and/or modify it under the terms of the GNU General Public
+ License as published by the Free Software Foundation; either
+ version 2 of the License, or (at your option) any later
+ version.
+ .
+ This program is distributed in the hope that it will be
+ useful, but WITHOUT ANY WARRANTY; without even the implied
+ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more
+ details.
+ .
+ You should have received a copy of the GNU General Public
+ License along with this package; if not, write to the Free
+ Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+ Boston, MA  02110-1301 USA
+ .
+ On Debian systems, the full text of the GNU General Public
+ License version 2 can be found in the file
+ /usr/share/common-licenses/GPL-2'.

sprout/autotile.py

@@ -0,0 +1,57 @@
+"""Autotiling 16 / 47 — reducción canónica de máscaras de vecindad 8-bit.
+
+Bits (convención canónica sprout, ver INVESTIGACION.md §5.3)::
+
+    N=1, NE=2, E=4, SE=8, S=16, SW=32, W=64, NW=128
+
+El bit diagonal solo cuenta si **ambos** cardinales adyacentes están presentes:
+así 2**8 = 256 vecindades colapsan a 47. Un "corner bit" describe el cuadrante
+donde se juntan sus dos lados; si falta un lado, ese cuadrante ya es borde
+exterior y la diagonal no aporta una silueta distinta.
+
+Referencia verificada contra Godot 4.7 (Blobsmith Autotile Wirer, MIT):
+https://github.com/leobaray/blobsmith-autotile-wirer/blob/master/docs/why-47-tiles-not-256.md
+"""
+from __future__ import annotations
+
+N, NE, E, SE, S, SW, W, NW = 1, 2, 4, 8, 16, 32, 64, 128
+
+SIDES = N | E | S | W  # 0b01010101 == 85
+CORNERS = NE | SE | SW | NW
+
+BITMASK = "N1,E4,S16,W64,NE2,SE8,SW32,NW128"
+
+
+def canonical_47(mask: int) -> int:
+    """Máscara canónica del sistema 8-bit (47 clases)."""
+    m = mask & SIDES
+    if (mask & NE) and (mask & N) and (mask & E):
+        m |= NE
+    if (mask & SE) and (mask & S) and (mask & E):
+        m |= SE
+    if (mask & SW) and (mask & S) and (mask & W):
+        m |= SW
+    if (mask & NW) and (mask & N) and (mask & W):
+        m |= NW
+    return m
+
+
+def canonical_16(mask: int) -> int:
+    """Máscara canónica del sistema cardinal (16 clases, Match Sides)."""
+    return mask & SIDES
+
+
+def canonical(mask: int, size: int) -> int:
+    if size == 16:
+        return canonical_16(mask)
+    if size == 47:
+        return canonical_47(mask)
+    raise ValueError(f"autotile no soportado: {size!r} (esperado 16 | 47)")
+
+
+def masks(size: int) -> list[int]:
+    """Máscaras canónicas en orden ascendente = orden de la hoja (cols=8)."""
+    fn = {16: canonical_16, 47: canonical_47}.get(size)
+    if fn is None:
+        raise ValueError(f"autotile no soportado: {size!r} (esperado 16 | 47)")
+    return [m for m in range(256) if fn(m) == m]

sprout/cli.py

@@ -0,0 +1,518 @@
+"""CLI `sprout`: generación procedural determinista de assets 2D para Expo.
+
+Uso:
+  sprout generate specs/demo.json --out ../demo/assets/procgen
+  sprout generate specs/demo.json --png-mode png8 --texturepacker --mipmaps
+  sprout batch specs/ --out ../demo/assets/procgen
+  sprout watch specs/ --out ../demo/assets/procgen
+  sprout info specs/demo.json [--json]
+  sprout lint specs/demo.json [--json]
+  sprout diff <a> <b> [--json]
+  sprout validate specs/demo.json
+"""
+from __future__ import annotations
+
+import io
+import json
+import time
+import zlib
+from pathlib import Path
+
+import typer
+
+from . import __version__
+from .exporter import (
+    apply_png_mode,
+    build_autotile_map,
+    build_font_map,
+    build_manifest,
+    build_shader,
+    build_sheet,
+    build_texturepacker,
+    compute_mipmap_meta,
+    emit_index_ts,
+    render_items,
+    shader_filename,
+    texturepacker_filename,
+    write_manifest,
+    write_mipmap_files,
+    write_png,
+    write_texturepacker,
+)
+from .generators.base import FrameData
+from .spec import Spec, SpecError, load_spec
+
+app = typer.Typer(add_completion=False, no_args_is_help=True,
+                  help="sprout — assets 2D procedurales deterministas para Expo + react-native-skia.")
+
+
+PNG_MODES = ("rgba", "png8", "png24")
+
+
+def _generate(spec_path: Path, out_dir: Path | None, seed: int | None,
+              skip_existing: bool, png_mode: str = "rgba",
+              texturepacker: bool = False, mipmaps: bool = False,
+              mip_levels: int = 3) -> dict:
+    spec = load_spec(spec_path)
+    if seed is not None:
+        spec.seed = seed
+
+    frames = render_items(spec)
+    sheet, records = build_sheet(spec, frames)
+    out = out_dir if out_dir is not None else spec_path.parent
+    atlas_name = spec.filename
+    atlas_path = out / atlas_name
+    manifest_path = out / "manifest.json"
+    index_path = out / "index.ts"
+    tp_path = out / texturepacker_filename(spec) if texturepacker else None
+
+    autotile_map = build_autotile_map(spec, frames)
+    font_map = build_font_map(spec, frames)
+    shader_source, shader_block = build_shader(spec)
+    shader_path = out / shader_filename(spec) if shader_block else None
+    mip_meta = compute_mipmap_meta(sheet, spec, mip_levels) if mipmaps else []
+    manifest = build_manifest(spec, records, atlas_name, sheet, str(spec_path),
+                              autotile_map, shader_block, font_map,
+                              {"levels": mip_meta} if mip_meta else None)
+
+    if skip_existing and atlas_path.is_file() and manifest_path.is_file() and index_path.is_file():
+        missing_extra = (
+            (shader_block and not (shader_path and shader_path.is_file()))
+            or (texturepacker and not tp_path.is_file())
+            or (mipmaps and not all((out / lvl["file"]).is_file() for lvl in mip_meta))
+        )
+        if missing_extra:
+            pass  # falta un artefacto opcional -> regenerar
+        else:
+            current = zlib.crc32(atlas_path.read_bytes()) & 0xFFFFFFFF
+            probe = io.BytesIO()
+            apply_png_mode(sheet, png_mode).save(probe, format="PNG")
+            fresh = zlib.crc32(probe.getvalue()) & 0xFFFFFFFF
+            same_manifest = manifest_path.read_bytes() == (
+                json.dumps(manifest, indent=2) + "\n"
+            ).encode()
+            same_shader = (
+                shader_source is None
+                or (shader_path is not None
+                    and shader_path.read_bytes() == shader_source.encode())
+            )
+            if current == fresh and same_manifest and same_shader:
+                return {"spec": spec, "out": out, "atlas": atlas_path, "crc": current,
+                        "skipped": True}
+
+    crc = write_png(sheet, atlas_path, png_mode)
+    write_manifest(manifest, manifest_path)
+    if shader_source is not None and shader_path is not None:
+        shader_path.parent.mkdir(parents=True, exist_ok=True)
+        shader_path.write_text(shader_source)
+    emit_index_ts(manifest, index_path)
+    if texturepacker:
+        tp = build_texturepacker(spec, records, atlas_name, sheet, png_mode)
+        write_texturepacker(tp, tp_path)
+    if mipmaps:
+        write_mipmap_files(sheet, out, png_mode, mip_meta)
+    return {"spec": spec, "out": out, "atlas": atlas_path, "crc": crc, "skipped": False}
+
+
+@app.command()
+def generate(
+    spec: Path = typer.Argument(..., help="spec.json a generar"),
+    out: Path = typer.Option(None, "--out", "-o", help="directorio de salida (default: junto a la spec)"),
+    seed: int = typer.Option(None, "--seed", "-s", help=f"sobreescribe el seed de la spec"),
+    skip_existing: bool = typer.Option(False, "--skip-existing", help="no reescribe si el atlas ya existe con el mismo crc"),
+    png_mode: str = typer.Option("rgba", "--png-mode", help="formato del atlas: rgba | png8 | png24"),
+    texturepacker: bool = typer.Option(False, "--texturepacker", help="emite además <name>.tpsheet.json (formato TexturePacker JSON Hash)"),
+    mipmaps: bool = typer.Option(False, "--mipmaps", help="genera una cadena de mip levels del atlas (@0.5x, @0.25x, ...)"),
+    mipmap_levels: int = typer.Option(3, "--mipmap-levels", help="cantidad máxima de niveles de mip (con --mipmaps)"),
+) -> None:
+    """Genera spritesheet + manifest.json + index.ts desde una spec."""
+    if png_mode not in PNG_MODES:
+        typer.secho(f"--png-mode inválido '{png_mode}' (disponibles: {', '.join(PNG_MODES)})",
+                    fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    try:
+        r = _generate(spec, out, seed, skip_existing, png_mode, texturepacker, mipmaps, mipmap_levels)
+    except SpecError as e:
+        typer.secho(f"error en {spec}: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    s: Spec = r["spec"]
+    if r["skipped"]:
+        typer.secho(f"[{s.name}] sin cambios (crc {r['crc']:08x}) — skip", fg=typer.colors.YELLOW)
+        return
+    typer.secho(
+        f"[{s.name}] seed={s.seed} frames={s.total_frames} "
+        f"sheet={s.layout.cols}x{s.layout.resolve_rows(s.total_frames)} grid"
+        f" -> {r['out'].resolve()}",
+        fg=typer.colors.GREEN,
+    )
+    typer.secho(f"  atlas.png crc=0x{r['crc']:08x}", fg=typer.colors.BRIGHT_BLACK)
+
+
+@app.command()
+def batch(
+    specs_dir: Path = typer.Argument(..., help="directorio (o glob) con specs"),
+    out: Path = typer.Option(None, "--out", "-o", help="directorio de salida común"),
+    skip_existing: bool = typer.Option(False, "--skip-existing", help="no reescribe atlases sin cambios"),
+    png_mode: str = typer.Option("rgba", "--png-mode", help="formato del atlas: rgba | png8 | png24"),
+    texturepacker: bool = typer.Option(False, "--texturepacker", help="emite además <name>.tpsheet.json (formato TexturePacker JSON Hash)"),
+    mipmaps: bool = typer.Option(False, "--mipmaps", help="genera una cadena de mip levels del atlas (@0.5x, @0.25x, ...)"),
+    mipmap_levels: int = typer.Option(3, "--mipmap-levels", help="cantidad máxima de niveles de mip (con --mipmaps)"),
+) -> None:
+    """Genera todas las specs de un directorio (patrón *.json)."""
+    if png_mode not in PNG_MODES:
+        typer.secho(f"--png-mode inválido '{png_mode}' (disponibles: {', '.join(PNG_MODES)})",
+                    fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    files = sorted(specs_dir.glob("*.json"))
+    if not files:
+        typer.secho(f"no hay specs (*.json) en {specs_dir}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    failed = 0
+    for f in files:
+        try:
+            _generate(f, out, None, skip_existing, png_mode, texturepacker, mipmaps, mipmap_levels)
+        except SpecError as e:
+            typer.secho(f"error en {f}: {e}", fg=typer.colors.RED, err=True)
+            failed += 1
+    typer.echo(f"[batch] {len(files) - failed}/{len(files)} specs ok")
+    if failed:
+        raise typer.Exit(1)
+
+
+@app.command()
+def validate(spec: Path = typer.Argument(..., help="spec.json a validar")) -> None:
+    """Valida la estructura y los plug-ins de una spec."""
+    try:
+        s = load_spec(spec)
+    except SpecError as e:
+        typer.secho(f"inválida: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    typer.secho(
+        f"[{s.name}] OK — items={[i.id for i in s.items]} "
+        f"frames={s.total_frames} seed={s.seed}",
+        fg=typer.colors.GREEN,
+    )
+
+
+@app.command()
+def info(
+    spec: Path = typer.Argument(..., help="spec.json a inspeccionar"),
+    as_json: bool = typer.Option(False, "--json", help="salida machine-readable"),
+) -> None:
+    """Reporte de una spec: items, frames, layout y tamaño estimado del atlas."""
+    try:
+        s = load_spec(spec)
+    except SpecError as e:
+        typer.secho(f"inválida: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    cols = s.layout.cols
+    rows = s.layout.resolve_rows(s.total_frames)
+    fpx = s.layout.frame_px
+    atlas_w, atlas_h = cols * fpx, rows * fpx
+
+    if as_json:
+        typer.echo(json.dumps({
+            "name": s.name,
+            "seed": s.seed,
+            "target": s.target,
+            "spec": str(spec),
+            "layout": {
+                "framePx": fpx, "cols": cols, "rows": rows,
+                "tileLogical": s.layout.tile_logical, "sample": s.layout.sample,
+            },
+            "atlas": {
+                "file": s.filename, "width": atlas_w, "height": atlas_h,
+                "frames": s.total_frames,
+            },
+            "items": [
+                {"id": it.id, "generator": it.generator, "frames": it.frames,
+                 "autotile": it.autotile, "params": it.params}
+                for it in s.items
+            ],
+            "animations": {
+                n: {"frames": a.frames, "fps": a.fps, "loop": a.loop}
+                for n, a in s.animations.items()
+            },
+            "runtime": bool(s.runtime),
+        }, indent=2))
+        return
+
+    typer.secho(f"[{s.name}] {spec}", fg=typer.colors.GREEN, bold=True)
+    typer.echo(f"  seed    : {s.seed}")
+    typer.echo(f"  target  : {s.target}")
+    typer.echo(f"  layout  : framePx={fpx} cols={cols} rows={rows} "
+               f"tileLogical={s.layout.tile_logical} sample={s.layout.sample}")
+    typer.echo(f"  atlas   : {s.filename} {atlas_w}x{atlas_h} ({s.total_frames} frames)")
+    typer.echo(f"  runtime : {'sí' if s.runtime else 'no'}")
+    typer.echo("  items:")
+    for it in s.items:
+        extra = ""
+        if it.autotile:
+            extra += f" autotile={it.autotile}"
+        keys = sorted(k for k in it.params if k != "autotile")
+        if keys:
+            extra += f" params[{','.join(keys)}]"
+        typer.echo(f"    - {it.id:<14} {it.generator:<10} frames={it.frames}{extra}")
+    if s.animations:
+        typer.echo("  anim:")
+        for name, a in s.animations.items():
+            typer.echo(f"    - {name:<14} frames={a.frames} fps={a.fps} loop={a.loop}")
+
+
+PADDING_WARN_RATIO = 0.25
+
+
+def _lint_warnings(spec: Spec, items_frames: list[list[FrameData]]) -> list[dict]:
+    """Advertencias de calidad de una spec ya renderizada: padding de atlas
+    (celdas de grilla sin usar) y frames completamente transparentes."""
+    warnings: list[dict] = []
+
+    cols = spec.layout.cols
+    rows = spec.layout.resolve_rows(spec.total_frames)
+    capacity = cols * rows
+    unused = capacity - spec.total_frames
+    if capacity and unused / capacity > PADDING_WARN_RATIO:
+        warnings.append({
+            "check": "padding",
+            "message": f"{unused}/{capacity} celdas del atlas sin usar ({unused / capacity:.0%})",
+        })
+
+    empty_ids = [
+        fr.id
+        for item, frames in zip(spec.items, items_frames, strict=True)
+        # el generador `font` produce glifos vacíos a propósito (el espacio
+        # no pinta ningún píxel) — no es un frame desperdiciado.
+        if item.generator != "font"
+        for fr in frames
+        # los tiles RGB (p. ej. terrain sin autotile) son opacos por diseño
+        # y no tienen canal alpha que consultar.
+        if fr.image.mode == "RGBA" and fr.image.getchannel("A").getbbox() is None
+    ]
+    if empty_ids:
+        warnings.append({
+            "check": "empty_frames",
+            "message": f"{len(empty_ids)} frame(s) completamente transparentes",
+            "ids": empty_ids,
+        })
+
+    return warnings
+
+
+@app.command()
+def lint(
+    spec: Path = typer.Argument(..., help="spec.json a analizar"),
+    as_json: bool = typer.Option(False, "--json", help="salida machine-readable"),
+) -> None:
+    """Analiza una spec: padding de atlas y frames vacíos (renderiza para verificar)."""
+    try:
+        s = load_spec(spec)
+        items_frames = render_items(s)
+    except SpecError as e:
+        typer.secho(f"inválida: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    warnings = _lint_warnings(s, items_frames)
+    if as_json:
+        typer.echo(json.dumps({"spec": str(spec), "warnings": warnings}, indent=2))
+    elif not warnings:
+        typer.secho(f"[{s.name}] OK — sin advertencias", fg=typer.colors.GREEN)
+    else:
+        typer.secho(f"[{s.name}] {len(warnings)} advertencia(s):", fg=typer.colors.YELLOW)
+        for w in warnings:
+            typer.echo(f"  - [{w['check']}] {w['message']}")
+    raise typer.Exit(1 if warnings else 0)
+
+
+def _diff_specs(a: Spec, b: Spec) -> list[dict]:
+    """Diferencias estructurales entre dos specs: `[{"field", "a", "b"}, ...]`."""
+    diffs: list[dict] = []
+
+    for field in ("name", "seed", "target"):
+        av, bv = getattr(a, field), getattr(b, field)
+        if av != bv:
+            diffs.append({"field": field, "a": av, "b": bv})
+
+    for f in ("frame_px", "cols", "tile_logical", "sample"):
+        av, bv = getattr(a.layout, f), getattr(b.layout, f)
+        if av != bv:
+            diffs.append({"field": f"layout.{f}", "a": av, "b": bv})
+
+    a_items = {i.id: i for i in a.items}
+    b_items = {i.id: i for i in b.items}
+    for iid in sorted(set(b_items) - set(a_items)):
+        diffs.append({"field": f"items.{iid}", "a": None, "b": "added"})
+    for iid in sorted(set(a_items) - set(b_items)):
+        diffs.append({"field": f"items.{iid}", "a": "removed", "b": None})
+    for iid in sorted(set(a_items) & set(b_items)):
+        ia, ib = a_items[iid], b_items[iid]
+        if (ia.generator, ia.frames, ia.params) != (ib.generator, ib.frames, ib.params):
+            diffs.append({
+                "field": f"items.{iid}",
+                "a": {"generator": ia.generator, "frames": ia.frames, "params": ia.params},
+                "b": {"generator": ib.generator, "frames": ib.frames, "params": ib.params},
+            })
+
+    a_anim, b_anim = a.animations, b.animations
+    for name in sorted(set(b_anim) - set(a_anim)):
+        diffs.append({"field": f"animations.{name}", "a": None, "b": "added"})
+    for name in sorted(set(a_anim) - set(b_anim)):
+        diffs.append({"field": f"animations.{name}", "a": "removed", "b": None})
+    for name in sorted(set(a_anim) & set(b_anim)):
+        ia, ib = a_anim[name], b_anim[name]
+        if (ia.frames, ia.fps, ia.loop) != (ib.frames, ib.fps, ib.loop):
+            diffs.append({
+                "field": f"animations.{name}",
+                "a": {"frames": ia.frames, "fps": ia.fps, "loop": ia.loop},
+                "b": {"frames": ib.frames, "fps": ib.fps, "loop": ib.loop},
+            })
+
+    return diffs
+
+
+def _diff_outputs(a: Path, b: Path) -> list[dict]:
+    """Diferencias entre dos directorios de salida: CRC del atlas + manifest.json."""
+    diffs: list[dict] = []
+
+    atlas_a, atlas_b = a / "atlas.png", b / "atlas.png"
+    if atlas_a.is_file() and atlas_b.is_file():
+        crc_a = zlib.crc32(atlas_a.read_bytes()) & 0xFFFFFFFF
+        crc_b = zlib.crc32(atlas_b.read_bytes()) & 0xFFFFFFFF
+        if crc_a != crc_b:
+            diffs.append({"field": "atlas.crc", "a": f"{crc_a:08x}", "b": f"{crc_b:08x}"})
+    else:
+        diffs.append({"field": "atlas.png", "a": atlas_a.is_file(), "b": atlas_b.is_file()})
+
+    man_a_p, man_b_p = a / "manifest.json", b / "manifest.json"
+    if not (man_a_p.is_file() and man_b_p.is_file()):
+        diffs.append({"field": "manifest.json", "a": man_a_p.is_file(), "b": man_b_p.is_file()})
+        return diffs
+
+    man_a = json.loads(man_a_p.read_text())
+    man_b = json.loads(man_b_p.read_text())
+
+    for field in ("name", "seed"):
+        if man_a.get(field) != man_b.get(field):
+            diffs.append({"field": field, "a": man_a.get(field), "b": man_b.get(field)})
+
+    size_a = (man_a["files"]["atlasW"], man_a["files"]["atlasH"])
+    size_b = (man_b["files"]["atlasW"], man_b["files"]["atlasH"])
+    if size_a != size_b:
+        diffs.append({"field": "atlas.size", "a": list(size_a), "b": list(size_b)})
+
+    ids_a = {f["id"] for f in man_a["frames"]}
+    ids_b = {f["id"] for f in man_b["frames"]}
+    if ids_b - ids_a:
+        diffs.append({"field": "frames.added", "a": None, "b": sorted(ids_b - ids_a)})
+    if ids_a - ids_b:
+        diffs.append({"field": "frames.removed", "a": sorted(ids_a - ids_b), "b": None})
+
+    for block in ("autotile", "shader", "font"):
+        if (block in man_a) != (block in man_b):
+            diffs.append({"field": f"{block}.present", "a": block in man_a, "b": block in man_b})
+
+    return diffs
+
+
+@app.command()
+def diff(
+    a: Path = typer.Argument(..., help="spec.json o directorio de salida A"),
+    b: Path = typer.Argument(..., help="spec.json o directorio de salida B"),
+    as_json: bool = typer.Option(False, "--json", help="salida machine-readable"),
+) -> None:
+    """Compara dos specs (.json) o dos directorios de salida (atlas+manifest)."""
+    a_is_spec, b_is_spec = a.suffix == ".json", b.suffix == ".json"
+    if a_is_spec != b_is_spec:
+        typer.secho("no se puede comparar una spec (.json) con un directorio de salida",
+                    fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    try:
+        if a_is_spec:
+            kind, diffs = "spec", _diff_specs(load_spec(a), load_spec(b))
+        else:
+            if not a.is_dir() or not b.is_dir():
+                typer.secho(f"directorio no encontrado: {a if not a.is_dir() else b}",
+                            fg=typer.colors.RED, err=True)
+                raise typer.Exit(1)
+            kind, diffs = "output", _diff_outputs(a, b)
+    except SpecError as e:
+        typer.secho(f"inválida: {e}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    if as_json:
+        typer.echo(json.dumps({"a": str(a), "b": str(b), "kind": kind, "diffs": diffs}, indent=2))
+    elif not diffs:
+        typer.secho(f"sin diferencias ({kind})", fg=typer.colors.GREEN)
+    else:
+        typer.secho(f"{len(diffs)} diferencia(s) ({kind}):", fg=typer.colors.YELLOW)
+        for d in diffs:
+            typer.echo(f"  - {d['field']}: {d['a']!r} -> {d['b']!r}")
+    raise typer.Exit(1 if diffs else 0)
+
+
+@app.command()
+def watch(
+    specs_dir: Path = typer.Argument(..., help="directorio con specs (*.json)"),
+    out: Path = typer.Option(None, "--out", "-o", help="directorio de salida (default: junto a cada spec)"),
+    interval: float = typer.Option(1.0, "--interval", "-i", help="sondaje de cambios en segundos"),
+) -> None:
+    """Vigila specs/ y regenera assets cuando cambian (Ctrl-C para detener)."""
+    if not specs_dir.is_dir():
+        typer.secho(f"no existe el directorio: {specs_dir}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    files = sorted(specs_dir.glob("*.json"))
+    if not files:
+        typer.secho(f"no hay specs (*.json) en {specs_dir}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+
+    typer.secho(
+        f"[watch] {specs_dir} -> {out or specs_dir} cada {interval}s "
+        f"({len(files)} specs) — Ctrl-C para salir",
+        fg=typer.colors.CYAN,
+    )
+    mtimes: dict[Path, float] = {}
+    primera = True
+    try:
+        while True:
+            for f in sorted(specs_dir.glob("*.json")):
+                try:
+                    mt = f.stat().st_mtime
+                except OSError:
+                    continue
+                if mtimes.get(f, 0.0) >= mt:
+                    continue
+                mtimes[f] = mt
+                if not primera:
+                    typer.secho(f"  [cambio] {f.name}", fg=typer.colors.BLUE)
+                try:
+                    r = _generate(f, out, None, True)
+                except SpecError as e:
+                    typer.secho(f"  [error] {f.name}: {e}", fg=typer.colors.RED, err=True)
+                    continue
+                s: Spec = r["spec"]
+                if r["skipped"]:
+                    typer.secho(f"  [skip]  {s.name} sin cambios (crc {r['crc']:08x})",
+                                fg=typer.colors.YELLOW)
+                else:
+                    typer.secho(
+                        f"  [ok]    {s.name} seed={s.seed} frames={s.total_frames} "
+                        f"-> {r['out'].resolve()} (crc {r['crc']:08x})",
+                        fg=typer.colors.GREEN,
+                    )
+            primera = False
+            time.sleep(interval)
+    except KeyboardInterrupt:
+        typer.secho("\n[watch] detenido.", fg=typer.colors.CYAN)
+
+
+@app.callback(invoke_without_command=True)
+def _version(version: bool = typer.Option(False, "--version", help="muestra la versión")) -> None:
+    if version:
+        typer.echo(f"sprout {__version__}")
+        raise typer.Exit()
+
+
+if __name__ == "__main__":
+    app()