feat(gamedev): comfyui_build_inpaint_asset_workflow — editar solo una región de un asset (inpaint)

Cuarto vértice del eje transform de gamedev-2d: editar SOLO una región de un
asset 2D ya pintado vía inpaint, conservando el resto del sprite. Completa el
eje junto a txt2img (crear de cero), asset_variant (img2img: reescribe todo) y
sprite_from_sketch (ControlNet: sprite nuevo desde boceto).

Función pura (API format dict) que compone comfyui_build_inpaint_workflow (base)
+ comfyui_inject_lora (estilo opcional). Recibe asset + máscara (blanco=editar,
negro=conservar) + prompt de qué poner; VAEEncodeForInpaint codifica respetando
la máscara y dilata el borde grow_mask px para difuminar la costura; el KSampler
regenera solo esa zona. mode="noise_mask" degrada a VAEEncode+SetLatentNoiseMask
para servidores sin VAEEncodeForInpaint (error path). size escala imagen Y máscara
de forma consistente. class_types verificados contra /object_info (8GB lowvram).

Probado e2e en GPU con SD1.5: máscara circular sobre la mano del goblin
enemy_creature_00001_.png, prompt "a glowing blue magic orb" (prompt_id 88b52c66).
Solo la región enmascarada cambió: diff medio dentro 40.3 vs fuera 1.97 (ratio
20.4x), 44.6% px cambiados dentro vs 1.7% fuera. Confirmación visual: orbe azul
en la región, resto del goblin idéntico.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

docs/capabilities/gamedev-2d.md

@@ -68,15 +68,19 @@ VFX (ver `reports/0143`).
 ## Builders de transformación (`gamedev-2d`, puros — parten de una imagen/dibujo de entrada)
 
 A diferencia de los builders de **generación** de arriba (parten de TEXTO, txt2img desde
-ruido), estos parten de una **imagen de entrada** y la transforman. Dos sub-ejes:
+ruido), estos parten de una **imagen de entrada** y la transforman. Tres sub-ejes:
 
 - **img2img** (`asset_variant`): parte de un asset **ya pintado**; el KSampler arranca del
   latente de la imagen base (LoadImage → VAEEncode), no de ruido, así que con `denoise` medio
-  conserva la estructura mientras el prompt reescribe material/paleta/tier. Conserva forma **y**
-  color del original.
+  conserva la estructura mientras el prompt reescribe material/paleta/tier. Reescribe **todo** el
+  asset conservando forma **y** color del original.
 - **sketch→ControlNet** (`sprite_from_sketch`): parte del **dibujo tosco** del dev (boceto,
   lineart, garabato); es `txt2img` (arranca de ruido) pero condicionado por un ControlNet atado
   al mapa de líneas del dibujo. Conserva solo la **forma**; la IA pone material/color/acabado.
+- **inpaint** (`inpaint_asset`): parte de un asset **ya pintado** + una **máscara** que marca qué
+  región editar (blanco) y cuál conservar (negro); el sampler regenera **solo** la zona enmascarada
+  dejando el resto del pixel intacto. Cambia **una parte** (arma, casco, escudo, reparación), no el
+  asset entero.
 
 Cubren el eje que el critic de generación (`reports/0178`) no exploró: derivar de un asset o
 del dibujo del dev, no inventar un tipo nuevo desde texto.
