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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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.tsindex 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 upimport { 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.tsindex 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 rawait 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.tsindex 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.tsindex 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.tsindex 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 donereturn 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.pyindex 0a65e44f96..3bb3ab881e 100644--- a/marimo/_pyodide/bootstrap.py+++ b/marimo/_pyodide/bootstrap.py@@ -2,7 +2,6 @@# ruff: noqa: E402from __future__ import annotations-import jsonfrom typing import TYPE_CHECKINGfrom 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_headerfrom marimo._server.app_defaults import AppDefaults-from marimo._server.models.models import SaveNotebookRequestfrom marimo._session.model import SessionModefrom marimo._session.notebook import AppFileManager-from marimo._utils.parse_dataclass import parse_rawif 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.pyindex 893518339b..7cfd84da46 100644--- a/marimo/_pyodide/notebook.py+++ b/marimo/_pyodide/notebook.py@@ -3,6 +3,7 @@from __future__ import annotations+import asynciofrom pathlib import Pathfrom typing import TYPE_CHECKING@@ -11,11 +12,14 @@ import msgspecfrom marimo._core import protocolfrom marimo._core.calls import OperationCall, dispatchfrom marimo._core.document import Document+from marimo._core.errors import Conflict, Forbidden, Invalidfrom marimo._core.executions import Executionsfrom marimo._core.host import Hostfrom marimo._core.ids import mintfrom marimo._core.notebook import Notebookfrom marimo._core.operations import Mutations, problem+from marimo._messaging.notebook import NotebookDocument, Transaction+from marimo._messaging.notebook.reconcile import reconcile_transactionfrom 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 documentsfrom marimo._server.host.events import notification_event, serialize_event+from marimo._server.models.models import NotebookDocumentTransactionRequestfrom marimo._session.model import SessionMode+from marimo._session.notebook.writer import NotebookWriter, cells_to_irif TYPE_CHECKING:- from collections.abc import Callable, Mapping, Sequence+ from collections.abc import Awaitable, Callable, Mapping, Sequence+ from typing import Anyfrom marimo._core.stream import Sinkfrom marimo._messaging.notification import NotificationMessage@@ -71,7 +82,9 @@ class PyodideNotebook:self._session = sessionself._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.EDITelse (),),@@ -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:returnnotebook = 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 = persistasync 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 = Truediff --git a/marimo/_pyodide/pyodide_session.py b/marimo/_pyodide/pyodide_session.pyindex 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_snapshotfrom 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 KernelStreamsfrom marimo._pyodide.restartable_task import RestartableTaskfrom 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 = sessionself.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()@propertydef notebook(self) -> PyodideNotebook:@@ -262,6 +292,8 @@ class PyodideBridge:return self._notebookdef 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.pyindex 16de658f85..67eba139e4 100644--- a/tests/_pyodide/test_bootstrap.py+++ b/tests/_pyodide/test_bootstrap.py@@ -6,12 +6,9 @@ from typing import TYPE_CHECKING, Anyimport pytestfrom 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_sessionfrom marimo._pyodide.pyodide_session import PyodideSession-from marimo._server.models.models import SaveNotebookRequestfrom marimo._session.model import SessionMode-from marimo._types.ids import CellId_tif TYPE_CHECKING:from pathlib import Path@@ -136,27 +133,3 @@ async def test_instantiate(assert len(captured_request.execution_requests) == 1assert 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_contentdiff --git a/tests/_pyodide/test_pyodide_acceptance.mjs b/tests/_pyodide/test_pyodide_acceptance.mjsindex 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.pyindex 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 asyncioimport jsonfrom typing import TYPE_CHECKING+from unittest.mock import AsyncMockimport msgspecimport pytest@@ -11,11 +13,14 @@ if TYPE_CHECKING:from pathlib import Pathfrom marimo._ast.app_config import _AppConfig+from marimo._ast.cell import CellConfigfrom marimo._config.config import DEFAULT_CONFIGfrom marimo._core.calls import EditCall, dispatch+from marimo._messaging.notebook import CreateCell, Transactionfrom 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 LayoutConfigfrom marimo._session.model import SessionModefrom 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"] == 403save = {**request, "operation": "notebook.save", "body": {}}- assert (await send(bridge, save))["status"] == 501+ assert (await send(bridge, save))["status"] == 403async 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.pyindex 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: