dev/docs/history_render_cache_bridge.md

# History Render Cache Bridge

This document captures the current bridge between the new `HistoryState` data
model and the legacy per-cell layout caches that still live inside a few
history cells (`ExecCell`, streaming/assistant cells, and diff cells). The
bridge allows `ChatWidget` to render the unified history vector without
re-computing expensive layouts every frame while we complete the Step 6 renderer
work.

## Rendering pipeline overview

1. The draw loop in `ChatWidget::render_history` assembles a list of
   `RenderRequest` values. Each request contains the `HistoryId` of the record
   being rendered, the existing `HistoryCell` cache if one exists, and a set of
   "fallback" lines derived on demand from the semantic `HistoryRecord`.
2. `HistoryRenderState::visible_cells()` receives those requests along with the
   current `RenderSettings` (width, theme epoch, and reasoning visibility
   toggle). The render state stores cached layouts in a `HashMap<CacheKey,
   CachedLayout>`, where `CacheKey` is `(HistoryId, width, theme_epoch,
   reasoning_visible)`.
3. When a cache entry exists, `visible_cells()` returns the layout immediately.
   Otherwise it invokes the builder closure supplied in the request. The
   closure uses the `HistoryCell` if one exists, and falls back to the semantic
   lines so the renderer can still make forward progress even when we no longer
   materialize a trait object.
4. The resulting `VisibleCell` bundles the resolved layout (plus the assistant
   streaming plan, if applicable). `ChatWidget` uses these `VisibleCell`
   snapshots to copy pre-rendered buffer rows into the terminal buffer.

## Cache invalidation

`HistoryRenderState` exposes several targeted invalidation helpers:

- `invalidate_history_id(HistoryId)` removes cached layouts for a single
  record. We call this whenever a record’s semantic state changes (for example
  when streaming assistant output arrives).
- `handle_width_change(width)` prunes cache entries whose width no longer
  matches the viewport. Width changes also clear prefix sums so we rebuild the
  height map.
- `invalidate_all()` clears the layout cache and prefix sums. We use this when
  restoring snapshots or performing operations that massively reshuffle
  history.

The prefix sum cache (`prefix_sums`, `last_prefix_*` fields) is separate from
the layout cache. It stores cumulative heights so that scrolling computations
are O(1) per frame.

## Fallback behaviors

- `RenderRequest::fallback_lines` are derived from the semantic
  `HistoryRecord`. This ensures that even if a legacy `HistoryCell` cache is
  missing (for example, after deserializing a snapshot from disk) we still have
  content to render.
- `ChatWidget::draw_history` keeps the old `HistoryCell` objects around only as
  an optimization; any cache miss rebuilds the layout from semantic state and
  stores the result in the shared cache.
- Cells that still own per-width caches (`ExecCell`, diff/assistant streaming)
  remain responsible for invalidating their internal caches. The history render
  cache treats those cells as opaque; once Step 6 lands we can remove the
  per-cell caches and rely exclusively on `HistoryRenderState`.

## Removal roadmap

The interim bridge exists solely to prevent regressions while we finish Step 6
of the plan. Once all cells render from structured state and the shared cache
proves stable, we can:

1. Delete the per-cell layout caches (`ExecCell::cached_layout`, assistant
   streaming wrappers, diff caches).
2. Convert all render paths to supply semantic state only, removing
   `HistoryCell` trait objects from the steady-state draw loop.
3. Simplify `ChatWidget::draw_history` so it only iterates over
   `HistoryState.records`.

Tracking this work in the plan keeps the team aligned on why the bridge exists
and what remains before it can be removed.