Problem Symptoms
After upgrading from Blits v1.44.0 → v2.1.3, when scrolling the OverlayApplist, the entire app list disappeared after pressing the down key for the 4th time (focusedRow = 3), but reappeared when pressing the up key to go back.
Root Cause
Lightning.js has a rendering optimization mechanism for elements with negative Y coordinates: when the container's Y coordinate becomes negative (-66, -239, -412...), the engine optimizes out (doesn't render) that container and all its child elements.
Original code:
<Element x="100" :y.transition="280 - $focusedRow * 173" ref="cardsContainer">
When focusedRow = 3, Y = 280 - 3×173 = -239, the container was optimized out by Lightning.js, causing the list to disappear.
Debugging Process (spend 2-Day Timeline)
False Path 1: Alpha Transition Reactivity Issue,Time Spent: ~4 hours
False Path 2: Lazy Loading Race Condition,Time Spent: ~6 hours
False Path 3: Parent Container Clipping Issue ,Time Spent: ~2 hours
False Path 4: Focus Management During Transition ,Time Spent: ~2 hours
Key Breakthrough: Container Rendering Validation ,Time Spent: ~4 hours
- Test: Fixed container Y at 280 (no scrolling)
- Result: ✅ List no longer disappeared!
- Root Cause Confirmed: Negative Y coordinates caused Lightning.js rendering optimization
Final Solution
Changed the scrolling implementation to keep container Y coordinate positive:
// OverlayApplist.js - Container fixed at Y=280
<Element x="100" y="280" ref="cardsContainer">
// Calculate scroll offset
computed: {
scrollOffset() {
return this.focusedRow * 173
}
}
// Pass scrollOffset to each Appcard
<Appcard :scrollOffset="$scrollOffset" ... />
// Appcard.js - Y coordinate minus scrollOffset
:y.transition="{value: $row * 180 + 20 - $scrollOffset, duration: 300}"
Effect: Scrolling behavior is identical, but container always maintains positive Y coordinate and won't be optimized out by the engine.
Lessons Learned
1. Framework Low-Level Behavior May Differ From Expectations
Lightning.js's rendering optimization for negative coordinate elements is a reasonable performance strategy, but may not be clearly documented, leading to unexpected behavior after upgrades.
2. Critical Debugging Techniques
- Verify Basic Assumptions: Before diving into complex logic, first confirm element actually exists (via ref access)
- Simplify Testing: Fix variables (e.g., Y=280) to quickly validate hypotheses
- Binary Elimination: Progressively disable features (lazy loading, alpha, transition) to isolate the issue
- Log-Driven Debugging: Add detailed logs to observe state changes and timing
3. Avoid Over-Assumption
The first 4 hypotheses were all based on "complex logic errors," but the actual problem was "simple coordinate value causing rendering optimization." Should check simple causes first.
4. Upgrade Considerations
- Read Breaking Changes documentation (although this issue wasn't in breaking changes)
- Test edge cases (negative coordinates, large values, extreme states)
- Maintain rollback paths (version control)
5. Time Allocation Reflection
- 70% time spent on wrong hypotheses
- 20% time spent on logging and test tools
- 10% time finding the actual cause
Recommendation: Next time encountering similar issues, spend 30 minutes first verifying basic questions like "does element exist" before diving into complex logic.
Hope this summary helps you and your team save time in future debugging!
Problem Symptoms
After upgrading from Blits v1.44.0 → v2.1.3, when scrolling the OverlayApplist, the entire app list disappeared after pressing the down key for the 4th time (focusedRow = 3), but reappeared when pressing the up key to go back.
Root Cause
Lightning.js has a rendering optimization mechanism for elements with negative Y coordinates: when the container's Y coordinate becomes negative (-66, -239, -412...), the engine optimizes out (doesn't render) that container and all its child elements.
Original code:
<Element x="100" :y.transition="280 - $focusedRow * 173" ref="cardsContainer">When focusedRow = 3, Y = 280 - 3×173 = -239, the container was optimized out by Lightning.js, causing the list to disappear.
Debugging Process (spend 2-Day Timeline)
Final Solution
Changed the scrolling implementation to keep container Y coordinate positive:
Effect: Scrolling behavior is identical, but container always maintains positive Y coordinate and won't be optimized out by the engine.
Lessons Learned
1. Framework Low-Level Behavior May Differ From Expectations
Lightning.js's rendering optimization for negative coordinate elements is a reasonable performance strategy, but may not be clearly documented, leading to unexpected behavior after upgrades.
2. Critical Debugging Techniques
3. Avoid Over-Assumption
The first 4 hypotheses were all based on "complex logic errors," but the actual problem was "simple coordinate value causing rendering optimization." Should check simple causes first.
4. Upgrade Considerations
5. Time Allocation Reflection
Recommendation: Next time encountering similar issues, spend 30 minutes first verifying basic questions like "does element exist" before diving into complex logic.
Hope this summary helps you and your team save time in future debugging!