Support fully custom asset manifests

README.md

@@ -11,46 +11,73 @@ pinned: false
 
 # Image Generator for HTML Games
 
-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.
+Paste an HTML game, select its game type and shared perspective, and define exactly which images the game needs through a user-authored asset manifest. Asset IDs are not restricted to players or backgrounds. The Space rewrites the game only when every requested asset set has a deterministic integration point.
+
+## Custom asset manifest
+
+The recommended JSON input makes generation behavior explicit instead of guessing from asset names:
+
+```json
+{
+  "assets": [
+    {
+      "id": "crystal_pickups",
+      "description": "distinct glowing mineral pickups",
+      "quantity": 3,
+      "width": 96,
+      "height": 96,
+      "transparent": true,
+      "composition": "single_subject",
+      "camera": "isometric",
+      "variations": "different silhouette and mineral color"
+    },
+    {
+      "id": "desert_outpost",
+      "description": "abandoned science-fantasy outpost with readable traversal space",
+      "quantity": 1,
+      "width": 1280,
+      "height": 720,
+      "transparent": false,
+      "composition": "full_frame",
+      "camera": "top-down"
+    }
+  ]
+}
+```
+
+Supported technical compositions are `single_subject`, `full_frame`, `seamless`, `icon`, `animation_frame`, `sprite_sheet`, and `freeform`. Optional `expected_subjects` and `silhouette: "humanoid"` fields enable stricter validation when appropriate. The older `name: description` syntax remains available for compatibility, but the JSON contract is preferred because it does not infer processing rules from names.
+
+Each requested quantity is generated through an independent model call and saved as a separate PNG. A quantity of three produces keys such as `crystal_pickups_01` through `crystal_pickups_03`, plus a grouped array at `GAME_ASSETS.crystal_pickups`. The free ZeroGPU batch is capped by `MAX_GENERATED_ASSETS` (default eight outputs); larger libraries should be produced in multiple batches.
 
 ## Deterministic asset contract
 
-Reference each requested role with either an exact filename or an explicit `GAME_ASSETS` hook:
+Reference each requested asset 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 pickupImage = new Image();
+pickupImage.src = GAME_ASSETS.crystal_pickups[0];
 
-const backgroundImage = new Image();
-backgroundImage.src = GAME_ASSETS.background; // or "sprite_background.png"
+const outpostImage = new Image();
+outpostImage.src = GAME_ASSETS.desert_outpost; // or "sprite_desert_outpost.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.
+The generator injects an immutable `window.GAME_ASSETS` manifest whose keys are normalized asset IDs. Single-output IDs contain a data URI; multi-output IDs contain an ordered array and also expose individual numbered keys. It does not monkey-patch browser image APIs, guess aliases, or silently replace canvas primitives such as `fillRect()`, `arc()`, and `fill()`.
 
-## Multiple character sprites
+If a requested asset has no deterministic hook, images 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.
 
-Define each distinct character as its own role so the model produces a separate PNG and the game can address it independently:
-
-```text
-player: agile desert ranger with a leather bow
-enemy_grunt: compact orange patrol robot
-enemy_boss: towering red armored commander
-npc_merchant: elderly traveling potion seller
-```
+## Contract-driven generation and validation
 
-The generator runs one neural image request per role rather than intentionally combining character roles into a contact sheet. The image model can still violate the one-subject instruction, so every result requires visual review. When the submitted HTML references additional deterministic hooks such as `GAME_ASSETS.enemy_grunt`, `GAME_ASSETS.enemy_boss`, or `sprite_npc_merchant.png`, missing roles are automatically added to the generation set. Explicit role descriptions remain preferable because code identifiers alone provide limited visual direction. Repeated instances of the same enemy should reuse one role, while visually distinct character types should use separate roles.
+Filenames and IDs do not decide whether an image is a scene or sprite. Dimensions, transparency, composition, camera, quantity, subject count, and silhouette requirements come from the manifest. Transparent single-subject outputs receive alpha extraction, occupancy normalization, and subject-count checks. Opaque outputs are checked for unwanted transparency. Seamless requests receive an opposite-edge similarity check. Other compositions are not incorrectly rejected for containing multiple subjects.
 
-Generated sprites receive automated dimension, alpha-channel, corner-transparency, and significant-foreground-component checks. A multi-subject sprite is rejected and regenerated with a fresh model seed rather than cropped or procedurally rearranged. These checks do not establish semantic or artistic correctness, so every role also has a manual approval control and per-role regeneration.
+The image model can still violate these instructions, so every result requires visual review. Single-subject outputs that fail automated checks are regenerated with a fresh seed rather than cropped into a guessed subject. The review UI can regenerate one output or a complete multi-output asset set.
 
-The UI reports the configured prompt and image pipeline and labels every role with its actual source. Every asset carries a normalized camera contract (`top_down`, `side_view`, `isometric`, `first_person`, or `front_view`). Top-down background prompts explicitly forbid a sky, horizon, eye-level view, and front-facing facades.
+The UI reports the configured prompt and image pipeline and labels every output with its actual source. Every asset carries a normalized camera contract (`top_down`, `side_view`, `isometric`, `first_person`, or `front_view`) or retains an explicit custom camera instruction. Top-down prompts explicitly forbid a sky, horizon, eye-level view, and front-facing facades.
 
-The public production path uses diffusion rather than procedural drawing. Diffusion provides much better open-ended subject and style fidelity but can still miss perspective, 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. A procedural renderer remains available only for local development when fail-closed production mode is disabled.
+The public production path uses diffusion rather than procedural drawing. Diffusion provides much better open-ended subject and style fidelity but can still miss perspective, alpha, seamless-edge, or layout constraints. Negative prompts are selected from the explicit composition contract; full-frame and freeform images are not forced to be empty environments, while single-subject outputs reject contact sheets and duplicates. A procedural renderer remains available only for local development when fail-closed production mode is disabled.
 
-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.
+The app combines the game type, perspective, theme, pasted code, and manifest into explicit per-output image prompts, then generates PNG assets and embeds contract-compatible assets as base64 data URIs.
 
