bend_puzzle/docs/interaction-performance.md

# Bend Field interaction performance and persistence

## Problems addressed

- Cursor movement felt uneven.
- Camera panning could appear to stop redrawing during a long held gesture.
- Pickup dragging needed a stable upper frame-rate limit.
- Zoomed-out play could exhaust its cached field image while the camera was still moving.
- A solved puzzle could later return to an unsolved state.
- Puzzle gates still had a dormant debug scheduling switch.

## Implemented solutions

### Cursor, camera, and pickup cadence

- Cursor rendering now keeps only the newest pointer sample and commits it on a display frame.
- Cursor commits use the shared 33.33 ms visual interval, limiting presentation to 30 FPS even on high-refresh displays.
- Camera commits use the same 30 FPS ceiling with a separate missed-frame fallback.
- Pickup dragging remains on the bounded 30 FPS visual scheduler and keeps logical catch-up work separate from visual pointer tracking.

### Continuous overview panning

- The zoomed-out field still pans by transforming a cached bitmap, avoiding a full map redraw on every pointer event.
- When a held pan reaches the bitmap's overscan boundary, the game now requests a cache rebuild during the gesture.
- These rebuilds run through an idle callback, are separated by at least 180 ms, and are capped by the benchmark. Camera transforms continue while the new bitmap is prepared.

### Durable puzzle completion

- A durable `solved: true` value is now monotonic for the same puzzle.
- Route sanitization may remove damaged path data, but it no longer revokes the clear, score, solver identity, or store state.
- Existing cloud-pull, cross-tab, recovery-journal, and board-hydration merges continue to preserve compatible solved records.

### Production-only puzzle gates

- The `SPECIAL_CELL_DEBUG_ALL_LEVELS` switch was removed.
- Internal gates and other special cells now use only the normal production level schedule, beginning at level 5.

## Verification

- Focused regression coverage executes the in-gesture cache refresh, durable-clear sanitization, and production-only gate schedule.
- The complete fast test suite passes.
- The real Edge benchmark gates cursor, camera, and pickup presentation at the shared 30 FPS ceiling, checks input age and camera work separately, and rejects uncapped presentation.
- Edge and benchmark server processes are checked after every browser run; the final count is zero.

## Remaining stress-test observation

The optional 4× CPU-throttled Edge scenario recorded one 106.70 ms functional-drag outlier. Its steady cadence (8.40 ms p95), model work (2.80 ms p95), visual work (4.90 ms p95), and render work (2.60 ms p95) stayed within their individual budgets. This outlier should remain visible in future profiling rather than being hidden by a relaxed acceptance threshold.