Inline Editor

Data Flow

User presses 'e' on file
  -> enterInlineEditMode()
  -> tmux new-session -d -s {sessionName} {editor} {path}
  -> InlineEditStartedMsg
  -> handleInlineEditStarted()
  -> tty.Model.Enter()
  -> Start polling tmux capture-pane
  -> renderInlineEditorContent() in preview pane
  -> User types -> tty.Model forwards to tmux
  -> User exits -> SessionDeadMsg or exit keys
  -> exitInlineEditMode()
  -> Refresh preview

Key Files

Critical Implementation Details

1. Preview Pane Rendering (Not Full-Screen)

The editor renders within renderPreviewPane(), NOT as a full-screen takeover. The file tree stays visible.

// view.go - renderPreviewPane()
func (p *Plugin) renderPreviewPane(visibleHeight int) string {
    if p.inlineEditMode && p.inlineEditor != nil && p.inlineEditor.IsActive() {
        return p.renderInlineEditorContent(visibleHeight)
    }
    // ... normal preview rendering
}

2. Dimension Calculations

The tty.Model needs exact dimensions matching the preview pane content area:

func (p *Plugin) calculateInlineEditorWidth() int {
    if !p.treeVisible {
        return p.width - 4 // borders + padding
    }
    p.calculatePaneWidths()
    return p.previewWidth - 4
}

func (p *Plugin) calculateInlineEditorHeight() int {
    paneHeight := p.height
    innerHeight := paneHeight - 2 // pane borders
    contentHeight := innerHeight - 2 // header lines
    if len(p.tabs) > 1 {
        contentHeight-- // tab line
    }
    return contentHeight
}

These MUST stay in sync with renderInlineEditorContent() layout calculations.

3. Confirmation Behavior

Rule: session alive = show confirmation, session dead = exit immediately.

Always show confirmation when the session is alive, regardless of file modification status. Vim's modification status cannot be reliably detected externally.

func (p *Plugin) isInlineEditSessionAlive() bool {
    if p.inlineEditSession == "" {
        return false
    }
    err := exec.Command("tmux", "has-session", "-t", p.inlineEditSession).Run()
    return err == nil
}

Check session alive status:

1. At the start of Update() when in inline edit mode - if dead, exit immediately
2. In click-away handling - if dead, skip confirmation and clean up

4. Exit Confirmation Dialog

State fields:

showExitConfirmation bool        // Dialog visible
pendingClickRegion   string      // Where user clicked
pendingClickData     interface{} // Click data (tree index, tab index)
exitConfirmSelection int         // 0=Save&Exit, 1=Exit without saving, 2=Cancel

Options:

• Save & Exit: Sends editor-appropriate save-and-quit sequence, waits for session death
• Exit without saving: Kills tmux session immediately
• Cancel: Returns to editing

5. Click-Away Detection

Mouse regions are registered during render. Clicks between items may miss regions, so always include position-based fallback:

if p.inlineEditMode && p.inlineEditor != nil && p.inlineEditor.IsActive() {
    action := p.mouseHandler.HandleMouse(msg)

    handleClickAway := func(regionID string, regionData interface{}) (*Plugin, tea.Cmd) {
        if !p.isInlineEditSessionAlive() {
            p.exitInlineEditMode()
            p.pendingClickRegion = regionID
            p.pendingClickData = regionData
            return p.processPendingClickAction()
        }
        p.pendingClickRegion = regionID
        p.pendingClickData = regionData
        p.showExitConfirmation = true
        p.exitConfirmSelection = 0
        return p, nil
    }

    if action.Type == mouse.ActionClick {
        if action.Region != nil {
            switch action.Region.ID {
            case regionTreePane, regionTreeItem, regionPreviewTab:
                return handleClickAway(action.Region.ID, action.Region.Data)
            }
        }
        // Fallback: position-based detection
        if p.treeVisible && action.X < p.treeWidth {
            return handleClickAway(regionTreePane, nil)
        }
    }
    // Forward to tty model
    return p, p.inlineEditor.Update(msg)
}

6. Gradient Border Feedback

Visual indicator that edit mode is active:

if p.inlineEditMode && p.inlineEditor != nil && p.inlineEditor.IsActive() {
    rightPane = styles.RenderPanelWithGradient(previewContent, p.previewWidth,
        paneHeight, styles.GetInteractiveGradient())
}

7. Mouse Support (SGR Protocol)

Full mouse interaction including text selection via SGR (1006) protocol. Mouse events are forwarded to the tty model which translates them into SGR escape sequences: \x1b[<button;x;y;M/m where M = press/drag, m = release.

8. Multi-Editor Support

sendEditorSaveAndQuit() detects which editor is running and sends the appropriate sequence:

Exit Paths

State Management

Plugin State (plugin.go)

inlineEditor         *tty.Model // Embeddable tty model
inlineEditMode       bool       // Currently editing
inlineEditSession    string     // Tmux session name
inlineEditFile       string     // File being edited
showExitConfirmation bool
pendingClickRegion   string
pendingClickData     interface{}
exitConfirmSelection int

Update Priority (plugin.go)

func (p *Plugin) Update(msg tea.Msg) (plugin.Plugin, tea.Cmd) {
    // 1. Handle exit confirmation dialog FIRST
    if p.showExitConfirmation { /* j/k navigation, Enter confirm, Esc cancel */ }
    // 2. Handle inline edit mode
    if p.inlineEditMode && p.inlineEditor.IsActive() { /* Delegate to tty.Model */ }
    // 3. Normal plugin handling
}

App-Level Key Routing

The app intercepts global shortcuts (q, 1-5, `, ~, ?, !, @) before plugins. For inline edit to receive ALL keys, internal/app/update.go must recognize the context:

if m.activeContext == "workspace-interactive" || m.activeContext == "file-browser-inline-edit" {
    // Forward ALL keys to plugin
}

The plugin returns "file-browser-inline-edit" from FocusContext().

Common Pitfalls

1. Do NOT render full-screen - render within preview pane only, keeping file tree visible
2. Always include position-based click fallback - mouse regions may not cover every pixel
3. Always confirm on click-away when session is alive - prevents accidental data loss
4. Check IsActive() on every message - tty model can become inactive asynchronously; without this check, users get a blank screen after vim exits
5. Never query tmux synchronously in View() - use cached content from tty.Model.View()
6. Handle tab row clicks by Y position BEFORE region-based detection - prevents incorrect handling as preview pane clicks
7. Ensure app-level key routing recognizes "file-browser-inline-edit" context - otherwise typing q in vim triggers quit instead of inserting character

Feature Flag

Gated behind tmux_inline_edit. Enable in ~/.config/sidecar/config.json:

{ "features": { "tmux_inline_edit": true } }

Fallback: features.IsEnabled(features.TmuxInlineEdit.Name) returns false -> opens external editor.

Keyboard Shortcuts

Registered in:

• internal/plugins/filebrowser/plugin.go - Commands() method
• internal/plugins/filebrowser/handlers.go - Key handling
• internal/keymap/bindings.go - Key bindings for file-browser-tree and file-browser-preview contexts

References

• Interactive shell guide: docs/guides/interactive-shell-implementation.md
• TTY model: internal/tty/tty.go
• Feature flags: internal/features/features.go