@marimo-team/islands 0.21.2-dev1 → 0.21.2-dev100

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

@@ -2,9 +2,15 @@
 
 import { closeCompletion, completionStatus } from "@codemirror/autocomplete";
 import { type Extension, Prec } from "@codemirror/state";
-import { EditorView, type KeyBinding, keymap } from "@codemirror/view";
+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 { loroSyncAnnotation } from "@/core/codemirror/rtc/loro/sync";
 import type { KeymapConfig } from "@/core/config/config-schema";
 import type { HotkeyProvider } from "@/core/hotkeys/hotkeys";
 import { duplicateWithCtrlModifier } from "@/core/hotkeys/shortcuts";
@@ -330,6 +336,53 @@ function cellCodeEditing(hotkeys: HotkeyProvider): Extension[] {
   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 RTC sync changes to avoid duplicate runs from remote edits.
+    if (tr.annotation(loroSyncAnnotation) !== undefined) {
+      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
  */
@@ -339,30 +392,16 @@ export function markdownAutoRunExtension({
   predicate: () => boolean;
 }): Extension {
   return EditorView.updateListener.of((update) => {
-    // If the doc didn't change, ignore
-    if (!update.docChanged) {
-      return;
-    }
-
-    // If not focused, ignore
-    // This can cause multiple runs when in RTC mode
-    if (!update.view.hasFocus) {
-      return;
-    }
-
-    if (!predicate()) {
+    if (
+      !shouldAutorunMarkdownUpdate({
+        docChanged: update.docChanged,
+        transactions: update.transactions,
+        predicate,
+        hasFocus: update.view.hasFocus,
+      })
+    ) {
       return;
     }
-
-    // This happens on mount when we start in markdown mode
-    const isFormattingChange = update.transactions.some((tr) =>
-      tr.effects.some((effect) => effect.is(formattingChangeEffect)),
-    );
-    if (isFormattingChange) {
-      // Ignore formatting changes
-      return;
-    }
-
     const actions = update.view.state.facet(cellActionsState);
     actions.onRun();
   });
@@ -388,3 +427,7 @@ export function cellBundle({
     ),
   ];
 }
+
+export const exportedForTesting = {
+  shouldAutorunMarkdownUpdate,
+};

package/src/core/codemirror/completion/__tests__/keymap.test.ts

@@ -1,44 +1,24 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { EditorState } from "@codemirror/state";
-import { EditorView } from "@codemirror/view";
-import { describe, expect, it, vi } from "vitest";
-import { completionKeymap } from "../keymap";
+import { completionKeymap as defaultCompletionKeymap } from "@codemirror/autocomplete";
+import { describe, expect, it } from "vitest";
+import { filterCompletionBindings } from "../keymap";
 
 describe("completionKeymap", () => {
-  it("should propagate Escape key when completion is pending", () => {
-    const state = EditorState.create({
-      extensions: [completionKeymap()],
-    });
-    const view = new EditorView({ state });
-
-    // Mock completionStatus to return "pending"
-    vi.spyOn(view.state, "field").mockReturnValue("pending");
-
-    view.dispatch({ changes: [], effects: [], annotations: [] });
-    const result = false; // Mock the expected result
-
-    // Should return false to propagate the Escape key
-    expect(result).toBe(false);
-
-    view.destroy();
+  it("upstream includes the macOS-only completion bindings we care about", () => {
+    expect(
+      defaultCompletionKeymap.some((binding) => binding.mac === "Alt-`"),
+    ).toBe(true);
+    expect(
+      defaultCompletionKeymap.some((binding) => binding.mac === "Alt-i"),
+    ).toBe(true);
   });
 
-  it("should not propagate Escape key when completion is active", () => {
-    const state = EditorState.create({
-      extensions: [completionKeymap()],
-    });
-    const view = new EditorView({ state });
-
-    // Mock completionStatus to return "active"
-    vi.spyOn(view.state, "field").mockReturnValue("active");
-
-    view.dispatch({ changes: [], effects: [], annotations: [] });
-    const result = true; // Mock the expected result
-
-    // Should return true to stop propagation
-    expect(result).toBe(true);
+  it("removes Alt-backtick and Escape while keeping Alt-i", () => {
+    const filtered = filterCompletionBindings(defaultCompletionKeymap);
 
-    view.destroy();
+    expect(filtered.some((binding) => binding.mac === "Alt-`")).toBe(false);
+    expect(filtered.some((binding) => binding.key === "Escape")).toBe(false);
+    expect(filtered.some((binding) => binding.mac === "Alt-i")).toBe(true);
   });
 });

package/src/core/codemirror/completion/keymap.ts

@@ -6,7 +6,7 @@ import {
   moveCompletionSelection,
 } from "@codemirror/autocomplete";
 import { type Extension, Prec } from "@codemirror/state";
-import { keymap } from "@codemirror/view";
+import { type KeyBinding, keymap } from "@codemirror/view";
 import { isInVimMode } from "../utils";
 
 const KEYS_TO_REMOVE = new Set<string | undefined>([
@@ -22,10 +22,20 @@ const KEYS_TO_REMOVE = new Set<string | undefined>([
   "Alt-`",
 ]);
 
-export function completionKeymap(): Extension {
-  const withoutKeysToRemove = defaultCompletionKeymap.filter(
-    (binding) => !KEYS_TO_REMOVE.has(binding.key),
+function hasRemovedKeybinding(binding: KeyBinding): boolean {
+  return [binding.key, binding.mac, binding.linux, binding.win].some((key) =>
+    KEYS_TO_REMOVE.has(key),
   );
+}
+
+export function filterCompletionBindings(
+  bindings: readonly KeyBinding[],
+): readonly KeyBinding[] {
+  return bindings.filter((binding) => !hasRemovedKeybinding(binding));
+}
+
+export function completionKeymap(): Extension {
+  const withoutKeysToRemove = filterCompletionBindings(defaultCompletionKeymap);
 
   return Prec.highest(
     keymap.of([

package/src/core/codemirror/copilot/__tests__/getCodes.test.ts

@@ -3,28 +3,27 @@
 import { EditorState } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
 import { describe, expect, it } from "vitest";
+import { cellId, variableName } from "@/__tests__/branded";
 import { initialNotebookState, notebookAtom } from "@/core/cells/cells";
-import type { CellId } from "@/core/cells/ids";
 import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
 import { store } from "@/core/state/jotai";
 import { variablesAtom } from "@/core/variables/state";
-import type { VariableName, Variables } from "@/core/variables/types";
 import { MultiColumn } from "@/utils/id-tree";
 import { cellConfigExtension } from "../../config/extension";
 import { adaptiveLanguageConfiguration } from "../../language/extension";
 import { getCodes, getTopologicalCellIds } from "../getCodes";
 
 const Cells = {
-  cell1: "cell1" as CellId,
-  cell2: "cell2" as CellId,
-  cell3: "cell3" as CellId,
-  cell4: "cell4" as CellId,
+  cell1: cellId("cell1"),
+  cell2: cellId("cell2"),
+  cell3: cellId("cell3"),
+  cell4: cellId("cell4"),
 };
 
 const Variables = {
-  var1: "var1" as VariableName,
-  var2: "var2" as VariableName,
-  var3: "var3" as VariableName,
+  var1: variableName("var1"),
+  var2: variableName("var2"),
+  var3: variableName("var3"),
 };
 
 function createMockEditorView(code: string) {
@@ -33,7 +32,7 @@ function createMockEditorView(code: string) {
       doc: code,
       extensions: [
         adaptiveLanguageConfiguration({
-          cellId: "cell1" as CellId,
+          cellId: cellId("cell1"),
           completionConfig: {
             copilot: false,
             activate_on_typing: true,
@@ -45,7 +44,7 @@ function createMockEditorView(code: string) {
           lspConfig: {},
         }),
         cellConfigExtension({
-          cellId: "cell1" as CellId,
+          cellId: cellId("cell1"),
           completionConfig: {
             copilot: false,
             activate_on_typing: true,
@@ -71,7 +70,7 @@ describe("getTopologicalCellIds", () => {
   it("should return topologically sorted cell IDs", () => {
     // Setup mock data
     const cellIds = [Cells.cell1, Cells.cell2, Cells.cell3, Cells.cell4];
-    const variables: Variables = {
+    const variables = {
       [Variables.var1]: {
         name: Variables.var1,
         declaredBy: [Cells.cell1],
@@ -125,7 +124,7 @@ describe("getTopologicalCellIds", () => {
 
   it("should put new cells (with no dependencies) at the end", () => {
     const cellIds = [Cells.cell1, Cells.cell2, Cells.cell3, Cells.cell4];
-    const variables: Variables = {
+    const variables = {
       [Variables.var1]: {
         name: Variables.var1,
         declaredBy: [Cells.cell2],

package/src/core/codemirror/language/__tests__/utils.test.ts

@@ -3,7 +3,7 @@
 import { EditorState } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
 import { describe, expect, it } from "vitest";
-import type { CellId } from "@/core/cells/ids";
+import { cellId } from "@/__tests__/branded";
 import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
 import { cellConfigExtension } from "../../config/extension";
 import { adaptiveLanguageConfiguration, switchLanguage } from "../extension";
@@ -26,12 +26,12 @@ function createEditor(doc: string) {
             codeium_api_key: null,
           },
           hotkeys: new OverridingHotkeyProvider({}),
-          cellId: "cell1" as CellId,
+          cellId: cellId("cell1"),
           placeholderType: "marimo-import",
           lspConfig: {},
         }),
         cellConfigExtension({
-          cellId: "cell1" as CellId,
+          cellId: cellId("cell1"),
           completionConfig: {
             activate_on_typing: true,
             signature_hint_on_typing: false,

package/src/core/codemirror/language/embedded/__tests__/embedded-python.test.ts

@@ -5,10 +5,9 @@ import { python } from "@codemirror/lang-python";
 import { EditorState } from "@codemirror/state";
 import type { InlineContext } from "@lezer/markdown";
 import { beforeEach, describe, expect, it } from "vitest";
-import type { CellId } from "@/core/cells/ids";
+import { cellId, variableName } from "@/__tests__/branded";
 import { store } from "@/core/state/jotai";
 import { variablesAtom } from "@/core/variables/state";
-import type { VariableName, Variables } from "@/core/variables/types";
 import { parsePython, variableCompletionSource } from "../embedded-python";
 
 const IS_ACTIVE = () => true;
@@ -51,16 +50,16 @@ describe("parsePython", () => {
 
 describe("variableCompletionSource", () => {
   beforeEach(() => {
-    const mockCellId = "cell-1" as CellId;
-    const mockVariables: Variables = {
-      ["var1" as VariableName]: {
-        name: "var1" as VariableName,
+    const mockCellId = cellId("cell-1");
+    const mockVariables = {
+      [variableName("var1")]: {
+        name: variableName("var1"),
         dataType: "int",
         declaredBy: [mockCellId],
         usedBy: [mockCellId],
       },
-      ["var2" as VariableName]: {
-        name: "var2" as VariableName,
+      [variableName("var2")]: {
+        name: variableName("var2"),
         dataType: "str",
         declaredBy: [mockCellId],
         usedBy: [mockCellId],

package/src/core/codemirror/language/languages/python.ts

@@ -69,6 +69,10 @@ const pylspClient = once((lspConfig: LSPConfig) => {
     "W292", // No newline at end of file
     // Modules can be imported in any cell
     "E402", // Module level import not at top of file
+    // Blank line rules are not useful in marimo because cells are joined
+    // without extra blank lines, which can trigger these rules at cell boundaries
+    "E302", // Expected 2 blank lines, found 0
+    "E305", // Expected 2 blank lines after class or function definition, found 0
   ];
   const ignoredRuffRules = [
     // Even ruff documentation of this rule explains it is not useful in notebooks

package/src/core/codemirror/lsp/__tests__/notebook-lsp.test.ts

@@ -8,6 +8,7 @@ import {
 } from "@marimo-team/codemirror-languageserver";
 import { beforeEach, describe, expect, it, type Mocked, vi } from "vitest";
 import * as LSP from "vscode-languageserver-protocol";
+import { cellId } from "@/__tests__/branded";
 import type { CellId } from "@/core/cells/ids";
 import { store } from "@/core/state/jotai";
 import { topologicalCodesAtom } from "../../copilot/getCodes";
@@ -19,9 +20,9 @@ import { NotebookLanguageServerClient } from "../notebook-lsp";
 import { CellDocumentUri, type ILanguageServerClient } from "../types";
 
 const Cells = {
-  cell1: "cell1" as CellId,
-  cell2: "cell2" as CellId,
-  cell3: "cell3" as CellId,
+  cell1: cellId("cell1"),
+  cell2: cellId("cell2"),
+  cell3: cellId("cell3"),
 };
 
 describe("createNotebookLens", () => {

package/src/core/codemirror/lsp/notebook-lsp.ts

@@ -178,6 +178,8 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
     string,
     Promise<LSP.CompletionItem>
   >(10);
+  private latestDiagnosticsVersion: number | null = null;
+  private forwardedDiagnosticsVersion = 0;
 
   constructor(
     client: ILanguageServerClient,
@@ -270,6 +272,8 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
 
     // Get the current document state
     const { lens, version } = this.snapshotter.snapshot();
+    this.latestDiagnosticsVersion = null;
+    this.forwardedDiagnosticsVersion = 0;
 
     // Re-open the merged document with the LSP server
     // This sends a textDocument/didOpen for the entire notebook
@@ -768,13 +772,34 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
         | { method: "other"; params: unknown },
     ) => {
       if (notification.method === "textDocument/publishDiagnostics") {
+        const incomingVersion = notification.params.version;
+        if (incomingVersion != null) {
+          const latestVersion = this.latestDiagnosticsVersion;
+          if (
+            latestVersion !== null &&
+            Number.isFinite(incomingVersion) &&
+            incomingVersion < latestVersion
+          ) {
+            Logger.debug(
+              "[lsp] dropping stale diagnostics notification",
+              notification,
+            );
+            return;
+          }
+          this.latestDiagnosticsVersion = incomingVersion;
+        }
+
         Logger.debug("[lsp] handling diagnostics", notification);
         // Use the correct lens by version
         const payload = this.snapshotter.getLatestSnapshot();
 
         const diagnostics = notification.params.diagnostics;
 
-        const { lens, version: cellVersion } = payload;
+        const { lens } = payload;
+        // Forward diagnostics with a strictly increasing version so downstream
+        // plugin updates/clears reliably, even when server repeats the same
+        // document version across multiple publishDiagnostics notifications.
+        const diagnosticsVersion = ++this.forwardedDiagnosticsVersion;
 
         // Pre-partition diagnostics by cell
         const diagnosticsByCellId = new Map<CellId, LSP.Diagnostic[]>();
@@ -817,7 +842,7 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
             params: {
               ...notification.params,
               uri: cellDocumentUri,
-              version: cellVersion,
+              version: diagnosticsVersion,
               diagnostics: cellDiagnostics,
             },
           });
@@ -832,6 +857,7 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
               method: "textDocument/publishDiagnostics",
               params: {
                 uri: cellDocumentUri,
+                version: diagnosticsVersion,
                 diagnostics: [],
               },
             });

package/src/core/codemirror/reactive-references/__tests__/analyzer.test.ts

@@ -3,8 +3,8 @@
 import { python } from "@codemirror/lang-python";
 import { EditorState } from "@codemirror/state";
 import { describe, expect, test } from "vitest";
-import type { CellId } from "@/core/cells/ids";
-import type { VariableName, Variables } from "@/core/variables/types";
+import { cellId, variableName } from "@/__tests__/branded";
+import type { Variables } from "@/core/variables/types";
 import { findReactiveVariables, type ReactiveVariableRange } from "../analyzer";
 
 describe("findReactiveVariables - Lexical Scoping", () => {
@@ -1199,16 +1199,17 @@ class Foo:
 function runHighlight(variableNames: string[], code: string): string {
   const variables: Variables = {};
   for (const name of variableNames) {
-    variables[name as VariableName] = {
-      name: name as VariableName,
-      declaredBy: ["other-cell" as CellId],
+    const varName = variableName(name);
+    variables[varName] = {
+      name: varName,
+      declaredBy: [cellId("other-cell")],
       usedBy: [],
       value: "test-value",
       dataType: "str",
     };
   }
   const ranges = findReactiveVariables({
-    cellId: "current-cell" as CellId,
+    cellId: cellId("current-cell"),
     state: EditorState.create({
       doc: code,
       extensions: [python()],

package/src/core/codemirror/reactive-references/analyzer.ts

@@ -3,7 +3,7 @@
 import { syntaxTree } from "@codemirror/language";
 import type { EditorState } from "@codemirror/state";
 import type { SyntaxNode, Tree, TreeCursor } from "@lezer/common";
-import type { CellId } from "@/core/cells/ids";
+import { type CellId, SETUP_CELL_ID } from "@/core/cells/ids";
 import type { VariableName, Variables } from "@/core/variables/types";
 
 export interface ReactiveVariableRange {
@@ -52,7 +52,7 @@ export function findReactiveVariables(options: {
       const variable = options.variables[name as VariableName];
       return (
         variable.dataType !== "module" &&
-        !variable.declaredBy.includes("setup" as CellId) &&
+        !variable.declaredBy.includes(SETUP_CELL_ID) &&
         !variable.declaredBy.includes(options.cellId)
       );
     }),

package/src/core/codemirror/rtc/extension.ts

@@ -2,8 +2,8 @@
 
 import type { Extension } from "@codemirror/state";
 import { EditorView, ViewPlugin } from "@codemirror/view";
+import { dequal as isEqual } from "dequal";
 import { atom } from "jotai";
-import { isEqual } from "lodash-es";
 import { Awareness, LoroDoc, LoroMap, LoroText } from "loro-crdt";
 import ReconnectingWebSocket from "partysocket/ws";
 import type { CellId } from "@/core/cells/ids";

package/src/core/codemirror/rtc/loro/__tests__/sync.test.ts

@@ -0,0 +1,52 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { EditorState } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
+import { LoroDoc, LoroText } from "loro-crdt";
+import { describe, expect, it, vi } from "vitest";
+import { LoroSyncPluginValue, loroSyncAnnotation } from "../sync";
+
+describe("LoroSyncPluginValue", () => {
+  it("annotates the initial reconciliation dispatch as RTC sync", async () => {
+    const dispatch = vi.fn();
+    const view = {
+      state: EditorState.create({ doc: "local" }),
+      dispatch,
+    } as unknown as EditorView;
+
+    const doc = new LoroDoc();
+    const text = doc
+      .getMap("codes")
+      .getOrCreateContainer("cell-1", new LoroText());
+    text.insert(0, "remote");
+
+    const plugin = new LoroSyncPluginValue(
+      view,
+      doc,
+      ["codes", "cell-1"],
+      () => text,
+    );
+
+    await Promise.resolve();
+
+    expect(dispatch).toHaveBeenCalledTimes(1);
+    expect(dispatch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        changes: [
+          {
+            from: 0,
+            to: view.state.doc.length,
+            insert: "remote",
+          },
+        ],
+        annotations: [
+          expect.objectContaining({
+            type: loroSyncAnnotation,
+          }),
+        ],
+      }),
+    );
+
+    plugin.destroy();
+  });
+});

package/src/core/codemirror/rtc/loro/sync.ts

@@ -72,6 +72,7 @@ export class LoroSyncPluginValue implements PluginValue {
             insert: text.toString(),
           },
         ],
+        annotations: [loroSyncAnnotation.of(this)],
       });
     });
   }