Sprimo/issues/issue4.md

Title

Packaged sprimo-tauri sprite rendering breaks after pack switch; default switch errors and scaling stops applying.

Severity

P1

Environment

• OS: Windows
• App version/build: packaged release (sprimo-tauri.exe)
• Renderer/backend details: Tauri main overlay + settings pop-out
• Evidence screenshots:
  • issues/screenshots/issue4.png
  • issues/screenshots/issue4-b.png
  • issues/screenshots/issue4-c.png

Summary

In packaged runtime, sprite display is incorrectly split/tiled, switching to default can fail, and scaling becomes ineffective after the error.

Reproduction Steps

1. Run packaged sprimo-tauri.exe from ZIP extract.
2. Open settings window.
3. Switch character between ferris and default.
4. Observe main overlay rendering and debug output.
5. Change scale slider.

Expected Result

• Sprite sheet is split into the correct frame grid regardless of image resolution.
• Pack switching works for both ferris and default.
• Scale changes continue to apply after pack changes.

Actual Result

• Main overlay shows incorrectly split/tiled sprite sheet.
• Pack switch can produce runtime error and break subsequent behavior.
• Scale update stops working reliably after the error.

Root Cause Analysis

1. Existing splitting logic relied on fixed pixel frame metadata that did not generalize to packaged sprite.png dimension variants.
2. Pack metadata inconsistency:

• assets/sprite-packs/ferris/manifest.json used duplicated id (default), causing pack identity ambiguity.

3. Settings/runtime flow then entered an unstable state after pack switch failures.
4. Renderer reload lifecycle in tauri UI was unsafe:

• PixiPetRenderer::dispose performed duplicate teardown (ticker.destroy + app.destroy), which could trigger runtime TypeError during pack reload.
• Renderer replacement disposed previous renderer before new renderer creation succeeded, leaving the view in a broken/cropped state on creation failures.

5. Chroma-key conversion tolerance removed most #FF00FF background but still left magenta fringe on anti-aliased edges.

Fix Plan

1. Introduce generic splitter policy for sprite.png:

• fixed topology: 8 columns x 7 rows
• derive frame size from actual image dimensions
• keep chroma-key background handling (#FF00FF) in renderer

2. Validate animation frame indices against fixed frame count (56) for sprite.png.
3. Ensure pack apply path validates atlas geometry before committing SetSpritePack.
4. Fix ferris manifest ID uniqueness.

Implementation Notes

Implemented:

1. crates/sprimo-tauri/src/main.rs

• Added sprite.png-specific frame derivation (8x7) from PNG dimensions.
• Added PNG header dimension decoding utility.
• Added animation frame index validation against fixed 56 frames for sprite.png.
• Applied validation in both load_active_sprite_pack and set_sprite_pack.

2. assets/sprite-packs/ferris/manifest.json

• Changed manifest id from default to ferris.

3. docs/SPRITE_PACK_SCHEMA.md

• Documented Tauri sprite.png override behavior and 8x7 derived frame policy.

4. frontend/tauri-ui/src/renderer/pixi_pet.ts

• Made renderer disposal idempotent and removed duplicate ticker destruction.
• Delayed DOM canvas replacement until atlas load succeeds.
• Improved chroma-key edge handling with soft alpha + magenta spill suppression.

5. frontend/tauri-ui/src/main.tsx

• Made pack reload transactional (keep old renderer until new renderer creation succeeds).
• Improved fit-window flow so scale apply continues after reload retries.
• Added targeted diagnostics for reload failures.

Verification

Commands Run

• just build-release-tauri
• just package-win-tauri
• just smoke-win-tauri
• cargo check -p sprimo-tauri

Visual Checklist

• Before screenshot(s): issues/screenshots/issue4.png
• Before screenshot(s): issues/screenshots/issue4-b.png
• Before screenshot(s): issues/screenshots/issue4-c.png
• After screenshot(s): issues/screenshots/issue4-after-YYYYMMDD-HHMMSS.png

Result

• Status: Fix Implemented
• Notes: packaged runtime validation and after screenshots for this round are pending.

Status History

• 2026-02-14 00:00 - reporter - Reported - packaged runtime failure screenshots attached.
• 2026-02-14 00:00 - codex - Triaged - localized to sprite splitting/pack identity behavior.
• 2026-02-14 00:00 - codex - Fix Implemented - applied 8x7 generic splitter policy and pack-ID correction.
• 2026-02-14 00:00 - reporter - In Progress - reported issue4-after-fix1 still failing in packaged runtime.
• 2026-02-14 00:00 - codex - Fix Implemented - hardened renderer reload/dispose and chroma-key edge cleanup.

Closure

• Current Status: Fix Implemented
• Close Date:
• Owner:
• Linked PR/commit: