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.

Read cell content and order from the host document (#11529)

Trevor Manz61821868ef1d
diff --git a/frontend/benchmarks/cell-editing.bench.ts b/frontend/benchmarks/cell-editing.bench.ts
index 0bf27a10c8..8c9f20bfef 100644
--- a/frontend/benchmarks/cell-editing.bench.ts
+++ b/frontend/benchmarks/cell-editing.bench.ts
@@ -1,10 +1,11 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { type Atom, createStore } from "jotai";
-import { bench, describe, expect, vi } from "vitest";
+import { bench, describe, expect } from "vitest";
import { MockNotebook } from "@/__mocks__/notebook";
import { cellId } from "@/__tests__/branded";
import {
+ type CellActions,
cellDataAtom,
cellErrorsAtom,
cellHandleAtom,
@@ -18,20 +19,11 @@ import {
notebookReducer,
} from "@/core/cells/cells";
import type { CellData } from "@/core/cells/types";
-import type { CellAction } from "@/core/cells/document-changes";
import { layoutStateAtom } from "@/core/layout/state";
import { lastSavedNotebookAtom, needsSaveAtom } from "@/core/saving/state";
+import type { DispatchedActionOf } from "@/utils/createReducer";
-// Keep action-to-document conversion, but exclude the network queue and timers.
-// Otherwise a throughput benchmark queues millions of artificial keystrokes.
-vi.mock("@/core/cells/document-changes", async (importOriginal) => {
- const actual =
- await importOriginal<typeof import("@/core/cells/document-changes")>();
- return {
- ...actual,
- documentTransactionMiddleware: actual.toDocumentChanges,
- };
-});
+type CellAction = DispatchedActionOf<CellActions>;
const options = { time: 500, warmupTime: 200, iterations: 100 };
const code = Array.from({ length: 20 }, (_, i) => `value_${i} = ${i}`).join(
diff --git a/frontend/src/__mocks__/requests.ts b/frontend/src/__mocks__/requests.ts
index 148b19ba1c..81b64c5a15 100644
--- a/frontend/src/__mocks__/requests.ts
+++ b/frontend/src/__mocks__/requests.ts
@@ -17,7 +17,6 @@ export const MockRequestClient = {
sendModelValue: vi.fn().mockResolvedValue({}),
sendRename: vi.fn().mockResolvedValue({}),
sendRestart: vi.fn().mockResolvedValue({}),
- sendDocumentTransaction: vi.fn().mockResolvedValue({}),
sendSave: vi.fn().mockResolvedValue({}),
sendCopy: vi.fn().mockResolvedValue({}),
sendStdin: vi.fn().mockResolvedValue({}),
diff --git a/frontend/src/components/editor/cell/StagedAICell.tsx b/frontend/src/components/editor/cell/StagedAICell.tsx
index 9d4dc546bb..2d6f37ae1e 100644
--- a/frontend/src/components/editor/cell/StagedAICell.tsx
+++ b/frontend/src/components/editor/cell/StagedAICell.tsx
@@ -11,7 +11,7 @@ import {
} from "@/core/ai/staged-cells";
import { getCellEditorView } from "@/core/cells/cells";
import type { CellId } from "@/core/cells/ids";
-import { updateEditorCodeFromPython } from "@/core/codemirror/language/utils";
+import { prepareCellCodeUpdate } from "@/core/codemirror/language/cell-code";
import { cn } from "@/utils/cn";
import { Logger } from "@/utils/Logger";
import {
@@ -144,7 +144,15 @@ export function rejectStagedCell(
break;
}
- updateEditorCodeFromPython(editorView, edit.previousCode);
+ const update = prepareCellCodeUpdate(
+ editorView.state,
+ edit.previousCode,
+ { initialize: true },
+ );
+
+ if (update) {
+ editorView.dispatch(update);
+ }
removeStagedCell(cellId);
break;
}
diff --git a/frontend/src/components/editor/cell/code/cell-editor.tsx b/frontend/src/components/editor/cell/code/cell-editor.tsx
index 80e837d88d..03ad3c8646 100644
--- a/frontend/src/components/editor/cell/code/cell-editor.tsx
+++ b/frontend/src/components/editor/cell/code/cell-editor.tsx
@@ -24,10 +24,8 @@ import {
reconfigureLanguageEffect,
switchLanguage,
} from "@/core/codemirror/language/extension";
-import {
- getEditorCodeAsPython,
- updateEditorCodeFromPython,
-} from "@/core/codemirror/language/utils";
+import { prepareCellCodeUpdate } from "@/core/codemirror/language/cell-code";
+import { getEditorCodeAsPython } from "@/core/codemirror/language/utils";
import { MARKDOWN_INITIAL_HIDE_CODE } from "@/core/codemirror/language/languages/markdown";
import type { LanguageAdapterType } from "@/core/codemirror/language/types";
import {
@@ -253,7 +251,10 @@ const CellEditorInternal = ({
? `${existing.trimEnd()}\n\n${code}`
: code;
if (view) {
- updateEditorCodeFromPython(view, merged);
+ const update = prepareCellCodeUpdate(view.state, merged);
+ if (update) {
+ view.dispatch(update);
+ }
}
cellActions.updateCellCode({
cellId: SETUP_CELL_ID,
@@ -363,15 +364,7 @@ const CellEditorInternal = ({
return composeRtcEditorConfig(code, extensions, undefined);
}
- const rtc = realTimeCollaboration(
- cellId,
- (code) => {
- // It's not really a formatting change,
- // but this means it won't be marked as stale
- cellActions.updateCellCode({ cellId, code, formattingChange: true });
- },
- initialCode,
- );
+ const rtc = realTimeCollaboration(cellId, initialCode);
return composeRtcEditorConfig(code, extensions, rtc);
};
diff --git a/frontend/src/components/editor/chrome/wrapper/__tests__/document-sync-status.test.tsx b/frontend/src/components/editor/chrome/wrapper/__tests__/document-sync-status.test.tsx
new file mode 100644
index 0000000000..84cb951bb4
--- /dev/null
+++ b/frontend/src/components/editor/chrome/wrapper/__tests__/document-sync-status.test.tsx
@@ -0,0 +1,92 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { atom, createStore, Provider } from "jotai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TooltipProvider } from "@/components/ui/tooltip";
+import { createDocumentModel } from "@/core/notebook/document";
+import { document } from "@/core/notebook/document/__tests__/fixtures";
+import {
+ type FakeEdit,
+ fakeBackend,
+} from "@/core/notebook/replica/__tests__/fixtures";
+import { activeDocumentModelAtom } from "@/core/session/active-notebook";
+import { DocumentSyncStatus } from "../footer-items/document-sync-status";
+
+const lifetimes: AbortController[] = [];
+
+afterEach(() => {
+ act(() => lifetimes.splice(0).forEach((controller) => controller.abort()));
+});
+
+const conflict = {
+ ok: false as const,
+ status: 409,
+ problem: {
+ type: "tag:marimo.io,2026:host/conflict",
+ title: "Conflict",
+ status: 409,
+ detail: "cell c1 has changed since it was read.",
+ },
+};
+
+function setup(edit: FakeEdit) {
+ const store = createStore();
+ const model = createDocumentModel({
+ store,
+ documentAtom: atom(document()),
+ backendAtom: atom(fakeBackend({ edit })),
+ });
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
+ store.set(activeDocumentModelAtom, model);
+ render(
+ <Provider store={store}>
+ <TooltipProvider>
+ <DocumentSyncStatus />
+ </TooltipProvider>
+ </Provider>,
+ );
+ return { store, model };
+}
+
+describe("DocumentSyncStatus", () => {
+ it("renders nothing while edits reach the server", () => {
+ setup(vi.fn<FakeEdit>());
+ expect(screen.queryByTestId("footer-document-sync")).toBeNull();
+ });
+
+ it("shows a rejected edit and resubmits it on click", async () => {
+ const accepted = document().revision;
+ const edit = vi
+ .fn<FakeEdit>()
+ .mockResolvedValueOnce(conflict)
+ .mockResolvedValueOnce({
+ ok: true,
+ status: 200,
+ data: {
+ document: { ...accepted, version: 2, etag: "document-2" },
+ cells: {},
+ },
+ });
+ const { store, model } = setup(edit);
+
+ await act(async () => {
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "x = 2"));
+ await model.flush().catch(() => undefined);
+ });
+ const item = screen.getByTestId("footer-document-sync");
+ expect(item).toHaveAttribute(
+ "aria-label",
+ "Edits are not reaching the server",
+ );
+
+ await act(async () => {
+ fireEvent.click(item);
+ await Promise.resolve();
+ });
+ expect(edit).toHaveBeenCalledTimes(2);
+ expect(screen.queryByTestId("footer-document-sync")).toBeNull();
+ });
+});
diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/document-sync-status.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/document-sync-status.tsx
new file mode 100644
index 0000000000..c41f32106f
--- /dev/null
+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/document-sync-status.tsx
@@ -0,0 +1,54 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom, useAtomValue } from "jotai";
+import { AlertCircleIcon } from "lucide-react";
+import type React from "react";
+import { activeDocumentModelAtom } from "@/core/session/active-notebook";
+import { FooterItem } from "../footer-item";
+
+/** The active notebook's document sync status, or null without a model. */
+const syncStatusAtom = atom((get) => {
+ const model = get(activeDocumentModelAtom);
+ return model === null ? null : get(model.syncStatusAtom);
+});
+
+/**
+ * Shown when this client's edits stop reaching the server.
+ *
+ * Typing keeps working locally and Run still uses the editor's code, but
+ * other clients stop seeing the edits and Save fails until they are
+ * through. A rejected edit is retried on click.
+ */
+export const DocumentSyncStatus: React.FC = () => {
+ const model = useAtomValue(activeDocumentModelAtom);
+ const status = useAtomValue(syncStatusAtom);
+ if (model === null || status === null || status.status !== "error") {
+ return null;
+ }
+ const retry = status.retryable
+ ? () => {
+ // The status shows the outcome, so a failed retry needs no handling.
+ model.retry().catch(() => undefined);
+ }
+ : undefined;
+ const detail = status.problem?.detail ?? status.error.message;
+ return (
+ <FooterItem
+ tooltip={
+ <div className="w-[260px] space-y-1">
+ <div>Edits are not reaching the server.</div>
+ <div className="text-muted-foreground">{detail}</div>
+ <div>
+ {retry ? "Click to retry." : "Reload the page to continue."}
+ </div>
+ </div>
+ }
+ selected={false}
+ onClick={retry}
+ aria-label="Edits are not reaching the server"
+ data-testid="footer-document-sync"
+ >
+ <AlertCircleIcon className="w-4 h-4 text-destructive" />
+ </FooterItem>
+ );
+};
diff --git a/frontend/src/components/editor/chrome/wrapper/footer.tsx b/frontend/src/components/editor/chrome/wrapper/footer.tsx
index 572cdc115c..03e846ec5c 100644
--- a/frontend/src/components/editor/chrome/wrapper/footer.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/footer.tsx
@@ -18,6 +18,7 @@ import {
connectionStatusAtom,
} from "./footer-items/backend-status";
import { CopilotStatusIcon } from "./footer-items/copilot-status";
+import { DocumentSyncStatus } from "./footer-items/document-sync-status";
import { MachineStats } from "./footer-items/machine-stats";
import { PyodideStatus } from "./footer-items/pyodide-status";
import { RTCStatus } from "./footer-items/rtc-status";
@@ -107,6 +108,7 @@ export const Footer: React.FC = () => {
</ShowInKioskMode>
<div className="flex items-center shrink-0 min-w-0">
+ <DocumentSyncStatus />
<MachineStats />
<AttachmentStatus />
<AIStatusIcon />
diff --git a/frontend/src/core/ai/__tests__/staged-cells.test.ts b/frontend/src/core/ai/__tests__/staged-cells.test.ts
index 2b2301efcd..fcc921bbfe 100644
--- a/frontend/src/core/ai/__tests__/staged-cells.test.ts
+++ b/frontend/src/core/ai/__tests__/staged-cells.test.ts
@@ -7,7 +7,7 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
import { cellId } from "@/__tests__/branded";
import { CellId } from "@/core/cells/ids";
import { getCellEditorView } from "../../cells/cells";
-import { updateEditorCodeFromPython } from "../../codemirror/language/utils";
+import { prepareCellCodeUpdate } from "../../codemirror/language/cell-code";
import {
stagedAICellsAtom,
stagedGenerationInProgressAtom,
@@ -57,8 +57,8 @@ vi.mock("@/core/network/requests", () => ({
getRequestClient: () => ({ sendRun: vi.fn() }),
}));
-vi.mock("../../codemirror/language/utils", () => ({
- updateEditorCodeFromPython: vi.fn(),
+vi.mock("../../codemirror/language/cell-code", () => ({
+ prepareCellCodeUpdate: vi.fn(() => ({ effects: [] })),
}));
// Mock CellId.create
@@ -402,7 +402,7 @@ describe("staged cell generation", () => {
// No cell or cell update should have been called
expect(mockCreateNewCell).not.toHaveBeenCalled();
- expect(updateEditorCodeFromPython).not.toHaveBeenCalled();
+ expect(prepareCellCodeUpdate).not.toHaveBeenCalled();
expect(store.get(stagedGenerationInProgressAtom)).toBe(true);
});
@@ -686,7 +686,10 @@ describe("staged cell generation", () => {
expect(mockCreateNewCell).toHaveBeenCalledTimes(2);
expect(store.get(stagedAICellsAtom).has(cellId("first-cell"))).toBe(true);
expect(store.get(stagedAICellsAtom).has(cellId("second-cell"))).toBe(true);
- expect(updateEditorCodeFromPython).toHaveBeenCalledTimes(2);
+ expect(prepareCellCodeUpdate).toHaveBeenCalledTimes(2);
+ expect(
+ mockCellHandle.current.editorViewOrNull.dispatch,
+ ).toHaveBeenCalledTimes(2);
});
it("should update notebook state when the cell editor is not mounted", () => {
diff --git a/frontend/src/core/ai/staged-cells.ts b/frontend/src/core/ai/staged-cells.ts
index b339c7a7e8..82443ee3bb 100644
--- a/frontend/src/core/ai/staged-cells.ts
+++ b/frontend/src/core/ai/staged-cells.ts
@@ -19,7 +19,7 @@ import {
getCellEditorView,
useCellActions,
} from "../cells/cells";
-import { updateEditorCodeFromPython } from "../codemirror/language/utils";
+import { prepareCellCodeUpdate } from "../codemirror/language/cell-code";
import type { JotaiStore } from "../state/jotai";
import type { EditType } from "./tools/edit-notebook-tool";
@@ -124,7 +124,12 @@ export function useStagedCells(store: JotaiStore) {
const editorView = getCellEditorView(cellId);
if (editorView) {
- updateEditorCodeFromPython(editorView, code);
+ const update = prepareCellCodeUpdate(editorView.state, code, {
+ initialize: true,
+ });
+ if (update) {
+ editorView.dispatch(update);
+ }
} else {
updateCellCode({ cellId, code, formattingChange: false });
}
diff --git a/frontend/src/core/ai/tools/__tests__/edit-notebook-tool.test.ts b/frontend/src/core/ai/tools/__tests__/edit-notebook-tool.test.ts
index 11533e4e72..c9af4ca375 100644
--- a/frontend/src/core/ai/tools/__tests__/edit-notebook-tool.test.ts
+++ b/frontend/src/core/ai/tools/__tests__/edit-notebook-tool.test.ts
@@ -8,7 +8,6 @@ import { MockNotebook } from "@/__mocks__/notebook";
import { cellId } from "@/__tests__/branded";
import { notebookAtom } from "@/core/cells/cells";
import type { CellId } from "@/core/cells/ids";
-import { updateEditorCodeFromPython } from "@/core/codemirror/language/utils";
import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
import { MultiColumn } from "@/utils/id-tree";
import { cellConfigExtension } from "../../../codemirror/config/extension";
@@ -22,11 +21,6 @@ vi.mock("@/components/editor/links/cell-link", () => ({
scrollAndHighlightCell: vi.fn(),
}));
-// Mock updateEditorCodeFromPython
-vi.mock("@/core/codemirror/language/utils", () => ({
- updateEditorCodeFromPython: vi.fn(),
-}));
-
function createMockEditorView(code: string): EditorView {
return new EditorView({
state: EditorState.create({
@@ -140,10 +134,7 @@ describe("EditNotebookTool", () => {
);
expect(result.status).toBe("success");
- expect(vi.mocked(updateEditorCodeFromPython)).toHaveBeenCalledWith(
- editorView,
- newCode,
- );
+ expect(editorView.state.doc.toString()).toBe(newCode);
// Check that cell was staged
const stagedCells = store.get(stagedAICellsAtom);
@@ -166,10 +157,7 @@ describe("EditNotebookTool", () => {
);
expect(result2.status).toBe("success");
- expect(vi.mocked(updateEditorCodeFromPython)).toHaveBeenCalledWith(
- editorView,
- "x = 3",
- );
+ expect(editorView.state.doc.toString()).toBe("x = 3");
const stagedCells2 = store.get(stagedAICellsAtom);
expect(stagedCells2.has(cellId1)).toBe(true);
@@ -206,7 +194,7 @@ describe("EditNotebookTool", () => {
// Should NOT stage the cell or update the editor
expect(toolContext.addStagedCell).not.toHaveBeenCalled();
- expect(vi.mocked(updateEditorCodeFromPython)).not.toHaveBeenCalled();
+ expect(editorView.state.doc.toString()).toBe(code);
// No staged cells
const stagedCells = store.get(stagedAICellsAtom);
diff --git a/frontend/src/core/ai/tools/edit-notebook-tool.ts b/frontend/src/core/ai/tools/edit-notebook-tool.ts
index 76f76df594..cde445763b 100644
--- a/frontend/src/core/ai/tools/edit-notebook-tool.ts
+++ b/frontend/src/core/ai/tools/edit-notebook-tool.ts
@@ -9,7 +9,7 @@ import {
notebookAtom,
} from "@/core/cells/cells";
import { CellId } from "@/core/cells/ids";
-import { updateEditorCodeFromPython } from "@/core/codemirror/language/utils";
+import { prepareCellCodeUpdate } from "@/core/codemirror/language/cell-code";
import type { CellColumnId } from "@/utils/id-tree";
import { stagedAICellsAtom } from "../staged-cells";
import {
@@ -117,7 +117,12 @@ export class EditNotebookTool implements AiTool<
// If previous edit was from a new cell, just replace editor code with the new code
if (existingStagedCell?.type === "add_cell") {
- updateEditorCodeFromPython(editorView, code);
+ const update = prepareCellCodeUpdate(editorView.state, code, {
+ initialize: true,
+ });
+ if (update) {
+ editorView.dispatch(update);
+ }
break;
}
@@ -137,7 +142,13 @@ export class EditNotebookTool implements AiTool<
edit: { type: "update_cell", previousCode: previousCode },
});
- updateEditorCodeFromPython(editorView, code);
+ const update = prepareCellCodeUpdate(editorView.state, code, {
+ initialize: true,
+ });
+
+ if (update) {
+ editorView.dispatch(update);
+ }
break;
}
diff --git a/frontend/src/core/cells/__tests__/apply-transaction.test.ts b/frontend/src/core/cells/__tests__/apply-transaction.test.ts
deleted file mode 100644
index c290bb5de1..0000000000
--- a/frontend/src/core/cells/__tests__/apply-transaction.test.ts
+++ /dev/null
@@ -1,991 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-/**
- * Tests for fromDocumentChanges / applyTransactionChanges in isolation.
- *
- * These test the change→action mapping for edge cases and error paths that
- * can't be exercised via the round-trip tests (since toDocumentChanges would
- * never produce malformed or conflicting changes). Basic correctness is
- * covered by document-roundtrip.test.ts. This file focuses on:
- *
- * - Multi-change transactions (create+move, create+set-code, set-code+delete)
- * - Cancelled changes (create+delete same cell)
- * - Missing/nonexistent anchors and cells
- * - Config propagation on create-cell (disabled, column)
- */
-
-import { python } from "@codemirror/lang-python";
-import { EditorState } from "@codemirror/state";
-import { EditorView } from "@codemirror/view";
-import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
-import { cellId } from "@/__tests__/branded";
-import type { CellHandle } from "@/components/editor/notebook-cell";
-import { adaptiveLanguageConfiguration } from "@/core/codemirror/language/extension";
-import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
-import { MultiColumn } from "@/utils/id-tree";
-import { exportedForTesting, type NotebookState } from "../cells";
-import {
- applyTransactionChanges,
- exportedForTesting as middlewareExports,
-} from "../document-changes";
-import { CellId } from "../ids";
-
-const { initialNotebookState, reducer, createActions } = exportedForTesting;
-
-function createEditor(code: string) {
- const state = EditorState.create({
- doc: code,
- extensions: [
- python(),
- adaptiveLanguageConfiguration({
- cellId: "cell1" as CellId,
- completionConfig: {
- activate_on_typing: true,
- signature_hint_on_typing: false,
- copilot: false,
- codeium_api_key: null,
- },
- hotkeys: new OverridingHotkeyProvider({}),
- placeholderType: "marimo-import",
- lspConfig: {},
- }),
- ],
- });
- return new EditorView({ state, parent: document.body });
-}
-
-let state: NotebookState;
-let actions: ReturnType<typeof createActions>;
-
-function setup(...codes: string[]) {
- state = initialNotebookState();
- state.cellIds = MultiColumn.from([]);
- actions = createActions((action) => {
- state = reducer(state, action);
- for (const [cellId, handle] of Object.entries(state.cellHandles)) {
- if (!handle.current) {
- const view = createEditor(state.cellData[cellId as CellId].code);
- const h: CellHandle = { editorView: view, editorViewOrNull: view };
- state.cellHandles[cellId as CellId] = { current: h };
- }
- }
- });
- for (const code of codes) {
- actions.createNewCell({ cellId: "__end__", before: false, code });
- }
-}
-
-afterEach(() => {
- middlewareExports.cancelPendingChanges();
-});
-
-function apply(changes: Parameters<typeof applyTransactionChanges>[0]) {
- applyTransactionChanges(changes, actions, () => state.cellIds.inOrderIds);
-}
-
-/** Snapshot of document state: ordering, code, name, config. */
-function pretty(s: NotebookState): string {
- const lines = s.cellIds.inOrderIds.map((id) => {
- const cell = s.cellData[id];
- const flags: string[] = [];
- if (cell.name && cell.name !== "_") {
- flags.push(`name=${cell.name}`);
- }
- if (cell.config.hide_code) {
- flags.push("hide_code");
- }
- if (cell.config.disabled) {
- flags.push("disabled");
- }
- if (cell.config.column != null) {
- flags.push(`col=${cell.config.column}`);
- }
- const suffix = flags.length > 0 ? ` [${flags.join(", ")}]` : "";
- return `${id}: '${cell.code}'${suffix}`;
- });
- return `\n${lines.join("\n")}\n`;
-}
-
-/** Snapshot showing the physical column grouping in the MultiColumn tree. */
-function prettyColumns(s: NotebookState): string {
- const lines = s.cellIds
- .getColumns()
- .map((col, idx) => `col${idx}: [${col.inOrderIds.join(", ")}]`);
- return `\n${lines.join("\n")}\n`;
-}
-
-let i = 0;
-
-beforeAll(() => {
- CellId.create = () => `${i++}` as CellId;
-});
-
-beforeEach(() => {
- i = 0;
-});
-
-describe("applyTransactionChanges edge cases", () => {
- it("create-cell applies disabled and column config", () => {
- setup("a");
- apply([
- {
- type: "create-cell",
- cellId: cellId("new-cell"),
- code: "configured",
- name: "",
- config: { hide_code: true, disabled: true, column: 1 },
- },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- new-cell: 'configured' [hide_code, disabled, col=1]
- "
- `);
- // The new cell must physically land in the second column, not just
- // carry col=1 as stale metadata.
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0]
- col1: [new-cell]
- "
- `);
- });
-
- it("create-cell then move-cell in same transaction", () => {
- setup("a", "b");
- const [a] = state.cellIds.inOrderIds;
- apply([
- {
- type: "create-cell",
- cellId: cellId("new-cell"),
- code: "new",
- name: "",
- config: {},
- },
- { type: "move-cell", cellId: cellId("new-cell"), before: a },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- new-cell: 'new'
- 0: 'a'
- 1: 'b'
- "
- `);
- });
-
- it("create-cell then set-code in same transaction", () => {
- setup("a");
- apply([
- {
- type: "create-cell",
- cellId: cellId("new-cell"),
- code: "initial",
- name: "",
- config: {},
- },
- { type: "set-code", cellId: cellId("new-cell"), code: "updated" },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- new-cell: 'updated'
- "
- `);
- });
-
- it("create-cell then delete-cell same cell cancels out", () => {
- setup("a");
- apply([
- {
- type: "create-cell",
- cellId: cellId("ephemeral"),
- code: "tmp",
- name: "",
- config: {},
- },
- { type: "delete-cell", cellId: cellId("ephemeral") },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- "
- `);
- });
-
- it("multiple changes in one transaction", () => {
- setup("a", "b", "c");
- const [a, b, c] = state.cellIds.inOrderIds;
- apply([
- { type: "set-code", cellId: a, code: "x = 1" },
- { type: "set-name", cellId: b, name: "middle" },
- { type: "delete-cell", cellId: c },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'x = 1'
- 1: 'b' [name=middle]
- "
- `);
- });
-
- it("move-cell with no anchor appends to end", () => {
- setup("a", "b", "c");
- const [a] = state.cellIds.inOrderIds;
- apply([{ type: "move-cell", cellId: a }]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 1: 'b'
- 2: 'c'
- 0: 'a'
- "
- `);
- });
-
- it("move-cell with missing after anchor falls back to end", () => {
- setup("a", "b");
- const [a] = state.cellIds.inOrderIds;
- apply([{ type: "move-cell", cellId: a, after: cellId("nonexistent") }]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 1: 'b'
- 0: 'a'
- "
- `);
- });
-
- it("move-cell with missing before anchor falls back to start", () => {
- setup("a", "b");
- const [, b] = state.cellIds.inOrderIds;
- apply([{ type: "move-cell", cellId: b, before: cellId("nonexistent") }]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 1: 'b'
- 0: 'a'
- "
- `);
- });
-
- it("move-cell on nonexistent cell is a no-op", () => {
- setup("a", "b");
- apply([
- {
- type: "move-cell",
- cellId: cellId("nonexistent"),
- after: cellId("0"),
- },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- 1: 'b'
- "
- `);
- });
-
- it("delete-cell for nonexistent cell does not crash subsequent changes", () => {
- setup("a", "b", "c");
- const [, b] = state.cellIds.inOrderIds;
- // Simulate the scenario from the bug report: a delete-cell for a cell ID
- // that was never added to the frontend, followed by a create-cell and
- // a set-code update. The delete should be silently skipped, and the rest
- // of the transaction should still apply.
- apply([
- { type: "delete-cell", cellId: cellId("nonexistent") },
- {
- type: "create-cell",
- cellId: cellId("VrZA"),
- code: "import altair as alt",
- name: "",
- config: { hide_code: true },
- },
- { type: "set-code", cellId: b, code: "updated" },
- ]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- 1: 'updated'
- 2: 'c'
- VrZA: 'import altair as alt' [hide_code]
- "
- `);
- });
-
- it("empty changes is a no-op", () => {
- setup("a", "b");
- apply([]);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- 1: 'b'
- "
- `);
- });
-
- it("set-code updates the mounted editor view's document", () => {
- // Existing tests only check cellData.code — this covers the editor
- // view side, so regressions in the reducer's imperative sync (or in
- // the CellEditor useEffect that backs it up) don't go unnoticed.
- setup('x = "BEFORE"');
- const [a] = state.cellIds.inOrderIds;
- const editorView = state.cellHandles[a].current?.editorViewOrNull;
- expect(editorView?.state.doc.toString()).toBe('x = "BEFORE"');
-
- apply([{ type: "set-code", cellId: a, code: 'x = "AFTER"' }]);
-
- expect(state.cellData[a].code).toBe('x = "AFTER"');
- expect(editorView?.state.doc.toString()).toBe('x = "AFTER"');
- });
-
- it("create-cell then set-code on same cell updates editor", () => {
- // Mirrors the code_mode flow that exposed marimo-pair#27: create_cell
- // in one batch, edit_cell in a second batch, each arriving as a
- // separate transaction.
- setup();
- apply([
- {
- type: "create-cell",
- cellId: cellId("repro"),
- code: 'x = "BEFORE"',
- name: "repro_bug",
- config: {},
- },
- ]);
- const editorView =
- state.cellHandles[cellId("repro")].current?.editorViewOrNull;
- expect(editorView?.state.doc.toString()).toBe('x = "BEFORE"');
-
- apply([
- { type: "set-code", cellId: cellId("repro"), code: 'x = "AFTER"' },
- { type: "reorder-cells", cellIds: [cellId("repro")] },
- ]);
-
- expect(state.cellData[cellId("repro")].code).toBe('x = "AFTER"');
- expect(editorView?.state.doc.toString()).toBe('x = "AFTER"');
- });
-});
-
-describe("applyTransactionChanges column rebuild", () => {
- it("boundary anchors: set-config on column boundaries splits cells into columns", () => {
- // The user's exact example. Server sends a reorder + set-config only on
- // the cells at column boundaries. The replica must infer that the cells
- // in between inherit the column of the preceding anchor.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- });
-
- it("boundary anchors on reordered cells: order follows reorder-cells", () => {
- // Start from a single column, reorder the cells and split at c.
- // The rebuild must use the new flat order from reorder-cells so that
- // b ends up next to a (col 0) and d ends up next to c (col 1).
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [d, a, c, b] },
- {
- type: "set-config",
- cellId: d,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [3, 0]
- col1: [2, 1]
- "
- `);
- });
-
- it("three columns: inherits column through consecutive cells", () => {
- setup("a", "b", "c", "d", "e", "f");
- const [a, b, c, d, e, f] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d, e, f] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: e,
- column: 2,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- col2: [4, 5]
- "
- `);
- });
-
- it("every cell explicitly tagged with a column", () => {
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: b,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: d,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- // a and c in col0; b and d in col1. Order within each column follows
- // the reorder-cells order.
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 2]
- col1: [1, 3]
- "
- `);
- });
-
- it("set-config without reorder-cells moves the cell to the new column", () => {
- setup("a", "b", "c");
- const [, b] = state.cellIds.inOrderIds;
- apply([
- {
- type: "set-config",
- cellId: b,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- // Without reorder-cells, the flat order comes from the current tree.
- // b gets explicit col=1; a and c stay with default null → follow the
- // previous cell's column (a → col0 because prev=0; c → col1 because
- // prev was just set to 1 by b).
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0]
- col1: [1, 2]
- "
- `);
- });
-
- it("no column change: set-config only touching other fields does not repartition", () => {
- setup("a", "b", "c");
- const [, b] = state.cellIds.inOrderIds;
- apply([
- {
- type: "set-config",
- cellId: b,
- column: null,
- disabled: false,
- hideCode: true,
- expandOutput: false,
- },
- ]);
- // All three cells remain in a single column. No rebuild triggered.
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1, 2]
- "
- `);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- 1: 'b' [hide_code]
- 2: 'c'
- "
- `);
- });
-
- it("no changes: empty transaction leaves column structure alone", () => {
- // Setup a multi-column state first
- setup("a", "b");
- const [a, b] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: b,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0]
- col1: [1]
- "
- `);
- // Now apply no changes — column structure should be preserved.
- apply([]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0]
- col1: [1]
- "
- `);
- });
-
- it("merging columns: set-config col=0 for everything collapses to one column", () => {
- // Start in a multi-column state.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- // Now merge everything back to col 0.
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: c,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: d,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1, 2, 3]
- "
- `);
- });
-
- it("create-cell with column places cell in correct column", () => {
- setup("a", "b");
- const [, b] = state.cellIds.inOrderIds;
- apply([
- {
- type: "create-cell",
- cellId: cellId("fresh"),
- code: "x",
- name: "",
- config: { column: 1 },
- after: b,
- },
- ]);
- // a and b are in col 0 (unchanged). The new cell is created at the end
- // with column=1, so it should land physically in col 1.
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [fresh]
- "
- `);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'a'
- 1: 'b'
- fresh: 'x' [col=1]
- "
- `);
- });
-
- it("multi-change transaction with column + code + name updates", () => {
- setup("a", "b", "c");
- const [a, b, c] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c] },
- { type: "set-code", cellId: a, code: "x = 1" },
- { type: "set-name", cellId: b, name: "middle" },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: b,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0]
- col1: [1, 2]
- "
- `);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'x = 1' [col=0]
- 1: 'b' [name=middle, col=1]
- 2: 'c'
- "
- `);
- });
-
- it("cancelled create+delete does not trigger column rebuild", () => {
- setup("a", "b");
- apply([
- {
- type: "create-cell",
- cellId: cellId("ephemeral"),
- code: "tmp",
- name: "",
- config: { column: 1 },
- },
- { type: "delete-cell", cellId: cellId("ephemeral") },
- ]);
- // The create+delete cancel out. The column metadata on the cancelled
- // create-cell shouldn't cause a spurious column rebuild.
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- "
- `);
- });
-
- it("boundary-anchor convention: moving an anchor pulls non-anchored followers", () => {
- // This documents the boundary-anchor convention used by the server: only
- // cells at column boundaries carry an explicit column. Non-anchor cells
- // have config.column=null and inherit the column of the previous cell.
- // That means moving an anchor also moves its silent followers.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- // Split into two columns. Only a and c are anchors.
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- // Move the c anchor to col 0. d has no explicit column so it follows c.
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: c,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1, 2, 3]
- "
- `);
- });
-
- it("explicit anchors on followers: move anchor leaves explicitly-tagged follower behind", () => {
- // Contrast with the previous test: if d is explicitly tagged col=1,
- // moving c back to col 0 should leave d in col 1.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: d,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- // Move c back to col 0. Because d has its own explicit column=1, it
- // does NOT follow c.
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: c,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1, 2]
- col1: [3]
- "
- `);
- });
-
- it("set-config before reorder-cells: processing is sorted so set-config runs last", () => {
- // Defensive test: even if a transaction has set-config *before*
- // reorder-cells, the implementation must process reorder-cells first so
- // that the column rebuild sees the intended final flat order. This
- // matches the order the backend plans transactions in.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- // set-config appears FIRST in the transaction.
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- // reorder-cells comes afterwards.
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- ]);
- // Result must be identical to the canonical order:
- // the tree is reshaped first, then column metadata is applied.
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- });
-
- it("set-config interleaved between other changes is still run last", () => {
- // Another ordering variant: set-config interleaved between set-code and
- // reorder-cells. Our sort must move set-config to the end regardless of
- // position, while preserving the relative order of the other changes.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- { type: "set-code", cellId: a, code: "x = 1" },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- { type: "set-name", cellId: d, name: "last" },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- expect(pretty(state)).toMatchInlineSnapshot(`
- "
- 0: 'x = 1' [col=0]
- 1: 'b'
- 2: 'c' [col=1]
- 3: 'd' [name=last]
- "
- `);
- });
-
- it("reorder-cells alone (no column changes) preserves existing columns", () => {
- // Start in a two-column state.
- setup("a", "b", "c", "d");
- const [a, b, c, d] = state.cellIds.inOrderIds;
- apply([
- { type: "reorder-cells", cellIds: [a, b, c, d] },
- {
- type: "set-config",
- cellId: a,
- column: 0,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- {
- type: "set-config",
- cellId: c,
- column: 1,
- disabled: false,
- hideCode: false,
- expandOutput: false,
- },
- ]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [0, 1]
- col1: [2, 3]
- "
- `);
- // Now reorder without any column changes. The rebuild must NOT fire.
- // setCellIds with fromWithPreviousShape preserves the column assignments.
- apply([{ type: "reorder-cells", cellIds: [b, a, d, c] }]);
- expect(prettyColumns(state)).toMatchInlineSnapshot(`
- "
- col0: [1, 0]
- col1: [3, 2]
- "
- `);
- });
-});
diff --git a/frontend/src/core/cells/__tests__/cells.test.ts b/frontend/src/core/cells/__tests__/cells.test.ts
index e21487f05f..9105763b81 100644
--- a/frontend/src/core/cells/__tests__/cells.test.ts
+++ b/frontend/src/core/cells/__tests__/cells.test.ts
@@ -6,7 +6,6 @@ import { EditorView } from "@codemirror/view";
import { createStore } from "jotai";
import {
afterAll,
- afterEach,
beforeAll,
beforeEach,
describe,
@@ -34,7 +33,6 @@ import {
type NotebookState,
notebookAtom,
} from "../cells";
-import { exportedForTesting as documentTransactionTestExports } from "../document-changes";
import {
focusAndScrollCellIntoView,
scrollToBottom,
@@ -156,10 +154,6 @@ describe("cell reducer", () => {
firstCellId = state.cellIds.inOrderIds[0];
});
- afterEach(() => {
- documentTransactionTestExports.cancelPendingChanges();
- });
-
afterAll(() => {
CellId.create = originalCreate;
});
@@ -1761,187 +1755,6 @@ describe("cell reducer", () => {
expect(state.cellData[firstCellId].name).toBe("Test Cell");
});
- it("can set cell IDs and codes", () => {
- const newIds = [cellId("3"), cellId("4"), cellId("5")];
- const newCodes = ["code1", "code2", "code3"];
-
- actions.setCellIds({ cellIds: newIds });
- expect(state.cellIds.atOrThrow(FIRST_COLUMN).topLevelIds).toEqual(newIds);
-
- // When codeIsStale is false, lastCodeRun should match code
- actions.setCellCodes({
- codes: newCodes,
- ids: newIds,
- codeIsStale: false,
- });
- newIds.forEach((id, index) => {
- expect(state.cellData[id].code).toBe(newCodes[index]);
- expect(state.cellData[id].lastCodeRun).toBe(newCodes[index]);
- expect(state.cellData[id].edited).toBe(false);
- });
-
- // When codeIsStale is true, lastCodeRun should not change
- const staleCodes = ["stale1", "stale2", "stale3"];
- actions.setCellCodes({
- codes: staleCodes,
- ids: newIds,
- codeIsStale: true,
- });
- newIds.forEach((id, index) => {
- expect(state.cellData[id].code).toBe(staleCodes[index]);
- expect(state.cellData[id].lastCodeRun).toBe(newCodes[index]);
- expect(state.cellData[id].edited).toBe(true);
- });
- });
-
- it("can can add a new cell with/without stale code", () => {
- actions.setCellCodes({
- codes: ["new code"],
- ids: [cellId("2")],
- codeIsStale: false,
- });
-
- expect(state.cellData[cellId("2")].code).toBe("new code");
- expect(state.cellData[cellId("2")].edited).toBe(false);
- expect(state.cellData[cellId("2")].lastCodeRun).toBe("new code");
-
- actions.setCellCodes({
- codes: ["new code 2"],
- ids: [cellId("9")],
- codeIsStale: true,
- });
-
- expect(state.cellData[cellId("9")].code).toBe("new code 2");
- expect(state.cellData[cellId("9")].edited).toBe(true);
- expect(state.cellData[cellId("9")].lastCodeRun).toBe(null);
- });
-
- it("can partial update cell codes", () => {
- actions.createNewCell({ cellId: firstCellId, before: false });
- actions.createNewCell({ cellId: cellId("1"), before: false });
-
- expect(state.cellIds.inOrderIds).toEqual([
- cellId("0"),
- cellId("1"),
- cellId("2"),
- ]);
- expect(state.cellData[cellId("0")].code).toBe("");
- expect(state.cellData[cellId("1")].code).toBe("");
- expect(state.cellData[cellId("2")].code).toBe("");
-
- // Update cell 1
- actions.setCellCodes({
- codes: ["new code 2"],
- ids: [cellId("1")],
- codeIsStale: false,
- });
-
- expect(state.cellIds.inOrderIds).toEqual([
- cellId("0"),
- cellId("1"),
- cellId("2"),
- ]);
- expect(state.cellData[cellId("0")].code).toBe("");
- expect(state.cellData[cellId("1")].code).toBe("new code 2");
- expect(state.cellData[cellId("1")].edited).toBe(false);
- expect(state.cellData[cellId("2")].code).toBe("");
- });
-
- it("can set cell codes with new cell ids, while preserving the old cell data", () => {
- actions.setCellCodes({
- codes: ["code1", "code2", "code3"],
- ids: [cellId("3"), cellId("4"), cellId("5")],
- codeIsStale: false,
- });
- expect(state.cellData[cellId("3")].code).toBe("code1");
- expect(state.cellData[cellId("4")].code).toBe("code2");
- expect(state.cellData[cellId("5")].code).toBe("code3");
-
- // Update with some new cell ids and some old cell ids
- actions.setCellIds({
- cellIds: [cellId("1"), cellId("2"), cellId("3"), cellId("4")],
- });
- actions.setCellCodes({
- codes: ["new1", "new2", "code1", "code2"],
- ids: [cellId("1"), cellId("2"), cellId("3"), cellId("4")],
- codeIsStale: false,
- });
- expect(state.cellData[cellId("1")].code).toBe("new1");
- expect(state.cellData[cellId("2")].code).toBe("new2");
- expect(state.cellData[cellId("3")].code).toBe("code1");
- expect(state.cellData[cellId("4")].code).toBe("code2");
- expect(state.cellIds.inOrderIds).toEqual([
- cellId("1"),
- cellId("2"),
- cellId("3"),
- cellId("4"),
- ]);
- // Cell 5 data is preserved (possibly used for tracing), but it's not in the cellIds
- expect(state.cellData[cellId("5")]).not.toBeUndefined();
- });
-
- it("can set cell codes with names and configs", () => {
- const newIds = [cellId("3"), cellId("4")];
- actions.setCellIds({ cellIds: newIds });
- actions.setCellCodes({
- codes: ["code1", "code2"],
- ids: newIds,
- codeIsStale: false,
- names: ["setup_cell", "analysis"],
- configs: [
- { hide_code: true, disabled: false, column: null },
- { hide_code: false, disabled: true, column: null },
- ],
- });
-
- expect(state.cellData[cellId("3")].name).toBe("setup_cell");
- expect(state.cellData[cellId("3")].config.hide_code).toBe(true);
- expect(state.cellData[cellId("3")].config.disabled).toBe(false);
-
- expect(state.cellData[cellId("4")].name).toBe("analysis");
- expect(state.cellData[cellId("4")].config.hide_code).toBe(false);
- expect(state.cellData[cellId("4")].config.disabled).toBe(true);
- });
-
- it("can set cell codes without names/configs (backward compat)", () => {
- const newIds = [cellId("3")];
- actions.setCellIds({ cellIds: newIds });
- actions.setCellCodes({
- codes: ["code1"],
- ids: newIds,
- codeIsStale: false,
- });
-
- // Should use defaults when names/configs not provided
- expect(state.cellData[cellId("3")].code).toBe("code1");
- expect(state.cellData[cellId("3")].config.hide_code).toBe(false);
- expect(state.cellData[cellId("3")].config.disabled).toBe(false);
- });
-
- it("can update names and configs on existing cells via setCellCodes", () => {
- // Set initial state
- actions.setCellCodes({
- codes: ["x = 1"],
- ids: [firstCellId],
- codeIsStale: false,
- names: ["old_name"],
- configs: [{ hide_code: false, disabled: false, column: null }],
- });
- expect(state.cellData[firstCellId].name).toBe("old_name");
- expect(state.cellData[firstCellId].config.hide_code).toBe(false);
-
- // Update with new name and config (same code)
- actions.setCellCodes({
- codes: ["x = 1"],
- ids: [firstCellId],
- codeIsStale: true,
- names: ["new_name"],
- configs: [{ hide_code: true, disabled: false, column: null }],
- });
- expect(state.cellData[firstCellId].name).toBe("new_name");
- expect(state.cellData[firstCellId].config.hide_code).toBe(true);
- });
-
it("can fold and unfold all cells", () => {
actions.foldAll();
expect(foldAllBulk).toHaveBeenCalled();
@@ -2632,116 +2445,6 @@ describe("cell reducer", () => {
expect(state.cellIds.getColumns()[2].topLevelIds).toEqual([cellId("2")]);
});
- it("rebuildCellColumns regroups cells by config.column", () => {
- // Create four cells in a single column.
- actions.createNewCell({ cellId: firstCellId, before: false });
- actions.createNewCell({ cellId: cellId("1"), before: false });
- actions.createNewCell({ cellId: cellId("2"), before: false });
- expect(state.cellIds.getColumns().length).toBe(1);
-
- // Explicitly set config.column on each cell. This ONLY updates metadata —
- // updateCellConfig does not touch the MultiColumn tree.
- actions.updateCellConfig({
- cellId: cellId("0"),
- config: { column: 0 },
- });
- actions.updateCellConfig({
- cellId: cellId("2"),
- config: { column: 1 },
- });
-
- // Tree is still a single column at this point.
- expect(state.cellIds.getColumns().length).toBe(1);
-
- // Now rebuild the column tree from metadata.
- actions.rebuildCellColumns({
- cellIds: [cellId("0"), cellId("1"), cellId("2"), cellId("3")],
- });
-
- expect(state.cellIds.getColumns().length).toBe(2);
- // Cell 1 inherits from 0 (col 0), cell 3 inherits from 2 (col 1).
- expect(state.cellIds.getColumns()[0].topLevelIds).toEqual([
- cellId("0"),
- cellId("1"),
- ]);
- expect(state.cellIds.getColumns()[1].topLevelIds).toEqual([
- cellId("2"),
- cellId("3"),
- ]);
- });
-
- it("rebuildCellColumns with explicit column on every cell", () => {
- actions.createNewCell({ cellId: firstCellId, before: false });
- actions.createNewCell({ cellId: cellId("1"), before: false });
- actions.createNewCell({ cellId: cellId("2"), before: false });
-
- for (const [id, col] of [
- ["0", 1],
- ["1", 0],
- ["2", 1],
- ["3", 0],
- ] as const) {
- actions.updateCellConfig({ cellId: cellId(id), config: { column: col } });
- }
-
- actions.rebuildCellColumns({
- cellIds: [cellId("0"), cellId("1"), cellId("2"), cellId("3")],
- });
-
- expect(state.cellIds.getColumns().length).toBe(2);
- expect(state.cellIds.getColumns()[0].topLevelIds).toEqual([
- cellId("1"),
- cellId("3"),
- ]);
- expect(state.cellIds.getColumns()[1].topLevelIds).toEqual([
- cellId("0"),
- cellId("2"),
- ]);
- });
-
- it("rebuildCellColumns collapses to one column when all cells are col 0", () => {
- actions.createNewCell({ cellId: firstCellId, before: false });
- actions.addColumnBreakpoint({ cellId: cellId("1") });
- expect(state.cellIds.getColumns().length).toBe(2);
-
- // Wipe column metadata back to 0 for both cells.
- actions.updateCellConfig({ cellId: cellId("0"), config: { column: 0 } });
- actions.updateCellConfig({ cellId: cellId("1"), config: { column: 0 } });
-
- actions.rebuildCellColumns({
- cellIds: [cellId("0"), cellId("1")],
- });
-
- expect(state.cellIds.getColumns().length).toBe(1);
- expect(state.cellIds.getColumns()[0].topLevelIds).toEqual([
- cellId("0"),
- cellId("1"),
- ]);
- });
-
- it("rebuildCellColumns follows the provided order, not current tree order", () => {
- // Start with a single column.
- actions.createNewCell({ cellId: firstCellId, before: false });
- actions.createNewCell({ cellId: cellId("1"), before: false });
- actions.updateCellConfig({ cellId: cellId("0"), config: { column: 0 } });
- actions.updateCellConfig({ cellId: cellId("2"), config: { column: 1 } });
-
- // Pass the reversed order. The rebuild should honor it.
- actions.rebuildCellColumns({
- cellIds: [cellId("2"), cellId("1"), cellId("0")],
- });
-
- // cellIds iteration:
- // 2 → col=1, pushed to col1, prev=1
- // 1 → col=null, pushed to col[prev=1] = col1
- // 0 → col=0, pushed to col0
- expect(state.cellIds.getColumns()[0].topLevelIds).toEqual([cellId("0")]);
- expect(state.cellIds.getColumns()[1].topLevelIds).toEqual([
- cellId("2"),
- cellId("1"),
- ]);
- });
-
it("can clear output of a single cell", () => {
// Set up initial state with output
actions.handleCellMessage({
diff --git a/frontend/src/core/cells/__tests__/document-changes.test.ts b/frontend/src/core/cells/__tests__/document-changes.test.ts
deleted file mode 100644
index 3af4230667..0000000000
--- a/frontend/src/core/cells/__tests__/document-changes.test.ts
+++ /dev/null
@@ -1,1140 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-/**
- * Tests for toDocumentChanges (action → change mapping) as a pure function.
- *
- * Each test calls the reducer to produce prevState/newState, then calls
- * toDocumentChanges directly — no middleware, no side effects. Basic round-trip
- * correctness is covered by document-roundtrip.test.ts. This file focuses on:
- *
- * - anchorOf edge cases (before vs after, first cell, __end__)
- * - Field name mapping (hide_code → hideCode)
- * - Column structure actions emitting reorder-cells
- * - Actions that should NOT emit changes
- */
-
-import { python } from "@codemirror/lang-python";
-import { EditorState } from "@codemirror/state";
-import { EditorView } from "@codemirror/view";
-import {
- afterAll,
- afterEach,
- beforeAll,
- beforeEach,
- describe,
- expect,
- it,
- vi,
-} from "vitest";
-import { cellId } from "@/__tests__/branded";
-import type { CellHandle } from "@/components/editor/notebook-cell";
-import { adaptiveLanguageConfiguration } from "@/core/codemirror/language/extension";
-import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
-import { requestClientAtom } from "@/core/network/requests";
-import type { EditRequests, RunRequests } from "@/core/network/types";
-import { store } from "@/core/state/jotai";
-import { Deferred } from "@/utils/Deferred";
-import { MultiColumn } from "@/utils/id-tree";
-import { exportedForTesting, type NotebookState } from "../cells";
-import {
- type CellAction,
- abortDocumentResync,
- beginDocumentResync,
- coalesceChanges,
- completeDocumentResync,
- type DocumentChange,
- flushDocumentChanges,
- exportedForTesting as middlewareExports,
- toDocumentChanges,
- withDocumentSave,
-} from "../document-changes";
-import { CellId } from "../ids";
-
-const { initialNotebookState, reducer } = exportedForTesting;
-
-function createEditor(code: string) {
- const state = EditorState.create({
- doc: code,
- extensions: [
- python(),
- adaptiveLanguageConfiguration({
- cellId: cellId("cell1"),
- completionConfig: {
- activate_on_typing: true,
- signature_hint_on_typing: false,
- copilot: false,
- codeium_api_key: null,
- },
- hotkeys: new OverridingHotkeyProvider({}),
- placeholderType: "marimo-import",
- lspConfig: {},
- }),
- ],
- });
- return new EditorView({ state, parent: document.body });
-}
-
-/** Dispatch an action through the reducer and auto-create editor handles. */
-function dispatch(state: NotebookState, action: CellAction): NotebookState {
- const next = reducer(state, action);
- for (const [cellIdString, handle] of Object.entries(next.cellHandles)) {
- const cid = cellIdString as CellId;
- if (!handle.current) {
- const view = createEditor(next.cellData[cid].code);
- const h: CellHandle = { editorView: view, editorViewOrNull: view };
- next.cellHandles[cid] = { current: h };
- }
- }
- return next;
-}
-
-/** Dispatch an action and return the changes it produces. */
-function resolve(state: NotebookState, action: CellAction) {
- const next = dispatch(state, action);
- const changes = toDocumentChanges(state, next, action);
- return { next, changes };
-}
-
-let state: NotebookState;
-
-let i = 0;
-const originalCreate = CellId.create.bind(CellId);
-
-beforeAll(() => {
- CellId.create = () => cellId(`${i++}`);
-});
-
-beforeEach(() => {
- i = 0;
- state = initialNotebookState();
- state.cellIds = MultiColumn.from([]);
-});
-
-afterAll(() => {
- CellId.create = originalCreate;
-});
-
-function setup(...codes: string[]) {
- for (const code of codes) {
- state = dispatch(state, {
- type: "createNewCell",
- payload: {
- cellId: "__end__",
- before: false,
- code,
- newCellId: CellId.create(),
- },
- });
- }
-}
-
-describe("toDocumentChanges", () => {
- describe("anchorOf edge cases", () => {
- it("uses before anchor when new cell is first", () => {
- setup("a");
- const [a] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "createNewCell",
- payload: {
- cellId: a,
- before: true,
- code: "first",
- newCellId: CellId.create(),
- },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "before": "0",
- "cellId": "1",
- "code": "first",
- "config": {
- "column": null,
- "disabled": false,
- "expand_output": false,
- "hide_code": false,
- },
- "name": "_",
- "type": "create-cell",
- },
- ]
- `);
- });
-
- it("uses after anchor for __end__ insertion", () => {
- setup("a");
- const { changes } = resolve(state, {
- type: "createNewCell",
- payload: {
- cellId: "__end__",
- before: false,
- code: "last",
- newCellId: CellId.create(),
- },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "after": "0",
- "cellId": "1",
- "code": "last",
- "config": {
- "column": null,
- "disabled": false,
- "expand_output": false,
- "hide_code": false,
- },
- "name": "_",
- "type": "create-cell",
- },
- ]
- `);
- });
-
- it("uses before when sendToTop moves cell to first position", () => {
- setup("a", "b", "c");
- const [, b] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "sendToTop",
- payload: { cellId: b },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "before": "0",
- "cellId": "1",
- "type": "move-cell",
- },
- ]
- `);
- });
- });
-
- describe("field name mapping", () => {
- it("maps hide_code to hideCode in set-config", () => {
- setup("a");
- const [a] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "updateCellConfig",
- payload: { cellId: a, config: { hide_code: true } },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "0",
- "column": null,
- "disabled": false,
- "expandOutput": false,
- "hideCode": true,
- "type": "set-config",
- },
- ]
- `);
- });
-
- it("maps expand_output to expandOutput in set-config", () => {
- setup("a");
- const [a] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "updateCellConfig",
- payload: { cellId: a, config: { expand_output: true } },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "0",
- "column": null,
- "disabled": false,
- "expandOutput": true,
- "hideCode": false,
- "type": "set-config",
- },
- ]
- `);
- });
-
- it("includes full CellConfig in create-cell", () => {
- setup("a");
-
- const { changes } = resolve(state, {
- type: "createNewCell",
- payload: {
- cellId: "__end__",
- before: false,
- code: "hidden",
- newCellId: CellId.create(),
- config: { expand_output: true },
- hideCode: true,
- },
- });
-
- expect(changes[0]).toMatchObject({
- type: "create-cell",
- config: { hide_code: true, expand_output: true },
- });
- });
- });
-
- describe("column structure actions", () => {
- it("dropOverNewColumn emits set-config + reorder-cells", () => {
- setup("a", "b");
- const [, b] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "dropOverNewColumn",
- payload: { cellId: b },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "1",
- "column": 1,
- "disabled": false,
- "expandOutput": false,
- "hideCode": false,
- "type": "set-config",
- },
- {
- "cellIds": [
- "0",
- "1",
- ],
- "type": "reorder-cells",
- },
- ]
- `);
- });
-
- it("addColumnBreakpoint emits set-config + reorder-cells", () => {
- setup("a", "b", "c");
- const [, b] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "addColumnBreakpoint",
- payload: { cellId: b },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "1",
- "column": 1,
- "disabled": false,
- "expandOutput": false,
- "hideCode": false,
- "type": "set-config",
- },
- {
- "cellId": "2",
- "column": 1,
- "disabled": false,
- "expandOutput": false,
- "hideCode": false,
- "type": "set-config",
- },
- {
- "cellIds": [
- "0",
- "1",
- "2",
- ],
- "type": "reorder-cells",
- },
- ]
- `);
- });
-
- it("mergeAllColumns emits set-config + reorder-cells", () => {
- setup("a", "b", "c");
- const [, b] = state.cellIds.inOrderIds;
- state = dispatch(state, {
- type: "addColumnBreakpoint",
- payload: { cellId: b },
- });
-
- const { changes } = resolve(state, {
- type: "mergeAllColumns",
- payload: {},
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "1",
- "column": 0,
- "disabled": false,
- "expandOutput": false,
- "hideCode": false,
- "type": "set-config",
- },
- {
- "cellId": "2",
- "column": 0,
- "disabled": false,
- "expandOutput": false,
- "hideCode": false,
- "type": "set-config",
- },
- {
- "cellIds": [
- "0",
- "1",
- "2",
- ],
- "type": "reorder-cells",
- },
- ]
- `);
- });
- });
-
- describe("cell lifecycle actions", () => {
- it("addColumn emits create-cell + column layout changes", () => {
- setup("a");
- const [a] = state.cellIds.inOrderIds;
- const columnId = state.cellIds.findWithId(a).id;
-
- const { changes } = resolve(state, {
- type: "addColumn",
- payload: { columnId },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "after": "0",
- "cellId": "1",
- "code": "",
- "config": {
- "column": null,
- "disabled": false,
- "expand_output": false,
- "hide_code": false,
- },
- "name": "_",
- "type": "create-cell",
- },
- {
- "cellId": "1",
- "column": 1,
- "disabled": false,
- "expandOutput": false,
- "hideCode": false,
- "type": "set-config",
- },
- {
- "cellIds": [
- "0",
- "1",
- ],
- "type": "reorder-cells",
- },
- ]
- `);
- });
-
- it("undoDeleteCell emits create-cell for restored cell", () => {
- setup("a", "b");
- const [, b] = state.cellIds.inOrderIds;
-
- // Delete cell b, then undo
- state = dispatch(state, {
- type: "deleteCell",
- payload: { cellId: b },
- });
-
- const { changes } = resolve(state, {
- type: "undoDeleteCell",
- payload: {},
- });
-
- // Restored cell should have original code
- expect(changes[0]).toMatchObject({
- type: "create-cell",
- code: "b",
- });
- });
-
- it("splitCell emits set-code + create-cell", () => {
- setup("line1\nline2");
- const [a] = state.cellIds.inOrderIds;
-
- // Position cursor at end of "line1" (position 5)
- const view = state.cellHandles[a].current!.editorView!;
- view.dispatch({ selection: { anchor: 5 } });
-
- const { changes } = resolve(state, {
- type: "splitCell",
- payload: { cellId: a },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "0",
- "code": "line1",
- "type": "set-code",
- },
- {
- "after": "0",
- "cellId": "1",
- "code": "line2",
- "config": {
- "column": null,
- "disabled": false,
- "expand_output": false,
- "hide_code": false,
- },
- "name": "_",
- "type": "create-cell",
- },
- ]
- `);
- });
-
- it("undoSplitCell emits set-code + delete-cell", () => {
- setup("line1\nline2");
- const [a] = state.cellIds.inOrderIds;
-
- // Split the cell first
- const view = state.cellHandles[a].current!.editorView!;
- view.dispatch({ selection: { anchor: 5 } });
- const snapshot = view.state.doc.toString();
- state = dispatch(state, {
- type: "splitCell",
- payload: { cellId: a },
- });
- const [, newCell] = state.cellIds.inOrderIds;
-
- // Now undo the split
- const { changes } = resolve(state, {
- type: "undoSplitCell",
- payload: { cellId: a, snapshot },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "cellId": "0",
- "code": "line1
- line2",
- "type": "set-code",
- },
- {
- "cellId": "${newCell}",
- "type": "delete-cell",
- },
- ]
- `);
- });
-
- it("moveToNextCell emits create-cell when past last cell", () => {
- setup("a");
- const [a] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "moveToNextCell",
- payload: { cellId: a, before: false },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "after": "0",
- "cellId": "1",
- "code": "",
- "config": {
- "column": null,
- "disabled": false,
- "expand_output": false,
- "hide_code": false,
- },
- "name": "_",
- "type": "create-cell",
- },
- ]
- `);
- });
-
- it("moveToNextCell emits nothing when moving within bounds", () => {
- setup("a", "b");
- const [a] = state.cellIds.inOrderIds;
-
- const { changes } = resolve(state, {
- type: "moveToNextCell",
- payload: { cellId: a, before: false },
- });
-
- expect(changes).toHaveLength(0);
- });
-
- it("addSetupCellIfDoesntExist emits create-cell when new", () => {
- setup("a");
-
- const { changes } = resolve(state, {
- type: "addSetupCellIfDoesntExist",
- payload: { code: "import marimo as mo" },
- });
-
- expect(changes).toMatchInlineSnapshot(`
- [
- {
- "before": "0",
- "cellId": "setup",
- "code": "import marimo as mo",
- "config": {
- "column": null,
- "disabled": false,
- "expand_output": false,
- "hide_code": false,
- },
- "name": "setup",
- "type": "create-cell",
- },
- ]
- `);
- });
-
- it("addSetupCellIfDoesntExist emits nothing when already exists", () => {
- setup("a");
- // Add setup cell first
- state = dispatch(state, {
- type: "addSetupCellIfDoesntExist",
- payload: { code: "import marimo as mo" },
- });
-
- // Try to add again — should just focus
- const { changes } = resolve(state, {
- type: "addSetupCellIfDoesntExist",
- payload: {},
- });
-
- expect(changes).toHaveLength(0);
- });
- });
-
- describe("actions that should NOT emit changes", () => {
- it("focusCell returns empty", () => {
- setup("a", "b");
- const [a] = state.cellIds.inOrderIds;
- const { changes } = resolve(state, {
- type: "focusCell",
- payload: { cellId: a, where: "after" },
- });
- expect(changes).toHaveLength(0);
- });
-
- it("prepareForRun returns empty", () => {
- setup("a");
- const [a] = state.cellIds.inOrderIds;
- const { changes } = resolve(state, {
- type: "prepareForRun",
- payload: { cellId: a },
- });
- expect(changes).toHaveLength(0);
- });
- });
-});
-
-describe("coalesceChanges", () => {
- const X = cellId("X");
- const Y = cellId("Y");
- const A = cellId("A");
- const config = { column: null, disabled: false, hide_code: false };
-
- it("drops set-code that precedes a delete of the same cell", () => {
- const changes: DocumentChange[] = [
- { type: "set-code", cellId: X, code: "x = 2" },
- { type: "delete-cell", cellId: X },
- ];
- expect(coalesceChanges(changes)).toEqual([
- { type: "delete-cell", cellId: X },
- ]);
- });
-
- it("keeps create+delete for a created-then-deleted cell, dropping the edit", () => {
- const changes: DocumentChange[] = [
- { type: "create-cell", cellId: X, code: "", name: "_", config },
- { type: "set-code", cellId: X, code: "x = 1" },
- { type: "delete-cell", cellId: X },
- ];
- expect(coalesceChanges(changes)).toEqual([
- { type: "create-cell", cellId: X, code: "", name: "_", config },
- { type: "delete-cell", cellId: X },
- ]);
- });
-
- it("drops set-code, set-name, set-config, and move-cell for a deleted cell", () => {
- const changes: DocumentChange[] = [
- { type: "create-cell", cellId: X, code: "", name: "_", config },
- { type: "set-code", cellId: X, code: "x = 1" },
- { type: "set-name", cellId: X, name: "foo" },
- {
- type: "set-config",
- cellId: X,
- column: null,
- disabled: true,
- hideCode: false,
- expandOutput: false,
- },
- { type: "move-cell", cellId: X, after: A },
- { type: "delete-cell", cellId: X },
- ];
- expect(coalesceChanges(changes)).toEqual([
- { type: "create-cell", cellId: X, code: "", name: "_", config },
- { type: "delete-cell", cellId: X },
- ]);
- });
-
- it("leaves a plain delete of an unedited cell unchanged", () => {
- const changes: DocumentChange[] = [{ type: "delete-cell", cellId: X }];
- expect(coalesceChanges(changes)).toEqual([
- { type: "delete-cell", cellId: X },
- ]);
- });
-
- it("does not touch set-* for cells that are not deleted, preserving order", () => {
- const changes: DocumentChange[] = [
- { type: "set-code", cellId: A, code: "a = 1" },
- { type: "set-code", cellId: Y, code: "y = 1" },
- { type: "delete-cell", cellId: X },
- ];
- expect(coalesceChanges(changes)).toEqual([
- { type: "set-code", cellId: A, code: "a = 1" },
- { type: "set-code", cellId: Y, code: "y = 1" },
- { type: "delete-cell", cellId: X },
- ]);
- });
-
- it("collapses repeated set-code for a surviving cell to the last value", () => {
- const changes: DocumentChange[] = [
- { type: "set-code", cellId: X, code: "x = 1" },
- { type: "set-name", cellId: X, name: "foo" },
- { type: "set-code", cellId: X, code: "x = 2" },
- ];
- expect(coalesceChanges(changes)).toEqual([
- { type: "set-name", cellId: X, name: "foo" },
- { type: "set-code", cellId: X, code: "x = 2" },
- ]);
- });
-
- it("keeps both creates so a downstream anchor stays resolvable", () => {
- const changes: DocumentChange[] = [
- { type: "create-cell", cellId: X, code: "", name: "_", config, after: A },
- { type: "create-cell", cellId: Y, code: "", name: "_", config, after: X },
- { type: "delete-cell", cellId: X },
- ];
- expect(coalesceChanges(changes)).toEqual([
- { type: "create-cell", cellId: X, code: "", name: "_", config, after: A },
- { type: "create-cell", cellId: Y, code: "", name: "_", config, after: X },
- { type: "delete-cell", cellId: X },
- ]);
- });
-});
-
-describe("document transaction middleware", () => {
- let sent: DocumentChange[][];
-
- const updateCode = (cellId: CellId, code: string) => {
- state = dispatch(state, {
- type: "updateCellCode",
- payload: { cellId, code, formattingChange: false },
- });
- };
-
- beforeEach(() => {
- vi.useFakeTimers();
- sent = [];
- middlewareExports.cancelPendingChanges();
- const captureClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- sent.push(changes);
- return null;
- },
- };
- store.set(
- requestClientAtom,
- captureClient as unknown as EditRequests & RunRequests,
- );
- });
-
- afterEach(() => {
- middlewareExports.cancelPendingChanges();
- store.set(requestClientAtom, null);
- vi.useRealTimers();
- });
-
- it("coalesces edit + delete of the same cell within one debounce window", async () => {
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- // Discard the create-cell from setup; it would flush as its own batch.
- middlewareExports.cancelPendingChanges();
-
- updateCode(x, "x = 2");
- state = dispatch(state, {
- type: "deleteCell",
- payload: { cellId: x },
- });
-
- expect(sent).toEqual([]);
-
- await vi.advanceTimersByTimeAsync(400);
-
- expect(sent).toHaveLength(1);
- expect(sent[0]).toEqual([{ type: "delete-cell", cellId: x }]);
- });
-
- it("sends edit and delete as separate clean transactions across windows", async () => {
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
-
- updateCode(x, "x = 2");
- await vi.advanceTimersByTimeAsync(400);
-
- state = dispatch(state, {
- type: "deleteCell",
- payload: { cellId: x },
- });
- await vi.advanceTimersByTimeAsync(400);
-
- expect(sent).toHaveLength(2);
- expect(sent[0]).toEqual([{ type: "set-code", cellId: x, code: "x = 2" }]);
- expect(sent[1]).toEqual([{ type: "delete-cell", cellId: x }]);
- });
-
- it("flushes pending changes before a dependent operation", async () => {
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
-
- await flushDocumentChanges();
-
- expect(sent).toEqual([[{ type: "set-code", cellId: x, code: "x = 2" }]]);
- });
-
- it("keeps a failed transaction sticky before a dependent operation", async () => {
- const failingClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- sent.push(changes);
- throw new Error("connection lost");
- },
- };
- store.set(
- requestClientAtom,
- failingClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- await vi.advanceTimersByTimeAsync(400);
-
- updateCode(x, "x = 3");
- await expect(flushDocumentChanges()).rejects.toThrow("connection lost");
-
- expect(sent).toEqual([[{ type: "set-code", cellId: x, code: "x = 2" }]]);
- });
-
- it("resumes after a full document save establishes a fresh baseline", async () => {
- let attempt = 0;
- const recoveringClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- sent.push(changes);
- attempt += 1;
- if (attempt === 1) {
- throw new Error("connection lost");
- }
- return null;
- },
- };
- store.set(
- requestClientAtom,
- recoveringClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- await vi.advanceTimersByTimeAsync(400);
-
- updateCode(x, "x = 3");
- await withDocumentSave(async () => {
- updateCode(x, "x = 4");
- });
-
- await vi.advanceTimersByTimeAsync(400);
- expect(sent).toEqual([
- [{ type: "set-code", cellId: x, code: "x = 2" }],
- [{ type: "set-code", cellId: x, code: "x = 4" }],
- ]);
- });
-
- it("restores unsent edits when a full document save fails", async () => {
- const firstStarted = new Deferred<void>();
- const firstRelease = new Deferred<void>();
- const failingClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- sent.push(changes);
- if (sent.length === 1) {
- firstStarted.resolve();
- await firstRelease.promise;
- throw new Error("connection lost");
- }
- return null;
- },
- };
- store.set(
- requestClientAtom,
- failingClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- vi.advanceTimersByTime(400);
- await firstStarted.promise;
-
- updateCode(x, "x = 3");
- await vi.advanceTimersByTimeAsync(400);
- firstRelease.resolve();
- await expect(flushDocumentChanges()).rejects.toThrow("connection lost");
-
- updateCode(x, "x = 4");
- const firstResync = beginDocumentResync();
- abortDocumentResync(firstResync);
- const secondResync = beginDocumentResync();
- expect(secondResync?.includedTransactions).toEqual([
- [{ type: "set-code", cellId: x, code: "x = 3" }],
- ]);
- expect(secondResync?.includedChanges).toEqual([
- { type: "set-code", cellId: x, code: "x = 4" },
- ]);
- await completeDocumentResync(secondResync);
-
- updateCode(x, "x = 5");
- await vi.advanceTimersByTimeAsync(400);
- expect(sent.at(-1)).toEqual([
- { type: "set-code", cellId: x, code: "x = 5" },
- ]);
- });
-
- it("keeps edits debounced while an earlier transaction is in flight", async () => {
- const firstRelease = new Deferred<void>();
- const firstStarted = new Deferred<void>();
- const delayedClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- sent.push(changes);
- if (sent.length === 1) {
- firstStarted.resolve();
- await firstRelease.promise;
- }
- return null;
- },
- };
- store.set(
- requestClientAtom,
- delayedClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- vi.advanceTimersByTime(400);
- await firstStarted.promise;
-
- updateCode(x, "x = 3");
- firstRelease.resolve();
- await vi.advanceTimersByTimeAsync(399);
- expect(sent).toHaveLength(1);
-
- await vi.advanceTimersByTimeAsync(1);
- expect(sent).toEqual([
- [{ type: "set-code", cellId: x, code: "x = 2" }],
- [{ type: "set-code", cellId: x, code: "x = 3" }],
- ]);
- });
-
- it("waits for every transaction queued while flushing", async () => {
- const releases = Array.from({ length: 3 }, () => new Deferred<void>());
- const starts = Array.from({ length: 3 }, () => new Deferred<void>());
- const orderedClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- const index = sent.length;
- sent.push(changes);
- starts[index].resolve();
- await releases[index].promise;
- return null;
- },
- };
- store.set(
- requestClientAtom,
- orderedClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- vi.advanceTimersByTime(400);
- await starts[0].promise;
-
- const flushed = flushDocumentChanges();
-
- updateCode(x, "x = 3");
- await vi.advanceTimersByTimeAsync(400);
- expect(sent).toHaveLength(1);
-
- releases[0].resolve();
- await starts[1].promise;
-
- updateCode(x, "x = 4");
- await vi.advanceTimersByTimeAsync(400);
- expect(sent).toHaveLength(2);
-
- let flushResolved = false;
- void flushed.then(() => {
- flushResolved = true;
- });
- releases[1].resolve();
- await starts[2].promise;
- expect(flushResolved).toBe(false);
-
- releases[2].resolve();
- await flushed;
- expect(sent).toEqual([
- [{ type: "set-code", cellId: x, code: "x = 2" }],
- [{ type: "set-code", cellId: x, code: "x = 3" }],
- [{ type: "set-code", cellId: x, code: "x = 4" }],
- ]);
- });
-
- it("orders a full save between earlier and later transactions", async () => {
- const firstStarted = new Deferred<void>();
- const firstRelease = new Deferred<void>();
- const saveStarted = new Deferred<void>();
- const saveRelease = new Deferred<void>();
- const events: string[] = [];
- const delayedClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- const change = changes[0];
- events.push("code" in change ? change.code : change.type);
- if (events.length === 1) {
- firstStarted.resolve();
- await firstRelease.promise;
- }
- return null;
- },
- };
- store.set(
- requestClientAtom,
- delayedClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- vi.advanceTimersByTime(400);
- await firstStarted.promise;
-
- const saving = withDocumentSave(async () => {
- events.push("save");
- saveStarted.resolve();
- await saveRelease.promise;
- });
- expect(events).toEqual(["x = 2"]);
-
- firstRelease.resolve();
- await saveStarted.promise;
- updateCode(x, "x = 3");
- await vi.advanceTimersByTimeAsync(400);
- expect(events).toEqual(["x = 2", "save"]);
-
- saveRelease.resolve();
- await saving;
- await flushDocumentChanges();
- expect(events).toEqual(["x = 2", "save", "x = 3"]);
- });
-
- it("ignores a failure from a transaction reset while in flight", async () => {
- const firstStarted = new Deferred<void>();
- const firstRelease = new Deferred<void>();
- const firstFinished = new Deferred<void>();
- const delayedClient: Pick<
- EditRequests & RunRequests,
- "sendDocumentTransaction"
- > = {
- sendDocumentTransaction: async ({ changes }) => {
- sent.push(changes);
- if (sent.length === 1) {
- firstStarted.resolve();
- try {
- await firstRelease.promise;
- } finally {
- firstFinished.resolve();
- }
- }
- return null;
- },
- };
- store.set(
- requestClientAtom,
- delayedClient as unknown as EditRequests & RunRequests,
- );
-
- setup("x = 1");
- const [x] = state.cellIds.inOrderIds;
- middlewareExports.cancelPendingChanges();
- updateCode(x, "x = 2");
- vi.advanceTimersByTime(400);
- await firstStarted.promise;
-
- middlewareExports.cancelPendingChanges();
- firstRelease.reject(new Error("stale connection failure"));
- await firstFinished.promise;
- await Promise.resolve();
-
- updateCode(x, "x = 3");
- await flushDocumentChanges();
- expect(sent.at(-1)).toEqual([
- { type: "set-code", cellId: x, code: "x = 3" },
- ]);
- });
-});
diff --git a/frontend/src/core/cells/__tests__/document-roundtrip.test.ts b/frontend/src/core/cells/__tests__/document-roundtrip.test.ts
deleted file mode 100644
index 77ab724476..0000000000
--- a/frontend/src/core/cells/__tests__/document-roundtrip.test.ts
+++ /dev/null
@@ -1,392 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-/**
- * Round-trip tests: perform actions on a primary notebook (producing changes
- * via the middleware), then apply those changes to a replica notebook via
- * applyTransactionChanges. The two should converge to identical document state.
- *
- * This catches drift between what the middleware emits and what
- * apply-transaction consumes.
- */
-
-import { python } from "@codemirror/lang-python";
-import { EditorState } from "@codemirror/state";
-import { EditorView } from "@codemirror/view";
-import {
- afterAll,
- afterEach,
- beforeAll,
- beforeEach,
- describe,
- expect,
- it,
-} from "vitest";
-import { cellId } from "@/__tests__/branded";
-import type { CellHandle } from "@/components/editor/notebook-cell";
-import { adaptiveLanguageConfiguration } from "@/core/codemirror/language/extension";
-import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
-import { MultiColumn } from "@/utils/id-tree";
-import { exportedForTesting, type NotebookState } from "../cells";
-import {
- applyTransactionChanges,
- exportedForTesting as middlewareExports,
-} from "../document-changes";
-import { CellId } from "../ids";
-
-const { initialNotebookState, reducer, createActions } = exportedForTesting;
-const { drainChanges } = middlewareExports;
-
-function createEditor(code: string) {
- const state = EditorState.create({
- doc: code,
- extensions: [
- python(),
- adaptiveLanguageConfiguration({
- cellId: cellId("cell1"),
- completionConfig: {
- activate_on_typing: true,
- signature_hint_on_typing: false,
- copilot: false,
- codeium_api_key: null,
- },
- hotkeys: new OverridingHotkeyProvider({}),
- placeholderType: "marimo-import",
- lspConfig: {},
- }),
- ],
- });
- return new EditorView({ state, parent: document.body });
-}
-
-// --- Primary notebook: performs actions, middleware produces changes ---
-
-let primary: NotebookState;
-
-const primaryActions = createActions((action) => {
- primary = reducer(primary, action);
- for (const [cellIdString, handle] of Object.entries(primary.cellHandles)) {
- // @ts-expect-error - Object.entries doesn't know keys are CellId
- const cid: CellId = cellIdString;
- if (!handle.current) {
- const view = createEditor(primary.cellData[cid].code);
- const h: CellHandle = { editorView: view, editorViewOrNull: view };
- primary.cellHandles[cid] = { current: h };
- }
- }
-});
-
-// --- Replica notebook: receives changes via applyTransactionChanges ---
-
-let replica: NotebookState;
-
-const replicaActions = createActions((action) => {
- replica = reducer(replica, action);
- for (const [cellIdString, handle] of Object.entries(replica.cellHandles)) {
- // @ts-expect-error - Object.entries doesn't know keys are CellId
- const cid: CellId = cellIdString;
- if (!handle.current) {
- const view = createEditor(replica.cellData[cid].code);
- const h: CellHandle = { editorView: view, editorViewOrNull: view };
- replica.cellHandles[cid] = { current: h };
- }
- }
-});
-
-let i = 0;
-const originalCreate = CellId.create.bind(CellId);
-
-beforeAll(() => {
- CellId.create = () => cellId(`${i++}`);
-});
-
-beforeEach(() => {
- i = 0;
- primary = initialNotebookState();
- primary.cellIds = MultiColumn.from([]);
- drainChanges();
-});
-
-afterEach(() => {
- middlewareExports.cancelPendingChanges();
-});
-
-afterAll(() => {
- CellId.create = originalCreate;
-});
-
-/** Set up both notebooks with the same initial cells. */
-function setup(...codes: string[]) {
- for (const code of codes) {
- primaryActions.createNewCell({
- cellId: "__end__",
- before: false,
- code,
- newCellId: CellId.create(),
- });
- }
-
- // Apply the setup changes to the replica so both start identical
- const setupChanges = drainChanges();
- replica = initialNotebookState();
- replica.cellIds = MultiColumn.from([]);
- applyTransactionChanges(
- setupChanges,
- replicaActions,
- () => replica.cellIds.inOrderIds,
- );
- // Drain any changes the replica's middleware produced
- drainChanges();
-}
-
-/**
- * Drain changes from the primary's middleware and apply them to the replica.
- */
-function sync() {
- const changes = drainChanges();
- applyTransactionChanges(
- changes,
- replicaActions,
- () => replica.cellIds.inOrderIds,
- );
- // Drain any changes the replica's middleware produced (we don't want those)
- drainChanges();
-}
-
-/**
- * Extract the document-relevant state: cell ordering, code, name, config.
- * This is the "NotebookDocument" equivalent — what the Python side tracks.
- *
- * TODO(column-config): config.column is excluded because the column
- * reducers (addColumnBreakpoint, dropOverNewColumn, moveColumn, etc.)
- * update cellIds (MultiColumn structure) but don't sync config.column
- * on affected cells. The middleware correctly emits set-config changes with
- * the new column index, but the primary's config.column stays stale,
- * causing a mismatch with the replica. Fix: have the column reducers
- * update config.column as part of their state transition, then remove
- * the { column: _, ...config } exclusion here.
- */
-function documentSnapshot(state: NotebookState) {
- return state.cellIds.inOrderIds.map((id) => {
- const { column: _, ...config } = state.cellData[id].config;
- return {
- id,
- code: state.cellData[id].code,
- name: state.cellData[id].name,
- config,
- };
- });
-}
-
-describe("document round-trip", () => {
- it("applies a server transaction that deletes every cell", () => {
- setup("a", "b");
- applyTransactionChanges(
- [
- ...replica.cellIds.inOrderIds.map((cellId) => ({
- type: "delete-cell" as const,
- cellId,
- })),
- { type: "reorder-cells", cellIds: [] },
- ],
- replicaActions,
- () => replica.cellIds.inOrderIds,
- );
- expect(documentSnapshot(replica)).toEqual([]);
- });
-
- it("initial setup converges", () => {
- setup("a", "b", "c");
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("createNewCell at end", () => {
- setup("a", "b");
- primaryActions.createNewCell({
- cellId: "__end__",
- before: false,
- code: "c",
- newCellId: CellId.create(),
- });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("createNewCell before first cell", () => {
- setup("a", "b");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.createNewCell({
- cellId: a,
- before: true,
- code: "before-a",
- newCellId: CellId.create(),
- });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("createNewCell between cells", () => {
- setup("a", "b", "c");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.createNewCell({
- cellId: a,
- before: false,
- code: "between",
- newCellId: CellId.create(),
- });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("createNewCell with hideCode config", () => {
- setup("a");
- primaryActions.createNewCell({
- cellId: "__end__",
- before: false,
- code: "hidden",
- newCellId: CellId.create(),
- hideCode: true,
- });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("deleteCell", () => {
- setup("a", "b", "c");
- const [, b] = primary.cellIds.inOrderIds;
- primaryActions.deleteCell({ cellId: b });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("updateCellCode", () => {
- setup("a", "b");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.updateCellCode({
- cellId: a,
- code: "updated",
- formattingChange: false,
- });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("updateCellName", () => {
- setup("a");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.updateCellName({ cellId: a, name: "my_var" });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("updateCellConfig", () => {
- setup("a");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.updateCellConfig({
- cellId: a,
- config: { hide_code: true, disabled: true },
- });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("moveCell down", () => {
- setup("a", "b", "c");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.moveCell({ cellId: a, before: false });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("sendToTop", () => {
- setup("a", "b", "c");
- const c = primary.cellIds.inOrderIds[2];
- primaryActions.sendToTop({ cellId: c });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("sendToBottom", () => {
- setup("a", "b", "c");
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.sendToBottom({ cellId: a });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("dropCellOverCell", () => {
- setup("a", "b", "c");
- const [a, , c] = primary.cellIds.inOrderIds;
- primaryActions.dropCellOverCell({ cellId: c, overCellId: a });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("multiple operations in sequence", () => {
- setup("a", "b", "c");
-
- // Add a cell
- const [a] = primary.cellIds.inOrderIds;
- primaryActions.createNewCell({
- cellId: a,
- before: false,
- code: "new",
- newCellId: CellId.create(),
- });
- sync();
-
- // Rename it
- const newId = primary.cellIds.inOrderIds[1];
- primaryActions.updateCellName({ cellId: newId, name: "inserted" });
- sync();
-
- // Move it to top
- primaryActions.sendToTop({ cellId: newId });
- sync();
-
- // Update code on another cell
- const last =
- primary.cellIds.inOrderIds[primary.cellIds.inOrderIds.length - 1];
- primaryActions.updateCellCode({
- cellId: last,
- code: "modified",
- formattingChange: false,
- });
- sync();
-
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("create then delete", () => {
- setup("a", "b");
- primaryActions.createNewCell({
- cellId: "__end__",
- before: false,
- code: "temporary",
- newCellId: CellId.create(),
- });
- sync();
-
- const newId =
- primary.cellIds.inOrderIds[primary.cellIds.inOrderIds.length - 1];
- primaryActions.deleteCell({ cellId: newId });
- sync();
-
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("addColumnBreakpoint", () => {
- setup("a", "b", "c");
- const [, b] = primary.cellIds.inOrderIds;
- primaryActions.addColumnBreakpoint({ cellId: b });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-
- it("dropOverNewColumn", () => {
- setup("a", "b", "c");
- const [, b] = primary.cellIds.inOrderIds;
- primaryActions.dropOverNewColumn({ cellId: b });
- sync();
- expect(documentSnapshot(primary)).toEqual(documentSnapshot(replica));
- });
-});
diff --git a/frontend/src/core/cells/__tests__/document.test.ts b/frontend/src/core/cells/__tests__/document.test.ts
new file mode 100644
index 0000000000..b60d3513dd
--- /dev/null
+++ b/frontend/src/core/cells/__tests__/document.test.ts
@@ -0,0 +1,410 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { python } from "@codemirror/lang-python";
+import { EditorState } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import { atom } from "jotai";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cellId } from "@/__tests__/branded";
+import type {
+ DocumentEdit,
+ DocumentEditor,
+ DocumentModel,
+ DocumentSyncStatus,
+ EditableCell,
+ EditableDocument,
+} from "@/core/notebook/document";
+import {
+ adaptiveLanguageConfiguration,
+ languageAdapterState,
+} from "@/core/codemirror/language/extension";
+import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
+import { store } from "@/core/state/jotai";
+import { activeDocumentModelAtom } from "@/core/session/active-notebook";
+import { MultiColumn } from "@/utils/id-tree";
+import { isRtcEnabled } from "../../rtc/state";
+import {
+ createNotebookActions,
+ exportedForTesting,
+ type NotebookState,
+ notebookReducer,
+} from "../cells";
+import { applyDocument, flushDocument, withDocumentSave } from "../document";
+import { type CellId, SCRATCH_CELL_ID } from "../ids";
+
+vi.mock("../../rtc/state", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../../rtc/state")>()),
+ isRtcEnabled: vi.fn(() => false),
+}));
+
+const { initialNotebookState } = exportedForTesting;
+
+const a = cellId("a");
+const b = cellId("b");
+const c = cellId("c");
+const d = cellId("d");
+
+function cell(id: CellId, patch: Partial<EditableCell> = {}): EditableCell {
+ return {
+ id,
+ code: `${id} = 1`,
+ name: "_",
+ config: {
+ column: null,
+ disabled: false,
+ hide_code: false,
+ expand_output: false,
+ },
+ ...patch,
+ };
+}
+
+function documentOf(cells: EditableCell[]): EditableDocument {
+ return {
+ order: cells.map((cell) => cell.id),
+ cells: new Map(cells.map((cell) => [cell.id, cell])),
+ };
+}
+
+/** A mounted cell editor, as the notebook's cells have. */
+function createEditor(content: string) {
+ const state = EditorState.create({
+ doc: content,
+ extensions: [
+ python(),
+ adaptiveLanguageConfiguration({
+ cellId: a,
+ completionConfig: {
+ activate_on_typing: true,
+ signature_hint_on_typing: false,
+ copilot: false,
+ codeium_api_key: null,
+ },
+ hotkeys: new OverridingHotkeyProvider({}),
+ placeholderType: "marimo-import",
+ lspConfig: {},
+ }),
+ ],
+ });
+ return new EditorView({ state, parent: globalThis.document.body });
+}
+
+/** A notebook that follows `cells`, as the session builds one. */
+function notebookOf(cells: EditableCell[]): NotebookState {
+ return applyDocument(initialNotebookState(), documentOf(cells));
+}
+
+describe("applyDocument", () => {
+ it("adds the document's cells to an empty notebook", () => {
+ const state = notebookOf([cell(a), cell(b, { code: "" })]);
+
+ expect(state.cellIds.inOrderIds).toEqual([a, b]);
+ expect(state.cellData[a]).toMatchObject({
+ code: "a = 1",
+ name: "_",
+ edited: false,
+ lastCodeRun: null,
+ });
+ expect(state.cellRuntime[a]).toBeDefined();
+ expect(state.cellHandles[a]).toBeDefined();
+ expect(state.cellData[SCRATCH_CELL_ID]).toBeDefined();
+ });
+
+ it("returns the same state when the document matches", () => {
+ const cells = [cell(a), cell(b)];
+ const state = notebookOf(cells);
+
+ expect(applyDocument(state, documentOf(cells))).toBe(state);
+ });
+
+ it("brings a code change into the cell's editor", () => {
+ const state = notebookOf([cell(a), cell(b)]);
+ const view = createEditor("b = 1");
+ state.cellHandles[b].current = { editorView: view, editorViewOrNull: view };
+ state.cellData[b] = { ...state.cellData[b], lastCodeRun: "b = 1" };
+
+ const next = applyDocument(
+ state,
+ documentOf([cell(a), cell(b, { code: "b = 2" })]),
+ );
+
+ expect(next.cellData[b]).toMatchObject({ code: "b = 2", edited: true });
+ expect(next.cellData[a]).toBe(state.cellData[a]);
+ expect(view.state.doc.toString()).toBe("b = 2");
+ });
+
+ it("leaves an editor that already shows the document's code alone", () => {
+ const state = notebookOf([cell(a)]);
+ // The editor runs ahead of the notebook while this client types.
+ const view = createEditor('mo.md("hi")');
+ state.cellHandles[a].current = { editorView: view, editorViewOrNull: view };
+
+ const next = applyDocument(
+ state,
+ documentOf([cell(a, { code: 'mo.md("hi")' })]),
+ );
+
+ expect(next.cellData[a].code).toBe('mo.md("hi")');
+ expect(view.state.doc.toString()).toBe('mo.md("hi")');
+ expect(view.state.field(languageAdapterState).type).toBe("python");
+ });
+
+ it("leaves an RTC editor to Loro", () => {
+ vi.mocked(isRtcEnabled).mockReturnValueOnce(true);
+ const state = notebookOf([cell(a)]);
+ const view = createEditor("a = 1");
+ state.cellHandles[a].current = { editorView: view, editorViewOrNull: view };
+
+ const next = applyDocument(state, documentOf([cell(a, { code: "a = 2" })]));
+
+ expect(next.cellData[a].code).toBe("a = 2");
+ expect(view.state.doc.toString()).toBe("a = 1");
+ });
+
+ it("keeps the code this client has when the host withholds source", () => {
+ const state = notebookOf([cell(a)]);
+
+ expect(applyDocument(state, documentOf([cell(a, { code: null })]))).toBe(
+ state,
+ );
+ });
+
+ it("follows a cell's name and config", () => {
+ const state = notebookOf([cell(a)]);
+
+ const next = applyDocument(
+ state,
+ documentOf([
+ cell(a, {
+ name: "renamed",
+ config: { ...cell(a).config, hide_code: true },
+ }),
+ ]),
+ );
+
+ expect(next.cellData[a]).toMatchObject({
+ name: "renamed",
+ config: { hide_code: true },
+ edited: false,
+ });
+ });
+
+ it("removes cells the document no longer has", () => {
+ const state = notebookOf([cell(a), cell(b), cell(c)]);
+
+ const next = applyDocument(state, documentOf([cell(a), cell(c)]));
+
+ expect(next.cellIds.inOrderIds).toEqual([a, c]);
+ expect(next.cellData[b]).toBeUndefined();
+ expect(next.cellRuntime[b]).toBeUndefined();
+ expect(next.cellHandles[b]).toBeUndefined();
+ });
+
+ it("regroups columns from the cells' configs, keeping column ids and collapsed sections", () => {
+ const column1 = { ...cell(d).config, column: 1 };
+ const state = notebookOf([
+ cell(a),
+ cell(b),
+ cell(c),
+ cell(d, { config: column1 }),
+ ]);
+ const [first, second] = state.cellIds.getColumns();
+ const collapsed = {
+ ...state,
+ cellIds: new MultiColumn([first.collapse(a, b), second]),
+ };
+
+ const next = applyDocument(
+ collapsed,
+ documentOf([cell(c), cell(a), cell(b), cell(d, { config: column1 })]),
+ );
+
+ expect(next.cellIds.inOrderIds).toEqual([c, a, b, d]);
+ expect(next.cellIds.getColumnIds()).toEqual(
+ collapsed.cellIds.getColumnIds(),
+ );
+ expect(next.cellIds.atOrThrow(0).isCollapsed(a)).toBe(true);
+ expect(next.cellIds.atOrThrow(1).inOrderIds).toEqual([d]);
+ });
+
+ it("keeps a trailing empty column", () => {
+ const state = notebookOf([cell(a)]);
+ const withEmpty = {
+ ...state,
+ cellIds: state.cellIds.addColumn(state.cellIds.atOrThrow(0).id),
+ };
+
+ const next = applyDocument(withEmpty, documentOf([cell(a, { code: "" })]));
+
+ expect(next.cellIds.colLength).toBe(2);
+ expect(next.cellData[a].code).toBe("");
+ });
+});
+
+describe("documentEditMiddleware", () => {
+ type Call = [string, ...unknown[]];
+ let calls: Call[];
+ let state: NotebookState;
+ const editor: DocumentEditor = {
+ setCode: (id, code) => calls.push(["setCode", id, code]),
+ setName: (id, name) => calls.push(["setName", id, name]),
+ updateConfig: (id, patch) => calls.push(["updateConfig", id, patch]),
+ createCell: (cell, placement) =>
+ calls.push(["createCell", cell, placement]),
+ deleteCell: (id) => calls.push(["deleteCell", id]),
+ setOrder: (order) => calls.push(["setOrder", order]),
+ };
+ const model: DocumentModel = {
+ documentAtom: atom(null),
+ editAtom: atom(null, (_get, _set, edit: DocumentEdit) => edit(editor)),
+ syncStatusAtom: atom<DocumentSyncStatus>({ status: "idle" }),
+ flush: vi.fn(),
+ retry: vi.fn(),
+ hold: () => () => undefined,
+ start: vi.fn(),
+ };
+ const actions = createNotebookActions((action) => {
+ state = notebookReducer(state, action);
+ });
+
+ beforeEach(() => {
+ calls = [];
+ state = notebookOf([cell(a), cell(b), cell(c)]);
+ store.set(activeDocumentModelAtom, model);
+ });
+
+ afterEach(() => {
+ store.set(activeDocumentModelAtom, null);
+ });
+
+ it("creates a cell at the end without setting the order", () => {
+ actions.createNewCell({
+ cellId: c,
+ before: false,
+ code: "d = 1",
+ newCellId: d,
+ });
+
+ expect(calls.map((call) => call[0])).toEqual(["createCell"]);
+ expect(calls[0][1]).toMatchObject({ id: d, code: "d = 1" });
+ });
+
+ it("creates a cell elsewhere and sets the order", () => {
+ actions.createNewCell({ cellId: a, before: true, newCellId: d });
+
+ expect(calls.map((call) => call[0])).toEqual(["createCell", "setOrder"]);
+ expect(calls[1][1]).toEqual([d, a, b, c]);
+ });
+
+ it("deletes a cell", () => {
+ actions.deleteCell({ cellId: b });
+
+ expect(calls).toEqual([["deleteCell", b]]);
+ });
+
+ it("writes code, name, and config", () => {
+ actions.updateCellCode({
+ cellId: a,
+ code: "a = 2",
+ formattingChange: false,
+ });
+ actions.updateCellName({ cellId: a, name: "first" });
+ actions.updateCellConfig({ cellId: a, config: { hide_code: true } });
+
+ expect(calls).toEqual([
+ ["setCode", a, "a = 2"],
+ ["setName", a, "first"],
+ ["updateConfig", a, { hide_code: true }],
+ ]);
+ });
+
+ it("sets the order when a cell moves", () => {
+ actions.moveCell({ cellId: c, before: true });
+
+ expect(calls).toEqual([["setOrder", [a, c, b]]]);
+ });
+
+ it("sets the column of a cell that changes column", () => {
+ state = notebookOf([
+ cell(a),
+ cell(b),
+ cell(c, { config: { ...cell(c).config, column: 1 } }),
+ ]);
+
+ actions.moveCell({ cellId: b, direction: "right" });
+
+ expect(state.cellIds.atOrThrow(1).inOrderIds).toEqual([b, c]);
+ expect(calls).toEqual([["updateConfig", b, { column: 1 }]]);
+ });
+
+ it("clears columns merged into one", () => {
+ state = notebookOf([
+ cell(a),
+ cell(b),
+ cell(c, { config: { ...cell(c).config, column: 1 } }),
+ ]);
+
+ actions.mergeAllColumns();
+
+ expect(calls).toEqual([["updateConfig", c, { column: null }]]);
+ });
+
+ it("ignores the kernel's cells and runtime state", () => {
+ actions.prepareForRun({ cellId: a });
+ actions.setCells([state.cellData[a]]);
+
+ expect(calls).toEqual([]);
+ });
+
+ it("leaves the scratchpad alone", () => {
+ actions.updateCellCode({
+ cellId: SCRATCH_CELL_ID,
+ code: "scratch",
+ formattingChange: false,
+ });
+
+ expect(calls).toEqual([]);
+ });
+});
+
+describe("flushing before host commands", () => {
+ const model = {
+ syncStatusAtom: atom<DocumentSyncStatus>({ status: "idle" }),
+ flush: vi.fn<() => Promise<never>>(),
+ retry: vi.fn<() => Promise<never>>(),
+ hold: () => () => undefined,
+ } as unknown as DocumentModel;
+
+ beforeEach(() => {
+ vi.mocked(model.flush).mockReset();
+ vi.mocked(model.retry).mockReset();
+ store.set(activeDocumentModelAtom, model);
+ });
+
+ afterEach(() => {
+ store.set(activeDocumentModelAtom, null);
+ });
+
+ it("flushes the session's model, or nothing without one", async () => {
+ vi.mocked(model.flush).mockResolvedValue(undefined as never);
+ await flushDocument();
+ expect(model.flush).toHaveBeenCalledOnce();
+
+ store.set(activeDocumentModelAtom, null);
+ await expect(flushDocument()).resolves.toBeUndefined();
+ });
+
+ it("saves after a flush and resumes the model when the flush failed", async () => {
+ vi.mocked(model.flush).mockRejectedValue(new Error("conflict"));
+ vi.mocked(model.retry).mockResolvedValue(undefined as never);
+ const save = vi.fn().mockResolvedValue("saved");
+
+ await expect(withDocumentSave(save)).resolves.toBe("saved");
+ expect(save).toHaveBeenCalledOnce();
+ expect(model.retry).toHaveBeenCalledOnce();
+
+ vi.mocked(model.flush).mockResolvedValue(undefined as never);
+ await withDocumentSave(save);
+ expect(model.retry).toHaveBeenCalledOnce();
+ });
+});
diff --git a/frontend/src/core/cells/__tests__/flush-document.test.ts b/frontend/src/core/cells/__tests__/flush-document.test.ts
new file mode 100644
index 0000000000..381156d1f2
--- /dev/null
+++ b/frontend/src/core/cells/__tests__/flush-document.test.ts
@@ -0,0 +1,40 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDocumentModel } from "@/core/notebook/document";
+import {
+ type FakeEdit,
+ fakeBackend,
+} from "@/core/notebook/replica/__tests__/fixtures";
+import type { Document } from "@/core/notebook/replica/resources/document";
+import { activeDocumentModelAtom } from "@/core/session/active-notebook";
+import { store } from "@/core/state/jotai";
+import { flushDocument } from "../document";
+
+const lifetimes: AbortController[] = [];
+
+afterEach(() => {
+ lifetimes.splice(0).forEach((controller) => controller.abort());
+ store.set(activeDocumentModelAtom, null);
+});
+
+describe("flushDocument", () => {
+ it("sends nothing while the document is unavailable", async () => {
+ const edit = vi.fn<FakeEdit>();
+ const model = createDocumentModel({
+ store,
+ documentAtom: atom<Document | null>(null),
+ backendAtom: atom(fakeBackend({ edit })),
+ });
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
+ store.set(activeDocumentModelAtom, model);
+
+ expect(store.get(model.syncStatusAtom)).toEqual({ status: "unavailable" });
+ await expect(model.flush()).rejects.toThrow("unavailable");
+ await expect(flushDocument()).resolves.toBeUndefined();
+ expect(edit).not.toHaveBeenCalled();
+ });
+});
diff --git a/frontend/src/core/cells/__tests__/notebook-outline.test.ts b/frontend/src/core/cells/__tests__/notebook-outline.test.ts
index 147df01617..febb375e0f 100644
--- a/frontend/src/core/cells/__tests__/notebook-outline.test.ts
+++ b/frontend/src/core/cells/__tests__/notebook-outline.test.ts
@@ -1,7 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { createStore } from "jotai";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it, vi } from "vitest";
import { MockNotebook } from "@/__mocks__/notebook";
import { cellId } from "@/__tests__/branded";
import {
@@ -10,7 +10,6 @@ import {
notebookOutline,
notebookReducer,
} from "../cells";
-import { exportedForTesting } from "../document-changes";
import type { Outline } from "../outline";
const first = cellId("first");
@@ -40,10 +39,6 @@ function setup() {
return { store, actions };
}
-afterEach(() => {
- exportedForTesting.cancelPendingChanges();
-});
-
describe("notebookOutline", () => {
it("does not notify outline subscribers when cell code changes", () => {
const { store, actions } = setup();
diff --git a/frontend/src/core/cells/__tests__/with-document-save.test.ts b/frontend/src/core/cells/__tests__/with-document-save.test.ts
new file mode 100644
index 0000000000..3e2a72c78c
--- /dev/null
+++ b/frontend/src/core/cells/__tests__/with-document-save.test.ts
@@ -0,0 +1,67 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDocumentModel } from "@/core/notebook/document";
+import { document } from "@/core/notebook/document/__tests__/fixtures";
+import type { Document } from "@/core/notebook/replica/resources/document";
+import {
+ type FakeEdit,
+ fakeBackend,
+} from "@/core/notebook/replica/__tests__/fixtures";
+import { activeDocumentModelAtom } from "@/core/session/active-notebook";
+import { store } from "@/core/state/jotai";
+import { Deferred } from "@/utils/Deferred";
+import { withDocumentSave } from "../document";
+
+const lifetimes: AbortController[] = [];
+
+afterEach(() => {
+ lifetimes.splice(0).forEach((controller) => controller.abort());
+ store.set(activeDocumentModelAtom, null);
+});
+
+describe("withDocumentSave", () => {
+ it("sends an edit made during the save only after the save finishes", async () => {
+ const source = atom<Document | null>(document());
+ const base = document();
+ const accepted: Document = {
+ ...base,
+ revision: { ...base.revision, version: 2, etag: "document-2" },
+ };
+ // Answer the edit, then publish the accepted document as the host would.
+ const edit = vi.fn<FakeEdit>().mockImplementation(async () => {
+ queueMicrotask(() => store.set(source, accepted));
+ return {
+ ok: true,
+ status: 200,
+ data: { document: accepted.revision, cells: {} },
+ };
+ });
+ const model = createDocumentModel({
+ store,
+ documentAtom: source,
+ backendAtom: atom(fakeBackend({ edit })),
+ });
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
+ store.set(activeDocumentModelAtom, model);
+
+ const saving = new Deferred<void>();
+ let flushing: Promise<unknown> | undefined;
+ const saved = withDocumentSave(async () => {
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "x = 2"));
+ flushing = model.flush();
+ await Promise.resolve();
+ expect(edit).not.toHaveBeenCalled();
+ await saving.promise;
+ return "saved";
+ });
+
+ saving.resolve();
+ await expect(saved).resolves.toBe("saved");
+ await flushing;
+ expect(edit).toHaveBeenCalledTimes(1);
+ });
+});
diff --git a/frontend/src/core/cells/cells.ts b/frontend/src/core/cells/cells.ts
index 428d8c2fed..32af48af27 100644
--- a/frontend/src/core/cells/cells.ts
+++ b/frontend/src/core/cells/cells.ts
@@ -1,11 +1,11 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { historyField } from "@codemirror/commands";
-import { dequal as isEqual } from "dequal";
import { type Atom, atom, useAtom, useAtomValue } from "jotai";
import { atomFamily, selectAtom, splitAtom } from "jotai/utils";
import { createRef, type ReducerWithoutAction } from "react";
import type { CellHandle } from "@/components/editor/notebook-cell";
+import type { EditableDocument } from "@/core/notebook/document";
import type { CollapsibleTree } from "@/utils/id-tree";
import {
type CellColumnId,
@@ -20,20 +20,17 @@ import { extractAllTracebackInfo, type TracebackInfo } from "@/utils/traceback";
import { createReducerAndAtoms } from "../../utils/createReducer";
import { foldAllBulk, unfoldAllBulk } from "../codemirror/editing/commands";
import { editorMountScheduler } from "../codemirror/editor-mount-scheduler";
-import {
- splitEditor,
- updateEditorCodeFromPython,
-} from "../codemirror/language/utils";
+import { prepareCellCodeUpdate } from "../codemirror/language/cell-code";
+import { splitEditor } from "../codemirror/language/utils";
import type { SerializedEditorState } from "../codemirror/types";
import { findCollapseRange, mergeOutlines } from "../dom/outline";
import type { CellMessage } from "../kernel/messages";
import { isErrorMime } from "../mime";
import type { CellConfig } from "../network/types";
-import { canUseRtc, isRtcEnabled } from "../rtc/state";
import { createDeepEqualAtom, store } from "../state/jotai";
import { isWasm } from "../wasm/utils";
import { prepareCellForExecution, transitionCell } from "./cell";
-import { documentTransactionMiddleware } from "./document-changes";
+import { applyDocument, documentEditMiddleware } from "./document";
import { CellId, SCRATCH_CELL_ID, SETUP_CELL_ID } from "./ids";
import { type CellLog, getCellLogsForMessage } from "./logs";
import {
@@ -939,158 +936,19 @@ const {
cellLogs: [...state.cellLogs, ...action.logs],
};
},
- setCellIds: (state, action: { cellIds: CellId[] }) => {
- const isTheSame = isEqual(state.cellIds.inOrderIds, action.cellIds);
- if (isTheSame) {
- return state;
- }
-
- // Create new cell data and runtime states for the new cell IDs
- const nextCellData = { ...state.cellData };
- const nextCellRuntime = { ...state.cellRuntime };
- const nextCellHandles = { ...state.cellHandles };
-
- for (const cellId of action.cellIds) {
- if (!(cellId in state.cellData)) {
- nextCellData[cellId] = createCell({ id: cellId });
- }
- if (!(cellId in state.cellRuntime)) {
- nextCellRuntime[cellId] = createCellRuntimeState();
- }
- if (!(cellId in state.cellHandles)) {
- nextCellHandles[cellId] = createRef();
- }
- }
-
- return {
- ...state,
- cellIds: MultiColumn.fromWithPreviousShape(action.cellIds, state.cellIds),
- cellData: nextCellData,
- cellRuntime: nextCellRuntime,
- cellHandles: nextCellHandles,
- };
- },
/**
- * Rebuild the MultiColumn tree using each cell's `config.column` value.
+ * Follow the host document's cells and order.
*
- * Used after a transaction whose `set-config` changes updated cells'
- * column metadata without physically moving them in the tree. Cells with
- * `config.column == null` inherit the column of the previous cell in the
- * given order (see `MultiColumn.fromIdsAndColumns`), which lets the server
- * send column changes only at column boundaries.
+ * Dispatched without middleware, since the document already has these
+ * changes.
*/
- rebuildCellColumns: (state, action: { cellIds: CellId[] }) => {
- const newCellIds = MultiColumn.fromIdsAndColumns(
- action.cellIds.map((id) => [
- id,
- state.cellData[id]?.config.column ?? null,
- ]),
- );
- return { ...state, cellIds: newCellIds };
- },
- setCellCodes: (
- state,
- action: {
- codes: string[];
- ids: CellId[];
- codeIsStale: boolean;
- names?: string[];
- configs?: CellConfig[];
- },
- ) => {
- invariant(
- action.codes.length === action.ids.length,
- "Expected codes and ids to have the same length",
- );
-
- let nextState = { ...state };
-
- const cellReducer = ({
- cell,
- code,
- cellId,
- name,
- config,
- }: {
- cell: CellData | undefined;
- code: string;
- cellId: CellId;
- name?: string;
- config?: CellConfig;
- }) => {
- if (!cell) {
- return createCell({
- id: cellId,
- code,
- name: name,
- config: config,
- lastCodeRun: action.codeIsStale ? null : code,
- edited: action.codeIsStale && code.trim().length > 0,
- });
- }
-
- // If code is stale, we don't promote it to lastCodeRun
- const lastCodeRun = action.codeIsStale ? cell.lastCodeRun : code;
-
- // Mark as edited if the code has changed
- const edited = lastCodeRun
- ? lastCodeRun.trim() !== code.trim()
- : Boolean(code);
-
- // No change
- if (cell.code.trim() === code.trim()) {
- return {
- ...cell,
- code: code,
- edited,
- lastCodeRun,
- ...(name !== undefined && { name }),
- ...(config !== undefined && { config }),
- };
- }
-
- // Update codemirror if mounted. RTC-backed cells sync via Loro; others
- // (e.g. scratchpad) still need an explicit editor update.
- if (!isRtcEnabled() || !canUseRtc(cellId)) {
- const cellHandle = nextState.cellHandles[cellId].current;
- if (cellHandle?.editorViewOrNull) {
- updateEditorCodeFromPython(cellHandle.editorViewOrNull, code);
- }
- }
-
- return {
- ...cell,
- code: code,
- edited,
- lastCodeRun,
- ...(name !== undefined && { name }),
- ...(config !== undefined && { config }),
- };
- };
-
- for (let i = 0; i < action.ids.length; i++) {
- const cellId = action.ids[i];
- const code = action.codes[i];
- if (cellId === undefined || code === undefined) {
- continue;
+ reconcileDocument: (state, document: EditableDocument) => {
+ const nextState = applyDocument(state, document);
+ for (const cellId of state.cellIds.inOrderIds) {
+ if (!(cellId in nextState.cellData)) {
+ releaseCellAtoms(cellId);
}
- const name = action.names?.[i];
- const config = action.configs?.[i];
- nextState = {
- ...nextState,
- cellData: {
- ...nextState.cellData,
- [cellId]: cellReducer({
- cell: nextState.cellData[cellId],
- code,
- cellId,
- name,
- config,
- }),
- },
- };
}
-
return nextState;
},
setStdinResponse: (
@@ -1440,7 +1298,14 @@ const {
cellHandle.editorView,
);
- updateEditorCodeFromPython(cellHandle.editorView, beforeCursorCode);
+ const update = prepareCellCodeUpdate(
+ cellHandle.editorView.state,
+ beforeCursorCode,
+ );
+
+ if (update) {
+ cellHandle.editorView.dispatch(update);
+ }
const newCellId = CellId.create();
@@ -1488,7 +1353,11 @@ const {
return state;
}
- updateEditorCodeFromPython(cellHandle.editorView, snapshot);
+ const update = prepareCellCodeUpdate(cellHandle.editorView.state, snapshot);
+
+ if (update) {
+ cellHandle.editorView.dispatch(update);
+ }
return {
...state,
@@ -1599,9 +1468,9 @@ const {
});
// We apply the middleware here (rather than inline in createReducerAndAtoms)
-// so that the document transaction middleware can import CellActions and
+// so that the document edit middleware can import CellActions and
// strictly type the dispatched actions without creating a circular dependency.
-addMiddleware(documentTransactionMiddleware);
+addMiddleware(documentEditMiddleware);
function isCellCodeHidden(state: NotebookState, cellId: CellId): boolean {
return (
diff --git a/frontend/src/core/cells/columns.ts b/frontend/src/core/cells/columns.ts
new file mode 100644
index 0000000000..1f2c86e9be
--- /dev/null
+++ b/frontend/src/core/cells/columns.ts
@@ -0,0 +1,38 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** How a document's cells fall into columns. */
+
+import type { EditableDocument } from "@/core/notebook/document";
+import type { CellId } from "./ids";
+
+/**
+ * Each cell's column: its `column` config, or the column of the cell before
+ * it. The first cell starts in column 0.
+ */
+export function resolveColumns(
+ document: EditableDocument,
+): Map<CellId, number> {
+ const columns = new Map<CellId, number>();
+ let current = 0;
+ for (const id of document.order) {
+ const column = document.cells.get(id)?.config.column;
+ if (column != null && column >= 0) {
+ current = column;
+ }
+ // The protocol's ids are plain strings; the notebook brands them.
+ columns.set(id as CellId, current);
+ }
+ return columns;
+}
+
+/** The cells of each column in order, with empty columns for gaps. */
+export function groupByColumn(document: EditableDocument): CellId[][] {
+ const columns: CellId[][] = [[]];
+ for (const [id, column] of resolveColumns(document)) {
+ while (columns.length <= column) {
+ columns.push([]);
+ }
+ columns[column].push(id);
+ }
+ return columns;
+}
diff --git a/frontend/src/core/cells/document-changes.ts b/frontend/src/core/cells/document-changes.ts
deleted file mode 100644
index 924b6bbcca..0000000000
--- a/frontend/src/core/cells/document-changes.ts
+++ /dev/null
@@ -1,944 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-/**
- * Document changes: the bridge between notebook reducer actions and the
- * document transaction wire format.
- *
- * Pure functions:
- * - toDocumentChanges: reducer action + state diff → document changes
- * - fromDocumentChanges: document changes → reducer actions
- * - cancelledCellIds: detect create+delete cancellations
- *
- * Impure wrappers (for use by the reducer middleware and websocket):
- * - documentTransactionMiddleware: debounces and sends changes to the server
- * - applyTransactionChanges: dispatches actions from incoming changes
- */
-
-import { debounce } from "lodash-es";
-import { assertNever } from "@/utils/assertNever";
-import type { DispatchedActionOf } from "@/utils/createReducer";
-import { Deferred } from "@/utils/Deferred";
-import { Logger } from "@/utils/Logger";
-import type { NotificationMessageData } from "../kernel/messages";
-import { kioskModeAtom } from "../mode";
-import { getRequestClient } from "../network/requests";
-import type { NotebookDocumentTransactionRequest } from "../network/types";
-import { store } from "../state/jotai";
-import type { CellActions, NotebookState } from "./cells";
-import type { CellId } from "./ids";
-import { SCRATCH_CELL_ID } from "./ids";
-import type { CellData } from "./types";
-
-export type DocumentChange =
- NotebookDocumentTransactionRequest["changes"][number];
-
-type Transaction =
- NotificationMessageData<"notebook-document-transaction">["transaction"];
-type TransactionChange = Transaction["changes"][number];
-
-export type CellAction = DispatchedActionOf<CellActions>;
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Look up a cell in state by ID. Logs a warning and returns undefined
- * if the cell doesn't exist.
- */
-function getCell(
- cellId: CellId | undefined,
- state: NotebookState,
-): CellData | undefined {
- if (!cellId) {
- Logger.warn("getCell: cellId is undefined");
- return undefined;
- }
- const cell = state.cellData[cellId];
- if (!cell) {
- Logger.warn(`getCell: cell ${cellId} not found in state`);
- return undefined;
- }
- return cell;
-}
-
-/**
- * Derive the position anchor for a cell from the notebook state.
- * Returns `{ after: prevId }` if there's a cell before it,
- * `{ before: nextId }` if it's the first cell, or `undefined` if it's alone.
- */
-function anchorOf(
- cellId: CellId,
- state: NotebookState,
-): { after: CellId } | { before: CellId } | undefined {
- const ids = state.cellIds.inOrderIds;
- const idx = ids.indexOf(cellId);
- if (idx > 0) {
- return { after: ids[idx - 1] };
- }
- if (idx === 0 && ids.length > 1) {
- return { before: ids[1] };
- }
- return undefined;
-}
-
-/**
- * Build a map from cellId → column index for all cells in the state.
- */
-function columnIndexMap(state: NotebookState): Map<CellId, number> {
- const map = new Map<CellId, number>();
- const columns = state.cellIds.getColumns();
- for (const [col, column] of columns.entries()) {
- for (const id of column.inOrderIds) {
- map.set(id, col);
- }
- }
- return map;
-}
-
-/**
- * Find cells that were added between prevState and newState and return
- * create-cell changes for each, with position derived from newState.
- */
-function newCellChanges(
- prevState: NotebookState,
- newState: NotebookState,
-): DocumentChange[] {
- const prevIds = new Set(prevState.cellIds.inOrderIds);
- const changes: DocumentChange[] = [];
- for (const id of newState.cellIds.inOrderIds) {
- if (!prevIds.has(id)) {
- const cell = getCell(id, newState);
- if (cell) {
- changes.push({
- type: "create-cell",
- cellId: cell.id,
- code: cell.code,
- name: cell.name,
- config: cell.config,
- ...anchorOf(cell.id, newState),
- });
- }
- }
- }
- return changes;
-}
-
-/**
- * Find cells that were removed between prevState and newState and return
- * delete-cell changes for each.
- */
-function deletedCellChanges(
- prevState: NotebookState,
- newState: NotebookState,
-): DocumentChange[] {
- const newIds = new Set(newState.cellIds.inOrderIds);
- const changes: DocumentChange[] = [];
- for (const id of prevState.cellIds.inOrderIds) {
- if (!newIds.has(id)) {
- changes.push({ type: "delete-cell", cellId: id });
- }
- }
- return changes;
-}
-
-/**
- * Produce set-config changes for cells whose column index changed between
- * prevState and newState, plus a reorder-cells change for the new ordering.
- */
-function columnChanges(
- prevState: NotebookState,
- newState: NotebookState,
-): DocumentChange[] {
- const prevColumns = columnIndexMap(prevState);
- const newColumns = columnIndexMap(newState);
- const changes: DocumentChange[] = [];
-
- for (const [cellId, newCol] of newColumns) {
- const prevCol = prevColumns.get(cellId);
- if (prevCol !== newCol) {
- const cell = getCell(cellId, newState);
- changes.push({
- type: "set-config",
- cellId: cellId,
- column: newCol,
- disabled: cell?.config.disabled ?? false,
- hideCode: cell?.config.hide_code ?? false,
- expandOutput: cell?.config.expand_output ?? false,
- });
- }
- }
-
- changes.push({
- type: "reorder-cells",
- cellIds: newState.cellIds.inOrderIds,
- });
-
- return changes;
-}
-
-// ---------------------------------------------------------------------------
-// toDocumentChanges: action + state → changes
-// ---------------------------------------------------------------------------
-
-/**
- * Given a reducer action and the before/after notebook state, return the
- * document changes that represent the diff. Returns an empty array for
- * actions that don't affect document structure.
- */
-export function toDocumentChanges(
- prevState: NotebookState,
- newState: NotebookState,
- action: DispatchedActionOf<CellActions>,
-): DocumentChange[] {
- switch (action.type) {
- // createNewCell → create-cell
- // Reads code, name, and config from the newly created cell in newState.
- // Position is derived from newState via anchorOf (after or before neighbor).
- case "createNewCell":
- return newCellChanges(prevState, newState);
-
- // deleteCell → delete-cell
- // Direct 1:1 mapping. Only the cellId is needed.
- case "deleteCell":
- return [{ type: "delete-cell", cellId: action.payload.cellId }];
-
- // moveCell/sendToTop/sendToBottom → move-cell
- // All three change a single cell's position. We derive the final
- // position from newState via anchorOf rather than interpreting the
- // action's before/direction payload.
- case "moveCell":
- case "sendToTop":
- case "sendToBottom": {
- const { cellId } = action.payload;
- return [
- {
- type: "move-cell",
- cellId: cellId,
- ...anchorOf(cellId, newState),
- },
- ];
- }
-
- // dropCellOverCell/dropCellOverColumn/moveCellToIndex/moveCellsRelativeTo → set-config + reorder-cells
- // Drag-and-drop reorders can move cells within or across columns.
- // We emit config changes for cells whose column changed, then
- // the full ordering.
- case "dropCellOverCell":
- case "dropCellOverColumn":
- case "moveCellToIndex":
- case "moveCellsRelativeTo":
- return columnChanges(prevState, newState);
-
- // updateCellCode → set-code
- // Reads the code from newState via getCell.
- case "updateCellCode": {
- const cell = getCell(action.payload.cellId, newState);
- if (!cell) {
- return [];
- }
- return [
- {
- type: "set-code",
- cellId: cell.id,
- code: cell.code,
- },
- ];
- }
-
- // updateCellName → set-name
- // Reads the name from newState via getCell.
- case "updateCellName": {
- const cell = getCell(action.payload.cellId, newState);
- if (!cell) {
- return [];
- }
- return [
- {
- type: "set-name",
- cellId: cell.id,
- name: cell.name,
- },
- ];
- }
-
- // updateCellConfig → set-config
- // SetConfig is full-replacement: emit the cell's complete config from
- // newState (which already merged the action's partial payload).
- case "updateCellConfig": {
- const { cellId } = action.payload;
- const cell = getCell(cellId, newState);
- if (!cell) {
- return [];
- }
- return [
- {
- type: "set-config",
- cellId: cellId,
- column: cell.config.column ?? null,
- disabled: cell.config.disabled ?? false,
- hideCode: cell.config.hide_code ?? false,
- expandOutput: cell.config.expand_output ?? false,
- },
- ];
- }
-
- // Column structure changes → set-config + reorder-cells
- // All of these change column layout. We emit config changes for
- // cells whose column index changed, then the full ordering.
- case "dropOverNewColumn":
- case "moveColumn":
- case "addColumnBreakpoint":
- case "deleteColumn":
- case "mergeAllColumns":
- case "compactColumns":
- return columnChanges(prevState, newState);
-
- // addColumn creates a new column with a new empty cell.
- // Emits create-cell for the new cell plus column layout changes.
- case "addColumn":
- return [
- ...newCellChanges(prevState, newState),
- ...columnChanges(prevState, newState),
- ];
-
- // undoDeleteCell restores a deleted cell from history.
- case "undoDeleteCell": {
- const changes = newCellChanges(prevState, newState);
- const colChanges = columnChanges(prevState, newState);
- // Undo-cut has no new cells — always emit reorder to sync the move.
- if (changes.length === 0) {
- return colChanges;
- }
- // Only include column changes if layout actually changed
- // (colChanges always has at least a reorder-cells change)
- return colChanges.length > 1 ? [...changes, ...colChanges] : changes;
- }
-
- // splitCell: original cell gets truncated code, new cell gets remainder.
- case "splitCell": {
- const { cellId } = action.payload;
- const cell = getCell(cellId, newState);
- if (!cell) {
- return [];
- }
- return [
- { type: "set-code", cellId, code: cell.code },
- ...newCellChanges(prevState, newState),
- ];
- }
-
- // undoSplitCell: merge next cell back into current, delete the next cell.
- case "undoSplitCell": {
- const { cellId } = action.payload;
- const cell = getCell(cellId, newState);
- if (!cell) {
- return [];
- }
- return [
- { type: "set-code", cellId, code: cell.code },
- ...deletedCellChanges(prevState, newState),
- ];
- }
-
- // moveToNextCell: may create a new cell at boundary.
- case "moveToNextCell":
- return newCellChanges(prevState, newState);
-
- // addSetupCellIfDoesntExist: creates setup cell if missing.
- case "addSetupCellIfDoesntExist":
- return newCellChanges(prevState, newState);
-
- // UI-only actions — no document changes.
- case "focusCell":
- case "focusTopCell":
- case "focusBottomCell":
- case "scrollToTarget":
- case "showCellIfHidden":
- case "markTouched":
- case "markUntouched":
- return [];
-
- // Kernel/runtime state — never produces document changes.
- case "prepareForRun":
- case "handleCellMessage":
- case "setCellIds":
- case "rebuildCellColumns":
- case "setCellCodes":
- case "setCells":
- case "setStdinResponse":
- case "clearSerializedEditorState":
- case "clearCellOutput":
- case "clearCellConsoleOutput":
- case "clearAllCellOutputs":
- case "clearLogs":
- case "addLogs":
- return [];
-
- // Editor UI state — no document changes.
- case "foldAll":
- case "unfoldAll":
- case "collapseCell":
- case "expandCell":
- case "collapseAllCells":
- case "expandAllCells":
- return [];
-
- default:
- assertNever(action);
- }
-}
-
-// ---------------------------------------------------------------------------
-// fromDocumentChanges: changes → actions
-// ---------------------------------------------------------------------------
-
-/**
- * Find cell IDs that are both created and deleted in a set of changes.
- * These cancel out and should be skipped.
- */
-export function cancelledCellIds(changes: TransactionChange[]): Set<string> {
- const created = new Set<string>();
- const deleted = new Set<string>();
- for (const change of changes) {
- if (change.type === "create-cell") {
- created.add(change.cellId);
- } else if (change.type === "delete-cell") {
- deleted.add(change.cellId);
- }
- }
- return created.intersection(deleted);
-}
-
-/**
- * Given document changes (from the server) and the current cell ordering,
- * return the reducer actions that apply them to frontend state.
- */
-export function fromDocumentChanges(
- changes: TransactionChange[],
- getCurrentCellIds: () => CellId[],
-): CellAction[] {
- const actions: CellAction[] = [];
-
- for (const change of changes) {
- switch (change.type) {
- // create-cell → createNewCell + updateCellName + updateCellConfig
- // Translates the change's before/after anchor into createNewCell's
- // cellId+before pair. The change carries code, name, and a full CellConfig.
- // createNewCell only accepts hideCode, so name and remaining config
- // (disabled, column) are applied as separate follow-up actions.
- case "create-cell": {
- let cellId: CellId | "__end__" = "__end__";
- let before = false;
- if (change.after) {
- cellId = change.after;
- before = false;
- } else if (change.before) {
- cellId = change.before;
- before = true;
- }
- actions.push({
- type: "createNewCell",
- payload: {
- cellId,
- before,
- code: change.code,
- newCellId: change.cellId,
- autoFocus: false,
- hideCode: change.config?.hide_code ?? false,
- },
- });
- if (change.name) {
- actions.push({
- type: "updateCellName",
- payload: { cellId: change.cellId, name: change.name },
- });
- }
- if (
- change.config?.disabled != null ||
- change.config?.column != null ||
- change.config?.expand_output != null
- ) {
- actions.push({
- type: "updateCellConfig",
- payload: {
- cellId: change.cellId,
- config: {
- ...(change.config.disabled != null && {
- disabled: change.config.disabled,
- }),
- ...(change.config.column != null && {
- column: change.config.column,
- }),
- ...(change.config.expand_output != null && {
- expand_output: change.config.expand_output,
- }),
- },
- },
- });
- }
- break;
- }
-
- // delete-cell → deleteCell
- // Direct 1:1 mapping.
- case "delete-cell":
- actions.push({
- type: "deleteCell",
- payload: { cellId: change.cellId },
- });
- break;
-
- // move-cell → setCellIds
- // Reconstructs the full ordering by splicing the cell out and
- // reinserting it relative to the before/after anchor. Falls back
- // to appending (after) or prepending (before) if the anchor is
- // missing. No-ops if the cell itself doesn't exist.
- case "move-cell": {
- const ids = [...getCurrentCellIds()];
- const cellId = change.cellId;
- const idx = ids.indexOf(cellId);
- if (idx < 0) {
- break;
- }
- ids.splice(idx, 1);
- if (change.after) {
- const afterIdx = ids.indexOf(change.after);
- if (afterIdx >= 0) {
- ids.splice(afterIdx + 1, 0, cellId);
- } else {
- ids.push(cellId);
- }
- } else if (change.before) {
- const beforeIdx = ids.indexOf(change.before);
- if (beforeIdx >= 0) {
- ids.splice(beforeIdx, 0, cellId);
- } else {
- ids.unshift(cellId);
- }
- } else {
- ids.push(cellId);
- }
- actions.push({
- type: "setCellIds",
- payload: { cellIds: ids },
- });
- break;
- }
-
- // reorder-cells → setCellIds
- // Replaces the full cell ordering. Used for drag-and-drop and
- // bulk reorders where expressing individual moves is impractical.
- case "reorder-cells":
- actions.push({
- type: "setCellIds",
- payload: { cellIds: change.cellIds },
- });
- break;
-
- // set-code → setCellCodes
- // Marks the code as stale (codeIsStale: true) since it came from
- // an external source and hasn't been executed yet.
- case "set-code":
- actions.push({
- type: "setCellCodes",
- payload: {
- ids: [change.cellId],
- codes: [change.code],
- codeIsStale: true,
- },
- });
- break;
-
- // set-name → updateCellName
- // Direct 1:1 mapping.
- case "set-name":
- actions.push({
- type: "updateCellName",
- payload: { cellId: change.cellId, name: change.name },
- });
- break;
-
- // set-config → updateCellConfig
- case "set-config":
- actions.push({
- type: "updateCellConfig",
- payload: {
- cellId: change.cellId,
- config: {
- column: change.column,
- disabled: change.disabled,
- hide_code: change.hideCode,
- expand_output: change.expandOutput,
- },
- },
- });
- break;
- }
- }
-
- return actions;
-}
-
-// ---------------------------------------------------------------------------
-// Coalescing: reduce a buffered change sequence to its net effect
-// ---------------------------------------------------------------------------
-
-const COLLAPSIBLE_TYPES = new Set(["set-code", "set-name", "set-config"]);
-const DROPPABLE_ON_DELETE = new Set([
- "set-code",
- "set-name",
- "set-config",
- "move-cell",
-]);
-
-/**
- * Reduce a buffered sequence of changes to an equivalent batch that reflects
- * net effect rather than edit history. The server applies a transaction
- * atomically and rejects internally contradictory batches (e.g. updating a
- * cell that is also deleted in the same transaction), so a debounced sequence
- * of edits must be reconciled before it is sent.
- *
- * Two reductions, both order-preserving:
- * - For any cell deleted in the batch, drop its property/move changes. The
- * `create-cell` and `delete-cell` are kept so anchors referencing the cell
- * stay resolvable on the server; create+delete applies to a net no-op.
- * - Collapse repeated `set-code`/`set-name`/`set-config` for a surviving cell
- * to the last occurrence.
- */
-export function coalesceChanges(changes: DocumentChange[]): DocumentChange[] {
- const deletedIds = new Set<CellId>();
- for (const change of changes) {
- if (change.type === "delete-cell") {
- deletedIds.add(change.cellId);
- }
- }
-
- const withoutEditsToDeletedCells = changes.filter(
- (change) =>
- !(
- DROPPABLE_ON_DELETE.has(change.type) &&
- "cellId" in change &&
- deletedIds.has(change.cellId)
- ),
- );
-
- const lastIndexByKey = new Map<string, number>();
- withoutEditsToDeletedCells.forEach((change, index) => {
- if (COLLAPSIBLE_TYPES.has(change.type) && "cellId" in change) {
- lastIndexByKey.set(`${change.type}:${change.cellId}`, index);
- }
- });
-
- return withoutEditsToDeletedCells.filter((change, index) => {
- if (COLLAPSIBLE_TYPES.has(change.type) && "cellId" in change) {
- return lastIndexByKey.get(`${change.type}:${change.cellId}`) === index;
- }
- return true;
- });
-}
-
-// ---------------------------------------------------------------------------
-// Middleware: debounced change dispatch to the server
-// ---------------------------------------------------------------------------
-
-let pendingChanges: DocumentChange[] = [];
-let stagedTransactions: DocumentChange[][] = [];
-let transactionQueue: Promise<void> = Promise.resolve();
-let transactionGeneration = 0;
-let activeDocumentSave: Deferred<void> | null = null;
-
-type TransactionSyncState =
- | { status: "synchronized" }
- | { status: "failed"; error: unknown };
-
-interface DocumentResync {
- failure: Extract<TransactionSyncState, { status: "failed" }>;
- includedChanges: DocumentChange[];
- includedTransactions: DocumentChange[][];
-}
-
-let transactionSyncState: TransactionSyncState = { status: "synchronized" };
-
-function stagePendingTransaction(): void {
- if (transactionSyncState.status === "failed") {
- return;
- }
- const changes = coalesceChanges(pendingChanges);
- pendingChanges = [];
- if (changes.length > 0) {
- stagedTransactions.push(changes);
- }
-}
-
-async function sendStagedTransactions(generation: number): Promise<void> {
- if (generation !== transactionGeneration) {
- return;
- }
- if (transactionSyncState.status === "failed") {
- throw transactionSyncState.error;
- }
-
- while (stagedTransactions.length > 0) {
- const changes = stagedTransactions[0];
-
- try {
- await getRequestClient().sendDocumentTransaction({ changes });
- } catch (error) {
- if (generation !== transactionGeneration) {
- return;
- }
- // A transport failure is ambiguous: the server may have applied the
- // transaction before the response was lost. Keep the failure sticky so
- // an export cannot claim synchronization without a fresh document.
- transactionSyncState = { status: "failed", error };
- stagedTransactions = stagedTransactions.slice(1);
- throw error;
- }
- if (generation !== transactionGeneration) {
- return;
- }
- stagedTransactions.shift();
- }
-}
-
-function queuePendingTransactions(): Promise<void> {
- const generation = transactionGeneration;
- const saveBarrier = activeDocumentSave?.promise ?? Promise.resolve();
- const queued = Promise.all([
- transactionQueue.catch(() => undefined),
- saveBarrier,
- ]).then(() => sendStagedTransactions(generation));
- transactionQueue = queued;
- return queued;
-}
-
-const flushChanges = debounce(() => {
- stagePendingTransaction();
- void queuePendingTransactions().catch(() => undefined);
-}, 400);
-
-export async function flushDocumentChanges(): Promise<void> {
- if (transactionSyncState.status === "failed") {
- throw transactionSyncState.error;
- }
- flushChanges.cancel();
- stagePendingTransaction();
- let awaitedQueue = queuePendingTransactions();
- while (true) {
- await awaitedQueue;
- flushChanges.cancel();
- stagePendingTransaction();
- if (
- pendingChanges.length === 0 &&
- stagedTransactions.length === 0 &&
- transactionQueue === awaitedQueue
- ) {
- return;
- }
- awaitedQueue =
- transactionQueue === awaitedQueue
- ? queuePendingTransactions()
- : transactionQueue;
- }
-}
-
-export function beginDocumentResync(): DocumentResync | null {
- if (transactionSyncState.status !== "failed") {
- return null;
- }
- flushChanges.cancel();
- const includedChanges = pendingChanges;
- const includedTransactions = stagedTransactions;
- pendingChanges = [];
- stagedTransactions = [];
- return {
- failure: transactionSyncState,
- includedChanges,
- includedTransactions,
- };
-}
-
-export function abortDocumentResync(resync: DocumentResync | null): void {
- if (resync === null || transactionSyncState !== resync.failure) {
- return;
- }
- pendingChanges = [...resync.includedChanges, ...pendingChanges];
- stagedTransactions = [...resync.includedTransactions, ...stagedTransactions];
-}
-
-export async function completeDocumentResync(
- resync: DocumentResync | null,
-): Promise<void> {
- if (resync === null) {
- return;
- }
- await transactionQueue.catch(() => undefined);
- if (transactionSyncState !== resync.failure) {
- return;
- }
- transactionSyncState = { status: "synchronized" };
- transactionQueue = Promise.resolve();
- if (pendingChanges.length > 0) {
- flushChanges();
- }
-}
-
-function releaseDocumentSave(barrier: Deferred<void>): void {
- if (activeDocumentSave === barrier) {
- activeDocumentSave = null;
- }
- barrier.resolve();
-}
-
-/**
- * Runs a full save after earlier document transactions and holds later
- * transactions until the save settles. A failed transaction makes the save
- * the authoritative document resync boundary.
- */
-export async function withDocumentSave<T>(save: () => Promise<T>): Promise<T> {
- let resync: DocumentResync | null = null;
- try {
- await flushDocumentChanges();
- } catch (error) {
- resync = beginDocumentResync();
- if (resync === null) {
- throw error;
- }
- }
-
- const barrier = new Deferred<void>();
- activeDocumentSave = barrier;
- try {
- const result = await save();
- releaseDocumentSave(barrier);
- await completeDocumentResync(resync);
- return result;
- } catch (error) {
- abortDocumentResync(resync);
- releaseDocumentSave(barrier);
- throw error;
- }
-}
-
-function isScratchChange(change: DocumentChange): boolean {
- if ("cellId" in change && change.cellId === SCRATCH_CELL_ID) {
- return true;
- }
- return false;
-}
-
-function enqueue(change: DocumentChange) {
- if (store.get(kioskModeAtom)) {
- return;
- }
- // The scratchpad cell is local-only — don't sync it to the document.
- if (isScratchChange(change)) {
- return;
- }
- pendingChanges.push(change);
- if (transactionSyncState.status === "synchronized") {
- flushChanges();
- }
-}
-
-/**
- * Middleware for the notebook reducer. Converts actions to document changes
- * via toDocumentChanges and enqueues them for debounced dispatch.
- */
-export function documentTransactionMiddleware(
- prevState: NotebookState,
- newState: NotebookState,
- action: CellAction,
-): void {
- for (const change of toDocumentChanges(prevState, newState, action)) {
- enqueue(change);
- }
-}
-
-// ---------------------------------------------------------------------------
-// Apply: dispatch incoming changes as reducer actions
-// ---------------------------------------------------------------------------
-
-/**
- * Apply document transaction changes to the frontend cell state.
- *
- * Each change is applied immediately and in order so that subsequent changes
- * see the state produced by earlier changes (e.g. move-cell after create-cell).
- */
-export function applyTransactionChanges(
- changes: TransactionChange[],
- actions: CellActions,
- getCurrentCellIds: () => CellId[],
-): void {
- const cancelled = cancelledCellIds(changes);
-
- // Process set-config changes after everything else. The tree must be fully
- // restructured (create-cell, delete-cell, reorder-cells, move-cell) before
- // we start applying column metadata, since the follow-up rebuildCellColumns
- // step interprets each cell's config.column against the *final* flat order.
- // Sorting is stable within each group.
- const sortedChanges: TransactionChange[] = [
- ...changes.filter((c) => c.type !== "set-config"),
- ...changes.filter((c) => c.type === "set-config"),
- ];
-
- // Track whether any change updated a cell's column, and remember the final
- // flat order produced by a reorder-cells change (if any). After all changes
- // are applied, these are used to rebuild the MultiColumn tree so that cells
- // physically move to the column their metadata says they belong in.
- let hasColumnChange = false;
- let reorderOrder: CellId[] | null = null;
-
- for (const change of sortedChanges) {
- if (
- cancelled.size > 0 &&
- "cellId" in change &&
- cancelled.has(change.cellId)
- ) {
- continue;
- }
- if (change.type === "set-config") {
- hasColumnChange = true;
- }
- if (change.type === "create-cell" && change.config?.column != null) {
- hasColumnChange = true;
- }
- if (change.type === "reorder-cells") {
- reorderOrder = change.cellIds as CellId[];
- }
- for (const action of fromDocumentChanges([change], getCurrentCellIds)) {
- // @ts-expect-error - TypeScript is not smart enough to know we have correctly mapped type -> payload
- actions[action.type](action.payload);
- }
- }
-
- if (hasColumnChange) {
- actions.rebuildCellColumns({
- cellIds: reorderOrder ?? getCurrentCellIds(),
- });
- }
-}
-
-// ---------------------------------------------------------------------------
-// Test helpers
-// ---------------------------------------------------------------------------
-
-export const exportedForTesting = {
- cancelPendingChanges: () => {
- flushChanges.cancel();
- activeDocumentSave?.resolve();
- activeDocumentSave = null;
- transactionGeneration += 1;
- pendingChanges = [];
- stagedTransactions = [];
- transactionSyncState = { status: "synchronized" };
- transactionQueue = Promise.resolve();
- },
- drainChanges: (): DocumentChange[] => {
- flushChanges.cancel();
- const drained = pendingChanges;
- pendingChanges = [];
- return drained;
- },
-};
diff --git a/frontend/src/core/cells/document.ts b/frontend/src/core/cells/document.ts
new file mode 100644
index 0000000000..c8b5eb20f1
--- /dev/null
+++ b/frontend/src/core/cells/document.ts
@@ -0,0 +1,360 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Keep the notebook state and the host document in step while cells live
+ * in both.
+ *
+ * TODO(MO-8028): Delete this module once components read cells from the
+ * document model and `notebookAtom` holds only runtime and editor state.
+ */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import { dequal as isEqual } from "dequal";
+import { createRef, type RefObject } from "react";
+import type { CellHandle } from "@/components/editor/notebook-cell";
+import type {
+ DocumentEdit,
+ DocumentEditor,
+ EditableCell,
+ EditableDocument,
+} from "@/core/notebook/document";
+import type { DispatchedActionOf } from "@/utils/createReducer";
+import { CollapsibleTree, MultiColumn } from "@/utils/id-tree";
+import { prepareCellCodeUpdate } from "../codemirror/language/cell-code";
+import type { CellConfig } from "../network/types";
+import { canUseRtc, isRtcEnabled } from "../rtc/state";
+import { store } from "../state/jotai";
+import { activeDocumentModelAtom } from "../session/active-notebook";
+import type { CellActions, NotebookState } from "./cells";
+import { groupByColumn } from "./columns";
+import type { CellId } from "./ids";
+import {
+ type CellData,
+ createCell,
+ createCellConfig,
+ createCellRuntimeState,
+ isEdited,
+} from "./types";
+
+type CellAction = DispatchedActionOf<CellActions>;
+
+// Following the document ----------------------------------------------------
+
+/** Rebuild the tree for `columns`, keeping column ids and collapsed sections. */
+function reconcileColumns(
+ current: MultiColumn<CellId>,
+ columns: CellId[][],
+): MultiColumn<CellId> {
+ const previous = current.getColumns();
+ // The document cannot hold an empty column, so keep the ones this client has.
+ while (previous[columns.length]?.length === 0) {
+ columns.push([]);
+ }
+ if (
+ columns.length === previous.length &&
+ columns.every((ids, index) => isEqual(ids, previous[index].inOrderIds))
+ ) {
+ return current;
+ }
+ return new MultiColumn(
+ columns.map((ids, index) =>
+ CollapsibleTree.fromWithPreviousShape(ids, previous[index]),
+ ),
+ );
+}
+
+/** The cell's data with the document's fields, and its editor brought along. */
+function followCell(
+ current: CellData,
+ cell: EditableCell,
+ handle: RefObject<CellHandle | null> | undefined,
+): CellData {
+ // Withheld source keeps the code this client has.
+ const code = cell.code ?? current.code;
+ const config = isEqual(current.config, cell.config)
+ ? current.config
+ : createCellConfig(cell.config);
+ if (
+ code === current.code &&
+ cell.name === current.name &&
+ config === current.config
+ ) {
+ return current;
+ }
+ if (code === current.code) {
+ return { ...current, name: cell.name, config };
+ }
+ // RTC cells follow Loro. Other editors take the host's code; one that
+ // shows it already, as the editor this client types in does, is left alone.
+ if (!isRtcEnabled() || !canUseRtc(current.id)) {
+ const view = handle?.current?.editorViewOrNull;
+ const update = view && prepareCellCodeUpdate(view.state, code);
+ if (update) {
+ view.dispatch(update);
+ }
+ }
+ return {
+ ...current,
+ code,
+ name: cell.name,
+ config,
+ edited: isEdited(current.lastCodeRun, code),
+ };
+}
+
+/**
+ * Make the notebook's cells and order follow the document.
+ *
+ * Returns the same state when nothing differs, so a local edit that the
+ * document already reflects changes nothing.
+ *
+ * TODO(MO-8028): Delete with `reconcileDocument` once cells are read from
+ * the document model.
+ */
+export function applyDocument(
+ state: NotebookState,
+ document: EditableDocument,
+): NotebookState {
+ const cellIds = reconcileColumns(state.cellIds, groupByColumn(document));
+ let { cellData, cellRuntime, cellHandles } = state;
+ for (const id of cellIds.inOrderIds) {
+ const cell = document.cells.get(id);
+ const current = state.cellData[id];
+ if (cell === undefined) {
+ continue;
+ }
+ if (current === undefined) {
+ // A new cell has no run to be edited from.
+ cellData = {
+ ...cellData,
+ [id]: createCell({
+ id,
+ code: cell.code ?? "",
+ name: cell.name,
+ config: createCellConfig(cell.config),
+ }),
+ };
+ cellRuntime = { ...cellRuntime, [id]: createCellRuntimeState() };
+ cellHandles = { ...cellHandles, [id]: createRef() };
+ continue;
+ }
+ const next = followCell(current, cell, state.cellHandles[id]);
+ if (next !== current) {
+ cellData = { ...cellData, [id]: next };
+ }
+ }
+ const present = new Set(cellIds.inOrderIds);
+ const removed = state.cellIds.inOrderIds.filter((id) => !present.has(id));
+ if (removed.length > 0) {
+ const gone = new Set(removed);
+ const keep = <V>(record: Record<CellId, V>): Record<CellId, V> =>
+ Object.fromEntries(
+ Object.entries(record).filter(([id]) => !gone.has(id as CellId)),
+ ) as Record<CellId, V>;
+ cellData = keep(cellData);
+ cellRuntime = keep(cellRuntime);
+ cellHandles = keep(cellHandles);
+ }
+ if (
+ cellIds === state.cellIds &&
+ cellData === state.cellData &&
+ removed.length === 0
+ ) {
+ return state;
+ }
+ return { ...state, cellIds, cellData, cellRuntime, cellHandles };
+}
+
+// Editing the document ------------------------------------------------------
+
+const CONFIG_FIELDS = ["disabled", "hide_code", "expand_output"] as const;
+
+/** The fields of `after` that differ from `before`, leaving `column` to the tree. */
+function configPatch(
+ before: CellConfig,
+ after: CellConfig,
+): Partial<Protocol.CellConfig> | null {
+ const patch: Partial<Protocol.CellConfig> = {};
+ for (const field of CONFIG_FIELDS) {
+ if (before[field] !== after[field]) {
+ patch[field] = after[field] ?? false;
+ }
+ }
+ return Object.keys(patch).length === 0 ? null : patch;
+}
+
+/**
+ * The `column` configs that make the document's columns match the tree's.
+ *
+ * A cell without a column follows the cell before it, so only cells whose
+ * resolved column differs from their position need one.
+ */
+function columnFixes(state: NotebookState): Array<[CellId, number | null]> {
+ const fixes: Array<[CellId, number | null]> = [];
+ const columns = state.cellIds.getColumns();
+ if (columns.length === 1) {
+ for (const id of columns[0].inOrderIds) {
+ const column = state.cellData[id].config.column;
+ if (column != null && column !== 0) {
+ fixes.push([id, null]);
+ }
+ }
+ return fixes;
+ }
+ let inherited = 0;
+ columns.forEach((column, target) => {
+ for (const id of column.inOrderIds) {
+ const configured = state.cellData[id].config.column;
+ const resolved =
+ configured != null && configured >= 0 ? configured : inherited;
+ if (resolved !== target) {
+ fixes.push([id, target]);
+ }
+ inherited = target;
+ }
+ });
+ return fixes;
+}
+
+/** The edit that makes the document match `next`, or null when it already does. */
+function diffNotebook(
+ prev: NotebookState,
+ next: NotebookState,
+): DocumentEdit | null {
+ const steps: Array<(tx: DocumentEditor) => void> = [];
+ const prevOrder = prev.cellIds.inOrderIds;
+ const nextOrder = next.cellIds.inOrderIds;
+ const prevIds = new Set(prevOrder);
+ const nextIds = new Set(nextOrder);
+ for (const id of prevOrder) {
+ if (!nextIds.has(id)) {
+ steps.push((tx) => tx.deleteCell(id));
+ }
+ }
+ const created: CellId[] = [];
+ for (const id of nextOrder) {
+ const cell = next.cellData[id];
+ const before = prev.cellData[id];
+ if (!prevIds.has(id) || before === undefined) {
+ created.push(id);
+ steps.push((tx) =>
+ tx.createCell({
+ id,
+ code: cell.code,
+ name: cell.name,
+ config: cell.config,
+ }),
+ );
+ continue;
+ }
+ if (before === cell) {
+ continue;
+ }
+ if (before.code !== cell.code) {
+ steps.push((tx) => tx.setCode(id, cell.code));
+ }
+ if (before.name !== cell.name) {
+ steps.push((tx) => tx.setName(id, cell.name));
+ }
+ const patch = configPatch(before.config, cell.config);
+ if (patch !== null) {
+ steps.push((tx) => tx.updateConfig(id, patch));
+ }
+ }
+ for (const [id, column] of columnFixes(next)) {
+ steps.push((tx) => tx.updateConfig(id, { column }));
+ }
+ // Created cells go to the end, so the order is set when they belong elsewhere.
+ const survivors = prevOrder.filter((id) => nextIds.has(id));
+ if (!isEqual(nextOrder, [...survivors, ...created])) {
+ steps.push((tx) => tx.setOrder(nextOrder));
+ }
+ if (steps.length === 0) {
+ return null;
+ }
+ return (tx) => {
+ for (const step of steps) {
+ step(tx);
+ }
+ };
+}
+
+/**
+ * Middleware for the notebook reducer. Writes what an action changed about
+ * the cells and their order into the document model as one edit.
+ *
+ * TODO(MO-8028): Each action family that moves onto the model removes its
+ * part of `diffNotebook`. The middleware goes with the last one, code.
+ */
+export function documentEditMiddleware(
+ prev: NotebookState,
+ next: NotebookState,
+ action: CellAction,
+): void {
+ // The kernel's cells replace the notebook rather than edit it.
+ if (action.type === "setCells") {
+ return;
+ }
+ if (prev.cellIds === next.cellIds && prev.cellData === next.cellData) {
+ return;
+ }
+ const model = store.get(activeDocumentModelAtom);
+ if (model === null) {
+ return;
+ }
+ const edit = diffNotebook(prev, next);
+ if (edit !== null) {
+ store.set(model.editAtom, edit);
+ }
+}
+
+// Commands that read the document on the host -------------------------------
+
+/**
+ * Send this client's edits to the host before a command that reads them
+ * there. Without a document or a backend, as on a static page, there is
+ * nothing to send and the command proceeds.
+ */
+export async function flushDocument(): Promise<void> {
+ const model = store.get(activeDocumentModelAtom);
+ if (
+ model === null ||
+ store.get(model.syncStatusAtom).status === "unavailable"
+ ) {
+ return;
+ }
+ await model.flush();
+}
+
+/**
+ * Run a legacy save after this client's edits reach the host, and keep
+ * later edits local until it finishes. The save carries the whole
+ * notebook and the host takes it as the document, so an edit sent
+ * meanwhile would be overwritten. When the edits cannot be sent the save
+ * still runs, and the model resumes against the saved document.
+ *
+ * TODO(MO-8028): Goes with the legacy save, along with the hold.
+ */
+export async function withDocumentSave<T>(save: () => Promise<T>): Promise<T> {
+ const model = store.get(activeDocumentModelAtom);
+ if (model === null) {
+ return save();
+ }
+ let flushed = true;
+ try {
+ await model.flush();
+ } catch {
+ flushed = false;
+ }
+ const release = model.hold();
+ let result: T;
+ try {
+ result = await save();
+ } finally {
+ release();
+ }
+ if (!flushed) {
+ void model.retry().catch(() => undefined);
+ }
+ return result;
+}
diff --git a/frontend/src/core/cells/types.ts b/frontend/src/core/cells/types.ts
index 0193ddf41c..351c6fa4b8 100644
--- a/frontend/src/core/cells/types.ts
+++ b/frontend/src/core/cells/types.ts
@@ -8,6 +8,18 @@ import type { CellId } from "./ids";
import { DEFAULT_CELL_NAME } from "./names";
import type { Outline } from "./outline";
+/**
+ * Whether a cell's code has changed since it last ran. A cell that never ran
+ * is edited once it has code. Whitespace at the ends does not count.
+ *
+ * TODO(MO-8028): Temporary until staleness comes from the host's executions.
+ */
+export function isEdited(lastCodeRun: string | null, code: string): boolean {
+ return lastCodeRun === null
+ ? code.trim().length > 0
+ : lastCodeRun.trim() !== code.trim();
+}
+
/**
* Create a new cell with default state.
*/
diff --git a/frontend/src/core/codemirror/cells/__tests__/extensions.test.ts b/frontend/src/core/codemirror/cells/__tests__/extensions.test.ts
index e1bd55578b..103520171b 100644
--- a/frontend/src/core/codemirror/cells/__tests__/extensions.test.ts
+++ b/frontend/src/core/codemirror/cells/__tests__/extensions.test.ts
@@ -11,7 +11,8 @@ import { formattingChangeEffect } from "../../format";
import { loroSyncAnnotation } from "../../rtc/loro/sync";
import { exportedForTesting } from "../extensions";
-const { shouldAutorunMarkdownUpdate } = exportedForTesting;
+const { isCollaboratorUpdate, shouldAutorunMarkdownUpdate } =
+ exportedForTesting;
function createTransaction(spec: TransactionSpec) {
return EditorState.create({ doc: "" }).update(spec);
@@ -125,3 +126,28 @@ describe("shouldAutorunMarkdownUpdate", () => {
).toBe(false);
});
});
+
+describe("isCollaboratorUpdate", () => {
+ it("recognizes an update made only of Loro sync transactions", () => {
+ const transaction = createTransaction({
+ changes: { from: 0, insert: "#" },
+ annotations: [loroSyncAnnotation.of(true)],
+ });
+
+ expect(isCollaboratorUpdate([transaction])).toBe(true);
+ });
+
+ it("treats typing beside a Loro sync transaction as local", () => {
+ const remote = createTransaction({
+ changes: { from: 0, insert: "#" },
+ annotations: [loroSyncAnnotation.of(true)],
+ });
+ const local = createTransaction({
+ changes: { from: 0, insert: "x" },
+ annotations: [Transaction.userEvent.of("input.type")],
+ });
+
+ expect(isCollaboratorUpdate([remote, local])).toBe(false);
+ expect(isCollaboratorUpdate([])).toBe(false);
+ });
+});
diff --git a/frontend/src/core/codemirror/cells/extensions.ts b/frontend/src/core/codemirror/cells/extensions.ts
index 966dc8a5a0..f3d2de0401 100644
--- a/frontend/src/core/codemirror/cells/extensions.ts
+++ b/frontend/src/core/codemirror/cells/extensions.ts
@@ -325,6 +325,11 @@ function cellKeymaps({
function cellCodeEditing(hotkeys: HotkeyProvider): Extension[] {
const onChangePlugin = EditorView.updateListener.of((update) => {
if (update.docChanged) {
+ // Loro already applied a collaborator's change here. The client that
+ // typed it syncs it to the document.
+ if (isCollaboratorUpdate(update.transactions)) {
+ return;
+ }
// Check if the doc update was a formatting change
// e.g. changing from python to markdown
const isFormattingChange = update.transactions.some((tr) =>
@@ -350,6 +355,14 @@ function cellCodeEditing(hotkeys: HotkeyProvider): Extension[] {
return [onChangePlugin, formatKeymapExtension(hotkeys)];
}
+/** Whether every transaction in an update arrived from a collaborator through Loro. */
+function isCollaboratorUpdate(transactions: readonly Transaction[]): boolean {
+ return (
+ transactions.length > 0 &&
+ transactions.every((tr) => tr.annotation(loroSyncAnnotation) !== undefined)
+ );
+}
+
const MARKDOWN_AUTORUN_USER_EVENTS = ["input", "delete", "undo", "redo"];
function shouldAutorunMarkdownUpdate({
@@ -467,5 +480,6 @@ export function cellBundle({
}
export const exportedForTesting = {
+ isCollaboratorUpdate,
shouldAutorunMarkdownUpdate,
};
diff --git a/frontend/src/core/codemirror/format.ts b/frontend/src/core/codemirror/format.ts
index 297b02f267..09b70855ed 100644
--- a/frontend/src/core/codemirror/format.ts
+++ b/frontend/src/core/codemirror/format.ts
@@ -18,10 +18,8 @@ import { cellIdState } from "./config/extension";
import { languageAdapterState } from "./language/extension";
import { SCHEMA_CACHE } from "./language/languages/sql/completion-store";
import { isKnownDialect } from "./language/languages/sql/utils";
-import {
- getEditorCodeAsPython,
- updateEditorCodeFromPython,
-} from "./language/utils";
+import { prepareCellCodeUpdate } from "./language/cell-code";
+import { getEditorCodeAsPython } from "./language/utils";
import { replaceEditorContent } from "./replace-editor-content";
export const formattingChangeEffect = StateEffect.define<boolean>();
@@ -62,7 +60,10 @@ export async function formatEditorViews(views: Record<CellId, EditorView>) {
code: formattedCode,
formattingChange: true,
});
- updateEditorCodeFromPython(view, formattedCode);
+ const update = prepareCellCodeUpdate(view.state, formattedCode);
+ if (update) {
+ view.dispatch(update);
+ }
}
}
diff --git a/frontend/src/core/codemirror/language/__tests__/utils.test.ts b/frontend/src/core/codemirror/language/__tests__/utils.test.ts
index 81ea27aa1b..c41eb37fc3 100644
--- a/frontend/src/core/codemirror/language/__tests__/utils.test.ts
+++ b/frontend/src/core/codemirror/language/__tests__/utils.test.ts
@@ -1,23 +1,35 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { EditorState } from "@codemirror/state";
+import { history, redo, undo } from "@codemirror/commands";
+import { EditorSelection, EditorState, StateEffect } from "@codemirror/state";
import { EditorView } from "@codemirror/view";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
import { cellId } from "@/__tests__/branded";
import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
import { cellConfigExtension } from "../../config/extension";
-import { adaptiveLanguageConfiguration, switchLanguage } from "../extension";
+import { prepareCellCodeUpdate } from "../cell-code";
+import { languageMetadataField } from "../metadata";
import {
- getEditorCodeAsPython,
- splitEditor,
- updateEditorCodeFromPython,
-} from "../utils";
+ adaptiveLanguageConfiguration,
+ languageAdapterState,
+ switchLanguage,
+} from "../extension";
+import { getEditorCodeAsPython, splitEditor } from "../utils";
+
+const views: EditorView[] = [];
+
+afterEach(() => {
+ for (const view of views.splice(0)) {
+ view.destroy();
+ }
+});
function createEditor(doc: string) {
- return new EditorView({
+ const view = new EditorView({
state: EditorState.create({
doc,
extensions: [
+ history(),
adaptiveLanguageConfiguration({
completionConfig: {
activate_on_typing: true,
@@ -50,6 +62,8 @@ function createEditor(doc: string) {
],
}),
});
+ views.push(view);
+ return view;
}
describe("getEditorCodeAsPython", () => {
@@ -72,14 +86,172 @@ describe("getEditorCodeAsPython", () => {
});
});
-describe("updateEditorCodeFromPython", () => {
- it("should update the editor code with the provided Python code", () => {
- const mockEditor = createEditor("");
- const pythonCode = "print('Hello, World!')";
- const result = updateEditorCodeFromPython(mockEditor, pythonCode);
- expect(result).toEqual(pythonCode);
- expect(mockEditor.state.doc.toString()).toEqual(pythonCode);
+describe("prepareCellCodeUpdate transactions", () => {
+ it("applies text and metadata together, including metadata-only undo", () => {
+ const view = createEditor('mo.md(r"hi")');
+ switchLanguage(view, { language: "markdown" });
+ const observed: Array<{ text: string; prefix: string }> = [];
+ view.dispatch({
+ effects: StateEffect.appendConfig.of(
+ EditorView.updateListener.of((update) => {
+ if (
+ update.transactions.some(
+ (tr) => tr.effects.length > 0 || tr.docChanged,
+ )
+ ) {
+ observed.push({
+ text: update.state.doc.toString(),
+ prefix: update.state.field(languageMetadataField).quotePrefix,
+ });
+ }
+ }),
+ ),
+ });
+ observed.length = 0;
+
+ view.dispatch(prepareCellCodeUpdate(view.state, 'mo.md(f"hi")')!);
+ expect(observed).toEqual([{ text: "hi", prefix: "f" }]);
+ expect(undo(view)).toBe(true);
+ expect(view.state.field(languageMetadataField).quotePrefix).toBe("r");
+ expect(redo(view)).toBe(true);
+ expect(view.state.field(languageMetadataField).quotePrefix).toBe("f");
+ });
+
+ it("clears incompatible history while applying a language fallback atomically", () => {
+ const view = createEditor('mo.md("hi")');
+ switchLanguage(view, { language: "markdown" });
+ view.dispatch({ changes: { from: 2, insert: "!" } });
+ const observed: Array<{ text: string; language: string }> = [];
+ view.dispatch({
+ effects: StateEffect.appendConfig.of(
+ EditorView.updateListener.of((update) => {
+ observed.push({
+ text: update.state.doc.toString(),
+ language: update.state.field(languageAdapterState).type,
+ });
+ }),
+ ),
+ });
+ observed.length = 0;
+
+ view.dispatch(prepareCellCodeUpdate(view.state, "x = 1")!);
+ expect(observed).toEqual([{ text: "x = 1", language: "python" }]);
+ expect(undo(view)).toBe(false);
+ view.dispatch({ changes: { from: 5, insert: "0" } });
+ expect(undo(view)).toBe(true);
+ expect(view.state.doc.toString()).toBe("x = 1");
});
+
+ it("maps the selection through separate edits and keeps the update undoable", () => {
+ const view = createEditor("a = 1\nb = 2\nc = 3");
+ view.dispatch({ selection: EditorSelection.range(6, 11) });
+ view.dispatch(
+ prepareCellCodeUpdate(view.state, "alpha = 1\nb = 2\ncharlie = 3")!,
+ );
+ expect(
+ view.state.sliceDoc(
+ view.state.selection.main.from,
+ view.state.selection.main.to,
+ ),
+ ).toBe("b = 2");
+ expect(undo(view)).toBe(true);
+ expect(view.state.doc.toString()).toBe("a = 1\nb = 2\nc = 3");
+ });
+
+ it.each(["mo.md()", 'mo.md("hi")', 'df = mo.sql("SELECT 1")'])(
+ "keeps Python mode when receiving %s",
+ (code) => {
+ const view = createEditor("mo.md");
+ view.dispatch(prepareCellCodeUpdate(view.state, code)!);
+ expect({
+ language: view.state.field(languageAdapterState).type,
+ code: view.state.doc.toString(),
+ }).toEqual({ language: "python", code });
+ },
+ );
+
+ it.each([
+ {
+ language: "markdown",
+ initial: 'mo.md("hi")',
+ next: 'mo.md("bye")',
+ text: "bye",
+ },
+ {
+ language: "sql",
+ initial: 'df = mo.sql("SELECT 1")',
+ next: 'df = mo.sql("SELECT 2")',
+ text: "SELECT 2",
+ },
+ ] as const)(
+ "preserves compatible $language mode",
+ ({ language, initial, next, text }) => {
+ const view = createEditor(initial);
+ switchLanguage(view, { language });
+ view.dispatch(prepareCellCodeUpdate(view.state, next)!);
+ expect({
+ language: view.state.field(languageAdapterState).type,
+ code: view.state.doc.toString(),
+ }).toEqual({ language, code: text });
+ },
+ );
+
+ it.each([
+ {
+ language: "markdown",
+ initial: 'mo.md("hi")',
+ next: 'df = mo.sql("SELECT 1")',
+ },
+ {
+ language: "sql",
+ initial: 'df = mo.sql("SELECT 1")',
+ next: 'mo.md("hi")',
+ },
+ { language: "markdown", initial: 'mo.md("hi")', next: "x = 1" },
+ ] as const)(
+ "falls back from $language to Python for $next",
+ ({ language, initial, next }) => {
+ const view = createEditor(initial);
+ switchLanguage(view, { language });
+ view.dispatch(prepareCellCodeUpdate(view.state, next)!);
+ expect({
+ language: view.state.field(languageAdapterState).type,
+ code: view.state.doc.toString(),
+ }).toEqual({ language: "python", code: next });
+ },
+ );
+});
+
+describe("prepareCellCodeUpdate", () => {
+ it("does not normalize an editor that already represents the source", () => {
+ const view = createEditor('mo.md("hi")');
+ switchLanguage(view, { language: "markdown" });
+ expect(prepareCellCodeUpdate(view.state, 'mo.md("hi")')).toBeNull();
+ view.dispatch({ changes: { from: 2, insert: "\n " } });
+ const source = getEditorCodeAsPython(view);
+ expect(prepareCellCodeUpdate(view.state, source)).toBeNull();
+ expect(view.state.doc.toString()).toBe("hi\n ");
+ });
+
+ it.each(["", 'mo.md(f"hi {x}")'])(
+ "prepares initialization from %j without mutating the editor",
+ (initial) => {
+ const view = createEditor(initial);
+ const update = prepareCellCodeUpdate(view.state, 'mo.md(f"hi {x}")', {
+ initialize: true,
+ });
+ expect(view.state.doc.toString()).toBe(initial);
+ expect(view.state.field(languageAdapterState).type).toBe("python");
+ expect(update).not.toBeNull();
+ if (update) {
+ view.dispatch(update);
+ }
+ expect(view.state.doc.toString()).toBe("hi {x}");
+ expect(view.state.field(languageAdapterState).type).toBe("markdown");
+ expect(view.state.field(languageMetadataField).quotePrefix).toBe("f");
+ expect(undo(view)).toBe(false);
+ },
+ );
});
describe("splitEditor", () => {
diff --git a/frontend/src/core/codemirror/language/cell-code.ts b/frontend/src/core/codemirror/language/cell-code.ts
new file mode 100644
index 0000000000..d0f8ebaefb
--- /dev/null
+++ b/frontend/src/core/codemirror/language/cell-code.ts
@@ -0,0 +1,114 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { diff } from "@codemirror/merge";
+import {
+ type EditorState,
+ type StateEffect,
+ Transaction,
+ type TransactionSpec,
+} from "@codemirror/state";
+import { suppressSignatureHelp } from "@marimo-team/codemirror-languageserver";
+import { dequal } from "dequal";
+import {
+ languageAdapterFromCode,
+ languageAdapterState,
+ languageConfigurationEffects,
+} from "./extension";
+import { LanguageAdapters } from "./LanguageAdapters";
+import { sqlDialectEffect } from "./languages/sql/sql";
+import { languageMetadataField, setLanguageMetadata } from "./metadata";
+
+/** The Python source represented by the editor's text and language metadata. */
+export function getCellCode(state: EditorState): string {
+ const text = state.doc.toString();
+ const adapter = state.field(languageAdapterState, false);
+ return adapter
+ ? adapter.transformOut(
+ text,
+ state.field(languageMetadataField, false) ?? {},
+ )[0]
+ : text;
+}
+
+/** Account for adapters normalizing quotes and whitespace when reading source. */
+export function editorShowsCellCode(
+ state: EditorState,
+ source: string,
+): boolean {
+ if (getCellCode(state) === source) {
+ return true;
+ }
+ const adapter = state.field(languageAdapterState, false);
+ if (!adapter?.isSupported(source)) {
+ return false;
+ }
+ const [text, , metadata] = adapter.transformIn(source);
+ return (
+ text === state.doc.toString() &&
+ dequal(metadata, state.field(languageMetadataField, false))
+ );
+}
+
+/**
+ * Prepare one update to the editor's text, language, and metadata.
+ * Existing editors keep a compatible mode; only initial loading infers one.
+ * The caller decides whether this is a local edit or a remote synchronization.
+ */
+export function prepareCellCodeUpdate(
+ state: EditorState,
+ source: string,
+ { initialize = false }: { initialize?: boolean } = {},
+): TransactionSpec | null {
+ const current = state.field(languageAdapterState, false);
+ let target = current;
+ if (current) {
+ if (initialize) {
+ target = languageAdapterFromCode(source);
+ } else if (!current.isSupported(source)) {
+ target = LanguageAdapters.python;
+ }
+ }
+ const languageChanged = target?.type !== current?.type;
+ if (!languageChanged && editorShowsCellCode(state, source)) {
+ return null;
+ }
+
+ const effects: StateEffect<unknown>[] = [];
+ let text = source;
+ if (target) {
+ if (languageChanged) {
+ effects.push(...languageConfigurationEffects(state, target));
+ }
+ const [inner, , metadata] = target.transformIn(source);
+ text = inner;
+ const metadataChanged = !dequal(
+ metadata,
+ state.field(languageMetadataField, false),
+ );
+ if (metadataChanged) {
+ effects.push(setLanguageMetadata.of(metadata));
+ }
+ if (target.type === "sql" && (languageChanged || metadataChanged)) {
+ effects.push(sqlDialectEffect(metadata.engine));
+ }
+ }
+
+ // Match the merge view's scan limit so large rewrites stay bounded. The diff
+ // maps selections, folds, and diagnostics through each individual edit.
+ const changes = diff(state.doc.toString(), text, { scanLimit: 500 }).map(
+ (change) => ({
+ from: change.fromA,
+ to: change.toA,
+ insert: text.slice(change.fromB, change.toB),
+ }),
+ );
+ return {
+ changes,
+ effects,
+ annotations: [
+ suppressSignatureHelp.of(true),
+ // History was reset with the language; the previous text uses another representation.
+ ...(languageChanged ? [Transaction.addToHistory.of(false)] : []),
+ ],
+ };
+}
diff --git a/frontend/src/core/codemirror/language/extension.ts b/frontend/src/core/codemirror/language/extension.ts
index 54ee67a94e..6a557ea60a 100644
--- a/frontend/src/core/codemirror/language/extension.ts
+++ b/frontend/src/core/codemirror/language/extension.ts
@@ -1,11 +1,13 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { history } from "@codemirror/commands";
+import { history, historyField, invertedEffects } from "@codemirror/commands";
import {
Compartment,
EditorSelection,
+ EditorState,
StateEffect,
StateField,
+ Transaction,
} from "@codemirror/state";
import { type EditorView, keymap, showPanel } from "@codemirror/view";
import type { CellId } from "@/core/cells/ids";
@@ -25,11 +27,10 @@ import {
placeholderState,
} from "../config/extension";
import type { PlaceholderType } from "../config/types";
-import { historyCompartment } from "../editing/extensions";
import { formattingChangeEffect } from "../format";
import { createPanel } from "../react-dom/createPanel";
import { getLanguageAdapters, LanguageAdapters } from "./LanguageAdapters";
-import { initializeSQLDialect } from "./languages/sql/sql";
+import { sqlDialectEffect } from "./languages/sql/sql";
import type { LanguageMetadata } from "./metadata";
import { languageMetadataField, setLanguageMetadata } from "./metadata";
import { LanguagePanelComponent } from "./panel/panel";
@@ -42,6 +43,32 @@ import { getEditorCodeAsPython } from "./utils";
*/
const languageCompartment = new Compartment();
+/** Reconfigure a language and discard history written in its previous representation. */
+export function languageConfigurationEffects(
+ state: EditorState,
+ language: LanguageAdapter,
+): StateEffect<unknown>[] {
+ const extensions = language.getExtension({
+ cellId: state.facet(cellIdState),
+ completionConfig: state.facet(completionConfigState),
+ hotkeys: state.facet(hotkeysProviderState),
+ placeholderType: state.facet(placeholderState),
+ lspConfig: state.facet(lspConfigState),
+ });
+ if (state.field(historyField, false) !== undefined) {
+ // A fresh initializer resets the history in the same transaction as the language.
+ extensions.push(
+ historyField.init(() =>
+ EditorState.create({ extensions: [history()] }).field(historyField),
+ ),
+ );
+ }
+ return [
+ setLanguageAdapter.of(language),
+ languageCompartment.reconfigure(extensions),
+ ];
+}
+
/**
* State effect to set the language adapter.
*/
@@ -129,11 +156,6 @@ function updateLanguageAdapterAndCode({
}) {
const currentLanguage = view.state.field(languageAdapterState);
const code = view.state.doc.toString();
- const completionConfig = view.state.facet(completionConfigState);
- const hotkeysProvider = view.state.facet(hotkeysProviderState);
- const placeholderType = view.state.facet(placeholderState);
- const cellId = view.state.facet(cellIdState);
- const lspConfig = view.state.facet(lspConfigState);
let metadata = view.state.field(languageMetadataField);
let cursor = view.state.selection.main.head;
@@ -164,22 +186,15 @@ function updateLanguageAdapterAndCode({
// Update the state
view.dispatch({
effects: [
- setLanguageAdapter.of(nextLanguage),
+ ...languageConfigurationEffects(view.state, nextLanguage),
setLanguageMetadata.of(metadata),
- languageCompartment.reconfigure(
- nextLanguage.getExtension({
- cellId,
- completionConfig,
- hotkeys: hotkeysProvider,
- placeholderType,
- lspConfig,
- }),
- ),
- // Clear history
- historyCompartment.reconfigure([]),
+ ...(nextLanguage.type === "sql"
+ ? [sqlDialectEffect(metadata.engine)]
+ : []),
// Let downstream extensions know that this is a formatting change
formattingChangeEffect.of(true),
],
+ annotations: Transaction.addToHistory.of(false),
changes: opts.keepCodeAsIs
? undefined
: {
@@ -189,16 +204,6 @@ function updateLanguageAdapterAndCode({
},
selection: opts.keepCodeAsIs ? undefined : EditorSelection.cursor(cursor),
});
-
- // Add history back
- view.dispatch({
- effects: [historyCompartment.reconfigure([history()])],
- });
-
- // Initialize SQL dialect if switching to SQL
- if (nextLanguage.type === "sql") {
- initializeSQLDialect(view);
- }
}
/**
@@ -228,6 +233,18 @@ export function adaptiveLanguageConfiguration(opts: {
),
languageAdapterState,
languageMetadataField,
+ invertedEffects.of((tr) => {
+ if (!tr.effects.some((effect) => effect.is(setLanguageMetadata))) {
+ return [];
+ }
+ const metadata = tr.startState.field(languageMetadataField);
+ return [
+ setLanguageMetadata.of(metadata),
+ ...(tr.startState.field(languageAdapterState).type === "sql"
+ ? [sqlDialectEffect(metadata.engine)]
+ : []),
+ ];
+ }),
];
}
diff --git a/frontend/src/core/codemirror/language/languages/sql/sql.ts b/frontend/src/core/codemirror/language/languages/sql/sql.ts
index c215fbafee..8a82b5a80f 100644
--- a/frontend/src/core/codemirror/language/languages/sql/sql.ts
+++ b/frontend/src/core/codemirror/language/languages/sql/sql.ts
@@ -2,7 +2,7 @@
import { acceptCompletion, autocompletion } from "@codemirror/autocomplete";
import { insertTab } from "@codemirror/commands";
-import { type SQLDialect, type SQLNamespace, sql } from "@codemirror/lang-sql";
+import { type SQLNamespace, sql } from "@codemirror/lang-sql";
import type { EditorState, Extension } from "@codemirror/state";
import { Compartment } from "@codemirror/state";
import {
@@ -497,12 +497,12 @@ function isDuckDBConnection(
}
/**
- * Update the SQL dialect in the editor view.
+ * The effect that reconfigures the SQL language for the connection's dialect.
+ * Callers dispatch it, alone or with the change that selected the connection.
*/
-function updateSQLDialect(view: EditorView, dialect: SQLDialect) {
- view.dispatch({
- effects: sqlConfigCompartment.reconfigure(sql({ dialect })),
- });
+export function sqlDialectEffect(connectionName: ConnectionName) {
+ const dialect = SCHEMA_CACHE.getDialect(connectionName);
+ return sqlConfigCompartment.reconfigure(sql({ dialect }));
}
// Helper functions to update the SQL dialect
@@ -511,17 +511,7 @@ export function updateSQLDialectFromConnection(
view: EditorView,
connectionName: ConnectionName,
) {
- const dialect = SCHEMA_CACHE.getDialect(connectionName);
- updateSQLDialect(view, dialect);
-}
-
-export function initializeSQLDialect(view: EditorView) {
- // Get current engine and update dialect
- const metadata = getSQLMetadata(view.state);
- const connectionName = metadata.engine;
- const dialect = SCHEMA_CACHE.getDialect(connectionName);
-
- updateSQLDialect(view, dialect);
+ view.dispatch({ effects: sqlDialectEffect(connectionName) });
}
function getSQLMetadata(state: EditorState): SQLLanguageAdapterMetadata {
diff --git a/frontend/src/core/codemirror/language/utils.ts b/frontend/src/core/codemirror/language/utils.ts
index 0cc2ee6cf7..241d241e29 100644
--- a/frontend/src/core/codemirror/language/utils.ts
+++ b/frontend/src/core/codemirror/language/utils.ts
@@ -2,12 +2,8 @@
import type { EditorState } from "@codemirror/state";
import type { EditorView } from "@codemirror/view";
-import { replaceEditorContent } from "../replace-editor-content";
-import {
- languageAdapterFromCode,
- languageAdapterState,
- switchLanguage,
-} from "./extension";
+import { getCellCode } from "./cell-code";
+import { languageAdapterState } from "./extension";
import { languageMetadataField } from "./metadata";
/**
@@ -19,42 +15,16 @@ export function getEditorCodeAsPython(
fromPos?: number,
toPos?: number,
): string {
+ if (fromPos === undefined) {
+ return getCellCode(editor.state);
+ }
const languageAdapter = editor.state.field(languageAdapterState);
const metadata = editor.state.field(languageMetadataField);
const editorText = editor.state.doc.toString();
- if (fromPos !== undefined) {
- return languageAdapter.transformOut(
- editorText.slice(fromPos, toPos),
- metadata,
- )[0];
- }
- return languageAdapter.transformOut(editorText, metadata)[0];
-}
-
-/**
- * Update the editor code from Python code
- * Handles when the editor is showing a different language (e.g. markdown)
- */
-export function updateEditorCodeFromPython(
- editor: EditorView,
- pythonCode: string,
-): string {
- const currentAdapter = editor.state.field(languageAdapterState);
- const correctAdapter = languageAdapterFromCode(pythonCode);
-
- // If the language type changed (e.g., markdown → python), switch adapters
- if (correctAdapter.type !== currentAdapter.type) {
- switchLanguage(editor, {
- language: correctAdapter.type,
- keepCodeAsIs: true,
- });
- }
-
- const languageAdapter = editor.state.field(languageAdapterState);
- const [code] = languageAdapter.transformIn(pythonCode);
- // Use replaceEditorContent which preserves cursor position when focused
- replaceEditorContent(editor, code);
- return code;
+ return languageAdapter.transformOut(
+ editorText.slice(fromPos, toPos),
+ metadata,
+ )[0];
}
/**
diff --git a/frontend/src/core/codemirror/lsp/notebook-lsp.ts b/frontend/src/core/codemirror/lsp/notebook-lsp.ts
index 3cc2203bfd..d721dd51ba 100644
--- a/frontend/src/core/codemirror/lsp/notebook-lsp.ts
+++ b/frontend/src/core/codemirror/lsp/notebook-lsp.ts
@@ -12,10 +12,8 @@ import { Objects } from "@/utils/objects";
import { isRecord } from "@/utils/records";
import { getPositionAtWordBounds } from "../completion/hints";
import { topologicalCodesAtom } from "../copilot/getCodes";
-import {
- getEditorCodeAsPython,
- updateEditorCodeFromPython,
-} from "../language/utils";
+import { prepareCellCodeUpdate } from "../language/cell-code";
+import { getEditorCodeAsPython } from "../language/utils";
import { createNotebookLens, type NotebookLens } from "./lens";
import { normalizeLspDocumentation } from "./normalize-markdown-math";
import {
@@ -770,7 +768,10 @@ export class NotebookLanguageServerClient implements ILanguageServerClient {
// Only update if it has changed
const code = getEditorCodeAsPython(ev);
if (code !== newCode) {
- updateEditorCodeFromPython(ev, newCode);
+ const update = prepareCellCodeUpdate(ev.state, newCode);
+ if (update) {
+ ev.dispatch(update);
+ }
updatedCount++;
}
}
diff --git a/frontend/src/core/codemirror/rtc/extension.ts b/frontend/src/core/codemirror/rtc/extension.ts
index 257acae3ce..3e28056bc8 100644
--- a/frontend/src/core/codemirror/rtc/extension.ts
+++ b/frontend/src/core/codemirror/rtc/extension.ts
@@ -172,7 +172,6 @@ awareness.addListener((updates, origin) => {
export function realTimeCollaboration(
cellId: CellId,
- _updateCellCode: (code: string) => void,
initialCode = "",
): { extension: Extension; code: string } {
if (isWasm()) {
diff --git a/frontend/src/core/edit-app.tsx b/frontend/src/core/edit-app.tsx
index 3d369e0e27..96005720af 100644
--- a/frontend/src/core/edit-app.tsx
+++ b/frontend/src/core/edit-app.tsx
@@ -34,6 +34,7 @@ import {
useCellActions,
} from "./cells/cells";
import type { AppConfig, UserConfig } from "./config/config-schema";
+import { DocumentProvider } from "./notebook/document";
import { RuntimeState } from "./kernel/RuntimeState";
import { getSessionId } from "./kernel/session";
import { useTogglePresenting } from "./layout/useTogglePresenting";
@@ -83,7 +84,7 @@ export const EditApp: React.FC<AppProps> = ({
};
}, [sendComponentValues]);
- const { connection, reconnect } = useNotebookSession({
+ const { connection, reconnect, documentModel } = useNotebookSession({
autoInstantiate: userConfig.runtime.auto_instantiate,
setCells: (cells, layout) => {
setCells(cells);
@@ -174,7 +175,7 @@ export const EditApp: React.FC<AppProps> = ({
);
return (
- <>
+ <DocumentProvider model={documentModel}>
<SandboxController onReconnect={reconnect} />
<AppContainer
connection={connection}
@@ -228,6 +229,6 @@ export const EditApp: React.FC<AppProps> = ({
/>
</TooltipProvider>
)}
- </>
+ </DocumentProvider>
);
};
diff --git a/frontend/src/core/export/layout.ts b/frontend/src/core/export/layout.ts
index f55b202dde..e455aaca76 100644
--- a/frontend/src/core/export/layout.ts
+++ b/frontend/src/core/export/layout.ts
@@ -1,9 +1,9 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { flushDocumentChanges } from "@/core/cells/document-changes";
+import { flushDocument } from "@/core/cells/document";
import { getSerializedLayout } from "@/core/layout/layout";
export async function getExportLayout() {
- await flushDocumentChanges();
+ await flushDocument();
return getSerializedLayout();
}
diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.ts
index 23287010c1..5668b9f3f0 100644
--- a/frontend/src/core/islands/bridge.ts
+++ b/frontend/src/core/islands/bridge.ts
@@ -347,7 +347,6 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
public saveAppConfig = throwNotImplemented;
public saveCellConfig = throwNotImplemented;
public sendRestart = throwNotImplemented;
- public sendDocumentTransaction = throwNotImplemented;
public readCode = throwNotImplemented;
public readSnippets = throwNotImplemented;
public previewDatasetColumn = throwNotImplemented;
diff --git a/frontend/src/core/network/requests-lazy.ts b/frontend/src/core/network/requests-lazy.ts
index 4cf30925a9..4946f31305 100644
--- a/frontend/src/core/network/requests-lazy.ts
+++ b/frontend/src/core/network/requests-lazy.ts
@@ -144,7 +144,6 @@ const ACTIONS: Record<keyof AllRequests, Action> = {
downloadStorage: "waitForConnectionOpen",
// Sync operations that wait for connection
- sendDocumentTransaction: "waitForConnectionOpen",
sendCodeCompletionRequest: "waitForConnectionOpen",
};
diff --git a/frontend/src/core/network/requests-network.ts b/frontend/src/core/network/requests-network.ts
index a55ffa71f2..d931c61ea1 100644
--- a/frontend/src/core/network/requests-network.ts
+++ b/frontend/src/core/network/requests-network.ts
@@ -70,15 +70,6 @@ export function createNetworkRequests(): EditRequests & RunRequests {
})
.then(handleResponseReturnNull);
},
- sendDocumentTransaction: async (request) => {
- await waitForConnectionOpen();
- return getClient()
- .POST("/api/document/transaction", {
- body: request,
- params: getParams(),
- })
- .then(handleResponseReturnNull);
- },
sendRename: (request) => {
return getClient()
.POST("/api/kernel/rename", {
diff --git a/frontend/src/core/network/requests-static.ts b/frontend/src/core/network/requests-static.ts
index 6cf6350232..4d027e98cd 100644
--- a/frontend/src/core/network/requests-static.ts
+++ b/frontend/src/core/network/requests-static.ts
@@ -40,7 +40,6 @@ export function createStaticRequests(): EditRequests & RunRequests {
return null;
},
sendRestart: throwNotInEditMode,
- sendDocumentTransaction: throwNotInEditMode,
sendRun: throwNotInEditMode,
sendRunScratchpad: throwNotInEditMode,
sendRename: throwNotInEditMode,
diff --git a/frontend/src/core/network/requests-toasting.tsx b/frontend/src/core/network/requests-toasting.tsx
index f686da15bc..a98659c9b6 100644
--- a/frontend/src/core/network/requests-toasting.tsx
+++ b/frontend/src/core/network/requests-toasting.tsx
@@ -21,7 +21,6 @@ export function createErrorToastingRequests(
sendInstantiate: "Failed to instantiate",
sendFunctionRequest: "Failed to send function request",
sendRestart: "Failed to restart",
- sendDocumentTransaction: "Failed to sync document transaction",
sendRun: "Failed to run",
sendRunScratchpad: "Failed to run scratchpad",
sendRename: "Failed to rename",
diff --git a/frontend/src/core/network/types.ts b/frontend/src/core/network/types.ts
index 78208f0c1c..fbd809d8ca 100644
--- a/frontend/src/core/network/types.ts
+++ b/frontend/src/core/network/types.ts
@@ -117,8 +117,6 @@ export interface FileCreateInput {
}
export type UpdateUIElementRequest = schemas["UpdateUIElementRequest"];
export type ModelRequest = schemas["ModelRequest"];
-export type NotebookDocumentTransactionRequest =
- schemas["NotebookDocumentTransactionRequest"];
export type UpdateUserConfigRequest = schemas["UpdateUserConfigRequest"];
export type ShutdownSessionRequest = schemas["ShutdownSessionRequest"];
export type Snippet = schemas["Snippet"];
@@ -179,9 +177,6 @@ export interface EditRequests {
saveAppConfig: (request: SaveAppConfigurationRequest) => Promise<null>;
saveCellConfig: (request: SetCellConfigRequest) => Promise<null>;
sendRestart: () => Promise<null>;
- sendDocumentTransaction: (
- request: NotebookDocumentTransactionRequest,
- ) => Promise<null>;
sendInstallMissingPackages: (
request: InstallPackagesRequest,
) => Promise<null>;
diff --git a/frontend/src/core/notebook/document/__tests__/codemirror.test.ts b/frontend/src/core/notebook/document/__tests__/codemirror.test.ts
index 560103be5b..51a7ade0bb 100644
--- a/frontend/src/core/notebook/document/__tests__/codemirror.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/codemirror.test.ts
@@ -84,14 +84,14 @@ function setup({
} = {}) {
const store = createStore();
const source = atom(initial);
- const controller = new AbortController();
- lifetimes.push(controller);
const model = createDocumentModel({
store,
documentAtom: source,
backendAtom: atom(fakeBackend({ edit: () => new Promise(() => {}) })),
- signal: controller.signal,
});
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
const editor = (text = doc) => {
const view = new EditorView({
state: EditorState.create({
@@ -326,7 +326,7 @@ describe("cellCodeBinding", () => {
});
});
- it("switches language for host code without rewriting it", async () => {
+ it("keeps Python mode for host code without rewriting it", async () => {
const { store, source, view, code, status } = setup({ adapters: true });
await settle();
expect(language(view)).toBe("python");
@@ -337,12 +337,58 @@ describe("cellCodeBinding", () => {
);
await settle();
- expect(language(view)).toBe("markdown");
- expect(view.state.doc.toString()).toBe("hi");
+ expect(language(view)).toBe("python");
+ expect(view.state.doc.toString()).toBe('mo.md("hi")');
expect(code()).toBe('mo.md("hi")');
expect(status()).toEqual({ status: "idle" });
});
+ it("keeps Python mode while typing mo.md() and receiving its echo", async () => {
+ const { store, source, view, type } = setup({
+ adapters: true,
+ initial: withCells(document(), { c1: cell("c1", "") }),
+ });
+ await settle();
+ type("mo.md");
+ await settle();
+ type("()");
+ await settle();
+ store.set(source, withCells(document(), { c1: cell("c1", "mo.md()") }));
+ await settle();
+
+ expect(language(view)).toBe("python");
+ expect(view.state.doc.toString()).toBe("mo.md()");
+ });
+
+ it("falls back to Python when host code no longer fits Markdown", async () => {
+ const { store, source, view, code, status } = setup({
+ adapters: true,
+ initial: withCells(document(), { c1: cell("c1", 'mo.md("hi")') }),
+ });
+ await settle();
+ expect(language(view)).toBe("markdown");
+
+ store.set(source, withCells(document(), { c1: cell("c1", "x = 1") }));
+ await settle();
+
+ expect(language(view)).toBe("python");
+ expect(view.state.doc.toString()).toBe("x = 1");
+ expect(code()).toBe("x = 1");
+ expect(status()).toEqual({ status: "idle" });
+ });
+
+ it("preserves Python when typing before the initial pull", async () => {
+ const { view, type } = setup({
+ adapters: true,
+ initial: withCells(document(), { c1: cell("c1", "") }),
+ });
+ type("mo.md()");
+ await settle();
+
+ expect(language(view)).toBe("python");
+ expect(view.state.doc.toString()).toBe("mo.md()");
+ });
+
it("writes changes to language metadata alone", async () => {
const { view, code } = setup({
adapters: true,
@@ -435,15 +481,12 @@ describe("cellCodeBinding", () => {
});
it("edits SQL as SQL and keeps its output name", async () => {
- const { store, source, view, code, type } = setup({ adapters: true });
- await settle();
-
- store.set(
- source,
- withCells(document(), {
+ const { view, code, type } = setup({
+ adapters: true,
+ initial: withCells(document(), {
c1: cell("c1", 'df = mo.sql(f"""SELECT 1""")'),
}),
- );
+ });
await settle();
expect(language(view)).toBe("sql");
expect(view.state.doc.toString()).toBe("SELECT 1");
@@ -456,7 +499,12 @@ describe("cellCodeBinding", () => {
});
it("sets the SQL dialect from the host's engine", async () => {
- const { store, source } = setup({ adapters: true });
+ const { store, source } = setup({
+ adapters: true,
+ initial: withCells(document(), {
+ c1: cell("c1", 'df = mo.sql("SELECT 1")'),
+ }),
+ });
await settle();
const dialect = vi.spyOn(SCHEMA_CACHE, "getDialect");
try {
@@ -483,3 +531,17 @@ describe("cellCodeBinding", () => {
});
});
});
+
+describe("cellCodeBinding before the cell has source", () => {
+ it("still infers the language when the source first arrives", async () => {
+ const { store, view, source, type } = setup({
+ initial: null,
+ adapters: true,
+ });
+ type("x");
+ await settle();
+ store.set(source, withCells(document(), { c1: cell("c1", 'mo.md("hi")') }));
+ await settle();
+ expect(view.state.field(languageAdapterState).type).toBe("markdown");
+ });
+});
diff --git a/frontend/src/core/notebook/document/__tests__/hold.test.ts b/frontend/src/core/notebook/document/__tests__/hold.test.ts
new file mode 100644
index 0000000000..8f09dd762b
--- /dev/null
+++ b/frontend/src/core/notebook/document/__tests__/hold.test.ts
@@ -0,0 +1,88 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom, createStore } from "jotai";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { Document } from "../../replica/resources/document";
+import { createDocumentModel } from "..";
+import { type FakeEdit, fakeBackend } from "../../replica/__tests__/fixtures";
+import { document } from "./fixtures";
+
+const lifetimes: AbortController[] = [];
+
+afterEach(() => {
+ lifetimes.splice(0).forEach((controller) => controller.abort());
+});
+
+/** The document after the host accepts one edit. */
+function accepted(): Document {
+ const base = document();
+ return {
+ ...base,
+ revision: { ...base.revision, version: 2, etag: "document-2" },
+ };
+}
+
+function setup() {
+ const store = createStore();
+ const source = atom<Document | null>(document());
+ // Answer the edit, then publish the accepted document as the host would.
+ const edit = vi.fn<FakeEdit>().mockImplementation(async () => {
+ queueMicrotask(() => store.set(source, accepted()));
+ return {
+ ok: true,
+ status: 200,
+ data: { document: accepted().revision, cells: {} },
+ };
+ });
+ const model = createDocumentModel({
+ store,
+ documentAtom: source,
+ backendAtom: atom(fakeBackend({ edit })),
+ });
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
+ return { store, model, edit, controller };
+}
+
+describe("document sync hold", () => {
+ it("keeps an edit local until released, then lets a waiting flush send it", async () => {
+ const { store, model, edit } = setup();
+ const release = model.hold();
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "x = 2"));
+ const flushing = model.flush();
+ await Promise.resolve();
+ expect(edit).not.toHaveBeenCalled();
+ expect(store.get(model.syncStatusAtom)).toEqual({ status: "pending" });
+
+ release();
+ await flushing;
+ expect(edit).toHaveBeenCalledTimes(1);
+ });
+
+ it("releases once the last of nested holds is released", async () => {
+ const { store, model, edit } = setup();
+ const outer = model.hold();
+ const inner = model.hold();
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "x = 2"));
+ const flushing = model.flush();
+
+ inner();
+ inner();
+ await Promise.resolve();
+ expect(edit).not.toHaveBeenCalled();
+
+ outer();
+ await flushing;
+ expect(edit).toHaveBeenCalledTimes(1);
+ });
+
+ it("rejects a flush waiting on a hold when the model stops", async () => {
+ const { store, model, controller } = setup();
+ model.hold();
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "x = 2"));
+ const flushing = model.flush();
+ controller.abort(new Error("session ended"));
+ await expect(flushing).rejects.toThrow("session ended");
+ });
+});
diff --git a/frontend/src/core/notebook/document/__tests__/hooks.test.tsx b/frontend/src/core/notebook/document/__tests__/hooks.test.tsx
index 00c2037119..2c97538778 100644
--- a/frontend/src/core/notebook/document/__tests__/hooks.test.tsx
+++ b/frontend/src/core/notebook/document/__tests__/hooks.test.tsx
@@ -32,14 +32,14 @@ function setup(
const source = atom(initial);
const detached = vi.fn();
source.onMount = () => detached;
- const controller = new AbortController();
- lifetimes.push(controller);
const model = createDocumentModel({
store,
documentAtom: source,
backendAtom: atom(fakeBackend({ edit })),
- signal: controller.signal,
});
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
const wrapper = ({ children }: PropsWithChildren) => (
<Provider store={store}>
<DocumentProvider model={model}>{children}</DocumentProvider>
diff --git a/frontend/src/core/notebook/document/__tests__/lifecycle-scenarios.test.ts b/frontend/src/core/notebook/document/__tests__/lifecycle-scenarios.test.ts
index 2500e098b2..52945a5b85 100644
--- a/frontend/src/core/notebook/document/__tests__/lifecycle-scenarios.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/lifecycle-scenarios.test.ts
@@ -13,7 +13,7 @@ test("closing a session before the debounce prevents submission", async ({
await vi.advanceTimersByTimeAsync(1000);
expect(notebook.edit).not.toHaveBeenCalled();
expect(vi.getTimerCount()).toBe(0);
- await expect(user.sync()).rejects.toBe(reason);
+ await expect(user.sync()).rejects.toThrow("not started");
});
test("closing a session before a queued flush starts prevents submission", async ({
@@ -55,7 +55,7 @@ test.for(["request", "confirmation", "retry"] as const)(
await vi.advanceTimersByTimeAsync(1000);
expect(notebook.edit).toHaveBeenCalledOnce();
expect(vi.getTimerCount()).toBe(0);
- await expect(user.sync()).rejects.toBe(reason);
- await expect(user.retry()).rejects.toBe(reason);
+ await expect(user.sync()).rejects.toThrow("not started");
+ await expect(user.retry()).rejects.toThrow("not started");
},
);
diff --git a/frontend/src/core/notebook/document/__tests__/model.test.ts b/frontend/src/core/notebook/document/__tests__/model.test.ts
index 48eccf97a7..552d34bad1 100644
--- a/frontend/src/core/notebook/document/__tests__/model.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/model.test.ts
@@ -52,14 +52,14 @@ function setup({ connected = true } = {}) {
sent({ notebookId, changes, ...options }),
});
const backendAtom = atom<NotebookBackend | null>(connected ? backend : null);
- const controller = new AbortController();
- lifetimes.push(controller);
const model = createDocumentModel({
store,
documentAtom: source,
backendAtom,
- signal: controller.signal,
});
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ model.start({ signal: controller.signal });
return {
store,
source,
@@ -85,28 +85,84 @@ afterEach(() => {
});
describe("document synchronization", () => {
- it("rejects an aborted lifetime before subscribing or sending", () => {
+ it("subscribes to nothing until started", async () => {
const store = createStore();
const source = atom<Document | null>(document());
const mounted = vi.fn();
source.onMount = mounted;
- const controller = new AbortController();
- const reason = new Error("Session ended");
- controller.abort(reason);
const edit = vi.fn<FakeEdit>();
- expect(() =>
- createDocumentModel({
- store,
- documentAtom: source,
- backendAtom: atom(fakeBackend({ edit })),
- signal: controller.signal,
- }),
- ).toThrow(reason);
+ const model = createDocumentModel({
+ store,
+ documentAtom: source,
+ backendAtom: atom(fakeBackend({ edit })),
+ });
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "local"));
+ await expect(model.flush()).rejects.toThrow("not started");
+ expect(store.get(model.documentAtom)).toBeNull();
+ expect(store.get(model.syncStatusAtom)).toEqual({ status: "unavailable" });
expect(mounted).not.toHaveBeenCalled();
expect(edit).not.toHaveBeenCalled();
expect(vi.getTimerCount()).toBe(0);
});
+ it("rejects an aborted signal before subscribing", () => {
+ const store = createStore();
+ const source = atom<Document | null>(document());
+ const mounted = vi.fn();
+ source.onMount = mounted;
+ const model = createDocumentModel({
+ store,
+ documentAtom: source,
+ backendAtom: atom(fakeBackend({ edit: vi.fn<FakeEdit>() })),
+ });
+ const reason = new Error("Session ended");
+ expect(() => model.start({ signal: AbortSignal.abort(reason) })).toThrow(
+ reason,
+ );
+ expect(mounted).not.toHaveBeenCalled();
+ });
+
+ it("starts again after a subscriber aborts during startup", async () => {
+ const store = createStore();
+ const model = createDocumentModel({
+ store,
+ documentAtom: atom(document()),
+ backendAtom: atom(null),
+ });
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ const unsubscribe = store.sub(model.documentAtom, () => {
+ if (store.get(model.documentAtom)) {
+ controller.abort();
+ }
+ });
+ model.start({ signal: controller.signal });
+ unsubscribe();
+ expect(controller.signal.aborted).toBe(true);
+ expect(store.get(model.documentAtom)).toBeNull();
+ await expect(model.flush()).rejects.toThrow("not started");
+
+ const next = new AbortController();
+ lifetimes.push(next);
+ model.start({ signal: next.signal });
+ expect(store.get(model.documentAtom)?.cells.get("c1")?.code).toBe("x = 1");
+ });
+
+ it("starts again without the drafts of a stopped run", () => {
+ const { store, model, controller, edit, value } = setup();
+ expect(() => model.start({ signal: new AbortController().signal })).toThrow(
+ "already started",
+ );
+ edit("local");
+ controller.abort();
+ const next = new AbortController();
+ lifetimes.push(next);
+ model.start({ signal: next.signal });
+ expect(value()?.code).toBe("x = 1");
+ store.set(model.editAtom, (tx) => tx.setCode("c1", "restarted"));
+ expect(value()?.code).toBe("restarted");
+ });
+
it("fails without repeating a request when the response names another notebook", async () => {
const { sent, replies, edit, model, status } = setup();
edit("local");
diff --git a/frontend/src/core/notebook/document/__tests__/scenario-fixture.ts b/frontend/src/core/notebook/document/__tests__/scenario-fixture.ts
index 14e4f323c1..0f74aa4b52 100644
--- a/frontend/src/core/notebook/document/__tests__/scenario-fixture.ts
+++ b/frontend/src/core/notebook/document/__tests__/scenario-fixture.ts
@@ -15,8 +15,8 @@ function createSession(initial: Document, controller: AbortController) {
store,
documentAtom: notebook.documentAtom,
backendAtom: notebook.backendAtom,
- signal: controller.signal,
});
+ model.start({ signal: controller.signal });
return {
user: createUser(store, model),
host: control,
diff --git a/frontend/src/core/notebook/document/codemirror.ts b/frontend/src/core/notebook/document/codemirror.ts
index dc7be954af..c10e0b9361 100644
--- a/frontend/src/core/notebook/document/codemirror.ts
+++ b/frontend/src/core/notebook/document/codemirror.ts
@@ -28,34 +28,24 @@
* coarsely instead of blocking the editor.
*/
-import { diff } from "@codemirror/merge";
import {
- type ChangeSpec,
type EditorState,
type Extension,
- type StateEffect,
Transaction,
} from "@codemirror/state";
import { type EditorView, ViewPlugin, type ViewUpdate } from "@codemirror/view";
import type { CellId } from "@marimo-team/client/protocol";
-import { dequal } from "dequal";
import type { Atom, createStore } from "jotai/vanilla";
import {
- languageAdapterFromCode,
- languageAdapterState,
- switchLanguage,
-} from "../../codemirror/language/extension";
-import { initializeSQLDialect } from "../../codemirror/language/languages/sql/sql";
-import {
- languageMetadataField,
- setLanguageMetadata,
-} from "../../codemirror/language/metadata";
+ 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";
-/** The diff scan limit, matching the default of the merge view. */
-const SCAN_LIMIT = 500;
-
interface Binding {
readonly store: ReturnType<typeof createStore>;
readonly model: DocumentModel;
@@ -94,17 +84,11 @@ export function cellCodeBinding({
}
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;
- /**
- * A pull is dispatching to the editor.
- *
- * A language switch dispatches transactions of its own before the text, and
- * their in-between states represent the wrong code. Until the switch can be
- * part of the pull's one remote transaction, this keeps them from pushing.
- */
- #pulling = false;
/**
* The code the editor and the model last agreed on.
*
@@ -130,7 +114,10 @@ class CellCodeSync {
}
public update(update: ViewUpdate) {
- if (!this.#pulling && changesCode(update)) {
+ if (
+ changesCode(update) &&
+ !update.transactions.every((tr) => tr.annotation(Transaction.remote))
+ ) {
this.#push(update.state);
}
if (this.#deferred && !update.view.composing) {
@@ -164,11 +151,12 @@ class CellCodeSync {
this.#synced = undefined;
return;
}
- if (shows(state, current)) {
+ this.#initialized = true;
+ if (editorShowsCellCode(state, current)) {
this.#synced = current;
return;
}
- const next = codeOf(state);
+ const next = getCellCode(state);
this.#synced = next;
store.set(model.editAtom, (tx) => tx.setCode(cellId, next));
}
@@ -185,15 +173,21 @@ class CellCodeSync {
return;
}
this.#deferred = false;
- if (next !== this.#synced && !shows(this.#view.state, next)) {
- this.#pulling = true;
- try {
- replaceCode(this.#view, next);
- } finally {
- this.#pulling = 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. */
@@ -205,44 +199,6 @@ class CellCodeSync {
}
}
-/**
- * The cell code an editor state represents.
- *
- * With a language adapter, this is the adapter's Python for the editor text.
- */
-function codeOf(state: EditorState): string {
- const text = state.doc.toString();
- const adapter = state.field(languageAdapterState, false);
- return adapter
- ? adapter.transformOut(
- text,
- state.field(languageMetadataField, false) ?? {},
- )[0]
- : text;
-}
-
-/**
- * Whether an editor state shows the given cell code.
- *
- * An adapter can spell the same code more than one way, such as `mo.md("hi")`
- * and its canonical form, so a state shows code that reads into its text and
- * metadata as well as the code its own spelling produces.
- */
-function shows(state: EditorState, code: string): boolean {
- if (codeOf(state) === code) {
- return true;
- }
- const adapter = state.field(languageAdapterState, false);
- if (!adapter) {
- return false;
- }
- const [text, , metadata] = adapter.transformIn(code);
- return (
- text === state.doc.toString() &&
- dequal(metadata, state.field(languageMetadataField, false))
- );
-}
-
/**
* Whether an update could change the code an editor represents.
*
@@ -258,54 +214,3 @@ function changesCode(update: ViewUpdate): boolean {
update.startState.field(languageMetadataField, false)
);
}
-
-/**
- * Show cell code in the language it implies.
- *
- * The language switch happens first, in its own transactions, and clears undo
- * history because its entries edit the previous language's text. The text and
- * metadata follow in one remote transaction that undo history leaves out. An
- * SQL dialect depends on the engine in the metadata, so it is set again after.
- */
-function replaceCode(view: EditorView, code: string) {
- let text = code;
- const effects: StateEffect<unknown>[] = [];
- let sql = false;
- const adapter = view.state.field(languageAdapterState, false);
- if (adapter) {
- const target = languageAdapterFromCode(code);
- sql = target.type === "sql";
- if (target.type !== adapter.type) {
- switchLanguage(view, { language: target.type, keepCodeAsIs: true });
- }
- const [inner, , metadata] = target.transformIn(code);
- text = inner;
- if (!dequal(metadata, view.state.field(languageMetadataField, false))) {
- effects.push(setLanguageMetadata.of(metadata));
- }
- }
- const current = view.state.doc.toString();
- if (current === text && effects.length === 0) {
- return;
- }
- view.dispatch({
- changes: changesBetween(current, text),
- effects,
- annotations: [
- Transaction.remote.of(true),
- Transaction.addToHistory.of(false),
- ],
- });
- if (sql && effects.length > 0) {
- initializeSQLDialect(view);
- }
-}
-
-/** The changes that turn one text into another, one per edited range. */
-function changesBetween(from: string, to: string): ChangeSpec {
- return diff(from, to, { scanLimit: SCAN_LIMIT }).map((change) => ({
- from: change.fromA,
- to: change.toA,
- insert: to.slice(change.fromB, change.toB),
- }));
-}
diff --git a/frontend/src/core/notebook/document/hooks.tsx b/frontend/src/core/notebook/document/hooks.tsx
index f06b3cc8fa..49a1c83da9 100644
--- a/frontend/src/core/notebook/document/hooks.tsx
+++ b/frontend/src/core/notebook/document/hooks.tsx
@@ -12,8 +12,8 @@ const DocumentContext = createContext<DocumentModel | null>(null);
/**
* Expose a session-owned model to React. Construct the model with the same store
- * as the enclosing Jotai Provider. The session owner controls its AbortSignal;
- * mounting or unmounting this provider does not change the model's lifetime.
+ * as the enclosing Jotai Provider. The session owner starts it; mounting or
+ * unmounting this provider does not change the model's lifetime.
*
* ```tsx
* <Provider store={store}>
diff --git a/frontend/src/core/notebook/document/index.ts b/frontend/src/core/notebook/document/index.ts
index 48d9ec8a0f..24be4f54bb 100644
--- a/frontend/src/core/notebook/document/index.ts
+++ b/frontend/src/core/notebook/document/index.ts
@@ -12,4 +12,12 @@ export {
useNotebookDocumentEdit,
useNotebookDocumentSync,
} from "./hooks";
-export { createDocumentModel, type DocumentModel } from "./model";
+export {
+ createDocumentModel,
+ type DocumentEdit,
+ type DocumentEditor,
+ type DocumentModel,
+ type DocumentSyncStatus,
+ type EditableCell,
+ type EditableDocument,
+} from "./model";
diff --git a/frontend/src/core/notebook/document/model.ts b/frontend/src/core/notebook/document/model.ts
index 6dabaa55be..01fa0625de 100644
--- a/frontend/src/core/notebook/document/model.ts
+++ b/frontend/src/core/notebook/document/model.ts
@@ -1,9 +1,19 @@
/* Copyright 2026 Marimo. All rights reserved. */
import type * as Protocol from "@marimo-team/client/protocol";
-import type { Atom, createStore } from "jotai/vanilla";
+import {
+ type Atom,
+ atom,
+ type createStore,
+ type WritableAtom,
+} from "jotai/vanilla";
import type { Document, NotebookBackend } from "../replica";
-import { createDocumentState, type DocumentState } from "./state";
+import type { EditableDocument } from "./draft";
+import {
+ createDocumentState,
+ type DocumentEdit,
+ type DocumentState,
+} from "./state";
import { createDocumentSync, type DocumentSyncStatus } from "./sync";
export type { DocumentEdit, DocumentEditor } from "./state";
@@ -11,45 +21,85 @@ export type { EditableCell, EditableDocument } from "./draft";
export type { DocumentSyncStatus } from "./sync";
/** The editable document and its synchronization with the host. */
-export interface DocumentModel extends Pick<
- DocumentState,
- "documentAtom" | "editAtom"
-> {
+export interface DocumentModel {
+ /** Confirmed host state with local drafts applied, null while unavailable or stopped. */
+ readonly documentAtom: Atom<EditableDocument | null>;
+ /** Ignored while stopped. */
+ readonly editAtom: WritableAtom<null, [edit: DocumentEdit], void>;
readonly syncStatusAtom: Atom<DocumentSyncStatus>;
/** Drain local edits and return the confirmed revision. */
flush(): Promise<Protocol.Document>;
/** Retry a rejection against fresh state, or repeat an uncertain request exactly. */
retry(): Promise<Protocol.Document>;
+ /** Keep edits local until the returned release is called. A no-op while stopped. */
+ hold(): () => void;
+ /**
+ * Edit and synchronize until the signal aborts, which discards local drafts.
+ * The model can start again once stopped.
+ */
+ start(options: { signal: AbortSignal }): void;
}
-/** Create once per editing session; abort to stop editing and synchronization together. */
+interface Running {
+ readonly state: DocumentState;
+ readonly sync: ReturnType<typeof createDocumentSync>;
+}
+
+/** Create without subscribing to anything; editing begins on start. */
export function createDocumentModel({
store,
- documentAtom,
+ documentAtom: source,
backendAtom,
- signal,
}: {
store: ReturnType<typeof createStore>;
/** The document the host last confirmed. */
documentAtom: Atom<Document | null>;
/** The backend that confirmed it, whose commands reach its host. */
backendAtom: Atom<NotebookBackend | null>;
- signal: AbortSignal;
}): DocumentModel {
- signal.throwIfAborted();
- const state = createDocumentState({ store, source: documentAtom, signal });
- const sync = createDocumentSync({
- store,
- documentAtom,
- backendAtom,
- state,
- signal,
- });
+ const runningAtom = atom<Running | null>(null);
+
+ function stopped(): Promise<never> {
+ return Promise.reject(new Error("The document model is not started"));
+ }
+
return {
- documentAtom: state.documentAtom,
- editAtom: state.editAtom,
- syncStatusAtom: sync.statusAtom,
- flush: sync.flush,
- retry: sync.retry,
+ documentAtom: atom((get) => {
+ const running = get(runningAtom);
+ return running ? get(running.state.documentAtom) : null;
+ }),
+ editAtom: atom(null, (get, set, edit: DocumentEdit) => {
+ const running = get(runningAtom);
+ if (running) {
+ set(running.state.editAtom, edit);
+ }
+ }),
+ syncStatusAtom: atom((get) => {
+ const running = get(runningAtom);
+ return running ? get(running.sync.statusAtom) : { status: "unavailable" };
+ }),
+ flush: () => store.get(runningAtom)?.sync.flush() ?? stopped(),
+ retry: () => store.get(runningAtom)?.sync.retry() ?? stopped(),
+ hold: () => store.get(runningAtom)?.sync.hold() ?? (() => undefined),
+ start({ signal }) {
+ signal.throwIfAborted();
+ if (store.get(runningAtom)) {
+ throw new Error("The document model is already started");
+ }
+ const state = createDocumentState({ store, source, signal });
+ const sync = createDocumentSync({
+ store,
+ documentAtom: source,
+ backendAtom,
+ state,
+ signal,
+ });
+ const stop = () => store.set(runningAtom, null);
+ signal.addEventListener("abort", stop, { once: true });
+ store.set(runningAtom, { state, sync });
+ if (signal.aborted) {
+ stop();
+ }
+ },
};
}
diff --git a/frontend/src/core/notebook/document/sync.ts b/frontend/src/core/notebook/document/sync.ts
index 81b6fb9a78..873c6bf9ea 100644
--- a/frontend/src/core/notebook/document/sync.ts
+++ b/frontend/src/core/notebook/document/sync.ts
@@ -97,6 +97,13 @@ export function createDocumentSync({
let failure: Extract<DocumentSyncStatus, { status: "error" }> | null = null;
let timer: ReturnType<typeof setTimeout> | undefined;
let refreshing = false;
+ // Holds keep edits local, as a legacy save needs while it writes the
+ // notebook the flush before it produced.
+ let holds = 0;
+ let releaseWaiters: Array<{
+ resolve: () => void;
+ reject: (reason: unknown) => void;
+ }> = [];
function clearTimer() {
clearTimeout(timer);
@@ -139,9 +146,11 @@ export function createDocumentSync({
store.set(statusAtom, { status: "idle" });
} else {
store.set(statusAtom, { status: "pending" });
- timer = setTimeout(() => {
- void flush().catch(() => undefined);
- }, DEBOUNCE_MS);
+ if (holds === 0) {
+ timer = setTimeout(() => {
+ void flush().catch(() => undefined);
+ }, DEBOUNCE_MS);
+ }
}
} finally {
refreshing = false;
@@ -314,6 +323,11 @@ export function createDocumentSync({
if (running) {
return running;
}
+ if (holds > 0) {
+ return new Promise<void>((resolve, reject) => {
+ releaseWaiters.push({ resolve, reject });
+ }).then(flush);
+ }
const notebookId =
active?.submission.notebookId ?? store.get(source)?.revision.notebook_id;
if (notebookId === undefined) {
@@ -353,17 +367,52 @@ export function createDocumentSync({
return flush();
}
+ /**
+ * Keep edits local until the returned release is called. Flushes
+ * requested meanwhile wait for it. Holds nest, and a release is
+ * idempotent.
+ *
+ * TODO(MO-8028): Only the legacy save needs this, since the host takes
+ * the notebook it writes as the document. Saving through the host
+ * removes both.
+ */
+ function hold(): () => void {
+ holds += 1;
+ let held = true;
+ return () => {
+ if (!held) {
+ return;
+ }
+ held = false;
+ holds -= 1;
+ if (holds > 0) {
+ return;
+ }
+ const waiters = releaseWaiters;
+ releaseWaiters = [];
+ for (const waiter of waiters) {
+ waiter.resolve();
+ }
+ refresh();
+ };
+ }
+
const unsubscribe = store.sub(observed, refresh);
function stop() {
clearTimer();
unsubscribe();
signal.removeEventListener("abort", stop);
active?.controller.abort(signal.reason);
+ const waiters = releaseWaiters;
+ releaseWaiters = [];
+ for (const waiter of waiters) {
+ waiter.reject(signal.reason);
+ }
}
signal.addEventListener("abort", stop, { once: true });
if (signal.aborted) {
stop();
}
refresh();
- return { statusAtom, flush, retry };
+ return { statusAtom, flush, retry, hold };
}
diff --git a/frontend/src/core/run-app.tsx b/frontend/src/core/run-app.tsx
index bc3c17311f..a113ead911 100644
--- a/frontend/src/core/run-app.tsx
+++ b/frontend/src/core/run-app.tsx
@@ -17,6 +17,7 @@ import {
useCellActions,
} from "./cells/cells";
import type { AppConfig } from "./config/config-schema";
+import { DocumentProvider } from "./notebook/document";
import { RuntimeState } from "./kernel/RuntimeState";
import { getSessionId } from "./kernel/session";
import { connectionAtom } from "./network/connection";
@@ -51,7 +52,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
};
}, [sendComponentValues]);
- const { connection, reconnect } = useNotebookSession({
+ const { connection, reconnect, documentModel } = useNotebookSession({
autoInstantiate: true,
setCells: setCells,
sessionId: getSessionId(),
@@ -73,47 +74,49 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
})();
return (
- <AppContainer
- connection={connection}
- isRunning={isRunning}
- width={appConfig.width}
- onReconnect={reconnect}
- >
- <KernelStartupErrorModal />
- <AppHeader
+ <DocumentProvider model={documentModel}>
+ <AppContainer
connection={connection}
- className={hideHeader ? "hidden" : "sm:pt-8"}
+ isRunning={isRunning}
+ width={appConfig.width}
+ onReconnect={reconnect}
>
- {galleryHref && (
- <div className="flex items-center px-6 pt-4 sm:-mt-8">
- <a
- href={galleryHref}
- aria-label="Back to gallery"
- className={cn(
- buttonVariants({ variant: "text", size: "sm" }),
- "gap-2 px-0 text-muted-foreground hover:text-foreground",
- )}
- >
- <ArrowLeftIcon className="size-4" aria-hidden={true} />
- <span>Back</span>
- </a>
- </div>
- )}
- </AppHeader>
- <ProgressiveBoundary
- requires={canPaintRunAppAtom}
- delay={2000}
- fallback={
- <>
- <Spinner className="mx-auto" />
- <p className="text-center text-sm text-muted-foreground mt-2">
- Connecting...
- </p>
- </>
- }
- >
- <CellsRenderer appConfig={appConfig} mode="read" />
- </ProgressiveBoundary>
- </AppContainer>
+ <KernelStartupErrorModal />
+ <AppHeader
+ connection={connection}
+ className={hideHeader ? "hidden" : "sm:pt-8"}
+ >
+ {galleryHref && (
+ <div className="flex items-center px-6 pt-4 sm:-mt-8">
+ <a
+ href={galleryHref}
+ aria-label="Back to gallery"
+ className={cn(
+ buttonVariants({ variant: "text", size: "sm" }),
+ "gap-2 px-0 text-muted-foreground hover:text-foreground",
+ )}
+ >
+ <ArrowLeftIcon className="size-4" aria-hidden={true} />
+ <span>Back</span>
+ </a>
+ </div>
+ )}
+ </AppHeader>
+ <ProgressiveBoundary
+ requires={canPaintRunAppAtom}
+ delay={2000}
+ fallback={
+ <>
+ <Spinner className="mx-auto" />
+ <p className="text-center text-sm text-muted-foreground mt-2">
+ Connecting...
+ </p>
+ </>
+ }
+ >
+ <CellsRenderer appConfig={appConfig} mode="read" />
+ </ProgressiveBoundary>
+ </AppContainer>
+ </DocumentProvider>
);
};
diff --git a/frontend/src/core/saving/save-component.tsx b/frontend/src/core/saving/save-component.tsx
index 4eca9be682..5d2c2e9279 100644
--- a/frontend/src/core/saving/save-component.tsx
+++ b/frontend/src/core/saving/save-component.tsx
@@ -21,10 +21,7 @@ import { Label } from "../../components/ui/label";
import { useEvent } from "../../hooks/useEvent";
import { Logger } from "../../utils/Logger";
import { getCellConfigs, getNotebook, useNotebook } from "../cells/cells";
-import {
- flushDocumentChanges,
- withDocumentSave,
-} from "../cells/document-changes";
+import { flushDocument, withDocumentSave } from "../cells/document";
import { notebookCells } from "../cells/utils";
import { formatAll } from "../codemirror/format";
import { autoSaveConfigAtom } from "../config/config";
@@ -165,7 +162,7 @@ export function useSaveNotebook() {
// TODO(MO-7955): Remove this conditional once all frontend saves use
// the host protocol. Host saves cannot recover edits from an editor snapshot.
const savedNotebook = isWasm()
- ? await flushDocumentChanges().then(save)
+ ? await flushDocument().then(save)
: await withDocumentSave(save);
setLastSavedNotebook(savedNotebook);
}),
diff --git a/frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx b/frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx
index 925eb912b2..478c806eb3 100644
--- a/frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx
+++ b/frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx
@@ -52,7 +52,10 @@ import { RuntimeManager } from "../../runtime/runtime";
import { WebSocketClosedReason, ConnectionState } from "../types";
import { classifyCloseEvent } from "../../transports/connection-state";
import { createEditorBackend } from "../backend";
-import { fakeBackend } from "../../notebook/replica/__tests__/fixtures";
+import {
+ fakeBackend,
+ fixtureMessages,
+} from "../../notebook/replica/__tests__/fixtures";
import { useNotebookSession } from "../useNotebookSession";
import { type NotebookTransport, StreamStopped } from "@marimo-team/client";
@@ -142,7 +145,10 @@ function makeRuntimeManager(
return runtime;
}
-function renderConnectionHook(store: ReturnType<typeof createStore>) {
+function renderConnectionHook(
+ store: ReturnType<typeof createStore>,
+ { reactStrictMode = false } = {},
+) {
const wrapper: React.FC<React.PropsWithChildren> = ({ children }) => (
<JotaiProvider store={store}>
<ErrorBoundary fallback={null}>{children}</ErrorBoundary>
@@ -155,7 +161,7 @@ function renderConnectionHook(store: ReturnType<typeof createStore>) {
autoInstantiate: false,
setCells: vi.fn(),
}),
- { wrapper },
+ { wrapper, reactStrictMode },
);
}
@@ -228,6 +234,60 @@ describe("useNotebookSession.reconnect()", () => {
});
});
+describe("useNotebookSession document model", () => {
+ it("keeps drafts while the connection drops and discards them when the session ends", async () => {
+ const fake = withTransport();
+ vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
+ const store = createStore();
+ const { result, unmount } = renderConnectionHook(store, {
+ reactStrictMode: true,
+ });
+ await started();
+ act(() => {
+ connection(fake).open();
+ fixtureMessages("notebook-events.sse").forEach(connection(fake).receive);
+ });
+ const model = result.current.documentModel;
+ const code = () => store.get(model.documentAtom)?.cells.get("c1")?.code;
+ act(() => store.set(model.editAtom, (tx) => tx.setCode("c1", "local")));
+ expect(code()).toBe("local");
+
+ await act(async () => connection(fake).drop());
+ expect(result.current.documentModel).toBe(model);
+ expect(code()).toBe("local");
+
+ unmount();
+ expect(code()).toBeUndefined();
+ await expect(model.flush()).rejects.toThrow("not started");
+ });
+
+ it("follows the host document into the notebook's cells", async () => {
+ const fake = withTransport();
+ vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
+ const store = createStore();
+ const { result, unmount } = renderConnectionHook(store);
+ await started();
+ act(() => {
+ connection(fake).open();
+ fixtureMessages("notebook-events.sse").forEach(connection(fake).receive);
+ });
+
+ let notebook = store.get(notebookAtom);
+ expect(notebook.cellIds.inOrderIds).toEqual(["c1", "c3", "k7f2"]);
+ expect(notebook.cellData[cellId("k7f2")]).toMatchObject({
+ code: "y = x * 2",
+ config: { hide_code: true },
+ });
+
+ const model = result.current.documentModel;
+ act(() => store.set(model.editAtom, (tx) => tx.setCode("c3", "x = 42")));
+ notebook = store.get(notebookAtom);
+ expect(notebook.cellData[cellId("c3")].code).toBe("x = 42");
+
+ unmount();
+ });
+});
+
describe("useNotebookSession messages", () => {
let store: ReturnType<typeof createStore>;
let fake: FakeTransport;
diff --git a/frontend/src/core/session/active-notebook.ts b/frontend/src/core/session/active-notebook.ts
index ec0901d812..d474272712 100644
--- a/frontend/src/core/session/active-notebook.ts
+++ b/frontend/src/core/session/active-notebook.ts
@@ -1,7 +1,11 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { atom } from "jotai";
+import type { DocumentModel } from "../notebook/document";
import type { NotebookReplica } from "../notebook/replica";
/** The replica owned by the mounted notebook session. */
export const activeNotebookReplicaAtom = atom<NotebookReplica | null>(null);
+
+/** The document model owned by the mounted notebook session. */
+export const activeDocumentModelAtom = atom<DocumentModel | null>(null);
diff --git a/frontend/src/core/session/useNotebookSession.tsx b/frontend/src/core/session/useNotebookSession.tsx
index 5291020879..0a4cb7cd7a 100644
--- a/frontend/src/core/session/useNotebookSession.tsx
+++ b/frontend/src/core/session/useNotebookSession.tsx
@@ -2,16 +2,13 @@
import { invalidatePackageData } from "@/core/packages/package-data";
import { useAtom, useAtomValue, useSetAtom, useStore } from "jotai";
-import { useLayoutEffect } from "react";
+import { useEffect, useLayoutEffect, useMemo } from "react";
import { useErrorBoundary } from "react-error-boundary";
import { toast } from "@/components/ui/use-toast";
import { getNotebook, useCellActions } from "@/core/cells/cells";
-import { applyTransactionChanges } from "@/core/cells/document-changes";
import { AUTOCOMPLETER } from "@/core/codemirror/completion/Autocompleter";
-import type {
- NotificationMessageData,
- NotificationPayload,
-} from "@/core/kernel/messages";
+import { createDocumentModel } from "@/core/notebook/document";
+import type { NotificationPayload } from "@/core/kernel/messages";
import { useNotebookReplica } from "@/core/session/useNotebookReplica";
import { renderHTML } from "@/plugins/core/RenderHTML";
import {
@@ -75,6 +72,7 @@ import {
import { useStorageActions } from "../storage/state";
import { useVariablesActions } from "../variables/state";
import type { VariableName } from "../variables/types";
+import { activeDocumentModelAtom } from "./active-notebook";
import { WebSocketClosedReason, ConnectionState } from "./types";
const SUPPORTS_LAZY_KERNELS = true;
@@ -100,17 +98,7 @@ export function useNotebookSession(opts: {
const { showBoundary } = useErrorBoundary();
const { handleCellMessage } = useCellActions();
- const actionsWithoutMiddleware = useCellActions({ skipMiddleware: true });
-
- const handleDocumentTransaction = (
- transaction: NotificationMessageData<"notebook-document-transaction">["transaction"],
- ) => {
- applyTransactionChanges(
- transaction.changes,
- actionsWithoutMiddleware,
- () => getNotebook().cellIds.inOrderIds,
- );
- };
+ const { reconcileDocument } = useCellActions({ skipMiddleware: true });
const { addCellNotification } = useRunsActions();
const setKernelState = useSetAtom(kernelStateAtom);
const setInitialRunCompleted = useSetAtom(initialRunCompletedAtom);
@@ -395,7 +383,7 @@ export function useNotebookSession(opts: {
);
return;
case "notebook-document-transaction":
- handleDocumentTransaction(msg.data.transaction);
+ // Edits reach the notebook through the host document.
return;
case "consumer-capabilities":
setKioskMode(!msg.data.consumer_capabilities.edit);
@@ -440,6 +428,38 @@ export function useNotebookSession(opts: {
},
});
+ const documentModel = useMemo(
+ () =>
+ createDocumentModel({
+ store,
+ documentAtom: replica.documentAtom,
+ backendAtom: replica.backendAtom,
+ }),
+ [store, replica],
+ );
+ // Edits outlive reconnects and end with the session. The notebook's cells
+ // follow the document for as long as the session is mounted.
+ useEffect(() => {
+ const controller = new AbortController();
+ documentModel.start({ signal: controller.signal });
+ store.set(activeDocumentModelAtom, documentModel);
+ const follow = () => {
+ const document = store.get(documentModel.documentAtom);
+ if (document !== null) {
+ reconcileDocument(document);
+ }
+ };
+ const unsubscribe = store.sub(documentModel.documentAtom, follow);
+ follow();
+ return () => {
+ unsubscribe();
+ controller.abort();
+ if (store.get(activeDocumentModelAtom) === documentModel) {
+ store.set(activeDocumentModelAtom, null);
+ }
+ };
+ }, [documentModel, store, reconcileDocument]);
+
// Subscribe before passive connection setup: static/WASM transports can emit synchronously.
useLayoutEffect(() => {
const updateConnection = () => {
@@ -485,5 +505,5 @@ export function useNotebookSession(opts: {
updateStartupProgress,
]);
- return { replica, connection, reconnect: replica.reconnect };
+ return { replica, documentModel, connection, reconnect: replica.reconnect };
}
diff --git a/frontend/src/core/wasm/__tests__/bridge.test.ts b/frontend/src/core/wasm/__tests__/bridge.test.ts
index 235f6d3459..9b74bbd9ef 100644
--- a/frontend/src/core/wasm/__tests__/bridge.test.ts
+++ b/frontend/src/core/wasm/__tests__/bridge.test.ts
@@ -101,9 +101,9 @@ vi.mock("@/core/wasm/store", () => ({
notebookFileStore: { readFile: mockNotebookReadFile, saveFile: vi.fn() },
}));
-vi.mock("@/core/cells/document-changes", () => ({
- flushDocumentChanges: mockFlush,
- documentTransactionMiddleware: vi.fn(),
+vi.mock("@/core/cells/document", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@/core/cells/document")>()),
+ flushDocument: mockFlush,
}));
// Import after all mocks are set up
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index ef4cf9fcb2..0cb53f3ac0 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -13,7 +13,7 @@ import { once } from "@/utils/once";
import { generateUUID } from "@/utils/uuid";
import { createModuleWorker } from "@/utils/worker";
import { notebookIsRunningAtom } from "../cells/cells";
-import { flushDocumentChanges } from "../cells/document-changes";
+import { flushDocument } from "../cells/document";
import { createWasmNotebookBackend } from "../transports/wasm";
import type { ClientCommand } from "../kernel/messages";
import { getInitialAppMode } from "../mode";
@@ -280,7 +280,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
}
public sendSave: EditRequests["sendSave"] = async ({ layout }) => {
- await flushDocumentChanges();
+ await flushDocument();
await this.rpc.proxy.request.setNotebookLayout(layout ?? null);
await this.saveHostNotebook();
return null;
@@ -565,7 +565,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
public exportAsHTML: EditRequests["exportAsHTML"] = async (
request: ExportAsHTMLRequest,
) => {
- await flushDocumentChanges();
+ await flushDocument();
const response = await this.rpc.proxy.request.bridge({
functionName: "export_html",
payload: withDevAssetUrl(request),
@@ -576,7 +576,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
public exportAsMarkdown: EditRequests["exportAsMarkdown"] = async (
request: ExportAsMarkdownRequest,
) => {
- await flushDocumentChanges();
+ await flushDocument();
const response = await this.rpc.proxy.request.bridge({
functionName: "export_markdown",
payload: request,
@@ -587,7 +587,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
public exportAsScript: EditRequests["exportAsScript"] = async (
request: ExportAsScriptRequest,
) => {
- await flushDocumentChanges();
+ await flushDocument();
const response = await this.rpc.proxy.request.bridge({
functionName: "export_script",
payload: request,
@@ -658,13 +658,6 @@ export class PyodideBridge implements RunRequests, EditRequests {
return null;
};
- public sendDocumentTransaction: EditRequests["sendDocumentTransaction"] =
- async (request) => {
- await this.initialized.promise;
- await this.rpc.proxy.request.documentTransaction(request);
- return null;
- };
-
public addPackage: EditRequests["addPackage"] = async (request) => {
return this.rpc.proxy.request.addPackage(request);
};
diff --git a/frontend/src/core/wasm/worker/worker.ts b/frontend/src/core/wasm/worker/worker.ts
index 9d4fe791fc..e5e6eb426c 100644
--- a/frontend/src/core/wasm/worker/worker.ts
+++ b/frontend/src/core/wasm/worker/worker.ts
@@ -12,7 +12,6 @@ import type { UserConfig } from "@/core/config/config-schema";
import type {
ListPackagesResponse,
PackageOperationResponse,
- NotebookDocumentTransactionRequest,
SaveNotebookRequest,
} from "@/core/network/types";
import { decodeUtf8 } from "@/utils/strings";
@@ -302,14 +301,6 @@ const requestHandler = createRPCRequestHandler({
};
},
- documentTransaction: async (request: NotebookDocumentTransactionRequest) => {
- const notebook = await getNotebook();
- try {
- await notebook.transaction(JSON.stringify(request));
- } finally {
- notebook.destroy();
- }
- },
setNotebookLayout: async (layout: SaveNotebookRequest["layout"]) => {
const notebook = await getNotebook();
try {
diff --git a/frontend/src/utils/__tests__/createReducer.test.ts b/frontend/src/utils/__tests__/createReducer.test.tsx
similarity index 85%
rename from frontend/src/utils/__tests__/createReducer.test.ts
rename to frontend/src/utils/__tests__/createReducer.test.tsx
index d504a5c8ba..47536c7170 100644
--- a/frontend/src/utils/__tests__/createReducer.test.ts
+++ b/frontend/src/utils/__tests__/createReducer.test.tsx
@@ -1,4 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
+import { renderHook } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import type { PropsWithChildren } from "react";
import { describe, expect, it, vi } from "vitest";
import { Logger } from "@/utils/Logger";
import { createReducer, createReducerAndAtoms } from "../createReducer";
@@ -140,6 +143,31 @@ describe("createReducerAndAtoms", () => {
expect(middleware).toHaveBeenCalledWith(state, { count: 5 }, action);
});
+ it("runs middleware after the write commits, so it sees the new state", () => {
+ const initialState = () => ({ count: 0 });
+ const reducers = {
+ increment: (state: State, payload: number) => ({
+ count: state.count + payload,
+ }),
+ };
+ const seen: number[] = [];
+ const { valueAtom, useActions } = createReducerAndAtoms(
+ initialState,
+ reducers,
+ [(_prev, next) => seen.push(store.get(valueAtom).count, next.count)],
+ );
+ const store = createStore();
+ const wrapper = ({ children }: PropsWithChildren) => (
+ <Provider store={store}>{children}</Provider>
+ );
+ const { result } = renderHook(() => useActions(), { wrapper });
+
+ result.current.increment(5);
+
+ expect(seen).toEqual([5, 5]);
+ expect(store.get(valueAtom)).toEqual({ count: 5 });
+ });
+
it("should log an error for non-existent action types", () => {
const initialState = () => ({ count: 0 });
const reducers = {
diff --git a/frontend/src/utils/createReducer.ts b/frontend/src/utils/createReducer.ts
index d551377836..d3563daa68 100644
--- a/frontend/src/utils/createReducer.ts
+++ b/frontend/src/utils/createReducer.ts
@@ -104,49 +104,70 @@ export function createReducerAndAtoms<
};
const { reducer, createActions } = createReducer(initialState, reducers);
- const reducerWithMiddleware = (state: State, action: ReducerActionOf<RH>) => {
+ const reduceSafely = (state: State, action: ReducerActionOf<RH>) => {
try {
- const newState = reducer(state, action);
- for (const mw of allMiddleware) {
- try {
- mw(state, newState, action);
- } catch (error) {
- Logger.error(`Error in middleware for action ${action.type}:`, error);
- }
- }
- return newState;
+ return reducer(state, action);
} catch (error) {
Logger.error(`Error in reducer for action ${action.type}:`, error);
return state;
}
};
+ const runMiddleware = (
+ prev: State,
+ next: State,
+ action: ReducerActionOf<RH>,
+ ) => {
+ for (const mw of allMiddleware) {
+ try {
+ mw(prev, next, action);
+ } catch (error) {
+ Logger.error(`Error in middleware for action ${action.type}:`, error);
+ }
+ }
+ };
+
+ const reducerWithMiddleware = (state: State, action: ReducerActionOf<RH>) => {
+ const next = reduceSafely(state, action);
+ runMiddleware(state, next, action);
+ return next;
+ };
+
const valueAtom = atom(initialState());
- // map of SetAtom => Actions
+ // map of SetAtom => Actions, with and without middleware
const actionsMap = new WeakMap();
+ const plainActionsMap = new WeakMap();
function useActions(
options: { skipMiddleware?: boolean } = {},
): ReducerActions<RH> {
const setState = useSetAtom(valueAtom);
+ const skipMiddleware = options.skipMiddleware === true;
+ const cache = skipMiddleware ? plainActionsMap : actionsMap;
- if (options.skipMiddleware === true) {
- return createActions((action: ReducerActionOf<RH>) => {
- setState((state: State) => reducer(state, action));
- });
- }
-
- if (!actionsMap.has(setState)) {
- actionsMap.set(
+ if (!cache.has(setState)) {
+ cache.set(
setState,
createActions((action: ReducerActionOf<RH>) => {
- setState((state: State) => reducerWithMiddleware(state, action));
+ // Reduce inside the write. Middleware runs once the write has
+ // committed and its subscribers have run, so anything it sets in
+ // turn observes the new state rather than the one being replaced.
+ let prev: State | undefined;
+ let next: State | undefined;
+ setState((state: State) => {
+ prev = state;
+ next = reduceSafely(state, action);
+ return next;
+ });
+ if (!skipMiddleware && prev !== undefined && next !== undefined) {
+ runMiddleware(prev, next, action);
+ }
}),
);
}
// oxlint-disable-next-line typescript/no-non-null-assertion
- return actionsMap.get(setState)!;
+ return cache.get(setState)!;
}
return {
diff --git a/marimo/_cli/development/schema.py b/marimo/_cli/development/schema.py
index 98cf952272..bf3ad21f06 100644
--- a/marimo/_cli/development/schema.py
+++ b/marimo/_cli/development/schema.py
@@ -385,7 +385,6 @@ def generate_server_api_schema() -> dict[str, Any]:
models.StdinRequest,
models.SuccessResponse,
models.UpdateCellConfigRequest,
- models.NotebookDocumentTransactionRequest,
models.FocusCellRequest,
session_requests.UpdateUIElementValuesRequest,
models.UpdateUIElementRequest,
diff --git a/marimo/_pyodide/notebook.py b/marimo/_pyodide/notebook.py
index 7cfd84da46..8e7e843500 100644
--- a/marimo/_pyodide/notebook.py
+++ b/marimo/_pyodide/notebook.py
@@ -12,14 +12,12 @@ import msgspec
from marimo._core import protocol
from marimo._core.calls import OperationCall, dispatch
from marimo._core.document import Document
-from marimo._core.errors import Conflict, Forbidden, Invalid
+from marimo._core.errors import Conflict, Invalid
from marimo._core.executions import Executions
from marimo._core.host import Host
from marimo._core.ids import mint
from marimo._core.notebook import Notebook
from marimo._core.operations import Mutations, problem
-from marimo._messaging.notebook import NotebookDocument, Transaction
-from marimo._messaging.notebook.reconcile import reconcile_transaction
from marimo._messaging.notification import (
NotebookDocumentTransactionNotification,
)
@@ -34,7 +32,6 @@ from marimo._runtime.layout.layout import (
)
from marimo._server.host import document as documents
from marimo._server.host.events import notification_event, serialize_event
-from marimo._server.models.models import NotebookDocumentTransactionRequest
from marimo._session.model import SessionMode
from marimo._session.notebook.writer import NotebookWriter, cells_to_ir
@@ -236,26 +233,6 @@ class PyodideNotebook:
if update is not None and self._session.instantiated:
self._session.put_control_request(update)
- async def transaction(self, raw: str) -> None:
- """Apply the editor's incremental transactions to the host document."""
- if self._session.mode is not SessionMode.EDIT:
- raise Forbidden("The notebook is read-only")
- request = msgspec.json.decode(
- raw, type=NotebookDocumentTransactionRequest
- )
- notebook = await self.host.notebook(self.id)
- self.refresh()
- staged = NotebookDocument(
- documents.to_notebook_cell(cell) for cell in notebook.document
- )
- changes = reconcile_transaction(tuple(request.changes), staged)
- staged.apply(Transaction(changes=changes, source="frontend"))
- notebook.replace(
- documents.sources(staged.cells), notebook.document.app_config
- )
- # Echoing an acknowledged edit could overwrite newer local typing.
- self._apply_to_session(notebook, notify=False)
-
async def update_config(self, config: dict[str, Any]) -> None:
notebook = await self.host.notebook(self.id)
self._session.app_manager.app.update_config(config)
diff --git a/marimo/_server/api/endpoints/document.py b/marimo/_server/api/endpoints/document.py
deleted file mode 100644
index 2987dde7d7..0000000000
--- a/marimo/_server/api/endpoints/document.py
+++ /dev/null
@@ -1,65 +0,0 @@
-# Copyright 2026 Marimo. All rights reserved.
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from starlette.authentication import requires
-
-from marimo._messaging.notebook.changes import Transaction
-from marimo._messaging.notebook.reconcile import reconcile_transaction
-from marimo._messaging.notification import (
- NotebookDocumentTransactionNotification,
-)
-from marimo._server.api.deps import AppState
-from marimo._server.api.utils import parse_request
-from marimo._server.models.models import (
- BaseResponse,
- NotebookDocumentTransactionRequest,
- SuccessResponse,
-)
-from marimo._server.router import APIRouter
-from marimo._types.ids import ConsumerId
-
-if TYPE_CHECKING:
- from starlette.requests import Request
-
-router = APIRouter()
-
-
[email protected]("/transaction")
-@requires("edit")
-async def document_transaction(request: Request) -> BaseResponse:
- """
- parameters:
- - in: header
- name: Marimo-Session-Id
- schema:
- type: string
- required: true
- requestBody:
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/NotebookDocumentTransactionRequest"
- responses:
- 200:
- description: Apply a document transaction
- content:
- application/json:
- schema:
- $ref: "#/components/schemas/SuccessResponse"
- """
- app_state = AppState(request)
- body = await parse_request(request, cls=NotebookDocumentTransactionRequest)
- session = app_state.require_current_session()
- session_id = app_state.require_current_session_id()
-
- sanitized = reconcile_transaction(tuple(body.changes), session.document)
- transaction = Transaction(changes=sanitized, source="frontend")
- applied = session.document.apply(transaction)
- session.notify(
- NotebookDocumentTransactionNotification(transaction=applied),
- from_consumer_id=ConsumerId(session_id),
- )
-
- return SuccessResponse()
diff --git a/marimo/_server/api/router.py b/marimo/_server/api/router.py
index 0173a9c936..8bb8c11816 100644
--- a/marimo/_server/api/router.py
+++ b/marimo/_server/api/router.py
@@ -10,7 +10,6 @@ from marimo._server.api.endpoints.config import router as config_router
from marimo._server.api.endpoints.datasources import (
router as datasources_router,
)
-from marimo._server.api.endpoints.document import router as document_router
from marimo._server.api.endpoints.documentation import (
router as documentation_router,
)
@@ -62,9 +61,6 @@ def build_routes(base_url: str = "") -> list[BaseRoute]:
app_router.include_router(
documentation_router, prefix="/api/documentation", name="documentation"
)
- app_router.include_router(
- document_router, prefix="/api/document", name="document"
- )
app_router.include_router(
datasources_router, prefix="/api/datasources", name="datasources"
)
diff --git a/marimo/_server/models/models.py b/marimo/_server/models/models.py
index 9f25dec41c..84f249b2d3 100644
--- a/marimo/_server/models/models.py
+++ b/marimo/_server/models/models.py
@@ -6,7 +6,6 @@ from typing import Any, Literal
import msgspec
from marimo._ast.cell import CellConfig
-from marimo._messaging.notebook.changes import DocumentChange
from marimo._runtime.commands import (
ClearCacheCommand,
CodeCompletionCommand,
@@ -254,10 +253,6 @@ class RenameNotebookRequest(msgspec.Struct, rename="camel"):
filename: str
-class NotebookDocumentTransactionRequest(msgspec.Struct, rename="camel"):
- changes: list[DocumentChange]
-
-
class FocusCellRequest(msgspec.Struct, rename="camel"):
cell_id: CellId_t
diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yaml
index a99d1e4513..38dc1c70c1 100644
--- a/packages/openapi/api.yaml
+++ b/packages/openapi/api.yaml
@@ -4195,33 +4195,6 @@ components:
- transaction
title: NotebookDocumentTransactionNotification
type: object
- NotebookDocumentTransactionRequest:
- properties:
- changes:
- items:
- anyOf:
- - $ref: '#/components/schemas/CreateCell'
- - $ref: '#/components/schemas/DeleteCell'
- - $ref: '#/components/schemas/MoveCell'
- - $ref: '#/components/schemas/ReorderCells'
- - $ref: '#/components/schemas/SetCode'
- - $ref: '#/components/schemas/SetName'
- - $ref: '#/components/schemas/SetConfig'
- discriminator:
- mapping:
- create-cell: '#/components/schemas/CreateCell'
- delete-cell: '#/components/schemas/DeleteCell'
- move-cell: '#/components/schemas/MoveCell'
- reorder-cells: '#/components/schemas/ReorderCells'
- set-code: '#/components/schemas/SetCode'
- set-config: '#/components/schemas/SetConfig'
- set-name: '#/components/schemas/SetName'
- propertyName: type
- type: array
- required:
- - changes
- title: NotebookDocumentTransactionRequest
- type: object
NotificationMessage:
anyOf:
- $ref: '#/components/schemas/CellNotification'
@@ -6796,26 +6769,6 @@ paths:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: Preview a list of tables in an SQL schema
- /api/document/transaction:
- post:
- parameters:
- - in: header
- name: Marimo-Session-Id
- required: true
- schema:
- type: string
- requestBody:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/NotebookDocumentTransactionRequest'
- responses:
- 200:
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/SuccessResponse'
- description: Apply a document transaction
/api/documentation/snippets:
get:
parameters:
diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.ts
index f73058107c..414bbc0e62 100644
--- a/packages/openapi/src/api.ts
+++ b/packages/openapi/src/api.ts
@@ -612,47 +612,6 @@ export interface paths {
patch?: never;
trace?: never;
};
- "/api/document/transaction": {
- parameters: {
- query?: never;
- header?: never;
- path?: never;
- cookie?: never;
- };
- get?: never;
- put?: never;
- post: {
- parameters: {
- query?: never;
- header: {
- "Marimo-Session-Id": string;
- };
- path?: never;
- cookie?: never;
- };
- requestBody?: {
- content: {
- "application/json": components["schemas"]["NotebookDocumentTransactionRequest"];
- };
- };
- responses: {
- /** @description Apply a document transaction */
- 200: {
- headers: {
- [name: string]: unknown;
- };
- content: {
- "application/json": components["schemas"]["SuccessResponse"];
- };
- };
- };
- };
- delete?: never;
- options?: never;
- head?: never;
- patch?: never;
- trace?: never;
- };
"/api/documentation/snippets": {
parameters: {
query?: never;
@@ -6303,18 +6262,6 @@ export interface components {
op: "notebook-document-transaction";
transaction: components["schemas"]["Transaction"];
};
- /** NotebookDocumentTransactionRequest */
- NotebookDocumentTransactionRequest: {
- changes: (
- | components["schemas"]["CreateCell"]
- | components["schemas"]["DeleteCell"]
- | components["schemas"]["MoveCell"]
- | components["schemas"]["ReorderCells"]
- | components["schemas"]["SetCode"]
- | components["schemas"]["SetName"]
- | components["schemas"]["SetConfig"]
- )[];
- };
NotificationMessage:
| components["schemas"]["CellNotification"]
| components["schemas"]["ExecutionNotification"]
diff --git a/tests/_pyodide/test_pyodide_notebook.py b/tests/_pyodide/test_pyodide_notebook.py
index 2393113e3f..aeb7674bdc 100644
--- a/tests/_pyodide/test_pyodide_notebook.py
+++ b/tests/_pyodide/test_pyodide_notebook.py
@@ -466,32 +466,40 @@ async def test_save_serializes_writes_and_checks_revision_after_waiting(
assert notebook.saved_etag == notebook.document.etag
-async def test_editor_transactions_config_layout_and_reload(bridge):
+async def test_host_edits_config_layout_and_reload(bridge):
events = await snapshot(bridge)
- messages = []
- bridge.session.consumers.append(messages.append)
- cell_id = events[1]["data"]["cell"]["id"]
- await bridge.notebook.transaction(
- json.dumps(
- {
+ cell = next(e["data"]["cell"] for e in events if e["event"] == "cell")
+ edited = await send(
+ bridge,
+ {
+ "operation": "notebook.edit",
+ "params": {"notebook_id": bridge.notebook.id},
+ "headers": {"idempotency-key": "edit-1"},
+ "body": {
"changes": [
- {"type": "set-code", "cellId": cell_id, "code": "x = 9"},
- {"type": "set-name", "cellId": cell_id, "name": "example"},
{
- "type": "create-cell",
- "cellId": "new",
- "code": "y = 2",
- "name": "_",
- "config": {},
+ "kind": "put_cell",
+ "base_etag": cell["etag"],
+ "cell": {
+ "id": cell["id"],
+ "code": "x = 9",
+ "name": "example",
+ "config": cell["config"],
+ },
+ },
+ {
+ "kind": "put_cell",
+ "base_etag": None,
+ "before": cell["id"],
+ "cell": {"id": "new", "code": "y = 2"},
},
- {"type": "reorder-cells", "cellIds": ["new", cell_id]},
]
- }
- )
+ },
+ },
)
- assert not messages # Do not echo old typing into the editor.
+ assert edited["status"] == 200, edited
await bridge.save_app_config(json.dumps({"config": {"width": "full"}}))
- layout = {"type": "slides", "data": {"slides": [[cell_id]]}}
+ layout = {"type": "slides", "data": {"slides": [[cell["id"]]]}}
await bridge.notebook.set_layout(json.dumps(layout))
path = bridge.session.app_manager.filename
@@ -507,15 +515,24 @@ async def test_editor_transactions_config_layout_and_reload(bridge):
assert list(restored.app.cell_manager.names()) == ["_", "example"]
assert restored.app.config.width == "full"
assert restored.read_layout_config() == LayoutConfig(**layout)
- await bridge.notebook.transaction(
- json.dumps(
- {
+ deleted = await send(
+ bridge,
+ {
+ "operation": "notebook.edit",
+ "params": {"notebook_id": bridge.notebook.id},
+ "headers": {"idempotency-key": "edit-2"},
+ "body": {
"changes": [
- {"type": "delete-cell", "cellId": "new"},
+ {
+ "kind": "delete_cell",
+ "id": "new",
+ "base_etag": edited["body"]["cells"]["new"]["etag"],
+ }
]
- }
- )
+ },
+ },
)
+ assert deleted["status"] == 200, deleted
assert list(bridge.session.app_manager.app.cell_manager.codes()) == [
"x = 9"
]
diff --git a/tests/_pyodide/test_pyodide_session.py b/tests/_pyodide/test_pyodide_session.py
index 471303b301..7d046cf327 100644
--- a/tests/_pyodide/test_pyodide_session.py
+++ b/tests/_pyodide/test_pyodide_session.py
@@ -877,21 +877,30 @@ async def test_pyodide_bridge_format(pyodide_bridge: PyodideBridge) -> None:
async def test_pyodide_bridge_document_export(
pyodide_bridge: PyodideBridge,
) -> None:
- request_json = json.dumps(
- {
- "changes": [
+ result = json.loads(
+ await pyodide_bridge.notebook.call(
+ json.dumps(
{
- "type": "create-cell",
- "cellId": "test",
- "code": 'message = "NEW"',
- "name": "_",
- "config": {},
+ "operation": "notebook.edit",
+ "params": {"notebook_id": pyodide_bridge.notebook.id},
+ "headers": {"idempotency-key": "edit-1"},
+ "body": {
+ "changes": [
+ {
+ "kind": "put_cell",
+ "base_etag": None,
+ "cell": {
+ "id": "test",
+ "code": 'message = "NEW"',
+ },
+ }
+ ]
+ },
}
- ],
- }
+ )
+ )
)
-
- await pyodide_bridge.notebook.transaction(request_json)
+ assert result["status"] == 200, result
request = json.dumps({"download": False})
script = json.loads(pyodide_bridge.export_script(request))
diff --git a/tests/_server/api/endpoints/test_document_endpoints.py b/tests/_server/api/endpoints/test_document_endpoints.py
deleted file mode 100644
index c03c1c7869..0000000000
--- a/tests/_server/api/endpoints/test_document_endpoints.py
+++ /dev/null
@@ -1,76 +0,0 @@
-# Copyright 2026 Marimo. All rights reserved.
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from tests._server.api.endpoints.ws_helpers import (
- HEADERS as _HEADERS,
- assert_kernel_ready_response,
- receive_notification,
-)
-
-if TYPE_CHECKING:
- from starlette.testclient import TestClient
-
-HEADERS = {
- **_HEADERS,
- "Marimo-Session-Id": "123",
-}
-
-
-def test_create_cell_with_missing_anchor_is_appended(
- client: TestClient,
-) -> None:
- with client.websocket_connect(
- "/ws?session_id=123", headers=_HEADERS
- ) as websocket:
- assert_kernel_ready_response(receive_notification(websocket))
-
- response = client.post(
- "/api/document/transaction",
- headers=HEADERS,
- json={
- "changes": [
- {
- "type": "create-cell",
- "cellId": "new1",
- "code": "",
- "name": "_",
- "config": {
- "column": None,
- "disabled": False,
- "hideCode": False,
- },
- "after": "ghost_cell_xyz",
- }
- ],
- },
- )
- assert response.status_code == 200, response.text
-
- sm = client.app.state.session_manager
- session = next(iter(sm.sessions.values()))
- assert session.document.cell_ids[-1] == "new1"
-
-
-def test_delete_of_missing_cell_is_a_no_op(client: TestClient) -> None:
- with client.websocket_connect(
- "/ws?session_id=123", headers=_HEADERS
- ) as websocket:
- assert_kernel_ready_response(receive_notification(websocket))
-
- sm = client.app.state.session_manager
- session = next(iter(sm.sessions.values()))
- cell_ids_before = session.document.cell_ids
-
- response = client.post(
- "/api/document/transaction",
- headers=HEADERS,
- json={
- "changes": [
- {"type": "delete-cell", "cellId": "ghost_cell_xyz"}
- ],
- },
- )
- assert response.status_code == 200, response.text
- assert session.document.cell_ids == cell_ids_before
diff --git a/tests/_server/api/endpoints/test_export.py b/tests/_server/api/endpoints/test_export.py
index cd59da3439..1bf0ec6365 100644
--- a/tests/_server/api/endpoints/test_export.py
+++ b/tests/_server/api/endpoints/test_export.py
@@ -21,6 +21,8 @@ from marimo._convert.markdown.flavor.base import MarkdownFlavorName
from marimo._dependencies.dependencies import DependencyManager
from marimo._export.requests import PDFExportRequest
from marimo._messaging.cell_output import CellChannel, CellOutput
+from marimo._messaging.notebook import Transaction
+from marimo._messaging.notebook.changes import SetCode
from marimo._messaging.notification import CellNotification
from marimo._output.utils import uri_encode_component
from marimo._runtime.layout.layout import LayoutConfig
@@ -994,20 +996,17 @@ def test_auto_export_html(client: TestClient, temp_marimo_file: str) -> None:
)
)
cell_id = session.document.cell_ids[0]
- response = client.post(
- "/api/document/transaction",
- headers=HEADERS,
- json={
- "changes": [
- {
- "type": "set-code",
- "cellId": cell_id,
- "code": 'live_value = "export-current-session"',
- }
- ]
- },
+ session.document.apply(
+ Transaction(
+ changes=(
+ SetCode(
+ cell_id=cell_id,
+ code='live_value = "export-current-session"',
+ ),
+ ),
+ source="frontend",
+ )
)
- assert response.status_code == 200
def auto_export(**overrides: object) -> Response:
return client.post(
diff --git a/tests/_server/api/endpoints/test_kiosk.py b/tests/_server/api/endpoints/test_kiosk.py
index 5b23fa84c5..a293138f6e 100644
--- a/tests/_server/api/endpoints/test_kiosk.py
+++ b/tests/_server/api/endpoints/test_kiosk.py
@@ -1,7 +1,7 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
from tests._server.api.endpoints.ws_helpers import (
HEADERS as _HEADERS,
@@ -10,6 +10,7 @@ from tests._server.api.endpoints.ws_helpers import (
receive_notification,
receive_until,
)
+from tests._server.host.drive import socket_snapshot
if TYPE_CHECKING:
from starlette.testclient import TestClient
@@ -21,11 +22,29 @@ HEADERS = {
}
+def notebook_id_of(snapshot: list[dict[str, Any]]) -> str:
+ return next(
+ event["data"]["notebook"]["id"]
+ for event in snapshot
+ if event["event"] == "notebook"
+ )
+
+
+def new_cell(cell_id: str) -> dict[str, Any]:
+ """A host edit that adds a cell, which every consumer hears about."""
+ return {
+ "kind": "put_cell",
+ "base_etag": None,
+ "cell": {"id": cell_id, "code": f"{cell_id} = 1"},
+ }
+
+
async def test_connect_kiosk_with_session(client: TestClient) -> None:
# Create the first session
with client.websocket_connect(
"/ws?session_id=123", headers=_HEADERS
) as websocket:
+ notebook_id = notebook_id_of(socket_snapshot(websocket))
editor_ready = receive_notification(websocket)
assert_kernel_ready_response(editor_ready)
@@ -54,18 +73,11 @@ async def test_connect_kiosk_with_session(client: TestClient) -> None:
== "environment-state"
)
- # Send document transaction to reorder cells
+ # Edit the notebook through the host
response = client.post(
- "/api/document/transaction",
- headers=HEADERS,
- json={
- "changes": [
- {
- "type": "reorder-cells",
- "cellIds": ["cell-123"],
- }
- ],
- },
+ f"/api/marimo/v1/notebooks/{notebook_id}/edits",
+ headers={**HEADERS, "Idempotency-Key": "edit-1"},
+ json={"changes": [new_cell("fresh")]},
)
assert response.status_code == 200, response.text
@@ -173,6 +185,7 @@ def test_takeover_ping_pong_preserves_membership(client: TestClient) -> None:
def test_third_viewer_survives_takeover(client: TestClient) -> None:
with client.websocket_connect("/ws?session_id=a", headers=_HEADERS) as ta:
+ notebook_id = notebook_id_of(socket_snapshot(ta))
assert_kernel_ready_response(receive_notification(ta))
with client.websocket_connect(
"/ws?session_id=b", headers=_HEADERS
@@ -192,13 +205,13 @@ def test_third_viewer_survives_takeover(client: TestClient) -> None:
# New editor (b) broadcasts; the third viewer (c) still gets it.
resp = client.post(
- "/api/document/transaction",
- headers={**HEADERS, "Marimo-Session-Id": "b"},
- json={
- "changes": [
- {"type": "reorder-cells", "cellIds": ["cell-123"]}
- ]
+ f"/api/marimo/v1/notebooks/{notebook_id}/edits",
+ headers={
+ **HEADERS,
+ "Marimo-Session-Id": "b",
+ "Idempotency-Key": "edit-1",
},
+ json={"changes": [new_cell("fresh")]},
)
assert resp.status_code == 200, resp.text
data = receive_until("notebook-document-transaction", tc)
diff --git a/tests/_server/test_scratchpad_integration.py b/tests/_server/test_scratchpad_integration.py
index 6f4cf07f39..2c6da1df31 100644
--- a/tests/_server/test_scratchpad_integration.py
+++ b/tests/_server/test_scratchpad_integration.py
@@ -13,8 +13,8 @@ stream out entirely, so real kernel timing and cross-process
notification ordering aren't testable there. These tests share one
`marimo edit` subprocess across the module and drive it through
the full HTTP surface: a websocket for session setup and
-`completed-run` synchronization, `/api/document/transaction` to
-populate `session.document` (required for `code_mode` cell
+`completed-run` synchronization, host edits to populate
+`session.document` (required for `code_mode` cell
lookup by name), `/api/kernel/run` to register and execute cells,
and `/api/kernel/execute` to hit the scratchpad. Each test gets a
fresh session via a per-test `session` fixture that calls
@@ -39,18 +39,10 @@ import time
import uuid
from typing import TYPE_CHECKING, Any
-import msgspec
import pytest
import websockets.sync.client
from inline_snapshot import snapshot
-from marimo._ast.cell import CellConfig
-from marimo._messaging.notebook.changes import (
- CreateCell,
- DocumentChange,
-)
-from marimo._types.ids import CellId_t
-
if TYPE_CHECKING:
from collections.abc import Callable, Generator
from pathlib import Path
@@ -155,6 +147,8 @@ class _Session:
def __init__(self, base: str) -> None:
self.base = base
self.session_id = f"it_{uuid.uuid4().hex[:8]}"
+ self.notebook_id = ""
+ self.cells: dict[str, str] = {}
self.ws = websockets.sync.client.connect(
f"{base.replace('http', 'ws')}/ws?session_id={self.session_id}",
open_timeout=5,
@@ -189,6 +183,11 @@ class _Session:
raise TimeoutError("websocket predicate never satisfied")
raw = self.ws.recv(timeout=remaining)
event = json.loads(raw)
+ if event["event"] == "notebook":
+ self.notebook_id = event["data"]["notebook"]["id"]
+ if event["event"] == "cell":
+ cell = event["data"]["cell"]
+ self.cells[cell["id"]] = cell["etag"]
if event["event"] != "marimo":
continue
msg: dict[str, Any] = event["data"]["marimo"]
@@ -202,7 +201,12 @@ class _Session:
timeout_s=timeout_s,
)
- def _post(self, path: str, body: dict[str, Any]) -> str:
+ def _post(
+ self,
+ path: str,
+ body: dict[str, Any],
+ headers: dict[str, str] | None = None,
+ ) -> str:
import urllib.request
req = urllib.request.Request(
@@ -212,18 +216,26 @@ class _Session:
headers={
"Content-Type": "application/json",
"Marimo-Session-Id": self.session_id,
+ **(headers or {}),
},
)
with urllib.request.urlopen(req, timeout=10) as resp:
text: str = resp.read().decode()
return text
- def apply_changes(self, changes: list[DocumentChange]) -> None:
- """POST a document transaction built from typed change objects."""
- self._post(
- "/api/document/transaction",
- {"changes": msgspec.to_builtins(changes)},
+ def edit(self, changes: list[dict[str, Any]]) -> None:
+ """Edit the notebook through the host, as the frontend does."""
+ body = self._post(
+ f"/api/marimo/v1/notebooks/{self.notebook_id}/edits",
+ {"changes": changes},
+ headers={"Idempotency-Key": uuid.uuid4().hex},
)
+ # The response names each cell the edit touched, null if deleted.
+ for cell_id, cell in json.loads(body)["cells"].items():
+ if cell is None:
+ self.cells.pop(cell_id, None)
+ else:
+ self.cells[cell_id] = cell["etag"]
def run_cells(self, cell_ids: list[str], codes: list[str]) -> None:
"""Register + run cells in the kernel graph, then wait for idle."""
@@ -239,25 +251,33 @@ class _Session:
codes: list[str],
names: list[str] | None = None,
) -> None:
- """Register cells in both `session.document` and the kernel graph.
+ """Make the notebook hold exactly these cells, then run them.
`/api/kernel/run` only touches the graph; `ctx.edit_cell` /
`ctx.run_cell` in code_mode look up cells from
- `session.document`, which is kept in sync via document
- transactions from the frontend. We emulate the frontend with
- typed `CreateCell` changes.
+ `session.document`, which host edits keep in sync. The host
+ notebook outlives the session, so cells from earlier tests are
+ deleted here.
"""
if names is None:
names = cell_ids
- self.apply_changes(
+ self.edit(
[
- CreateCell(
- cell_id=CellId_t(cid),
- code=code,
- name=name,
- config=CellConfig(),
- )
- for cid, code, name in zip(cell_ids, codes, names, strict=True)
+ *(
+ {"kind": "delete_cell", "id": cid, "base_etag": etag}
+ for cid, etag in self.cells.items()
+ if cid not in cell_ids
+ ),
+ *(
+ {
+ "kind": "put_cell",
+ "base_etag": self.cells.get(cid),
+ "cell": {"id": cid, "code": code, "name": name},
+ }
+ for cid, code, name in zip(
+ cell_ids, codes, names, strict=True
+ )
+ ),
]
)
self.run_cells(cell_ids, codes)