Make validation aware of image model behavior

README.md

@@ -31,6 +31,8 @@ If a requested role has no deterministic hook, assets are still generated for re
 
 Generated sprites receive automated dimension, alpha-channel, and corner-transparency checks. These checks do not establish semantic or artistic correctness, so every role also has a manual approval control and per-role regeneration.
 
+The UI reports the configured prompt and image pipeline and labels every role with its actual source. Procedural generators provide predictable structure and real transparency but have limited open-ended semantic fidelity. Diffusion models provide more visual variety but are more likely to miss perspective, subject, background, or edge constraints; sprite outputs therefore receive alpha post-processing and still require visual approval. Background and sprite diffusion runs use different negative prompts so valid characters and vehicles are not accidentally excluded from sprite generation.
+
 The app combines the game type, perspective, theme, and pasted code into explicit per-role image prompts, then generates PNG assets and embeds contract-compatible assets as base64 data URIs.
 
 If the Space has an `HF_TOKEN` secret, it first uses the text model in `HF_PROMPT_MODEL` to interpret the code, roles, and theme into image prompts. The default prompt model is `Qwen/Qwen2.5-Coder-7B-Instruct`.

app.py

@@ -1046,7 +1046,15 @@ def local_asset_png(spec: AssetSpec, index: int, run_id: int) -> bytes:
         content = draw_background(spec, rng)
     else:
         content = draw_sprite(spec, rng)
-    return apply_style_finish(content, spec, rng)
+    content = apply_style_finish(content, spec, rng)
+    if not is_background_spec(spec):
+        return content
+
+    image = Image.open(io.BytesIO(content)).convert("RGBA")
+    image.putalpha(Image.new("L", image.size, 255))
+    out = io.BytesIO()
+    image.save(out, format="PNG")
+    return out.getvalue()
 
 
 def placeholder_png_bytes(role: str, width: int, height: int) -> bytes:
@@ -1070,6 +1078,17 @@ def diffusion_dimensions(spec: AssetSpec) -> tuple[int, int]:
     return 256, 256
 
 
+def diffusion_negative_prompt(spec: AssetSpec) -> str:
+    common = (
+        "texture map, material texture, seamless texture, tiled pattern, uv map, uv unwrap, "
+        "3d model texture, normal map, roughness map, diffuse map, sprite sheet, atlas, "
+        "multiple objects, cropped subject, close-up surface, fabric swatch, text, watermark"
+    )
+    if is_background_spec(spec):
+        return common + ", person, character, player, hero, creature, monster, vehicle, mascot, foreground subject"
+    return common + ", landscape, environment scene, room, horizon, opaque background, drop shadow"
+
+
 def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
     image = image.convert("RGBA")
     if not is_background_spec(spec):
@@ -1123,15 +1142,9 @@ def free_diffusion_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes
         width, height = diffusion_dimensions(spec)
         seed = abs(hash(f"{spec.role}|{spec.prompt}|{index}|{run_id}")) % 2147483647
         generator = torch.Generator(device="cpu").manual_seed(seed)
-        negative_prompt = (
-            "texture map, material texture, seamless texture, tiled pattern, uv map, uv unwrap, "
-            "skin texture, 3d model texture, normal map, roughness map, diffuse map, sprite sheet, "
-            "atlas, multiple objects, cropped subject, close-up surface, fabric swatch, text, watermark, "
-            "person, character, player, hero, creature, monster, vehicle, mascot, foreground subject"
-        )
         image = FREE_DIFFUSION_PIPE(
             spec.prompt,
-            negative_prompt=negative_prompt,
+            negative_prompt=diffusion_negative_prompt(spec),
             width=width,
             height=height,
             num_inference_steps=FREE_IMAGE_STEPS,
@@ -1163,9 +1176,7 @@ def hf_image_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes | None
             guidance_scale=0.0,
             seed=abs(hash(f"{spec.role}|{spec.prompt}|{index}|{run_id}")) % 2147483647,
         )
-        out = io.BytesIO()
-        image.save(out, format="PNG")
-        return image_to_png_bytes(out.getvalue(), spec.width, spec.height), None
+        return polish_diffusion_asset(image, spec), None
     except Exception as exc:
         return None, short_error(exc)
 
@@ -1348,7 +1359,31 @@ def build_prompt_preview(specs: list[AssetSpec]) -> str:
 
 
 def build_model_report(rows: list[tuple[str, str, str]]) -> str:
-    return "\n".join(f"{role}: prompt={prompt_model}; image={image_model}" for role, prompt_model, image_model in rows)
+    return "\n".join(
+        f"{role}: prompt={prompt_model}; image={image_model}; {model_source_note(image_model)}"
+        for role, prompt_model, image_model in rows
+    )
+
+
+def model_source_note(image_model: str) -> str:
+    lowered = image_model.lower()
+    if "shape-aware" in lowered or "scene-safe" in lowered or "procedural" in lowered:
+        return "procedural/heuristic output—predictable structure, limited open-ended semantic fidelity"
+    return "diffusion output—higher visual variety; verify subject, perspective, alpha edges, and prompt compliance"
+
+
+def model_configuration_summary() -> str:
+    prompt_source = HF_PROMPT_MODEL if USE_HF_PROMPT_PROVIDER else "local prompt interpreter"
+    sprite_source = FREE_IMAGE_MODEL if USE_DIFFUSION_FOR_SPRITES else "shape-aware procedural generator"
+    background_source = FREE_IMAGE_MODEL if USE_DIFFUSION_FOR_BACKGROUNDS else "scene-safe procedural generator"
+    remote_fallback = HF_IMAGE_MODEL if USE_HF_IMAGE_PROVIDER else "disabled"
+    return (
+        "**Configured model pipeline:** "
+        f"prompts: `{prompt_source}` · sprites: `{sprite_source}` · backgrounds: `{background_source}` · "
+        f"remote image fallback: `{remote_fallback}`. "
+        "Procedural output is structurally predictable but semantically limited; diffusion output is more varied "
+        "and therefore requires stricter visual review."
+    )
 
 
 def summarize_model_sources(rows: list[tuple[str, str, str]]) -> str:
@@ -1553,6 +1588,7 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
         "`GAME_ASSETS.<role>` hooks or exact role filenames such as `sprite_player.png`. "
         "Primitive canvas geometry is preserved and never silently guessed."
     )
+    gr.Markdown(model_configuration_summary())
 
     generation_state = gr.State({})