feat(vim): zz/zt/zb scroll for notebook viewport (#9701)

[LioSergent]

Override the built-in no-op zz/zt/zb vim commands (which target CodeMirror's own scroll container, unused in marimo) to instead scroll the current in-cell cursor to the center/top/bottom of the notebook viewport.

📝 Summary

Closes #9701

📋 Pre-Review Checklist

• [ ] For large changes, or changes that affect the public API: this change was discussed or approved through an issue, on Discord, or the community discussions (Please provide a link if applicable). => not a large change.
• Any AI generated code has been reviewed line-by-line by the human PR author, who stands by it.
• [ ] Video or media evidence is provided for any visual changes (optional).

✅ Merge Checklist

• I have read the contributor guidelines.
• Documentation has been updated where applicable, including docstrings for API changes. => I don't think this is worthy of documentation change as no API change and this expected vim behavior.
• Tests have been added for the changes made. => No test, but other Vim actions are not tested either.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	May 29, 2026 5:26pm

[kirangadhave]

Can you please add a video which demos the new behavior?

[kirangadhave]

@cubic-dev-ai

[cubic-dev-ai]

@cubic-dev-ai

@kirangadhave I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 1 file

Architecture diagram

sequenceDiagram
    participant User as User
    participant CodeMirror as CodeMirror Editor
    participant Vim as Vim Keymap Plugin
    participant scrollCursorTo as scrollCursorTo()
    participant DOM as DOM (#App element)
    
    Note over User,DOM: Vim scroll commands for notebook viewport
    
    User->>CodeMirror: Press zz/zt/zb
    CodeMirror->>Vim: Keydown event (normal mode)
    Vim->>Vim: Lookup mapped command
    
    alt zz
        Vim->>scrollCursorTo: Execute action "scrollCursorToCenter"
        scrollCursorTo->>scrollCursorTo: position = "center"
    else zt
        Vim->>scrollCursorTo: Execute action "scrollCursorToTop"
        scrollCursorTo->>scrollCursorTo: position = "start"
    else zb
        Vim->>scrollCursorTo: Execute action "scrollCursorToBottom"
        scrollCursorTo->>scrollCursorTo: position = "end"
    end
    
    Note over scrollCursorTo,DOM: Get cursor position in viewport
    
    scrollCursorTo->>CodeMirror: cm.cm6 view reference
    CodeMirror-->>scrollCursorTo: view object
    scrollCursorTo->>CodeMirror: view.coordsAtPos(selection.main.head)
    CodeMirror-->>scrollCursorTo: cursor coordinates (top, bottom)
    
    Note over scrollCursorTo,DOM: Calculate scroll offset
    
    scrollCursorTo->>DOM: document.getElementById("App")
    DOM-->>scrollCursorTo: app element
    scrollCursorTo->>DOM: appEl.clientHeight (viewport height)
    
    alt position = center
        scrollCursorTo->>scrollCursorTo: delta = (coords.top + coords.bottom) / 2 - viewportHeight / 2
    else position = start
        scrollCursorTo->>scrollCursorTo: delta = coords.top
    else position = end
        scrollCursorTo->>scrollCursorTo: delta = coords.bottom - viewportHeight
    end
    
    Note over scrollCursorTo,DOM: Smooth scroll the notebook viewport
    
    scrollCursorTo->>DOM: appEl.scrollBy({ top: delta, behavior: "smooth" })
    DOM-->>scrollCursorTo: Scroll executed
    
    rect rgba(255, 255, 255, 0.1)
        Note over scrollCursorTo: Guard clauses (no-op paths)
        alt cm.cm6 view is null
            scrollCursorTo->>scrollCursorTo: return (no-op)
        else cursor coords are null
            scrollCursorTo->>scrollCursorTo: return (no-op)
        else #App element not found
            scrollCursorTo->>scrollCursorTo: return (no-op)
        end
    end

Loading

_{Re-trigger cubic}

[Copilot]

Pull request overview

Adds custom Vim scroll commands so zz, zt, and zb scroll the active CodeMirror cursor within marimo’s notebook viewport instead of CodeMirror’s unused internal scroll container.

Changes:

• Adds scrollCursorTo helper to compute cursor coordinates and scroll #App.
• Maps Vim normal-mode zz, zt, and zb to center/top/bottom viewport scrolling actions.

[LioSergent]

Can you please add a video which demos the new behavior?

[kirangadhave]

Thanks @LioSergent, looks great. Merging this now.