Skip to content

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.

14.0 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */

import { closeCompletion, completionStatus } from "@codemirror/autocomplete";
import { type Extension, Prec, Transaction } from "@codemirror/state";
import {
  EditorView,
  type KeyBinding,
  keymap,
  type ViewUpdate,
} from "@codemirror/view";
import { createTracebackInfoAtom } from "@/core/cells/cells";
import { type CellId, HTMLCellId, SCRATCH_CELL_ID } from "@/core/cells/ids";
import {
  clearPendingCutAtom,
  pendingCutCellIdsAtom,
} from "@/core/cells/pending-cut-service";
import type { KeymapConfig } from "@/core/config/config-schema";
import type { HotkeyProvider } from "@/core/hotkeys/hotkeys";
import { getFeatureFlag } from "@/core/config/feature-flag";
import { duplicateWithCtrlModifier } from "@/core/hotkeys/shortcuts";
import { store } from "@/core/state/jotai";
import { createObservable } from "@/core/state/observable";
import { formatKeymapExtension } from "../extensions";
import { formattingChangeEffect } from "../format";
import { goToDefinitionAtCursorPosition } from "../go-to-definition/utils";
import { getEditorCodeAsPython } from "../language/utils";
import { isAtEndOfEditor, isAtStartOfEditor } from "../utils";
import {
  breakpointGutter,
  debuggerLineHighlighter,
} from "./debugger-decorations";
import {
  createActiveLineInfoAtom,
  createCellBreakpointsAtom,
  createDebuggerLineAtom,
} from "./debugger-state";
import { activeLineTimer } from "./line-timing-decorations";
import {
  type CodemirrorCellActions,
  cellActionsState,
  cellIdState,
} from "./state";
import { errorLineHighlighter } from "./traceback-decorations";

/**
 * Extensions for cell actions
 */
