Diff Pane Views and Tools
Overview
This area is the /diff pane's view/model layer and the hook-side integration points that decide when backend diff state is shown or refreshed. The orchestration lives outside this doc in mods/…/register.ts, but it calls the types and pure helpers documented here to translate backend fetches, transcript rows, tool results, and UI events into pane state and render trees.
mods/…/host.ts defines the host façade that session.start binds from the engine: timers, process and filesystem reads, store access, transcript reads, pane open/close, render invalidation, status, commands, session identity, and telemetry. View and tool code never reaches directly back into $; register.ts closes over a Host and passes its effects into the helpers in this area.
The pane model is centered on mods/…/pane-model.ts. It holds the last good backend diff (data), requested base mode, selected file, noise/pre-session toggles, current-vs-turn source, transcript-derived turns, fetched body hunks, todo progress, armed ask path, dock/inline placement, dialog view, and scroll/list geometry. mods/…/initial-model.ts starts in session mode with no data, current source, dock placement, no bodies, and zero todo progress. mods/…/after-fetch.ts applies one refresh: data outcomes replace the model's data, unavailable outcomes keep the previous data on screen, no-repository/null outcomes clear it, and the same transcript read is reduced into turns and todos. mods/…/after-new-session.ts handles /clear and /resume by dropping selections, turn source, turns, and bodies while leaving the last fetch available.
Backend rows are reshaped for display in mods/…/partition-of.ts, mods/…/header-totals-of.ts, mods/…/empty-state-of.ts, mods/…/mode-label-of.ts, and mods/…/dialog-title-of.ts. Current diff rows are sorted by display path, split into session and pre-session rows, and optionally filtered to hide tests/generated files. Header totals subtract pre-session counts from backend totals and preserve a notShown count for rows beyond the fetch cap. Empty states distinguish unavailable diff, no tracked changes because untracked rows were withheld, unborn repositories, uncommitted mode, branch mode, and session mode.
Transcript-derived views are built under mods/diff/hooks/turns/** and mods/diff/hooks/todos/**. mods/…/turn-diffs-of.ts splits $.session.messages() into prompt-delimited turns, drops turns with no edited files, and returns newest first. A turn begins at a non-empty user message without tool results (mods/…/is-prompt-row.ts). mods/…/turn-of.ts truncates the prompt preview to 30 characters, extracts assistant edit/write results, merges repeated edits per path, and cuts hunks through the git hunk cap. mods/…/file-edit-of.ts only accepts non-staged edit/create results with a filePath, using structuredPatch when present or create content as an all-added hunk. mods/…/todo-progress-of.ts finds the latest TodoWrite tool call and counts completed statuses over all todos for the pane progress bar.
Tool integration is intentionally small. mods/…/editing-tools.ts treats Edit, Write, and NotebookEdit success as file-changing events that can auto-open the pane and refresh it. mods/…/shell-tools.ts treats Bash and PowerShell as refresh-only triggers. mods/…/may-have-written.ts mirrors the built-in gating for shell results: thrown calls and non-denied calls count as possible writes unless the engine marks them isReadOnly; denied calls do not. mods/…/todo-tool.ts is the transcript tool name used by todo progress extraction.
Pane open/toggle and surface detection live in mods/diff/hooks/pane-toggle/** and mods/…/is-on-pane-surface.ts. paneToggleOf closes an already-open pane, opens a closed pane when width is unknown or at least OPEN_MIN_COLUMNS, and otherwise reports too-narrow; register.ts passes fullscreen presentation width and uses the answer to call Host.openPane/Host.closePane or return a resize message. isOnPaneSurface rejects mobile render surfaces and lets terminal/desktop pane surfaces draw.
Refresh pacing is handled by mods/…/refresh-rest-of.ts. After a refresh caused by an edit, command, or HEAD move, the next refresh waits for the greater of the previous listing duration (capped at SLOW_REFRESH_REST_MAX_MS) and a timeout backoff (TIMED_OUT_REST_MS doubled per consecutive timeout up to TIMED_OUT_REST_MAX_MS). If that wait would not exceed the normal REFRESH_DEBOUNCE_MS, it returns 0 and the debounce is enough.
Rendering begins at mods/…/pane-view.tsx. A docked seat draws mods/…/sidebar-pane.tsx with a right pad; an inline seat draws mods/…/dialog-pane.tsx, except fullscreen terminals narrower than OPEN_MIN_COLUMNS get the resize note. mods/…/prelude-of.tsx short-circuits both layouts before data settles, showing either a not-in-repository line or a centered Loading diff… message.
The docked layout mirrors the built-in sidebar. mods/…/dock-plan-of.ts decides the header totals, base/turn/unborn line, listed rows, pre-session rows, hidden-noise notes, empty messages, and whether untracked-withheld text is needed. mods/…/sidebar-pane.tsx pins the header, source picker, base-cycle button, todo bar, and summary list; then mods/…/body-layout-of.ts lays out the scrolling body from segments produced by mods/…/segments-of.ts. mods/…/draw-window.tsx draws only the hunk/name/note segments in the current scroll window, clamps the requested top, and stops when the code/text budget is exceeded. Docked interactions use mods/…/place-at-file.ts to jump a list row to its body block, mods/…/list-scrolled-by.ts for the eight-row summary window, mods/…/body-scrolled-by.ts for wheel/page/home/end body scrolling, and mods/…/is-wheel-over-list.ts to route wheel ticks over an overflowing list to list scrolling rather than body scrolling.
The inline dialog layout in mods/…/dialog-pane.tsx lists current or turn files five at a time, shows more files edges, switches to detail mode on selection, and sizes itself through mods/…/dialog-rows-of.ts. mods/…/dialog-entries-of.ts lists turn files from transcript hunks or all backend files sorted by display path. mods/…/dialog-window-of.ts centers the five-row window on the selected path. mods/…/dialog-focus-of.ts translates focus-ring movement into selected paths and landing keys while suppressing wraparound jumps from the first/last file. mods/…/message-pane-of.tsx centers empty/loading messages in the available rows and optionally keeps a pre-session toggle at the foot.
Rows and detail rendering are shared. mods/…/body-entry-of.ts combines a backend file stat with the model's bodies map, where undefined means still loading and null means unreadable. mods/…/turn-entry-of.ts wraps turn hunks as already-loaded non-binary entries. mods/…/detail-view.tsx draws a name row, divider, code blocks, or placeholders. mods/…/placeholder-of.ts supplies untracked, binary, loading, unavailable, large, and empty-body messages. mods/…/code-blocks-of.ts and mods/…/sub-hunks-of.ts split hunks under host leaf and body budgets. mods/diff/hooks/views/layout/** sanitizes names and diff lines, measures terminal cell widths, pads/truncates rows, handles tabs, and pluralizes counts so backend strings and transcript text cannot inject invisible/control characters into the render tree.
Pane controls are declared in mods/…/pane-actions.ts: select a file, scroll the docked list, toggle noise, toggle pre-session, cycle base, choose current/turn source, and arm/disarm a file diff for the next prompt. register.ts owns the mutable closures for these actions; the view code only calls the functions through the Kit type in mods/…/kit.ts.
Telemetry parity is under mods/diff/hooks/record/**. mods/…/recorder-of.ts wraps Host.mark and Host.log and drops missing/refused telemetry through mods/…/safely.ts. It emits built-in-compatible feature names from mods/…/features.ts, shown triggers from mods/…/shown-triggers.ts, tab names from mods/…/tabs.ts, base-resolve outcomes from mods/…/base-outcomes.ts, and terminal width buckets from mods/…/width-bucket-of.ts.
Coverage / Routing
This doc owns the diff pane view/tool layer under:
mods/diff/hooks/host/**mods/diff/hooks/is-on-pane-surface/**mods/diff/hooks/pane-state/**mods/diff/hooks/pane-toggle/**mods/diff/hooks/refresh-rest-of/**mods/diff/hooks/todos/**mods/diff/hooks/tools/**mods/diff/hooks/turns/**mods/diff/hooks/views/**mods/diff/hooks/record/**
Route changes here when they alter how fetched backend diff state, transcript/tool state, or pane UI events are represented in PaneModel, converted into docked/inline rows, acted on by pane controls, or recorded as telemetry. Backend git fetching/classification itself belongs to the backend/git docs; orchestration details in mods/…/register.ts only belong here when needed to explain how these helpers are invoked.
Coupling
- If backend fetch shapes change, update mods/…/after-fetch.ts, mods/…/header-totals-of.ts, mods/…/empty-state-of.ts, mods/…/body-entry-of.ts, and mods/…/dialog-entries-of.ts together. They assume
Git.FetchOutcome,Git.DiffData.stats,Git.FileStat,isUntrackedWithheld,isUnborn, andsourcecarry the fields needed to keep previous data on unavailable reads and to render empty/base labels correctly. - If tool result schemas change, update both
mods/diff/hooks/tools/**and transcript reducers in mods/…/file-edit-of.ts and mods/…/todo-progress-of.ts. Refresh/open behavior is based on tool names and result flags, while turn/todo rendering reads transcript payloads directly and will silently omit rows if field names drift. - If
mods/diff/hooks/limits/**changes pane widths, row windows, listed turns, or refresh timing, verify mods/…/pane-toggle-of.ts, mods/…/pane-view.tsx, mods/…/source-picker.tsx, mods/…/body-layout-of.ts, mods/…/dialog-window-of.ts, and mods/…/refresh-rest-of.ts. These helpers duplicate built-in layout/timing thresholds rather than deriving them dynamically. - If the engine UI event contract changes, verify mods/…/is-on-pane-surface.ts, mods/…/ui.ts, mods/…/pane-seat.ts, mods/…/dialog-focus-of.ts, and mods/…/is-wheel-over-list.ts. They depend on render
surface, paneplacement, viewport columns/fullscreen, focus element keys, and scroll pointer rows. - If row keys or displayed path formatting change, update mods/…/file-key-of.ts, mods/…/ask-key-of.ts, mods/…/dialog-focus-of.ts, mods/…/place-at-file.ts, and the row renderers in
mods/diff/hooks/views/sections/**. Focus landing, ask buttons, and scroll-to-file behavior all use stable keys/paths to reconnect user actions to model state. - If telemetry names or props change, update mods/…/features.ts, mods/…/recorder-of.ts, mods/…/tabs.ts, mods/…/shown-triggers.ts, and mods/…/width-bucket-of.ts with the call sites in mods/…/register.ts. The recorder intentionally emits rows shaped like the built-in panel's metrics.
Risks
- mods/…/dialog-focus-of.ts, mods/…/body-scrolled-by.ts, mods/…/is-wheel-over-list.ts, and mods/…/dialog-rows-of.ts are tightly coupled to engine focus/scroll sizing. Recent history contains focused parity fixes for dialog focus wrapping, list-wheel routing, and dialog row sizing; if the engine changes how focus keys wrap or how scroll rows are reported, selection can jump to the wrong file or wheel/page events can scroll the wrong region.
- mods/…/may-have-written.ts treats missing
isReadOnlyas a possible write. This is safe but intentionally refresh-heavy; a tool API change that stops settingisReadOnlyfor read-only shell commands would makeBash/PowerShellcalls refresh the diff after reads such asgit status. - mods/…/code-blocks-of.ts, mods/…/sub-hunks-of.ts, and mods/…/draw-window.tsx enforce host leaf/tree budgets manually. If the host's render limits change, long diffs may truncate too early or still exceed the render tree budget unless the constants in mods/…/max-body-chars.ts, mods/…/max-code-chars.ts, and related budget files move with them.