Add deterministic asset integration workflow

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/

README.md

@@ -11,9 +11,27 @@ pinned: false
 
 # Image Generator for HTML Games
 
-Paste an HTML game, describe asset roles like `player`, `background`, or `enemy`, and generate a rewritten version of the game with image data embedded directly into the HTML.
+Paste an HTML game, select its game type and camera perspective, describe asset roles like `player`, `background`, or `enemy`, and generate game-ready images. The Space rewrites the game only when every requested role has a deterministic integration point.
 
-The app interprets the shared art style and pasted game code into explicit per-role image prompts, then generates and embeds game assets as base64 data URIs.
+## Deterministic asset contract
+
+Reference each requested role with either an exact filename or an explicit `GAME_ASSETS` hook:
+
+```js
+const playerImage = new Image();
+playerImage.src = GAME_ASSETS.player; // or "sprite_player.png"
+
+const backgroundImage = new Image();
+backgroundImage.src = GAME_ASSETS.background; // or "sprite_background.png"
+```
+
+The generator injects an immutable `window.GAME_ASSETS` manifest whose keys are normalized role names. It does not monkey-patch browser image APIs, guess aliases, or silently replace canvas primitives such as `fillRect()`, `arc()`, and `fill()`.
+
+If a requested role has no deterministic hook, assets are still generated for review, but no rewritten game is returned. The status explains which hooks are missing and the preview is explicitly the unchanged original game.
+
+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 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

@@ -105,6 +105,15 @@ class StylePlan:
     tags: tuple[str, ...]
 
 
+@dataclass
+class IntegrationReport:
+    supported: bool
+    mode: str
+    referenced_roles: tuple[str, ...]
+    missing_roles: tuple[str, ...]
+    warnings: tuple[str, ...]
+
+
 HF_TOKEN = os.environ.get("HF_TOKEN", "")
 FREE_IMAGE_MODEL = os.environ.get("FREE_IMAGE_MODEL", "segmind/tiny-sd")
 FREE_IMAGE_STEPS = int(os.environ.get("FREE_IMAGE_STEPS", "5"))
@@ -189,10 +198,16 @@ def interpret_style_hint(style_hint: str) -> StylePlan:
         lighting = "balanced game lighting"
         linework = "clear readable silhouette and controlled edges"
 
-    if has("top-down", "top down", "shooter", "rpg", "arena"):
+    if has("top-down", "top down", "overhead"):
         camera = "top-down readable game camera"
     elif has("platformer", "side-scroller", "side scroller"):
         camera = "side-view platformer camera"
+    elif has("isometric", "3/4 view", "three-quarter"):
+        camera = "consistent isometric three-quarter game camera"
+    elif has("first-person", "first person"):
+        camera = "first-person game camera"
+    elif has("front-facing", "front facing"):
+        camera = "front-facing game camera"
     else:
         camera = "game-ready camera angle matching the role"
 
@@ -211,18 +226,31 @@ def build_asset_prompt(role: str, prompt: str, style_hint: str) -> str:
         )
     else:
         asset_instruction = (
-            "Create one complete standalone 2D sprite of the whole subject, centered, full body or full vehicle, "
+            "Create one complete standalone 2D sprite of the whole subject, centered and fully visible, "
             "single object, transparent or plain background, readable silhouette. Not a texture map, not a tiled "
             "pattern, not a material swatch, not a UV unwrap, not a 3D model skin."
         )
     return (
-        f"{role} asset: {prompt}. Style interpretation: {plan.medium}; {plan.palette}; "
+        f"{role} asset: {prompt}. Creative brief: {style_hint}. "
+        f"Style interpretation: {plan.medium}; {plan.palette}; "
         f"{plan.texture}; {plan.lighting}; {plan.linework}; {plan.camera}. "
         f"{asset_instruction} "
         "Game asset, readable at small size, no text, no watermark."
     )
 
 
+def build_style_context(game_type: str, perspective: str, theme: str) -> str:
+    parts = []
+    if game_type and game_type != "Other / custom":
+        parts.append(f"Game type: {game_type}")
+    if perspective and perspective != "Auto-detect from code":
+        parts.append(f"Required camera perspective: {perspective}")
+    normalized_theme = (theme or "").strip()
+    if normalized_theme:
+        parts.append(f"Theme and visual direction: {normalized_theme}")
+    return ". ".join(parts) or "cohesive game-ready 2D art"
+
+
 def parse_role_lines(raw_roles: str) -> list[tuple[str, str]]:
     parsed: list[tuple[str, str]] = []
     for line in raw_roles.splitlines():
