feat(comfyui): pipeline comfyui_pixelart_real_oneshot — pixelart REAL (PixelOE + cuantizacion dura)

Materializa el metodo ganador del report 0215: generar a alta-res con SDXL + LoRA SDXL_pixel-art, downscale contrast-aware con PixelOE (engine=pixeloe para sprites/personajes) o nearest (tiles), y cuantizacion dura con comfyui_pixelize_image (16 colores libres o paleta fija pico-8/nes/game-boy). - pixeloe_downscale_py_ml: downscale contrast-aware via lib pixeloe con bridge de interprete (la lib vive en el venv de ComfyUI, no en el del registry). No-throw, fallback limpio si pixeloe no disponible. - comfyui_pixelart_real_oneshot_py_pipelines: one-shot que compone build_pixelart + submit + wait + fetch + pixeloe_downscale + pixelize_image. Fallback automatico pixeloe->nearest. Sweet-spot 64px personajes, 32px iconos. Verificado por PIL: personaje 64x64=16 colores, icono 32x32=16 colores (vs ~33k de la imagen de difusion cruda). 100% grid duro + outline nitido. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
chore: auto-commit (1 archivos)
2026-06-28 15:24:15 +02:00 · 2026-06-28 15:03:24 +02:00 · 2026-06-28 15:02:45 +02:00 · 2026-06-28 15:01:37 +02:00 · 2026-06-28 07:34:26 +02:00 · 2026-06-28 07:34:02 +02:00
26 changed files with 1739 additions and 25 deletions
@@ -14,7 +14,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu

 | Grupo | N | Que cubre |
 |---|---|---|
-| [gamedev-2d](gamedev-2d.md) | 36 | Assets 2D para Godot via ComfyUI: 31 builders de workflow (pixelart/seamless/iso/sprite/topdown/card/enemy/prop/structure/foliage/trap/projectile/decal/particle/rune/weather/badge/skill-tree/dialogue/icon/portrait/VFX...) + 5 de apoyo: post-proceso (pixelize, luma->alpha) + puente de assets a Godot 4 (.import + reimport headless). Tag canonico `gamedev-2d` (antes `gamedev`, ya unificado) |
+| [gamedev-2d](gamedev-2d.md) | 47 | Assets 2D para Godot via ComfyUI: 36 builders de workflow (31 de generación desde texto: pixelart/seamless/iso/sprite/topdown/card/enemy/prop/structure/foliage/trap/projectile/decal/particle/rune/weather/badge/skill-tree/dialogue/icon/portrait/VFX... + 5 de transformación desde imagen: asset_variant/sprite_from_sketch/inpaint_asset/outpaint_asset/directional_sprite) + 11 de apoyo: post-proceso (pixelize, luma->alpha, flatten_alpha), puente de assets a Godot 4 (.import + reimport headless), style presets (get/apply_gamedev_style_preset) y pipelines one-shot (asset_pack/character_set/styled_asset). Tag canonico `gamedev-2d` (antes `gamedev`, ya unificado) |
 | [gamedev-engine](gamedev-engine.md) | 8 | Runtime de juego C++ multiplataforma (PC + WebAssembly): SDL3 + sokol_gfx + miniaudio. Game loop fixed-timestep, camara 2D, input unificado (teclado/gamepad/touch), sprite batch, setup de render/audio y build a wasm. Grupo hermano de `gamedev-2d` (este ejecuta el juego, aquel genera los assets) |
 | [registry](registry.md) | 17 | Auditoria y monitorizacion del propio registry: copied-code, uses-functions, unused, proposals, telemetria |
 | [systemd](systemd.md) | 14 | Generar, instalar, restart y status de unit files systemd via SSH (deploys a VPS) |
@@ -72,8 +72,9 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu
 | [seo](seo.md) | 3 | SEO orientado a datos sobre Google Search Console: autenticar con service account (`gsc_auth`), extraer Search Analytics paginado (`pull_gsc_search_analytics`) y el pipeline de ingesta a DuckDB + espejo Postgres para Metabase (`ingest_gsc_search_analytics`). Cadena de ingesta del proyecto `seo_analytics`; alimenta dashboards de striking distance, CTR opportunities y content decay |
 | [local-hub](local-hub.md) | 4 | Exponer los procesos locales como subdominios `*.localhost` (via Caddy, sin DNS) y reunirlos en una pantalla principal Glance con estado en vivo, refrescada a diario por dag_engine. Descubre servicios (manifiesto + registry), renderiza Caddyfile + config Glance (puras), y el pipeline `refresh_local_hub` regenera+recarga. Fuente de verdad: `apps/local_hub/local_services.yaml` |
 | [comfyui-judge](comfyui-judge.md) | 4 | Panel multi-juez de calidad de imagen: estético LAION-V2 (`comfyui_score_aesthetic`, 0-10) + fidelidad CLIP prompt↔imagen (`comfyui_score_clip_alignment`, 0-1) + crítica LLM-vision (`comfyui_critique_image_llm`, good/bad). Agregados por voto mayoría en `comfyui_judge_image`. Gate objetivo para tests/DoD y el bucle de mejora de skills ComfyUI; degrada con gracia si un juez cae. Jueces estético/fidelidad por subproceso al venv ComfyUI (torch+open_clip), crítico via claude-direct |
-| [comfyui](comfyui.md) | 29 | Controlar ComfyUI (Stable Diffusion por grafos) de dos formas: por API HTTP (build_txt2img_workflow puro → submit → wait → object_info; download_model con validación Civitai/HF) y por la UI web vía CDP sobre la pestaña abierta (load_workflow_ui, set_node_widget_ui para tunear prompt/steps/seed en vivo, queue_prompt_ui = botón Queue Prompt, export_workflow_ui, refresh_nodes_ui). El API format es el puente entre ambos caminos. Las funciones de UI componen `cdp_eval`. Incluye imagen→3D nativo (Hunyuan3D-2, tag `img-to-3d`): build_image_to_3d_workflow + fetch_output_mesh + install_3d_model + pipeline image_to_3d_oneshot |
-| [comfyui-skill](comfyui-skill.md) | 11 | Tratar una configuración de generación ComfyUI como una skill: receta versionada en disco (checkpoint + LoRAs + params + scaffold de prompt + post-proceso) que se compila a un workflow cambiando solo el subject. Save/load/list de recetas, bucle de mejora genera→juzga→bump con gate objetivo (el score del juez decide qué se promueve), export de la skill a grafo cargable en el navegador, y cosecha de Civitai (extract_recipe_from_png + harvest oneshot) que destila el workflow embebido de una imagen pública en una skill candidata |
+| [comfyui](comfyui.md) | 126 | Controlar ComfyUI (Stable Diffusion por grafos) de dos formas: por API HTTP (build_txt2img_workflow puro → submit → wait → object_info; download_model con validación Civitai/HF) y por la UI web vía CDP sobre la pestaña abierta (load_workflow_ui, set_node_widget_ui para tunear prompt/steps/seed en vivo, queue_prompt_ui = botón Queue Prompt, export_workflow_ui, refresh_nodes_ui). El API format es el puente entre ambos caminos. Las funciones de UI componen `cdp_eval`. Cubre txt2img/img2img/inpaint/controlnet/sdxl-refiner/flux, upscale + hires-fix + facedetailer, vídeo (LTX/Wan/SVD), audio (ACE-Step), imagen→3D nativo (Hunyuan3D-2) + post-proceso de malla, templates oficiales, civitai harvest y control de cola. N = funciones con tag `comfyui` (incluye los sub-grupos `comfyui-skill`/`comfyui-styles` y 45 de `gamedev-2d`); las páginas madre de cada sub-grupo desglosan su parte |
+| [comfyui-skill](comfyui-skill.md) | 17 | Tratar una configuración de generación ComfyUI como una skill: receta versionada en disco (checkpoint + LoRAs + params + scaffold de prompt + post-proceso) que se compila a un workflow cambiando solo el subject. Save/load/list de recetas, bucle de mejora genera→juzga→bump con gate objetivo (el score del juez decide qué se promueve), export de la skill a grafo cargable en el navegador, y cosecha de Civitai (extract_recipe_from_png + harvest oneshot) que destila el workflow embebido de una imagen pública en una skill candidata |
+| [comfyui-styles](comfyui-styles.md) | 5 | Capa de estilo reutilizable sobre los builders ComfyUI. Catálogo WAS (tag `comfyui-styles`): `curated_styles_catalog` (~190 estilos), `generate_styles_llm` (genera estilos por LLM via ask_llm), `append_styles` (merge+dedup+backup sobre el styles.json del selector WAS). Style presets gamedev (tag `gamedev-2d`): `get_gamedev_style_preset` (gameboy/ghibli/pixel-art-retro como datos puros) + `apply_style_preset` (preset+subject → kwargs de un builder gamedev-2d). El estilo se trata como dato curado, no como prompt repetido |
 | [comfyui-overview](comfyui-overview.md) | — | Mapa cross-grupo de las capacidades de generación ComfyUI (txt2img, img2img/inpaint, controlnet, skills/multiestilo-LoRA, video, upscale/detail, 3D, juez, operación): cada capacidad → builders/pipelines del registry + grafos UI + skills que la cubren. Índice de entrada al stack ComfyUI; las firmas y gotchas viven en `comfyui.md`/`comfyui-skill.md`/`comfyui-judge.md`. Catálogo navegable de los grafos en disco (subcarpetas por capacidad) en `~/ComfyUI/CAPABILITIES.md` |

 ## Como anadir grupo
@@ -8,7 +8,9 @@ Las tres páginas madre detalladas siguen siendo la fuente de verdad por grupo:

 - [comfyui.md](comfyui.md) — grupo `comfyui`: builders de workflow, ejecución HTTP, UI vía CDP, I/O.
 - [comfyui-skill.md](comfyui-skill.md) — grupo `comfyui-skill`: recetas de estilo versionadas.
+- [comfyui-styles.md](comfyui-styles.md) — grupo `comfyui-styles`: presets + catálogo de estilo (selector WAS).
 - [comfyui-judge.md](comfyui-judge.md) — grupo `comfyui-judge`: panel multi-juez de calidad.
+- [gamedev-2d.md](gamedev-2d.md) — grupo `gamedev-2d`: 47 builders de assets 2D para Godot (45 también `comfyui`).

 El catálogo navegable con los grafos concretos en disco (subcarpetas por capacidad, cómo cargar
 cada uno) vive **fuera del repo**, junto a la instalación: `~/ComfyUI/CAPABILITIES.md`. Este doc es
