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.

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

/**
 * A CodeMirror binding between an editor and one cell's code.
 *
 * The editor and the document model each hold the code, and the binding keeps
 * them equal in both directions.
 *
 * - Push. An update that could change the code writes it to the model before
 *   the update returns, so the model keeps pace with typing.
 * - Pull. A model change reaches the editor in a microtask, because a view
 *   cannot dispatch while it is constructing or updating. The binding keeps
 *   the code both sides last agreed on, so the model's echo of a push is
 *   skipped while a different value, even one written during that push, is
 *   pulled. A real change is marked remote, stays out of undo history, and
 *   waits for IME composition to end.
 *
 * The editor shows code through marimo's language adapters, so a markdown
 * cell edits the text inside `mo.md`. Both directions compare the cell's
 * Python code rather than the editor text, so an adapter that normalizes what
 * it reads back leaves typing alone.
 *
 * A pulled change replaces only what differs, using `diff` from
 * `@codemirror/merge`. Separate edits stay separate, so the selection, folds,
 * and diagnostics between them keep their place. The diff uses a scan limit of
 * 500, as the merge view does. Past it, the search trades precision for speed,
 * so a rewrite of a large cell costs microseconds and maps the selection
 * coarsely instead of blocking the editor.
 */

import {
  type EditorState,
  type Extension,
  Transaction,
} from "@codemirror/state";
import { type EditorView, ViewPlugin, type ViewUpdate } from "@codemirror/view";
import type { CellId } from "@marimo-team/client/protocol";
import type { Atom, createStore } from "jotai/vanilla";
import {
  editorShowsCellCode,
  getCellCode,
  prepareCellCodeUpdate,
} from "../../codemirror/language/cell-code";
import { languageAdapterState } from "../../codemirror/language/extension";
import { languageMetadataField } from "../../codemirror/language/metadata";
import type { DocumentModel } from "./model";
import { selectCellField } from "./select";

interface Binding {
  readonly store: ReturnType<typeof createStore>;
  readonly model: DocumentModel;
  readonly cellId: CellId;
  /** Undefined while the cell is absent, null while its source is withheld. */
  readonly code: Atom<string | null | undefined>;
}

/**
 * Bind an editor to one cell's code.
 *
 * Editors without marimo's language configuration bind their text as is.
 */
export function cellCodeBinding({
  store,
  model,
  cellId,
}: {
  store: ReturnType<typeof createStore>;
  model: DocumentModel;
  cellId: CellId;
}): Extension {
  const binding: Binding = {
    store,
    model,
    cellId,
    code: selectCellField(model.documentAtom, cellId, "code"),
  };
  return ViewPlugin.define((view) => new CellCodeSync(view, binding), {
    eventObservers: {
      compositionend() {
        this.compositionEnded();
      },
    },
  });
}

class CellCodeSync {
  // Only the initial load infers a mode; subsequent edits preserve it.
  #initialized = false;
  #scheduled = false;
  /** A pull arrived during IME composition and runs once it ends. */
  #deferred = false;
  /**
   * The code the editor and the model last agreed on.
   *
   * A change the model cannot take clears it, so once the cell is available
   * again its code is pulled even if it matches what was agreed before.
   */
  #synced: string | undefined;
  #destroyed = false;
  readonly #view: EditorView;
  readonly #binding: Binding;
  readonly #unsubscribe: () => void;

  public constructor(view: EditorView, binding: Binding) {
    this.#view = view;
    this.#binding = binding;
    // A change to the agreed code is the echo of a push and needs no pull.
    this.#unsubscribe = binding.store.sub(binding.code, () => {
      if (binding.store.get(binding.code) !== this.#synced) {
        this.#schedule();
      }
    });
    this.#schedule();
  }

  public update(update: ViewUpdate) {
    if (
      changesCode(update) &&
      !update.transactions.every((tr) => tr.annotation(Transaction.remote))
    ) {
      this.#push(update.state);
    }
    if (this.#deferred && !update.view.composing) {
      this.#schedule();
    }
  }

  /**
   * Run a pull that waited for the composition.
   *
   * A composition that ends without changing the text need not produce an
   * update. CodeMirror finishes handling the end in a microtask, so the pull
   * waits for the next task.
   */
  public compositionEnded() {
    if (this.#deferred) {
      setTimeout(() => this.#schedule(), 0);
    }
  }

  public destroy() {
    this.#destroyed = true;
    this.#unsubscribe();
  }

  /** Write the editor's code to the model unless the editor already shows it. */
  #push(state: EditorState) {
    const { store, model, cellId, code } = this.#binding;
    const current = store.get(code);
    if (typeof current !== "string") {
      this.#synced = undefined;
      return;
    }
    this.#initialized = true;
    if (editorShowsCellCode(state, current)) {
      this.#synced = current;
      return;
    }
    const next = getCellCode(state);
    this.#synced = next;
    store.set(model.editAtom, (tx) => tx.setCode(cellId, next));
  }

  /** Show the model's code unless the editor already shows it. */
  #pull() {
    this.#scheduled = false;
    const next = this.#binding.store.get(this.#binding.code);
    if (this.#destroyed || typeof next !== "string") {
      return;
    }
    if (this.#view.composing) {
      this.#deferred = true;
      return;
    }
    this.#deferred = false;
    if (next !== this.#synced) {
      const update = prepareCellCodeUpdate(this.#view.state, next, {
        initialize: !this.#initialized,
      });
      if (update) {
        this.#view.dispatch(update, {
          annotations: [
            Transaction.remote.of(true),
            Transaction.addToHistory.of(false),
          ],
        });
      }
    }
    this.#synced = next;
    this.#initialized = true;
  }

  /** Pull once after the current update, however many changes arrive. */
  #schedule() {
    if (!this.#scheduled) {
      this.#scheduled = true;
      queueMicrotask(() => this.#pull());
    }
  }
}

/**
 * Whether an update could change the code an editor represents.
 *
 * Language metadata, such as an SQL cell's output name, changes the code
 * without changing the text.
 */
function changesCode(update: ViewUpdate): boolean {
  return (
    update.docChanged ||
    update.state.field(languageAdapterState, false) !==
      update.startState.field(languageAdapterState, false) ||
    update.state.field(languageMetadataField, false) !==
      update.startState.field(languageMetadataField, false)
  );
}