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.

Expose a session-owned document model to React (#11471)

Trevor Manzd389f26dc4b9
diff --git a/frontend/src/core/document/__tests__/hooks.test.tsx b/frontend/src/core/document/__tests__/hooks.test.tsx
new file mode 100644
index 0000000000..d61ae784eb
--- /dev/null
+++ b/frontend/src/core/document/__tests__/hooks.test.tsx
@@ -0,0 +1,386 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, render, renderHook } from "@testing-library/react";
+import { atom, createStore, Provider } from "jotai";
+import type { PropsWithChildren } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
+import type { Document } from "../../host/resources/document";
+import {
+ createDocumentModel,
+ DocumentProvider,
+ useCellCode,
+ useCellConfig,
+ useCellName,
+ useCellOrder,
+ useDocumentEdit,
+ useDocumentSync,
+ type DocumentHost,
+} from "..";
+import { cell, CONFIG, document, withCells } from "./fixtures";
+
+type HostEdit = DocumentHost["edit"];
+const lifetimes: AbortController[] = [];
+
+afterEach(() => {
+ act(() => lifetimes.splice(0).forEach((controller) => controller.abort()));
+});
+
+function setup(
+ initial: Document | null = document(),
+ edit: HostEdit = () => new Promise(() => {}),
+) {
+ const store = createStore();
+ const source = atom(initial);
+ const detached = vi.fn();
+ source.onMount = () => detached;
+ const controller = new AbortController();
+ lifetimes.push(controller);
+ const model = createDocumentModel({
+ store,
+ notebook: { documentAtom: source, edit },
+ signal: controller.signal,
+ });
+ const wrapper = ({ children }: PropsWithChildren) => (
+ <Provider store={store}>
+ <DocumentProvider model={model}>{children}</DocumentProvider>
+ </Provider>
+ );
+ return { store, source, model, controller, detached, wrapper };
+}
+
+describe("document hooks", () => {
+ it("flushes edits through the model and aborts work when the session ends", async () => {
+ const accepted = withCells(document(), { c1: cell("c1", "local") });
+ const edit = vi
+ .fn<HostEdit>()
+ .mockResolvedValueOnce({
+ ok: true,
+ status: 200,
+ data: { document: accepted.revision, cells: {} },
+ })
+ .mockImplementation(
+ () => new Deferred<Awaited<ReturnType<HostEdit>>>().promise,
+ );
+ const { store, source, wrapper, controller } = setup(document(), edit);
+ const { result, unmount } = renderHook(
+ () => ({
+ code: useCellCode("c1"),
+ edit: useDocumentEdit(),
+ sync: useDocumentSync(),
+ }),
+ { wrapper, reactStrictMode: true },
+ );
+ act(() => result.current.edit((tx) => tx.setCode("c1", "local")));
+ expect(result.current.sync.status).toEqual({ status: "pending" });
+ const { flush, retry } = result.current.sync;
+ await act(async () => {
+ const flushed = flush();
+ // Allow the response to arrive before publishing its confirmation.
+ await Promise.resolve();
+ store.set(source, accepted);
+ await expect(flushed).resolves.toEqual(accepted.revision);
+ });
+ expect(result.current.sync).toEqual({
+ status: { status: "idle" },
+ flush,
+ retry,
+ });
+ expect(result.current.code).toBe("local");
+ act(() => result.current.edit((tx) => tx.setCode("c1", "next")));
+ await act(async () => {
+ const rejected = (async () => {
+ await expect(flush()).rejects.toThrow("session ended");
+ })();
+ await Promise.resolve();
+ unmount();
+ controller.abort(new Error("session ended"));
+ await rejected;
+ });
+ expect(edit).toHaveBeenCalledTimes(2);
+ expect(edit.mock.calls[1][2].signal.aborted).toBe(true);
+ });
+
+ it("publishes compound edits atomically without changing host records", () => {
+ const initial = document();
+ const { store, source, wrapper } = setup(initial);
+ const seen = vi.fn();
+ const { result } = renderHook(
+ () => {
+ const value = {
+ code: useCellCode("c1"),
+ name: useCellName("c1"),
+ config: useCellConfig("c1"),
+ order: useCellOrder(),
+ };
+ seen(value);
+ return { ...value, edit: useDocumentEdit() };
+ },
+ { wrapper },
+ );
+ const edit = result.current.edit;
+ seen.mockClear();
+
+ act(() =>
+ edit((tx) => {
+ tx.setCode("c1", "edited");
+ tx.setName("c1", "renamed");
+ tx.updateConfig("c1", { hide_code: true });
+ tx.setOrder(["c2", "c1"]);
+ }),
+ );
+
+ const expected = {
+ code: "edited",
+ name: "renamed",
+ config: { ...CONFIG, hide_code: true },
+ order: ["c2", "c1"],
+ };
+ expect(result.current).toEqual({ ...expected, edit });
+ expect(seen.mock.calls.length).toBeGreaterThan(0);
+ for (const [value] of seen.mock.calls) {
+ expect(value).toEqual(expected);
+ }
+ expect(store.get(source)).toBe(initial);
+
+ expect(() =>
+ act(() =>
+ edit((tx) => {
+ tx.setCode("c1", "rolled back");
+ tx.deleteCell("missing");
+ }),
+ ),
+ ).toThrow("does not exist");
+ expect(result.current).toEqual({ ...expected, edit });
+ });
+
+ it("subscribes to individual fields and keeps the edit function stable", () => {
+ const { store, source, wrapper } = setup();
+ const onCode = vi.fn();
+ const onName = vi.fn();
+ const onConfig = vi.fn();
+ const onOrder = vi.fn();
+ const onEdit = vi.fn();
+ function Code() {
+ onCode(useCellCode("c1"));
+ return null;
+ }
+ function Name() {
+ onName(useCellName("c1"));
+ return null;
+ }
+ function Config() {
+ onConfig(useCellConfig("c1"));
+ return null;
+ }
+ function Order() {
+ onOrder(useCellOrder());
+ return null;
+ }
+ function Edit() {
+ onEdit(useDocumentEdit());
+ return null;
+ }
+ render(
+ <>
+ <Code />
+ <Name />
+ <Config />
+ <Order />
+ <Edit />
+ </>,
+ { wrapper },
+ );
+ const edit: ReturnType<typeof useDocumentEdit> = onEdit.mock.calls[0][0];
+ const clear = () =>
+ [onCode, onName, onConfig, onOrder, onEdit].forEach((fn) =>
+ fn.mockClear(),
+ );
+ clear();
+
+ act(() => edit((tx) => tx.setCode("c1", "local")));
+ expect(onCode).toHaveBeenCalledWith("local");
+ expect(onName).not.toHaveBeenCalled();
+ expect(onConfig).not.toHaveBeenCalled();
+ expect(onOrder).not.toHaveBeenCalled();
+ expect(onEdit).not.toHaveBeenCalled();
+ clear();
+
+ act(() => edit((tx) => tx.setCode("c2", "other")));
+ expect(
+ [onCode, onName, onConfig, onOrder, onEdit].map((fn) => fn.mock.calls),
+ ).toEqual([[], [], [], [], []]);
+
+ act(() =>
+ store.set(
+ source,
+ withCells(document(), {
+ c1: cell("c1", "remote", {
+ name: "host name",
+ config: { ...CONFIG },
+ }),
+ }),
+ ),
+ );
+ expect(onName).toHaveBeenCalledWith("host name");
+ expect(onCode).not.toHaveBeenCalled();
+ expect(onConfig).not.toHaveBeenCalled();
+ expect(onOrder).not.toHaveBeenCalled();
+ expect(onEdit).not.toHaveBeenCalled();
+ clear();
+
+ act(() =>
+ edit((tx) => {
+ tx.updateConfig("c1", { disabled: true });
+ tx.setOrder(["c2", "c1"]);
+ }),
+ );
+ expect(onConfig).toHaveBeenCalledWith({ ...CONFIG, disabled: true });
+ expect(onOrder).toHaveBeenCalledWith(["c2", "c1"]);
+ expect(onCode).not.toHaveBeenCalled();
+ expect(onName).not.toHaveBeenCalled();
+ expect(onEdit).not.toHaveBeenCalled();
+ });
+
+ it("switches field subscriptions when the cell id changes", () => {
+ const { wrapper } = setup();
+ const { result, rerender } = renderHook(
+ (id) => ({
+ code: useCellCode(id),
+ edit: useDocumentEdit(),
+ }),
+ { wrapper, initialProps: "c1" },
+ );
+ const edit = result.current.edit;
+ rerender("c2");
+ expect(result.current).toEqual({ code: "y = 2", edit });
+ act(() => edit((tx) => tx.setCode("c1", "old subscription")));
+ expect(result.current).toEqual({ code: "y = 2", edit });
+ act(() => edit((tx) => tx.setCode("c2", "new subscription")));
+ expect(result.current).toEqual({ code: "new subscription", edit });
+ });
+
+ it("distinguishes unavailable documents, hidden source, empty code, and deleted cells", () => {
+ const { store, source, wrapper } = setup(null);
+ const { result } = renderHook(
+ () => ({
+ order: useCellOrder(),
+ code: useCellCode("c1"),
+ name: useCellName("c1"),
+ config: useCellConfig("c1"),
+ edit: useDocumentEdit(),
+ }),
+ { wrapper },
+ );
+ const edit = result.current.edit;
+ const absent = {
+ code: undefined,
+ name: undefined,
+ config: undefined,
+ edit,
+ };
+ expect(result.current).toEqual({ ...absent, order: null });
+ const hidden = withCells(document(), {
+ c1: cell("c1", "", { code: null }),
+ });
+ act(() => store.set(source, hidden));
+ expect(result.current).toEqual({
+ code: null,
+ name: "_",
+ config: CONFIG,
+ order: ["c1", "c2"],
+ edit,
+ });
+ act(() => edit((tx) => tx.setCode("c1", "")));
+ expect(result.current.code).toBe("");
+ act(() => store.set(source, null));
+ expect(result.current).toEqual({ ...absent, order: null });
+ act(() => store.set(source, hidden));
+ expect(result.current.code).toBe("");
+ act(() =>
+ edit((tx) => {
+ tx.deleteCell("c1");
+ tx.deleteCell("c2");
+ }),
+ );
+ expect(result.current).toEqual({ ...absent, order: [] });
+ });
+
+ it("preserves drafts across Strict Mode remounts until the session ends", () => {
+ const { wrapper, controller, detached } = setup();
+ const useProbe = () => ({
+ code: useCellCode("c1"),
+ edit: useDocumentEdit(),
+ });
+ const first = renderHook(useProbe, { wrapper, reactStrictMode: true });
+ const edit = first.result.current.edit;
+ act(() => edit((tx) => tx.setCode("c1", "strict mode edit")));
+ expect(first.result.current.code).toBe("strict mode edit");
+ first.unmount();
+ expect(detached).not.toHaveBeenCalled();
+
+ const second = renderHook(useProbe, { wrapper, reactStrictMode: true });
+ expect(second.result.current.code).toBe("strict mode edit");
+ act(() => edit((tx) => tx.setCode("c1", "same session")));
+ expect(second.result.current.code).toBe("same session");
+ second.unmount();
+ controller.abort();
+ expect(detached).toHaveBeenCalledOnce();
+ const callback = vi.fn();
+ edit(callback);
+ expect(callback).not.toHaveBeenCalled();
+ });
+
+ it("switches reads and edits to the supplied model and store", () => {
+ const first = setup();
+ const second = setup(
+ withCells(document("n2"), {
+ c1: cell("c1", "second source", { notebook_id: "n2" }),
+ }),
+ );
+ const seen = vi.fn();
+ function Probe() {
+ seen({ code: useCellCode("c1"), edit: useDocumentEdit() });
+ return null;
+ }
+ const tree = ({ store, model }: typeof first) => (
+ <Provider store={store}>
+ <DocumentProvider model={model}>
+ <Probe />
+ </DocumentProvider>
+ </Provider>
+ );
+ const { rerender } = render(tree(first));
+ const oldEdit: ReturnType<typeof useDocumentEdit> =
+ seen.mock.calls.at(-1)![0].edit;
+ act(() => oldEdit((tx) => tx.setCode("c1", "first draft")));
+ rerender(tree(second));
+ act(() => first.controller.abort());
+ expect(first.detached).toHaveBeenCalledOnce();
+ const latest: {
+ code: string | null | undefined;
+ edit: ReturnType<typeof useDocumentEdit>;
+ } = seen.mock.calls.at(-1)![0];
+ expect(latest.code).toBe("second source");
+ expect(latest.edit).not.toBe(oldEdit);
+ act(() => latest.edit((tx) => tx.setCode("c1", "second draft")));
+ expect(seen.mock.calls.at(-1)![0].code).toBe("second draft");
+ const stale = vi.fn();
+ oldEdit(stale);
+ expect(stale).not.toHaveBeenCalled();
+ seen.mockClear();
+ act(() =>
+ first.store.set(
+ first.source,
+ withCells(document(), {
+ c1: cell("c1", "stale host"),
+ }),
+ ),
+ );
+ expect(seen).not.toHaveBeenCalled();
+ });
+
+ it("requires a document provider", () => {
+ expect(() => renderHook(useDocumentEdit)).toThrow("DocumentProvider");
+ });
+});
diff --git a/frontend/src/core/document/hooks.tsx b/frontend/src/core/document/hooks.tsx
new file mode 100644
index 0000000000..a8063f7d0d
--- /dev/null
+++ b/frontend/src/core/document/hooks.tsx
@@ -0,0 +1,118 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { CellId } from "@marimo-team/client/protocol";
+import { useAtomValue, useSetAtom, useStore } from "jotai";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { cellCodeBinding } from "./codemirror";
+import type { EditableCell } from "./draft";
+import type { DocumentModel } from "./model";
+import { selectCellField, selectOrder } from "./select";
+
+const DocumentContext = createContext<DocumentModel | null>(null);
+
+/**
+ * Expose a session-owned model to React. Construct the model with the same store
+ * as the enclosing Jotai Provider. The session owner controls its AbortSignal;
+ * mounting or unmounting this provider does not change the model's lifetime.
+ *
+ * ```tsx
+ * <Provider store={store}>
+ * <DocumentProvider model={model}>
+ * <Editor />
+ * </DocumentProvider>
+ * </Provider>
+ * ```
+ */
+export function DocumentProvider({
+ model,
+ children,
+}: {
+ model: DocumentModel;
+ children: ReactNode;
+}) {
+ return (
+ <DocumentContext.Provider value={model}>
+ {children}
+ </DocumentContext.Provider>
+ );
+}
+
+function useDocumentModel() {
+ const model = useContext(DocumentContext);
+ if (model === null) {
+ throw new Error("Document hooks require a DocumentProvider");
+ }
+ return model;
+}
+
+/** Null while the document is unavailable; an empty array for an empty document. */
+export function useCellOrder() {
+ const { documentAtom } = useDocumentModel();
+ return useAtomValue(useMemo(() => selectOrder(documentAtom), [documentAtom]));
+}
+
+function useCellField<K extends keyof EditableCell>(id: CellId, field: K) {
+ const { documentAtom } = useDocumentModel();
+ return useAtomValue(
+ useMemo(
+ () => selectCellField(documentAtom, id, field),
+ [documentAtom, id, field],
+ ),
+ );
+}
+
+/** Undefined for an absent cell; null when the host withholds its source. */
+export function useCellCode(id: CellId) {
+ return useCellField(id, "code");
+}
+
+/** Undefined when the cell or document is unavailable. */
+export function useCellName(id: CellId) {
+ return useCellField(id, "name");
+}
+
+/** Undefined when the cell or document is unavailable. */
+export function useCellConfig(id: CellId) {
+ return useCellField(id, "config");
+}
+
+/**
+ * A CodeMirror extension that binds the editor's text to a cell's code.
+ * Stable until the cell id or document model changes.
+ *
+ * ```tsx
+ * const extension = useCellCodeExtension(cellId);
+ * ```
+ */
+export function useCellCodeExtension(id: CellId) {
+ const model = useDocumentModel();
+ const store = useStore();
+ return useMemo(
+ () => cellCodeBinding({ store, model, cellId: id }),
+ [model, store, id],
+ );
+}
+
+/**
+ * A stable edit function. Synchronous callbacks publish atomically or roll back.
+ *
+ * ```ts
+ * const edit = useDocumentEdit();
+ * edit((tx) => tx.setCode(cellId, code));
+ * ```
+ */
+export function useDocumentEdit() {
+ return useSetAtom(useDocumentModel().editAtom);
+}
+
+/**
+ * Sync status and explicit recovery. flush waits for edits, including newer
+ * typing, to reach the confirmed source and returns the revision for Run/Save.
+ * Rejections retain local edits; retry explicitly resubmits them. Requests
+ * with an unknown outcome reuse their original key within the retry window.
+ */
+export function useDocumentSync() {
+ const model = useDocumentModel();
+ const status = useAtomValue(model.syncStatusAtom);
+ return { status, flush: model.flush, retry: model.retry };
+}
diff --git a/frontend/src/core/document/index.ts b/frontend/src/core/document/index.ts
index 6213d1aca0..b2f2f35808 100644
--- a/frontend/src/core/document/index.ts
+++ b/frontend/src/core/document/index.ts
@@ -1,5 +1,15 @@
/* Copyright 2026 Marimo. All rights reserved. */
+export {
+ DocumentProvider,
+ useCellCode,
+ useCellCodeExtension,
+ useCellConfig,
+ useCellName,
+ useCellOrder,
+ useDocumentEdit,
+ useDocumentSync,
+} from "./hooks";
export { createDocumentModel } from "./model";
export type {
DocumentEdit,