@@ -25,7 +27,9 @@ Filtros MCP: `mcp__registry__fn_search query="" tag="comfyui"` (y `tag="comfyui-
 | 02 | **img2img / inpaint** | imagen → imagen, regenerar zona enmascarada | `build_img2img`, `build_inpaint` | ✅ | — |
 | 03 | **controlnet** | generación guiada por mapa (depth/pose/canny) | `build_controlnet` | ✅ | — |
 | 04 | **skills (multiestilo/LoRA)** | recetas de estilo reproducibles con `{subject}` | `build_skill_workflow`, `inject_lora`, `generate_with_skill_oneshot`, `harvest_civitai_skill_oneshot` | ✅ ×2 | ✅ ×2 |
+| 04b | **styles (presets/catálogo)** | estilo reutilizable: catálogo WAS + presets gamedev | `curated_styles_catalog`, `generate_styles_llm`, `append_styles`, `get_gamedev_style_preset`, `apply_style_preset` | — | — |
 | 05 | **video** | imagen/texto → vídeo (SVD, LTX, Wan) | `build_img2vid`, `build_video` | ✅ | — |
+| 05b | **audio** | texto → música/SFX/voz (ACE-Step) | `build_audio_workflow`, `fetch_output_audio` | — | — |
 | 06 | **upscale / detail** | ampliar y recuperar detalle (ESRGAN, hires-fix, FaceDetailer) | `build_upscale`, `build_hires_fix`, `inject_hires_fix`, `build_facedetailer` | — | — |
 | 07 | **3D** | imagen/texto → malla 3D (Hunyuan3D) + limpieza | `build_image_to_3d`, `build_textured_3d_multiview`, `image_to_3d_oneshot`, `text_to_3d_oneshot`, `mesh_cleanup_oneshot` | — | — |
 | 08 | **juez / calidad** | puntuar lo generado (gate de DoD y bucle de mejora) | `judge_image`, `score_aesthetic`, `score_clip_alignment`, `critique_image_llm` | — | — |
@@ -67,6 +71,16 @@ sus IDs reales cuando se ejecute `fn index`.
 - `comfyui_extract_recipe_from_png_py_ml` — destila un PNG de Civitai en receta candidata.
 - CRUD + telemetría: `comfyui_list_skills_py_ml`, `comfyui_load_skill_py_ml`, `comfyui_save_skill_py_ml`, `comfyui_update_skill_score_py_ml`, `comfyui_bump_skill_version_py_ml`.

+### 04b · styles (presets / catálogo)
+
+Página madre: [comfyui-styles.md](comfyui-styles.md). Estilo reutilizable como dato, no como prompt repetido.
+
+- `comfyui_curated_styles_catalog_py_ml` (pura) — catálogo curado (~190 estilos) para el selector WAS.
+- `comfyui_generate_styles_llm_py_ml` (impura) — genera N estilos de una categoría vía `ask_llm`.
+- `comfyui_append_styles_py_ml` (impura) — fusiona estilos sobre el `styles.json` WAS (merge+dedup+backup).
+- `comfyui_get_gamedev_style_preset_py_ml` (pura) — receta de *style preset* gamedev (gameboy/ghibli/pixel-art-retro).
+- `comfyui_apply_style_preset_py_ml` (pura) — traduce un preset + subject a los kwargs de un builder gamedev-2d.
+
 ### 05 · video

 - `comfyui_build_img2vid_workflow_py_ml` (pura) — SVD: condicionamiento por CLIP_VISION (sin prompt de texto).
@@ -12,6 +12,13 @@ submit/wait). Una skill no es un workflow: es la *receta* que compila a uno.

 Filtro MCP: `mcp__registry__fn_search query="" tag="comfyui-skill"`.

+> **Tamaño del grupo (al 28/06/2026):** 17 funciones con tag `comfyui-skill` — CRUD de recetas
+> (save/load/list), compilación a workflow (`build_skill_workflow`), inyectores encadenables
+> (`inject_hires_fix`/`inject_multi_lora`, `build_ipadapter_workflow`), bucle de mejora
+> genera→juzga→bump (`generate_with_skill_oneshot` + `update_skill_score` + `bump_skill_version`),
+> export a grafo (`export_skill_template`), mixer de capacidades (`compose_capabilities` +
+> `generate_mixed_oneshot`) y cosecha de Civitai (`extract_recipe_from_png` + `harvest_civitai_skill_oneshot`).
+
 ## Qué es una skill

 Una receta vive en `~/ComfyUI/skills_library/<slug>/` y la manipulan las funciones de este grupo:
@@ -0,0 +1,101 @@
+# ComfyUI Styles — presets y catálogo de estilo
+
+Tag: `comfyui-styles` (+ `gamedev-2d` para los dos presets gamedev). Sub-grupo de
+[`comfyui`](comfyui.md) que añade una **capa de estilo reutilizable** sobre los builders de
+workflow: en vez de repetir a mano los mismos modificadores de cámara/iluminación/render en cada
+prompt, el estilo se trata como un dato curado y reusable.
+
+Dos vertientes complementarias:
+
+- **Catálogo WAS** (`comfyui-styles`): ~190 estilos curados en el formato exacto del selector WAS de
+  ComfyUI (*Prompt Styles Selector* / *Prompt Multiple Styles Selector*), generación de estilos
+  nuevos por LLM, y fusión segura sobre el `styles.json` del usuario.
+- **Style presets gamedev** (`gamedev-2d`): recetas que empaquetan como datos puros el *look* de un
+  juego entero (prefijo/sufijo de prompt, checkpoint, LoRA, negative, tamaño, post-proceso) y se
+  traducen a los kwargs que consume un builder de sujeto del grupo [`gamedev-2d`](gamedev-2d.md).
+
+Filtro MCP: `mcp__registry__fn_search query="" tag="comfyui-styles"` (catálogo WAS) y
+`mcp__registry__fn_search query="style preset" tag="gamedev-2d"` (presets gamedev).
+
+## Funciones del grupo
+
+### Catálogo WAS — dominio `ml` (tag `comfyui-styles`)
+
+| ID | Firma corta | Qué hace |
+|---|---|---|
+| [comfyui_curated_styles_catalog_py_ml](../../python/functions/ml/comfyui_curated_styles_catalog.md) | `curated_styles_catalog(category=None) -> dict` | Catálogo curado (~190 estilos) en el formato exacto `{nombre: {prompt, negative_prompt}}` que consume el selector WAS. Cada `prompt` son modificadores de estilo potentes (cámara, lente, iluminación, render engine, medio artístico, paleta, mood), no descripciones de escena. Filtra por `category`. **Pura**. |
+| [comfyui_generate_styles_llm_py_ml](../../python/functions/ml/comfyui_generate_styles_llm.md) | `generate_styles_llm(category, n=8, prefix='', avoid=None, model='claude-haiku-4-5-20251001') -> dict` | Genera N estilos de una categoría temática usando `ask_llm` (grupo claude-direct, API directa, arranque 0), en el mismo formato `{nombre: {prompt, negative_prompt}}`. `avoid` evita duplicar nombres ya existentes. **Impura** (LLM). |
+| [comfyui_append_styles_py_ml](../../python/functions/ml/comfyui_append_styles.md) | `append_styles(new_styles, styles_path=DEFAULT_STYLES_PATH, overwrite=False, backup=True, dry_run=False) -> dict` | Fusiona (merge + dedup por nombre) un dict de estilos sobre el `styles.json` del selector WAS de forma SEGURA y NO destructiva: preserva todos los existentes (ganan salvo `overwrite=True`), hace backup con timestamp antes de escribir. `dry_run=True` previsualiza sin tocar disco. **Impura** (I/O disco). |
+
+### Style presets gamedev — dominio `ml` (tag `gamedev-2d`)
+
+| ID | Firma corta | Qué hace |
+|---|---|---|
+| [comfyui_get_gamedev_style_preset_py_ml](../../python/functions/ml/comfyui_get_gamedev_style_preset.md) | `get_gamedev_style_preset(name=None) -> dict` | Devuelve la receta de un *style preset* gamedev curado (`gameboy`, `ghibli`, `pixel-art-retro`) o el catálogo de nombres si `name=None`. Un preset empaqueta como DATOS puros el look de un juego entero: `subject_prefix`/`suffix`, `style`, `negative`, checkpoint recomendado, LoRA + strength, `size`, `transparent`, post-proceso. **Pura**. |
+| [comfyui_apply_style_preset_py_ml](../../python/functions/ml/comfyui_apply_style_preset.md) | `apply_style_preset(preset, subject, *, style=None, negative=None) -> dict` | Traduce un *style preset* gamedev (de `get_gamedev_style_preset`) + un `subject` del usuario a lo que necesita un builder de sujeto del grupo gamedev-2d: el subject combinado con el prefijo/sufijo del estilo y los kwargs comunes (`style`, `checkpoint`, `lora`, `lora_strength`, `negative`, resolución) listos para `**spread`. `style`/`negative` permiten override puntual. **Pura**. |
+
+## Ejemplo canónico — generar un estilo, fusionarlo y aplicarlo
+
+Dos flujos típicos: (1) ampliar el catálogo del selector WAS, y (2) usar un preset gamedev para
+generar un asset con look consistente.
+
+### A) Ampliar el catálogo WAS con estilos nuevos por LLM
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join("python", "functions"))
+from ml.comfyui_generate_styles_llm import comfyui_generate_styles_llm
+from ml.comfyui_append_styles import comfyui_append_styles
+
+# 1. Pedir 6 estilos de una categoría. Devuelve el dict {nombre: {prompt, negative_prompt}}
+#    directo (best-effort: {} si el LLM falla).
+nuevos = comfyui_generate_styles_llm("film noir cinematic", n=6, prefix="noir-")
+
+# 2. Previsualizar la fusión (no escribe), luego aplicar con backup.
+if nuevos:
+    print(comfyui_append_styles(nuevos, dry_run=True)["total_after"])   # nº tras fusionar, sin tocar disco
+    res = comfyui_append_styles(nuevos)                                  # backup + merge + dedup + escritura
+    print(res["total_before"], "->", res["total_after"], "añadidos:", len(res["added"]))
+```
+
+### B) Aplicar un style preset gamedev a un sujeto
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join("python", "functions"))
+from ml.comfyui_get_gamedev_style_preset import comfyui_get_gamedev_style_preset
+from ml.comfyui_apply_style_preset import comfyui_apply_style_preset
+from ml.comfyui_build_enemy_creature_workflow import comfyui_build_enemy_creature_workflow
+
+preset = comfyui_get_gamedev_style_preset("gameboy")     # receta pura del look Game Boy
+ap = comfyui_apply_style_preset(preset, "a wizard casting a spell")
+# ap = {subject, builder_kwargs, size, transparent, post, ...} listo para un builder gamedev-2d:
+wf = comfyui_build_enemy_creature_workflow(
+    ap["subject"], size=ap["size"], transparent=ap["transparent"], **ap["builder_kwargs"]
+)
+```
+
+El catálogo curado completo se consulta sin red (devuelve el dict plano directo):
+
+```python
+from ml.comfyui_curated_styles_catalog import comfyui_curated_styles_catalog
+print(comfyui_curated_styles_catalog("__categories__"))  # {'categories': {...}, 'total': 190}
+todos = comfyui_curated_styles_catalog()                  # dict {nombre: {prompt, negative_prompt}}
+print(len(todos), list(todos)[:5])
+```
+
+## Fronteras
+
+- **No genera imágenes**: este sub-grupo produce y gestiona DATOS de estilo (dicts de prompt /
+  negative, presets). Generar el asset es trabajo de los builders del grupo [`comfyui`](comfyui.md)
+  y [`gamedev-2d`](gamedev-2d.md), o de los pipelines oneshot (p.ej.
+  `comfyui_generate_styled_asset_oneshot_py_pipelines`, que compone un preset + un builder + submit).
+- **El catálogo WAS asume el custom node WAS instalado**: `append_styles` escribe sobre el
+  `styles.json` que lee el selector WAS en la UI. Sin ese node, el catálogo sigue siendo usable como
+  dict de modificadores, pero el selector no aparecerá en el grafo.
+- **Los dos presets gamedev (`get`/`apply`) llevan tag `gamedev-2d`**, no `comfyui-styles`: son la
+  vía de estilo para los builders de assets de juego, no para el selector WAS genérico. Se listan
+  aquí por afinidad de capacidad (estilo reutilizable).
+- **Formato exacto**: el dict de estilos es `{nombre: {prompt, negative_prompt}}`. Los prompts son
+  modificadores (cámara/lente/luz/render/medio/paleta/mood), no descripciones de escena — la escena
+  la pone el `subject` del usuario.
@@ -13,6 +13,17 @@ Tag: `comfyui`. Grupo de funciones para controlar [ComfyUI](https://github.com/c

 Filtro MCP: `mcp__registry__fn_search query="" tag="comfyui"`.

+> **Tamaño del grupo (al 28/06/2026):** 126 funciones con tag `comfyui` (63 puras, 50 impuras,
+> 13 pipelines). El grupo se reparte en sub-grupos con página madre propia:
+> [`comfyui-skill`](comfyui-skill.md) (recetas de estilo versionadas),
+> [`comfyui-styles`](comfyui-styles.md) (presets + catálogo de estilo para el selector WAS),
+> [`comfyui-judge`](comfyui-judge.md) (panel de calidad) y
+> [`gamedev-2d`](gamedev-2d.md) (assets 2D para Godot: 47 funciones, 45 de ellas también `comfyui`).
+> Esta página documenta el **núcleo** (lifecycle del server, API HTTP, builders, I/O de workflows,
+> imagen→3D, UI por CDP, audio, templates); los builders específicos de gamedev-2d viven en su
+> propia página. El mapa cross-grupo de capacidades está en
+> [comfyui-overview.md](comfyui-overview.md).
+
 ## Dos caminos, mismo motor

 ```
@@ -44,7 +55,7 @@ El **API format** (dict de nodos numerados que produce `build_txt2img_workflow`
 | ID | Firma corta | Qué hace |
 |---|---|---|
 | [comfyui_build_txt2img_workflow_py_ml](../../python/functions/ml/comfyui_build_txt2img_workflow.md) | `build_txt2img_workflow(ckpt_name, positive, negative='', *, steps, cfg, width, height, seed, ...) -> dict` | Construye el dict del workflow txt2img básico (Checkpoint → CLIPTextEncode×2 + EmptyLatent → KSampler → VAEDecode → SaveImage) en API format. **Pura**. |
-| [comfyui_build_flux_workflow_py_ml](../../python/functions/ml/comfyui_build_flux_workflow.md) | `build_flux_workflow(prompt, *, unet='flux1-schnell-fp8-e4m3fn.safetensors', clip_l, t5xxl, vae='ae.safetensors', width=1024, height=1024, steps=4, guidance=3.5, seed, weight_dtype='fp8_e4m3fn', ...) -> dict` | Builder txt2img para **Flux** (schnell/dev): UNETLoader + DualCLIPLoader (clip_l + t5xxl, type flux) + VAELoader → CLIPTextEncode → FluxGuidance + EmptySD3LatentImage → KSampler (cfg fijo 1.0) → VAEDecode → SaveImage. La guía va por FluxGuidance, no por el cfg. fp8 + ~4 pasos para 8 GB. **Pura**. |
+| [comfyui_build_flux_workflow_py_ml](../../python/functions/ml/comfyui_build_flux_workflow.md) | `build_flux_workflow(prompt, *, variant='schnell', width=1024, height=1024, steps=None, guidance=3.5, seed=0, unet_name=None, clip_l_name='clip_l.safetensors', t5xxl_name='t5xxl_fp8_e4m3fn_scaled.safetensors', vae_name='ae.safetensors', weight_dtype='default', sampler_name='euler', scheduler='simple', ...) -> dict` | Builder txt2img para **Flux** (`variant='schnell'` o `'dev'`): UNETLoader + DualCLIPLoader (clip_l + t5xxl, type flux) + VAELoader → CLIPTextEncode → FluxGuidance + EmptySD3LatentImage → camino custom-advanced (RandomNoise + KSamplerSelect + BasicScheduler → BasicGuider → SamplerCustomAdvanced) → VAEDecode → SaveImage. La guía va por FluxGuidance, no por el cfg. `steps=None` autoselecciona por variante (~4 schnell); `unet_name=None` deduce el checkpoint de la variante; `weight_dtype='default'`. **Pura**. |
 | [comfyui_object_info_py_ml](../../python/functions/ml/comfyui_object_info.md) | `object_info(server='127.0.0.1:8188', node_class=None, timeout) -> dict` | Catálogo de nodos del server: inputs, tipos y enums (lista de checkpoints/samplers visibles). Para validar antes de enviar. Impura. |
 | [comfyui_submit_workflow_py_ml](../../python/functions/ml/comfyui_submit_workflow.md) | `submit_workflow(workflow, server, client_id, timeout) -> dict` | Encola un workflow API format vía POST /prompt; devuelve `prompt_id` + posición en cola. HTTP 400 propaga la validación por nodo. Impura. |
 | [comfyui_wait_result_py_ml](../../python/functions/ml/comfyui_wait_result.md) | `wait_result(prompt_id, server, timeout, poll_interval) -> dict` | Sondea GET /history/{prompt_id} hasta que termina; devuelve los outputs (PNGs con filename/subfolder/type). Impura. |
@@ -207,6 +218,22 @@ un error accionable, sin lanzar.
 | [comfyui_list_templates_py_ml](../../python/functions/ml/comfyui_list_templates.md) | `list_templates(comfyui_python=None, bundle=None, name_filter=None, with_nodes=True, workflows_only=True, limit=0) -> dict` | Lista los templates oficiales con su grafo: nombre, bundle/categoría, path en disco, `n_nodes` y `node_types` (class_types reales, aplanando subgrafos y descartando UUID de instancia). Filtra por bundle/nombre; excluye entradas no-workflow por defecto. Impura (lee disco vía el intérprete de ComfyUI). |
 | [comfyui_extract_template_py_ml](../../python/functions/ml/comfyui_extract_template.md) | `extract_template(name, comfyui_python=None, to_api=False, server='127.0.0.1:8188') -> dict` | Extrae el grafo completo (formato UI) + `class_types` de un template por su `template_id`. `to_api=True` lo convierte a API format vía `comfyui_import_workflow_json` (requiere servidor ComfyUI vivo). Nombre inexistente → `ok=False` con sugerencias cercanas, sin traceback. Impura. |

+### Estilos — presets y catálogo (sub-grupo `comfyui-styles`)
+
+Capa de **estilo reutilizable** sobre los builders: un catálogo curado de ~190 modificadores de
+estilo para el selector WAS (Prompt Styles Selector), generación de estilos por LLM, y *style
+presets* gamedev (gameboy, ghibli, pixel-art-retro) que empaquetan como datos puros el look de un
+juego entero (prefijo/sufijo de prompt, checkpoint, LoRA, negative, tamaño). Página madre dedicada:
+[comfyui-styles.md](comfyui-styles.md). Las 5 funciones:
+
+| ID | Firma corta | Qué hace |
+|---|---|---|
+| [comfyui_curated_styles_catalog_py_ml](../../python/functions/ml/comfyui_curated_styles_catalog.md) | `curated_styles_catalog(category=None) -> dict` | Catálogo curado (~190 estilos) en formato `{nombre: {prompt, negative_prompt}}` para el selector WAS. Cada prompt son modificadores potentes (cámara, lente, iluminación, render, medio, paleta). **Pura**. |
+| [comfyui_generate_styles_llm_py_ml](../../python/functions/ml/comfyui_generate_styles_llm.md) | `generate_styles_llm(category, n=8, prefix='', avoid=None, model='claude-haiku-4-5-...') -> dict` | Genera N estilos nuevos de una categoría temática vía `ask_llm` (grupo claude-direct), en el mismo formato del selector WAS. **Impura**. |
+| [comfyui_append_styles_py_ml](../../python/functions/ml/comfyui_append_styles.md) | `append_styles(new_styles, styles_path=..., overwrite=False, backup=True, dry_run=False) -> dict` | Fusiona (merge + dedup) estilos nuevos sobre el `styles.json` del selector WAS de forma NO destructiva: preserva los existentes (salvo `overwrite`), backup con timestamp. **Impura**. |
+| [comfyui_get_gamedev_style_preset_py_ml](../../python/functions/ml/comfyui_get_gamedev_style_preset.md) | `get_gamedev_style_preset(name=None) -> dict` | Devuelve la receta de un *style preset* gamedev curado (gameboy, ghibli, pixel-art-retro) o el catálogo de nombres si `name=None`. Empaqueta el look como datos puros. **Pura**. |
+| [comfyui_apply_style_preset_py_ml](../../python/functions/ml/comfyui_apply_style_preset.md) | `apply_style_preset(preset, subject, *, style=None, negative=None) -> dict` | Traduce un *style preset* gamedev + un subject del usuario a los kwargs que consume un builder de sujeto del grupo gamedev-2d (subject combinado + `**kwargs` listos para spread). **Pura**. |
+
 ## Ejemplo canónico end-to-end (build → load → tune → queue → resultado)

 Combina API + UI: construyes el workflow por API, lo cargas en la UI del usuario, ajustas el
@@ -11,8 +11,9 @@ Cluster de funciones para producir y mover assets 2D de juego entre **ComfyUI**
 3. **Puente de assets** (CPU): coloca el resultado en un proyecto Godot
   con sus import settings.

-Tag único del grupo: `gamedev-2d` (los 31 builders de workflow + las 5 funciones de
-apoyo de post-proceso y puente). El tag plano `gamedev` quedó deprecado y unificado a
+Tag único del grupo: `gamedev-2d` — **47 funciones**: 36 builders de workflow (31 de
+generación desde texto + 5 de transformación desde una imagen de entrada) + 11 de apoyo
+(post-proceso, puente a Godot, style presets y pipelines one-shot). El tag plano `gamedev` quedó deprecado y unificado a
 `gamedev-2d`. El **runtime de juego C++** (el motor que ejecuta el juego: game loop,
 cámara, input, render por lotes, audio) vive en el grupo hermano `gamedev-engine`.
 Filtro: `mcp__registry__fn_search query="" tag="gamedev-2d"`.
@@ -78,6 +78,21 @@ CheckpointLoaderSimple -> ... -> KSampler -> VAEDecode --IMAGE--+-> SaveImage (f
                                                                 `-> DepthAnythingV2Preprocessor -> SaveImage (depth)
 ```

+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join("python", "functions"))
+from ml.comfyui_build_parallax_background_workflow import comfyui_build_parallax_background_workflow
+
+# Fondo apaisado + su mapa de profundidad, 4 bandas de parallax (función pura, sin red).
+wf = comfyui_build_parallax_background_workflow("forest at dusk, fantasy", layers=4, seed=7)
+
+# El dict API format trae DOS SaveImage: el fondo y el depth map. Encólalo con submit_workflow.
+saves = [n for n in wf.values() if n.get("class_type") == "SaveImage"]
+print(len(saves), "SaveImage (fondo + depth)")   # 2
+```
+
 ## Cuando usarla

 Cuando necesites el fondo de un nivel 2D con scroll parallax y quieras las capas
@@ -5,7 +5,7 @@ lang: py
 domain: ml
 version: "1.0.0"
 purity: impure
-signature: "def comfyui_fetch_civitai_image_meta(image_ref, *, token: str | None = None, timeout: float = 15.0) -> dict"
+signature: "def comfyui_fetch_civitai_image_meta(image_ref, token: str | None = None, timeout: float = 15.0) -> dict"
 description: "Recupera los detalles de generacion de una imagen de Civitai por su id o URL (civitai.com/images/<id>): prompt, prompt negativo, modelo, sampler, steps, cfg, seed, dimensiones, recursos (checkpoint + LoRAs) y nivel NSFW. Es el paso 'entrar al link y observar como lo hicieron'. Usa los endpoints tRPC image.getGenerationData + image.get que consume la propia web de civitai.com, porque la API v1 publica (GET /api/v1/images) hoy devuelve meta=null y un JPEG recomprimido sin workflow embebido. Si la meta trae un workflow ComfyUI embebido (campo comfy) lo devuelve en API format. NO descarga la imagen ni reconstruye workflow: solo lee. Impura: HTTP a civitai.com + subprocess (pass para el token)."
 tags: [comfyui, civitai, replicate, ml, metadata, http, stable-diffusion]
 uses_functions: []
@@ -128,15 +128,15 @@ def _extract_comfy_workflow(meta):
    return {}


-def comfyui_fetch_civitai_image_meta(image_ref, *, token=None, timeout=15.0):
+def comfyui_fetch_civitai_image_meta(image_ref, token=None, timeout=15.0):
    """Recupera los detalles de generación de una imagen de Civitai por id/URL.

    Args:
        image_ref: id numérico de la imagen (int o str), o su URL
            `https://civitai.com/images/<id>` (con o sin query string).
        token: API token de Civitai (header Authorization Bearer). Si None se
-            resuelve de `pass civitai/api-token`. No hardcodear. keyword-only.
-        timeout: timeout HTTP en segundos por petición. keyword-only.
+            resuelve de `pass civitai/api-token`. No hardcodear.
+        timeout: timeout HTTP en segundos por petición.

    Returns:
        dict {ok, image_id, meta, resources, process, comfy_workflow, width,
@@ -5,7 +5,7 @@ lang: py
 domain: ml
 version: "1.0.0"
 purity: impure
-signature: "def comfyui_import_workflow_png(png_path_or_url: str, *, timeout: float = 15.0) -> dict"
+signature: "def comfyui_import_workflow_png(png_path_or_url: str, timeout: float = 15.0) -> dict"
 description: "Extrae el workflow embebido en los chunks de texto de un PNG de ComfyUI. Lee el chunk 'prompt' (API format) y/o 'workflow' (UI graph) de los chunks tEXt/zTXt/iTXt con stdlib (struct, zlib). Acepta path local o URL. Impura: red opcional + lectura de disco."
 tags: [comfyui, ml, import, png, workflow, stable-diffusion]
 uses_functions: []
@@ -14,12 +14,12 @@ import urllib.request
 import zlib


-def comfyui_import_workflow_png(png_path_or_url: str, *, timeout: float = 15.0) -> dict:
+def comfyui_import_workflow_png(png_path_or_url: str, timeout: float = 15.0) -> dict:
    """Devuelve el/los workflow(s) embebido(s) en un PNG de ComfyUI.

    Args:
        png_path_or_url: ruta local de un PNG, o URL http(s) de un PNG.
-        timeout: timeout HTTP en segundos (solo si es URL). keyword-only.
+        timeout: timeout HTTP en segundos (solo si es URL).

    Returns:
        dict {ok, prompt, workflow, format_detected, error}:
@@ -5,7 +5,7 @@ lang: py
 domain: ml
 version: "1.1.0"
 purity: impure
-signature: "def comfyui_interrupt_queue(*, clear_pending: bool = False, server: str = \"127.0.0.1:8188\", timeout: float = 10.0) -> dict"
+signature: "def comfyui_interrupt_queue(clear_pending: bool = False, server: str = \"127.0.0.1:8188\", timeout: float = 10.0) -> dict"
 description: "Corta la generacion en curso de ComfyUI (POST /interrupt) y, si clear_pending=True, vacia ademas la cola de pendientes (POST /queue {\"clear\":true}). Consulta GET /queue al final para reportar queue_remaining. Devuelve {ok, interrupted, cleared, queue_remaining, error}. NO lanza excepcion en fallo de red: degrada a {ok: False, error}. /interrupt corta solo el prompt en ejecucion, no vacia los pendientes salvo clear_pending. Impura: HTTP POST + GET, solo stdlib (urllib, json)."
 tags: [comfyui, ml, queue, interrupt, control, http]
 uses_functions: []
@@ -5,7 +5,7 @@ lang: py
 domain: ml
 version: "1.0.0"
 purity: impure
-signature: "def comfyui_list_skills(*, library_dir: str = None, include_nsfw: bool = False) -> dict"
+signature: "def comfyui_list_skills(library_dir: str = None, include_nsfw: bool = False) -> dict"
 description: "Lista las skills ComfyUI guardadas en la libreria de disco con su metadata de resumen: slug, title, base_workflow, version, score_mean/score_n y nsfw (de provenance.nsfw), mas n_versions. Respeta include_nsfw=False (oculta las NSFW por defecto). Libreria inexistente o vacia -> lista vacia sin error. library_dir default ~/ComfyUI/skills_library."
 error_type: error_go_core
 tags: [comfyui, comfyui-skill, ml, skill, library]
@@ -28,13 +28,12 @@ def _n_versions(skill_dir):
                if f.startswith("v") and f.endswith(".json")])


-def comfyui_list_skills(*, library_dir: str = None, include_nsfw: bool = False) -> dict:
+def comfyui_list_skills(library_dir: str = None, include_nsfw: bool = False) -> dict:
    """Lista las skills de la libreria con su metadata de resumen.

    Args:
-        library_dir: raiz de la libreria. Default `~/ComfyUI/skills_library`. keyword-only.
+        library_dir: raiz de la libreria. Default `~/ComfyUI/skills_library`.
        include_nsfw: si False (default), oculta las skills con `provenance.nsfw == True`.
-            keyword-only.

    Returns:
        dict ``{ok, skills, count, error}`` donde `skills` es una lista de dicts
@@ -5,7 +5,7 @@ lang: py
 domain: ml
 version: "1.0.0"
 purity: impure
-signature: "def comfyui_load_skill(slug: str, *, version=None, library_dir: str = None) -> dict"
+signature: "def comfyui_load_skill(slug: str, version=None, library_dir: str = None) -> dict"
 description: "Lee una receta de skill ComfyUI de la libreria de disco: recipe.json (version actual) o un snapshot versions/vN.json. Hermana inversa de comfyui_save_skill; el round-trip save(recipe)->load(slug) devuelve un dict identico. library_dir default ~/ComfyUI/skills_library. Slug, version o archivo inexistente -> {ok:False} sin lanzar."
 error_type: error_go_core
 tags: [comfyui, comfyui-skill, ml, skill, library]
@@ -36,14 +36,14 @@ def _version_filename(version):
    return None


-def comfyui_load_skill(slug: str, *, version=None, library_dir: str = None) -> dict:
+def comfyui_load_skill(slug: str, version=None, library_dir: str = None) -> dict:
    """Lee la receta de una skill (version actual o un snapshot concreto).

    Args:
        slug: slug de la skill (nombre de su carpeta en la libreria).
        version: si None, lee `recipe.json` (version actual). Si se pasa (int, "1" o
-            "v1"), lee el snapshot `versions/vN.json`. keyword-only.
-        library_dir: raiz de la libreria. Default `~/ComfyUI/skills_library`. keyword-only.
+            "v1"), lee el snapshot `versions/vN.json`.
+        library_dir: raiz de la libreria. Default `~/ComfyUI/skills_library`.

    Returns:
        dict ``{ok, recipe, slug, path, version, error}``. En exito ``ok=True`` y `recipe`
@@ -5,7 +5,7 @@ lang: py
 domain: ml
 version: "1.0.0"
 purity: impure
-signature: "def comfyui_save_skill(recipe: dict, *, library_dir: str = None) -> dict"
+signature: "def comfyui_save_skill(recipe: dict, library_dir: str = None) -> dict"
 description: "Persiste una receta de skill ComfyUI (schema comfyui-skill) en la libreria de disco: valida el schema minimo y escribe <library_dir>/<slug>/recipe.json + un snapshot inmutable versions/vN.json (N incremental) + bitacora growth_log.jsonl + regenera INDEX.md. No muta la receta (round-trip identico con comfyui_load_skill). library_dir default ~/ComfyUI/skills_library. Devuelve dict {ok, slug, path, version_file, n_versions, error}; nunca lanza."
 error_type: error_go_core
 tags: [comfyui, comfyui-skill, ml, skill, library, persistence]
@@ -91,13 +91,13 @@ def _rewrite_index(lib):
        fh.write("\n".join(lines))


-def comfyui_save_skill(recipe: dict, *, library_dir: str = None) -> dict:
+def comfyui_save_skill(recipe: dict, library_dir: str = None) -> dict:
    """Valida y persiste una receta de skill en la libreria de disco.

    Args:
        recipe: dict de la receta (schema `comfyui-skill`). Requiere al menos `slug`,
            `base_workflow` y `version` (strings no vacios). No se muta.
-        library_dir: raiz de la libreria. Default `~/ComfyUI/skills_library`. keyword-only.
+        library_dir: raiz de la libreria. Default `~/ComfyUI/skills_library`.

    Returns:
        dict ``{ok, slug, path, recipe_path, version_file, n_versions, error}``. En error de
@@ -0,0 +1,92 @@
+---
+name: pixeloe_downscale
+kind: function
+lang: py
+domain: ml
+version: "1.0.0"
+purity: impure
+signature: "def pixeloe_downscale(src_path: str, dst_path: str, *, mode: str = 'contrast', target_size: int = 64, patch_size: int = 16, thickness: int = 2, color_matching: bool = True, no_upscale: bool = True, comfy_python: str | None = None) -> dict"
+description: "Downscale contrast-aware (Contrast-Aware Outline Expansion de Kohaku, lib `pixeloe`) que colapsa una ilustracion a un grid de pixel-art pequeno (64 personajes, 32 iconos) conservando contornos/silueta. Es la etapa de downscale del metodo SOTA de pixel-art (report 0215). NO cuantiza la paleta (eso lo hace despues comfyui_pixelize_image). Resuelve el gotcha de que `pixeloe` solo vive en el venv de ComfyUI con un 'bridge' de interprete: si falta en el interprete actual, re-ejecuta su nucleo por subprocess con el python de ComfyUI. No-throw: todo error viaja en `error`. Determinista; impura por I/O de disco + subprocess. Devuelve {ok, out_path, size, mode, target_size, via, error}."
+tags: [comfyui, gamedev-2d, pixelart, ml, pixeloe, downscale, contrast-aware, image, bridge]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_py_core"
+imports: []
+params:
+  - name: src_path
+    desc: "ruta de la imagen de entrada (PNG/JPG/...). Si no existe -> ok=False con error."
+  - name: dst_path
+    desc: "ruta del PNG de salida; se crea el directorio padre si falta."
+  - name: mode
+    desc: "algoritmo de downscale de pixeloe: 'contrast' (SOTA, conserva silueta), 'bicubic', 'nearest', 'center' o 'k-centroid'. keyword-only."
+  - name: target_size
+    desc: "lado del grid resultante en pixeles (64 para personajes, 32 para iconos). keyword-only."
+  - name: patch_size
+    desc: "tamano del patch que pixeloe colapsa por celda del grid. keyword-only."
+  - name: thickness
+    desc: "grosor de la expansion de contorno (outline expansion). keyword-only."
+  - name: color_matching
+    desc: "corrige el color de cada celda contra el original si True. keyword-only."
+  - name: no_upscale
+    desc: "True devuelve el grid real target_size x target_size (lo habitual, para luego cuantizar); False re-escala al tamano original con pixeles duros (preview). keyword-only."
+  - name: comfy_python
+    desc: "ruta a un interprete con `pixeloe` para el bridge cuando el actual no la tiene. Si None: COMFY_PYTHON y luego ~/ComfyUI/.venv/bin/python3. keyword-only."
+output: "dict con ok (bool), out_path (str), size ([w,h] de la imagen escrita), mode (str usado), target_size (int pedido), via ('inproc' si pixeloe estaba en este interprete, 'bridge' si se delego por subprocess) y error (str, vacio si OK). No lanza excepciones."
+tested: true
+tests: [test_golden_downscale_64_or_clean_degrade, test_edge_target_size_32, test_edge_mode_nearest_no_color_matching, test_error_missing_src_no_throw, test_error_no_interpreter_with_pixeloe]
+test_file_path: "python/functions/ml/pixeloe_downscale_test.py"
+file_path: "python/functions/ml/pixeloe_downscale.py"
+---
+
+## Ejemplo
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
+from ml.pixeloe_downscale import pixeloe_downscale
+
+# Colapsa el render del caballero (1024x1024) a un grid de pixel-art 64x64
+# conservando la silueta. NO cuantiza paleta todavia.
+res = pixeloe_downscale(
+    os.path.expanduser("~/ComfyUI/output/pixel_compare/knight_base_00001_.png"),
+    "/tmp/knight_grid64.png",
+    mode="contrast", target_size=64, no_upscale=True,
+)
+# {'ok': True, 'out_path': '/tmp/knight_grid64.png', 'size': [64, 64],
+#  'mode': 'contrast', 'target_size': 64, 'via': 'bridge', 'error': ''}
+
+# Despues: dureza de color (cuantizacion) con la funcion hermana.
+from ml.comfyui_pixelize_image import comfyui_pixelize_image
+comfyui_pixelize_image("/tmp/knight_grid64.png", "/tmp/knight_q16.png",
+                       downscale=1, colors=16, upscale_back=False)
+```
+
+## Cuando usarla
+
+Primera etapa del metodo SOTA de pixel-art: cuando ya tienes una ilustracion (render
+SDXL/Flux, sprite, foto) y quieres reducirla a un grid de pixel-art chico **sin perder
+los contornos** (lo que arruina un resize NEAREST/lanczos normal). Usala **antes** de
+la cuantizacion dura de paleta con `comfyui_pixelize_image` (paso de color). `target_size`
+64 para personajes, 32 para iconos. Si solo necesitas el resize+cuantizado rapido sin
+contornos finos, `comfyui_pixelize_image` sola basta; para el resultado ganador, encadena
+`pixeloe_downscale` -> `comfyui_pixelize_image`.
+
+## Gotchas
+
+- **`pixeloe` solo esta en el venv de ComfyUI** (`~/ComfyUI/.venv`), no en el del registry.
+  La funcion lo resuelve con un *bridge*: si `import pixeloe` falla, re-ejecuta su nucleo
+  por subprocess con el python de ComfyUI. El campo `via` dice si fue `inproc` o `bridge`.
+- **El modulo es `pixeloe.legacy.pixelize`**, no `pixeloe.pixelize` (ruta vieja eliminada).
+- **El nodo `PixelOEPixelize+` de ComfyUI_essentials estaba roto** por ese cambio de import;
+  por eso aqui se llama la lib directa (numpy + PIL, sin cv2).
+- **NO cuantiza la paleta**: el resultado conserva muchos colores; la dureza retro la aplica
+  despues `comfyui_pixelize_image`. No esperes pocos colores en la salida.
+- **No-throw**: src inexistente, pixeloe ausente en todos los interpretes, o subprocess
+  caido -> `ok=False` con `error` explicado, nunca excepcion. El pipeline llamante hace
+  fallback mirando `ok`.
+- Resolucion del interprete del bridge: arg `comfy_python` -> env `COMFY_PYTHON` ->
+  `~/ComfyUI/.venv/bin/python3` (el primero que exista como archivo).
+- `no_upscale=True` (default) devuelve el grid real `target_size x target_size`; con `False`
+  vuelve al tamano original con pixeles duros (preview), no el grid pequeno.
@@ -0,0 +1,322 @@
+"""pixeloe_downscale — downscale contrast-aware a un grid de pixel-art (etapa SOTA).
+
+Colapsa una ilustracion a un grid de pixel-art pequeno (p.ej. 64x64) usando la
+libreria `pixeloe` de Kohaku (Contrast-Aware Outline Expansion), el metodo SOTA
+para preservar contornos/silueta al reducir. Es la etapa de *downscale* del
+metodo ganador de pixel-art (ver report 0215): NO cuantiza la paleta — esa dureza
+de color la aplica despues otra funcion (`comfyui_pixelize_image`).
+
+Gotcha de entorno (resuelto con un "bridge" de interprete): la lib `pixeloe` solo
+esta instalada en el venv de ComfyUI (`~/ComfyUI/.venv`), no en el venv del
+registry, y su modulo vive en `pixeloe.legacy.pixelize` (la ruta vieja
+`pixeloe.pixelize` ya no existe). Por eso la funcion:
+
+  1. Intenta `import pixeloe` en el interprete actual y ejecuta el nucleo directo.
+  2. Si falta (`ModuleNotFoundError`), re-ejecuta este mismo archivo como subprocess
+     (`python pixeloe_downscale.py --bridge <json>`) con un interprete que SI la
+     tenga, parseando la unica linea JSON que ese hijo imprime a stdout.
+  3. Si no hay ningun interprete con pixeloe, devuelve ok=False (sin excepcion);
+     el pipeline que la llama hara fallback.
+
+La funcion es no-throw: cualquier error se captura y viaja en el campo `error`.
+Determinista; impura solo por la lectura/escritura de disco y el subprocess.
+"""
+
+import os
+
+
+def _resolve_comfy_python(comfy_python):
+    """Devuelve el primer interprete candidato que exista como archivo, o None.
+
+    Orden: arg comfy_python -> env COMFY_PYTHON -> ~/ComfyUI/.venv/bin/python3.
+    """
+    candidates = []
+    if comfy_python:
+        candidates.append(comfy_python)
+    env = os.environ.get("COMFY_PYTHON")
+    if env:
+        candidates.append(env)
+    candidates.append(os.path.expanduser("~/ComfyUI/.venv/bin/python3"))
+    for c in candidates:
+        if c and os.path.isfile(c):
+            return c
+    return None
+
+
+def _run_core(src_path, dst_path, mode, target_size, patch_size, thickness,
+              color_matching, no_upscale):
+    """Nucleo no-throw: requiere `pixeloe` importable EN ESTE interprete.
+
+    Lee src como RGB uint8 (numpy + PIL, sin cv2), llama
+    `pixeloe.legacy.pixelize.pixelize` y guarda el resultado como PNG. Devuelve el
+    dict de resultado. NO lanza excepciones: las captura en `error`.
+    """
+    out = {
+        "ok": False,
+        "out_path": "",
+        "size": [0, 0],
+        "mode": mode,
+        "target_size": int(target_size),
+        "via": "inproc",
+        "error": "",
+    }
+
+    try:
+        import numpy as np
+        from PIL import Image
+    except Exception as exc:  # noqa: BLE001 - degradacion limpia, no relanzar
+        out["error"] = f"numpy/PIL no disponible en este interprete: {exc}"
+        return out
+
+    if not os.path.isfile(src_path):
+        out["error"] = f"src_path no existe: {src_path!r}"
+        return out
+
+    try:
+        from pixeloe.legacy.pixelize import pixelize
+    except Exception as exc:  # noqa: BLE001
+        out["error"] = f"no se pudo importar pixeloe.legacy.pixelize: {exc}"
+        return out
+
+    try:
+        img = np.array(Image.open(src_path).convert("RGB"))  # HxWx3 uint8
+    except Exception as exc:  # noqa: BLE001
+        out["error"] = f"no se pudo leer/decodificar {src_path!r}: {exc}"
+        return out
+
+    try:
+        res = pixelize(
+            img,
+            mode=mode,
+            target_size=int(target_size),
+            patch_size=int(patch_size),
+            thickness=int(thickness),
+            contrast=1.0,
+            saturation=1.0,
+            color_matching=bool(color_matching),
+            no_upscale=bool(no_upscale),
+        )
+    except TypeError as exc:
+        # Firma de pixelize distinta a la esperada: reseñar, no relanzar.
+        out["error"] = f"pixelize rechazo los kwargs (firma distinta?): {exc}"
+        return out
+    except Exception as exc:  # noqa: BLE001
+        out["error"] = f"pixelize fallo: {exc}"
+        return out
+
+    try:
+        arr = np.asarray(res)
+        result_img = Image.fromarray(arr)
+        dst_dir = os.path.dirname(os.path.abspath(dst_path))
+        os.makedirs(dst_dir, exist_ok=True)
+        result_img.save(dst_path)
+    except Exception as exc:  # noqa: BLE001
+        out["error"] = f"no se pudo escribir {dst_path!r}: {exc}"
+        return out
+
+    out.update(ok=True, out_path=dst_path, size=list(result_img.size), error="")
+    return out
+
+
+def _run_via_bridge(interp, src_path, dst_path, mode, target_size, patch_size,
+                    thickness, color_matching, no_upscale):
+    """Ejecuta el nucleo en otro interprete (que tiene pixeloe) via subprocess.
+
+    Corre `interp <este_archivo> --bridge <json_args>` y parsea la ultima linea de
+    stdout que sea JSON valido (pixeloe puede emitir ruido antes). No-throw.
+    """
+    import json
+    import subprocess
+
+    out = {
+        "ok": False,
+        "out_path": "",
+        "size": [0, 0],
+        "mode": mode,
+        "target_size": int(target_size),
+        "via": "bridge",
+        "error": "",
+    }
+
+    args = {
+        "src_path": src_path,
+        "dst_path": dst_path,
+        "mode": mode,
+        "target_size": int(target_size),
+        "patch_size": int(patch_size),
+        "thickness": int(thickness),
+        "color_matching": bool(color_matching),
+        "no_upscale": bool(no_upscale),
+    }
+
+    try:
+        proc = subprocess.run(
+            [interp, os.path.abspath(__file__), "--bridge", json.dumps(args)],
+            capture_output=True,
+            text=True,
+            timeout=600,
+        )
+    except Exception as exc:  # noqa: BLE001
+        out["error"] = f"fallo el subprocess bridge ({interp}): {exc}"
+        return out
+
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[-500:]
+        out["error"] = f"bridge salio con codigo {proc.returncode}: {tail}"
+        return out
+
+    # Parsea de atras hacia delante la primera linea que sea JSON valido.
+    parsed = None
+    for ln in reversed((proc.stdout or "").splitlines()):
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            parsed = json.loads(ln)
+            break
+        except Exception:  # noqa: BLE001 - linea de ruido, sigue probando
+            continue
+
+    if parsed is None:
+        tail = (proc.stderr or "").strip()[-300:]
+        out["error"] = f"bridge no produjo salida JSON. stderr: {tail}"
+        return out
+
+    parsed["via"] = "bridge"
+    return parsed
+
+
+def pixeloe_downscale(
+    src_path: str,
+    dst_path: str,
+    *,
+    mode: str = "contrast",
+    target_size: int = 64,
+    patch_size: int = 16,
+    thickness: int = 2,
+    color_matching: bool = True,
+    no_upscale: bool = True,
+    comfy_python: str | None = None,
+) -> dict:
+    """Downscale contrast-aware de una imagen a un grid de pixel-art (no cuantiza).
+
+    Args:
+        src_path: ruta de la imagen de entrada (PNG/JPG/...).
+        dst_path: ruta del PNG de salida (se crea el directorio si falta).
+        mode: algoritmo de downscale de pixeloe: "contrast" (SOTA, conserva
+            silueta), "bicubic", "nearest", "center" o "k-centroid". keyword-only.
+        target_size: lado del grid resultante en pixeles (64 personajes, 32
+            iconos). keyword-only.
+        patch_size: tamano del patch que pixeloe colapsa por celda. keyword-only.
+        thickness: grosor de la expansion de contorno (outline). keyword-only.
+        color_matching: corrige el color de cada celda contra el original si True.
+            keyword-only.
+        no_upscale: True devuelve el grid real target_size x target_size (lo
+            habitual para luego cuantizar); False re-escala al tamano original con
+            pixeles duros (preview). keyword-only.
+        comfy_python: ruta a un interprete con `pixeloe` para el bridge cuando el
+            actual no la tiene. Si None, se prueba COMFY_PYTHON y luego
+            ~/ComfyUI/.venv/bin/python3. keyword-only.
+
+    Returns:
+        dict con:
+        - ok (bool): True si se hizo el downscale y se guardo el PNG.
+        - out_path (str): ruta del PNG generado.
+        - size (list[int]): [w, h] de la imagen escrita.
+        - mode (str): modo de downscale usado.
+        - target_size (int): lado del grid pedido.
+        - via (str): "inproc" si pixeloe estaba en este interprete, "bridge" si se
+          delego a otro interprete por subprocess.
+        - error (str): mensaje de error; cadena vacia si todo OK.
+    """
+    out = {
+        "ok": False,
+        "out_path": "",
+        "size": [0, 0],
+        "mode": mode,
+        "target_size": int(target_size),
+        "via": "",
+        "error": "",
+    }
+
+    try:
+        if not os.path.isfile(src_path):
+            out["error"] = f"src_path no existe: {src_path!r}"
+            return out
+
+        # 1. pixeloe disponible en el interprete actual -> nucleo directo.
+        has_local = True
+        try:
+            import pixeloe  # noqa: F401
+        except ModuleNotFoundError:
+            has_local = False
+        except Exception:  # noqa: BLE001 - pixeloe presente pero roto -> bridge
+            has_local = False
+
+        if has_local:
+            res = _run_core(
+                src_path, dst_path, mode, int(target_size), int(patch_size),
+                int(thickness), bool(color_matching), bool(no_upscale),
+            )
+            res["via"] = "inproc"
+            return res
+
+        # 2. Bridge a un interprete que tenga pixeloe.
+        interp = _resolve_comfy_python(comfy_python)
+        if interp is None:
+            out["error"] = (
+                "pixeloe no disponible: no se encontro ningun interprete con "
+                "pixeloe (pasa comfy_python, define COMFY_PYTHON, o instala "
+                "~/ComfyUI/.venv)"
+            )
+            return out
+
+        return _run_via_bridge(
+            interp, src_path, dst_path, mode, int(target_size), int(patch_size),
+            int(thickness), bool(color_matching), bool(no_upscale),
+        )
+    except Exception as exc:  # noqa: BLE001 - contrato no-throw
+        out["error"] = f"error inesperado: {exc}"
+        return out
+
+
+if __name__ == "__main__":
+    import json
+    import sys
+
+    if "--bridge" in sys.argv:
+        # Modo bridge: ejecuta el nucleo y emite UNA linea JSON a stdout.
+        _idx = sys.argv.index("--bridge")
+        _payload = sys.argv[_idx + 1] if len(sys.argv) > _idx + 1 else "{}"
+        try:
+            _a = json.loads(_payload)
+        except Exception as _exc:  # noqa: BLE001
+            print(json.dumps({
+                "ok": False, "out_path": "", "size": [0, 0], "mode": "",
+                "target_size": 0, "via": "inproc",
+                "error": f"payload --bridge invalido: {_exc}",
+            }))
+            sys.exit(0)
+        _res = _run_core(
+            _a.get("src_path", ""),
+            _a.get("dst_path", ""),
+            _a.get("mode", "contrast"),
+            _a.get("target_size", 64),
+            _a.get("patch_size", 16),
+            _a.get("thickness", 2),
+            _a.get("color_matching", True),
+            _a.get("no_upscale", True),
+        )
+        print(json.dumps(_res))
+        sys.exit(0)
+
+    # Modo CLI normal.
+    if len(sys.argv) < 3:
+        print("uso: pixeloe_downscale.py <src> <dst> [target_size] [mode]",
+              file=sys.stderr)
+        sys.exit(2)
+    _src, _dst = sys.argv[1], sys.argv[2]
+    _ts = int(sys.argv[3]) if len(sys.argv) > 3 else 64
+    _md = sys.argv[4] if len(sys.argv) > 4 else "contrast"
+    print(json.dumps(pixeloe_downscale(_src, _dst, target_size=_ts, mode=_md),
+                     indent=2))
@@ -0,0 +1,122 @@
+"""Tests de pixeloe_downscale — tolerantes al entorno.
+
+El venv del registry NO trae `pixeloe`, asi que estas pruebas ejercitan el
+"bridge" de interprete (subprocess al python de ComfyUI, que si la tiene). Si
+tampoco hay ningun interprete con pixeloe disponible, la funcion debe degradar
+limpiamente: ok=False con error no vacio y SIN lanzar excepcion.
+
+Por eso cada test PASA en los dos escenarios:
+  - pixeloe disponible (inproc o via bridge): assert sobre el resultado real.
+  - pixeloe ausente en todos lados: assert sobre la degradacion no-throw.
+Asi la suite es verde tanto en este PC (ComfyUI presente) como en uno sin ComfyUI,
+y el contrato "no-throw" queda cubierto en ambos.
+"""
+
+import os
+import sys
+
+import numpy as np
+from PIL import Image
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from ml.pixeloe_downscale import pixeloe_downscale  # noqa: E402
+
+
+def _shapes_png(path, w=256, h=256):
+    """PNG 256x256 RGB con un gradiente + formas (contraste con silueta clara)."""
+    yy, xx = np.mgrid[0:h, 0:w]
+    arr = np.zeros((h, w, 3), dtype=np.uint8)
+    arr[..., 0] = (xx * 255 // max(1, w - 1)).astype(np.uint8)   # gradiente rojo
+    arr[..., 1] = (yy * 255 // max(1, h - 1)).astype(np.uint8)   # gradiente verde
+    # Bloque azul central: borde duro para que el modo "contrast" tenga silueta.
+    arr[h // 4:3 * h // 4, w // 4:3 * w // 4, 2] = 255
+    Image.fromarray(arr, "RGB").save(path)
+    return path
+
+
+def test_golden_downscale_64_or_clean_degrade(tmp_path):
+    """Golden: 256x256 -> grid 64x64 (no_upscale). Si pixeloe no esta -> ok=False limpio."""
+    src = _shapes_png(str(tmp_path / "raw.png"))
+    dst = str(tmp_path / "grid64.png")
+    res = pixeloe_downscale(src, dst, target_size=64, no_upscale=True)
+    assert isinstance(res, dict)
+    if res["ok"]:
+        assert os.path.isfile(dst)
+        assert res["size"] == [64, 64]          # no_upscale=True -> grid real
+        assert res["error"] == ""
+        assert res["via"] in ("inproc", "bridge")
+        assert res["mode"] == "contrast"
+        assert res["target_size"] == 64
+    else:
+        # Degradacion limpia: sin pixeloe en ningun interprete.
+        assert res["error"] != ""
+        assert res["via"] in ("", "bridge", "inproc")
+
+
+def test_edge_target_size_32(tmp_path):
+    """Edge: grid de 32 (iconos). size==[32,32] cuando pixeloe esta presente."""
+    src = _shapes_png(str(tmp_path / "raw.png"))
+    dst = str(tmp_path / "grid32.png")
+    res = pixeloe_downscale(src, dst, target_size=32, no_upscale=True)
+    if res["ok"]:
+        assert res["size"] == [32, 32]
+        assert res["target_size"] == 32
+        assert os.path.isfile(dst)
+    else:
+        assert res["error"] != ""
+
+
+def test_edge_mode_nearest_no_color_matching(tmp_path):
+    """Edge: otro modo + color_matching off; debe seguir produciendo el grid o degradar."""
+    src = _shapes_png(str(tmp_path / "raw.png"))
+    dst = str(tmp_path / "near.png")
+    res = pixeloe_downscale(
+        src, dst, mode="nearest", target_size=64,
+        color_matching=False, no_upscale=True,
+    )
+    assert isinstance(res, dict)
+    if res["ok"]:
+        assert res["mode"] == "nearest"
+        assert res["size"] == [64, 64]
+    else:
+        assert res["error"] != ""
+
+
+def test_error_missing_src_no_throw(tmp_path):
+    """Error path: src inexistente -> ok=False, error explica, sin excepcion."""
+    res = pixeloe_downscale(
+        str(tmp_path / "nope.png"), str(tmp_path / "o.png"), target_size=64,
+    )
+    assert res["ok"] is False
+    assert "no existe" in res["error"]
+    assert res["size"] == [0, 0]
+
+
+def test_error_no_interpreter_with_pixeloe(tmp_path):
+    """Error path: forzar comfy_python invalido cuando el actual no tiene pixeloe.
+
+    Si el interprete que corre el test YA tiene pixeloe (inproc), el comfy_python
+    invalido se ignora y la llamada puede salir ok=True; el test sigue siendo
+    valido (no-throw). Si NO lo tiene, no hay ningun interprete con pixeloe y debe
+    devolver ok=False con error, nunca lanzar.
+    """
+    src = _shapes_png(str(tmp_path / "raw.png"))
+    dst = str(tmp_path / "o.png")
+    res = pixeloe_downscale(
+        src, dst, target_size=64, comfy_python="/no/such/python-interpreter",
+    )
+    assert isinstance(res, dict)
+    try:
+        import pixeloe  # noqa: F401
+        has_local = True
+    except Exception:  # noqa: BLE001
+        has_local = False
+    if has_local:
+        # pixeloe en el interprete del test -> ruta inproc, comfy_python ignorado.
+        assert res["ok"] is True
+    else:
+        # comfy_python invalido + env vacio: si ~/ComfyUI/.venv existe, puede
+        # bridgear y salir ok; si no, ok=False con error. Ambos no-throw.
+        assert res["ok"] in (True, False)
+        if not res["ok"]:
+            assert res["error"] != ""
@@ -0,0 +1,131 @@
+---
+name: comfyui_generate_until_quality
+kind: pipeline
+lang: py
+domain: pipelines
+version: "1.0.0"
+purity: impure
+signature: "comfyui_generate_until_quality(builder, subject, *, threshold=6.0, clip_threshold=0.24, max_iters=4, strategy='reroll+escalate+refine_prompt', server='127.0.0.1:8188', dest_dir='~/ComfyUI/output', judge_prompt=None, seed=0, refine_model='claude-haiku-4-5-20251001', judge_model='claude-opus-4-8', wait_timeout=300.0, **builder_kwargs) -> dict"
+description: "Loop evaluator-optimizer (GAN sin entrenar): genera una imagen con un builder del registry, la juzga con el panel multi-juez, y si no alcanza la calidad pedida refina (nueva seed, mas calidad, prompt corregido con el feedback del juez) y regenera hasta pasar el umbral o agotar intentos. Siempre devuelve la mejor candidata por score (best-of-N)."
+tags: [comfyui, comfyui-skill, pipeline, launcher, generate, judge, quality-loop, evaluator-optimizer]
+uses_functions:
+  - comfyui_submit_workflow_py_ml
+  - comfyui_wait_result_py_ml
+  - comfyui_fetch_output_image_py_ml
+  - comfyui_judge_image_py_ml
+  - ask_llm_py_core
+uses_types: []
+returns: []
+returns_optional: false
+error_type: error_py_core
+imports: [comfyui_submit_workflow_py_ml, comfyui_wait_result_py_ml, comfyui_fetch_output_image_py_ml, comfyui_judge_image_py_ml, ask_llm_py_core]
+params:
+  - name: builder
+    desc: "Callable o nombre (str) de un builder comfyui_build_*_workflow del registry. El subject se pasa como primer positional (builders de asset: ui_hud, item_icon, enemy_creature...)."
+  - name: subject
+    desc: "Descripcion del elemento a generar (p.ej. 'RPG health and mana bars'). Se inyecta en el builder y, si se refina, se reescribe con el feedback del juez."
+  - name: threshold
+    desc: "Umbral estetico 0-10 que el juez usa para votar good/bad."
+  - name: clip_threshold
+    desc: "Umbral de fidelidad CLIP 0-1 del juez (prompt<->imagen)."
+  - name: max_iters
+    desc: "Numero maximo de iteraciones de generacion."
+  - name: strategy
+    desc: "Tacticas de mejora separadas por '+': reroll (seed nueva), escalate (mas steps/cfg en iters tardias), refine_prompt (reescribe el subject con ask_llm usando las razones del juez)."
+  - name: server
+    desc: "host:port del servidor ComfyUI sin esquema."
+  - name: dest_dir
+    desc: "Directorio local donde guardar los PNG."
+  - name: judge_prompt
+    desc: "Texto que se pasa al juez para medir fidelidad. None = se extrae el positive del workflow construido."
+  - name: seed
+    desc: "Semilla base; los rerolls derivan de ella de forma determinista."
+  - name: refine_model
+    desc: "Modelo de ask_llm para el refine del prompt (barato, haiku por defecto)."
+  - name: judge_model
+    desc: "Modelo del juez critico LLM-vision."
+  - name: wait_timeout
+    desc: "Segundos maximos esperando cada generacion."
+  - name: builder_kwargs
+    desc: "Parametros extra del builder (ui_style, checkpoint, size, transparent...). Solo se pasan los que el builder acepta (filtrados por inspect.signature)."
+output: "dict {ok, converged, best_image_path, best_score, best_verdict, iterations, error}. iterations = lista de {iter, seed, params, score, verdict, reasons, image, error}. converged=True si alguna iteracion logro verdict 'good'. best_* apuntan a la mejor candidata por score aunque ninguna convergiera."
+file_path: "python/functions/pipelines/comfyui_generate_until_quality.py"
+tested: false
+tests: []
+test_file_path: ""
+---
+
+# comfyui_generate_until_quality
+
+Loop **evaluator-optimizer** sobre ComfyUI: el patrón de una GAN (generador vs.
+discriminador) pero **sin entrenar nada**. Un builder genera una imagen, el panel
+multi-juez (`comfyui_judge_image`) la puntúa, y si no llega al umbral el pipeline
+**refina** (nueva seed, más calidad, prompt corregido con las quejas del juez) y
+regenera, hasta converger (`verdict == 'good'`) o agotar `max_iters`. Devuelve
+**siempre la mejor candidata por score** (best-of-N): nunca basura por agotar
+intentos.
+
+Es la promoción a pipeline one-shot (issue 0087) del bucle de mejora del grupo
+`comfyui-skill`: build → submit → wait → fetch → judge → (refine) → repeat.
+
+## Ejemplo
+
+```python
+import sys, json
+sys.path.insert(0, "python/functions")
+from pipelines.comfyui_generate_until_quality import comfyui_generate_until_quality
+
+res = comfyui_generate_until_quality(
+    "comfyui_build_ui_hud_workflow",                 # builder por nombre
+    "RPG health and mana bars, clean game UI",       # subject
+    ui_style="fantasy game UI, clean vector, high contrast, sharp edges",
+    threshold=6.5, max_iters=3,
+    dest_dir="/tmp/comfy_until_quality", transparent=False, seed=1000,
+)
+print(res["converged"], round(res["best_score"], 2), res["best_verdict"])
+print("scores:", [it["score"] for it in res["iterations"]])  # historial subiendo
+print("mejor imagen:", res["best_image_path"])
+```
+
+```bash
+# Lanzar directo (caso HUD del ejemplo __main__)
+~/fn_registry/python/.venv/bin/python3 \
+  python/functions/pipelines/comfyui_generate_until_quality.py
+```
+
+## Cuando usarla
+
+- Cuando pides un asset (HUD, icono, sprite) y la primera generación sale
+  borrosa/floja y quieres que el sistema **itere solo** hasta una versión usable,
+  en vez de re-tirar seeds a mano.
+- Cuando quieres un **gate de calidad objetivo** que devuelva lo mejor de N
+  intentos rankeado por el panel multi-juez, no la primera que salga.
+- Como bloque del bucle reactivo del grupo `comfyui-skill`: un skill no está
+  "hecho" hasta que su imagen pasa el panel; este pipeline es ese bucle.
+
+## Gotchas
+
+- **Impuro**: red (HTTP a ComfyUI), GPU (generación), disco (PNG), API
+  (juez crítico LLM + refine de prompt). Necesita ComfyUI vivo en `server` y el
+  venv de jueces (`~/ComfyUI/.venv`, ver `comfyui-judge`).
+- **El `subject` se pasa como PRIMER positional del builder**. Vale para los
+  builders de asset (`comfyui_build_ui_hud_workflow`, `_item_icon_`,
+  `_enemy_creature_`...), cuyo primer arg es el elemento. NO para
+  `comfyui_build_txt2img_workflow` (primer arg = `ckpt`): para texto crudo, envuélvelo
+  o pasa un builder de asset.
+- **Filtra kwargs con `inspect.signature`**: solo pasa al builder los que acepta,
+  así `escalate` (sube `steps`/`cfg`) y `reroll` (set `seed`) no rompen entre
+  builders con firmas distintas. Si un builder no expone `steps`/`seed`, esa
+  táctica simplemente no aplica en él.
+- **`escalate` sube `steps`+`cfg`**, no inyecta hires-fix (no todos los builders
+  lo soportan y ui_hud lleva Rembg). Para upscale dedicado, usar
+  `comfyui_build_hires_fix_workflow` como builder.
+- **Degrada con gracia**: si el juez cae (HTTP 429) la imagen se conserva con
+  score 0/verdict 'unknown' y el loop sigue; si una iteración falla en
+  submit/wait/fetch se registra su `error` y se reintenta la siguiente. Solo
+  devuelve `ok=False` si NINGUNA iteración produjo imagen.
+- **VRAM (8GB)**: entre familias de generación, liberar con
+  `POST /free {"unload_models":true,"free_memory":true}` si el juez estético
+  (CLIP+LAION en el venv ComfyUI) compite por VRAM con el checkpoint SD.
+- **Determinista en estructura**: nunca lanza excepción cruda; siempre dict de
+  estado. El refine usa `ask_llm` (best-effort): si falla, mantiene el subject.
@@ -0,0 +1,349 @@
+"""comfyui_generate_until_quality — loop evaluator-optimizer (GAN sin entrenar).
+
+Genera una imagen con un builder del registry, la juzga con el panel multi-juez
+(`comfyui_judge_image`), y si no alcanza la calidad pedida REFINA (nueva seed,
+mas calidad, prompt corregido con el feedback del juez) y regenera, hasta que
+pasa el umbral (`verdict == 'good'`) o se agotan los intentos. Siempre devuelve
+la MEJOR candidata por score (best-of-N): nunca devuelve basura por agotar
+iteraciones.
+
+Es la doctrina del issue 0087 (promover una secuencia repetida a un pipeline
+one-shot) aplicada al bucle de mejora del grupo `comfyui-skill`: build -> submit
+-> wait -> fetch -> judge -> (refine) -> repeat. Compone funciones del registry:
+
+    <builder>_py_ml                       (workflow de nodos en API format)
+    comfyui_submit_workflow_py_ml         (POST /prompt)
+    comfyui_wait_result_py_ml             (poll /history)
+    comfyui_fetch_output_image_py_ml      (GET /view -> disco)
+    comfyui_judge_image_py_ml             (panel estetico + CLIP + critica LLM)
+    ask_llm_py_core                       (refine del prompt con el feedback)
+
+Pipeline impuro: red (HTTP), GPU (generacion), disco (PNG), y API (juez critico
+ refine de prompt). Determinista en estructura: nunca lanza excepcion cruda,
+siempre devuelve un dict de estado.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import os
+import sys
+
+# Importa las funciones del registry (mismo arbol python/functions).
+_FUNCTIONS_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _FUNCTIONS_ROOT not in sys.path:
+    sys.path.insert(0, _FUNCTIONS_ROOT)
+
+from ml.comfyui_fetch_output_image import comfyui_fetch_output_image
+from ml.comfyui_judge_image import comfyui_judge_image
+from ml.comfyui_submit_workflow import comfyui_submit_workflow
+from ml.comfyui_wait_result import comfyui_wait_result
+
+
+# Primo grande para derrochar el espacio de seeds entre rerolls de forma
+# determinista (mismo subject + mismo base_seed -> misma traza de seeds).
+_SEED_STRIDE = 101_117
+
+
+def _resolve_builder(builder):
+    """Devuelve el callable del builder.
+
+    Acepta un callable directo o el nombre de la funcion (string), que se
+    resuelve desde el paquete `ml` (convencion del registry: el modulo se llama
+    igual que la funcion, p.ej. `comfyui_build_ui_hud_workflow`).
+    """
+    if callable(builder):
+        return builder
+    if isinstance(builder, str):
+        mod = importlib.import_module(f"ml.{builder}")
+        return getattr(mod, builder)
+    raise TypeError(
+        f"builder debe ser callable o str (nombre de funcion ml.*), no {type(builder)}"
+    )
+
+
+def _extract_positive_prompt(workflow: dict) -> str:
+    """Extrae el prompt positivo textual del workflow para pasarselo al juez.
+
+    Sigue el input `positive` del KSampler hasta su CLIPTextEncode. Fallback: el
+    CLIPTextEncode con el texto mas largo (heuristica: el positive suele serlo).
+    """
+    if not isinstance(workflow, dict):
+        return ""
+    for node in workflow.values():
+        if not isinstance(node, dict):
+            continue
+        if node.get("class_type") in ("KSampler", "KSamplerAdvanced"):
+            pos = node.get("inputs", {}).get("positive")
+            if isinstance(pos, list) and pos:
+                tgt = workflow.get(str(pos[0]))
+                if isinstance(tgt, dict) and tgt.get("class_type") == "CLIPTextEncode":
+                    txt = tgt.get("inputs", {}).get("text")
+                    if isinstance(txt, str) and txt.strip():
+                        return txt
+    texts = [
+        n["inputs"]["text"]
+        for n in workflow.values()
+        if isinstance(n, dict)
+        and n.get("class_type") == "CLIPTextEncode"
+        and isinstance(n.get("inputs", {}).get("text"), str)
+    ]
+    return max(texts, key=len) if texts else ""
+
+
+def _builder_default(sig: inspect.Signature, name: str, fallback):
+    """Default declarado de un parametro del builder, o el fallback dado."""
+    p = sig.parameters.get(name)
+    if p is None or p.default is inspect.Parameter.empty:
+        return fallback
+    return p.default if isinstance(p.default, (int, float)) else fallback
+
+
+def _refine_subject(subject: str, judge_prompt: str, reasons, model: str) -> str:
+    """Reescribe el subject corrigiendo lo que el juez senalo, via ask_llm.
+
+    Devuelve el subject mejorado (string corto) o el original si el LLM falla.
+    """
+    from core.ask_llm import ask_llm
+
+    complaints = "; ".join(str(r) for r in (reasons or []) if r) or "(sin razones)"
+    system = (
+        "Eres un prompt-engineer de generacion de imagenes. Recibes el SUBJECT de "
+        "una imagen rechazada por un juez de calidad y la lista de quejas del juez. "
+        "Devuelve un SUBJECT mejorado y conciso (una frase, en ingles) que conserve la "
+        "intencion original pero corrija las quejas anadiendo descriptores visuales "
+        "concretos (p.ej. 'clean vector UI, sharp edges, high contrast, crisp lines' "
+        "si era borroso). NO escribas explicaciones, NO uses comillas: responde SOLO "
+        "con el subject mejorado."
+    )
+    user = (
+        f"SUBJECT original: {subject}\n"
+        f"Prompt completo generado: {judge_prompt}\n"
+        f"Quejas del juez: {complaints}\n"
+        "SUBJECT mejorado:"
+    )
+    try:
+        out = ask_llm(user, model=model, system=system, echo=False)
+        out = (out or "").strip().strip('"').strip()
+        return out or subject
+    except Exception:  # noqa: BLE001 — refine es best-effort; nunca rompe el loop.
+        return subject
+
+
+def comfyui_generate_until_quality(
+    builder,
+    subject: str,
+    *,
+    threshold: float = 6.0,
+    clip_threshold: float = 0.24,
+    max_iters: int = 4,
+    strategy: str = "reroll+escalate+refine_prompt",
+    server: str = "127.0.0.1:8188",
+    dest_dir: str = "~/ComfyUI/output",
+    judge_prompt: str | None = None,
+    seed: int = 0,
+    refine_model: str = "claude-haiku-4-5-20251001",
+    judge_model: str = "claude-opus-4-8",
+    wait_timeout: float = 300.0,
+    **builder_kwargs,
+) -> dict:
+    """Genera y refina hasta alcanzar la calidad pedida (o agotar intentos).
+
+    Args:
+        builder: callable o nombre (str) de un builder `comfyui_build_*_workflow`
+            del registry. El `subject` se pasa como PRIMER positional del builder
+            (caso de los builders de asset: ui_hud, item_icon, enemy_creature...,
+            cuyo primer arg es el elemento/sujeto).
+        subject: descripcion del elemento a generar (p.ej. "RPG health and mana
+            bars" para `comfyui_build_ui_hud_workflow`). Se inyecta en el builder
+            y, si se refina, se reescribe con el feedback del juez.
+        threshold: umbral estetico (0-10) que el juez usa para votar good/bad.
+            keyword-only.
+        clip_threshold: umbral de fidelidad CLIP (0-1) del juez. keyword-only.
+        max_iters: numero maximo de iteraciones de generacion. keyword-only.
+        strategy: combinacion de tacticas de mejora separadas por '+':
+            'reroll' (seed nueva cada iter), 'escalate' (mas steps/cfg en iters
+            tardias) y 'refine_prompt' (reescribe el subject con ask_llm usando
+            las razones del juez). keyword-only.
+        server: host:port del servidor ComfyUI (sin esquema). keyword-only.
+        dest_dir: directorio local donde guardar los PNG. keyword-only.
+        judge_prompt: texto que se pasa al juez para medir fidelidad. Si None,
+            se extrae el prompt positivo del workflow construido. keyword-only.
+        seed: semilla base; los rerolls derivan de ella de forma determinista.
+            keyword-only.
+        refine_model: modelo de ask_llm para el refine del prompt (barato).
+        judge_model: modelo del juez critico LLM-vision. keyword-only.
+        wait_timeout: segundos maximos esperando cada generacion. keyword-only.
+        **builder_kwargs: parametros extra del builder (ui_style, checkpoint,
+            size, transparent...). Solo se pasan los que el builder acepta.
+
+    Returns:
+        dict {ok, converged, best_image_path, best_score, best_verdict,
+        iterations, error}. `iterations` es una lista de
+        {iter, seed, params, score, verdict, reasons, image, error}. `converged`
+        True si alguna iteracion logro verdict 'good'. `best_*` apuntan a la
+        candidata de mayor score (aunque ninguna convergiera). Si nada se pudo
+        generar, ok=False y error explica.
+    """
+    parts = {p.strip() for p in str(strategy).split("+") if p.strip()}
+    do_reroll = "reroll" in parts
+    do_escalate = "escalate" in parts
+    do_refine = "refine_prompt" in parts
+
+    try:
+        builder_fn = _resolve_builder(builder)
+    except (ImportError, AttributeError, TypeError) as exc:
+        return {
+            "ok": False, "converged": False, "best_image_path": "",
+            "best_score": None, "best_verdict": "", "iterations": [],
+            "error": f"no se pudo resolver el builder: {exc}",
+        }
+
+    sig = inspect.signature(builder_fn)
+    accepts = set(sig.parameters)
+    base_steps = builder_kwargs.get("steps", _builder_default(sig, "steps", 28))
+    base_cfg = builder_kwargs.get("cfg", _builder_default(sig, "cfg", 7.0))
+    prefix = builder_kwargs.get("filename_prefix", "until_quality")
+
+    dest = os.path.expanduser(dest_dir)
+    subject_cur = subject
+    iterations: list[dict] = []
+    best: dict | None = None
+    converged = False
+
+    for i in range(max(1, int(max_iters))):
+        # --- parametros de esta iteracion segun la estrategia ---
+        cur_seed = (seed + i * _SEED_STRIDE) if do_reroll else seed
+        kw = dict(builder_kwargs)
+        if "seed" in accepts:
+            kw["seed"] = cur_seed
+        if do_escalate and i > 0:
+            if "steps" in accepts:
+                kw["steps"] = int(base_steps) + i * 8  # mas pasos = mas nitidez
+            if "cfg" in accepts:
+                kw["cfg"] = round(min(float(base_cfg) + i * 0.5, 12.0), 2)
+        if "filename_prefix" in accepts:
+            kw["filename_prefix"] = f"{prefix}_i{i}"
+        # Solo pasamos kwargs que el builder acepta (evita TypeError entre builders).
+        kw = {k: v for k, v in kw.items() if k in accepts}
+        params = {
+            "seed": cur_seed,
+            "steps": kw.get("steps", base_steps),
+            "cfg": kw.get("cfg", base_cfg),
+            "subject": subject_cur,
+        }
+
+        rec = {"iter": i, "seed": cur_seed, "params": params, "score": None,
+               "verdict": "", "reasons": [], "image": "", "error": ""}
+
+        # --- build ---
+        try:
+            workflow = builder_fn(subject_cur, **kw)
+        except Exception as exc:  # noqa: BLE001 — registra y reintenta siguiente iter.
+            rec["error"] = f"build fallo: {exc}"
+            iterations.append(rec)
+            continue
+
+        jp = judge_prompt if judge_prompt else _extract_positive_prompt(workflow)
+
+        # --- submit ---
+        try:
+            sub = comfyui_submit_workflow(workflow, server=server)
+            prompt_id = sub["prompt_id"]
+        except (RuntimeError, KeyError) as exc:
+            rec["error"] = f"submit fallo: {exc}"
+            iterations.append(rec)
+            continue
+
+        # --- wait ---
+        try:
+            outputs = comfyui_wait_result(prompt_id, server=server, timeout=wait_timeout)
+        except (TimeoutError, RuntimeError) as exc:
+            rec["error"] = f"wait fallo: {exc}"
+            iterations.append(rec)
+            continue
+
+        # --- localizar el PNG ---
+        img = None
+        for node_out in outputs.values():
+            images = node_out.get("images") if isinstance(node_out, dict) else None
+            if images:
+                img = images[0]
+                break
+        if img is None:
+            rec["error"] = f"el workflow no produjo imagenes (outputs={list(outputs)})"
+            iterations.append(rec)
+            continue
+
+        # --- fetch ---
+        fetched = comfyui_fetch_output_image(
+            img["filename"], subfolder=img.get("subfolder", ""),
+            type_=img.get("type", "output"), server=server, dest_dir=dest,
+        )
+        if not fetched.get("ok"):
+            rec["error"] = f"fetch fallo: {fetched.get('error')}"
+            iterations.append(rec)
+            continue
+        rec["image"] = fetched["path"]
+
+        # --- judge (degrada con gracia si un juez cae) ---
+        try:
+            verdict = comfyui_judge_image(
+                fetched["path"], jp, threshold=threshold,
+                clip_threshold=clip_threshold, server=server, model=judge_model,
+            )
+        except Exception as exc:  # noqa: BLE001 — un juez caido no debe tumbar el loop.
+            verdict = {"ok": False, "verdict": "unknown", "score": 0.0,
+                       "reasons": [f"juez no disponible: {exc}"]}
+
+        rec["score"] = float(verdict.get("score") or 0.0)
+        rec["verdict"] = verdict.get("verdict", "unknown")
+        rec["reasons"] = list(verdict.get("reasons") or [])
+        iterations.append(rec)
+
+        # --- best-of-N: guarda siempre la mejor por score ---
+        if best is None or rec["score"] > best["score"]:
+            best = rec
+
+        # --- convergencia ---
+        if rec["verdict"] == "good":
+            converged = True
+            break
+
+        # --- refine para la siguiente iteracion ---
+        if do_refine and i < max_iters - 1:
+            subject_cur = _refine_subject(subject_cur, jp, rec["reasons"], refine_model)
+
+    if best is None:
+        last_err = iterations[-1]["error"] if iterations else "sin iteraciones"
+        return {
+            "ok": False, "converged": False, "best_image_path": "",
+            "best_score": None, "best_verdict": "", "iterations": iterations,
+            "error": f"ninguna iteracion produjo imagen ({last_err})",
+        }
+
+    return {
+        "ok": True,
+        "converged": converged,
+        "best_image_path": best["image"],
+        "best_score": best["score"],
+        "best_verdict": best["verdict"],
+        "iterations": iterations,
+        "error": "",
+    }
+
+
+if __name__ == "__main__":
+    import json
+
+    res = comfyui_generate_until_quality(
+        "comfyui_build_ui_hud_workflow",
+        "RPG health and mana bars, clean game UI",
+        ui_style="fantasy game UI, clean vector, high contrast",
+        threshold=6.5,
+        max_iters=3,
+        dest_dir="/tmp/comfy_until_quality",
+        transparent=False,
+    )
+    print(json.dumps(res, indent=2))
@@ -0,0 +1,133 @@
+---
+name: comfyui_pixelart_real_oneshot
+kind: pipeline
+lang: py
+domain: pipelines
+version: "1.0.0"
+purity: impure
+signature: "def comfyui_pixelart_real_oneshot(subject: str, *, size: int = 64, colors: int = 16, engine: str = \"pixeloe\", palette=None, server: str = \"127.0.0.1:8188\", dest_dir: str = \"~/ComfyUI/output\", seed: int = 0, negative: str | None = None, mode: str = \"contrast\", patch_size: int = 16, thickness: int = 2, fill_frame: bool = True, upscale_preview: int = 512, keep_base: bool = True, comfy_python: str | None = None, wait_timeout: float = 300.0, filename_prefix: str = \"pixelart_real\", **gen_kwargs) -> dict"
+description: "Pipeline one-shot prompt de texto -> sprite pixel-art REAL (grid duro + paleta limitada) en disco. Materializa el metodo ganador del report 0215: generar a alta-res con SDXL + LoRA SDXL_pixel-art, downscale contrast-aware con PixelOE (engine=pixeloe, sprites) o nearest (tiles), y cuantizacion dura con comfyui_pixelize_image (16 colores libres o paleta fija pico-8/nes/game-boy). Sweet-spot 64px personajes, 32px iconos. Fallback automatico pixeloe->nearest. Compone build_pixelart + submit + wait + fetch + pixeloe_downscale + pixelize_image. Impuro: HTTP + disco."
+tags: [comfyui, gamedev-2d, pixelart, pipelines, sprite, launcher]
+uses_functions: [comfyui_build_pixelart_workflow_py_ml, comfyui_submit_workflow_py_ml, comfyui_wait_result_py_ml, comfyui_fetch_output_image_py_ml, pixeloe_downscale_py_ml, comfyui_pixelize_image_py_ml]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: error_py_core
+imports: [comfyui_build_pixelart_workflow_py_ml, comfyui_submit_workflow_py_ml, comfyui_wait_result_py_ml, comfyui_fetch_output_image_py_ml, pixeloe_downscale_py_ml, comfyui_pixelize_image_py_ml]
+params:
+  - name: subject
+    desc: "Prompt positivo (lo que se quiere ver: 'pixel art knight, full body, side view'). No puede estar vacio."
+  - name: size
+    desc: "Lado del grid final en pixeles. 64 personajes/sprites, 32 iconos/objetos simples. keyword-only."
+  - name: colors
+    desc: "Numero de colores de la paleta libre (MEDIANCUT) cuando palette es None. keyword-only."
+  - name: engine
+    desc: "'pixeloe' (downscale contrast-aware, sujetos con silueta) o 'nearest' (downscale simple, tiles/texturas). Fallback automatico a nearest si pixeloe falla. keyword-only."
+  - name: palette
+    desc: "None (paleta libre a `colors`), nombre builtin ('pico-8', 'nes', 'game-boy') o lista de hex. Una paleta fija ignora `colors`. keyword-only."
+  - name: server
+    desc: "host:port del servidor ComfyUI (sin esquema). keyword-only."
+  - name: dest_dir
+    desc: "Directorio donde guardar los PNG (se expande ~). keyword-only."
+  - name: seed
+    desc: "Semilla del KSampler. keyword-only."
+  - name: negative
+    desc: "Prompt negativo; None usa el default de build_pixelart (evita blur/gradientes/anti-alias). keyword-only."
+  - name: mode
+    desc: "Modo de downscale de PixelOE ('contrast' SOTA, 'k-centroid', 'nearest', 'center', 'bicubic'); solo con engine='pixeloe'. keyword-only."
+  - name: patch_size
+    desc: "Tamano de patch de PixelOE (default 16). keyword-only."
+  - name: thickness
+    desc: "Grosor del outline expansion de PixelOE (default 2). keyword-only."
+  - name: fill_frame
+    desc: "Si True anade un hint de encuadre al subject para que el sujeto llene el frame (mejor detalle por pixel tras el downscale). keyword-only."
+  - name: upscale_preview
+    desc: "Si > 0 escribe ademas un PNG re-escalado nearest a ese lado (preview con pixeles duros, p.ej. 512). 0 lo desactiva. keyword-only."
+  - name: keep_base
+    desc: "Si True conserva el PNG base de alta resolucion; si False lo borra tras pixelizar. keyword-only."
+  - name: comfy_python
+    desc: "Ruta al interprete de ComfyUI (con la lib pixeloe); None autodetecta. keyword-only."
+  - name: wait_timeout
+    desc: "Segundos maximos esperando al server. keyword-only."
+  - name: filename_prefix
+    desc: "Prefijo de los archivos de salida. keyword-only."
+  - name: gen_kwargs
+    desc: "Params extra para comfyui_build_pixelart_workflow (width, height, ckpt_name, lora_strength, use_lcm, steps, cfg, ...). keyword-only (**gen_kwargs)."
+output: "dict {ok, out_path, out_path_upscaled, base_path, size, colors_final, engine_used, prompt_id, error}. out_path = PNG final size x size; out_path_upscaled = preview re-escalado; engine_used refleja el fallback (pixeloe->nearest). Si falla, ok=False y error explica en que paso. No-throw."
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/pipelines/comfyui_pixelart_real_oneshot.py"
+---
+
+## Ejemplo
+
+```bash
+# Personaje 64px, 16 colores, motor pixeloe (sprites con silueta).
+./fn run comfyui_pixelart_real_oneshot "pixel art knight, full body, side view, game sprite"
+```
+
+```python
+import sys, os
+sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
+from pipelines.comfyui_pixelart_real_oneshot import comfyui_pixelart_real_oneshot
+
+# (a) Personaje 64px, paleta libre 16 colores, PixelOE contrast.
+res = comfyui_pixelart_real_oneshot(
+    "pixel art knight, full body, side view, game sprite",
+    size=64, colors=16, engine="pixeloe", seed=42,
+    dest_dir="~/ComfyUI/output",
+)
+print(res["out_path"], res["colors_final"], res["engine_used"])  # ~16 colores, pixeloe
+
+# (b) Icono 32px de un item.
+res = comfyui_pixelart_real_oneshot(
+    "pixel art sword icon, single object",
+    size=32, colors=16, engine="pixeloe", seed=7,
+)
+
+# (c) Tile sin silueta -> nearest (mas barato) + paleta fija PICO-8.
+res = comfyui_pixelart_real_oneshot(
+    "pixel art grass texture tile, top down, seamless",
+    size=64, engine="nearest", palette="pico-8", fill_frame=False,
+)
+```
+
+## Cuando usarla
+
+Cuando quieres pixel-art **de verdad** (grid duro + paleta limitada, verificable
+por conteo de colores), no la salida cruda de la difusion (que parece pixelada
+pero tiene decenas de miles de colores y bordes con anti-aliasing). Una sola
+llamada hace generar -> downscale -> cuantizar. Usa `engine="pixeloe"` para
+personajes/criaturas/iconos con silueta (conserva el contorno) y
+`engine="nearest"` para tiles/texturas/fondos sin contorno (mas barato, CPU puro).
+64px es el sweet-spot de personajes; 32px solo para iconos/objetos simples.
+
+## Gotchas
+
+- Impuro: requiere el **servidor ComfyUI vivo** en `server` (default
+  `127.0.0.1:8188`) y los modelos instalados (SDXL Juggernaut + LoRA
+  `SDXL_pixel-art` + `SDXL_lcm-lora`). Si esta caido, falla en submit con
+  `ok=False` y el error de conexion (nunca lanza).
+- `engine="pixeloe"` necesita la lib `pixeloe`, que vive en el venv de ComfyUI
+  (no en el del registry). `pixeloe_downscale` hace el puente de interprete
+  automaticamente; si no la encuentra, el pipeline **cae a `nearest`** y lo
+  reporta en `engine_used` + `error` (no aborta).
+- El nodo `PixelOEPixelize+` de ComfyUI_essentials estaba **roto** por un import
+  obsoleto (`pixeloe.pixelize` -> ahora `pixeloe.legacy.pixelize`); por eso el
+  pipeline usa la lib directa via `pixeloe_downscale`, no el nodo del server.
+- `dest_dir` es un **directorio** (se crea si no existe). Los nombres de salida
+  son `<prefix>_<size>px_<engine>_<paleta|qN>.png` y `..._up.png` (preview).
+- Una **paleta fija** (`pico-8`/`nes`/`game-boy`/lista hex) ignora `colors` y
+  puede dar menos colores que `colors` si el sujeto no cubre toda la paleta.
+- Encuadre: si el sujeto ocupa poca area del frame, a 64/32px queda diminuto.
+  `fill_frame=True` (default) empuja al sujeto a llenar el frame; aun asi, para
+  sprites conviene un subject que pida "full body, centered".
+- No reintenta el sampler: para mejor toma, varia `seed`.
+
+## Capability growth log
+
+- v1.0.0 (2026-06-28) — pipeline inicial. Materializa el metodo ganador del
+  report 0215 (PixelOE contrast downscale -> cuantizacion dura). Compone
+  build_pixelart + submit + wait + fetch + pixeloe_downscale + pixelize_image
+  (issue 0087).
@@ -0,0 +1,312 @@
+"""comfyui_pixelart_real_oneshot — prompt de texto -> sprite pixel-art REAL en disco.
+
+Pipeline one-shot (issue 0087) que materializa el metodo ganador de la
+investigacion (report 0215): la difusion NO sabe pintar pixel-perfect (su salida
+tiene decenas de miles de colores y bordes con anti-aliasing — pixel-art FALSO),
+asi que el pixel-art de verdad es siempre post-proceso en dos ejes: colapsar a un
+grid duro y limitar la paleta. El metodo ganador combina:
+
+  1. Generar a alta resolucion con el look pixel-art (SDXL Juggernaut + LoRA
+     SDXL_pixel-art), via comfyui_build_pixelart_workflow.
+  2. Downscale contrast-aware con PixelOE (pixeloe_downscale): elige el pixel mas
+     representativo de cada zona y engrosa contornos -> silueta legible. Es lo que
+     distingue un sprite reconocible de una mancha. Solo para sujetos con silueta
+     (engine="pixeloe"); para tiles/texturas sin contorno, un downscale nearest
+     simple basta (engine="nearest") y es mas barato.
+  3. Cuantizacion dura con comfyui_pixelize_image (downscale=1): clava la paleta
+     exacta (N colores libres MEDIANCUT, o paleta fija pico-8 / nes / game-boy)
+     sobre el grid ya hecho -> 16 colores exactos + 100% grid duro.
+
+Resultado del combo verificado por PIL: grid duro perfecto + paleta limitada +
+outline nitido. Sweet-spot: 64px personajes/sprites, 32px iconos/objetos simples.
+
+Compone funciones del registry, no reescribe su logica:
+    comfyui_build_pixelart_workflow_py_ml  (workflow SDXL + LoRA pixel-art)
+    comfyui_submit_workflow_py_ml          (POST /prompt)
+    comfyui_wait_result_py_ml              (poll /history)
+    comfyui_fetch_output_image_py_ml       (GET /view -> disco, imagen base)
+    pixeloe_downscale_py_ml                (downscale contrast-aware, engine pixeloe)
+    comfyui_pixelize_image_py_ml           (cuantizacion dura + nearest fallback)
+
+Pipeline impuro: red (HTTP a ComfyUI) + escritura en disco. No-throw: cualquier
+fallo se captura y se devuelve en el dict de estado (campo error).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Importa las funciones del registry (mismo arbol python/functions).
+_FUNCTIONS_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if _FUNCTIONS_ROOT not in sys.path:
+    sys.path.insert(0, _FUNCTIONS_ROOT)
+
+from ml.comfyui_build_pixelart_workflow import comfyui_build_pixelart_workflow
+from ml.comfyui_fetch_output_image import comfyui_fetch_output_image
+from ml.comfyui_pixelize_image import comfyui_pixelize_image
+from ml.comfyui_submit_workflow import comfyui_submit_workflow
+from ml.comfyui_wait_result import comfyui_wait_result
+from ml.pixeloe_downscale import pixeloe_downscale
+
+# Sufijo de encuadre: empuja al sujeto a llenar el frame para que tras el
+# downscale conserve detalle por pixel (gotcha del report: un sujeto que ocupa el
+# 25% del frame queda diminuto a 64px). Solo se anade si no esta ya presente.
+_FRAME_HINT = "full body, centered, fills frame, no margins"
+
+
+def _frame_subject(subject: str, fill_frame: bool) -> str:
+    """Anade el hint de encuadre al subject si fill_frame y no esta ya."""
+    if not fill_frame:
+        return subject
+    low = subject.lower()
+    if "fills frame" in low or "full body" in low or "centered" in low:
+        return subject
+    return f"{subject}, {_FRAME_HINT}"
+
+
+def comfyui_pixelart_real_oneshot(
+    subject: str,
+    *,
+    size: int = 64,
+    colors: int = 16,
+    engine: str = "pixeloe",
+    palette=None,
+    server: str = "127.0.0.1:8188",
+    dest_dir: str = "~/ComfyUI/output",
+    seed: int = 0,
+    negative: str | None = None,
+    mode: str = "contrast",
+    patch_size: int = 16,
+    thickness: int = 2,
+    fill_frame: bool = True,
+    upscale_preview: int = 512,
+    keep_base: bool = True,
+    comfy_python: str | None = None,
+    wait_timeout: float = 300.0,
+    filename_prefix: str = "pixelart_real",
+    **gen_kwargs,
+) -> dict:
+    """Genera un sprite pixel-art REAL desde un prompt de texto, end-to-end.
+
+    Args:
+        subject: prompt positivo (lo que se quiere ver: "pixel art knight, full
+            body, side view", etc.). No puede estar vacio.
+        size: lado del grid final en pixeles (64 personajes/sprites, 32 iconos).
+            keyword-only.
+        colors: numero de colores de la paleta libre cuando palette es None
+            (cuantizacion MEDIANCUT). keyword-only.
+        engine: "pixeloe" (downscale contrast-aware, para sujetos con silueta:
+            personajes/criaturas/iconos) o "nearest" (downscale nearest simple,
+            mas barato, para tiles/texturas/fondos sin contorno). Si "pixeloe"
+            falla o la lib no esta disponible, cae automaticamente a "nearest" y
+            lo reporta en engine_used. keyword-only.
+        palette: None (paleta libre a `colors`), nombre builtin ("pico-8", "nes",
+            "game-boy") o lista de hex. Una paleta fija ignora `colors`.
+            keyword-only.
+        server: host:port del servidor ComfyUI (sin esquema). keyword-only.
+        dest_dir: directorio donde guardar los PNG (se expande ~). keyword-only.
+        seed: semilla del KSampler. keyword-only.
+        negative: prompt negativo; None usa el default de build_pixelart
+            (evita blur/gradientes/anti-alias). keyword-only.
+        mode: modo de downscale de PixelOE ("contrast" SOTA, "k-centroid",
+            "nearest", "center", "bicubic"); solo aplica con engine="pixeloe".
+            keyword-only.
+        patch_size: tamano de patch de PixelOE (default 16). keyword-only.
+        thickness: grosor del outline expansion de PixelOE (default 2).
+            keyword-only.
+        fill_frame: si True, anade un hint de encuadre al subject para que el
+            sujeto llene el frame (mejor detalle por pixel tras el downscale).
+            keyword-only.
+        upscale_preview: si > 0, escribe ademas un PNG re-escalado nearest a
+            ese lado (preview con pixeles duros, p.ej. 512). 0 lo desactiva.
+            keyword-only.
+        keep_base: si True conserva el PNG base de alta resolucion; si False lo
+            borra tras pixelizar. keyword-only.
+        comfy_python: ruta al interprete de ComfyUI (con la lib pixeloe); None
+            autodetecta. keyword-only.
+        wait_timeout: segundos maximos esperando al server. keyword-only.
+        filename_prefix: prefijo de los archivos de salida. keyword-only.
+        **gen_kwargs: params extra para comfyui_build_pixelart_workflow
+            (width, height, ckpt_name, lora_strength, use_lcm, steps, cfg, ...).
+
+    Returns:
+        dict con:
+        - ok (bool): True si se produjo el PNG final pixelizado.
+        - out_path (str): ruta del PNG final size x size.
+        - out_path_upscaled (str): ruta del preview re-escalado, o "" si off.
+        - base_path (str): ruta del PNG base de alta resolucion (o "" si se borro).
+        - size (int): lado real del PNG final.
+        - colors_final (int): numero de colores distintos en el resultado.
+        - engine_used (str): "pixeloe" o "nearest" (refleja el fallback).
+        - prompt_id (str): id del trabajo en ComfyUI.
+        - error (str): mensaje de error; vacio si OK.
+    """
+    out = {
+        "ok": False, "out_path": "", "out_path_upscaled": "", "base_path": "",
+        "size": int(size), "colors_final": 0, "engine_used": engine,
+        "prompt_id": "", "error": "",
+    }
+
+    if not subject or not subject.strip():
+        out["error"] = "subject vacio"
+        return out
+    if int(size) < 1:
+        out["error"] = f"size debe ser >= 1, recibido {size!r}"
+        return out
+    if engine not in ("pixeloe", "nearest"):
+        out["error"] = f"engine invalido: {engine!r} (usa 'pixeloe' o 'nearest')"
+        return out
+
+    dest = os.path.expanduser(dest_dir)
+    try:
+        os.makedirs(dest, exist_ok=True)
+    except OSError as exc:
+        out["error"] = f"no se pudo crear dest_dir {dest!r}: {exc}"
+        return out
+
+    # --- Fase 1: generar la imagen base de alta resolucion (look pixel-art) ---
+    positive = _frame_subject(subject, fill_frame)
+    try:
+        if negative is None:
+            workflow = comfyui_build_pixelart_workflow(
+                positive, seed=seed, filename_prefix=f"{filename_prefix}_base",
+                **gen_kwargs,
+            )
+        else:
+            workflow = comfyui_build_pixelart_workflow(
+                positive, negative, seed=seed,
+                filename_prefix=f"{filename_prefix}_base", **gen_kwargs,
+            )
+    except (ValueError, TypeError) as exc:
+        out["error"] = f"build workflow fallo: {exc}"
+        return out
+
+    try:
+        sub = comfyui_submit_workflow(workflow, server=server)
+        prompt_id = sub["prompt_id"]
+        out["prompt_id"] = prompt_id
+    except (RuntimeError, KeyError, OSError) as exc:
+        out["error"] = f"submit fallo (server {server} responde?): {exc}"
+        return out
+
+    try:
+        outputs = comfyui_wait_result(prompt_id, server=server, timeout=wait_timeout)
+    except (TimeoutError, RuntimeError, OSError) as exc:
+        out["error"] = f"wait fallo: {exc}"
+        return out
+
+    img = None
+    for node_out in outputs.values():
+        images = node_out.get("images") if isinstance(node_out, dict) else None
+        if images:
+            img = images[0]
+            break
+    if img is None:
+        out["error"] = f"el workflow no produjo imagenes (outputs={list(outputs)})"
+        return out
+
+    fetched = comfyui_fetch_output_image(
+        img["filename"], subfolder=img.get("subfolder", ""),
+        type_=img.get("type", "output"), server=server, dest_dir=dest,
+    )
+    if not fetched.get("ok"):
+        out["error"] = f"fetch de imagen base fallo: {fetched.get('error')}"
+        return out
+    base_path = fetched["path"]
+    out["base_path"] = base_path
+
+    # --- Fase 2a: downscale a un grid `size` x `size` (mid). ---
+    mid_path = os.path.join(dest, f"{filename_prefix}_{size}px_mid.png")
+    engine_used = engine
+
+    if engine == "pixeloe":
+        ds = pixeloe_downscale(
+            base_path, mid_path, mode=mode, target_size=int(size),
+            patch_size=patch_size, thickness=thickness, no_upscale=True,
+            comfy_python=comfy_python,
+        )
+        if not ds.get("ok"):
+            # Fallback limpio: PixelOE no disponible / fallo -> nearest.
+            engine_used = "nearest"
+            out["error"] = (
+                f"pixeloe fallo ({ds.get('error')}); fallback a nearest"
+            )
+
+    if engine_used == "nearest":
+        # Downscale nearest simple a size x size (PIL en el venv del registry).
+        try:
+            from PIL import Image
+            with Image.open(base_path) as src:
+                small = src.convert("RGB").resize((int(size), int(size)), Image.NEAREST)
+                small.save(mid_path)
+        except (ImportError, OSError) as exc:
+            out["error"] = f"downscale nearest fallo: {exc}"
+            return out
+
+    if not os.path.isfile(mid_path):
+        out["error"] = "no se genero la imagen intermedia (mid)"
+        return out
+
+    # --- Fase 2b: cuantizacion dura (paleta exacta) sobre el grid ya hecho. ---
+    final_tag = palette if isinstance(palette, str) else f"q{colors}"
+    final_path = os.path.join(
+        dest, f"{filename_prefix}_{size}px_{engine_used}_{final_tag}.png"
+    )
+    quant = comfyui_pixelize_image(
+        mid_path, final_path, downscale=1, colors=int(colors),
+        palette=palette, upscale_back=False,
+    )
+    if not quant.get("ok"):
+        out["error"] = f"cuantizacion fallo: {quant.get('error')}"
+        return out
+
+    out["out_path"] = final_path
+    out["size"] = quant["size"][0] if quant.get("size") else int(size)
+    out["colors_final"] = quant.get("n_colors_final", 0)
+    out["engine_used"] = engine_used
+
+    # --- Fase 3 (opcional): preview re-escalado nearest a pixeles duros. ---
+    if int(upscale_preview) > 0:
+        up_path = os.path.join(
+            dest, f"{filename_prefix}_{size}px_{engine_used}_{final_tag}_up.png"
+        )
+        try:
+            from PIL import Image
+            with Image.open(final_path) as fin:
+                up = fin.convert("RGB").resize(
+                    (int(upscale_preview), int(upscale_preview)), Image.NEAREST
+                )
+                up.save(up_path)
+            out["out_path_upscaled"] = up_path
+        except (ImportError, OSError) as exc:
+            # El preview es opcional: no invalida el resultado.
+            out["out_path_upscaled"] = ""
+            if not out["error"]:
+                out["error"] = f"preview upscale fallo (no critico): {exc}"
+
+    # Limpieza opcional de la base y del intermedio.
+    try:
+        os.remove(mid_path)
+    except OSError:
+        pass
+    if not keep_base:
+        try:
+            os.remove(base_path)
+            out["base_path"] = ""
+        except OSError:
+            pass
+
+    out["ok"] = True
+    return out
+
+
+if __name__ == "__main__":
+    import json
+
+    res = comfyui_pixelart_real_oneshot(
+        "pixel art knight, full body, side view, game sprite",
+        size=64, colors=16, engine="pixeloe", seed=42,
+        dest_dir="/tmp/comfy_pixelart_real",
+    )
+    print(json.dumps(res, indent=2))
Author	SHA1	Message	Date
egutierrez	ccdd529bdc	feat(comfyui): pipeline comfyui_pixelart_real_oneshot — pixelart REAL (PixelOE + cuantizacion dura) Materializa el metodo ganador del report 0215: generar a alta-res con SDXL + LoRA SDXL_pixel-art, downscale contrast-aware con PixelOE (engine=pixeloe para sprites/personajes) o nearest (tiles), y cuantizacion dura con comfyui_pixelize_image (16 colores libres o paleta fija pico-8/nes/game-boy). - pixeloe_downscale_py_ml: downscale contrast-aware via lib pixeloe con bridge de interprete (la lib vive en el venv de ComfyUI, no en el del registry). No-throw, fallback limpio si pixeloe no disponible. - comfyui_pixelart_real_oneshot_py_pipelines: one-shot que compone build_pixelart + submit + wait + fetch + pixeloe_downscale + pixelize_image. Fallback automatico pixeloe->nearest. Sweet-spot 64px personajes, 32px iconos. Verificado por PIL: personaje 64x64=16 colores, icono 32x32=16 colores (vs ~33k de la imagen de difusion cruda). 100% grid duro + outline nitido. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-28 15:24:15 +02:00
egutierrez	741724f633	chore: auto-commit (1 archivos) - logs/ardour_mcp_server.log Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-06-28 15:03:24 +02:00
egutierrez	2be62f6ef6	merge(comfyui): comfyui_generate_until_quality — loop generar/juzgar/refinar (best-of-N + escalate + refine_prompt)	2026-06-28 15:02:45 +02:00
Egutierrez	8e9e1e6c8a	feat(comfyui): pipeline comfyui_generate_until_quality (loop evaluator-optimizer) Loop tipo GAN sin entrenar: genera con un builder del registry, juzga con el panel multi-juez (comfyui_judge_image) y, si no alcanza el umbral, refina (nueva seed, mas steps/cfg, prompt corregido con el feedback del juez via ask_llm) y regenera hasta converger (verdict 'good') o agotar max_iters. Devuelve siempre la mejor candidata por score (best-of-N), nunca lanza excepcion cruda. Compone comfyui_submit_workflow + comfyui_wait_result + comfyui_fetch_output_image + comfyui_judge_image + ask_llm. Filtra kwargs por inspect.signature para ser robusto entre builders. Caso HUD verificado: itera iter0 bad -> iter1 good. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-28 15:01:37 +02:00
egutierrez	ec46aae04c	chore: auto-commit (1 archivos) - logs/ardour_mcp_server.log Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-06-28 07:34:26 +02:00
egutierrez	b173ac2703	merge(comfyui): higiene capability pages (drift conteos + styles + audio/templates + build_flux + parallax)	2026-06-28 07:34:02 +02:00
egutierrez	ec0a5e53ac	docs(comfyui): remata drift de conteo en comfyui-skill (11→17) y gamedev-2d (36→47) - gamedev-2d.md: el header decía '31 builders + 5 de apoyo' (=36); inventario real = 47 funciones (36 builders: 31 de generación + 5 de transformación; 11 de apoyo: post-proceso, puente a Godot, style presets, pipelines one-shot). - comfyui-skill.md: añade bloque de tamaño del grupo (17 funciones tag comfyui-skill); la página no tenía conteo interno (el 11 obsoleto vivía solo en INDEX.md). - INDEX.md: gamedev-2d 36→47 y comfyui-skill 11→17, con descripciones actualizadas. Cierra el drift residual señalado en el report 0210. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-28 07:33:08 +02:00
egutierrez	5280499df5	merge(comfyui): tests offline para 16 builders puros (376 tests verdes) + tested:true	2026-06-28 07:32:15 +02:00
egutierrez	604d3d4feb	docs(comfyui): higiene de capability pages — drift 29→126 + styles + build_flux + parallax - comfyui.md: bloque de tamaño real del grupo (126 funciones tag comfyui: 63 puras, 50 impuras, 13 pipelines) con punteros a los sub-grupos (comfyui-skill, comfyui-styles, comfyui-judge, gamedev-2d). Corrige la firma corta de build_flux (variant/steps=None/ weight_dtype='default' + camino custom-advanced) que arrastraba drift del report 0205. Añade sección Styles con las 5 funciones del sub-grupo. - comfyui-styles.md (NUEVA): página madre del sub-grupo de estilo (catálogo WAS + style presets gamedev), tabla de las 5 funciones, ejemplos canónicos alineados con los retornos reales y fronteras. - comfyui-overview.md: añade audio (05b) y styles (04b) al mapa cross-grupo y a la tabla resumen; referencia las nuevas páginas madre comfyui-styles y gamedev-2d. - INDEX.md: comfyui 29→126 con descripción actualizada; nueva fila comfyui-styles. - comfyui_build_parallax_background_workflow.md: añade sección ## Ejemplo lanzable (el indexer extrae example del cuerpo, no del frontmatter) — cobertura del grupo pasa a 126/126 con ejemplo. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-28 07:27:32 +02:00
egutierrez	287abbd6ee	merge(comfyui): fix firmas keyword-only para que fn run despache (5 funciones de skills)	2026-06-28 07:26:02 +02:00
egutierrez	f8793f96ac	fix(comfyui): firmas sin keyword-only para que fn run las despache El generador de runner de fn run (cmd/fn/pyrunner.go::generatePyRunner) parsea la signature de la funcion desde el frontmatter del .md y emite `<param> = _args[i]` por cada parametro posicional. Cuando la firma es keyword-only (`def f(, ...)`), el `` se trata como un nombre de parametro y genera la linea invalida `* = _args[0]`, que rompe el runner con `SyntaxError: invalid syntax` antes de ejecutar la funcion. Se quita el separador keyword-only (`,`) de la firma — tanto en la `def` del .py como en el campo `signature:` del .md (la fuente que lee el indexer y el runner) — convirtiendo los parametros keyword-only en parametros normales con su mismo default. No cambia nombres, defaults ni comportamiento: las llamadas con keyword siguen siendo validas. Afecta a 5 funciones detectadas en el report 0208 §3.3, todas con SyntaxError reproducido via `fn run <id>`: - comfyui_fetch_civitai_image_meta - comfyui_load_skill - comfyui_save_skill - comfyui_import_workflow_png - comfyui_list_skills Se completa ademas el fix de comfyui_interrupt_queue: el commit `643ebfb8` quito el `,` del .py pero dejo el `*,` en el campo `signature:` del .md, que es justo lo que lee el runner — por eso `fn run comfyui_interrupt_queue` seguia fallando. Aqui se corrige el .md. Verificado: tras el cambio las 6 despachan sin SyntaxError (las 4 con primer arg requerido devuelven el `missing required arg` esperado del runner; list_skills e interrupt_queue ejecutan `ok:true`). Tests existentes verdes (comfyui_fetch_civitai_image_meta_test.py + tests/test_comfyui_interrupt_queue.py: 8 passed). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-06-28 07:23:59 +02:00