@@ -555,7 +583,10 @@ def draw_background(spec: AssetSpec, rng: random.Random) -> bytes:
     draw = ImageDraw.Draw(image, "RGBA")
     prompt = spec.prompt.lower()
 
-    if any(word in prompt for word in ("sci-fi", "scifi", "arena", "metal", "hazard", "grid", "shooter")):
+    if (
+        any(word in prompt for word in ("sci-fi", "scifi", "arena", "metal", "hazard", "grid", "shooter"))
+        and not any(word in prompt for word in ("space", "starfield", "nebula", "galaxy", "cosmic"))
+    ):
         image = Image.new("RGBA", (spec.width, spec.height), (18, 22, 31, 255))
         draw = ImageDraw.Draw(image, "RGBA")
         panel = 64
@@ -750,6 +781,34 @@ def draw_sprite(spec: AssetSpec, rng: random.Random) -> bytes:
     accent = colors[1] + (255,)
     trim = colors[3] + (255,)
 
+    if role in ("asteroid", "rock", "meteor") or any(
+        word in role_prompt for word in ("asteroid", "meteor", "space rock")
+    ):
+        points = []
+        for step in range(12):
+            angle = (math.pi * 2 * step / 12) - math.pi / 2
+            radius = rng.randint(int(34 * scale), int(49 * scale))
+            points.append((cx + math.cos(angle) * radius, cy + math.sin(angle) * radius))
+        draw.polygon(points, fill=outline)
+        inner = [
+            (cx + (x - cx) * 0.84, cy + (y - cy) * 0.84)
+            for x, y in points
+        ]
+        draw.polygon(inner, fill=body)
+        for _ in range(7):
+            crater_x = cx + rng.randint(-25, 25) * scale
+            crater_y = cy + rng.randint(-25, 25) * scale
+            crater_r = rng.randint(4, 11) * scale
+            draw.ellipse(
+                (crater_x - crater_r, crater_y - crater_r, crater_x + crater_r, crater_y + crater_r),
+                fill=outline[:3] + (105,),
+                outline=trim[:3] + (155,),
+                width=max(1, int(2 * scale)),
+            )
+        out = io.BytesIO()
+        image.save(out, format="PNG")
+        return out.getvalue()
+
     if any(word in role_prompt for word in ("car", "racing", "racer", "buggy", "vehicle", "truck")):
         shadow = (int(cx - 43 * scale), int(cy + 28 * scale), int(cx + 43 * scale), int(cy + 42 * scale))
         draw.ellipse(shadow, fill=(0, 0, 0, 58))
@@ -1149,151 +1208,124 @@ def generate_asset(spec: AssetSpec, index: int, run_id: int) -> tuple[str, str,
 
 def replacement_names(spec: AssetSpec) -> set[str]:
     slug = slugify(spec.role)
-    names = {
+    return {
         spec.filename,
         f"{slug}.png",
         f"{slug}.jpg",
         f"{slug}.jpeg",
         f"{slug}.webp",
-        f"asset_{slug}.png",
-        f"{spec.role.strip()}.png",
         f"{{{{{slug}}}}}",
         f"{{{slug}}}",
     }
-    if slug == "background":
-        names.update({"background.png", "sprite_background.jpg", "background.jpg"})
-    if slug == "player":
-        names.update({"player.png", "sprite_player.jpg", "hero.png"})
-    if slug == "enemy":
-        names.update({"enemy.png", "monster.png", "sprite_enemy.jpg"})
-    if slug == "bullet":
-        names.update({"bullet.png", "projectile.png", "laser.png", "shot.png", "sprite_bullet.jpg"})
-    return names
-
-
-def asset_aliases(spec: AssetSpec) -> list[str]:
+
+
+def code_references_role(html_code: str, spec: AssetSpec) -> bool:
     slug = slugify(spec.role)
-    aliases = {slug, spec.role.strip().lower(), spec.filename.lower()}
-    prompt = spec.prompt.lower()
-    role_groups = {
-        "player": ("player", "hero", "character", "avatar", "ship", "shooter", "tank", "knight", "wizard"),
-        "enemy": ("enemy", "monster", "alien", "drone", "foe", "zombie", "boss", "hazard"),
-        "bullet": ("bullet", "projectile", "laser", "shot", "missile", "beam", "ammo"),
-        "coin": ("coin", "gem", "seed", "star", "pickup", "collectible", "key", "orb"),
-        "background": ("background", "backdrop", "bg", "map", "level", "arena", "scene", "world", "floor"),
-    }
-    for group, words in role_groups.items():
-        if group in slug or any(word in prompt for word in words):
-            aliases.update(words)
-    return sorted(alias for alias in aliases if alias)
+    escaped_slug = re.escape(slug)
+    hook_patterns = (
+        rf"(?:window\.)?GAME_ASSETS\s*\.\s*{escaped_slug}\b",
+        rf"(?:window\.)?GAME_ASSETS\s*\[\s*['\"]{escaped_slug}['\"]\s*\]",
+    )
+    if any(re.search(pattern, html_code, flags=re.I) for pattern in hook_patterns):
+        return True
+    lowered = html_code.lower()
+    return any(name.lower() in lowered for name in replacement_names(spec))
+
+
+def analyze_integration(html_code: str, specs: list[AssetSpec]) -> IntegrationReport:
+    referenced = tuple(spec.role for spec in specs if code_references_role(html_code, spec))
+    missing = tuple(spec.role for spec in specs if spec.role not in referenced)
+    primitive_calls = sorted(
+        set(
+            re.findall(
+                r"\.(arc|ellipse|fillRect|strokeRect|moveTo|lineTo|fill|stroke)\s*\(",
+                html_code,
+            )
+        )
+    )
+    warnings = []
+    if primitive_calls:
+        warnings.append(
+            "Canvas primitive drawing detected ("
+            + ", ".join(primitive_calls)
+            + "). Primitive geometry is preserved; it is never guessed or silently replaced."
+        )
+    if missing:
+        warnings.append(
+            "Missing deterministic asset hook(s): "
+            + ", ".join(f"GAME_ASSETS.{slugify(role)}" for role in missing)
+            + "."
+        )
+    if missing:
+        return IntegrationReport(False, "unsupported", referenced, missing, tuple(warnings))
+    return IntegrationReport(True, "explicit asset contract", referenced, (), tuple(warnings))
+
+
+def validate_asset_png(content: bytes, spec: AssetSpec) -> list[str]:
+    image = Image.open(io.BytesIO(content)).convert("RGBA")
+    warnings = []
+    if image.size != (spec.width, spec.height):
+        warnings.append(f"unexpected dimensions {image.width}x{image.height}")
+    alpha = image.getchannel("A")
+    extrema = alpha.getextrema()
+    if is_background_spec(spec):
+        if extrema[0] < 255:
+            warnings.append("background contains transparency")
+    else:
+        transparent_pixels = sum(alpha.histogram()[:16])
+        transparent_ratio = transparent_pixels / max(1, image.width * image.height)
+        if transparent_ratio < 0.12:
+            warnings.append("sprite background is not sufficiently transparent")
+        corners = (
+            alpha.getpixel((0, 0)),
+            alpha.getpixel((image.width - 1, 0)),
+            alpha.getpixel((0, image.height - 1)),
+            alpha.getpixel((image.width - 1, image.height - 1)),
+        )
+        if any(value > 16 for value in corners):
+            warnings.append("sprite has opaque corner pixels")
+    return warnings
 
 
 def embed_assets(html_code: str, assets: dict[str, str], specs: list[AssetSpec]) -> str:
+    report = analyze_integration(html_code, specs)
+    if not report.supported:
+        raise ValueError("Cannot embed assets without deterministic GAME_ASSETS hooks or role filenames")
+
     output = html_code
     manifest_lines = ["<!-- Embedded game assets generated by Image Generator for HTML Games"]
-    background_uri = None
     asset_map: dict[str, str] = {}
-    alias_map: dict[str, list[str]] = {}
 
     for spec in specs:
         data_uri = assets[spec.role]
         slug = slugify(spec.role)
         asset_map[slug] = data_uri
-        alias_map[slug] = asset_aliases(spec)
         manifest_lines.append(f"{spec.role}: {spec.filename}")
-        if is_background_spec(spec) and background_uri is None:
-            background_uri = data_uri
         for name in replacement_names(spec):
             output = output.replace(f'"{name}"', f'"{data_uri}"')
             output = output.replace(f"'{name}'", f"'{data_uri}'")
-            output = output.replace(name, data_uri)
+            if name.startswith("{"):
+                output = output.replace(name, data_uri)
 
     manifest_lines.append("-->")
     manifest = "\n".join(manifest_lines) + "\n"
     asset_json = json.dumps(asset_map)
-    alias_json = json.dumps(alias_map)
-    background_json = json.dumps(background_uri)
     helper_script = f"""<script>
 (function () {{
   var ASSETS = {asset_json};
-  var ALIASES = {alias_json};
+  window.GAME_ASSETS = Object.freeze(Object.assign({{}}, window.GAME_ASSETS || {{}}, ASSETS));
   window.GENERATED_GAME_ASSETS = ASSETS;
-
-  function basename(value) {{
-    return String(value || "").split("?")[0].split("#")[0].split("/").pop().toLowerCase();
-  }}
-
-  function pickAsset(value) {{
-    var text = String(value || "").toLowerCase();
-    if (!text || text.indexOf("data:image/") === 0) return value;
-    var file = basename(text);
-    for (var role in ASSETS) {{
-      var aliases = ALIASES[role] || [role];
-      for (var i = 0; i < aliases.length; i++) {{
-        var alias = String(aliases[i]).toLowerCase();
-        if (!alias) continue;
-        if (file === alias || file === alias + ".png" || file === "sprite_" + alias + ".png") return ASSETS[role];
-        if (file.indexOf(alias) !== -1 || text.indexOf("/" + alias) !== -1 || text.indexOf("_" + alias) !== -1) return ASSETS[role];
-      }}
-    }}
-    return value;
-  }}
-
-  var descriptor = Object.getOwnPropertyDescriptor(HTMLImageElement.prototype, "src");
-  if (descriptor && descriptor.set && !HTMLImageElement.prototype.__generatedAssetMapper) {{
-    Object.defineProperty(HTMLImageElement.prototype, "src", {{
-      get: function () {{ return descriptor.get.call(this); }},
-      set: function (value) {{ descriptor.set.call(this, pickAsset(value)); }},
-      configurable: true,
-      enumerable: descriptor.enumerable
-    }});
-    HTMLImageElement.prototype.__generatedAssetMapper = true;
-  }}
-
-  var originalDrawImage = CanvasRenderingContext2D.prototype.drawImage;
-  if (!CanvasRenderingContext2D.prototype.__generatedAssetDrawGuard) {{
-    CanvasRenderingContext2D.prototype.drawImage = function (image) {{
-      try {{
-        if (image instanceof HTMLImageElement) {{
-          var current = image.getAttribute("src") || image.src || "";
-          var mapped = pickAsset(current);
-          if (mapped && mapped !== current) image.src = mapped;
-          if (!image.complete || image.naturalWidth === 0 || image.naturalHeight === 0) {{
-            var looksLikeBackground = /background|backdrop|scene|map|level|bg/i.test(current);
-            var coversCanvas = arguments.length >= 5 && arguments[1] === 0 && arguments[2] === 0 &&
-              arguments[3] >= this.canvas.width * 0.8 && arguments[4] >= this.canvas.height * 0.8;
-            if (looksLikeBackground || coversCanvas) {{
-              this.clearRect(0, 0, this.canvas.width, this.canvas.height);
-            }}
-            return;
-          }}
-        }}
-        return originalDrawImage.apply(this, arguments);
-      }} catch (error) {{
-        return;
-      }}
-    }};
-    CanvasRenderingContext2D.prototype.__generatedAssetDrawGuard = true;
-  }}
-
-  window.addEventListener("DOMContentLoaded", function () {{
-    document.querySelectorAll("img").forEach(function (img) {{
-      var mapped = pickAsset(img.getAttribute("src") || img.src);
-      if (mapped !== (img.getAttribute("src") || img.src)) img.src = mapped;
-    }});
-    var background = {background_json};
-    if (!background) return;
-    document.querySelectorAll("canvas").forEach(function (canvas) {{
-      canvas.style.backgroundImage = "url(" + background + ")";
-      canvas.style.backgroundSize = "cover";
-      canvas.style.backgroundPosition = "center";
-    }});
-  }});
 }})();
 </script>"""
 
-    if "</head>" in output:
-        output = output.replace("</head>", helper_script + "\n</head>", 1)
+    if re.search(r"<head(?:\s[^>]*)?>", output, flags=re.I):
+        output = re.sub(
+            r"(<head(?:\s[^>]*)?>)",
+            lambda match: match.group(1) + "\n" + helper_script,
+            output,
+            count=1,
+            flags=re.I,
+        )
     elif "<body" in output:
         output = output.replace("<body", helper_script + "\n<body", 1)
     else:
@@ -1325,19 +1357,102 @@ def summarize_model_sources(rows: list[tuple[str, str, str]]) -> str:
     return f"prompt={', '.join(prompt_sources)}; image={', '.join(image_sources)}"
 
 
-def generate_images_and_game(html_code: str, roles: str, style_hint: str):
+def build_quality_report(specs: list[AssetSpec], quality: dict[str, list[str]]) -> str:
+    lines = []
+    for spec in specs:
+        warnings = quality.get(spec.role, [])
+        lines.append(f"{spec.role}: {'PASS' if not warnings else 'WARNING — ' + '; '.join(warnings)}")
+    lines.append("Semantic subject/style accuracy still requires visual approval by a human.")
+    return "\n".join(lines)
+
+
+def render_generation_state(state: dict, action: str, errors: list[str] | None = None):
+    html_code = state["html_code"]
+    specs = state["specs"]
+    assets = state["assets"]
+    integration = analyze_integration(html_code, specs)
+    model_rows = [
+        (spec.role, state["prompt_model"], state["image_models"][spec.role])
+        for spec in specs
+    ]
+    if integration.supported:
+        rewritten = embed_assets(html_code, assets, specs)
+        preview_html = build_preview(rewritten)
+        status = (
+            f"{action} {len(specs)} asset(s) and embedded them through the deterministic "
+            f"GAME_ASSETS contract using {summarize_model_sources(model_rows)}."
+        )
+    else:
+        rewritten = ""
+        preview_html = build_preview(html_code)
+        status = (
+            f"{action} {len(specs)} asset(s), but did not rewrite the game because deterministic "
+            "asset hooks are missing. The preview below is the unchanged original game."
+        )
+    if integration.warnings:
+        status += "\n\n" + "\n".join(f"- {warning}" for warning in integration.warnings)
+    if errors:
+        status += "\n\n" + "\n".join(f"- {error}" for error in errors)
+    gallery = [
+        (state["gallery_paths"][spec.role], f"{spec.role} -> {spec.filename}")
+        for spec in specs
+    ]
+    return (
+        rewritten,
+        status,
+        gallery,
+        build_prompt_preview(specs),
+        build_model_report(model_rows),
+        build_quality_report(specs, state["quality"]),
+        preview_html,
+    )
+
+
+def empty_generation_result(message: str, html_code: str = ""):
+    return (
+        "",
+        message,
+        [],
+        "",
+        "",
+        "",
+        build_preview(html_code) if html_code.strip() else "",
+        {},
+        gr.Dropdown(choices=[], value=None),
+        gr.CheckboxGroup(choices=[], value=[]),
+    )
+
+
+def generate_images_and_game(
+    html_code: str,
+    roles: str,
+    game_type: str,
+    perspective: str,
+    theme: str,
+):
     if not html_code.strip():
-        return "", "Paste HTML game code first.", [], "", "", ""
+        return empty_generation_result("Paste HTML game code first.")
 
-    role_lines, prompt_map, prompt_model, prompt_error = build_prompt_map(html_code, roles, style_hint or "pixel art style")
-    specs = parse_assets(roles, style_hint or "pixel art style", prompt_map)
+    style_context = build_style_context(game_type, perspective, theme)
+    role_lines, prompt_map, prompt_model, prompt_error = build_prompt_map(html_code, roles, style_context)
+    specs = parse_assets(roles, style_context, prompt_map)
     if not specs:
-        return html_code, "Add at least one asset role, like `player: brave knight`.", [], "", "", build_preview(html_code)
+        return empty_generation_result(
+            "Add at least one asset role, like `player: brave knight`.",
+            html_code,
+        )
+    slugs = [slugify(spec.role) for spec in specs]
+    if len(slugs) != len(set(slugs)):
+        return empty_generation_result(
+            "Each asset role must have a unique name after normalization.",
+            html_code,
+        )
 
     assets: dict[str, str] = {}
-    gallery = []
+    gallery_paths: dict[str, str] = {}
+    image_models: dict[str, str] = {}
+    quality: dict[str, list[str]] = {}
     errors = []
-    model_rows = []
     run_id = time.time_ns()
     if prompt_error:
         errors.append(f"prompt model: {prompt_error}")
@@ -1345,19 +1460,71 @@ def generate_images_and_game(html_code: str, roles: str, style_hint: str):
     for index, spec in enumerate(specs):
         data_uri, gallery_path, error, image_model = generate_asset(spec, index, run_id)
         assets[spec.role] = data_uri
-        gallery.append((gallery_path, f"{spec.role} -> {spec.filename}"))
-        model_rows.append((spec.role, prompt_model, image_model))
+        gallery_paths[spec.role] = gallery_path
+        image_models[spec.role] = image_model
+        png_content = base64.b64decode(data_uri.split(",", 1)[1])
+        quality[spec.role] = validate_asset_png(png_content, spec)
         if error:
             errors.append(f"{spec.role}: image model failed ({error}); used local procedural fallback")
 
-    rewritten = embed_assets(html_code, assets, specs)
-    status = (
-        f"Generated and embedded {len(specs)} fresh asset(s) using "
-        f"{summarize_model_sources(model_rows)}. Run {str(run_id)[-6:]}."
+    state = {
+        "html_code": html_code,
+        "specs": specs,
+        "assets": assets,
+        "gallery_paths": gallery_paths,
+        "prompt_model": prompt_model,
+        "image_models": image_models,
+        "quality": quality,
+        "run_id": run_id,
+    }
+    rendered = render_generation_state(state, "Generated", errors)
+    role_choices = [spec.role for spec in specs]
+    return (
+        *rendered,
+        state,
+        gr.Dropdown(choices=role_choices, value=role_choices[0]),
+        gr.CheckboxGroup(choices=role_choices, value=[]),
+    )
+
+
+def regenerate_selected_asset(state: dict, selected_role: str, approved_roles: list[str]):
+    if not state or not selected_role:
+        return (
+            "",
+            "Generate the initial asset set before regenerating a role.",
+            [],
+            "",
+            "",
+            "",
+            "",
+            state or {},
+            gr.CheckboxGroup(choices=[], value=[]),
+        )
+    specs = state["specs"]
+    index = next((i for i, spec in enumerate(specs) if spec.role == selected_role), None)
+    if index is None:
+        rendered = render_generation_state(state, "Kept")
+        roles = [spec.role for spec in specs]
+        return (*rendered, state, gr.CheckboxGroup(choices=roles, value=approved_roles or []))
+
+    spec = specs[index]
+    run_id = time.time_ns()
+    data_uri, gallery_path, error, image_model = generate_asset(spec, index, run_id)
+    state["assets"][selected_role] = data_uri
+    state["gallery_paths"][selected_role] = gallery_path
+    state["image_models"][selected_role] = image_model
+    png_content = base64.b64decode(data_uri.split(",", 1)[1])
+    state["quality"][selected_role] = validate_asset_png(png_content, spec)
+    state["run_id"] = run_id
+    errors = [f"{selected_role}: {error}"] if error else []
+    rendered = render_generation_state(state, f"Regenerated {selected_role}; retained", errors)
+    roles = [item.role for item in specs]
+    retained_approvals = [role for role in (approved_roles or []) if role != selected_role]
+    return (
+        *rendered,
+        state,
+        gr.CheckboxGroup(choices=roles, value=retained_approvals),
     )
-    if errors:
-        status += "\n\n" + "\n".join(errors)
-    return rewritten, status, gallery, build_prompt_preview(specs), build_model_report(model_rows), build_preview(rewritten)
 
 
 def check_hf_token() -> str:
@@ -1382,34 +1549,74 @@ def check_hf_token() -> str:
 with gr.Blocks(title="Image Generator for HTML Games") as demo:
     gr.Markdown(
         "# Image Generator for HTML Games\n"
-        "Paste an HTML canvas game, list the image roles you want, and generate a rewritten version "
-        "with the images embedded directly into the code."
+        "Generate game assets and embed them only when the submitted game exposes deterministic "
+        "`GAME_ASSETS.<role>` hooks or exact role filenames such as `sprite_player.png`. "
+        "Primitive canvas geometry is preserved and never silently guessed."
     )
 
+    generation_state = gr.State({})
+
     with gr.Row():
         with gr.Column(scale=1):
             roles = gr.Textbox(
                 label="Image roles to generate",
                 lines=8,
                 placeholder=ROLE_PLACEHOLDER,
+                value=DEFAULT_ROLES,
                 info="One per line: role: image description. Example: player: blue robot hero",
             )
-            style = gr.Textbox(
-                label="Shared visual style",
+            game_type = gr.Dropdown(
+                label="Game type",
+                choices=[
+                    "Top-down action / RPG",
+                    "Platformer / side-scroller",
+                    "Isometric strategy / simulation",
+                    "First-person",
+                    "Card / board game",
+                    "Other / custom",
+                ],
+                value="Top-down action / RPG",
+            )
+            perspective = gr.Dropdown(
+                label="Camera perspective",
+                choices=[
+                    "Top-down / overhead",
+                    "Side view",
+                    "Isometric 3/4 view",
+                    "First-person",
+                    "Front-facing",
+                    "Auto-detect from code",
+                ],
+                value="Top-down / overhead",
+            )
+            theme = gr.Textbox(
+                label="Theme and shared visual style",
                 lines=2,
-                placeholder="Optional: describe the art style/theme, or leave blank.",
+                placeholder="Describe the setting, palette, medium, mood, and constraints.",
             )
             generate_btn = gr.Button("Generate Images + Embed Game", variant="primary")
             status = gr.Markdown("Ready.")
             token_btn = gr.Button("Check HF Token")
             token_status = gr.Markdown("")
             gallery = gr.Gallery(label="Generated assets", columns=2, height=300)
+            selected_role = gr.Dropdown(
+                label="Asset to regenerate",
+                choices=[],
+                interactive=True,
+            )
+            regenerate_btn = gr.Button("Regenerate selected asset")
+            approved_roles = gr.CheckboxGroup(
+                label="Visually approved assets",
+                choices=[],
+                info="Approve assets only after checking subject, perspective, style, and transparency.",
+            )
 
         with gr.Column(scale=2):
             html_input = gr.Textbox(
                 label="Original HTML game code",
                 lines=18,
                 placeholder="Paste your full HTML game code here.",
+                value=STARTER_HTML,
             )
             output_code = gr.Code(
                 label="Rewritten HTML with embedded images",
@@ -1426,14 +1633,45 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
                 lines=5,
                 interactive=False,
             )
+            quality_report = gr.Textbox(
+                label="Automated asset validation",
+                lines=6,
+                interactive=False,
+            )
 
     gr.Markdown("## Game preview")
     preview = gr.HTML("")
 
     generate_btn.click(
         fn=generate_images_and_game,
-        inputs=[html_input, roles, style],
-        outputs=[output_code, status, gallery, prompt_preview, model_report, preview],
+        inputs=[html_input, roles, game_type, perspective, theme],
+        outputs=[
+            output_code,
+            status,
+            gallery,
+            prompt_preview,
+            model_report,
+            quality_report,
+            preview,
+            generation_state,
+            selected_role,
+            approved_roles,
+        ],
+    )
+    regenerate_btn.click(
+        fn=regenerate_selected_asset,
+        inputs=[generation_state, selected_role, approved_roles],
+        outputs=[
+            output_code,
+            status,
+            gallery,
+            prompt_preview,
+            model_report,
+            quality_report,
+            preview,
+            generation_state,
+            approved_roles,
+        ],
     )
     token_btn.click(fn=check_hf_token, inputs=None, outputs=token_status)