AGENTS.md

1# Mobile Diff Editors
2 
3This document is the seed design note for the mobile file diff editor and mobile multi-file diff editor in Agent Sessions. Keep it intentionally small for now; it can grow toward a fuller user-guide shape as the implementation settles.
4 
5> Quick summary: mobile diff review uses phone-native full-screen overlays instead of desktop panes. The single-file view renders one unified diff. The multi-file view renders changed files in a continuous review surface with file-level and body-level virtualization.
6 
7## Contents
8 
9- [Why](#why)
10- [Current Design](#current-design)
11- [How It Works](#how-it-works)
12- [Body Virtualization](#body-virtualization)
13- [Rendering Ideas](#rendering-ideas)
14 
15## Why
16 
17Phone review needs the same capability as desktop review, but not the same presentation.
18 
19- Desktop side-by-side diffs are too wide for phone viewports.
20- Desktop auxiliary views are gated off in phone layout.
21- Touch review needs full-screen surfaces, sticky context, simple back navigation, and visible controls.
22- Large agent sessions need to avoid eager work for files the user has not opened or scrolled to yet.
23 
24## Current Design
25 
26There are two mobile diff surfaces:
27 
28- `MobileDiffView`: a single-file unified diff overlay with optional sibling navigation.
29- `MobileMultiDiffView`: a virtualized multi-file unified diff overlay with per-file headers, collapsible file bodies, and lazy loading for visible or near-visible files.
30 
31Both views use a lightweight diff payload:
32 
33```ts
34interface IFileDiffViewData {
35	readonly originalURI: URI | undefined;
36	readonly modifiedURI: URI | undefined;
37	readonly identical: boolean;
38	readonly added: number;
39	readonly removed: number;
40}
41```
42 
43This supports added, deleted, modified, and no-op files without importing desktop multi-diff workbench types into the mobile browser layer.
44 
45## How It Works
46 
47- File content is read from `ITextFileService`, with `IFileService` as a fallback in the multi-file view.
48- The multi-file view keeps persistent per-file state, reserves virtual height from known diff stats, and only mounts file sections that intersect the viewport overscan range.
49- File content is read, diffed, tokenized, and mounted incrementally as virtualized items become visible.
50- Test/demo hosts can pass an async `computeDiff` hook; the Vite mobile multi-diff page uses this to compute diffs in a worker and better mimic VS Code's worker-backed diff environment.
51- Virtualization owns mounted range and deterministic height accounting; native CSS owns sticky file-header behavior.
52- Keep file sections anchored at their virtual top so headers can use `position: sticky`; do not emulate sticky headers by moving sections on every scroll frame.
53- Lazy loading may defer file work, but visible file bodies must never be blank; unloaded or loading bodies need a stable placeholder that remains visible during native scrolling.
54- Prefetch can warm one near-boundary file's render data, but it should not mount DOM for that file and visible loads must keep priority over background work.
55- Loaded multi-file diff bodies flatten hunk headers and line rows into deterministic body entries, then render only the visible body range plus overscan.
56- Line changes are computed with `linesDiffComputers.getDefault()`.
57- The result is shaped into unified diff hunks with a small amount of surrounding context.
58- Syntax highlighting first tries Monaco tokenization through `tokenizeToString`.
59- When no tokenizer is available, a small regex tokenizer provides readable fallback colors.
60- Async rendering is guarded by generation counters so stale reads cannot update disposed or navigated-away views.
61 
62## Body Virtualization
63 
64`MobileMultiDiffView` uses two virtualization layers.
65 
66- The outer layer virtualizes file sections and keeps each file's full height in the scroll range.
67- The body layer virtualizes hunk headers and line rows within a loaded file.
68 
69The important behavior to preserve is that a large file contributes its full content height to the outer virtual scroll range. File sections stay anchored in that range, and the browser handles sticky file headers. Avoid JS-driven header pinning; it can drift during fast compositor scrolling.
70 
71The body layer should keep reusing cached diff/tokenization data, render only the visible hunk/line slice, and keep height accounting deterministic so outer scroll position remains stable as bodies load.
72 
73One remaining polish item is preserving horizontal scroll state per file when a virtualized section unmounts and remounts.
74 
75## Rendering Ideas
76 
77Useful ideas to borrow from Monaco/editor virtualization:
78 
79- Applied: reuse visible row DOM instead of clearing and rebuilding the whole visible body slice on every range change.
80- Applied: batch newly visible row runs, building markup in one pass before inserting it.
81- Applied: keep mounted file sections in DOM order without re-appending them on every scroll layout update.
82- Prefetch and cache render data for near-visible files, but do not pre-render their DOM.
83- Keep loaded rows positioned with absolute `top`; avoid transform-driven scrolling for loaded content because native sticky headers depend on stable section positioning.
84- Preserve horizontal scroll state per file across virtualized unmount/remount cycles.
85