function cellKeymaps({
  cellId,
  hotkeys,
}: {
  cellId: CellId;
  hotkeys: HotkeyProvider;
}): Extension[] {
  const keybindings: KeyBinding[] = [];

  // Run-related keybindings get Ctrl equivalents on macOS for Jupyter/Colab users
  keybindings.push(
    ...duplicateWithCtrlModifier({
      key: hotkeys.getHotkey("cell.run").key,
      preventDefault: true,
      stopPropagation: true,
      run: (ev) => {
        const actions = ev.state.facet(cellActionsState);
        actions.onRun();
        return true;
      },
    }),
    {
      // Shift-Enter has no Cmd, so no Ctrl equivalent needed
      key: hotkeys.getHotkey("cell.runAndNewBelow").key,
      preventDefault: true,
      stopPropagation: true,
      run: (ev) => {
        const actions = ev.state.facet(cellActionsState);
        actions.onRun();
        if (cellId === SCRATCH_CELL_ID) {
          return true;
        }
        ev.contentDOM.blur();
        actions.moveToNextCell({ cellId, before: false });
        return true;
      },
    },
    ...duplicateWithCtrlModifier({
      key: hotkeys.getHotkey("cell.runAndNewAbove").key,
      preventDefault: true,
      stopPropagation: true,
      run: (ev) => {
        const actions = ev.state.facet(cellActionsState);
        actions.onRun();
        if (cellId === SCRATCH_CELL_ID) {
          return true;
        }
        ev.contentDOM.blur();
        actions.moveToNextCell({ cellId, before: true });
        return true;
      },
    }),
    {
      key: hotkeys.getHotkey("cell.aiCompletion").key,
      preventDefault: true,
      stopPropagation: true,
      run: (ev) => {
        const actions = ev.state.facet(cellActionsState);
        const closed = actions.aiCellCompletion();
        if (closed) {
          ev.contentDOM.focus();
        }
        return true;
      },
    },
  );

  if (cellId !== SCRATCH_CELL_ID) {
    keybindings.push(
      {
        key: hotkeys.getHotkey("cell.goToDefinition").key,
        run: (ev) => {
          return goToDefinitionAtCursorPosition(ev);
        },
      },
      {
        key: hotkeys.getHotkey("cell.delete").key,
        preventDefault: true,
        stopPropagation: true,
        run: (cm) => {
          // When editing (not command mode), only allow deletion of empty cells
          if (cm.state.doc.length === 0) {
            const actions = cm.state.facet(cellActionsState);
            actions.deleteCell();
          }
          // shortcuts.delete (shift-backspace) overlaps with
          // defaultKeymap's deleteCharBackward (backspace); we don't want
          // shift-backspace to trigger character deletion, because otherwise
          // users might accidentally delete their whole notebook if they
          // absent-mindedly held these keys. That's why we always return true.
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.moveUp").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.moveCell({ cellId, before: true });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.moveDown").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.moveCell({ cellId, before: false });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.moveLeft").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.moveCell({ cellId, before: true, direction: "left" });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.moveRight").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.moveCell({ cellId, before: false, direction: "right" });
          return true;
        },
      },
      {
        key: "ArrowUp",
        run: (ev) => {
          // Skip if we are in the middle of an autocompletion
          const hasAutocomplete = completionStatus(ev.state);
          if (hasAutocomplete) {
            return false;
          }

          if (isAtStartOfEditor(ev)) {
            const actions = ev.state.facet(cellActionsState);
            actions.moveToNextCell({ cellId, before: true, create: false });
            return true;
          }
          return false;
        },
      },
      {
        key: "ArrowDown",
        run: (ev) => {
          // Skip if we are in the middle of an autocompletion
          const hasAutocomplete = completionStatus(ev.state);
          if (hasAutocomplete) {
            return false;
          }

          if (isAtEndOfEditor(ev)) {
            const actions = ev.state.facet(cellActionsState);
            actions.moveToNextCell({ cellId, before: false, create: false });
            return true;
          }
          return false;
        },
      },
      {
        key: hotkeys.getHotkey("cell.focusDown").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.moveToNextCell({ cellId, before: false, create: false });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.focusUp").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.moveToNextCell({ cellId, before: true, create: false });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.sendToBottom").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.sendToBottom({ cellId });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.sendToTop").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.sendToTop({ cellId });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.createAbove").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          ev.contentDOM.blur();
          const actions = ev.state.facet(cellActionsState);
          actions.createCell({ before: cellId });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.createBelow").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          ev.contentDOM.blur();
          const actions = ev.state.facet(cellActionsState);
          actions.createCell({ after: cellId });
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.hideCode").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          const isHidden = actions.toggleHideCode();
          closeCompletion(ev);
          // If we are newly hidden, blur the editor
          if (isHidden) {
            ev.contentDOM.blur();
            // Focus on the parent element
            // https://github.com/marimo-team/marimo/issues/2941
            document.getElementById(HTMLCellId.create(cellId))?.focus();
          } else {
            ev.contentDOM.focus();
          }
          return true;
        },
      },
      {
        key: hotkeys.getHotkey("cell.splitCell").key,
        preventDefault: true,
        stopPropagation: true,
        run: (ev) => {
          const actions = ev.state.facet(cellActionsState);
          actions.splitCell({ cellId });
          if (!actions.moveToNextCell) {
            return true;
          }
          requestAnimationFrame(() => {
            ev.contentDOM.blur();
            actions.moveToNextCell({ cellId, before: false }); // focus new cell
          });
          return true;
        },
      },
    );
  }

  // Highest priority so that we can override the default keymap
  return [Prec.high(keymap.of(keybindings))];
}

/**
 * Extensions for cell code editing
 */