@@ -85,6 +89,7 @@ del dibujo del dev, no inventar un tipo nuevo desde texto.
 |---|---|---|
 | `comfyui_build_asset_variant_workflow_py_ml` | `(input_image, variant, *, checkpoint="dreamshaper_8…", denoise=0.5, style="game asset", size=512, seed=0, lora=None, …) -> dict` | UNA **variante coherente de un asset 2D ya generado** (img2img): parte del sprite/icono que existe en `input_image` y produce su versión de **otro material/paleta/tier/estado** (`ice element`, `fire element`, `battle-damaged`, `golden tier 2`, `corrupted`) manteniendo **silueta, pose y composición** del original. Compone `comfyui_build_img2img_workflow` (LoadImage → VAEEncode → KSampler con `denoise`) + `comfyui_inject_lora` (estilo opcional) + `ImageScale` opcional (`size` normaliza la base a size×size; `size=None` preserva las dimensiones exactas sin deformar). El prompt es `{variant}, {style}, same composition, same pose, same silhouette, …`. **`denoise` es la palanca**: ~0.3 invisible, **0.45-0.6 recomendado** (cambia material/paleta, conserva forma), ~0.8 deriva la pose y se acerca a txt2img. Set de variantes del MISMO asset = mismo `input_image`/`style`/`seed`, varía solo `variant`. **DISTINTO de los builders txt2img** (`enemy_creature`, `item_icon`…): esos generan un tipo desde cero; éste transforma uno concreto. **NO inyecta Rembg** (img2img preserva el fondo/alpha del original según la base). ⚠️ la imagen base debe existir en `input/` del server (subir con `POST /upload/image`); pura, no valida (usar `comfyui_validate_workflow` antes de enviar); asset NO cuadrado + `size` fijo + `crop="disabled"` deforma → `size=None` o `crop="center"`. Probado e2e en GPU con SD1.5 — variante `ice element, frozen` del goblin `enemy_creature_00001_.png` denoise 0.5 seed 7 512×512 (`prompt_id 5e4a5d3d`): silueta conservada (luminance corr 0.63) + paleta a frío (blueness B−R −1.6→+1.9), `reports/0181`. SD1.5. |
 | `comfyui_build_sprite_from_sketch_workflow_py_ml` | `(sketch_image, subject, *, control_type="lineart", checkpoint="dreamshaper_8…", style="game asset, clean, centered", strength=0.8, size=512, seed=0, lora=None, preprocess=True, controlnet_name=None, …) -> dict` | UN **sprite pintado a partir del BOCETO del dev**, guiado por **ControlNet** (sub-eje sketch→ControlNet, **NO img2img**). Recibe el dibujo tosco que existe en `sketch_image` (boceto/lineart/garabato) + `subject` (qué es), y genera un sprite en estilo de juego que **conserva la forma dibujada**: el dev marca la silueta, la IA pone material/color/acabado. Mecanismo: `txt2img` base (ruido, `EmptyLatentImage`, `denoise 1.0`) cuyo positivo pasa por `ControlNetApply` atado al mapa de líneas del boceto. `control_type` elige el **preprocesador** (`LineArtPreprocessor` / `ScribblePreprocessor` / `CannyEdgePreprocessor`, interpuesto entre el boceto y el ControlNet por un helper) y, por defecto, el **modelo CN emparejado**. Compone `comfyui_build_txt2img_workflow` + `comfyui_inject_controlnet` + `comfyui_inject_lora` (estilo opcional). **`strength` es la palanca**: 0 = ignora el dibujo (txt2img puro), ~0.8 recomendado (respeta forma dejando limpiar a la IA), 1.0 = se ciñe estricto. **DISTINTO de `asset_variant`** (img2img conserva forma+color de una imagen ya pintada) y de los txt2img (`enemy_creature`…, inventan la forma desde texto): éste conserva **solo la forma** del dibujo. ⚠️ el boceto debe existir en `input/` (subir con `POST /upload/image`); pura, no valida (usar `comfyui_validate_workflow` antes de enviar); `preprocess=False` solo si el sketch ya es un lineart limpio. **GOTCHA del server 8GB: solo `canny`/`depth`/`openpose` SD1.5 instalados** — para `lineart`/`scribble` pasa `controlnet_name="control_v11p_sd15_canny_fp16.safetensors"` u usa `control_type="canny"` (out-of-the-box); pendiente humano descargar `control_v11p_sd15_lineart_fp16`/`scribble`. Probado e2e en GPU con SD1.5 — boceto del goblin `enemy_creature_00001_.png` → `CannyEdgePreprocessor` → ControlNet canny, `subject="dark fantasy goblin warrior"` strength 0.85 seed 123 512×512 (`prompt_id ea6fc372`): pose/orejas/hombrera/lanza dentada/espada del dibujo conservadas, repintado en estilo de juego, `reports/0182`. SD1.5. |
+| `comfyui_build_inpaint_asset_workflow_py_ml` | `(input_image, mask_image, prompt, *, checkpoint="dreamshaper_8…", denoise=1.0, style="game asset", grow_mask=6, size=None, seed=0, lora=None, mode="vae_encode", …) -> dict` | EDITA **solo una región** de un asset 2D ya pintado (**inpaint**, sub-eje propio). Recibe el asset en `input_image` + una **máscara** `mask_image` (BLANCO = editar, NEGRO = conservar) + `prompt` de qué poner ahí, y repinta **únicamente** la zona enmascarada dejando el resto del sprite intacto (cambiar/añadir un arma, quitar un casco, poner un escudo, reparar una zona dañada). Mecanismo (`mode="vae_encode"`): `VAEEncodeForInpaint` codifica el latente respetando la máscara y dilata su borde `grow_mask` px para difuminar la costura; `KSampler` (`denoise` alto) regenera solo esa región con `{prompt}, {style}, seamless blend…`. Compone `comfyui_build_inpaint_workflow` (base) + `comfyui_inject_lora` (estilo opcional); `size` escala imagen **Y** máscara de forma consistente (escalar solo una las desalinea). **`grow_mask` es la palanca de costura** (6-10 px difumina el borde lo/nuevo); `denoise` 1.0 reescribe entero, ~0.5-0.7 repara suave. **DISTINTO de `asset_variant`** (img2img reescribe TODO el asset) y de `sprite_from_sketch` (ControlNet parte de un dibujo de líneas para un sprite nuevo): éste edita **un trozo** delimitado por la máscara. **ERROR-PATH**: si el server no expone `VAEEncodeForInpaint`, pasar `mode="noise_mask"` → degrada a `VAEEncode` + `SetLatentNoiseMask` (+ `GrowMask`); `mask_image` vacío lanza `ValueError`. ⚠️ asset y máscara deben existir en `input/` (subir con `POST /upload/image`) y compartir resolución (o usar `size`); `ImageScale` aquí NO ofrece `lanczos` (válidos `bilinear`/`nearest-exact`/`area`/`bicubic`); pura, no valida. Probado e2e en GPU con SD1.5 — máscara circular (R70) sobre la mano del goblin `enemy_creature_00001_.png`, `prompt="a glowing blue magic orb"` grow_mask 8 denoise 1.0 seed 7 (`prompt_id 88b52c66`): orbe azul en la región, **resto idéntico** (diff medio dentro 40.3 vs fuera 1.97 → ratio 20.4×; 44.6% px cambiados dentro vs 1.7% fuera), `reports/0183`. SD1.5. |
 
 ## Funciones de post-proceso y puente (`gamedev-2d`, CPU)