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.

fix(debugger): classify SetBreakpointsCommand and resync breakpoints on restart (#10120)

Myles Scolnickf0a0a4bac104
diff --git a/docs/guides/debugging.md b/docs/guides/debugging.md
index 7baed9a37d..c14a615760 100644
--- a/docs/guides/debugging.md
+++ b/docs/guides/debugging.md
@@ -44,6 +44,23 @@ def _():
</video>
Clicking on the cell link will also take you to the cell where the error occurred.
+### Live debugger
+
+!!! warning "Experimental Feature"
+ The live debugger is currently experimental and under active development. Features and APIs may change.
+
+Enable **Debugger** under experimental settings to turn on a live debugger for
+the notebook editor:
+
+- Click a line in the gutter to set a breakpoint on it. Click it again to
+ remove it. Breakpoints are session-only; they're not saved to the notebook
+ file.
+- While a cell is running, the line it's currently executing is highlighted.
+- When execution reaches a breakpoint, the cell drops into `pdb` just like
+ `breakpoint()` does.
+
+This setting requires a page refresh to take effect.
+
### Postmortem debugging
If your code raises an exception, you can use postmortem debugging to inspect
diff --git a/frontend/src/core/codemirror/cells/__tests__/debugger-decorations.test.ts b/frontend/src/core/codemirror/cells/__tests__/debugger-decorations.test.ts
new file mode 100644
index 0000000000..fb6646adbe
--- /dev/null
+++ b/frontend/src/core/codemirror/cells/__tests__/debugger-decorations.test.ts
@@ -0,0 +1,185 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { python } from "@codemirror/lang-python";
+import { EditorState } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cellId } from "@/__tests__/branded";
+import type { CellId } from "@/core/cells/ids";
+import { createMockObservable } from "@/core/state/__mocks__/mocks";
+import type { Observable } from "@/core/state/observable";
+import {
+ breakpointGutter,
+ debuggerLineHighlighter,
+} from "../debugger-decorations";
+
+vi.mock("../debugger-state", () => ({
+ toggleBreakpoint: vi.fn(),
+}));
+
+import { toggleBreakpoint } from "../debugger-state";
+
+const CODE = `def my_function():
+ x = 1
+ y = 2
+ return x + y
+
+result = my_function()`;
+
+function createLineHighlighterEditor(
+ lineObservable: Observable<number | null>,
+) {
+ const state = EditorState.create({
+ doc: CODE,
+ extensions: [python(), debuggerLineHighlighter(lineObservable)],
+ });
+ return new EditorView({ state, parent: document.body });
+}
+
+function createBreakpointGutterEditor(
+ cid: CellId,
+ breakpointsObservable: Observable<ReadonlySet<number>>,
+) {
+ const state = EditorState.create({
+ doc: CODE,
+ extensions: [python(), breakpointGutter(cid, breakpointsObservable)],
+ });
+ return new EditorView({ state, parent: document.body });
+}
+
+/** Flush the microtask queue and apply the resulting state changes to `view`. */
+async function flush(view: EditorView): Promise<void> {
+ await Promise.resolve();
+ view.dispatch({});
+}
+
+/**
+ * Count rendered breakpoint markers, excluding the always-present hidden
+ * spacer element (`initialSpacer`) that isn't an actual breakpoint.
+ */
+function visibleMarkerCount(view: EditorView): number {
+ const gutterElement = view.dom.querySelector(".cm-breakpoint-gutter");
+ if (!gutterElement) {
+ return 0;
+ }
+ return gutterElement.querySelectorAll(
+ '.cm-gutterElement:not([style*="visibility: hidden"]) .cm-breakpoint-marker',
+ ).length;
+}
+
+describe("debugger-decorations", () => {
+ let view: EditorView | null = null;
+
+ afterEach(() => {
+ if (view) {
+ view.destroy();
+ view = null;
+ }
+ document.body.innerHTML = "";
+ vi.clearAllMocks();
+ });
+
+ describe("debuggerLineHighlighter", () => {
+ it("renders no highlight when the observable starts null", () => {
+ const lineObservable = createMockObservable<number | null>(null);
+ view = createLineHighlighterEditor(lineObservable);
+
+ expect(view.dom.querySelector(".cm-debugger-current-line")).toBeNull();
+ });
+
+ it("highlights the line reported by the observable", () => {
+ const lineObservable = createMockObservable<number | null>(null);
+ view = createLineHighlighterEditor(lineObservable);
+
+ lineObservable.set(2);
+ view.dispatch({});
+
+ expect(
+ view.dom.querySelector(".cm-debugger-current-line"),
+ ).not.toBeNull();
+ });
+
+ it("clears the highlight when the line is set back to null", () => {
+ const lineObservable = createMockObservable<number | null>(2);
+ view = createLineHighlighterEditor(lineObservable);
+ view.dispatch({});
+ expect(
+ view.dom.querySelector(".cm-debugger-current-line"),
+ ).not.toBeNull();
+
+ lineObservable.set(null);
+ view.dispatch({});
+
+ expect(view.dom.querySelector(".cm-debugger-current-line")).toBeNull();
+ });
+
+ it("does not throw for an out-of-range line", () => {
+ const lineObservable = createMockObservable<number | null>(null);
+ view = createLineHighlighterEditor(lineObservable);
+
+ expect(() => {
+ lineObservable.set(9999);
+ view?.dispatch({});
+ }).not.toThrow();
+ expect(view.dom.querySelector(".cm-debugger-current-line")).toBeNull();
+ });
+ });
+
+ describe("breakpointGutter", () => {
+ it("renders no markers when there are no breakpoints", () => {
+ const cid = cellId("cell1");
+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(
+ new Set(),
+ );
+ view = createBreakpointGutterEditor(cid, breakpointsObservable);
+
+ expect(visibleMarkerCount(view)).toBe(0);
+ });
+
+ it("syncs pre-existing breakpoints on mount", async () => {
+ const cid = cellId("cell1");
+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(
+ new Set([2]),
+ );
+ view = createBreakpointGutterEditor(cid, breakpointsObservable);
+ await flush(view); // initial sync is deferred to a microtask
+
+ expect(visibleMarkerCount(view)).toBe(1);
+ });
+
+ it("adds a marker when the observable reports a new breakpoint", () => {
+ const cid = cellId("cell1");
+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(
+ new Set(),
+ );
+ view = createBreakpointGutterEditor(cid, breakpointsObservable);
+
+ breakpointsObservable.set(new Set([1, 3]));
+ view.dispatch({});
+
+ expect(visibleMarkerCount(view)).toBe(2);
+ });
+
+ it("toggles a breakpoint when an existing marker is clicked", async () => {
+ const cid = cellId("cell1");
+ // A single breakpoint on line 1 renders exactly one non-spacer
+ // gutter element, so the click lands unambiguously on that line.
+ const breakpointsObservable = createMockObservable<ReadonlySet<number>>(
+ new Set([1]),
+ );
+ view = createBreakpointGutterEditor(cid, breakpointsObservable);
+ await flush(view);
+
+ const gutterElement = view.dom.querySelector(".cm-breakpoint-gutter");
+ const lineElement = gutterElement?.querySelector(
+ '.cm-gutterElement:not([style*="visibility: hidden"])',
+ );
+ expect(lineElement).not.toBeNull();
+ lineElement?.dispatchEvent(
+ new MouseEvent("mousedown", { bubbles: true }),
+ );
+
+ expect(toggleBreakpoint).toHaveBeenCalledWith(cid, 1);
+ });
+ });
+});
diff --git a/frontend/src/core/codemirror/cells/__tests__/debugger-state.test.ts b/frontend/src/core/codemirror/cells/__tests__/debugger-state.test.ts
new file mode 100644
index 0000000000..415a0c62cd
--- /dev/null
+++ b/frontend/src/core/codemirror/cells/__tests__/debugger-state.test.ts
@@ -0,0 +1,139 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { cellId } from "@/__tests__/branded";
+import { store } from "@/core/state/jotai";
+import {
+ breakpointsAtom,
+ clearCellBreakpoints,
+ createCellBreakpointsAtom,
+ createDebuggerLineAtom,
+ debuggerCurrentLineAtom,
+ resyncBreakpoints,
+ toggleBreakpoint,
+} from "../debugger-state";
+
+const mockRequestClient = MockRequestClient.create();
+vi.mock("@/core/network/requests", () => ({
+ getRequestClient: () => mockRequestClient,
+}));
+
+const cell1 = cellId("cell1");
+const cell2 = cellId("cell2");
+
+describe("debugger-state", () => {
+ beforeEach(() => {
+ store.set(breakpointsAtom, new Map());
+ store.set(debuggerCurrentLineAtom, null);
+ vi.clearAllMocks();
+ });
+
+ describe("toggleBreakpoint", () => {
+ it("adds a breakpoint and syncs the full set to the kernel", () => {
+ toggleBreakpoint(cell1, 3);
+
+ expect(store.get(breakpointsAtom).get(cell1)).toEqual(new Set([3]));
+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenCalledWith({
+ breakpoints: { [cell1]: [3] },
+ });
+ });
+
+ it("removes a breakpoint on second toggle and drops the cell once empty", () => {
+ toggleBreakpoint(cell1, 3);
+ toggleBreakpoint(cell1, 3);
+
+ expect(store.get(breakpointsAtom).has(cell1)).toBe(false);
+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenLastCalledWith({
+ breakpoints: {},
+ });
+ });
+
+ it("sends lines sorted ascending for a cell with multiple breakpoints", () => {
+ toggleBreakpoint(cell1, 5);
+ toggleBreakpoint(cell1, 2);
+
+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenLastCalledWith({
+ breakpoints: { [cell1]: [2, 5] },
+ });
+ });
+
+ it("keeps breakpoints for other cells independent", () => {
+ toggleBreakpoint(cell1, 1);
+ toggleBreakpoint(cell2, 2);
+
+ expect(store.get(breakpointsAtom).get(cell1)).toEqual(new Set([1]));
+ expect(store.get(breakpointsAtom).get(cell2)).toEqual(new Set([2]));
+ });
+ });
+
+ describe("clearCellBreakpoints", () => {
+ it("removes all breakpoints for a cell and syncs", () => {
+ toggleBreakpoint(cell1, 1);
+ toggleBreakpoint(cell1, 2);
+ vi.clearAllMocks();
+
+ clearCellBreakpoints(cell1);
+
+ expect(store.get(breakpointsAtom).has(cell1)).toBe(false);
+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenCalledWith({
+ breakpoints: {},
+ });
+ });
+
+ it("is a no-op when the cell has no breakpoints", () => {
+ clearCellBreakpoints(cell1);
+
+ expect(mockRequestClient.sendSetBreakpoints).not.toHaveBeenCalled();
+ });
+ });
+
+ describe("resyncBreakpoints", () => {
+ it("re-sends the current breakpoint set", () => {
+ toggleBreakpoint(cell1, 4);
+ vi.clearAllMocks();
+
+ resyncBreakpoints();
+
+ expect(mockRequestClient.sendSetBreakpoints).toHaveBeenCalledWith({
+ breakpoints: { [cell1]: [4] },
+ });
+ });
+
+ it("does not send when there are no breakpoints", () => {
+ resyncBreakpoints();
+
+ expect(mockRequestClient.sendSetBreakpoints).not.toHaveBeenCalled();
+ });
+ });
+
+ describe("createCellBreakpointsAtom", () => {
+ it("returns the empty set for a cell with no breakpoints", () => {
+ const atom = createCellBreakpointsAtom(cell1);
+ expect(store.get(atom)).toEqual(new Set());
+ });
+
+ it("reflects breakpoints for its own cell only", () => {
+ toggleBreakpoint(cell1, 7);
+ const cell1Atom = createCellBreakpointsAtom(cell1);
+ const cell2Atom = createCellBreakpointsAtom(cell2);
+
+ expect(store.get(cell1Atom)).toEqual(new Set([7]));
+ expect(store.get(cell2Atom)).toEqual(new Set());
+ });
+ });
+
+ describe("createDebuggerLineAtom", () => {
+ it("returns null when no line is set", () => {
+ const atom = createDebuggerLineAtom(cell1);
+ expect(store.get(atom)).toBeNull();
+ });
+
+ it("returns the line only for the matching cell", () => {
+ store.set(debuggerCurrentLineAtom, { cellId: cell1, line: 10 });
+
+ expect(store.get(createDebuggerLineAtom(cell1))).toBe(10);
+ expect(store.get(createDebuggerLineAtom(cell2))).toBeNull();
+ });
+ });
+});
diff --git a/frontend/src/core/codemirror/cells/debugger-state.ts b/frontend/src/core/codemirror/cells/debugger-state.ts
index 9609c3b989..af18890ccd 100644
--- a/frontend/src/core/codemirror/cells/debugger-state.ts
+++ b/frontend/src/core/codemirror/cells/debugger-state.ts
@@ -72,6 +72,14 @@ export function clearCellBreakpoints(cellId: CellId): void {
sendBreakpoints(next);
}
+/** Re-push the current breakpoints to a freshly started kernel, whose `MarimoPdb` starts empty. */
+export function resyncBreakpoints(): void {
+ const current = store.get(breakpointsAtom);
+ if (current.size > 0) {
+ sendBreakpoints(current);
+ }
+}
+
/** Toggle a breakpoint at `(cellId, line)` and sync the full set to the kernel. */
export function toggleBreakpoint(cellId: CellId, line: number): void {
const prev = store.get(breakpointsAtom);
diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
index ab62272406..f023013ee1 100644
--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx
+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx
@@ -32,7 +32,10 @@ import { cacheInfoAtom } from "../cache/requests";
import { SCRATCH_CELL_ID } from "../cells/ids";
import { useRunsActions } from "../cells/runs";
import { focusAndScrollCellOutputIntoView } from "../cells/scrollCellIntoView";
-import { debuggerCurrentLineAtom } from "../codemirror/cells/debugger-state";
+import {
+ debuggerCurrentLineAtom,
+ resyncBreakpoints,
+} from "../codemirror/cells/debugger-state";
import type { CellData } from "../cells/types";
import { capabilitiesAtom } from "../config/capabilities";
import { useSetAppConfig } from "../config/config";
@@ -223,6 +226,11 @@ export function useMarimoKernelConnection(opts: {
existingCells,
});
setKioskMode(msg.data.kiosk);
+ // A freshly started kernel has no breakpoints of its own; re-push
+ // the client's set so they still apply, and clear the stale
+ // highlighted line from the previous kernel instance.
+ setDebuggerCurrentLine(null);
+ resyncBreakpoints();
return;
}
diff --git a/marimo/_session/capabilities.py b/marimo/_session/capabilities.py
index 9d77f9c574..f9e08f2398 100644
--- a/marimo/_session/capabilities.py
+++ b/marimo/_session/capabilities.py
@@ -67,6 +67,7 @@ _EDIT_COMMANDS: frozenset[type] = frozenset(
commands.ExecuteScratchpadCommand,
commands.ExecuteStaleCellsCommand,
commands.DebugCellCommand,
+ commands.SetBreakpointsCommand,
commands.DeleteCellCommand,
commands.SyncGraphCommand,
commands.UpdateCellConfigCommand,
diff --git a/tests/_runtime/test_request_router.py b/tests/_runtime/test_request_router.py
index 359e2f7f26..c77c896194 100644
--- a/tests/_runtime/test_request_router.py
+++ b/tests/_runtime/test_request_router.py
@@ -43,7 +43,7 @@ ALL_CALLBACKS: list[type] = [
# Commands that are part of the CommandMessage dispatch surface but are
# intentionally not handled by the kernel's RequestRouter. These are delivered
# on the off-main-loop completion queue and processed by
-# start_completion_worker: CodeCompletionCommand (autocomplete) and
+# start_out_of_band_worker: CodeCompletionCommand (autocomplete) and
# SetBreakpointsCommand (live-debugger breakpoints, so they apply mid-run).
NOT_ROUTED: set[type] = {CodeCompletionCommand, SetBreakpointsCommand}