A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
/* Copyright 2026 Marimo. All rights reserved. */
import type { Extension } from "@codemirror/state";
import { EditorView, keymap, ViewPlugin } from "@codemirror/view";
import {
type CodeMirror,
type CodeMirrorV,
getCM,
Vim,
} from "@replit/codemirror-vim";
import { resolvedMarimoConfigAtom } from "@/core/config/config";
import { getRequestClient } from "@/core/network/requests";
import { store } from "@/core/state/jotai";
import { onIdle } from "@/utils/idle";
import { invariant } from "@/utils/invariant";
import { Logger } from "@/utils/Logger";
import { once } from "@/utils/once";
import { cellActionsState, cellIdState } from "../cells/state";
import { goToDefinitionAtCursorPosition } from "../go-to-definition/utils";
import {
isAtEndOfEditor,
isAtStartOfEditor,
isInVimNormalMode,
} from "../utils";
import { VimCursorVisibilityPlugin } from "../vim/cursor-visibility";
import { parseVimrc, type VimCommand } from "./vimrc";
export function vimKeymapExtension(): Extension[] {
addCustomVimCommandsOnce();
loadVimrcOnce();
return [
keymap.of([
{
key: "j",
run: (ev) => {
if (isAtEndOfEditor(ev, true) && isInVimNormalMode(ev)) {
const actions = ev.state.facet(cellActionsState);
const cellId = ev.state.facet(cellIdState);
actions.moveToNextCell({ cellId, before: false, create: false });
return true;
}
return false;
},
},
]),
keymap.of([
{
key: "k",
run: (ev) => {
if (isAtStartOfEditor(ev) && isInVimNormalMode(ev)) {
const actions = ev.state.facet(cellActionsState);
const cellId = ev.state.facet(cellIdState);
actions.moveToNextCell({ cellId, before: true, create: false });
return true;
}
return false;
},
},
]),
keymap.of([
{
// Ctrl-[ by default is to dedent
// But for Vim (on Linux and Windows), it should exit insert mode when in Insert mode
linux: "Ctrl-[",
win: "Ctrl-[",
run: (ev) => {
const cm = getCM(ev);
if (!cm) {
Logger.warn(
"Expected CodeMirror instance to have CodeMirror instance state",
);
return false;
}
if (!hasVimState(cm)) {
Logger.warn("Expected CodeMirror instance to have Vim state");
return false;
}
const vim = cm.state.vim;
if (vim.insertMode) {
Vim.exitInsertMode(cm, true);
return true;
}
return false;
},
},
]),
ViewPlugin.define((view) => {
// Wait for the next animation frame so the CodeMirror instance is ready
requestAnimationFrame(() => {
CodeMirrorVimSync.INSTANCES.addInstance(view);
});
return {
destroy() {
CodeMirrorVimSync.INSTANCES.removeInstance(view);
},
};
}),
ViewPlugin.define((view) => new VimCursorVisibilityPlugin({ view })),
// FIXME: The vim extension swallows `Ctrl+Escape` events, preventing them
// from bubbling to parent elements where react-aria's useKeyboard is listening.
// Re-dispatch the event to ensure it propagates up for vim mode transitions.
EditorView.domEventHandlers({
keydown(event, view) {
if (event.ctrlKey && event.key === "Escape") {
view.dom.dispatchEvent(new KeyboardEvent(event.type, event));
return true;
}
return false;
},
}),
];
}
function scrollCursorTo(cm: CodeMirror, position: "center" | "start" | "end") {
const view = cm.cm6;
if (!view) {
return;
}
const coords = view.coordsAtPos(view.state.selection.main.head);
if (!coords) {
return;
}
const appEl = document.getElementById("App");
if (!appEl) {
return;
}
const viewportHeight = appEl.clientHeight;
let delta: number;
switch (position) {
case "center":
delta = (coords.top + coords.bottom) / 2 - viewportHeight / 2;
break;
case "start":
delta = coords.top;
break;
case "end":
delta = coords.bottom - viewportHeight;
break;
}
appEl.scrollBy({ top: delta, behavior: "smooth" });
}
const addCustomVimCommandsOnce = once(() => {
// Go to definition
Vim.defineAction("goToDefinition", (cm: CodeMirror) => {
const view = cm.cm6;
return goToDefinitionAtCursorPosition(view);
});
Vim.mapCommand("gd", "action", "goToDefinition", {}, { context: "normal" });
// Scroll cursor to center/top/bottom of viewport (mirrors zz/zt/zb in classic vim)
Vim.defineAction("scrollCursorToCenter", (cm: CodeMirror) =>
scrollCursorTo(cm, "center"),
);
Vim.mapCommand(
"zz",
"action",
"scrollCursorToCenter",
{},
{ context: "normal" },
);
Vim.defineAction("scrollCursorToTop", (cm: CodeMirror) =>
scrollCursorTo(cm, "start"),
);
Vim.mapCommand(
"zt",
"action",
"scrollCursorToTop",
{},
{ context: "normal" },
);
Vim.defineAction("scrollCursorToBottom", (cm: CodeMirror) =>
scrollCursorTo(cm, "end"),
);
Vim.mapCommand(
"zb",
"action",
"scrollCursorToBottom",
{},
{ context: "normal" },
);
// Save command
Vim.defineEx("write", "w", (cm: CodeMirror) => {
const view = cm.cm6;
if (view) {
const actions = view.state.facet(cellActionsState);
actions.saveNotebook();
}
});
});
const loadVimrcOnce = once(async () => {
const config = store.get(resolvedMarimoConfigAtom);
const vimrc = config.keymap?.vimrc;
if (!vimrc) {
return;
}
try {
Logger.log(`Loading vimrc from ${vimrc}`);
const response = await getRequestClient().sendFileDetails({ path: vimrc });
const content = response.contents;
if (!content) {
Logger.error(`Failed to load vimrc from ${vimrc}`);
return;
}
const vimCommands = parseVimrc(content, Logger.warn);
applyVimCommands(vimCommands);
} catch (error) {
Logger.error("Failed to load vimrc:", error);
}
});
function applyVimCommands(vimCommands: VimCommand[]) {
// map, noremap and unmap can be used without ctx.
// It is an important behavior that we want to use.
function map(command: VimCommand) {
if (!command.args) {
Logger.warn(
`Could not execute vimrc command "${command.name}: expected arguments"`,
);
return;
}
if (!command.args.lhs || !command.args.rhs) {
Logger.warn(
`Could not execute vimrc command "${command.name}: expected arguments"`,
);
return;
}
if (command.mode) {
Vim.map(command.args.lhs, command.args.rhs, command.mode);
} else {
//@ts-expect-error We can use this without providing context (mode)
Vim.map(command.args.lhs, command.args.rhs);
}
}
function noremap(command: VimCommand) {
if (!command.args) {
Logger.warn(
`Could not execute vimrc command "${command.name}: expected arguments"`,
);
return;
}
if (!command.args.lhs || !command.args.rhs) {
Logger.warn(
`Could not execute vimrc command "${command.name}: expected arguments"`,
);
return;
}
if (command.mode) {
Vim.noremap(command.args.lhs, command.args.rhs, command.mode);
} else {
//@ts-expect-error We can use this without providing context (mode)
Vim.noremap(command.args.lhs, command.args.rhs);
}
}
function unmap(command: VimCommand) {
if (!command.args) {
Logger.warn(
`Could not execute vimrc command "${command.name}: expected arguments"`,
);
return;
}
if (!command.args.lhs) {
Logger.warn(
`Could not execute vimrc command "${command.name}: expected arguments"`,
);
return;
}
if (command.mode) {
Vim.unmap(command.args.lhs, command.mode);
} else {
//@ts-expect-error We can use this without providing context (mode)
Vim.unmap(command.args.lhs);
}
}
function mapclear(command: VimCommand) {
if (command.mode) {
Vim.mapclear(command.mode);
} else {
Vim.mapclear();
}
}
for (const command of vimCommands) {
if ("map|nmap|vmap|imap".split("|").includes(command.name)) {
map(command);
} else if (
"noremap|nnoremap|vnoremap|inoremap".split("|").includes(command.name)
) {
noremap(command);
} else if ("unmap|nunmap|vunmap|iunmap".split("|").includes(command.name)) {
unmap(command);
} else if (
"mapclear|nmapclear|vmapclear|imapclear".split("|").includes(command.name)
) {
mapclear(command);
} else {
Logger.warn(
`Could not execute vimrc command "${command.name}: unknown command"`,
);
}
}
}
interface ExtendedVim {
getVimGlobalState_: () => {
macroModeState?: {
isRecording: boolean;
isPlaying: boolean;
};
};
}
function isExtendedVim(vim: typeof Vim): vim is typeof Vim & ExtendedVim {
return (
"getVimGlobalState_" in vim && typeof vim.getVimGlobalState_ === "function"
);
}
function isMacroActive() {
if (!isExtendedVim(Vim)) {
return false;
}
const macroModeState = Vim.getVimGlobalState_()?.macroModeState;
if (!macroModeState) {
return false;
}
return Boolean(macroModeState.isRecording || macroModeState.isPlaying);
}
class CodeMirrorVimSync {
private instances = new Set<EditorView>();
private isBroadcasting = false;
public static INSTANCES: CodeMirrorVimSync = new CodeMirrorVimSync();
private constructor() {
// noop
}
public addInstance(instance: EditorView) {
this.instances.add(instance);
const cm = getCM(instance);
if (!cm) {
Logger.warn(
"Expected CodeMirror instance to have CodeMirror instance state",
);
return;
}
// Create an event listener for Vim mode changes
// When it changes, we broadcast it to all other CodeMirror instances
cm.on("vim-mode-change", (e: { mode: string; subMode?: string }) => {
if (this.isBroadcasting) {
return;
}
invariant("mode" in e, 'Expected event to have a "mode" property');
const skipBroadcast = isMacroActive();
this.isBroadcasting = true;
// We use onIdle to keep the focused editor snappy
onIdle(() => {
if (!skipBroadcast) {
this.broadcastModeChange(instance, e.mode);
}
this.isBroadcasting = false;
});
});
}
public removeInstance(instance: EditorView) {
this.instances.delete(instance);
}
public broadcastModeChange(originInstance: EditorView, mode: string) {
invariant(
"exitInsertMode" in Vim,
"Vim does not have an exitInsertMode method",
);
invariant(
"exitVisualMode" in Vim,
"Vim does not have an exitVisualMode method",
);
for (const instance of this.instances) {
if (instance !== originInstance) {
const cm = getCM(instance);
if (!cm) {
Logger.warn(
"Expected CodeMirror instance to have CodeMirror instance state",
);
continue;
}
// HACK: setSelections will steal focus from the current editor
// so we remove it and set it back afterwards
const prevSetSelections = cm.setSelections.bind(cm);
cm.setSelections = () => {
// noop
return [];
};
if (!hasVimState(cm)) {
Logger.warn("Expected CodeMirror instance to have Vim state");
continue;
}
const vim = cm.state.vim;
switch (mode) {
case "normal":
// Only exit insert mode if we're in it
if (vim.insertMode) {
Vim.exitInsertMode(cm, true);
}
// Only exit visual mode if we're in it
if (vim.visualMode) {
Vim.exitVisualMode(cm, true);
}
break;
case "insert":
// only enter insert mode if we're not already in it
if (!vim.insertMode) {
Vim.handleKey(cm, "i", "mapping");
}
break;
case "visual":
// We don't switch to visual mode across instances
break;
}
// HACK: restore selection
cm.setSelections = prevSetSelections;
}
}
}
}
function hasVimState(cm: CodeMirror): cm is CodeMirrorV {
return cm.state.vim !== undefined;
}