Add: windows mvp - transparent bugs not fixed

2026-02-12 22:58:33 +08:00
commit 61825f647d
147 changed files with 28498 additions and 0 deletions
--- a/issues/issue1.md
+++ b/issues/issue1.md
@@ -0,0 +1,235 @@
+## Title
+
+Windows overlay renders as large opaque window; background not transparent;
+sprite shows magenta matte; window is not pet-sized.
+
+## Severity
+
+P0
+
+## Environment
+
+- OS: Windows
+- App: `sprimo-app` frontend runtime
+- Reported on: 2026-02-12
+- Evidence screenshot: `issues/screenshots/issue1.png`
+
+## Summary
+
+Current runtime output violates overlay requirements:
+
+- opaque dark background is visible behind the pet
+- sprite keeps magenta matte background
+- window footprint is larger than expected pet footprint
+
+## Reproduction Steps
+
+1. Launch the frontend executable on Windows.
+2. Observe the initial overlay window at startup.
+
+## Expected Result
+
+- Window appears borderless and transparent.
+- Only pet pixels are visible.
+- Sprite background uses alpha (no magenta matte).
+- Window size is constrained to sprite bounds plus small margin.
+
+## Actual Result
+
+- Window background appears opaque dark gray.
+- Sprite contains magenta matte rectangle.
+- Window appears larger than a pet-sized overlay.
+
+## Root Cause Analysis
+
+Current findings from repository inspection:
+
+- The default sprite is RGB (`Format24bppRgb`) and depends on runtime chroma-key conversion.
+- Window and clear-color transparency settings were configured, but layered-window attributes
+  were not explicitly applied during window-handle attachment.
+- `SetTransform.x/y` was applied to both window coordinates and sprite world translation, causing
+  visible offset within the client area and making the window appear larger than pet bounds.
+- Chroma-key conversion used exact color matching only, which is fragile for near-magenta pixels.
+
+## Fix Plan
+
+1. Reproduce with runtime logs enabled and capture an explicit before screenshot.
+2. Validate chroma-key conversion path against loaded texture content.
+3. Validate Windows composition and layered style behavior with attached HWND.
+4. Apply targeted renderer/platform fixes.
+5. Capture after screenshot and rerun verification checklist.
+
+## Implementation Notes
+
+Implemented code changes:
+
+1. `crates/sprimo-app/src/main.rs`
+- Sprite now spawns centered at `(0, 0, 0)`; persisted `x/y` remains window placement only.
+- `SetTransform.x/y` no longer mutates sprite world translation.
+- Chroma-key conversion now:
+  - uses tolerance matching around `#FF00FF`,
+  - preserves non-key alpha values,
+  - forces chroma-key when an alpha-bearing image is fully opaque but key-colored in large areas.
+- Added regression tests for tolerant keying, alpha preservation, and force-key detection.
+
+2. `crates/sprimo-platform/src/lib.rs`
+- Windows adapter now applies layered style + `SetLayeredWindowAttributes` when window handle is
+  attached.
+- Click-through toggles now reuse the layered-style application path to keep transparency setup
+  stable.
+
+3. Additional Windows window configuration hardening (`crates/sprimo-app/src/main.rs`)
+- Primary window now explicitly sets `composite_alpha_mode = PreMultiplied`.
+- Primary window now starts with a small explicit resolution (`544x544`) to avoid large default
+  client area before runtime pack sizing applies.
+
+4. Follow-up rollback + keying adjustment after new screenshot review
+- Removed explicit `composite_alpha_mode` override to return control to Bevy/WGPU default.
+- Removed forced layered alpha attributes from Windows adapter to avoid opaque black composition.
+- Increased chroma-key tolerance to better remove magenta fringe around sprite edges.
+
+5. Windows compositor fallback for persistent opaque background
+- Added Windows color-key transparency fallback:
+  - sets `WS_EX_LAYERED` on attached HWND
+  - applies `SetLayeredWindowAttributes(..., LWA_COLORKEY)` with key color `#01FE03`
+- Switched Windows clear color to the same key color so non-sprite background can be cut out by
+  the OS compositor even when swapchain alpha blending is not honored.
+
+6. Windows mode switch to avoid swapchain-alpha path conflicts
+- On Windows, primary window now disables Bevy transparent swapchain mode
+  (`transparent = false`) and relies on layered color-key composition only.
+- Non-Windows behavior remains unchanged (`transparent = true` + alpha clear).
+
+7. DWM composition strategy after transparent color-key regression
+- Removed Windows color-key compositor strategy (it hid sprite on tested path).
+- Added DWM composition setup on HWND attach:
+  - `DwmIsCompositionEnabled`
+  - `DwmExtendFrameIntoClientArea` with full glass margins
+  - `DwmEnableBlurBehindWindow`
+- Restored Windows render path to alpha clear + `transparent = true`.
+
+8. Renderer alpha mode correction pass
+- Removed DWM composition overrides to avoid conflicting transparency mechanisms.
+- Forced Bevy window `CompositeAlphaMode::PostMultiplied` on Windows to align with transparent
+  swapchain blending expectations.
+- Kept native alpha clear color render path.
+
+9. Hardware-safe Windows fallback after runtime panic
+- Runtime log showed wgpu surface supports alpha modes `[Opaque]` only on this machine.
+- Switched Windows path to opaque swapchain (`transparent = false`) plus Win32 layered
+  color-key transparency (`WS_EX_LAYERED + LWA_COLORKEY`).
+- Aligned Windows clear color to the same key color (`#FF00FF`) and removed crash-causing
+  post-multiplied alpha request.
+
+10. Color-key visibility fix for opaque presentation path
+- In Windows colorkey mode, keyed pixels are now emitted with alpha `255` (not `0`) so key RGB
+  survives the presentation path and can be matched by `LWA_COLORKEY`.
+- Updated chroma-key unit tests for platform-specific keyed-alpha expectations.
+
+## Verification
+
+### Commands Run
+
+- [x] `cargo check --workspace`
+- [x] `cargo test --workspace`
+- [x] `just qa-validate`
+
+### Screenshots
+
+- Before:
+  - `issues/screenshots/issue1.png` (legacy baseline)
+- After:
+  - pending (capture required before `Verification Passed`/`Closed`)
+
+### Command Output Summary
+
+- `cargo check --workspace`: pass
+- `cargo test --workspace`: pass
+- `just qa-validate`: pass
+- `cargo check -p sprimo-app -p sprimo-platform`: pass
+- `cargo test -p sprimo-app`: pass
+- dist runtime binary refreshed from latest debug build: done
+- Follow-up rebuild + dist binary refresh after screenshot-guided rollback: done
+- Windows color-key fallback build + dist binary refresh: done
+- Windows transparent-mode switch build + dist binary refresh: done
+- DWM composition fallback build + dist binary refresh: done
+- Post-multiplied alpha mode build + dist binary refresh: done
+- Opaque+colorkey fallback build + dist binary refresh: done
+- Keyed-alpha colorkey build + dist binary refresh: done
+
+### Result
+
+- Current Status: `Fix Implemented`
+- Notes: code fix implemented and validated by tests; runtime after screenshot still pending.
+
+## Status History
+
+- `2026-02-12 20:15` - reporter - `Reported` - initial bug report with screenshot.
+- `2026-02-12 20:35` - codex - `Triaged` - validated screenshot symptoms and repository context.
+- `2026-02-12 20:50` - codex - `Reported` - lifecycle file normalized; fix not yet applied.
+- `2026-02-12 21:20` - codex - `In Progress` - implemented window/transparency/chroma-key fixes.
+- `2026-02-12 21:30` - codex - `Fix Implemented` - workspace checks/tests and QA validator passed.
+- `2026-02-12 22:10` - codex - `In Progress` - added explicit Windows composite alpha mode and startup resolution.
+- `2026-02-12 22:15` - codex - `Fix Implemented` - app/platform targeted checks passed and dist binary refreshed.
+- `2026-02-12 22:35` - codex - `In Progress` - analyzed new after screenshot showing black opaque background and magenta fringe.
+- `2026-02-12 22:45` - codex - `Fix Implemented` - rolled back layered alpha/composite override and tightened chroma-key edge removal.
+- `2026-02-12 22:55` - codex - `In Progress` - analyzed latest screenshot still showing opaque black background.
+- `2026-02-12 23:05` - codex - `Fix Implemented` - added Windows color-key compositor fallback and aligned clear color.
+- `2026-02-12 23:15` - codex - `In Progress` - analyzed latest screenshot showing color-key path still ineffective with swapchain transparency.
+- `2026-02-12 23:22` - codex - `Fix Implemented` - switched Windows to non-transparent swapchain mode and kept layered color-key compositor path.
+- `2026-02-12 23:30` - codex - `In Progress` - analyzed screenshot where window became effectively empty/over-transparent.
+- `2026-02-12 23:42` - codex - `Fix Implemented` - removed color-key strategy and switched to DWM composition setup.
+- `2026-02-12 23:55` - codex - `In Progress` - analyzed screenshot where black background persisted under DWM strategy.
+- `2026-02-13 00:05` - codex - `Fix Implemented` - removed DWM overrides and forced post-multiplied alpha mode on Windows.
+- `2026-02-13 00:35` - codex - `In Progress` - reproduced startup panic from runtime log (`alpha modes: [Opaque]`).
+- `2026-02-13 00:45` - codex - `Fix Implemented` - replaced transparent swapchain path with Windows opaque+colorkey fallback; startup panic no longer reproduced.
+- `2026-02-13 00:55` - codex - `In Progress` - analyzed persistent black background under opaque+colorkey path.
+- `2026-02-13 01:05` - codex - `Fix Implemented` - changed keyed-pixel alpha to 255 in Windows colorkey mode and updated tests.
+
+## Closure
+
+- Current Status: `Fix Implemented`
+- Close Date:
+- Owner:
+- Linked PR/commit:
+
+## Original Report (2026-02-12, normalized from legacy encoding)
+
+### Bug Report / Debugging Issue (Windows)
+
+**Title:** Windows overlay renders as large opaque window; background not transparent; sprite
+shows magenta matte; window not pet-sized.
+
+**Severity:** P0 (core functionality broken; not an overlay pet)
+
+**Component:** Frontend (Bevy renderer / windowing / transparency pipeline)
+
+**Summary:** The app shows a large opaque dark-gray window with a character sprite on top. The
+sprite includes a magenta rectangular matte. This violates transparent borderless overlay
+requirements.
+
+**Evidence from screenshot (`issues/screenshots/issue1.png`):**
+
+1. Opaque background fills most of the window.
+2. Window appears much larger than pet-only bounds.
+3. Magenta matte appears behind the sprite.
+
+**Expected:**
+
+- Borderless transparent overlay.
+- Pet-only visible pixels.
+- No magenta matte.
+
+**Actual:**
+
+- Opaque dark window.
+- Magenta sprite background.
+- Regular app-window behavior.
+
+**Likely causes in original report:**
+
+1. Missing OS-level transparent/layered window behavior.
+2. Non-transparent clear color or camera clear.
+3. Sprite asset alpha issue (RGB or wrong export).
+4. Missing chroma-key discard path.
+5. Missing pet-sized window sizing logic.