function cellCodeEditing(hotkeys: HotkeyProvider): Extension[] {
  const onChangePlugin = EditorView.updateListener.of((update) => {
    if (update.docChanged) {
      // Check if the doc update was a formatting change
      // e.g. changing from python to markdown
      const isFormattingChange = update.transactions.some((tr) =>
        tr.effects.some((effect) => effect.is(formattingChangeEffect)),
      );
      const nextCode = getEditorCodeAsPython(update.view);
      const cellActions = update.view.state.facet(cellActionsState);
      const cellId = update.view.state.facet(cellIdState);
      cellActions.updateCellCode({
        cellId,
        code: nextCode,
        formattingChange: isFormattingChange,
      });

      // Clear pending cut state if this cell was marked for cut
      const pendingCutCellIds = store.get(pendingCutCellIdsAtom);
      if (pendingCutCellIds.has(cellId)) {
        store.set(clearPendingCutAtom);
      }
    }
  });

  return [onChangePlugin, formatKeymapExtension(hotkeys)];
}

const MARKDOWN_AUTORUN_USER_EVENTS = ["input", "delete", "undo", "redo"];

function shouldAutorunMarkdownUpdate({
  docChanged,
  transactions,
  predicate = () => true,
  hasFocus = false,
}: Pick<ViewUpdate, "docChanged" | "transactions"> & {
  predicate?: () => boolean;
  hasFocus?: boolean;
}): boolean {
  // If the doc didn't change, ignore.
  if (!docChanged) {
    return false;
  }

  // The caller decides when markdown autorun is allowed, e.g. not for
  // f-strings where rerunning on every keystroke is usually incorrect.
  if (!predicate()) {
    return false;
  }

  // This happens on mount when we start in markdown mode.
  // Ignore formatting changes so language switches don't trigger autorun.
  const isFormattingChange = transactions.some((tr) =>
    tr.effects.some((effect) => effect.is(formattingChangeEffect)),
  );
  if (isFormattingChange) {
    return false;
  }

  return transactions.some((tr) => {
    // Ignore remote changes to avoid duplicate runs. The client that made the
    // edit runs it.
    if (tr.annotation(Transaction.remote)) {
      return false;
    }

    // Prefer explicit local edit transactions, but keep a focused fallback for
    // local rewrite paths like split-cell, which can update markdown content
    // without annotating a user event.
    return (
      MARKDOWN_AUTORUN_USER_EVENTS.some((kind) => tr.isUserEvent(kind)) ||
      hasFocus
    );
  });
}

/**
 * Extension for auto-running markdown cells
 */
export function markdownAutoRunExtension({
  predicate,
}: {
  predicate: () => boolean;
}): Extension {
  return EditorView.updateListener.of((update) => {
    if (
      !shouldAutorunMarkdownUpdate({
        docChanged: update.docChanged,
        transactions: update.transactions,
        predicate,
        hasFocus: update.view.hasFocus,
      })
    ) {
      return;
    }
    const actions = update.view.state.facet(cellActionsState);
    actions.onRun();
  });
}

export function cellBundle({
  cellId,
  hotkeys,
  cellActions,
}: {
  cellId: CellId;
  hotkeys: HotkeyProvider;
  cellActions: CodemirrorCellActions;
  keymapConfig: KeymapConfig;
}): Extension[] {
  const debuggerOn = getFeatureFlag("debugger");
  const lineTimingOn = getFeatureFlag("line_timing");
  return [
    cellActionsState.of(cellActions),
    cellIdState.of(cellId),
    cellKeymaps({ cellId, hotkeys }),
    cellCodeEditing(hotkeys),
    errorLineHighlighter(
      createObservable(createTracebackInfoAtom(cellId), store),
    ),
    // Experimental live debugger and line-timing highlight. Gated so there is
    // no gutter/overhead when disabled. Both track the same active line; when
    // both flags are on, the green timing highlight replaces the amber one.
    debuggerOn
      ? breakpointGutter(
          cellId,
          createObservable(createCellBreakpointsAtom(cellId), store),
        )
      : [],
    lineTimingOn
      ? activeLineTimer(
          createObservable(createActiveLineInfoAtom(cellId), store),
        )
      : debuggerOn
        ? debuggerLineHighlighter(
            createObservable(createDebuggerLineAtom(cellId), store),
          )
        : [],
  ];
}

export const exportedForTesting = {
  shouldAutorunMarkdownUpdate,
};