@marimo-team/islands 0.23.14-dev6 → 0.23.14-dev61

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,133 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import type { CellId } from "@/core/cells/ids";
+import type { ActiveLineInfo } from "@/core/codemirror/cells/line-timing-decorations";
+import { getRequestClient } from "@/core/network/requests";
+import { store } from "@/core/state/jotai";
+import { Logger } from "@/utils/Logger";
+
+/**
+ * State for the experimental live debugger and line-timing highlight.
+ *
+ * - `activeLineAtom` holds the cell + line the kernel's frame watcher is
+ *   currently executing (driven by `active-line` notifications), plus when
+ *   the frontend first saw execution on that line. 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 ActiveLine {
+  cellId: CellId;
+  line: number;
+  /** When the frontend first saw execution on this (cellId, line). */
+  startedAtMs: number;
+}
+
+export const activeLineAtom = atom<ActiveLine | null>(null);
+
+/**
+ * Update the active line, stamping `startedAtMs` only when the (cellId, line)
+ * actually changes, so duplicate notifications (e.g. reconnects) never reset
+ * the elapsed-time baseline.
+ */
+export function setActiveLine(
+  next: { cellId: CellId; line: number } | null,
+): void {
+  const prev = store.get(activeLineAtom);
+  if (next === null) {
+    store.set(activeLineAtom, null);
+    return;
+  }
+  if (prev?.cellId === next.cellId && prev.line === next.line) {
+    return;
+  }
+  store.set(activeLineAtom, { ...next, startedAtMs: Date.now() });
+}
+
+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(activeLineAtom);
+    return current?.cellId === cellId ? current.line : null;
+  });
+}
+
+/** Per-cell derived atom: the active line + start time for `cellId`, or `null`. */
+export function createActiveLineInfoAtom(cellId: CellId) {
+  return atom((get): ActiveLineInfo | null => {
+    const current = get(activeLineAtom);
+    return current?.cellId === cellId
+      ? { line: current.line, startedAtMs: current.startedAtMs }
+      : 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,16 @@ 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,
@@ -106,11 +117,8 @@ function cellKeymaps({
     keybindings.push(
       {
         key: hotkeys.getHotkey("cell.goToDefinition").key,
-        preventDefault: true,
-        stopPropagation: true,
         run: (ev) => {
-          goToDefinitionAtCursorPosition(ev);
-          return true;
+          return goToDefinitionAtCursorPosition(ev);
         },
       },
       {
@@ -423,6 +431,8 @@ export function cellBundle({
   cellActions: CodemirrorCellActions;
   keymapConfig: KeymapConfig;
 }): Extension[] {
+  const debuggerOn = getFeatureFlag("debugger");
+  const lineTimingOn = getFeatureFlag("line_timing");
   return [
     cellActionsState.of(cellActions),
     cellIdState.of(cellId),
@@ -431,6 +441,24 @@ export function cellBundle({
     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),
+          )
+        : [],
   ];
 }
 

package/src/core/codemirror/cells/line-timing-decorations.ts

@@ -0,0 +1,165 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import {
+  type EditorState,
+  type Extension,
+  RangeSetBuilder,
+} from "@codemirror/state";
+import {
+  Decoration,
+  type DecorationSet,
+  EditorView,
+  type PluginValue,
+  ViewPlugin,
+  type ViewUpdate,
+  WidgetType,
+} from "@codemirror/view";
+import type { Observable } from "@/core/state/observable";
+import { Logger } from "@/utils/Logger";
+import { formatElapsedTime } from "@/utils/time";
+
+/** The line a cell is currently executing and when execution first hit it. */
+export interface ActiveLineInfo {
+  line: number;
+  startedAtMs: number;
+}
+
+// Only show the timer once a line has been busy this long, so short-lived
+// lines never flash a pill.
+const SHOW_TIMER_AFTER_MS = 500;
+const TICK_INTERVAL_MS = 250;
+
+/**
+ * End-of-line elapsed-time pill for the currently executing line.
+ *
+ * Ticking is pure DOM mutation on the widget's own interval; no editor
+ * transactions are dispatched while the timer counts.
+ */
+class LineTimerWidget extends WidgetType {
+  // Track intervals per DOM node: CodeMirror may reuse the node across
+  // decoration remaps (`eq` below), and `destroy` only receives the node.
+  private static readonly intervals = new WeakMap<HTMLElement, number>();
+
+  private readonly startedAtMs: number;
+
+  constructor(startedAtMs: number) {
+    super();
+    this.startedAtMs = startedAtMs;
+  }
+
+  override eq(other: LineTimerWidget): boolean {
+    return other.startedAtMs === this.startedAtMs;
+  }
+
+  override toDOM(): HTMLElement {
+    const el = document.createElement("span");
+    el.className = "cm-line-timer";
+    el.setAttribute("aria-hidden", "true");
+    const tick = () => {
+      const elapsed = Date.now() - this.startedAtMs;
+      el.textContent =
+        elapsed >= SHOW_TIMER_AFTER_MS ? formatElapsedTime(elapsed) : "";
+    };
+    tick();
+    LineTimerWidget.intervals.set(
+      el,
+      window.setInterval(tick, TICK_INTERVAL_MS),
+    );
+    return el;
+  }
+
+  override destroy(dom: HTMLElement): void {
+    const interval = LineTimerWidget.intervals.get(dom);
+    if (interval !== undefined) {
+      window.clearInterval(interval);
+      LineTimerWidget.intervals.delete(dom);
+    }
+  }
+
+  override ignoreEvent(): boolean {
+    return true;
+  }
+}
+
+function createTimingDecorations(
+  state: EditorState,
+  info: ActiveLineInfo | null,
+): DecorationSet {
+  if (info === null || info.line < 1 || info.line > state.doc.lines) {
+    return Decoration.none;
+  }
+  const builder = new RangeSetBuilder<Decoration>();
+  try {
+    const line = state.doc.line(info.line);
+    builder.add(
+      line.from,
+      line.from,
+      Decoration.line({ class: "cm-timing-current-line" }),
+    );
+    builder.add(
+      line.to,
+      line.to,
+      Decoration.widget({
+        widget: new LineTimerWidget(info.startedAtMs),
+        side: 1,
+      }),
+    );
+  } catch (error) {
+    Logger.debug("Invalid timing line", { error });
+  }
+  return builder.finish();
+}
+
+class ActiveLineTimer implements PluginValue {
+  private unsubscribe: () => void;
+  decorations: DecorationSet;
+
+  constructor(
+    view: EditorView,
+    infoObservable: Observable<ActiveLineInfo | null>,
+  ) {
+    this.decorations = createTimingDecorations(
+      view.state,
+      infoObservable.get(),
+    );
+    this.unsubscribe = infoObservable.sub((info) => {
+      this.decorations = createTimingDecorations(view.state, info);
+      // Force a re-render; the decoration set changed out of band.
+      view.dispatch({ userEvent: "marimo.timing-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 in green,
+ * with a dim elapsed-time pill at the end of the line once it has been busy
+ * for a while.
+ */
+export function activeLineTimer(
+  infoObservable: Observable<ActiveLineInfo | null>,
+): Extension {
+  return [
+    ViewPlugin.define((view) => new ActiveLineTimer(view, infoObservable), {
+      decorations: (plugin) => plugin.decorations,
+    }),
+    EditorView.theme({
+      ".cm-timing-current-line": {
+        backgroundColor: "color-mix(in srgb, var(--grass-4) 50%, transparent)",
+      },
+      ".cm-line-timer": {
+        color: "var(--grass-11)",
+        fontSize: "0.85em",
+        marginLeft: "1.5ch",
+        pointerEvents: "none",
+      },
+    }),
+  ];
+}

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": {