-If the Space has an `HF_TOKEN` secret and `USE_HF_PROMPT_PROVIDER=1`, 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`. The camera contract is appended after model interpretation, so the model cannot silently remove it.
+If the Space has an `HF_TOKEN` secret and `USE_HF_PROMPT_PROVIDER=1`, it first uses the text model in `HF_PROMPT_MODEL` to interpret the code, requested assets, and theme into image prompts. The default prompt model is `Qwen/Qwen2.5-Coder-7B-Instruct`. The technical output contract is appended after model interpretation, so the model cannot silently remove it.
 
 ## Default neural image pipeline
 
@@ -70,7 +97,7 @@ The deployed Space is fail-closed: if the primary neural model cannot run, gener
 
 ZeroGPU is free for eligible personal accounts, but it is quota-limited rather than unlimited: free accounts currently receive five minutes of GPU time per day. Queueing or a quota message is therefore possible even though no inference credits or payment are required.
 
-Initial generation uses a dynamic ZeroGPU duration estimate based on the number of separate asset roles, while one-role regeneration reserves a smaller fixed window. This changes only scheduler reservation and queue priority; it does not reduce diffusion steps or image quality. The estimator avoids rejecting short jobs merely because an unnecessarily large fixed duration exceeds the visitor's remaining quota.
+Initial generation and regeneration use dynamic ZeroGPU duration estimates based on the number of independent outputs. This changes only scheduler reservation and queue priority; it does not reduce diffusion steps or image quality. The estimator avoids rejecting short jobs merely because an unnecessarily large fixed duration exceeds the visitor's remaining quota.
 
 The primary pipeline can be configured with:
 

app.py

@@ -45,9 +45,9 @@ STARTER_HTML = """<!DOCTYPE html>
     const ctx = canvas.getContext("2d");
 
     const background = new Image();
-    background.src = "sprite_background.png";
+    background.src = "sprite_forest_clearing.png";
     const playerImg = new Image();
-    playerImg.src = "sprite_player.png";
+    playerImg.src = "sprite_forest_adventurer.png";
 
     const keys = new Set();
     const player = { x: 380, y: 205, w: 48, h: 48, speed: 4 };
@@ -83,13 +83,46 @@ STARTER_HTML = """<!DOCTYPE html>
 </html>"""
 
 
-DEFAULT_ROLES = """player: top-down pixel-art adventurer hero, transparent background, bright readable silhouette
-background: enchanted forest clearing game background, top-down view, soft moonlight, detailed but not too busy"""
-
-ROLE_PLACEHOLDER = """player: blue robot hero sprite
-enemy_grunt: compact orange patrol robot
-enemy_boss: towering red armored commander
-background: empty space station floor map"""
+DEFAULT_ROLES = """{
+  "assets": [
+    {
+      "id": "forest_adventurer",
+      "description": "top-down pixel-art adventurer with a bright readable silhouette",
+      "quantity": 1,
+      "width": 128,
+      "height": 128,
+      "transparent": true,
+      "composition": "single_subject",
+      "camera": "top-down"
+    },
+    {
+      "id": "forest_clearing",
+      "description": "enchanted forest clearing with soft moonlight and readable traversal space",
+      "quantity": 1,
+      "width": 800,
+      "height": 450,
+      "transparent": false,
+      "composition": "full_frame",
+      "camera": "top-down"
+    }
+  ]
+}"""
+
+ROLE_PLACEHOLDER = """{
+  "assets": [
+    {
+      "id": "asset_name_used_by_game_code",
+      "description": "Describe exactly what should be generated",
+      "quantity": 1,
+      "width": 256,
+      "height": 256,
+      "transparent": true,
+      "composition": "single_subject",
+      "camera": "top-down",
+      "variations": "Optional instructions that distinguish multiple outputs"
+    }
+  ]
+}"""
 
 
 @dataclass
@@ -100,6 +133,15 @@ class AssetSpec:
     width: int
     height: int
     camera: str = "auto"
+    group: str = ""
+    variant_index: int = 1
+    total_variants: int = 1
+    transparent: bool = True
+    composition: str = "single_subject"
+    camera_instruction: str = "auto"
+    variation: str = ""
+    expected_subjects: int | None = 1
+    silhouette: str = "any"
 
 
 @dataclass
@@ -336,30 +378,78 @@ def interpret_style_hint(style_hint: str) -> StylePlan:
     return StylePlan(medium, palette, texture, lighting, linework, camera, tuple(tags))
 
 
-def build_asset_prompt(role: str, prompt: str, style_hint: str) -> str:
+SUPPORTED_COMPOSITIONS = {
+    "single_subject",
+    "full_frame",
+    "seamless",
+    "icon",
+    "animation_frame",
+    "sprite_sheet",
+    "freeform",
+}
+MAX_GENERATED_ASSETS = max(1, int(os.environ.get("MAX_GENERATED_ASSETS", "8")))
+
+
+class AssetManifestError(ValueError):
+    pass
+
+
+def composition_instruction(composition: str, transparent: bool) -> str:
+    instructions = {
+        "single_subject": (
+            "Create exactly one complete standalone subject in one pose. Center it, keep it fully visible, and make "
+            "it fill about eighty percent of the frame with modest even margins."
+        ),
+        "icon": "Create one centered readable icon with a strong silhouette and generous safe margins.",
+        "animation_frame": (
+            "Create one isolated animation frame with one complete subject, a stable scale, and consistent anchoring."
+        ),
+        "full_frame": "Create one complete edge-to-edge image that fills the entire canvas.",
+        "seamless": "Create one edge-to-edge seamless tile whose opposite edges repeat cleanly.",
+        "sprite_sheet": (
+            "Create one deliberately organized sprite sheet on a regular grid. Keep every cell aligned, equally sized, "
+            "and free of labels."
+        ),
+        "freeform": "Follow the requested composition exactly without adding labels or presentation mockups.",
+    }
+    alpha_instruction = (
+        "Use a clean uniform white studio field so the requested transparent cutout can be extracted."
+        if transparent
+        else "Use an opaque edge-to-edge presentation with no transparent holes."
+    )
+    return f"{instructions[composition]} {alpha_instruction}"
+
+
+def build_asset_prompt(
+    role: str,
+    prompt: str,
+    style_hint: str,
+    *,
+    transparent: bool | None = None,
+    composition: str | None = None,
+    camera_instruction: str = "",
+    variation: str = "",
+) -> str:
     plan = interpret_style_hint(style_hint)
-    camera = normalize_camera(f"{style_hint} {prompt}")
-    slug = slugify(role)
-    is_background = any(word in slug for word in ("background", "backdrop", "scene", "map", "level"))
-    if is_background:
-        asset_instruction = (
-            "Create one complete 2D game background scene, not a texture tile, not a material sample, "
-            "not a UV map. Full scene composition for a canvas game. Empty environment only: no player, "
-            "no character, no creature, no vehicle, no mascot, no foreground subject."
-        )
-    else:
-        asset_instruction = (
-            "Create a complete standalone 2D game character or object as a single centered subject. "
-            "Present one complete body in one pose from the required camera direction. Make the visible subject fill "
-            "about eighty percent of the frame with modest even margins. Use a clean uniform white studio field and "
-            "a readable game-scale silhouette."
-        )
+    if transparent is None or composition is None:
+        slug = slugify(role)
+        legacy_full_frame = any(word in slug for word in ("background", "backdrop", "scene", "map", "level"))
+        transparent = not legacy_full_frame if transparent is None else transparent
+        composition = ("full_frame" if legacy_full_frame else "single_subject") if composition is None else composition
+    camera_text = camera_instruction or f"{style_hint} {prompt}"
+    camera = normalize_camera(camera_text)
+    full_frame = composition in {"full_frame", "seamless", "sprite_sheet"} or not transparent
+    camera_contract = camera_prompt_contract(camera, full_frame)
+    if camera == "auto" and camera_instruction and camera_instruction.lower() != "auto":
+        camera_contract = f"Use this exact user-defined camera instruction: {camera_instruction}."
+    variation_instruction = f"Variation requirement: {variation}." if variation else ""
     return (
         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"Camera contract: {camera_prompt_contract(camera, is_background)} "
-        f"{asset_instruction} "
+        f"Camera contract: {camera_contract} "
+        f"Output contract: {composition_instruction(composition, transparent)} "
+        f"{variation_instruction} "
         "Game asset, readable at small size, with a clean unlabeled presentation."
     )
 
@@ -376,22 +466,63 @@ def build_style_context(game_type: str, perspective: str, theme: str) -> str:
     return ". ".join(parts) or "cohesive game-ready 2D art"
 
 
+def _coerce_manifest_bool(value, field: str) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str) and value.strip().lower() in {"true", "yes", "1"}:
+        return True
+    if isinstance(value, str) and value.strip().lower() in {"false", "no", "0"}:
+        return False
+    raise AssetManifestError(f"`{field}` must be true or false.")
+
+
+def parse_asset_entries(raw_roles: str) -> tuple[list[dict], bool]:
+    """Parse the recommended JSON manifest or the backwards-compatible role syntax."""
+    raw = (raw_roles or "").strip()
+    if not raw:
+        return [], False
+    if not raw.startswith(("{", "[")):
+        entries = []
+        for line in raw.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if ":" in line:
+                role, prompt = line.split(":", 1)
+            elif "=" in line:
+                role, prompt = line.split("=", 1)
+            else:
+                role, prompt = line, line
+            role = role.strip()
+            entries.append({"id": role, "description": prompt.strip() or role, "legacy": True})
+        return entries, False
+
+    try:
+        document = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise AssetManifestError(f"Asset manifest is not valid JSON: line {exc.lineno}, column {exc.colno}.") from exc
+    items = document.get("assets") if isinstance(document, dict) else document
+    if not isinstance(items, list):
+        raise AssetManifestError("Asset manifest must be a JSON array or an object containing an `assets` array.")
+    entries = []
+    for index, item in enumerate(items, 1):
+        if not isinstance(item, dict):
+            raise AssetManifestError(f"Asset {index} must be a JSON object.")
+        asset_id = str(item.get("id") or item.get("name") or item.get("role") or "").strip()
+        description = str(item.get("description") or item.get("prompt") or "").strip()
+        if not asset_id:
+            raise AssetManifestError(f"Asset {index} is missing a non-empty `id`.")
+        if not description:
+            raise AssetManifestError(f"Asset `{asset_id}` is missing a non-empty `description`.")
+        entries.append({**item, "id": asset_id, "description": description, "legacy": False})
+    return entries, True
+
+
 def parse_role_lines(raw_roles: str) -> list[tuple[str, str]]:
+    entries, _ = parse_asset_entries(raw_roles)
     parsed: list[tuple[str, str]] = []
-    for line in raw_roles.splitlines():
-        line = line.strip()
-        if not line or line.startswith("#"):
-            continue
-
-        if ":" in line:
-            role, prompt = line.split(":", 1)
-        elif "=" in line:
-            role, prompt = line.split("=", 1)
-        else:
-            role, prompt = line, line
-        role = role.strip()
-        prompt = prompt.strip() or role
-        parsed.append((role, prompt))
+    for entry in entries:
+        parsed.append((entry["id"], entry["description"]))
     return parsed
 
 
@@ -463,7 +594,8 @@ def infer_code_context(html_code: str) -> str:
 
 
 def local_prompt_map(role_lines: list[tuple[str, str]], style_hint: str) -> dict[str, str]:
-    return {role: build_asset_prompt(role, prompt, style_hint) for role, prompt in role_lines}
+    del style_hint
+    return {role: prompt for role, prompt in role_lines}
 
 
 def extract_json_object(text: str) -> dict | None:
@@ -495,12 +627,11 @@ def hf_prompt_json(html_code: str, role_lines: list[tuple[str, str]], style_hint
     role_block = "\n".join(f"- {role}: {prompt}" for role, prompt in role_lines)
     instruction = (
         "You are a senior game art director and prompt engineer. Read the HTML game context, "
-        "the requested asset roles, and the shared theme/style. Return ONLY a JSON object where "
+        "the requested user-defined assets, and the shared theme/style. Return ONLY a JSON object where "
         "each key is the exact role name and each value is one concise text-to-image prompt. "
-        "Each prompt must specify: subject silhouette/shape, camera angle, art style, palette, "
-        "transparent background for sprites/items, full scene for backgrounds, no text, no watermark. "
-        "Make different roles visually distinct and suitable for embedding in an HTML game. "
-        "Describe only one role per prompt; never combine multiple character roles into one image."
+        "Preserve the user's requested subject and make different assets visually distinct. Do not guess an asset "
+        "category from its name. The application will append the exact camera, composition, dimensions, alpha, and "
+        "quantity contracts after your response. Never combine different requested assets into one image."
     )
     user_text = (
         f"HTML/game context summary: {infer_code_context(html_code)}\n\n"
@@ -572,40 +703,131 @@ def parse_assets(
     prompt_map: dict[str, str] | None = None,
     role_lines: list[tuple[str, str]] | None = None,
 ) -> list[AssetSpec]:
+    entries, explicit_manifest = parse_asset_entries(raw_roles)
+    entries_by_slug = {slugify(entry["id"]): entry for entry in entries}
     specs: list[AssetSpec] = []
     for role, prompt in role_lines if role_lines is not None else parse_role_lines(raw_roles):
-        slug = slugify(role)
-        is_background = any(word in slug for word in ("background", "backdrop", "scene", "map", "level"))
-        width, height = (800, 450) if is_background else (128, 128)
-        filename = f"sprite_{slug}.png"
-        camera = normalize_camera(f"{style_hint} {prompt}")
-        interpreted_prompt = (prompt_map or {}).get(role)
-        if interpreted_prompt:
-            full_prompt = interpreted_prompt
-            if "camera contract:" not in interpreted_prompt.lower():
-                full_prompt = (
-                    f"{interpreted_prompt}. Camera contract: {camera_prompt_contract(camera, is_background)} "
-                    "Game asset, no text, no watermark."
+        group = slugify(role)
+        entry = entries_by_slug.get(group)
+        if entry is None:
+            entry = {"id": role, "description": prompt, "legacy": True}
+        legacy = bool(entry.get("legacy"))
+        if legacy:
+            legacy_full_frame = any(
+                word in group for word in ("background", "backdrop", "scene", "map", "level")
+            )
+            transparent = not legacy_full_frame
+            composition = "full_frame" if legacy_full_frame else "single_subject"
+            width, height = (800, 450) if legacy_full_frame else (128, 128)
+            expected_subjects = None if legacy_full_frame else 1
+            silhouette = (
+                "humanoid"
+                if contains_any_term(
+                    f"{role} {prompt}",
+                    ("player", "hero", "enemy", "boss", "npc", "character", "ranger", "knight", "adventurer"),
                 )
+                else "any"
+            )
         else:
-            full_prompt = build_asset_prompt(role, prompt, style_hint)
-        specs.append(
-            AssetSpec(
-                role=role,
-                prompt=full_prompt,
-                filename=filename,
-                width=width,
-                height=height,
-                camera=camera,
+            transparent = _coerce_manifest_bool(entry.get("transparent", True), f"{group}.transparent")
+            composition = str(entry.get("composition") or ("single_subject" if transparent else "full_frame"))
+            composition = slugify(composition)
+            if composition not in SUPPORTED_COMPOSITIONS:
+                allowed = ", ".join(sorted(SUPPORTED_COMPOSITIONS))
+                raise AssetManifestError(
+                    f"Asset `{group}` has unsupported composition `{composition}`. Choose one of: {allowed}."
+                )
+            default_size = (800, 450) if composition == "full_frame" else (256, 256)
+            try:
+                width = int(entry.get("width", default_size[0]))
+                height = int(entry.get("height", default_size[1]))
+            except (TypeError, ValueError) as exc:
+                raise AssetManifestError(f"Asset `{group}` width and height must be integers.") from exc
+            if not (32 <= width <= 2048 and 32 <= height <= 2048):
+                raise AssetManifestError(f"Asset `{group}` dimensions must each be between 32 and 2048 pixels.")
+            expected_value = entry.get("expected_subjects")
+            if expected_value is None:
+                expected_subjects = 1 if composition in {"single_subject", "icon", "animation_frame"} else None
+            else:
+                try:
+                    expected_subjects = int(expected_value)
+                except (TypeError, ValueError) as exc:
+                    raise AssetManifestError(f"Asset `{group}` expected_subjects must be an integer.") from exc
+                if not (1 <= expected_subjects <= 16):
+                    raise AssetManifestError(f"Asset `{group}` expected_subjects must be between 1 and 16.")
+            silhouette = slugify(str(entry.get("silhouette") or "any"))
+            if silhouette not in {"any", "humanoid"}:
+                raise AssetManifestError(f"Asset `{group}` silhouette must be `any` or `humanoid`.")
+        try:
+            quantity = int(entry.get("quantity", 1))
+        except (TypeError, ValueError) as exc:
+            raise AssetManifestError(f"Asset `{group}` quantity must be an integer.") from exc
+        if not (1 <= quantity <= MAX_GENERATED_ASSETS):
+            raise AssetManifestError(
+                f"Asset `{group}` quantity must be between 1 and {MAX_GENERATED_ASSETS}; use multiple batches for larger sets."
+            )
+        camera_instruction = str(entry.get("camera") or "").strip()
+        if not camera_instruction or camera_instruction.lower() in {"inherit", "shared", "auto"}:
+            camera_instruction = style_hint
+        camera = normalize_camera(camera_instruction)
+        variation = str(entry.get("variations") or entry.get("variation") or "").strip()
+        base_filename = str(entry.get("filename") or f"sprite_{group}.png").strip()
+        if not re.fullmatch(r"[a-zA-Z0-9_.-]+\.png", base_filename, flags=re.I):
+            raise AssetManifestError(
+                f"Asset `{group}` filename must be a simple PNG filename without folders."
             )
+        interpreted_prompt = (prompt_map or {}).get(role) or prompt
+        for variant_index in range(1, quantity + 1):
+            output_role = group if quantity == 1 else f"{group}_{variant_index:02d}"
+            stem, extension = base_filename.rsplit(".", 1)
+            filename = base_filename if quantity == 1 else f"{stem}_{variant_index:02d}.{extension}"
+            variant_direction = variation
+            if quantity > 1:
+                variant_direction = (
+                    f"Output {variant_index} of {quantity}. Make it recognizably different from the other outputs"
+                    + (f"; {variation}" if variation else ".")
+                )
+            full_prompt = build_asset_prompt(
+                output_role,
+                interpreted_prompt,
+                style_hint,
+                transparent=transparent,
+                composition=composition,
+                camera_instruction=camera_instruction,
+                variation=variant_direction,
+            )
+            specs.append(
+                AssetSpec(
+                    role=output_role,
+                    prompt=full_prompt,
+                    filename=filename,
+                    width=width,
+                    height=height,
+                    camera=camera,
+                    group=group,
+                    variant_index=variant_index,
+                    total_variants=quantity,
+                    transparent=transparent,
+                    composition=composition,
+                    camera_instruction=camera_instruction,
+                    variation=variant_direction,
+                    expected_subjects=expected_subjects,
+                    silhouette=silhouette,
+                )
+            )
+    if len(specs) > MAX_GENERATED_ASSETS:
+        raise AssetManifestError(
+            f"This request expands to {len(specs)} images. The free ZeroGPU batch limit is {MAX_GENERATED_ASSETS}; "
+            "reduce quantities and generate the remainder in another batch."
         )
     return specs
 
 
 def is_background_spec(spec: AssetSpec) -> bool:
-    slug = slugify(spec.role)
-    return spec.width > spec.height * 2 or any(
-        word in slug for word in ("background", "backdrop", "scene", "map", "level")
+    """Compatibility name for assets that should not use single-cutout post-processing."""
+    return not (
+        spec.transparent
+        and spec.composition in {"single_subject", "icon", "animation_frame"}
     )
 
 
@@ -1620,23 +1842,23 @@ def diffusion_dimensions(spec: AssetSpec) -> tuple[int, int]:
 
 
 def diffusion_negative_prompt(spec: AssetSpec) -> str:
-    if is_background_spec(spec):
-        camera_negative = {
-            "top_down": ", sky, horizon, eye-level view, front view, front-facing facade, vanishing point",
-            "isometric": ", eye-level view, front view, inconsistent perspective, horizon",
-            "side_view": ", overhead view, top-down view, isometric view",
-        }.get(spec.camera, "")
+    camera_negative = {
+        "top_down": ", sky, horizon, eye-level view, front view, front-facing facade, vanishing point",
+        "isometric": ", eye-level view, front view, inconsistent perspective, horizon",
+        "side_view": ", overhead view, top-down view, isometric view",
+    }.get(spec.camera, "")
+    if spec.composition in {"single_subject", "icon", "animation_frame"}:
         return (
-            "person, character, player, hero, creature, monster, vehicle, mascot, foreground subject, "
-            "particle effect, particles, confetti, sparkles, floating dots, glowing orbs, embers, lens flare, "
-            "texture map, tiled pattern, uv map, text, watermark"
+            "multiple subjects, duplicate character, duplicate subject, repeated subject, character sheet, model sheet, turnaround, "
+            "lineup, alternate views, multiple poses, multiple views, pair, group, cropped subject, scenery, landscape, "
+            "room, ground, floor, background props, drop shadow, text, watermark"
             + camera_negative
         )
-    return (
-        "multiple subjects, duplicate character, repeated character, character sheet, model sheet, turnaround, "
-        "lineup, alternate views, multiple poses, multiple views, pair, group, cropped body, scenery, landscape, "
-        "room, trees, foliage, ground, floor, background props, drop shadow, texture map, tiled pattern, text, watermark"
-    )
+    if spec.composition == "seamless":
+        return "visible seams, borders, frame, perspective mockup, text, watermark" + camera_negative
+    if spec.composition == "sprite_sheet":
+        return "irregular grid, overlapping cells, labels, text, watermark" + camera_negative
+    return "text, labels, watermark, presentation mockup" + camera_negative
 
 
 def build_camera_control_image(spec: AssetSpec, width: int = 1024, height: int = 576) -> Image.Image:
@@ -1728,18 +1950,38 @@ def initialize_primary_image_model() -> None:
 
 def primary_diffusion_prompt(spec: AssetSpec) -> str:
     camera = primary_camera_phrase(spec.camera, is_background_spec(spec))
-    if is_background_spec(spec):
-        description = compact_prompt_words(spec.prompt, 34)
+    if spec.camera == "auto" and spec.camera_instruction and spec.camera_instruction.lower() != "auto":
+        camera = f"User-defined camera: {compact_prompt_words(spec.camera_instruction, 10)}."
+    variation = f"Distinct variation: {compact_prompt_words(spec.variation, 8)}. " if spec.variation else ""
+    if spec.composition == "single_subject":
+        description = compact_prompt_words(spec.prompt, 12 if variation else 18)
+        subject = (spec.group or spec.role).replace("_", " ")
         return (
-            f"{camera} Empty playable 2D game environment with connected terrain and clear gameplay space. "
-            f"{description}"
+            f"{camera} Single isolated {subject} subject. One complete body, one pose, centered and fully visible. "
+            f"Fill about eighty percent of the frame with modest even margins on a uniform white field. "
+            f"{variation}{description}"
         )
-    description = compact_prompt_words(spec.prompt, 18)
-    subject = spec.role.replace("_", " ")
-    return (
-        f"{camera} Single isolated {subject} subject. One complete body, one pose, centered and fully visible. "
-        f"Fill about eighty percent of the frame with modest even margins on a uniform white field. {description}"
-    )
+    description = compact_prompt_words(spec.prompt, 26 if variation else 34)
+    composition = {
+        "icon": "Exactly one centered readable game icon, uniform white field.",
+        "animation_frame": "Exactly one isolated animation frame subject at stable scale, uniform white field.",
+        "full_frame": "One complete edge-to-edge game image filling the canvas.",
+        "seamless": "One seamless edge-to-edge repeating game-art tile.",
+        "sprite_sheet": "One deliberately organized regular-grid sprite sheet.",
+        "freeform": "One user-defined game image following the requested composition exactly.",
+    }[spec.composition]
+    return f"{camera} {composition} {variation}{description}"
+
+
+def primary_generation_dimensions(spec: AssetSpec) -> tuple[int, int]:
+    if not is_background_spec(spec):
+        return 768, 1024
+    aspect = spec.width / max(1, spec.height)
+    if aspect >= 1.35:
+        return 1344, 768
+    if aspect <= 0.74:
+        return 768, 1024
+    return 1024, 1024
 
 
 def primary_diffusion_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes | None, str | None]:
@@ -1756,7 +1998,7 @@ def primary_diffusion_png(spec: AssetSpec, index: int, run_id: int) -> tuple[byt
 
         is_background = is_background_spec(spec)
         attempts = 1 if is_background else PRIMARY_SPRITE_ATTEMPTS
-        width, height = (1344, 768) if is_background else (768, 1024)
+        width, height = primary_generation_dimensions(spec)
         last_failure_detail = "the last output did not contain one valid foreground subject"
         for attempt in range(attempts):
             seed = abs(hash(f"primary|{spec.role}|{spec.prompt}|{index}|{run_id}|{attempt}")) % 2147483647
@@ -1851,10 +2093,9 @@ def controlnet_background_png(spec: AssetSpec, index: int, run_id: int) -> tuple
 
 def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
     image = image.convert("RGBA")
-    if not is_background_spec(spec):
+    if spec.transparent:
         # Text-to-image models do not produce real transparency. This makes sprites
-        # usable by fading out colors similar to the generated corner background.
-        # Preserve the model's portrait composition instead of stretching it square.
+        # and other requested cutouts usable by removing corner-matched color.
         corner_source = image.resize((64, 64), Image.LANCZOS)
         source_corners = [
             corner_source.getpixel((0, 0)),
@@ -1864,15 +2105,15 @@ def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
         ]
         source_bg = tuple(sum(pixel[i] for pixel in source_corners) // len(source_corners) for i in range(3))
         contained = image.copy()
-        contained.thumbnail((128, 128), Image.LANCZOS)
-        small = Image.new("RGBA", (128, 128), (*source_bg, 255))
-        offset = ((128 - contained.width) // 2, (128 - contained.height) // 2)
+        contained.thumbnail((spec.width, spec.height), Image.LANCZOS)
+        small = Image.new("RGBA", (spec.width, spec.height), (*source_bg, 255))
+        offset = ((spec.width - contained.width) // 2, (spec.height - contained.height) // 2)
         small.alpha_composite(contained, dest=offset)
         corners = [
             small.getpixel((0, 0)),
-            small.getpixel((127, 0)),
-            small.getpixel((0, 127)),
-            small.getpixel((127, 127)),
+            small.getpixel((small.width - 1, 0)),
+            small.getpixel((0, small.height - 1)),
+            small.getpixel((small.width - 1, small.height - 1)),
         ]
         bg = tuple(sum(pixel[i] for pixel in corners) // len(corners) for i in range(3))
         pixels = small.load()
@@ -1886,7 +2127,11 @@ def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
                 elif dist < 125:
                     a = max(0, min(a, (dist - 64) * 4))
                 pixels[x, y] = (r, g, b, a)
-        image = normalize_sprite_foreground(small, spec)
+        image = (
+            normalize_sprite_foreground(small, spec)
+            if spec.composition in {"single_subject", "icon", "animation_frame"}
+            else small
+        )
     else:
         image = image.resize((spec.width, spec.height), Image.LANCZOS)
     out = io.BytesIO()
@@ -2066,7 +2311,7 @@ def estimated_foreground_subject_count(content: bytes) -> int:
 
 def has_implausibly_thin_foreground_subject(content: bytes, spec: AssetSpec) -> bool:
     """Reject collapsed humanoid silhouettes without penalizing projectiles or narrow props."""
-    if sprite_archetype(spec) not in ("humanoid", "enemy"):
+    if spec.silhouette != "humanoid":
         return False
     components = foreground_component_geometry(content)
     if not components:
@@ -2276,10 +2521,15 @@ def replacement_names(spec: AssetSpec) -> set[str]:
 
 def code_references_role(html_code: str, spec: AssetSpec) -> bool:
     slug = slugify(spec.role)
-    escaped_slug = re.escape(slug)
+    group = slugify(spec.group or spec.role)
+    hook_names = {slug, group}
     hook_patterns = (
-        rf"(?:window\.)?GAME_ASSETS\s*\.\s*{escaped_slug}\b",
-        rf"(?:window\.)?GAME_ASSETS\s*\[\s*['\"]{escaped_slug}['\"]\s*\]",
+        pattern
+        for hook_name in hook_names
+        for pattern in (
+            rf"(?:window\.)?GAME_ASSETS\s*\.\s*{re.escape(hook_name)}\b",
+            rf"(?:window\.)?GAME_ASSETS\s*\[\s*['\"]{re.escape(hook_name)}['\"]\s*\]",
+        )
     )
     if any(re.search(pattern, html_code, flags=re.I) for pattern in hook_patterns):
         return True
@@ -2323,14 +2573,14 @@ def validate_asset_png(content: bytes, spec: AssetSpec) -> list[str]:
         warnings.append(f"unexpected dimensions {image.width}x{image.height}")
     alpha = image.getchannel("A")
     extrema = alpha.getextrema()
-    if is_background_spec(spec):
+    if not spec.transparent:
         if extrema[0] < 255:
-            warnings.append("background contains transparency")
+            warnings.append("opaque output 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")
+            warnings.append("transparent output does not contain enough transparent area")
         corners = (
             alpha.getpixel((0, 0)),
             alpha.getpixel((image.width - 1, 0)),
@@ -2338,16 +2588,29 @@ def validate_asset_png(content: bytes, spec: AssetSpec) -> list[str]:
             alpha.getpixel((image.width - 1, image.height - 1)),
         )
         if any(value > 16 for value in corners):
-            warnings.append("sprite has opaque corner pixels")
-        subject_count = estimated_foreground_subject_count(content)
-        if not subject_count:
-            warnings.append("sprite has no significant foreground subject")
-        elif subject_count > 1:
-            warnings.append(f"sprite contains {subject_count} significant foreground subjects")
-        elif has_implausibly_thin_foreground_subject(content, spec):
-            warnings.append("sprite foreground silhouette is implausibly thin")
-        elif has_undersized_foreground_subject(content):
-            warnings.append("sprite foreground occupies too little of the sprite canvas")
+            warnings.append("transparent output has opaque corner pixels")
+        if spec.expected_subjects is not None:
+            subject_count = estimated_foreground_subject_count(content)
+            if subject_count != spec.expected_subjects:
+                warnings.append(
+                    f"expected {spec.expected_subjects} significant foreground subject(s), found {subject_count}"
+                )
+            elif spec.expected_subjects == 1 and has_implausibly_thin_foreground_subject(content, spec):
+                warnings.append("sprite foreground silhouette is implausibly thin")
+            elif spec.expected_subjects == 1 and has_undersized_foreground_subject(content):
+                warnings.append("foreground subject occupies too little of the output canvas")
+    if spec.composition == "seamless" and image.width > 1 and image.height > 1:
+        pixels = image.convert("RGB")
+        horizontal_error = sum(
+            sum(abs(a - b) for a, b in zip(pixels.getpixel((0, y)), pixels.getpixel((image.width - 1, y))))
+            for y in range(image.height)
+        ) / (image.height * 3 * 255)
+        vertical_error = sum(
+            sum(abs(a - b) for a, b in zip(pixels.getpixel((x, 0)), pixels.getpixel((x, image.height - 1))))
+            for x in range(image.width)
+        ) / (image.width * 3 * 255)
+        if max(horizontal_error, vertical_error) > 0.16:
+            warnings.append("opposite edges differ too much for a reliable seamless tile")
     return warnings
 
 
@@ -2358,12 +2621,16 @@ def embed_assets(html_code: str, assets: dict[str, str], specs: list[AssetSpec])
 
     output = html_code
     manifest_lines = ["<!-- Embedded game assets generated by Image Generator for HTML Games"]
-    asset_map: dict[str, str] = {}
+    asset_map: dict[str, str | list[str]] = {}
+    grouped_assets: dict[str, list[tuple[int, str]]] = {}
 
     for spec in specs:
         data_uri = assets[spec.role]
         slug = slugify(spec.role)
-        asset_map[slug] = data_uri
+        group = slugify(spec.group or spec.role)
+        grouped_assets.setdefault(group, []).append((spec.variant_index, data_uri))
+        if spec.total_variants > 1:
+            asset_map[slug] = data_uri
         manifest_lines.append(f"{spec.role}: {spec.filename}")
         for name in replacement_names(spec):
             output = output.replace(f'"{name}"', f'"{data_uri}"')
@@ -2371,12 +2638,19 @@ def embed_assets(html_code: str, assets: dict[str, str], specs: list[AssetSpec])
             if name.startswith("{"):
                 output = output.replace(name, data_uri)
 
+    for group, variants in grouped_assets.items():
+        ordered = [data_uri for _, data_uri in sorted(variants)]
+        asset_map[group] = ordered if len(ordered) > 1 else ordered[0]
+
     manifest_lines.append("-->")
     manifest = "\n".join(manifest_lines) + "\n"
     asset_json = json.dumps(asset_map)
     helper_script = f"""<script>
 (function () {{
   var ASSETS = {asset_json};
+  Object.keys(ASSETS).forEach(function (key) {{
+    if (Array.isArray(ASSETS[key])) Object.freeze(ASSETS[key]);
+  }});
   window.GAME_ASSETS = Object.freeze(Object.assign({{}}, window.GAME_ASSETS || {{}}, ASSETS));
   window.GENERATED_GAME_ASSETS = ASSETS;
 }})();
@@ -2482,12 +2756,13 @@ def model_configuration_summary() -> str:
         readiness = "loads in the deployed ZeroGPU runtime"
     return (
         "**Configured model pipeline:** "
-        f"prompts: `{prompt_source}` · sprites: `{sprite_source}` · backgrounds: `{background_source}` · "
+        f"prompts: `{prompt_source}` · transparent single-subject contracts: `{sprite_source}` · "
+        f"full-frame/freeform contracts: `{background_source}` · "
         f"remote image fallback: `{remote_fallback}` · neural image models: `{neural_status}` · "
         f"neural enforcement: `{enforcement}` · primary readiness: `{readiness}`. "
         "Every production image is generated directly from its written prompt by the primary text-to-image model. "
-        "Critical camera and subject constraints are placed first inside a conservative CLIP prompt budget. "
-        "Sprite foregrounds are tightly normalized to a consistent game-canvas occupancy, then must pass subject-count, "
+        "The user-defined composition and camera contract is placed first inside a conservative CLIP prompt budget. "
+        "Transparent single-subject foregrounds are normalized to the requested canvas, then pass configured subject-count, "
         "silhouette, and scale validation; failures are regenerated with a new seed up to "
         f"{PRIMARY_SPRITE_ATTEMPTS} times. No procedural guide is supplied to the model. The procedural renderer is "
         "development-only and is blocked in the deployed Space when the primary model fails."
@@ -2518,18 +2793,19 @@ def render_generation_state(state: dict, action: str, errors: list[str] | None =
         (spec.role, state["prompt_model"], state["image_models"][spec.role])
         for spec in specs
     ]
+    asset_set_count = len({spec.group or 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"{action} {len(specs)} output(s) across {asset_set_count} custom asset set(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 "
+            f"{action} {len(specs)} output(s) across {asset_set_count} custom asset set(s), but did not rewrite the game because deterministic "
             "asset hooks are missing. The preview below is the unchanged original game."
         )
     if integration.warnings:
@@ -2537,7 +2813,7 @@ def render_generation_state(state: dict, action: str, errors: list[str] | None =
     inferred_roles = state.get("inferred_roles", [])
     if inferred_roles:
         status += (
-            "\n\n- Added separate asset roles from deterministic game-code hooks: "
+            "\n\n- Added backward-compatible asset specifications from deterministic game-code hooks: "
             + ", ".join(inferred_roles)
             + ". Add explicit descriptions for these roles to improve art direction."
         )
@@ -2581,9 +2857,16 @@ def estimate_generation_gpu_duration(
     theme: str,
 ) -> int:
     """Reserve realistic ZeroGPU time based on the number of independent assets."""
-    del game_type, perspective, theme
-    role_count = max(1, len(resolve_role_lines(html_code or "", roles or "")[0]))
-    return min(120, 30 + role_count * 18)
+    try:
+        style_context = build_style_context(game_type, perspective, theme)
+        role_lines, _ = resolve_role_lines(html_code or "", roles or "")
+        output_count = max(1, len(parse_assets(roles or "", style_context, role_lines=role_lines)))
+    except AssetManifestError:
+        try:
+            output_count = max(1, len(resolve_role_lines(html_code or "", roles or "")[0]))
+        except AssetManifestError:
+            output_count = 1
+    return min(120, 30 + output_count * 18)
 
 
 @gpu_task(duration=estimate_generation_gpu_duration)
@@ -2598,15 +2881,18 @@ def generate_images_and_game(
         return empty_generation_result("Paste HTML game code first.")
 
     style_context = build_style_context(game_type, perspective, theme)
-    role_lines, prompt_map, prompt_model, prompt_error, inferred_roles = build_prompt_map(
-        html_code,
-        roles,
-        style_context,
-    )
-    specs = parse_assets(roles, style_context, prompt_map, role_lines)
+    try:
+        role_lines, prompt_map, prompt_model, prompt_error, inferred_roles = build_prompt_map(
+            html_code,
+            roles,
+            style_context,
+        )
+        specs = parse_assets(roles, style_context, prompt_map, role_lines)
+    except AssetManifestError as exc:
+        return empty_generation_result(str(exc), html_code)
     if not specs:
         return empty_generation_result(
-            "Add at least one asset role, like `player: brave knight`.",
+            "Add at least one asset specification to the manifest.",
             html_code,
         )
     slugs = [slugify(spec.role) for spec in specs]
@@ -2650,16 +2936,38 @@ def generate_images_and_game(
         "run_id": run_id,
     }
     rendered = render_generation_state(state, "Generated", errors)
-    role_choices = [spec.role for spec in specs]
+    role_choices = regeneration_choices(specs)
+    approval_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=[]),
+        gr.Dropdown(choices=role_choices, value=specs[0].role),
+        gr.CheckboxGroup(choices=approval_choices, value=[]),
     )
 
 
-@gpu_task(duration=45)
+def regeneration_choices(specs: list[AssetSpec]) -> list:
+    choices: list = [spec.role for spec in specs]
+    groups: dict[str, int] = {}
+    for spec in specs:
+        group = spec.group or spec.role
+        groups[group] = groups.get(group, 0) + 1
+    choices.extend((f"All outputs: {group}", f"group::{group}") for group, count in groups.items() if count > 1)
+    return choices
+
+
+def estimate_regeneration_gpu_duration(state: dict, selected_role: str, approved_roles: list[str]) -> int:
+    del approved_roles
+    specs = (state or {}).get("specs", [])
+    if (selected_role or "").startswith("group::"):
+        group = selected_role.split("::", 1)[1]
+        count = sum(1 for spec in specs if (spec.group or spec.role) == group)
+    else:
+        count = 1
+    return min(120, 27 + max(1, count) * 18)
+
+
+@gpu_task(duration=estimate_regeneration_gpu_duration)
 def regenerate_selected_asset(state: dict, selected_role: str, approved_roles: list[str]):
     if not state or not selected_role:
         return (
@@ -2674,34 +2982,43 @@ def regenerate_selected_asset(state: dict, selected_role: str, approved_roles: l
             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:
+    if selected_role.startswith("group::"):
+        selected_group = selected_role.split("::", 1)[1]
+        indices = [i for i, spec in enumerate(specs) if (spec.group or spec.role) == selected_group]
+    else:
+        indices = [i for i, spec in enumerate(specs) if spec.role == selected_role]
+    if not indices:
         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()
-    try:
-        data_uri, gallery_path, error, image_model = generate_asset(spec, index, run_id)
-    except RuntimeError as exc:
-        rendered = render_generation_state(state, "Kept", [str(exc)])
-        roles = [item.role for item in specs]
-        return (
-            *rendered,
-            state,
-            gr.CheckboxGroup(choices=roles, value=approved_roles or []),
-        )
-    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)
+    errors = []
+    regenerated_roles = []
+    for index in indices:
+        spec = specs[index]
+        try:
+            data_uri, gallery_path, error, image_model = generate_asset(spec, index, run_id)
+        except RuntimeError as exc:
+            rendered = render_generation_state(state, "Kept", [str(exc)])
+            roles = [item.role for item in specs]
+            return (*rendered, state, gr.CheckboxGroup(choices=roles, value=approved_roles or []))
+        state["assets"][spec.role] = data_uri
+        state["gallery_paths"][spec.role] = gallery_path
+        state["image_models"][spec.role] = image_model
+        png_content = base64.b64decode(data_uri.split(",", 1)[1])
+        state["quality"][spec.role] = validate_asset_png(png_content, spec)
+        regenerated_roles.append(spec.role)
+        if error:
+            errors.append(f"{spec.role}: {error}")
     state["run_id"] = run_id
-    errors = [f"{selected_role}: {error}"] if error else []
-    rendered = render_generation_state(state, f"Regenerated {selected_role}; retained", errors)
+    rendered = render_generation_state(
+        state,
+        f"Regenerated {', '.join(regenerated_roles)}; retained",
+        errors,
+    )
     roles = [item.role for item in specs]
-    retained_approvals = [role for role in (approved_roles or []) if role != selected_role]
+    retained_approvals = [role for role in (approved_roles or []) if role not in regenerated_roles]
     return (
         *rendered,
         state,
@@ -2880,9 +3197,9 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
             <header class="hero">
               <div class="eyebrow">Game asset studio</div>
               <h1>Turn your game code into a visual world.</h1>
-              <p>Describe the art direction, generate camera-aware assets, and embed them into deterministic image hooks—without rewriting your game logic.</p>
+              <p>Define exactly which images your game needs, generate each output from its own technical contract, and embed them without rewriting your game logic.</p>
               <div class="hero-chips">
-                <span>Multiple character roles</span><span>Game-ready PNGs</span><span>Safe code integration</span>
+                <span>User-defined asset sets</span><span>Separate variations</span><span>Contract-checked PNGs</span>
               </div>
             </header>
             """
@@ -2892,7 +3209,7 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
 
         gr.HTML(
             '<div class="step-heading"><span>Step 01</span><h2>Set up your generation</h2>'
-            '<p>Paste the game first, then define the assets and shared art direction.</p></div>'
+            '<p>Paste the game, then describe any image types and quantities through an explicit asset manifest.</p></div>'
         )
         with gr.Row(equal_height=False):
             with gr.Column(scale=3, elem_classes=["studio-panel"]):
@@ -2901,17 +3218,18 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
                     lines=22,
                     placeholder="Paste your full HTML game code here.",
                     value=STARTER_HTML,
-                    info="Use GAME_ASSETS.<role> or sprite_<role>.png for deterministic embedding.",
+                    info="Use GAME_ASSETS.<asset_id>, GAME_ASSETS.<asset_id>[index], or an exact manifest filename.",
                 )
             with gr.Column(scale=2, elem_classes=["studio-panel"]):
                 roles = gr.Textbox(
-                    label="Assets to create",
-                    lines=8,
+                    label="Custom asset manifest (JSON)",
+                    lines=18,
                     placeholder=ROLE_PLACEHOLDER,
                     value=DEFAULT_ROLES,
                     info=(
-                        "One separate role per character or asset, for example player, enemy_grunt, and enemy_boss. "
-                        "Missing deterministic GAME_ASSETS roles are added from the submitted code."
+                        "Define any asset IDs and quantities. Each output gets an independent model call. Supported "
+                        "compositions: single_subject, full_frame, seamless, icon, animation_frame, sprite_sheet, "
+                        "and freeform. The older `name: description` format remains supported."
                     ),
                 )
                 with gr.Row():
@@ -2953,14 +3271,14 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
 
         gr.HTML(
             '<div class="step-heading"><span>Step 02</span><h2>Review generated assets</h2>'
-            '<p>Check subject, perspective, style, and transparency before approving an asset.</p></div>'
+            '<p>Check every independently generated output against its subject, perspective, composition, and alpha contract.</p></div>'
         )
         with gr.Row(equal_height=False):
             with gr.Column(scale=3, elem_classes=["studio-panel", "gallery-panel"]):
                 gallery = gr.Gallery(label="Generated assets", columns=2, height=420)
             with gr.Column(scale=2, elem_classes=["studio-panel"]):
                 selected_role = gr.Dropdown(
-                    label="Asset to regenerate",
+                    label="Output or complete asset set to regenerate",
                     choices=[],
                     interactive=True,
                 )
@@ -2997,7 +3315,7 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
                 interactive=False,
             )
             model_report = gr.Textbox(
-                label="Model/source used by role",
+                label="Model/source used by output",
                 lines=5,
                 interactive=False,
             )