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.

Save WASM notebooks through the host (#11498)

Trevor Manzb0c6616e2888
diff --git a/frontend/src/core/host/__tests__/fixtures.ts b/frontend/src/core/host/__tests__/fixtures.ts
index 783f176672..f8d8131530 100644
--- a/frontend/src/core/host/__tests__/fixtures.ts
+++ b/frontend/src/core/host/__tests__/fixtures.ts
@@ -15,20 +15,28 @@ export type FakeEdit = (
...args: Parameters<Commands["edit"]>
) => ReturnType<Commands["edit"]>;
-/** A backend over `transport` whose edits go to `edit`. */
+export type FakeSave = (
+ notebookId: Protocol.NotebookId,
+ ...args: Parameters<Commands["save"]>
+) => ReturnType<Commands["save"]>;
+
+/** A backend over `transport` whose commands go to `edit` and `save`. */
export function fakeBackend({
transport = async () => undefined,
edit = vi.fn<FakeEdit>(),
+ save = vi.fn<FakeSave>(),
checkHealth,
}: {
transport?: NotebookTransport;
edit?: FakeEdit;
+ save?: FakeSave;
checkHealth?: () => Promise<boolean>;
} = {}): NotebookBackend {
return {
transport,
notebook: (notebookId) => ({
edit: (...args) => edit(notebookId, ...args),
+ save: (...args) => save(notebookId, ...args),
}),
checkHealth,
};
diff --git a/frontend/src/core/host/__tests__/static.test.ts b/frontend/src/core/host/__tests__/static.test.ts
index 43f7825374..63a01384e3 100644
--- a/frontend/src/core/host/__tests__/static.test.ts
+++ b/frontend/src/core/host/__tests__/static.test.ts
@@ -127,19 +127,25 @@ describe("static notebook backend", () => {
expect(events.at(-1)).toEqual({ event: "ready", id: "static", data: {} });
});
- it("advertises no mutations and returns a protocol failure for direct edits", async () => {
- const backend = createStaticNotebookBackend(snapshot());
- expect(await backend.notebook(snapshot().notebook.id).edit([])).toEqual({
- ok: false,
- status: 501,
- problem: {
- type: "tag:marimo.io,2026:host/unsupported-operation",
- title: "Unsupported operation",
+ it.each(["edit", "save"] as const)(
+ "rejects direct %s commands",
+ async (operation) => {
+ const backend = createStaticNotebookBackend(snapshot());
+ const client = backend.notebook(snapshot().notebook.id);
+ const result =
+ operation === "edit" ? await client.edit([]) : await client.save();
+ expect(result).toEqual({
+ ok: false,
status: 501,
- detail: "Static notebooks do not support editing",
- },
- });
- });
+ problem: {
+ type: "tag:marimo.io,2026:host/unsupported-operation",
+ title: "Unsupported operation",
+ status: 501,
+ detail: "Static notebooks do not support mutations",
+ },
+ });
+ },
+ );
it("respects cancellation before opening, during delivery, and for commands", async () => {
const backend = createStaticNotebookBackend(snapshot());
diff --git a/frontend/src/core/host/__tests__/wasm.test.ts b/frontend/src/core/host/__tests__/wasm.test.ts
index 3780cf1ad2..1b3aca59f9 100644
--- a/frontend/src/core/host/__tests__/wasm.test.ts
+++ b/frontend/src/core/host/__tests__/wasm.test.ts
@@ -23,7 +23,6 @@ function worker() {
const reply = { ok: true, status: 200, data: { document, cells: {} } };
const wire = { status: 200, body: reply.data };
const bridge = {
- notebookId: "n1",
subscribe: vi.fn(
async (_cursor: string | null, emit: (event: unknown) => void) => {
listeners.add(emit);
@@ -100,64 +99,68 @@ describe("WASM notebook backend", () => {
).rejects.toBeInstanceOf(StreamStopped);
});
- it("refuses commands for any notebook but the worker's", () => {
- const { bridge } = worker();
- expect(() => createWasmNotebookBackend(bridge).notebook("n2")).toThrow(
- "serves notebook n1, not n2",
- );
- expect(bridge.call).not.toHaveBeenCalled();
- });
-
- it("sends edits as calls with the retry key and validates replies", async () => {
- const { bridge, reply } = worker();
- const backend = createWasmNotebookBackend(bridge);
- expect(
- await backend.notebook("n1").edit([], { idempotencyKey: "edit-7" }),
- ).toEqual(reply);
- expect(bridge.call).toHaveBeenCalledWith({
- operation: "notebook.edit",
- params: { notebook_id: "n1" },
- headers: { "idempotency-key": "edit-7" },
- body: { changes: [] },
- });
- const problem = {
- type: "tag:marimo.io,2026:host/forbidden",
- title: "Forbidden",
- status: 403,
- };
- bridge.call.mockResolvedValue({ status: 403, body: problem });
- expect(await backend.notebook("n1").edit([])).toEqual({
- ok: false,
- status: 403,
- problem,
- });
- bridge.call.mockResolvedValue({ status: 200, body: {} });
- await expect(backend.notebook("n1").edit([])).rejects.toThrow(
- /Invalid input/,
- );
- });
+ it.each(["edit", "save"] as const)(
+ "sends %s calls with the retry key and validates replies",
+ async (operation) => {
+ const { bridge, reply } = worker();
+ const notebook = createWasmNotebookBackend(bridge).notebook("n1");
+ const command =
+ operation === "edit"
+ ? notebook.edit.bind(notebook, [])
+ : notebook.save.bind(notebook);
+ expect(await command({ idempotencyKey: `${operation}-7` })).toEqual(
+ reply,
+ );
+ expect(bridge.call).toHaveBeenCalledWith({
+ operation: `notebook.${operation}`,
+ params: { notebook_id: "n1" },
+ headers: { "idempotency-key": `${operation}-7` },
+ body: operation === "edit" ? { changes: [] } : {},
+ });
+ const problem = {
+ type: "tag:marimo.io,2026:host/forbidden",
+ title: "Forbidden",
+ status: 403,
+ };
+ bridge.call.mockResolvedValue({ status: 403, body: problem });
+ expect(await command()).toEqual({
+ ok: false,
+ status: 403,
+ problem,
+ });
+ bridge.call.mockResolvedValue({ status: 200, body: {} });
+ await expect(command()).rejects.toThrow(/Invalid input/);
+ },
+ );
- it("cancels waiting for an accepted edit and permits retry with the same key", async () => {
- const { bridge, reply, wire } = worker();
- const pending = new Deferred<unknown>();
- bridge.call.mockReturnValue(pending.promise);
- const backend = createWasmNotebookBackend(bridge);
- const controller = new AbortController();
- const editing = backend.notebook("n1").edit([], {
- signal: controller.signal,
- idempotencyKey: "edit-8",
- });
- await vi.waitFor(() => expect(bridge.call).toHaveBeenCalledOnce());
- controller.abort();
- await expect(editing).rejects.toBe(controller.signal.reason);
- pending.resolve(wire);
- expect(
- await backend.notebook("n1").edit([], { idempotencyKey: "edit-8" }),
- ).toEqual(reply);
- expect(bridge.call.mock.calls[0]).toEqual(bridge.call.mock.calls[1]);
- await expect(
- backend.notebook("n1").edit([], { signal: controller.signal }),
- ).rejects.toBe(controller.signal.reason);
- expect(bridge.call).toHaveBeenCalledTimes(2);
- });
+ it.each(["edit", "save"] as const)(
+ "cancels waiting for an accepted %s and permits retry with the same key",
+ async (operation) => {
+ const { bridge, reply, wire } = worker();
+ const pending = new Deferred<unknown>();
+ bridge.call.mockReturnValue(pending.promise);
+ const notebook = createWasmNotebookBackend(bridge).notebook("n1");
+ const command =
+ operation === "edit"
+ ? notebook.edit.bind(notebook, [])
+ : notebook.save.bind(notebook);
+ const controller = new AbortController();
+ const pendingCommand = command({
+ signal: controller.signal,
+ idempotencyKey: `${operation}-8`,
+ });
+ await vi.waitFor(() => expect(bridge.call).toHaveBeenCalledOnce());
+ controller.abort();
+ await expect(pendingCommand).rejects.toBe(controller.signal.reason);
+ pending.resolve(wire);
+ expect(await command({ idempotencyKey: `${operation}-8` })).toEqual(
+ reply,
+ );
+ expect(bridge.call.mock.calls[0]).toEqual(bridge.call.mock.calls[1]);
+ await expect(command({ signal: controller.signal })).rejects.toBe(
+ controller.signal.reason,
+ );
+ expect(bridge.call).toHaveBeenCalledTimes(2);
+ },
+ );
});
diff --git a/frontend/src/core/host/backend.ts b/frontend/src/core/host/backend.ts
index de6ce62d11..64460111db 100644
--- a/frontend/src/core/host/backend.ts
+++ b/frontend/src/core/host/backend.ts
@@ -13,7 +13,7 @@ export interface NotebookBackend {
*
* Method presence is not permission. The notebook advertises its operations.
*/
- notebook(id: NotebookId): Pick<NotebookClient, "edit">;
+ notebook(id: NotebookId): Pick<NotebookClient, "edit" | "save">;
/** Whether the host is reachable before an explicit reconnect. Absent means always. */
checkHealth?(): Promise<boolean>;
}
diff --git a/frontend/src/core/host/static.ts b/frontend/src/core/host/static.ts
index e44cafbc90..c86f305f01 100644
--- a/frontend/src/core/host/static.ts
+++ b/frontend/src/core/host/static.ts
@@ -2,6 +2,7 @@
/** A backend that serves a document snapshot without a host. */
+import type { NotebookClient } from "@marimo-team/client";
import type * as Protocol from "@marimo-team/client/protocol";
import type { NotebookBackend } from "./backend";
@@ -53,8 +54,8 @@ export function createStaticNotebookBackend(
message(frame);
}
}),
- notebook: () => ({
- edit: async (_changes, options) => {
+ notebook: () => {
+ const unsupported: NotebookClient["save"] = async (options) => {
options?.signal?.throwIfAborted();
return {
ok: false,
@@ -63,10 +64,14 @@ export function createStaticNotebookBackend(
type: "tag:marimo.io,2026:host/unsupported-operation",
title: "Unsupported operation",
status: 501,
- detail: "Static notebooks do not support editing",
+ detail: "Static notebooks do not support mutations",
},
};
- },
- }),
+ };
+ return {
+ edit: (_changes, options) => unsupported(options),
+ save: unsupported,
+ };
+ },
};
}
diff --git a/frontend/src/core/host/wasm.ts b/frontend/src/core/host/wasm.ts
index 909c5b344a..89dc47a7c1 100644
--- a/frontend/src/core/host/wasm.ts
+++ b/frontend/src/core/host/wasm.ts
@@ -11,7 +11,6 @@ import type { NotebookBackend } from "./backend";
/** The worker owns the notebook; this interface only carries commands and events. */
export interface WasmNotebookBridge {
- readonly notebookId: string;
subscribe(
cursor: string | null,
emit: (event: unknown) => void,
@@ -42,9 +41,6 @@ function abortable<T>(
export function createWasmNotebookBackend(
bridge: WasmNotebookBridge,
): NotebookBackend {
- const client = NotebookClient.unstable_over((call) => bridge.call(call), {
- notebookId: bridge.notebookId,
- });
return {
transport: async ({ cursor, signal }, { open, message }) => {
if (signal.aborted) {
@@ -95,13 +91,7 @@ export function createWasmNotebookBackend(
signal.removeEventListener("abort", abort);
}
},
- notebook: (id) => {
- if (id !== bridge.notebookId) {
- throw new Error(
- `The worker serves notebook ${bridge.notebookId}, not ${id}`,
- );
- }
- return client;
- },
+ notebook: (notebookId) =>
+ NotebookClient.unstable_over((call) => bridge.call(call), { notebookId }),
};
}
diff --git a/frontend/src/core/saving/save-component.tsx b/frontend/src/core/saving/save-component.tsx
index eb776652d2..bdbfaa52d9 100644
--- a/frontend/src/core/saving/save-component.tsx
+++ b/frontend/src/core/saving/save-component.tsx
@@ -21,7 +21,10 @@ import { Label } from "../../components/ui/label";
import { useEvent } from "../../hooks/useEvent";
import { Logger } from "../../utils/Logger";
import { getCellConfigs, getNotebook, useNotebook } from "../cells/cells";
-import { withDocumentSave } from "../cells/document-changes";
+import {
+ flushDocumentChanges,
+ withDocumentSave,
+} from "../cells/document-changes";
import { notebookCells } from "../cells/utils";
import { formatAll } from "../codemirror/format";
import { autoSaveConfigAtom } from "../config/config";
@@ -32,6 +35,7 @@ import { kioskModeAtom } from "../mode";
import { connectionAtom } from "../network/connection";
import { useRequestClient } from "../network/requests";
import { ConnectionState } from "../websocket/types";
+import { isWasm } from "../wasm/utils";
import { filenameAtom } from "./file-state";
import { useFilename, useUpdateFilename } from "./filename";
import { lastSavedNotebookAtom, needsSaveAtom } from "./state";
@@ -136,7 +140,7 @@ export function useSaveNotebook() {
return;
}
- const savedNotebook = await withDocumentSave(async () => {
+ const save = async () => {
// Grab the latest notebook state after formatting and after every
// earlier document transaction has reached the server.
const notebook = getNotebook();
@@ -157,7 +161,12 @@ export function useSaveNotebook() {
persist: true,
});
return { names: cellNames, codes, configs, layout };
- });
+ };
+ // 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 withDocumentSave(save);
setLastSavedNotebook(savedNotebook);
}),
);
diff --git a/frontend/src/core/wasm/__tests__/bridge.test.ts b/frontend/src/core/wasm/__tests__/bridge.test.ts
index 8b013a4b49..51d75928b2 100644
--- a/frontend/src/core/wasm/__tests__/bridge.test.ts
+++ b/frontend/src/core/wasm/__tests__/bridge.test.ts
@@ -8,20 +8,34 @@ const {
mockBridge,
mockNotebookReadFile,
mockReadNotebook,
- mockSaveNotebook,
+ mockWriteNotebook,
+ mockNotebookCall,
+ mockSetNotebookLayout,
+ mockFlush,
+ parentRequests,
mockBootstrap,
rpcListeners,
- mockNotebookInfo,
mockNotebookSubscribe,
mockNotebookUnsubscribe,
} = vi.hoisted(() => ({
mockBridge: vi.fn(),
mockNotebookReadFile: vi.fn(),
mockReadNotebook: vi.fn(),
- mockSaveNotebook: vi.fn(),
+ mockWriteNotebook: vi.fn(),
+ mockNotebookCall: vi.fn(),
+ mockSetNotebookLayout: vi.fn(),
+ mockFlush: vi.fn(),
+ parentRequests: {} as {
+ persistNotebook?: (snapshot: {
+ filename: string;
+ contents: string;
+ }) => Promise<void>;
+ },
mockBootstrap: vi.fn(),
- rpcListeners: {} as Record<string, () => void>,
- mockNotebookInfo: vi.fn(),
+ rpcListeners: {} as Record<
+ string,
+ (message?: { id: string; event: string }) => void
+ >,
mockNotebookSubscribe: vi.fn(),
mockNotebookUnsubscribe: vi.fn(),
}));
@@ -47,24 +61,31 @@ class MockURL extends URL {
vi.stubGlobal("URL", MockURL);
vi.mock("@/core/wasm/rpc", () => ({
- getWorkerRPC: () => ({
- send: { bootstrap: mockBootstrap },
- proxy: {
- request: {
- bridge: mockBridge,
- startSession: vi.fn(),
- readFile: vi.fn(),
- readNotebook: mockReadNotebook,
- saveNotebook: mockSaveNotebook,
- notebookInfo: mockNotebookInfo,
- notebookSubscribe: mockNotebookSubscribe,
- notebookUnsubscribe: mockNotebookUnsubscribe,
+ getWorkerRPC: (_worker: Worker, handlers?: typeof parentRequests) => {
+ Object.assign(parentRequests, handlers);
+ return {
+ send: { bootstrap: mockBootstrap },
+ proxy: {
+ request: {
+ bridge: mockBridge,
+ startSession: vi.fn(),
+ readFile: vi.fn(),
+ readNotebook: mockReadNotebook,
+ writeNotebook: mockWriteNotebook,
+ notebookSubscribe: mockNotebookSubscribe,
+ notebookUnsubscribe: mockNotebookUnsubscribe,
+ notebookCall: mockNotebookCall,
+ setNotebookLayout: mockSetNotebookLayout,
+ },
},
- },
- addMessageListener: (event: string, cb: () => void) => {
- rpcListeners[event] = cb;
- },
- }),
+ addMessageListener: (
+ event: string,
+ cb: (typeof rpcListeners)[string],
+ ) => {
+ rpcListeners[event] = cb;
+ },
+ };
+ },
}));
vi.mock("@/core/meta/globals", () => ({
@@ -80,14 +101,25 @@ vi.mock("@/core/wasm/store", () => ({
notebookFileStore: { readFile: mockNotebookReadFile, saveFile: vi.fn() },
}));
+vi.mock("@/core/cells/document-changes", () => ({
+ flushDocumentChanges: mockFlush,
+ documentTransactionMiddleware: vi.fn(),
+}));
+
// Import after all mocks are set up
import { store } from "@/core/state/jotai";
import { initialModeAtom } from "@/core/mode";
+import { fixtureEvents } from "@/core/host/__tests__/fixtures";
+import { createNotebookReplica } from "@/core/host";
+import { notebookReplicaAtom } from "@/core/websocket/state";
+import { createEditorBackend } from "@/core/websocket/backend";
+import { fallbackFileStore, notebookFileStore } from "../store";
import { getWasmWorkerName, PyodideBridge } from "../bridge";
-// Access INSTANCE once at module level so the constructor runs (and
-// addMessageListener populates rpcListeners) before any test executes.
-void PyodideBridge.INSTANCE;
+beforeEach(() => {
+ Reflect.deleteProperty(window, "_marimo_private_PyodideBridge");
+ void PyodideBridge.INSTANCE;
+});
describe("PyodideBridge.readCode", () => {
beforeEach(() => {
@@ -169,6 +201,7 @@ describe("PyodideBridge.exportAsScript", () => {
});
describe("PyodideBridge.sendSave", () => {
+ let disconnect: () => void;
const request = {
cellIds: [cellId("cell-1")],
codes: ['value = "NEW"'],
@@ -179,50 +212,140 @@ describe("PyodideBridge.sendSave", () => {
persist: true,
};
- beforeEach(() => {
+ beforeEach(async () => {
vi.clearAllMocks();
store.set(initialModeAtom, "edit");
rpcListeners.initialized();
- mockSaveNotebook.mockResolvedValue(null);
- mockReadNotebook.mockResolvedValue(
- "import marimo\napp = marimo.App()\n# NEW",
+ mockFlush.mockResolvedValue(undefined);
+ mockWriteNotebook.mockResolvedValue(undefined);
+ mockNotebookUnsubscribe.mockResolvedValue(undefined);
+ const document = fixtureEvents("notebook-events.sse").find(
+ (event) => event.event === "document",
+ )?.data.document;
+ mockNotebookCall.mockResolvedValue({
+ status: 200,
+ body: { document, cells: {} },
+ });
+ mockNotebookSubscribe.mockImplementation(async ({ id }) => {
+ for (const event of fixtureEvents("notebook-events.sse")) {
+ rpcListeners.notebookEvent({ id, event: JSON.stringify(event) });
+ }
+ });
+ const replica = createNotebookReplica(store);
+ store.set(notebookReplicaAtom, replica);
+ const backend = createEditorBackend({
+ static: false,
+ transportType: "sse",
+ url: () => "http://localhost/",
+ headers: () => ({}),
+ notebookUrl: (id) => new URL(`http://localhost/notebooks/${id}`),
+ waitUntilReady: async () => undefined,
+ checkHealth: async () => true,
+ });
+ disconnect = replica.connect(backend, { onNotification: vi.fn() });
+ await vi.waitFor(() =>
+ expect(store.get(replica.notebookAtom)?.id).toBe("n1"),
);
});
afterEach(() => {
+ disconnect();
+ store.set(notebookReplicaAtom, null);
store.set(initialModeAtom, undefined);
});
- it("waits for the session save before generating exports", async () => {
- const mainSave = new Deferred<void>();
- mockSaveNotebook
- .mockResolvedValueOnce(null)
- .mockReturnValueOnce(mainSave.promise);
+ it("saves through the connected backend using the stream's notebook ID", async () => {
+ const bridge = PyodideBridge.INSTANCE;
+ const createBackend = vi.spyOn(bridge, "createNotebookBackend");
+ await bridge.sendSave(request);
+ expect(createBackend).not.toHaveBeenCalled();
+ expect(mockNotebookCall).toHaveBeenCalledWith(
+ expect.objectContaining({
+ operation: "notebook.save",
+ params: { notebook_id: "n1" },
+ body: {},
+ }),
+ );
+ });
- await PyodideBridge.INSTANCE.sendSave(request);
- expect(mockSaveNotebook).toHaveBeenCalledTimes(2);
- expect(mockSaveNotebook).toHaveBeenNthCalledWith(1, request);
- expect(mockSaveNotebook).toHaveBeenNthCalledWith(2, request);
+ it.each(["unmounted", "not ready", "disconnected"])(
+ "does not save when the notebook is %s",
+ async (state) => {
+ if (state === "unmounted") {
+ store.set(notebookReplicaAtom, null);
+ } else if (state === "not ready") {
+ store.set(notebookReplicaAtom, createNotebookReplica(store));
+ } else {
+ disconnect();
+ }
+ await expect(PyodideBridge.INSTANCE.sendSave(request)).rejects.toThrow(
+ "The notebook is not connected",
+ );
+ expect(mockNotebookCall).not.toHaveBeenCalled();
+ },
+ );
- const markdown = PyodideBridge.INSTANCE.exportAsMarkdown({
- download: false,
- });
- const script = PyodideBridge.INSTANCE.exportAsScript({
- download: false,
- });
+ it("flushes edits before asking the host to save without an editor snapshot", async () => {
+ const flushed = new Deferred<void>();
+ mockFlush.mockReturnValueOnce(flushed.promise);
+ const saving = PyodideBridge.INSTANCE.sendSave(request);
await Promise.resolve();
- expect(mockBridge).not.toHaveBeenCalled();
+ expect(mockNotebookCall).not.toHaveBeenCalled();
+ flushed.resolve();
+ await saving;
+ expect(mockSetNotebookLayout).toHaveBeenCalledWith(null);
+ expect(mockNotebookCall).toHaveBeenCalledWith(
+ expect.objectContaining({ operation: "notebook.save", body: {} }),
+ );
+ expect(mockWriteNotebook).not.toHaveBeenCalled();
+ });
- mainSave.resolve();
- await Promise.all([markdown, script]);
- expect(mockBridge).toHaveBeenCalledWith({
- functionName: "export_markdown",
- payload: { download: false },
- });
- expect(mockBridge).toHaveBeenCalledWith({
- functionName: "export_script",
- payload: { download: false },
+ it("does not save when flushing fails", async () => {
+ mockFlush.mockRejectedValueOnce(new Error("unsynchronized edit"));
+ await expect(PyodideBridge.INSTANCE.sendSave(request)).rejects.toThrow(
+ "unsynchronized edit",
+ );
+ expect(mockNotebookCall).not.toHaveBeenCalled();
+ });
+
+ it("reports host persistence failures", async () => {
+ mockNotebookCall.mockResolvedValueOnce({
+ status: 409,
+ body: {
+ type: "tag:marimo.io,2026:host/conflict",
+ title: "Conflict",
+ status: 409,
+ detail: "storage full",
+ },
});
+ await expect(PyodideBridge.INSTANCE.sendSave(request)).rejects.toThrow(
+ "storage full",
+ );
+ });
+
+ it("persists exactly the host's content before acknowledging storage", async () => {
+ const durable = new Deferred<void>();
+ const snapshot = { filename: "notebook.py", contents: "# host revision" };
+ mockWriteNotebook.mockReturnValueOnce(durable.promise);
+ const writing = parentRequests.persistNotebook!(snapshot);
+ await Promise.resolve();
+ expect(mockWriteNotebook).toHaveBeenCalledWith(snapshot);
+ expect(notebookFileStore.saveFile).not.toHaveBeenCalled();
+ durable.resolve();
+ await writing;
+ expect(notebookFileStore.saveFile).toHaveBeenCalledWith(snapshot.contents);
+ expect(fallbackFileStore.saveFile).toHaveBeenCalledWith(snapshot.contents);
+ });
+
+ it("propagates storage failure without updating the URL", async () => {
+ mockWriteNotebook.mockRejectedValueOnce(new Error("IndexedDB failed"));
+ await expect(
+ parentRequests.persistNotebook!({
+ filename: "notebook.py",
+ contents: "# host",
+ }),
+ ).rejects.toThrow("IndexedDB failed");
+ expect(notebookFileStore.saveFile).not.toHaveBeenCalled();
});
});
@@ -231,7 +354,6 @@ it("cancels a pending notebook subscription before its RPC response", async () =
store.set(initialModeAtom, "read");
rpcListeners.initialized();
const pending = new Deferred<void>();
- mockNotebookInfo.mockResolvedValue({ id: "n1" });
mockNotebookSubscribe.mockReturnValue(pending.promise);
mockNotebookUnsubscribe.mockResolvedValue(undefined);
const controller = new AbortController();
diff --git a/frontend/src/core/wasm/__tests__/worker.test.ts b/frontend/src/core/wasm/__tests__/worker.test.ts
index 9126eac64c..a70e7ef165 100644
--- a/frontend/src/core/wasm/__tests__/worker.test.ts
+++ b/frontend/src/core/wasm/__tests__/worker.test.ts
@@ -77,6 +77,7 @@ async function startWorker(subscribing = Promise.resolve()) {
},
),
unsubscribe: (id: string) => subscribers.delete(id),
+ set_persistence: vi.fn(),
destroy: vi.fn(),
};
const bridge = { notebook, destroy: vi.fn() };
@@ -120,10 +121,13 @@ async function startWorker(subscribing = Promise.resolve()) {
}
it("delivers startup notifications after a delayed first subscription, without rerunning on resubscribe", async () => {
- const { controller, init, event, pyodide } = await startWorker();
+ const { controller, init, notebook, event, pyodide } = await startWorker();
try {
await new Promise((resolve) => setTimeout(resolve, 0));
expect(rpc.send.initialized).toHaveBeenCalledOnce();
+ expect(notebook.set_persistence).toHaveBeenCalledExactlyOnceWith(
+ expect.any(Function),
+ );
expect(pyodide.loadPackagesFromImports).toHaveResolved();
expect(init).not.toHaveBeenCalled();
@@ -137,6 +141,7 @@ it("delivers startup notifications after a delayed first subscription, without r
await handlers.requests.notebookSubscribe({ id: "second", cursor: null });
await new Promise((resolve) => setTimeout(resolve, 0));
expect(init).toHaveBeenCalledOnce();
+ expect(notebook.set_persistence).toHaveBeenCalledOnce();
} finally {
await controller.stopSession();
}
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index c6fa196237..c7d8339393 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -1,6 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
/* oxlint-disable typescript/no-explicit-any */
+import { createRPCRequestHandler } from "rpc-anywhere";
import { toast } from "@/components/ui/use-toast";
import { userConfigAtom } from "@/core/config/config";
import { serializeBlob } from "@/utils/blob";
@@ -12,6 +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 { createWasmNotebookBackend } from "../host";
import type { ClientCommand } from "../kernel/messages";
import { getInitialAppMode } from "../mode";
@@ -40,8 +42,9 @@ import type {
} from "../network/types";
import { filenameAtom } from "../saving/file-state";
import { store } from "../state/jotai";
+import { notebookReplicaAtom } from "../websocket/state";
import { PyodideRouter } from "./router";
-import { getWorkerRPC } from "./rpc";
+import { getWorkerRPC, type PersistNotebookRequest } from "./rpc";
import { getWasmRuntimeConfig } from "./runtime-config";
import { createShareableLink } from "./share";
import { wasmInitStateAtom } from "./state";
@@ -68,7 +71,6 @@ export class PyodideBridge implements RunRequests, EditRequests {
private rpc!: ReturnType<typeof getWorkerRPC<WorkerSchema>>;
private saveRpc: SaveWorker | undefined;
- private pendingSessionSave: Promise<unknown> = Promise.resolve();
private notebookConsumers = new Map<string, (event: unknown) => void>();
private interruptBuffer?: Uint8Array;
@@ -80,7 +82,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
return {
readFile: throwNotImplemented,
readNotebook: async () => (await notebookFileStore.readFile()) ?? "",
- saveNotebook: throwNotImplemented,
+ writeNotebook: throwNotImplemented,
};
}
@@ -95,7 +97,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
},
);
- const rpc = getWorkerRPC<SaveWorkerSchema>(saveWorker);
+ const rpc = getWorkerRPC<SaveWorkerSchema>(saveWorker, undefined, Infinity);
rpc.send.bootstrap(runtimeConfig);
return rpc.proxy.request;
}
@@ -114,7 +116,22 @@ export class PyodideBridge implements RunRequests, EditRequests {
});
// Create the RPC
- this.rpc = getWorkerRPC<WorkerSchema>(worker);
+ this.rpc = getWorkerRPC<WorkerSchema>(
+ worker,
+ createRPCRequestHandler({
+ persistNotebook: async (snapshot: PersistNotebookRequest) => {
+ if (!this.saveRpc) {
+ throw new Error("Notebook storage is not initialized");
+ }
+ await this.saveRpc.writeNotebook(snapshot);
+ notebookFileStore.saveFile(snapshot.contents);
+ fallbackFileStore.saveFile(snapshot.contents);
+ return null;
+ },
+ }),
+ // Synchronous Python execution can block worker requests indefinitely.
+ Infinity,
+ );
this.rpc.send.bootstrap(runtimeConfig);
this.rpc.addMessageListener("notebookEvent", ({ id, event }) => {
@@ -209,11 +226,8 @@ export class PyodideBridge implements RunRequests, EditRequests {
public async createNotebookBackend() {
await this.initialized.promise;
- const { id } = await this.rpc.proxy.request.notebookInfo();
return createWasmNotebookBackend({
- notebookId: id,
subscribe: async (cursor, emit, signal) => {
- await this.initialized.promise;
signal.throwIfAborted();
const id = generateUUID();
this.notebookConsumers.set(id, emit);
@@ -233,10 +247,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
throw error;
}
},
- call: async (call) => {
- await this.initialized.promise;
- return this.rpc.proxy.request.notebookCall(call);
- },
+ call: (call) => this.rpc.proxy.request.notebookCall(call),
});
}
@@ -255,30 +266,23 @@ export class PyodideBridge implements RunRequests, EditRequests {
return null;
};
- public sendSave: EditRequests["sendSave"] = async (request) => {
- if (!this.saveRpc) {
- Logger.warn("Save RPC not initialized");
- return null;
+ private async saveHostNotebook() {
+ const replica = store.get(notebookReplicaAtom);
+ const notebook = replica && store.get(replica.notebookAtom);
+ const backend = replica && store.get(replica.backendAtom);
+ if (!notebook || !backend) {
+ throw new Error("The notebook is not connected");
}
-
- const durableSave = this.saveRpc.saveNotebook(request);
- // Generated exports read the session-owned app in the main worker.
- this.pendingSessionSave = this.pendingSessionSave
- .catch(() => undefined)
- .then(async () => {
- await durableSave;
- await this.rpc.proxy.request.saveNotebook(request);
- });
- void this.pendingSessionSave.catch((error) => {
- Logger.error(error);
- });
-
- await durableSave;
- const code = await this.readCode();
- if (code.contents) {
- notebookFileStore.saveFile(code.contents);
- fallbackFileStore.saveFile(code.contents);
+ const result = await backend.notebook(notebook.id).save();
+ if (!result.ok) {
+ throw new Error(result.problem.detail ?? result.problem.title);
}
+ }
+
+ public sendSave: EditRequests["sendSave"] = async ({ layout }) => {
+ await flushDocumentChanges();
+ await this.rpc.proxy.request.setNotebookLayout(layout ?? null);
+ await this.saveHostNotebook();
return null;
};
@@ -395,6 +399,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
functionName: "save_app_config",
payload: request,
});
+ await this.saveHostNotebook();
return null;
};
@@ -560,7 +565,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
public exportAsHTML: EditRequests["exportAsHTML"] = async (
request: ExportAsHTMLRequest,
) => {
- await this.pendingSessionSave;
+ await flushDocumentChanges();
const response = await this.rpc.proxy.request.bridge({
functionName: "export_html",
payload: withDevAssetUrl(request),
@@ -571,7 +576,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
public exportAsMarkdown: EditRequests["exportAsMarkdown"] = async (
request: ExportAsMarkdownRequest,
) => {
- await this.pendingSessionSave;
+ await flushDocumentChanges();
const response = await this.rpc.proxy.request.bridge({
functionName: "export_markdown",
payload: request,
@@ -582,7 +587,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
public exportAsScript: EditRequests["exportAsScript"] = async (
request: ExportAsScriptRequest,
) => {
- await this.pendingSessionSave;
+ await flushDocumentChanges();
const response = await this.rpc.proxy.request.bridge({
functionName: "export_script",
payload: request,
@@ -653,7 +658,12 @@ export class PyodideBridge implements RunRequests, EditRequests {
return null;
};
- public sendDocumentTransaction = () => Promise.resolve(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/rpc.ts b/frontend/src/core/wasm/rpc.ts
index a4794e9bb9..751d8ab62c 100644
--- a/frontend/src/core/wasm/rpc.ts
+++ b/frontend/src/core/wasm/rpc.ts
@@ -9,18 +9,31 @@ import { Logger } from "@/utils/Logger";
import type { WasmRuntimeConfig } from "./runtime-config";
import { TRANSPORT_ID } from "./worker/constants";
+export interface PersistNotebookRequest {
+ filename: string;
+ contents: string;
+}
+
export type ParentSchema = RPCSchema<{
+ requests: {
+ persistNotebook: { params: PersistNotebookRequest; response: null };
+ };
messages: {
bootstrap: WasmRuntimeConfig;
};
}>;
-export function getWorkerRPC<WorkerSchema extends RPCSchema>(worker: Worker) {
+export function getWorkerRPC<WorkerSchema extends RPCSchema>(
+ worker: Worker,
+ requestHandler?: RPCOptions<ParentSchema, WorkerSchema>["requestHandler"],
+ maxRequestTime = 20_000,
+) {
return createRPC<ParentSchema, WorkerSchema>({
transport: createWorkerTransport(worker, {
transportId: TRANSPORT_ID,
}),
- maxRequestTime: 20_000, // 20 seconds
+ requestHandler,
+ maxRequestTime,
_debugHooks: {
onSend: (message) => {
Logger.debug("[rpc] Parent -> Worker", message);
diff --git a/frontend/src/core/wasm/worker/save-worker.ts b/frontend/src/core/wasm/worker/save-worker.ts
index 83defaf286..7cfa8ebe2e 100644
--- a/frontend/src/core/wasm/worker/save-worker.ts
+++ b/frontend/src/core/wasm/worker/save-worker.ts
@@ -7,12 +7,11 @@ import {
createWorkerParentTransport,
type RPCSchema,
} from "rpc-anywhere";
-import type { SaveNotebookRequest } from "@/core/network/types";
import { decodeUtf8 } from "@/utils/strings";
import { Deferred } from "../../../utils/Deferred";
import { prettyError } from "../../../utils/errors";
import { Logger } from "../../../utils/Logger";
-import type { ParentSchema } from "../rpc";
+import type { ParentSchema, PersistNotebookRequest } from "../rpc";
import type { WasmRuntimeConfig } from "../runtime-config";
import { TRANSPORT_ID } from "./constants";
import { WasmFileSystem } from "./fs";
@@ -70,14 +69,14 @@ const requestHandler = createRPCRequestHandler({
await pyodideReadyPromise; // Make sure loading is done
return WasmFileSystem.readNotebook(self.pyodide);
},
- saveNotebook: async (opts: SaveNotebookRequest) => {
- await pyodideReadyPromise; // Make sure loading is done
- const saveFile = self.pyodide.runPython(`
- from marimo._pyodide.bootstrap import save_file
-
- save_file
- `);
- await saveFile(JSON.stringify(opts), WasmFileSystem.NOTEBOOK_FILENAME);
+ writeNotebook: async ({ filename, contents }: PersistNotebookRequest) => {
+ await pyodideReadyPromise;
+ const directory = filename.substring(0, filename.lastIndexOf("/"));
+ if (directory) {
+ self.pyodide.FS.mkdirTree(directory);
+ }
+ self.pyodide.FS.writeFile(filename, contents);
+ self.pyodide.FS.writeFile(WasmFileSystem.NOTEBOOK_FILENAME, contents);
await WasmFileSystem.persistFilesToRemote(self.pyodide);
},
});
diff --git a/frontend/src/core/wasm/worker/types.ts b/frontend/src/core/wasm/worker/types.ts
index 14e1895042..6c6caa7815 100644
--- a/frontend/src/core/wasm/worker/types.ts
+++ b/frontend/src/core/wasm/worker/types.ts
@@ -30,7 +30,6 @@ import type {
FormatCellsRequest,
FormatResponse,
SaveAppConfigurationRequest,
- SaveNotebookRequest,
SaveUserConfigurationRequest,
Snippets,
} from "../../network/types";
@@ -79,7 +78,6 @@ export interface RawBridge {
read_snippets(): Promise<Snippets>;
get_environment_info(): Promise<EnvironmentInfo>;
format(request: FormatCellsRequest): Promise<FormatResponse>;
- save(request: SaveNotebookRequest): Promise<string>;
copy(request: CopyNotebookRequest): Promise<string>;
save_app_config(request: SaveAppConfigurationRequest): Promise<string>;
save_user_config(request: SaveUserConfigurationRequest): Promise<null>;
@@ -112,13 +110,12 @@ export type BridgePayload<T extends keyof RawBridge> = T extends keyof RawBridge
: undefined;
export type SerializedBridge = {
- [P in Exclude<keyof RawBridge, "save">]: RawBridge[P] extends (
+ [P in keyof RawBridge]: RawBridge[P] extends (
payload: string,
) => Promise<unknown>
? (payload: string) => Promise<string>
: RawBridge[P];
} & {
- save(payload: string): Promise<void>;
notebook: {
readonly id: string;
subscribe(
@@ -128,6 +125,11 @@ export type SerializedBridge = {
): Promise<void>;
unsubscribe(id: string): void;
call(call: string): Promise<string>;
+ transaction(request: string): Promise<void>;
+ set_layout(layout: string): Promise<void>;
+ set_persistence(
+ persist: (contents: string, filename: string) => Promise<void>,
+ ): void;
destroy(): void;
};
};
diff --git a/frontend/src/core/wasm/worker/worker.ts b/frontend/src/core/wasm/worker/worker.ts
index a99b4f365a..9d4fe791fc 100644
--- a/frontend/src/core/wasm/worker/worker.ts
+++ b/frontend/src/core/wasm/worker/worker.ts
@@ -12,6 +12,7 @@ import type { UserConfig } from "@/core/config/config-schema";
import type {
ListPackagesResponse,
PackageOperationResponse,
+ NotebookDocumentTransactionRequest,
SaveNotebookRequest,
} from "@/core/network/types";
import { decodeUtf8 } from "@/utils/strings";
@@ -83,14 +84,6 @@ async function getNotebook() {
}
const requestHandler = createRPCRequestHandler({
- notebookInfo: async () => {
- const notebook = await getNotebook();
- try {
- return { id: notebook.id };
- } finally {
- notebook.destroy();
- }
- },
notebookSubscribe: (request: { id: string; cursor: string | null }) => {
let canceled = false;
const subscribing = (async () => {
@@ -172,6 +165,17 @@ const requestHandler = createRPCRequestHandler({
queryParameters: opts.queryParameters,
userConfig: opts.userConfig,
});
+ const notebook = session.bridge.notebook;
+ try {
+ notebook.set_persistence(async (contents, filename) => {
+ // Keep file operations in the execution worker from syncing stale source.
+ self.pyodide.FS.writeFile(filename, contents);
+ self.pyodide.FS.writeFile(WasmFileSystem.NOTEBOOK_FILENAME, contents);
+ await rpc.proxy.request.persistNotebook({ filename, contents });
+ });
+ } finally {
+ notebook.destroy();
+ }
sessionReady.resolve(session);
rpc.send.initializingMessage({
message: "Initializing notebook...",
@@ -298,13 +302,21 @@ const requestHandler = createRPCRequestHandler({
};
},
- /**
- * Save the notebook
- */
- saveNotebook: async (opts: SaveNotebookRequest) => {
- await pyodideReadyPromise; // Make sure loading is done
- const { bridge } = await sessionReady.promise;
- await bridge.save(JSON.stringify(opts));
+ 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 {
+ await notebook.set_layout(JSON.stringify(layout));
+ } finally {
+ notebook.destroy();
+ }
},
/**
@@ -403,6 +415,8 @@ const rpc = createRPC<WorkerSchema, ParentSchema>({
transportId: TRANSPORT_ID,
}),
requestHandler,
+ // Persistence can include bootstrapping the storage worker.
+ maxRequestTime: Infinity,
});
rpc.addMessageListener("bootstrap", (config) => runtimeConfig.resolve(config));
@@ -410,8 +424,6 @@ rpc.addMessageListener("bootstrap", (config) => runtimeConfig.resolve(config));
rpc.send("ready", {});
const namesThatRequireSync = new Set<keyof RawBridge>([
- "save",
- "save_app_config",
"rename_file",
"create_file_or_directory",
"delete_file_or_directory",
diff --git a/frontend/src/core/websocket/__tests__/backend.test.ts b/frontend/src/core/websocket/__tests__/backend.test.ts
index 3add70bbd1..71990a884e 100644
--- a/frontend/src/core/websocket/__tests__/backend.test.ts
+++ b/frontend/src/core/websocket/__tests__/backend.test.ts
@@ -5,7 +5,11 @@ import { createStore } from "jotai/vanilla";
import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
import { ConnectionState } from "../../host/connection";
-import { type FakeEdit, fakeBackend } from "../../host/__tests__/fixtures";
+import {
+ type FakeEdit,
+ type FakeSave,
+ fakeBackend,
+} from "../../host/__tests__/fixtures";
import { createNotebookReplica } from "../../host/replica";
import { createEditorBackend } from "../backend";
@@ -119,11 +123,12 @@ describe("createEditorBackend", () => {
expect(fetch).not.toHaveBeenCalled();
});
- it("edits the WASM notebook through the worker once its stream starts", async () => {
+ it("routes WASM commands through the worker once its stream starts", async () => {
wasm.enabled = true;
const edit = vi.fn<FakeEdit>();
+ const save = vi.fn<FakeSave>();
const transport = vi.fn(async () => undefined);
- wasm.create.mockResolvedValue(fakeBackend({ transport, edit }));
+ wasm.create.mockResolvedValue(fakeBackend({ transport, edit, save }));
const backend = createEditorBackend(options);
expect(wasm.create).not.toHaveBeenCalled();
expect(() => backend.notebook("n1")).toThrow("has not started");
@@ -136,6 +141,8 @@ describe("createEditorBackend", () => {
expect(transport).toHaveBeenCalledWith(attempt, handlers);
await backend.notebook("n1").edit([], { idempotencyKey: "edit-1" });
expect(edit).toHaveBeenCalledWith("n1", [], { idempotencyKey: "edit-1" });
+ await backend.notebook("n2").save({ idempotencyKey: "save-1" });
+ expect(save).toHaveBeenCalledWith("n2", { idempotencyKey: "save-1" });
});
it("stops following WASM when the worker does not start", async () => {
diff --git a/frontend/src/core/websocket/backend.ts b/frontend/src/core/websocket/backend.ts
index 226631c31e..c0f0e01abd 100644
--- a/frontend/src/core/websocket/backend.ts
+++ b/frontend/src/core/websocket/backend.ts
@@ -92,17 +92,16 @@ function wasm(): NotebookBackend {
/** Commands for a notebook the editor cannot change through its backend. */
function uneditable(): ReturnType<NotebookBackend["notebook"]> {
- return {
- edit: async () => ({
- ok: false,
+ const unsupported: NotebookClient["save"] = async () => ({
+ ok: false,
+ status: 501,
+ problem: {
+ type: "tag:marimo.io,2026:host/unsupported-operation",
+ title: "Document mutations are unavailable on this connection",
status: 501,
- problem: {
- type: "tag:marimo.io,2026:host/unsupported-operation",
- title: "Document editing is unavailable on this connection",
- status: 501,
- },
- }),
- };
+ },
+ });
+ return { edit: () => unsupported(), save: unsupported };
}
/** Choose the backend for the editor's notebook. */
diff --git a/marimo/_pyodide/bootstrap.py b/marimo/_pyodide/bootstrap.py
index 0a65e44f96..3bb3ab881e 100644
--- a/marimo/_pyodide/bootstrap.py
+++ b/marimo/_pyodide/bootstrap.py
@@ -2,7 +2,6 @@
# ruff: noqa: E402
from __future__ import annotations
-import json
from typing import TYPE_CHECKING
from marimo._runtime._wasm import ensure_wasm_runtime_bootstrapped
@@ -19,10 +18,8 @@ from marimo._runtime.commands import (
)
from marimo._runtime.patches import extract_docstring_from_header
from marimo._server.app_defaults import AppDefaults
-from marimo._server.models.models import SaveNotebookRequest
from marimo._session.model import SessionMode
from marimo._session.notebook import AppFileManager
-from marimo._utils.parse_dataclass import parse_raw
if TYPE_CHECKING:
from marimo._config.config import MarimoConfig
@@ -121,21 +118,3 @@ def create_session(
bridge = PyodideBridge(session)
return session, bridge
-
-
-def save_file(
- request: str,
- filename: str,
-) -> None:
- """
- Save the app to the given filename.
-
- Args:
- request: serialized/stringified SaveNotebookRequest
- filename: the filename of the app
-
- This function is called by the WebAssembly frontend.
- """
- parsed = parse_raw(json.loads(request), SaveNotebookRequest)
- app_file_manager = AppFileManager(filename=filename)
- app_file_manager.save(parsed)
diff --git a/marimo/_pyodide/notebook.py b/marimo/_pyodide/notebook.py
index 893518339b..7cfd84da46 100644
--- a/marimo/_pyodide/notebook.py
+++ b/marimo/_pyodide/notebook.py
@@ -3,6 +3,7 @@
from __future__ import annotations
+import asyncio
from pathlib import Path
from typing import TYPE_CHECKING
@@ -11,11 +12,14 @@ 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.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,
)
@@ -24,12 +28,19 @@ from marimo._messaging.serde import (
serialize_kernel_message,
)
from marimo._pyodide.kernel_ready import kernel_ready
+from marimo._runtime.layout.layout import (
+ LayoutConfig,
+ layout_config_to_data_uri,
+)
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
if TYPE_CHECKING:
- from collections.abc import Callable, Mapping, Sequence
+ from collections.abc import Awaitable, Callable, Mapping, Sequence
+ from typing import Any
from marimo._core.stream import Sink
from marimo._messaging.notification import NotificationMessage
@@ -71,7 +82,9 @@ class PyodideNotebook:
self._session = session
self._subscriptions: dict[str, Callable[[], None]] = {}
self._closed = False
- self.host = Host(operations=("notebook.edit",))
+ self._save_lock = asyncio.Lock()
+ self._persist: Callable[[str, str], Awaitable[None]] | None = None
+ self.host = Host(operations=("notebook.edit", "notebook.save"))
project_id = mint(protocol.ProjectId, "p")
self.id = mint(protocol.NotebookId, "n")
self.host.update_project(
@@ -92,7 +105,7 @@ class PyodideNotebook:
name=Path(filename).name if filename else "Untitled",
path=None,
updated_at=None,
- operations=("notebook.edit",)
+ operations=("notebook.edit", "notebook.save")
if session.mode is SessionMode.EDIT
else (),
),
@@ -113,8 +126,8 @@ class PyodideNotebook:
saved_etag=document.etag,
)
- def refresh(self, *, saved: bool = False) -> None:
- """Observe writes through the existing session while it still owns saves."""
+ def refresh(self) -> None:
+ """Observe changes from session operations not yet exposed by the host."""
if self._closed:
return
notebook = self.host.peek_notebook(self.id)
@@ -122,7 +135,7 @@ class PyodideNotebook:
cells, config = documents.from_file_manager(
self._session.app_manager
)
- notebook.replace(cells, config, saved=saved)
+ notebook.replace(cells, config)
async def subscribe(
self,
@@ -203,11 +216,15 @@ class PyodideNotebook:
notebook = await self.host.notebook(notebook_id)
self.refresh()
result = notebook.edit(changes, request_id=request_id)
+ self._apply_to_session(notebook, notify=True)
+ return result
+
+ def _apply_to_session(self, notebook: Notebook, *, notify: bool) -> None:
transaction, update = documents.apply_to_document(
self._session.app_manager.app.cell_manager.document,
notebook.document,
)
- if transaction is not None:
+ if transaction is not None and notify:
self._session._on_message(
serialize_kernel_message(
NotebookDocumentTransactionNotification(
@@ -218,7 +235,50 @@ class PyodideNotebook:
# Before instantiation the kernel receives the latest app cells.
if update is not None and self._session.instantiated:
self._session.put_control_request(update)
- return result
+
+ 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)
+ notebook.replace(
+ list(notebook.document),
+ self._session.app_manager.app.config.asdict_difference(),
+ )
+
+ async def set_layout(self, raw: str) -> None:
+ layout = msgspec.json.decode(raw, type=LayoutConfig | None)
+ # Inline layouts survive URL/local-storage reloads along with the source.
+ await self.update_config(
+ {
+ "layout_file": layout_config_to_data_uri(layout)
+ if layout
+ else None,
+ }
+ )
+
+ def set_persistence(
+ self, persist: Callable[[str, str], Awaitable[None]]
+ ) -> None:
+ self._persist = persist
async def save(
self,
@@ -228,7 +288,33 @@ class PyodideNotebook:
decisions: Mapping[str, str],
request_id: str,
) -> protocol.EditResponse:
- raise NotImplementedError("Worker saves are not exposed yet")
+ notebook = await self.host.notebook(notebook_id)
+ async with self._save_lock:
+ if decisions:
+ raise Invalid("Worker saves do not require decisions")
+ if self._persist is None:
+ raise Conflict("Notebook persistence is unavailable")
+ if if_match is not None:
+ notebook.require_revision(if_match)
+ revision = notebook.document
+ manager = self._session.app_manager
+ path = Path(manager.filename or "notebook.py")
+ ir = cells_to_ir(
+ (documents.to_notebook_cell(cell) for cell in revision),
+ revision.app_config,
+ header=manager.app._app._header,
+ )
+ try:
+ contents = NotebookWriter().write_ir(
+ path, notebook=ir, persist=False
+ )
+ await self._persist(contents, str(path))
+ except Exception as e:
+ raise Conflict(f"The notebook cannot be saved: {e}") from e
+ document = notebook.mark_saved(
+ revision.etag, request_id=request_id
+ )
+ return protocol.EditResponse(document=document, cells={})
def close(self) -> None:
self._closed = True
diff --git a/marimo/_pyodide/pyodide_session.py b/marimo/_pyodide/pyodide_session.py
index 60ef1d608c..2bd1d9c847 100644
--- a/marimo/_pyodide/pyodide_session.py
+++ b/marimo/_pyodide/pyodide_session.py
@@ -22,6 +22,15 @@ from marimo._export.requests import (
)
from marimo._export.serialization import serialize_notebook_snapshot
from marimo._messaging.msgspec_encoder import encode_json_str
+from marimo._messaging.notebook import Transaction
+from marimo._messaging.notebook.reconcile import reconcile_transaction
+from marimo._messaging.notification import (
+ NotebookDocumentTransactionNotification,
+)
+from marimo._messaging.serde import (
+ deserialize_kernel_message,
+ deserialize_kernel_notification_name,
+)
from marimo._messaging.types import KernelStreams
from marimo._pyodide.restartable_task import RestartableTask
from marimo._pyodide.streams import (
@@ -73,7 +82,6 @@ from marimo._server.models.models import (
FormatResponse,
ReadCodeResponse,
SaveAppConfigurationRequest,
- SaveNotebookRequest,
SaveUserConfigurationRequest,
)
from marimo._session.model import SessionMode
@@ -252,6 +260,28 @@ class PyodideBridge:
self.session = session
self.file_system = OSFileSystem()
self._notebook: PyodideNotebook | None = None
+ self.session.consumers.append(self._on_message)
+
+ def _on_message(self, message: KernelMessage) -> None:
+ if (
+ deserialize_kernel_notification_name(message)
+ != "notebook-document-transaction"
+ ):
+ return
+ notification = deserialize_kernel_message(message)
+ assert isinstance(
+ notification, NotebookDocumentTransactionNotification
+ )
+ transaction = notification.transaction
+ if transaction.source == "host":
+ return
+ # Kernel/code-mode edits already reached the frontend; retain them for
+ # subsequent host saves without sending them back to the kernel.
+ document = self.session.app_manager.app.cell_manager.document
+ changes = reconcile_transaction(transaction.changes, document)
+ document.apply(Transaction(changes=changes, source=transaction.source))
+ if self._notebook is not None:
+ self._notebook.refresh()
@property
def notebook(self) -> PyodideNotebook:
@@ -262,6 +292,8 @@ class PyodideBridge:
return self._notebook
def close(self) -> None:
+ if self._on_message in self.session.consumers:
+ self.session.consumers.remove(self._on_message)
if self._notebook is not None:
self._notebook.close()
@@ -297,17 +329,9 @@ class PyodideBridge:
response = FormatResponse(codes=await formatter.format(parsed.codes))
return self._dump(response)
- def save(self, request: str) -> None:
- parsed = self._parse(request, SaveNotebookRequest)
- self.session.app_manager.save(parsed)
- if self._notebook is not None:
- self._notebook.refresh(saved=True)
-
- def save_app_config(self, request: str) -> None:
+ async def save_app_config(self, request: str) -> None:
parsed = self._parse(request, SaveAppConfigurationRequest)
- self.session.app_manager.save_app_config(parsed.config)
- if self._notebook is not None:
- self._notebook.refresh(saved=True)
+ await self.notebook.update_config(parsed.config)
def save_user_config(self, request: str) -> None:
parsed = self._parse(request, SaveUserConfigurationRequest)
diff --git a/tests/_pyodide/test_bootstrap.py b/tests/_pyodide/test_bootstrap.py
index 16de658f85..67eba139e4 100644
--- a/tests/_pyodide/test_bootstrap.py
+++ b/tests/_pyodide/test_bootstrap.py
@@ -6,12 +6,9 @@ from typing import TYPE_CHECKING, Any
import pytest
from marimo._config.config import DEFAULT_CONFIG
-from marimo._messaging.msgspec_encoder import encode_json_str
-from marimo._pyodide.bootstrap import create_session, save_file
+from marimo._pyodide.bootstrap import create_session
from marimo._pyodide.pyodide_session import PyodideSession
-from marimo._server.models.models import SaveNotebookRequest
from marimo._session.model import SessionMode
-from marimo._types.ids import CellId_t
if TYPE_CHECKING:
from pathlib import Path
@@ -136,27 +133,3 @@ async def test_instantiate(
assert len(captured_request.execution_requests) == 1
assert captured_request.execution_requests[0].code == '"Hello"'
assert captured_request.auto_run is True
-
-
-def test_save_file(
- mock_app_file: Path,
-) -> None:
- # Create a save request
- request = SaveNotebookRequest(
- codes=["print('hello')"],
- names=["cell-1"],
- configs=[{}],
- cell_ids=[CellId_t("cell-1")],
- layout=None,
- filename=str(mock_app_file),
- )
-
- # Save the file
- save_file(
- request=encode_json_str(request),
- filename=str(mock_app_file),
- )
-
- # Verify the file was saved correctly
- saved_content = mock_app_file.read_text()
- assert "print('hello')" in saved_content
diff --git a/tests/_pyodide/test_pyodide_acceptance.mjs b/tests/_pyodide/test_pyodide_acceptance.mjs
index 62f53448d7..3b20bc6739 100644
--- a/tests/_pyodide/test_pyodide_acceptance.mjs
+++ b/tests/_pyodide/test_pyodide_acceptance.mjs
@@ -251,7 +251,6 @@ expected_methods = [
"read_code",
"read_snippets",
"format",
- "save",
"save_app_config",
"save_user_config",
"rename_file",
@@ -329,6 +328,23 @@ json.dumps(result)
assert.deepEqual(JSON.parse(await notebook.call(call)), reply);
assert.equal(frames.length, count);
assert.equal(pyodide.runPython("list(session.app_manager.app.cell_manager.codes())[0]"), "x = 7");
+ notebook.set_persistence(async (contents, filename) => {
+ await Promise.resolve();
+ pyodide.FS.writeFile(filename, contents);
+ });
+ const save = JSON.stringify({
+ operation: "notebook.save",
+ params: { notebook_id: cell.notebook_id },
+ headers: { "idempotency-key": "wasm-acceptance-save" },
+ body: {},
+ });
+ const saved = JSON.parse(await notebook.call(save));
+ assert.equal(saved.status, 200);
+ assert.equal(saved.body.document.etag, saved.body.document.saved_etag);
+ assert.match(
+ pyodide.FS.readFile("/home/pyodide/test_notebook.py", { encoding: "utf8" }),
+ /x = 7/,
+ );
notebook.unsubscribe("acceptance");
} finally {
notebook.destroy();
diff --git a/tests/_pyodide/test_pyodide_notebook.py b/tests/_pyodide/test_pyodide_notebook.py
index 0feb3151f3..2393113e3f 100644
--- a/tests/_pyodide/test_pyodide_notebook.py
+++ b/tests/_pyodide/test_pyodide_notebook.py
@@ -1,8 +1,10 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import asyncio
import json
from typing import TYPE_CHECKING
+from unittest.mock import AsyncMock
import msgspec
import pytest
@@ -11,11 +13,14 @@ if TYPE_CHECKING:
from pathlib import Path
from marimo._ast.app_config import _AppConfig
+from marimo._ast.cell import CellConfig
from marimo._config.config import DEFAULT_CONFIG
from marimo._core.calls import EditCall, dispatch
+from marimo._messaging.notebook import CreateCell, Transaction
from marimo._messaging.notification import (
ModelLifecycleNotification,
ModelOpen,
+ NotebookDocumentTransactionNotification,
VariableDeclarationNotification,
VariablesNotification,
)
@@ -29,9 +34,10 @@ from marimo._runtime.commands import (
ModelCommand,
ModelUpdateMessage,
)
+from marimo._runtime.layout.layout import LayoutConfig
from marimo._session.model import SessionMode
from marimo._session.notebook import AppFileManager
-from marimo._types.ids import WidgetModelId
+from marimo._types.ids import CellId_t, WidgetModelId
@pytest.fixture
@@ -118,7 +124,10 @@ async def test_snapshot_edit_and_retry(bridge):
"document",
"ready",
]
- assert events[0]["data"]["notebook"]["operations"] == ["notebook.edit"]
+ assert events[0]["data"]["notebook"]["operations"] == [
+ "notebook.edit",
+ "notebook.save",
+ ]
request = edit(events)
response = await send(bridge, request)
assert response["status"] == 200
@@ -231,7 +240,7 @@ async def test_permissions_and_unsupported_operations(bridge):
request = edit(events)
assert (await send(bridge, request))["status"] == 403
save = {**request, "operation": "notebook.save", "body": {}}
- assert (await send(bridge, save))["status"] == 501
+ assert (await send(bridge, save))["status"] == 403
async def test_invalid_calls(bridge):
@@ -342,5 +351,202 @@ async def test_live_notifications_reach_each_subscription_until_it_closes(
assert ops(second)[-2:] == ["variables", "variables"]
bridge.notebook.unsubscribe("second")
assert bridge.session.consumers == [
- bridge.session.session_view.add_raw_notification
+ bridge.session.session_view.add_raw_notification,
+ bridge._on_message,
+ ]
+
+
+def save_call(bridge, key="save-1", if_match=None):
+ headers = {"idempotency-key": key}
+ if if_match is not None:
+ headers["if-match"] = if_match
+ return {
+ "operation": "notebook.save",
+ "params": {"notebook_id": bridge.notebook.id},
+ "headers": headers,
+ "body": {},
+ }
+
+
+async def test_save_keeps_newer_edits_and_kernel_updates(bridge):
+ events = await snapshot(bridge)
+ instantiate(bridge.session, auto_instantiate=False)
+ queue = bridge.session._queue_manager.control_queue
+ queue.get_nowait()
+ await send(bridge, edit(events))
+ queue.get_nowait()
+ notebook = await bridge.notebook.host.notebook(bridge.notebook.id)
+ saved_revision = notebook.document.etag
+ started, release = asyncio.Event(), asyncio.Event()
+ writes = []
+
+ async def persist(contents, _filename):
+ writes.append(contents)
+ started.set()
+ await release.wait()
+
+ bridge.notebook.set_persistence(persist)
+ request = save_call(bridge)
+ saving = asyncio.create_task(send(bridge, request))
+ await started.wait()
+ # A second subscriber observes the updated cell's current etag.
+ await send(
+ bridge, edit(await snapshot(bridge, "editor"), "x = 3", "edit-2")
+ )
+ update = queue.get_nowait()
+ assert isinstance(update, EditCellsCommand)
+ assert list(update.codes.values()) == ["x = 3"]
+ release.set()
+ reply = await saving
+ assert reply["status"] == 200
+ assert reply["body"]["document"]["saved_etag"] == saved_revision
+ assert notebook.document.etag != notebook.saved_etag
+ assert list(bridge.session.app_manager.app.cell_manager.codes()) == [
+ "x = 3"
+ ]
+ assert len(writes) == 1
+ assert "x = 2" in writes[0]
+ assert "x = 3" not in writes[0]
+ assert queue.empty()
+ # A lost reply retries the same save, rather than saving the newer document.
+ assert await send(bridge, request) == reply
+ assert len(writes) == 1
+
+
+async def test_failed_save_stays_dirty_and_can_retry(bridge):
+ events = await snapshot(bridge)
+ await send(bridge, edit(events))
+ notebook = await bridge.notebook.host.notebook(bridge.notebook.id)
+ saved = notebook.saved_etag
+ persist = AsyncMock(side_effect=OSError("storage full"))
+ bridge.notebook.set_persistence(persist)
+ request = save_call(bridge)
+ count = len(events)
+ failed = await send(bridge, request)
+ assert failed["status"] == 409
+ assert "storage full" in failed["body"]["detail"]
+ assert notebook.saved_etag == saved != notebook.document.etag
+ assert len(events) == count
+ persist.side_effect = None
+ assert (await send(bridge, request))["status"] == 200
+ assert notebook.saved_etag == notebook.document.etag
+ assert persist.await_count == 2
+
+
+async def test_save_serializes_writes_and_checks_revision_after_waiting(
+ bridge,
+):
+ events = await snapshot(bridge)
+ notebook = await bridge.notebook.host.notebook(bridge.notebook.id)
+ original = notebook.document.etag
+ started, release = asyncio.Event(), asyncio.Event()
+ writes = []
+
+ async def persist(contents, _filename):
+ writes.append(contents)
+ started.set()
+ await release.wait()
+
+ bridge.notebook.set_persistence(persist)
+ first = asyncio.create_task(send(bridge, save_call(bridge)))
+ await started.wait()
+ stale = asyncio.create_task(
+ send(bridge, save_call(bridge, "stale", original))
+ )
+ await send(bridge, edit(events))
+ second = asyncio.create_task(send(bridge, save_call(bridge, "save-2")))
+ await asyncio.sleep(0)
+ assert len(writes) == 1
+ release.set()
+ assert (await first)["status"] == 200
+ assert (await stale)["status"] == 409
+ assert (await second)["status"] == 200
+ assert len(writes) == 2
+ assert "x = 2" in writes[1]
+ assert notebook.saved_etag == notebook.document.etag
+
+
+async def test_editor_transactions_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(
+ {
+ "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": {},
+ },
+ {"type": "reorder-cells", "cellIds": ["new", cell_id]},
+ ]
+ }
+ )
+ )
+ assert not messages # Do not echo old typing into the editor.
+ await bridge.save_app_config(json.dumps({"config": {"width": "full"}}))
+ layout = {"type": "slides", "data": {"slides": [[cell_id]]}}
+ await bridge.notebook.set_layout(json.dumps(layout))
+ path = bridge.session.app_manager.filename
+
+ async def persist(contents, filename):
+ from pathlib import Path
+
+ await asyncio.to_thread(Path(filename).write_text, contents)
+
+ bridge.notebook.set_persistence(persist)
+ assert (await send(bridge, save_call(bridge)))["status"] == 200
+ restored = AppFileManager(path)
+ assert list(restored.app.cell_manager.codes()) == ["y = 2", "x = 9"]
+ 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(
+ {
+ "changes": [
+ {"type": "delete-cell", "cellId": "new"},
+ ]
+ }
+ )
+ )
+ assert list(bridge.session.app_manager.app.cell_manager.codes()) == [
+ "x = 9"
+ ]
+
+
+async def test_save_includes_kernel_document_edits(bridge):
+ await snapshot(bridge)
+ persist = AsyncMock()
+ bridge.notebook.set_persistence(persist)
+ bridge.session._on_message(
+ serialize_kernel_message(
+ NotebookDocumentTransactionNotification(
+ transaction=Transaction(
+ changes=(
+ CreateCell(
+ cell_id=CellId_t("kernel-cell"),
+ code="y = 8",
+ name="_",
+ config=CellConfig(),
+ ),
+ ),
+ source="kernel",
+ )
+ )
+ )
+ )
+ assert (await send(bridge, save_call(bridge)))["status"] == 200
+ contents, _filename = persist.call_args.args
+ assert "y = 8" in contents
+ assert list(bridge.session.app_manager.app.cell_manager.codes()) == [
+ "x = 1",
+ "y = 8",
]
+ assert bridge.session._queue_manager.control_queue.empty()
diff --git a/tests/_pyodide/test_pyodide_session.py b/tests/_pyodide/test_pyodide_session.py
index 260ccba2a7..471303b301 100644
--- a/tests/_pyodide/test_pyodide_session.py
+++ b/tests/_pyodide/test_pyodide_session.py
@@ -874,21 +874,24 @@ async def test_pyodide_bridge_format(pyodide_bridge: PyodideBridge) -> None:
assert "cell-1" in response["codes"]
-def test_pyodide_bridge_save(
+async def test_pyodide_bridge_document_export(
pyodide_bridge: PyodideBridge,
- pyodide_app_file: Path,
) -> None:
request_json = json.dumps(
{
- "cellIds": ["test"],
- "codes": ['message = "NEW"'],
- "names": ["_"],
- "configs": [{}],
- "filename": str(pyodide_app_file),
+ "changes": [
+ {
+ "type": "create-cell",
+ "cellId": "test",
+ "code": 'message = "NEW"',
+ "name": "_",
+ "config": {},
+ }
+ ],
}
)
- pyodide_bridge.save(request_json)
+ await pyodide_bridge.notebook.transaction(request_json)
request = json.dumps({"download": False})
script = json.loads(pyodide_bridge.export_script(request))
@@ -897,24 +900,6 @@ def test_pyodide_bridge_save(
assert 'message = "NEW"' in markdown["contents"]
-def test_pyodide_bridge_save_app_config(
- pyodide_bridge: PyodideBridge,
- pyodide_app_file: Path,
-) -> None:
- del pyodide_app_file
- """Test saving app config through the bridge."""
- request_json = json.dumps(
- {
- "config": {
- "width": "full",
- }
- }
- )
-
- # Should not raise
- pyodide_bridge.save_app_config(request_json)
-
-
def test_pyodide_bridge_save_user_config(
pyodide_bridge: PyodideBridge,
) -> None: