Document optional animation in reusable dice theme prompt

PROMPT_GENERATE_DICE.md

@@ -28,7 +28,12 @@ the game rules, physics and random-result logic.
 - **Workflow:** Blender previews first, then integrate after my visual approval.
   If I explicitly request full integration or have already approved the design,
   complete integration without asking for the same approval again.
-- **Animation:** Static models for this task. Discuss animation separately.
+- **Animation wanted:** [Yes / No. If unspecified, ask me before adding motion.]
+- **Animation brief (if Yes):** [What moves, its speed/mood, and what stays fixed.]
+- **Animation timing (if Yes):** [Continuously while visible, including after a
+  roll / only while rolling. Default: continuously while visible.]
+- **Animation by quality (if Yes):** [Default: Low static; Medium subtle, cheap
+  motion; High richer layered effects. Describe any different preference.]
 - **Publication after integration:** Commit and push the validated work to a
   feature branch. Report the branch and commit; do not merge or release the app.
 
@@ -56,6 +61,8 @@ Preserve unrelated changes. Read:
 - The current theme/quality persistence in the game stores
 - `package.json` and the lockfile
 - `docs/cosmic-black-hole.md`
+- For animation: `docs/cosmic-animation.md`, `src/dice-box/cosmic-material.js`,
+  `src/dice-box/cosmic-motion.js` and `scripts/patch-dice-box.mjs`
 - `scripts/build-cosmic-theme.mjs` and `scripts/export-cosmic-blender.py`
 - Existing theme, bridge and viewer tests and the browser/selection checks
 - The installed Dice-Box and dice-themes asset structure and loader code
@@ -72,7 +79,8 @@ scene before editing, preserve unrelated scenes, and keep the model editable.
 If Blender or its MCP connection is unavailable, report the exact limitation;
 do not claim to have modeled or rendered in Blender.
 
-Create three coherent static variants of the same theme:
+Create three coherent base models of the same theme. These remain usable as
+static variants whether animation is selected or not:
 
 | Quality | Design target |
 | --- | --- |
@@ -103,10 +111,22 @@ what should survive export and what is only a Blender preview effect. Save a
 self-contained `.blend` with packed textures and retained reference data.
 Verify it reopens with the intended scene and all required datablocks intact.
 
-If the chosen workflow requires visual approval, stop here with concrete
-previews and the saved source. Do not edit game integration until approval.
+If animation is requested, also build an editable Blender motion study for the
+chosen quality levels. Keep Low static by default. Show a short looping video
+comparing all three levels, including a settled die so continuous motion is
+clear. Keep pip positions, face mapping and collider geometry fixed. Identify
+which effects can become runtime UV/color shaders and which need approximation
+or baking; Blender node materials and keyframes do not export automatically.
+Retain the static authoring source alongside the animated study. If the
+animation choice is missing, ask once and continue the base model work while
+waiting; do not assume permission to animate.
 
-### 3. Export and integrate the approved static models
+If the chosen workflow requires visual approval, stop here with concrete
+previews (including motion when requested) and the saved source. Do not edit
+game integration until approval. Existing approval or an explicit request for
+full integration takes precedence; do not ask for the same approval again.
+
+### 3. Export and integrate the approved base models
 
 - Use real Dice-Box-compatible d6 meshes and supported theme configuration.
   Do not invent shader, emission, transparency, animation or quality fields.
@@ -142,14 +162,54 @@ previews and the saved source. Do not edit game integration until approval.
 - Use no runtime CDN requests or network-only assets. Do not patch the library
   for static models unless inspection demonstrates a necessary incompatibility.
 
-### 4. Keep animation separate
+### 4. Implement animation only when selected
 
-Do not implement continuous animation in this static-theme task. Blender
-keyframes and node materials are not proof that the game can render an effect.
-The current Dice-Box integration uses limited material loading and stops drawing
-when dice sleep. Reinspect those constraints before a later animation task.
-Any future renderer extension must keep visual animation separate from sleeping
-physics, emit each roll result once, keep pips fixed and pause when hidden.
+**If No:** deliver the static variants. Do not register the new theme for idle
+animation or add its animation effects. Preserve animation in existing themes.
+
+**If Yes:** translate the approved Blender study into the game's actual renderer:
+
+1. Inspect the current adapter and installed Dice-Box version first. The stock
+   renderer stops drawing when dice sleep; this repository already adds a
+   separate visual loop and Babylon CustomMaterial support for cosmic dice.
+   Reuse or deliberately generalize that implementation for the new theme,
+   preserving existing cosmic behavior. Do not add a second Babylon runtime,
+   duplicate render loops or unsupported theme configuration fields.
+2. Export static evaluated geometry and local baked textures as in section 3.
+   Translate animated Blender nodes into supported runtime shader operations,
+   such as UV flow, layered texture sampling or bounded procedural color noise.
+   Use a deliberate UV/material mask to restrict motion to decorative regions.
+   The cosmic white-atlas-corner mask is specific to its exports; verify or
+   adapt it for the new model. Keep pips, outlines and face recognition stable.
+   Do not animate the collider, move the whole die after settling or change
+   its result. Document effects that cannot survive translation faithfully.
+3. Register only the intended animated quality variants with the material
+   factory and visual loop's theme detection. Default to no idle rendering for
+   Low, inexpensive motion for Medium and richer effects for High. Use elapsed
+   time with a bounded, seamless phase. The current idle cap is 30 fps; preserve
+   it unless measurement justifies a change. Report shader/texture costs and
+   distinguish a frame-rate cap from measured mobile performance.
+4. Honor the requested timing. For continuous motion, redraw after Dice-Box
+   finishes the roll and stops physics. For rolling-only motion, do not start
+   an idle loop for this theme. Never keep the physics worker running just to
+   animate, reroll, alter random generation or emit a second completion.
+5. Reuse `VISIBILITY`, AppState and screen-focus handling. Pause hidden or
+   inactive views, resume without jumping through hidden time, and clean up
+   animation callbacks, observers and resources on reset/disposal. Wait for
+   pending initialization/theme loads before replacing a world. Preserve
+   `THEME`, `updateConfig({ theme })` and quality changes deferred during rolls.
+6. Keep adapter/shader source in the repository and bundle it offline through
+   `sync:dice`. The current adapter patches Dice-Box 1.1.4 in memory during
+   esbuild, with pinned versions, file hashes and single-match anchors. Preserve
+   these safeguards and the upstream license; never edit node_modules or
+   bypass a failed version check. Review any necessary library change explicitly
+   and explain it in the delivery. This adapter targets `offscreen: false`;
+   do not claim worker-renderer support without implementing and validating it.
+
+If the requested effect is incompatible or too expensive, show a simpler
+shader or baked alternative and explain the limitation. Do not silently replace
+requested motion with a static model or claim the Blender preview is proof of
+runtime compatibility.
 
 ### 5. Validate the integration
 
@@ -181,6 +241,14 @@ fixed readable pips, player/theme switching, persistence, default and existing
 themes, and no missing-file, worker, WebView or Babylon errors. Do not accept
 random fallback results as evidence that the 3D engine succeeded.
 
+For animated variants, additionally verify changing rendered pixels at the
+requested times, fixed pip geometry and settled poses, one completion per roll,
+and no physics commands caused by idle animation. Verify static variants draw
+no idle frames. Exercise pause/resume, reset, repeated quality/theme switching
+and disposal so old worlds cannot keep rendering. Check that static and existing
+themes retain their behavior. Extend the checks to the new theme's ids and
+timing rather than assuming every theme should animate like cosmic dice.
+
 Use an Android device/emulator if available, including an offline/airplane-mode
 check. Otherwise run the available desktop file-based browser checks and state
 that Android behavior and mobile performance remain unverified. Clearly
@@ -191,6 +259,9 @@ distinguish measured behavior, automated checks and visual inspection.
 Provide the editable Blender source, all runtime meshes/textures/configuration,
 export tooling, integration and tests. Document the theme in `docs/`, including
 quality differences, file locations, export instructions and visual limitations.
+State the animation choice and timing explicitly. For animated themes, include
+the Blender motion source/video, runtime shader and lifecycle changes, and
+describe differences between the approved preview and actual game rendering.
 
 Give a concise summary of changed files, exact validation commands and results,
 preview images, remaining limitations, and publication status. After the checks