TermAl

Feature Brief: Conversation Overview Map

Status

Foundation in progress. The frontend now has a pure overview projection helper and a first product rail for loaded long virtualized sessions. The rail derives lightweight map items from loaded messages, optional virtualizer layout snapshots, and marker inputs; renders clumped DOM segments for dense message runs; shows marker pins and the active viewport; and supports click/drag navigation through the virtualizer handle. Hover tooltips, marker filters, and summary-only hydration jumps are still future work. Canvas rendering is a last resort only if clumped DOM segments still profile poorly.

The conversation overview map is a zoomed-out, approximate view of a long session transcript. It gives the user a fast spatial sense of the whole conversation: where prompts happened, where long assistant outputs happened, where commands/diffs/errors appeared, and where conversation markers sit.

This is a separate feature from Conversation Markers. Markers are durable semantic anchors; the overview map is a navigation surface over the whole transcript.

Related feature: Conversation Markers.

Problem

Long TermAl sessions are hard to reason about from the normal chat viewport. The user can scroll, search, or jump to bottom, but there is no compact map of the conversation shape.

The screenshot/reference behavior is a zoomed-out transcript: not fully readable, but enough to understand density, sections, and landmarks. That should become a first-class navigation mode instead of forcing the user to physically scroll through thousands of pixels.

Goals

Non-goals for v1

Core Idea

Render a lightweight transcript map beside or over the normal conversation. Each message becomes a simplified block whose height approximates the message’s real visual footprint.

Example visual encoding:

The overview is a navigation approximation. It should be stable and useful even when not all message heights have been measured.

Data Model

The overview should be derived from existing session state and optional layout measurements.

type ConversationOverviewItem = {
  messageId: string;
  messageIndex: number;
  type: Message["type"];
  author: Message["author"];
  estimatedHeightPx: number;
  measuredHeightPx?: number | null;
  status?: "running" | "success" | "error" | "approval" | null;
  markerIds: string[];
  textSample?: string;
};

Rules:

Estimation

The overview must not depend on exact transcript rendering.

Initial estimates:

Refinement:

UI Placement

Possible placements:

Recommended v1:

Marker Integration

Conversation markers should be first-class landmarks in the overview.

Behavior:

Markers remain their own data. The overview only projects them into map coordinates.

Jumping from the overview should use the same infrastructure as marker jumps.

Flow:

  1. Resolve clicked map y-coordinate to nearest message index.
  2. Prefer exact messageId if the item is known.
  3. Ask the transcript virtualizer to scroll to that message/index.
  4. Hydrate the session first if the transcript is not loaded.
  5. Highlight the target message briefly.

The overview should also reflect normal scrolling:

Performance Rules

Relationship To Existing Virtualization

The transcript virtualizer already owns message paging, measurement, and scroll-position correction. The overview should not duplicate that machinery.

Recommended contract:

The overview should never write scrollTop directly except through the virtualizer/session navigation API.

Implementation Phases

Phase 1: static overview rail

Phase 2: virtualizer integration

Phase 3: interaction polish

Phase 4: large-session scaling

Testing Plan

Frontend:

Virtualizer integration:

Accessibility:

Acceptance Criteria