@marimo-team/islands 0.23.14-dev5 → 0.23.14-dev51

package/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();
+    });
+  });
+});

package/src/core/codemirror/cells/debugger-decorations.ts

@@ -0,0 +1,188 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import {
+  type EditorState,
+  type Extension,
+  RangeSet,
+  RangeSetBuilder,
+  StateEffect,
+  StateField,
+} from "@codemirror/state";
+import {
+  Decoration,
+  type DecorationSet,
+  EditorView,
+  gutter,
+  GutterMarker,
+  type PluginValue,
+  ViewPlugin,
+  type ViewUpdate,
+} from "@codemirror/view";
+import type { CellId } from "@/core/cells/ids";
+import type { Observable } from "@/core/state/observable";
+import { Logger } from "@/utils/Logger";
+import { toggleBreakpoint } from "./debugger-state";
+
+// --- Current-line highlight -------------------------------------------------
+
+function createLineDecoration(
+  state: EditorState,
+  line: number | null,
+): DecorationSet {
+  if (line == null || line < 1 || line > state.doc.lines) {
+    return Decoration.none;
+  }
+  const builder = new RangeSetBuilder<Decoration>();
+  try {
+    const doc = state.doc.line(line);
+    builder.add(
+      doc.from,
+      doc.from,
+      Decoration.line({ class: "cm-debugger-current-line" }),
+    );
+  } catch (error) {
+    Logger.debug("Invalid debugger line", { error });
+  }
+  return builder.finish();
+}
+
+class CurrentLineHighlighter implements PluginValue {
+  private unsubscribe: () => void;
+  decorations: DecorationSet;
+
+  constructor(view: EditorView, lineObservable: Observable<number | null>) {
+    this.decorations = createLineDecoration(view.state, lineObservable.get());
+    this.unsubscribe = lineObservable.sub((line) => {
+      this.decorations = createLineDecoration(view.state, line);
+      // Force a re-render; the decoration set changed out of band.
+      view.dispatch({ userEvent: "marimo.debugger-line-update" });
+    });
+  }
+
+  update(update: ViewUpdate) {
+    this.decorations = this.decorations.map(update.changes);
+  }
+
+  destroy() {
+    this.unsubscribe();
+  }
+}
+
+/** Highlight the line a cell's frame watcher is currently executing. */
+export function debuggerLineHighlighter(
+  lineObservable: Observable<number | null>,
+): Extension {
+  return [
+    ViewPlugin.define(
+      (view) => new CurrentLineHighlighter(view, lineObservable),
+      { decorations: (plugin) => plugin.decorations },
+    ),
+    EditorView.theme({
+      ".cm-debugger-current-line": {
+        backgroundColor: "color-mix(in srgb, var(--amber-4) 50%, transparent)",
+      },
+    }),
+  ];
+}
+
+// --- Breakpoint gutter ------------------------------------------------------
+
+class BreakpointMarker extends GutterMarker {
+  override toDOM() {
+    const dot = document.createElement("div");
+    dot.className = "cm-breakpoint-marker";
+    return dot;
+  }
+}
+
+const breakpointMarker = new BreakpointMarker();
+
+const setBreakpointLines = StateEffect.define<ReadonlySet<number>>();
+
+const breakpointLinesField = StateField.define<ReadonlySet<number>>({
+  create: () => new Set<number>(),
+  update(value, tr) {
+    for (const effect of tr.effects) {
+      if (effect.is(setBreakpointLines)) {
+        return effect.value;
+      }
+    }
+    return value;
+  },
+});
+
+function buildBreakpointMarkers(state: EditorState): RangeSet<GutterMarker> {
+  const lines = state.field(breakpointLinesField);
+  if (lines.size === 0) {
+    return RangeSet.empty;
+  }
+  const builder = new RangeSetBuilder<GutterMarker>();
+  for (const lineNo of [...lines].toSorted((a, b) => a - b)) {
+    if (lineNo >= 1 && lineNo <= state.doc.lines) {
+      const line = state.doc.line(lineNo);
+      builder.add(line.from, line.from, breakpointMarker);
+    }
+  }
+  return builder.finish();
+}
+
+/** Keep `breakpointLinesField` in sync with the per-cell breakpoints atom. */
+class BreakpointSync implements PluginValue {
+  private unsubscribe: () => void;
+
+  constructor(view: EditorView, observable: Observable<ReadonlySet<number>>) {
+    const apply = (lines: ReadonlySet<number>) => {
+      view.dispatch({ effects: setBreakpointLines.of(lines) });
+    };
+    // Dispatching during view construction is disallowed; defer the initial
+    // sync (e.g. for editors that mount after breakpoints already exist).
+    // Read the value fresh inside the microtask so a `sub` update that lands
+    // first isn't clobbered by a stale snapshot.
+    if (observable.get().size > 0) {
+      queueMicrotask(() => apply(observable.get()));
+    }
+    this.unsubscribe = observable.sub(apply);
+  }
+
+  destroy() {
+    this.unsubscribe();
+  }
+}
+
+/** A clickable gutter for toggling breakpoints on a cell's lines. */
+export function breakpointGutter(
+  cellId: CellId,
+  breakpointsObservable: Observable<ReadonlySet<number>>,
+): Extension {
+  return [
+    breakpointLinesField,
+    ViewPlugin.define(
+      (view) => new BreakpointSync(view, breakpointsObservable),
+    ),
+    gutter({
+      class: "cm-breakpoint-gutter",
+      markers: (view) => buildBreakpointMarkers(view.state),
+      initialSpacer: () => breakpointMarker,
+      domEventHandlers: {
+        mousedown: (view, line) => {
+          const lineNo = view.state.doc.lineAt(line.from).number;
+          toggleBreakpoint(cellId, lineNo);
+          return true;
+        },
+      },
+    }),
+    EditorView.theme({
+      ".cm-breakpoint-gutter": {
+        width: "14px",
+        cursor: "pointer",
+      },
+      ".cm-breakpoint-marker": {
+        width: "8px",
+        height: "8px",
+        borderRadius: "50%",
+        backgroundColor: "var(--red-9)",
+        margin: "4px auto",
+      },
+    }),
+  ];
+}

package/src/core/codemirror/cells/debugger-state.ts

@@ -0,0 +1,100 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import type { CellId } from "@/core/cells/ids";
+import { getRequestClient } from "@/core/network/requests";
+import { store } from "@/core/state/jotai";
+import { Logger } from "@/utils/Logger";
+
+/**
+ * State for the experimental live debugger.
+ *
+ * - `debuggerCurrentLineAtom` holds the cell + line the kernel's frame watcher
+ *   is currently executing (driven by `active-line` notifications). Only one
+ *   cell runs at a time, so a single global value suffices.
+ * - `breakpointsAtom` holds the user's gutter breakpoints, session-only. It is
+ *   the source of truth; mutations are mirrored to the kernel via
+ *   `sendSetBreakpoints`.
+ */
+
+export interface DebuggerLine {
+  cellId: CellId;
+  line: number;
+}
+
+export const debuggerCurrentLineAtom = atom<DebuggerLine | null>(null);
+
+export const breakpointsAtom = atom<ReadonlyMap<CellId, ReadonlySet<number>>>(
+  new Map<CellId, ReadonlySet<number>>(),
+);
+
+const EMPTY_LINES: ReadonlySet<number> = new Set();
+
+/** Per-cell derived atom: the current debug line for `cellId`, or `null`. */
+export function createDebuggerLineAtom(cellId: CellId) {
+  return atom((get) => {
+    const current = get(debuggerCurrentLineAtom);
+    return current?.cellId === cellId ? current.line : null;
+  });
+}
+
+/** Per-cell derived atom: the breakpoint lines for `cellId`. */
+export function createCellBreakpointsAtom(cellId: CellId) {
+  return atom((get) => get(breakpointsAtom).get(cellId) ?? EMPTY_LINES);
+}
+
+function sendBreakpoints(map: ReadonlyMap<CellId, ReadonlySet<number>>): void {
+  const breakpoints: Record<string, number[]> = {};
+  for (const [cellId, lines] of map) {
+    if (lines.size > 0) {
+      breakpoints[cellId] = [...lines].toSorted((a, b) => a - b);
+    }
+  }
+  // Fire-and-forget: the request layer rethrows on failure (e.g. static or
+  // wasm mode with no live kernel). Swallow it so toggling a breakpoint never
+  // surfaces as an unhandled promise rejection.
+  getRequestClient()
+    .sendSetBreakpoints({ breakpoints })
+    .catch((error) => {
+      Logger.debug("Failed to sync breakpoints to kernel", { error });
+    });
+}
+
+/** Remove all breakpoints for a cell and sync the full set to the kernel. */
+export function clearCellBreakpoints(cellId: CellId): void {
+  const prev = store.get(breakpointsAtom);
+  if (!prev.has(cellId)) {
+    return;
+  }
+  const next = new Map(prev);
+  next.delete(cellId);
+  store.set(breakpointsAtom, next);
+  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);
+  const next = new Map(prev);
+  const lines = new Set(next.get(cellId) ?? []);
+  if (lines.has(line)) {
+    lines.delete(line);
+  } else {
+    lines.add(line);
+  }
+  if (lines.size > 0) {
+    next.set(cellId, lines);
+  } else {
+    next.delete(cellId);
+  }
+  store.set(breakpointsAtom, next);
+  sendBreakpoints(next);
+}

