Clicking around in pivot viewer sometimes crashes it

[einari]

When clicking around in the pivot viewer. Scrolling, zooming and clicking elements - all of a sudden it crashes. But it crashes in a weird way, all the tiles are just gone. The navigation is there and the groups (buckets) when doing this in the Grouped mode.

We see this in the Chronicle Workbench in both the Pivot Viewer page and the Behavioral patterns page that uses the pivot viewer as well.

[cratis-direct]

Investigation

Final Investigation Report: #236

Issue

"Clicking around in pivot viewer sometimes crashes it" — All tiles disappear during scrolling, zooming, and clicking interactions while navigation and groups remain visible.

Root Cause Chain (Confirmed)

The tile disappearance results from a cascade of 9 issues working together:

Primary Critical Issues:

1. Missing prevLayout Parameter in Scroll Handler (PivotCanvas.tsx:716-759)

   • Scroll event handler calls syncSpritesToViewport WITHOUT prevLayout, but main effect passes it
   • During rapid scrolling in view transitions, sprites can't animate from old positions
   • Animation system breaks; sprites "teleport" instead of smoothly transitioning

2. Aggressive Cull Logic Race Condition (visibility.ts:228-236)

   • aggressiveCull rapidly flips between true and false as scroll stabilizes
   • Frame 1 (large scroll): all sprites visible; Frame 2 (scroll settles): normal culling kicks in
   • If viewport calculation returns 0 cards on frame 2, all sprites hidden immediately
   • Destroyed after 100ms with no recovery path

3. Insufficient Fallback Coverage (visibility.ts:168-218)

   • Two fallback mechanisms interfere: 5 cards for view transitions, 12-30 general fallback
   • Only guarantees 5 sprites during rapid mode switches (instead of 30)
   • But typical on-screen count is 80-150 tiles → 70+ tiles hidden after first visibility update

4. Aggressive 100ms Sprite Sweep (visibility.ts:287-310)

   • Hidden sprites destroyed after just 100ms
   • If viewport calculation glitches, destroyed sprites gone before recovery can happen
   • Fallback can't recreate them because they're not in inViewportIds

Secondary Issues Contributing:

5. No exception handling for root.addChild() during sprite creation
6. Coordinate transform stale during view transitions (offsetY calculation)
7. Scroll event listener captures stale layout from closure
8. Complex aggressiveCull boolean logic creates edge cases
9. Last rows prefetch logic can cause over-culling

Cascade Failure Sequence

1. User: rapid scroll + zoom + view mode switch
2. Large scroll Δ → aggressiveCull=true → all sprites visible
3. Scroll stabilizes → aggressiveCull=false 
4. Layout missing prevLayout in scroll handler → animation breaks
5. Only 5-30 fallback sprites loaded, but 100+ normally on screen
6. 70+ tiles hidden immediately
7. After 100ms: hidden sprites destroyed, removed from container
8. Viewport recalculates but sprites already gone
9. If layout.positions is stale or calculation still failing, fallback doesn't trigger
10. Result: Blank canvas with only navigation/groups visible ✓

Critical Evidence

File	Line(s)	Finding
PivotCanvas.tsx	716-759	Scroll handler missing prevLayout: prevLayoutRef.current
visibility.ts	168-218	5 vs 12-30 fallback mismatch
visibility.ts	228-236	aggressiveCull race condition during scroll stabilization
visibility.ts	289	SWEEP_MS = 100 (too aggressive)
animation.ts	34	sprite.container.position.set() assumes container valid (not checked)
sprites.ts	293-310	destroySprite removes from parent but doesn't validate parent state

What Would Trigger It

• Zoom out significantly (< 0.5x) while scrolling → buffer calculations unstable
• Rapid consecutive interactions: zoom + scroll + click + mode switch
• Large datasets (100+ items visible) → fallback insufficient
• Non-100% browser zoom → coordinate precision issues
• Chronicle Workbench (where it's observed) has complex interaction patterns

Fix Strategy (Sonnet-level complexity)

Three fixes required for stability:

1. Pass prevLayout in scroll handler (PivotCanvas.tsx line 743):

   syncSpritesToViewport({
       // ... existing params ...
       prevLayout: prevLayoutRef.current,  // ADD THIS
   });

2. Increase fallback coverage (visibility.ts line 208):

   const fallbackCount = isViewTransition ? 80 : 120;  // UP from 12-30

3. Prevent sweep during unstable scroll (visibility.ts line 289):

   const SWEEP_MS = scrollStabilized ? 100 : 500;  // Longer delay if still scrolling

Optional safeguard: Add guard to prevent sweep of >70% of sprites in one frame (signals calculation failure).

---

SUGGESTED-MODEL: sonnet

The fix is straightforward but requires careful coordination: missing parameter + insufficient fallback + too-aggressive sweep = silent cascade failure. Implementing all three ensures tiles remain visible during rapid interactions while preserving the culling optimization for performance.

Suggested model for implementation: opus

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.