Stitch Game Cover Pipeline

1. Check whether Stitch MCP is available

If Stitch MCP is available:

• use full pipeline mode

If Stitch MCP is unavailable:

• tell the user you can only run the HTML-only fallback
• continue only if the user already has a Stitch HTML export

If you need the exact full-pipeline execution order, read:

• references/stitch-mcp-runbook.md

2. Generate a Stitch experiment board

Do not start from a full business screen unless the user explicitly wants that.

For cover harvesting, ask Stitch for:

• a light mobile board
• a two-column grid
• 6-8 game cards
• one Chinese game name per card
• one standalone illustration per card
• one very short subtitle per card
• no continuous shared background
• no dark mode
• no heavy UI chrome

If you need prompt wording, read:

• references/prompt-templates.md

3. Read the screen exports before doing anything else

After the screen is generated, call get_screen.

You must read:

• htmlCode.downloadUrl
• screenshot.downloadUrl

If htmlCode.downloadUrl is missing, stop the full pipeline and regenerate instead of silently switching to screenshot cropping.

4. Download the HTML and screenshot locally

Use:

• scripts/download_stitch_exports.py

Inputs:

• the HTML download URL
• the screenshot download URL
• output directory
• optional project_id
• optional screen_id
• optional screen title

This script writes:

• local HTML export
• local screenshot export
• a screen metadata JSON file

5. Inspect the HTML before cropping anything

First check whether the HTML already contains reusable images.

Look for:

• <img src="https://...">
• background-image: url("https://...")

If direct image URLs exist, download them first. Do not crop a large screenshot if the HTML already exposes the images.

Use the bundled helper:

• scripts/extract_stitch_html_assets.py

6. Judge whether the experiment density is acceptable

Use this quick rule:

• 6 games: ideal
• 8 games: usually still safe
• 10+ games: high risk

Common failure mode when density is too high:

• illustrations collapse into icons
• cards keep text but lose unique artwork
• gradients replace real scene images

If the HTML contains 0 reusable images, assume the density or prompt is wrong and regenerate before doing manual cleanup.

7. Build a reviewable manifest skeleton

Use:

• scripts/build_cover_manifest.py

This script turns the extracted asset list into a reviewable manifest skeleton.

Expected fields include:

• index
• title
• game_id
• source_mode
• source_url
• downloaded_file
• output_file
• cover_image
• status
• notes

Default behavior:

• leave title and game_id empty
• set status to review
• carry through source_url and downloaded_file

8. Normalize and map carefully

After extraction:

1. review each image against the card title
2. remove weak matches
3. convert usable images into app-ready derivatives if the current project needs it
4. fill in the final manifest fields

Recommended delivery target:

• 320x320
• webp for app delivery
• png optional as backup/export format

Use three mapping levels:

• Exact match: title and image clearly match the official game
• Weak semantic match: image props match the official game closely enough
• No confident match: keep the asset unused and wait for a later batch

Never force a wrong match just to use every generated asset.

Decision Rules

Use direct download when

• Stitch HTML exposes direct image URLs
• each card has an independent illustration
• the image composition already works as a card thumbnail

Regenerate when

• htmlCode.downloadUrl is missing
• HTML exposes 0 reusable images
• the board density is too high
• Stitch has fallen back to icon-only cards

Use manual crop only when

• HTML exposes no reusable images
• HTML still exposes no reusable images after regeneration attempts
• one large scene contains multiple games
• direct images are too small or compositionally bad

Output Checklist

Before declaring the batch usable, verify:

1. the local HTML export exists
2. the extracted image count is non-zero
3. each used asset has a clear mapping rationale
4. unused assets are explicitly marked instead of silently discarded
5. the final cover_image paths match the target app runtime format

Resources

scripts/

• scripts/download_stitch_exports.py
  • Downloads Stitch HTML and screenshot exports locally
  • Writes screen metadata JSON
• scripts/extract_stitch_html_assets.py
  • Extracts direct image URLs from Stitch HTML exports
  • Optionally downloads them locally
• scripts/build_cover_manifest.py
  • Builds a reviewable manifest skeleton from extracted assets

references/

• references/prompt-templates.md
  • Ready-to-reuse prompt templates
  • Includes the full pipeline prompt, regeneration prompt, and tool checklist
• references/stitch-mcp-runbook.md
  • Exact execution order for Stitch MCP mode
  • Includes failure handling and expected outputs