Minimap (code overview) — GTK font scaling, TUI braille, quadraui-owned logic, on/off setting

[JDonaghy]

Code-overview minimap on the right edge of each editor pane: a scaled-down rendering of the
whole file with the viewport highlighted, click/drag to scroll.

Rewritten 2026-08-31. Three changes from the previous revision: the TUI rendering
technique is now braille (not block-character approximation), the GTK technique is
stated as font scaling rather than "Cairo scaled rendering", and the on/off setting is
a hard requirement with its own acceptance criteria, not a bullet under "Features". The
quadraui-first design is unchanged and is still the point of the issue. The "Key files"
list was also stale — render.rs and the backends moved.

Features

• Click/drag to scroll the main editor
• Syntax-coloured (dominant colour per rendered region)
• Off/on via a minimap setting — see The setting below

Backends

backend	technique	density
GTK	font scaling — real glyphs via Pango at a scaled-down absolute size (VS Code's minimap.renderCharacters: true), with a colour-bar fallback below the legibility floor	1 buffer line per ~2–6 px row
TUI	braille — U+2800 dot cells, 2 dots wide × 4 tall per terminal cell	4 buffer lines per terminal row
Win-GUI	out of scope until the Win backend ships in quadraui

Braille replaces the previous "block-character approximation, 1 cell per minimap line". It is
8× denser, and quadraui already has a working dot-packing implementation to lift from
(quadraui/src/tui/chart.rs:158–:245, incl. the BRAILLE_OFFSETS bit table), so this is
cheaper and better than what it replaces.

Design: quadraui-first (platform-neutral) — the whole point of this issue

This feature must not add substantive logic to src/gtk/ or src/tui_main/. All scale
math, line sampling, colour aggregation and dot packing live in quadraui.

1. quadraui prerequisite — quadraui#382 (Minimap primitive + both rasterisers):
   Minimap descriptor, Minimap::layout(), Backend::draw_minimap(), sample_lines(),
   aggregate_spans(), reserved_width(). Note that aggregate_spans aggregates per
   cell, not per line — a braille cell carries one foreground colour across 4 buffer
   lines, so per-line colours would force the TUI backend to re-reduce them, which is exactly
   the platform-specific arithmetic this design forbids.

2. vimcode side (after the primitive lands and the pin is bumped):

   • build_minimap_data() in src/render.rs — samples lines, hands syntax spans to
     aggregate_spans, builds the Minimap. Returns None when the setting is off.
   • ScreenLayout (src/render.rs:4239) gains minimap: Option<RenderedMinimap>.
   • Editor content width comes from quadraui::minimap::reserved_width(..) in both
     backends — do not compute the reclaimed width twice.
   • Each backend calls backend.draw_minimap(rect, &minimap). Thin wiring only.
   • Click/drag routes through the existing ClickTarget system → standard scroll commands.

The setting (required)

A minimap: bool option, defaulting to on, following the indent_guides precedent
exactly. In src/core/settings.rs that is eight sites — the option plumbing here is a
checklist, and missing one produces an option that works from :set but not from the
settings UI (or vice versa):

what	indent_guides reference
field + #[serde(default = ...)]	:296
default_minimap()	:339
entry in the Default construction	:788
parse_set_option boolean branch (minimap / nominimap)	:1082
:set minimap? query form	:1342
get-by-key string	:1475
set-by-key string	:1589
SettingDef { key, label, description, category: "Editor", setting_type: Bool } registry entry	:2038

Both spellings (minimap and nominimap) must work, and the setting must take effect on the
next paint without a restart — the editor reclaims the minimap's width when it is turned off.

Key files

• src/render.rs — build_minimap_data(), ScreenLayout.minimap (:4239)
• src/core/settings.rs — the eight sites above
• src/gtk/mod.rs — thin draw_minimap wiring
• src/tui_main/render_impl.rs — thin draw_minimap wiring
• Cargo.toml — quadraui rev pin bump (vimcode#691: rev-pinned, not a path dep;
  cargo update -p quadraui will not move it)
• quadraui: primitives/minimap.rs, gtk/minimap.rs, tui/minimap.rs

Acceptance

• :set nominimap hides it and the editor text area widens by exactly the reserved width;
  :set minimap restores both — asserted, not eyeballed
• :set minimap? reports minimap / nominimap
• the setting round-trips through the settings file and appears in the settings UI list
• TUI: a snapshot test (src/tui_main/snapshots/) covering a file with a distinctive
  indentation shape, showing braille glyphs — the snapshot is what pins that the dot grid
  is not transposed
• GTK: a pixel assertion in src/gtk/testing.rs that the minimap column is painted and
  that its width matches reserved_width
• click at the vertical middle of the minimap scrolls to ~50% of the file, in both
  backends
• platform-neutrality gate: grep -rn 'minimap' src/gtk/ src/tui_main/ returns only
  draw_minimap call sites and rect plumbing — no sampling, no scale arithmetic, no dot
  packing, no colour aggregation. If a reviewer finds any of those outside quadraui, that
  is a request-changes regardless of whether it works.

Blocked on

quadraui#382 (Minimap primitive), then a Cargo.toml pin bump here.

[JDonaghy]

Coordinator: Assignment Complete

Machine: elitebook
Status: done
Exit code: 0
Duration: 1m 7s

[JDonaghy]

Coordinator Assignment

Machine: dellserver
Repo: vimcode
Files: (unspecified)
Do not touch: (nothing else in flight)

Briefing

Issue #35: Minimap (code overview) — GTK font scaling, TUI braille, quadraui-owned logic, on/off setting

Code-overview minimap on the right edge of each editor pane: a scaled-down rendering of the
whole file with the viewport highlighted, click/drag to scroll.

Rewritten 2026-08-31. Three changes from the previous revision: the TUI rendering
technique is now braille (not block-character approximation), the GTK technique is
stated as font scaling rather than "Cairo scaled rendering", and the on/off setting is
a hard requirement with its own acceptance criteria, not a bullet under "Features". The
quadraui-first design is unchanged and is still the point of the issue. The "Key files"
list was also stale — render.rs and the backends moved.

Features

• Click/drag to scroll the main editor
• Syntax-coloured (dominant colour per rendered region)
• Off/on via a minimap setting — see The setting below

Backends

backend	technique	density
GTK	font scaling — real glyphs via Pango at a scaled-down absolute size (VS Code's minimap.renderCharacters: true), with a colour-bar fallback below the legibility floor	1 buffer line per ~2–6 px row
TUI	braille — U+2800 dot cells, 2 dots wide × 4 tall per terminal cell	4 buffer lines per terminal row
Win-GUI	out of scope until the Win backend ships in quadraui

Braille replaces the previous "block-character approximation, 1 cell per minimap line". It is
8× denser, and quadraui already has a working dot-packing implementation to lift from
(quadraui/src/tui/chart.rs:158–:245, incl. the BRAILLE_OFFSETS bit table), so this is
cheaper and better than what it replaces.

Design: quadraui-first (platform-neutral) — the whole point of this issue

This feature must not add substantive logic to src/gtk/ or src/tui_main/. All scale
math, line sampling, colour aggregation and dot packing live in quadraui.

1. quadraui prerequisite — quadraui#382 (Minimap primitive + both rasterisers):
   Minimap descriptor, Minimap::layout(), Backend::draw_minimap(), sample_lines(),
   aggregate_spans(), reserved_width(). Note that aggregate_spans aggregates per
   cell, not per line — a braille cell carries one foreground colour across 4 buffer
   lines, so per-line colours would force the TUI backend to re-reduce them, which is exactly
   the platform-specific arithmetic this design forbids.

2. vimcode side (after the primitive lands and the pin is bumped):

   • build_minimap_data() in src/render.rs — samples lines, hands syntax spans to
     aggregate_spans, builds the Minimap. Returns None when the setting is off.
   • ScreenLayout (src/render.rs:4239) gains minimap: Option<RenderedMinimap>.
   • Editor content width comes from quadraui::minimap::reserved_width(..) in both
     backends — do not compute the reclaimed width twice.
   • Each backend calls backend.draw_minimap(rect, &minimap). Thin wiring only.
   • Click/drag routes through the existing ClickTarget system → standard scroll commands.

The setting (required)

A minimap: bool option, defaulting to on, following the indent_guides precedent
exactly. In src/core/settings.rs that is eight sites — the option plumbing here is a
checklist, and missing one produces an option that works from :set but not from the
settings UI (or vice versa):

what	indent_guides reference
field + #[serde(default = ...)]	:296
default_minimap()	:339
entry in the Default construction	:788
parse_set_option boolean branch (minimap / nominimap)	:1082
:set minimap? query form	:1342
get-by-key string	:1475
set-by-key string	:1589
SettingDef { key, label, description, category: "Editor", setting_type: Bool } registry entry	:2038

Both spellings (minimap and nominimap) must work, and the setting must take effect on the
next paint without a restart — the editor reclaims the minimap's width when it is turned off.

Key files

• src/render.rs — build_minimap_data(), ScreenLayout.minimap (:4239)
• src/core/settings.rs — the eight sites above
• src/gtk/mod.rs — thin draw_minimap wiring
• src/tui_main/render_impl.rs — thin draw_minimap wiring
• Cargo.toml — quadraui rev pin bump (vimcode#691: rev-pinned, not a path dep;
  cargo update -p quadraui will not move it)
• quadraui: primitives/minimap.rs, gtk/minimap.rs, tui/minimap.rs

Acceptance

• :set nominimap hides it and the editor text area widens by exactly the reserved width;
  :set minimap restores both — asserted, not eyeballed
• :set minimap? reports minimap / nominimap
• the setting round-trips through the settings file and appears in the settings UI list
• TUI: a snapshot test (src/tui_main/snapshots/) covering a file with a distinctive
  indentation shape, showing braille glyphs — the snapshot is what pins that the dot grid
  is not transposed
• GTK: a pixel assertion in src/gtk/testing.rs that the minimap column is painted and
  that its width matches reserved_width
• click at the vertical middle of the minimap scrolls to ~50% of the file, in both
  backends
• platform-neutrality gate: grep -rn 'minimap' src/gtk/ src/tui_main/ returns only
  draw_minimap call sites and rect plumbing — no sampling, no scale arithmetic, no dot
  packing, no colour aggregation. If a reviewer finds any of those outside quadraui, that
  is a request-changes regardless of whether it works.

Blocked on

quadraui#382 (Minimap primitive), then a Cargo.toml pin bump here.

[JDonaghy]

Coordinator: Advisory — Worker Exited With 0 Commits

Machine: dellserver
Status: advisory
Duration: 1m 21s
Log: /home/john/.coord/logs/38271abf4552.log

The worker exited cleanly (exit code 0) but pushed no commits. This typically means the feature was already implemented or no change was needed. Human review is required to decide the next step.

Worker note

worker exited cleanly but pushed 0 commits

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 26m 40s
Log: /home/john/.coord/logs/e1d23d94dfd2.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: precision
Status: done
Exit code: 0
Duration: 2m 16s
Log: /home/john/.coord/logs/e65ed531a854.log

[JDonaghy]

Coordinator: Assignment Complete

Machine: dellserver
Status: done
Exit code: 0
Duration: —

Summary

Verdict: request-changes

Review findings

Blocking findings

• GTK minimap drag-to-scroll does not work -- only the initial mouse-down click seeks. src/gtk/click.rs:96-101 gates the whole minimap hit-test (apply_minimap_click) behind if mutate_focus. handle_mouse_drag (src/gtk/click.rs:702-722) always calls pixel_to_click_target(..., false) for drag continuation, and apply_minimap_click/pixel_to_click_target never call drag_state.begin(...) for the minimap, so handle_mouse_drag_msg's shared drag_active fast-path (src/gtk/mod.rs ~4880) never triggers for it either. Net effect: pressing and holding on the GTK minimap and dragging up/down does not continue to scroll -- you only get the position under the initial mouse-down. This contradicts the issue's top-level Feature bullet "Click/drag to scroll the main editor" and the vimcode-side design note "Click/drag routes through the existing ClickTarget system -> standard scroll commands." It also directly contradicts the PR's own comment in src/tui_main/mouse.rs ("Drag keeps seeking while the button is held, matching the GTK side") -- that claim is false; TUI supports drag-seek (its handle_mouse matches both Down and Drag unconditionally), GTK does not. No test in the PR exercises a drag on the GTK minimap (the only GTK click test, minimap_click_at_the_middle_scrolls_to_half_the_file in src/gtk/testing.rs, uses a single driver.click(...)), so this gap ships uncaught.

• Most of the new driver-tier ("black-box") tests carry no statement that they were observed RED against unfixed develop, which CLAUDE.md's Testing section makes mandatory for every behaviour-changing PR ("#448-F: GTK tab click (activate/close) dead when only ONE tab group exists #553 shipped black-box tests that stayed green with the bug reinstated... No such statement is a request-changes"). Only one test in the whole PR has this: minimap_paints_a_strip_whose_width_matches_reserved_width (src/gtk/testing.rs, explicit "RED-first: ... confirmed by hand before restoring the fix" comment). None of the following carry any such statement: minimap_click_at_the_middle_scrolls_to_half_the_file (GTK, src/gtk/testing.rs), snapshot_minimap_braille / nominimap_paints_no_braille (src/tui_main/render_impl.rs), or render_content_paints_minimap_braille_via_shell_app / render_content_paints_no_minimap_when_the_setting_is_off / minimap_click_at_the_middle_scrolls_to_half_the_file (TUI, src/tui_main/shell_app.rs). Neither commit message (c7d9aef, f88db64) states this either. Per the project's own testing policy this is a request-changes regardless of how good the tests otherwise look.

• minimap_click_at_the_middle_scrolls_to_half_the_file (GTK, src/gtk/testing.rs) asserts on h.engine.borrow().scroll_top() -- internal engine state -- not on painted/screen content. CLAUDE.md is explicit that this class of assertion is a reject: "Assert on rendered output -- never on state being populated... A test asserting the field is Some [or, by the same logic, a state value changed] passes against the bug." A regression where the click correctly mutates scroll_top but the frame never actually repaints to reflect the new position (exactly the Command palette fails to open silently (broken on develop) #587/GTK live render path silently drops 13 populated ScreenLayout fields (rest of #587's blast radius) #592 bug shape the policy calls out) would still pass this test. Contrast with the TUI equivalent in src/tui_main/shell_app.rs, which correctly reads back painted line numbers (top_line(&after)) from driver.screen() -- the GTK test should do the analogous thing (e.g. read a painted line-number/gutter value, or otherwise confirm the paint moved) rather than trusting engine state alone.

Non-blocking concerns

• minimap_click_line (src/render.rs) calls mm.minimap.layout(minimap_strip_rect(mm), MINIMAP_LINES_PER_ROW) directly (the primitive's own method) rather than routing through Backend::minimap_layout, which quadraui added specifically to mirror chart_layout/tree_layout for exactly this purpose ("Apps call this ... to hit-test a click against the same geometry the last paint used"). Today this is harmless because MinimapLayout::hit_test only reads bounds, which is identical regardless of lines_per_row -- but it's a second, hardcoded path that could silently diverge from what each backend actually painted if hit_test/layout ever start depending on the row grouping.
• The minimap is computed/painted only for the active window (build_screen_layout_with_breadcrumb_row only narrows/builds it for active_window_id), while the issue's title and Features list say "on the right edge of each editor pane." The more detailed "vimcode side" design section does say ScreenLayout gains a singular minimap: Option<RenderedMinimap>, so this looks like the intended, more-authoritative scope -- but worth a sentence in the PR description confirming that's deliberate, since a user with a :vsplit open will only see a minimap on the focused pane.
• The narrow-window suppression path (MINIMAP_MIN_TEXT_COLS, minimap_suppresses_itself_in_a_narrow_window) is only unit-tested against render.rs helpers directly, not through either driver. A regression that silently disabled the minimap at normal window widths wouldn't be caught by a GtkDriver/TuiDriver test.

Nits

• The src/tui_main/mouse.rs comment "Drag keeps seeking while the button is held, matching the GTK side" should be corrected (or GTK's drag support added) once the first blocking finding is addressed -- right now it asserts a cross-backend parity that doesn't exist.

[JDonaghy]

Review Complete — ⚠️ Changes Requested

Reviewer findings could not be posted directly to PR #714 (gh pr review was rejected — likely a self-review restriction). Findings are reproduced here.

Note: a completion comment was posted earlier but findings could not be extracted at that time. These are the retroactive findings.

Blocking findings

• GTK minimap drag-to-scroll does not work — only the initial mouse-down click seeks. src/gtk/click.rs:96-101 gates the whole minimap hit-test (apply_minimap_click) behind if mutate_focus. handle_mouse_drag (src/gtk/click.rs:702-722) always calls pixel_to_click_target(..., false) for drag continuation, and apply_minimap_click/pixel_to_click_target never call drag_state.begin(...) for the minimap, so handle_mouse_drag_msg's shared drag_active fast-path (src/gtk/mod.rs ~4880) never triggers for it either. Net effect: pressing and holding on the GTK minimap and dragging up/down does not continue to scroll — you only get the position under the initial mouse-down. This contradicts the issue's top-level Feature bullet "Click/drag to scroll the main editor" and the vimcode-side design note "Click/drag routes through the existing ClickTarget system → standard scroll commands." It also directly contradicts the PR's own comment in src/tui_main/mouse.rs ("Drag keeps seeking while the button is held, matching the GTK side") — that claim is false; TUI supports drag-seek (its handle_mouse matches both Down and Drag unconditionally), GTK does not. No test in the PR exercises a drag on the GTK minimap (the only GTK click test, minimap_click_at_the_middle_scrolls_to_half_the_file in src/gtk/testing.rs, uses a single driver.click(...)), so this gap ships uncaught.

• Most of the new driver-tier ("black-box") tests carry no statement that they were observed RED against unfixed develop, which CLAUDE.md's Testing section makes mandatory for every behaviour-changing PR ("#448-F: GTK tab click (activate/close) dead when only ONE tab group exists #553 shipped black-box tests that stayed green with the bug reinstated... No such statement is a request-changes"). Only one test in the whole PR has this: minimap_paints_a_strip_whose_width_matches_reserved_width (src/gtk/testing.rs, explicit "RED-first: ... confirmed by hand before restoring the fix" comment). None of the following carry any such statement: minimap_click_at_the_middle_scrolls_to_half_the_file (GTK, src/gtk/testing.rs), snapshot_minimap_braille / nominimap_paints_no_braille (src/tui_main/render_impl.rs), or render_content_paints_minimap_braille_via_shell_app / render_content_paints_no_minimap_when_the_setting_is_off / minimap_click_at_the_middle_scrolls_to_half_the_file (TUI, src/tui_main/shell_app.rs). Neither commit message (c7d9aef, f88db64) states this either. Per the project's own testing policy this is a request-changes regardless of how good the tests otherwise look.

• minimap_click_at_the_middle_scrolls_to_half_the_file (GTK, src/gtk/testing.rs) asserts on h.engine.borrow().scroll_top() — internal engine state — not on painted/screen content. CLAUDE.md is explicit that this class of assertion is a reject: "Assert on rendered output — never on state being populated... A test asserting the field is Some [or, by the same logic, a state value changed] passes against the bug." A regression where the click correctly mutates scroll_top but the frame never actually repaints to reflect the new position (exactly the Command palette fails to open silently (broken on develop) #587/GTK live render path silently drops 13 populated ScreenLayout fields (rest of #587's blast radius) #592 bug shape the policy calls out) would still pass this test. Contrast with the TUI equivalent in src/tui_main/shell_app.rs, which correctly reads back painted line numbers (top_line(&after)) from driver.screen() — the GTK test should do the analogous thing (e.g. read a painted line-number/gutter value, or otherwise confirm the paint moved) rather than trusting engine state alone.

Non-blocking concerns

• minimap_click_line (src/render.rs) calls mm.minimap.layout(minimap_strip_rect(mm), MINIMAP_LINES_PER_ROW) directly (the primitive's own method) rather than routing through Backend::minimap_layout, which quadraui added specifically to mirror chart_layout/tree_layout for exactly this purpose ("Apps call this ... to hit-test a click against the same geometry the last paint used"). Today this is harmless because MinimapLayout::hit_test only reads bounds, which is identical regardless of lines_per_row — but it's a second, hardcoded path that could silently diverge from what each backend actually painted if hit_test/layout ever start depending on the row grouping.
• The minimap is computed/painted only for the active window (build_screen_layout_with_breadcrumb_row only narrows/builds it for active_window_id), while the issue's title and Features list say "on the right edge of each editor pane." The more detailed "vimcode side" design section does say ScreenLayout gains a singular minimap: Option<RenderedMinimap>, so this looks like the intended, more-authoritative scope — but worth a sentence in the PR description confirming that's deliberate, since a user with a :vsplit open will only see a minimap on the focused pane.
• The narrow-window suppression path (MINIMAP_MIN_TEXT_COLS, minimap_suppresses_itself_in_a_narrow_window) is only unit-tested against render.rs helpers directly, not through either driver. A regression that silently disabled the minimap at normal window widths wouldn't be caught by a GtkDriver/TuiDriver test.

Nits

• The src/tui_main/mouse.rs comment "Drag keeps seeking while the button is held, matching the GTK side" should be corrected (or GTK's drag support added) once the first blocking finding is addressed — right now it asserts a cross-backend parity that doesn't exist.