P1-14: Document Map (minimap)

[hybridmachine]

Description

Narrow zoomed-out view of the document on the right side of the editor.

Implementation

• Create a second ScintillaView as minimap (read-only, zoomed out)
• Position as narrow panel on right side of editor
• Set very small zoom level via SCI_SETZOOM (e.g. -10)
• Highlight visible region of main editor (semi-transparent overlay)
• Click on minimap scrolls main editor to that position
• Sync content changes from main editor to minimap
• Toggle via View menu: "Document Map"
• Hide line numbers and margins in minimap

Key Files

• macos/platform/main_phase7.mm
• macos/platform/scintilla_bridge.h

Sprint

Sprint 8 - Content & Views

[hybridmachine]

Sprint plan: #33 Document Map (minimap)

Goal

Provide a right-side minimap for quick visual navigation and viewport positioning.

Dependency

• Build after P1-13: Synchronized scrolling (split views) #31 (synchronized scrolling) so viewport sync behavior is reusable/consistent.

Implementation breakdown

1. Add minimap component lifecycle.

• Create a dedicated secondary Scintilla view configured as minimap.
• Initialize/destroy alongside editor container lifecycle.

2. Configure minimap rendering profile.

• Read-only mode.
• Disable caret line, margins, line numbers, fold markers, and extra UI chrome.
• Apply zoomed-out level (e.g., SCI_SETZOOM negative value).
• Disable interactions not needed for minimap editing.

3. Layout and resizing.

• Add right-side panel region with fixed/default width and sensible min/max bounds.
• Recompute frame on window resize, split view changes, and sidebar/panel toggles.

4. Content synchronization.

• Keep minimap document/view synchronized with the active editor buffer.
• On tab switch, rebind minimap to the current document.
• On text updates, ensure minimap repaints efficiently.

5. Viewport indicator.

• Compute visible line range from active editor.
• Render a translucent overlay/highlight in minimap corresponding to current viewport.
• Update indicator on vertical/horizontal scroll and resize.

6. Navigation interactions.

• Click in minimap moves main editor near clicked line.
• Drag in minimap scrolls through document continuously (if supported by existing event handling patterns).

7. Toggle + persistence.

• Add View menu toggle (Document Map) with checked state.
• Persist enabled/width state using existing settings/session mechanisms.

Validation

• Manual checks:
  • Toggle shows/hides minimap instantly.
  • Minimap reflects content for current tab.
  • Clicking minimap jumps editor to expected region.
  • Viewport overlay tracks editor scrolling.
  • Works in both single and split view modes.
• Regression checks:
  • No editing capability introduced in minimap.
  • No layout breakage with existing side panels.

Key files

• macos/platform/main_phase7.mm
• macos/platform/scintilla_bridge.h

[hybridmachine]

Plan Review

Overall Assessment

Good high-level breakdown with correct dependency on #31. However, this plan needs more architectural detail given the complexity of adding a third Scintilla view to the existing layout system.

Critical Issues

1. Key file reference is incorrect
main_phase7.mm does not exist in the codebase. The relevant files are:

• macos/platform/app_delegate.mm — view creation and notification handling
• macos/platform/split_view.mm — split view layout, layoutSplitTopTabBars()
• macos/platform/app_state.h — AppContext struct (needs new minimap state fields)
• macos/platform/menu_builder.mm — View menu toggle
• macos/platform/wndproc.mm — command dispatch
• macos/platform/settings_manager.h — persistence (enabled state, width)
• New: macos/platform/document_map.h/mm

2. Missing layout architecture
The app currently uses ctx().splitView (NSSplitView) with ctx().editorContainer and ctx().editorContainer2. The plan doesn't specify where the minimap sits in the view hierarchy:

• Is it a subview inside each editor container?
• A third pane in the NSSplitView?
• A separate NSView alongside the split view?

Recommendation: The minimap should be a separate fixed-width NSView to the right of the editor container (or the NSSplitView when split), managed independently from the split view system. This avoids coupling to split view layout logic.

3. Missing SCI_SETDOCPOINTER — the key mechanism
The plan says "keep minimap document/view synchronized" and "on tab switch, rebind minimap" but doesn't mention SCI_SETDOCPOINTER, which is the Scintilla API for sharing a document between multiple views. Without this, content sync would require manual text copying, which is both slow and fragile. This is how Notepad++ implements Document Map on Windows — the minimap view shares the same document pointer as the active editor.

4. Split view interaction ambiguity
The plan says "works in both single and split view modes" but doesn't address:

• Does the minimap always track ctx().activeView (the focused editor)?
• Or are there two minimaps (one per split)?
• Recommendation: Single minimap tracking the active/focused view, switching on SCN_FOCUSIN.

Design Clarifications Needed

5. Viewport indicator implementation
"Render a translucent overlay/highlight" — this needs more detail. Options:

• Use Scintilla markers/indicators on the minimap view (simpler but limited visual control)
• Overlay a transparent NSView on top of the minimap ScintillaView (more control, macOS-native approach)
  The choice affects how click/drag navigation is handled.

6. Settings fields
Needs bool documentMap and int documentMapWidth added to AppSettings in settings_manager.h.

7. New state fields in AppContext
app_state.h needs fields like void* minimapView, NSView* minimapContainer, bool documentMapEnabled.

Minor Notes

• scintilla_bridge.h is listed as a key file but no changes to the bridge API should be needed — ScintillaBridge_createView and ScintillaBridge_sendMessage already cover minimap creation and configuration.
• The size/L estimate seems appropriate for this scope.
• Consider adding the minimap toggle to the View menu near the existing split view commands.

[hybridmachine]

Sprint plan amendment (addressing review)

Great feedback — this updates the plan with explicit layout architecture and document-sharing mechanics.

Final architecture

1. New module (required by repo pattern)

• Add macos/platform/document_map.h + macos/platform/document_map.mm
• Add to macos/CMakeLists.txt
• Module responsibilities: lifecycle, layout, active-doc binding, viewport indicator, minimap navigation

2. Correct file touch points

• app_delegate.mm: initialize/update document-map layout hooks, focus and notification forwarding
• split_view.mm: coordinate layout updates while split is active
• app_state.h: add minimap state fields
• menu_builder.mm: add View toggle
• wndproc.mm: command dispatch toggle
• settings_manager.h/.mm: persist enabled state and width

3. View hierarchy decision (explicit)

• Do not add minimap as third NSSplitView pane.
• Add a dedicated fixed-width NSView container to the right of the editor region (single editor or split area).
• Keeps minimap independent from split-pane sizing logic.

4. Document sync mechanism (explicit)

• Use Scintilla document sharing:
  • Get active editor document pointer (SCI_GETDOCPOINTER)
  • Bind minimap view with SCI_SETDOCPOINTER
• Rebind on:
  • tab switch
  • active view focus switch (SCN_FOCUSIN)

5. Single minimap behavior in split mode

• One minimap only.
• It tracks ctx().activeView (focused editor), switching source on focus change.

6. Viewport indicator approach

• Use an overlay NSView atop minimap (macOS-native, precise visuals).
• Overlay rectangle maps active editor visible-line range.
• Update on SCN_UPDATEUI scroll events and resize/layout events.

7. Interaction model

• Click in minimap scrolls active editor to corresponding line.
• Optional drag-scroll support in same overlay view if low-risk after click path is stable.

8. Settings + state fields

• settings_manager.h: add bool documentMap = false; int documentMapWidth = 140;
• app_state.h: add bool documentMapEnabled, int documentMapWidth, NSView* documentMapContainer, void* documentMapScintilla

9. Bridge/API constants

• If missing in npp_constants.h, add needed Scintilla message constants (SCI_GETDOCPOINTER, SCI_SETDOCPOINTER, plus any minimap config messages used).

Validation checklist

• Toggle show/hide works in single and split modes
• Minimap always reflects active tab content without text-copying
• Focus switch between split editors retargets minimap correctly
• Click navigation lands on expected line region
• Width + enabled state persist across relaunch