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.

Introduce a notebook backend with a static implementation (#11473)

Trevor Manz20157db4a61c
diff --git a/frontend/src/core/host/__tests__/static.test.ts b/frontend/src/core/host/__tests__/static.test.ts
new file mode 100644
index 0000000000..505869fdc1
--- /dev/null
+++ b/frontend/src/core/host/__tests__/static.test.ts
@@ -0,0 +1,167 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createNotebookReducer, NotebookEvents } from "@marimo-team/client";
+import * as Protocol from "@marimo-team/client/protocol";
+import { afterEach, assert, describe, expect, it, vi } from "vitest";
+import { document as documentResource } from "../resources/document";
+import {
+ createStaticNotebookBackend,
+ type StaticNotebookSnapshot,
+} from "../static";
+import { fixtureEvents } from "./fixtures";
+
+function snapshot(): StaticNotebookSnapshot {
+ const events = fixtureEvents("notebook-events.sse");
+ const notebook = events.find((event) => event.event === "notebook")?.data
+ .notebook;
+ const document = events.find((event) => event.event === "document")?.data
+ .document;
+ assert(notebook && document);
+ return {
+ notebook,
+ document,
+ cells: events.flatMap((event) =>
+ event.event === "cell" ? [event.data.cell] : [],
+ ),
+ };
+}
+
+const streams: NotebookEvents[] = [];
+afterEach(async () => {
+ const closed = streams.splice(0);
+ closed.forEach((stream) => stream.close());
+ await Promise.all(closed.map((stream) => stream.closed));
+ vi.useRealTimers();
+});
+
+async function read(
+ backend: ReturnType<typeof createStaticNotebookBackend>,
+ cursor?: string,
+) {
+ const stream = new NotebookEvents(backend.transport, { cursor });
+ streams.push(stream);
+ const events: Protocol.EventOutput[] = [];
+ await new Promise<void>((resolve, reject) => {
+ stream.subscribe((event) => {
+ events.push(Protocol.Event.parse(event));
+ if (event.event === "ready") {
+ resolve();
+ }
+ }, reject);
+ });
+ return { stream, events };
+}
+
+describe("static notebook backend", () => {
+ it("supplies a complete document through the normal event reader and reducer", async () => {
+ const source = snapshot();
+ const { stream, events } = await read(createStaticNotebookBackend(source));
+ const reducer = createNotebookReducer({ document: documentResource });
+ const state = events.reduce(reducer.reduce, reducer.initial);
+ expect(events.map((event) => event.event)).toEqual([
+ "notebook",
+ "cell",
+ "cell",
+ "cell",
+ "document",
+ "ready",
+ ]);
+ expect(state.notebook).toEqual({ ...source.notebook, operations: [] });
+ expect(state.resources.document.current).toEqual({
+ revision: source.document,
+ cells: new Map(source.cells.map((cell) => [cell.id, cell])),
+ });
+ expect(stream.status).toBe("connected");
+ });
+
+ it("preserves withheld source and its revision metadata", async () => {
+ const source = snapshot();
+ const cells = source.cells.map((cell) => ({ ...cell, code: null }));
+ const { events } = await read(
+ createStaticNotebookBackend({ ...source, cells }),
+ );
+ expect(
+ events
+ .filter((event) => event.event === "cell")
+ .map((event) => event.data.cell),
+ ).toEqual(cells);
+ expect(
+ events.find((event) => event.event === "document")?.data.document,
+ ).toEqual(source.document);
+ });
+
+ it("serves an empty document as available", async () => {
+ const source = snapshot();
+ const document = { ...source.document, order: [] };
+ const { events } = await read(
+ createStaticNotebookBackend({ ...source, document, cells: [] }),
+ );
+ const reducer = createNotebookReducer({ document: documentResource });
+ expect(
+ events.reduce(reducer.reduce, reducer.initial).resources.document.current,
+ ).toEqual({
+ revision: document,
+ cells: new Map(),
+ });
+ });
+
+ it("keeps independent readers open without polling or reconnecting", async () => {
+ vi.useFakeTimers();
+ const backend = createStaticNotebookBackend(snapshot());
+ const first = await read(backend);
+ const second = await read(backend);
+ first.stream.close();
+ await first.stream.closed;
+ await vi.advanceTimersByTimeAsync(60_000);
+ expect(second.events).toEqual(first.events);
+ expect(second.stream.status).toBe("connected");
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("resets a resume cursor before replaying its snapshot", async () => {
+ const { events } = await read(
+ createStaticNotebookBackend(snapshot()),
+ "previous-10",
+ );
+ expect(events[0]).toEqual({ event: "reset", data: {} });
+ 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.client.edit([])).toEqual({
+ ok: false,
+ status: 501,
+ problem: {
+ type: "tag:marimo.io,2026:host/unsupported-operation",
+ title: "Unsupported operation",
+ status: 501,
+ detail: "Static notebooks do not support editing",
+ },
+ });
+ });
+
+ it("respects cancellation before opening, during delivery, and for commands", async () => {
+ const backend = createStaticNotebookBackend(snapshot());
+ const before = new AbortController();
+ before.abort();
+ const open = vi.fn();
+ const message = vi.fn();
+ await backend.transport(
+ { cursor: null, signal: before.signal },
+ { open, message },
+ );
+ expect(open).not.toHaveBeenCalled();
+ expect(message).not.toHaveBeenCalled();
+ await expect(
+ backend.client.edit([], { signal: before.signal }),
+ ).rejects.toBe(before.signal.reason);
+ const during = new AbortController();
+ message.mockImplementation(() => during.abort());
+ await backend.transport(
+ { cursor: null, signal: during.signal },
+ { open, message },
+ );
+ expect(message).toHaveBeenCalledOnce();
+ });
+});
diff --git a/frontend/src/core/host/backend.ts b/frontend/src/core/host/backend.ts
new file mode 100644
index 0000000000..e019aac380
--- /dev/null
+++ b/frontend/src/core/host/backend.ts
@@ -0,0 +1,10 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { NotebookClient, NotebookTransport } from "@marimo-team/client";
+
+/** Events and commands for the same notebook, independent of React or a replica. */
+export interface NotebookBackend {
+ readonly transport: NotebookTransport;
+ /** Method presence is not permission; the notebook advertises its operations. */
+ readonly client: Pick<NotebookClient, "edit">;
+}
diff --git a/frontend/src/core/host/static.ts b/frontend/src/core/host/static.ts
new file mode 100644
index 0000000000..5b60921710
--- /dev/null
+++ b/frontend/src/core/host/static.ts
@@ -0,0 +1,70 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { NotebookBackend } from "./backend";
+
+/** A document snapshot with its own identity and revision metadata. */
+export interface StaticNotebookSnapshot {
+ readonly notebook: Omit<Protocol.Notebook, "operations">;
+ readonly document: Protocol.Document;
+ readonly cells: readonly Protocol.Cell[];
+}
+
+/**
+ * Serve a document without a server, runtime, or mutation operations.
+ * Callers and readers must treat the snapshot records as immutable.
+ */
+export function createStaticNotebookBackend(
+ snapshot: StaticNotebookSnapshot,
+): NotebookBackend {
+ const frames: Protocol.Event[] = [
+ {
+ event: "notebook",
+ data: { notebook: { ...snapshot.notebook, operations: [] } },
+ },
+ ...snapshot.cells.map((cell): Protocol.CellEvent => ({
+ event: "cell",
+ data: { cell },
+ })),
+ { event: "document", data: { document: snapshot.document } },
+ { event: "ready", id: "static", data: {} },
+ ];
+
+ return {
+ transport: ({ cursor, signal }, { open, message }) =>
+ new Promise((resolve) => {
+ if (signal.aborted) {
+ resolve();
+ return;
+ }
+ // Finishing would ask NotebookEvents to reconnect. A snapshot stays open
+ // until its reader closes, even though there are no more updates.
+ signal.addEventListener("abort", () => resolve(), { once: true });
+ open();
+ if (cursor !== null && !signal.aborted) {
+ message({ event: "reset", data: {} });
+ }
+ for (const frame of frames) {
+ if (signal.aborted) {
+ return;
+ }
+ message(frame);
+ }
+ }),
+ client: {
+ edit: async (_changes, options) => {
+ options?.signal?.throwIfAborted();
+ return {
+ ok: false,
+ status: 501,
+ problem: {
+ type: "tag:marimo.io,2026:host/unsupported-operation",
+ title: "Unsupported operation",
+ status: 501,
+ detail: "Static notebooks do not support editing",
+ },
+ };
+ },
+ },
+ };
+}