Xiaoqishuo Card

Turn one supplied front cover into a complete card in the validated React, TypeScript, and Three.js experience. Never ask the user for a back image; use assets/three-kingdoms-back.png.

Required references

Read references/visual-spec.md before editing the app. Read references/asset-prompts.md before generating the foreground layer.

Workflow

1. Locate the target project.
   • Prefer the project in the current workspace when it contains src/App.tsx, package.json, and the existing CARDS registry.
   • If no compatible project exists, run python scripts/clone_starter.py --target <absolute-path> and install dependencies.
2. Inspect the supplied cover with the image viewer. Infer the character name and a lowercase hyphenated slug; ask only when the name cannot be determined reliably. Identify the complete foreground subject before extraction. When the character is mounted, the rider, mount, weapon, reins, saddle, tack, mount armor, and their natural overlap form one indivisible subject unless the user explicitly requests otherwise.
3. Preserve the cover non-destructively as public/assets/<slug>-front.png. Do not alter weapons, hands, text, identity, pose, or card composition unless the user explicitly requests that edit.
4. Create public/assets/<slug>-foreground.png with the exact extraction prompt in references/asset-prompts.md.
   • Use the built-in image generation edit path with the cover as the explicit referenced image.
   • Generate on flat #ff00ff, then run the installed imagegen remove_chroma_key.py helper.
   • Keep the generated key image only when useful for later correction.
5. Run scripts/validate_card_assets.py --front <front> --foreground <foreground>. Fix alignment, transparency, or dimensions before integration.
6. Copy assets/three-kingdoms-back.png to public/assets/three-kingdoms-back.png only when the project does not already contain its shared back. Never replace a user-customized existing back without permission.
7. Register the card following references/app-structure.md.
   • In a freshly cloned starter, replace the sample card entry and its placeholder assets.
   • In an existing project, append the card. Never delete, replace, or reorder prior user cards.
8. Match the new card's color to the Guan Yu baseline.
   • Run python scripts/compare_background.py --candidate <front>.
   • The canonical sampled paper target is RGB (156.09, 127.73, 92.48) with a tolerance of 3 per channel.
   • Always generate a balanced base with python scripts/match_background.py --candidate <new-front> --output <balanced-front> when the source is outside that tolerance.
   • Use the balanced image only as the base cover. Keep the extracted foreground on its original color path.
   • Never change another card while calibrating the new card.
9. Run lint and production build. Start or reuse the Vite server.
10. Verify in a browser at desktop and narrow mobile sizes:
    • front artwork and extracted foreground align;
    • the card remains a thin plane at edge angles;
    • drag rotation, damped wheel/pinch zoom, front foil, and back parallax work;
    • the back is correctly oriented and never bulges or blurs;
    • every existing card remains selectable.

Guardrails

• Keep the background pure black and the page focused on one centered card.
• Keep click-to-flip disabled. Orbit dragging may reveal either side.
• Keep the card geometrically flat; do not use displaced mountain meshes or thick box geometry.
• Simulate back depth with subtle uniform UV translation driven by pointer and camera angle. Do not shear, blur, or locally bend the image.
• Build front depth from a separate transparent character plane with small damped x/y movement and minimal z separation.
• Do not add particles, decorative scenery, explanatory text, or unrelated controls.
• Use thumbnail buttons to switch cards and preserve all prior cards.
• Treat generated art as a derived asset. Keep the supplied cover intact.
• Preserve mounts by default. Never classify a horse or other ridden creature, its tack, or its overlap with the rider as removable background merely because the prompt says "character" or "figure".
• Do not separate a rider from the mount or reconstruct body parts hidden by the mount. Remove a mount only when the user explicitly asks for a rider-only extraction.
• Treat the canonical paper color as immutable unless the user explicitly changes the series-wide background standard.
• If image generation changes the pose or identity, discard that result and retry from the explicit cover path.

Bundled resources

• assets/starter/: portable working app with a replaceable placeholder card, shared back, interactions, and card picker.
• assets/three-kingdoms-back.png: canonical shared back.
• scripts/clone_starter.py: cross-platform safe starter copier for an absent project.
• scripts/validate_card_assets.py: front/foreground dimension and alpha validator.
• scripts/match_background.py: matches a new base cover's paper color to Guan Yu without changing its foreground layer.