package/src/core/codemirror/cells/extensions.ts

@@ -17,6 +17,7 @@ import {
 import { loroSyncAnnotation } from "@/core/codemirror/rtc/loro/sync";
 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";
@@ -25,6 +26,14 @@ 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 {
+  createCellBreakpointsAtom,
+  createDebuggerLineAtom,
+} from "./debugger-state";
 import {
   type CodemirrorCellActions,
   cellActionsState,
@@ -106,11 +115,8 @@ function cellKeymaps({
     keybindings.push(
       {
         key: hotkeys.getHotkey("cell.goToDefinition").key,
-        preventDefault: true,
-        stopPropagation: true,
         run: (ev) => {
-          goToDefinitionAtCursorPosition(ev);
-          return true;
+          return goToDefinitionAtCursorPosition(ev);
         },
       },
       {
@@ -431,6 +437,19 @@ export function cellBundle({
     errorLineHighlighter(
       createObservable(createTracebackInfoAtom(cellId), store),
     ),
+    // Experimental live debugger: clickable breakpoint gutter + current-line
+    // highlight. Gated so there is no gutter/overhead when disabled.
+    getFeatureFlag("debugger")
+      ? [
+          breakpointGutter(
+            cellId,
+            createObservable(createCellBreakpointsAtom(cellId), store),
+          ),
+          debuggerLineHighlighter(
+            createObservable(createDebuggerLineAtom(cellId), store),
+          ),
+        ]
+      : [],
   ];
 }
 

package/src/core/codemirror/go-to-definition/__tests__/utils.test.ts

@@ -2,13 +2,17 @@
 
 import { python } from "@codemirror/lang-python";
 import { EditorState } from "@codemirror/state";
-import { EditorView } from "@codemirror/view";
-import { afterEach, describe, expect, test } from "vitest";
+import { EditorView, keymap } from "@codemirror/view";
+import { afterEach, describe, expect, test, vi } from "vitest";
 import { cellId, variableName } from "@/__tests__/branded";
 import { initialNotebookState, notebookAtom } from "@/core/cells/cells";
 import { store } from "@/core/state/jotai";
 import { variablesAtom } from "@/core/variables/state";
-import { goToDefinitionAtCursorPosition } from "../utils";
+import {
+  goToDefinitionAtCursorPosition,
+  goToDefinitionWithLspFallback,
+  requestLspGoToDefinition,
+} from "../utils";
 
 async function tick(): Promise<void> {
   await new Promise((resolve) => requestAnimationFrame(resolve));
@@ -181,3 +185,71 @@ print(mymodule)`;
     );
   });
 });
+
+describe("goToDefinitionWithLspFallback", () => {
+  test("falls through to LSP when marimo cannot resolve the symbol", () => {
+    const lspGoToDefinition = vi.fn(() => true);
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: "parser.add_argument('--foo')",
+        selection: { anchor: "parser.add_argument".indexOf("add_argument") },
+        extensions: [
+          python(),
+          keymap.of([{ key: "F12", run: lspGoToDefinition }]),
+        ],
+      }),
+      parent: document.body,
+    });
+    views.push(view);
+
+    const result = goToDefinitionWithLspFallback(view);
+
+    expect(result).toBe(true);
+    expect(lspGoToDefinition).toHaveBeenCalledOnce();
+  });
+
+  test("does not invoke LSP when marimo resolves the symbol", async () => {
+    const lspGoToDefinition = vi.fn(() => true);
+    const code = "a = 10\nprint(a)";
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: code,
+        selection: { anchor: code.indexOf("a", 3) },
+        extensions: [
+          python(),
+          keymap.of([{ key: "F12", run: lspGoToDefinition }]),
+        ],
+      }),
+      parent: document.body,
+    });
+    views.push(view);
+
+    const result = goToDefinitionWithLspFallback(view);
+
+    expect(result).toBe(true);
+    expect(lspGoToDefinition).not.toHaveBeenCalled();
+    await tick();
+    expect(view.state.selection.main.head).toBe(0);
+  });
+
+  test("falls through with a modified shortcut like Ctrl-F12", () => {
+    const lspGoToDefinition = vi.fn(() => true);
+    const view = new EditorView({
+      state: EditorState.create({
+        doc: "parser.add_argument('--foo')",
+        selection: { anchor: "parser.add_argument".indexOf("add_argument") },
+        extensions: [
+          python(),
+          keymap.of([{ key: "Ctrl-F12", run: lspGoToDefinition }]),
+        ],
+      }),
+      parent: document.body,
+    });
+    views.push(view);
+
+    const result = requestLspGoToDefinition(view, "Ctrl-F12");
+
+    expect(result).toBe(true);
+    expect(lspGoToDefinition).toHaveBeenCalledOnce();
+  });
+});

package/src/core/codemirror/go-to-definition/extension.ts

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { EditorView } from "@codemirror/view";
 import { createUnderlinePlugin, underlineField } from "./underline";
-import { goToDefinition } from "./utils";
+import { goToDefinitionWithLspFallback } from "./utils";
 
 /**
  * Create a go-to-definition extension.
@@ -9,8 +9,8 @@ import { goToDefinition } from "./utils";
 export function goToDefinitionBundle() {
   return [
     underlineField,
-    createUnderlinePlugin((view, variableName) => {
-      goToDefinition(view, variableName);
+    createUnderlinePlugin((view) => {
+      goToDefinitionWithLspFallback(view);
     }),
     EditorView.baseTheme({
       ".underline": {

package/src/core/codemirror/go-to-definition/underline.ts

@@ -55,12 +55,9 @@ class MetaUnderlineVariablePlugin {
   private view: EditorView;
   private commandClickMode: boolean;
   private hoveredRange: { from: number; to: number; position: number } | null;
-  private onClick: (view: EditorView, variableName: string) => void;
+  private onClick: (view: EditorView) => void;
 
-  constructor(
-    view: EditorView,
-    onClick: (view: EditorView, variableName: string) => void,
-  ) {
+  constructor(view: EditorView, onClick: (view: EditorView) => void) {
     this.view = view;
     this.commandClickMode = false;
     this.hoveredRange = null;
@@ -191,20 +188,16 @@ class MetaUnderlineVariablePlugin {
   // If we have a hovered range, go to it
   private click = (event: MouseEvent) => {
     if (this.hoveredRange) {
-      const variableName = this.view.state.doc.sliceString(
-        this.hoveredRange.from,
-        this.hoveredRange.to,
-      );
       event.preventDefault();
       event.stopPropagation();
-      this.onClick(this.view, variableName);
-      // Move the cursor to the clicked position
+      // Move the cursor before resolving so LSP uses the clicked position.
       this.view.dispatch({
         selection: {
           head: this.hoveredRange.position,
           anchor: this.hoveredRange.position,
         },
       });
+      this.onClick(this.view);
     }
   };
 
@@ -217,7 +210,5 @@ class MetaUnderlineVariablePlugin {
   }
 }
 
-export const createUnderlinePlugin = (
-  onClick: (view: EditorView, variableName: string) => void,
-) =>
+export const createUnderlinePlugin = (onClick: (view: EditorView) => void) =>
   ViewPlugin.define((view) => new MetaUnderlineVariablePlugin(view, onClick));