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
Clean up the document model's public API (#11467)
Trevor Manzbccfb9e119d2
diff --git a/frontend/src/core/document/__tests__/model.test.ts b/frontend/src/core/document/__tests__/model.test.tsindex 5e5e02bb28..0d18e187f3 100644--- a/frontend/src/core/document/__tests__/model.test.ts+++ b/frontend/src/core/document/__tests__/model.test.ts@@ -67,8 +67,8 @@ function setup() {unmounted,edit: (code: string) =>store.set(model.editAtom, (tx) => tx.setCode("c1", code)),- state: () => store.get(model.syncStateAtom),- value: () => store.get(model.cellAtom("c1")),+ status: () => store.get(model.syncStatusAtom),+ value: () => store.get(model.documentAtom)?.cells.get("c1"),};}@@ -102,7 +102,7 @@ describe("document synchronization", () => {});it("fails without repeating a request when the response names another notebook", async () => {- const { sent, replies, edit, model, state } = setup();+ const { sent, replies, edit, model, status } = setup();edit("local");const rejected = expectFailure(model.flush(), "another notebook");await vi.advanceTimersByTimeAsync(0);@@ -110,7 +110,7 @@ describe("document synchronization", () => {await rejected;await vi.advanceTimersByTimeAsync(5000);expect(sent).toHaveBeenCalledOnce();- expect(state()).toMatchObject({ status: "error" });+ expect(status()).toMatchObject({ status: "error" });});it("ignores a late response and source update after its lifetime ends", async () => {@@ -145,7 +145,7 @@ describe("document synchronization", () => {});it("aborts an in-flight edit when notebook identity changes", async () => {- const { store, source, sent, edit, model, state } = setup();+ const { store, source, sent, edit, model, status } = setup();edit("local");const flushed = model.flush();const rejected = expectFailure(flushed, "notebook changed");@@ -153,6 +153,6 @@ describe("document synchronization", () => {store.set(source, document("n2"));await rejected;expect(sent.mock.calls[0][0].signal.aborted).toBe(true);- expect(state()).toMatchObject({ status: "error", retryable: false });+ expect(status()).toMatchObject({ status: "error", retryable: false });});});diff --git a/frontend/src/core/document/__tests__/state.test.ts b/frontend/src/core/document/__tests__/state.test.tsindex 152dc80056..d79e2de7da 100644--- a/frontend/src/core/document/__tests__/state.test.ts+++ b/frontend/src/core/document/__tests__/state.test.ts@@ -8,6 +8,7 @@ import {type DocumentEdit,type DocumentEditor,} from "../state";+import { selectCell, selectOrder } from "../select";import { cell, document, withCells } from "./fixtures";const lifetimes: AbortController[] = [];@@ -29,6 +30,8 @@ function setup(initial: Document | null = document()) {store,source,...model,+ cellAtom: (id: string) => selectCell(model.documentAtom, id),+ orderAtom: selectOrder(model.documentAtom),abort: () => controller.abort(),edit: (callback: DocumentEdit) => store.set(model.editAtom, callback),};@@ -252,10 +255,9 @@ describe("document model", () => {unsubscribeOrder();});- it("isolates cell, order and configuration subscriptions across local and host updates", () => {+ it("isolates cell and order subscriptions across local and host updates", () => {const initial = document();- const { store, source, cellAtom, orderAtom, appConfigAtom, edit } =- setup(initial);+ const { store, source, cellAtom, orderAtom, edit } = setup(initial);edit((tx) => {tx.setCode("c1", "local");tx.createCell({ id: "c3", code: "new" });@@ -263,16 +265,13 @@ describe("document model", () => {const c1 = cellAtom("c1");const first = store.get(c1);const order = store.get(orderAtom);- const config = store.get(appConfigAtom);const onFirst = vi.fn();const onSecond = vi.fn();const onOrder = vi.fn();- const onConfig = vi.fn();const unsubscribe = [store.sub(c1, onFirst),store.sub(cellAtom("c2"), onSecond),store.sub(orderAtom, onOrder),- store.sub(appConfigAtom, onConfig),];edit((tx) => tx.setCode("c2", "other local"));@@ -289,11 +288,9 @@ describe("document model", () => {});expect(store.get(c1)).toBe(first);expect(store.get(orderAtom)).toBe(order);- expect(store.get(appConfigAtom)).toBe(config);expect(onFirst).not.toHaveBeenCalled();expect(onSecond).toHaveBeenCalledOnce();expect(onOrder).not.toHaveBeenCalled();- expect(onConfig).not.toHaveBeenCalled();store.set(source,@@ -311,11 +308,6 @@ describe("document model", () => {edit((tx) => tx.setOrder(["c3", "c2", "c1"]));expect(onOrder).toHaveBeenCalledOnce();expect(onFirst).toHaveBeenCalledOnce();- store.set(source, {- ...remote,- revision: { ...remote.revision, app_config: { width: "full" } },- });- expect(onConfig).toHaveBeenCalledOnce();unsubscribe.forEach((fn) => fn());});diff --git a/frontend/src/core/document/__tests__/submission.test.ts b/frontend/src/core/document/__tests__/submission.test.tsindex bee525661a..0a6423935e 100644--- a/frontend/src/core/document/__tests__/submission.test.ts+++ b/frontend/src/core/document/__tests__/submission.test.ts@@ -3,6 +3,7 @@import { atom, createStore } from "jotai/vanilla";import { afterEach, describe, expect, it, vi } from "vitest";import type { Document } from "../../host/resources/document";+import { selectCell } from "../select";import { createDocumentState, type DocumentSubmission } from "../state";import { cell, document, withCells } from "./fixtures";@@ -25,6 +26,7 @@ function setup() {store,source,...model,+ cellAtom: (id: string) => selectCell(model.documentAtom, id),submit() {const submission = store.set(model.submitAtom);if (submission === null) {diff --git a/frontend/src/core/document/__tests__/user.ts b/frontend/src/core/document/__tests__/user.tsindex 91d6279aa0..5420f89e2f 100644--- a/frontend/src/core/document/__tests__/user.ts+++ b/frontend/src/core/document/__tests__/user.ts@@ -43,7 +43,7 @@ export function createUser(store.set(model.editAtom, (tx) => tx.deleteCell(id));},cell(id: Protocol.CellId) {- const cell = store.get(model.cellAtom(id));+ const cell = store.get(model.documentAtom)?.cells.get(id);return cell === undefined? undefined: {@@ -53,8 +53,8 @@ export function createUser(config: cell.config,};},- order: () => store.get(model.orderAtom),- status: () => store.get(model.syncStateAtom),+ order: () => store.get(model.documentAtom)?.order ?? null,+ status: () => store.get(model.syncStatusAtom),sync: () => observe(model.flush()),retry: () => observe(model.retry()),};diff --git a/frontend/src/core/document/index.ts b/frontend/src/core/document/index.tsindex 4b779f498c..6213d1aca0 100644--- a/frontend/src/core/document/index.ts+++ b/frontend/src/core/document/index.ts@@ -6,5 +6,7 @@ export type {DocumentEditor,DocumentHost,DocumentModel,- DocumentSyncState,+ DocumentSyncStatus,+ EditableCell,+ EditableDocument,} from "./model";diff --git a/frontend/src/core/document/model.ts b/frontend/src/core/document/model.tsindex 050ad79c36..e418033ca8 100644--- a/frontend/src/core/document/model.ts+++ b/frontend/src/core/document/model.ts@@ -6,18 +6,19 @@ import { createDocumentState, type DocumentState } from "./state";import {createDocumentSync,type DocumentHost,- type DocumentSyncState,+ type DocumentSyncStatus,} from "./sync";export type { DocumentEdit, DocumentEditor } from "./state";-export type { DocumentHost, DocumentSyncState } from "./sync";+export type { EditableCell, EditableDocument } from "./draft";+export type { DocumentHost, DocumentSyncStatus } from "./sync";/** The editable document and its synchronization with the host. */export interface DocumentModel extends Pick<DocumentState,- "cellAtom" | "orderAtom" | "appConfigAtom" | "editAtom"+ "documentAtom" | "editAtom"> {- readonly syncStateAtom: Atom<DocumentSyncState>;+ readonly syncStatusAtom: Atom<DocumentSyncStatus>;/** Drain local edits and return the confirmed revision. */flush(): Promise<Protocol.Document>;/** Retry a rejection against fresh state, or repeat an uncertain request exactly. */@@ -42,11 +43,9 @@ export function createDocumentModel({});const sync = createDocumentSync({ store, notebook, state, signal });return {- cellAtom: state.cellAtom,- orderAtom: state.orderAtom,- appConfigAtom: state.appConfigAtom,+ documentAtom: state.documentAtom,editAtom: state.editAtom,- syncStateAtom: sync.stateAtom,+ syncStatusAtom: sync.statusAtom,flush: sync.flush,retry: sync.retry,};diff --git a/frontend/src/core/document/select.ts b/frontend/src/core/document/select.tsnew file mode 100644index 0000000000..05a609c8fd--- /dev/null+++ b/frontend/src/core/document/select.ts@@ -0,0 +1,32 @@+/* Copyright 2026 Marimo. All rights reserved. */++import type * as Protocol from "@marimo-team/client/protocol";+import { dequal } from "dequal";+import type { Atom } from "jotai/vanilla";+import { selectAtom } from "jotai/vanilla/utils";+import { type EditableCell, type EditableDocument, sameCell } from "./draft";++/**+ * Select one cell of a document.+ *+ * The atom notifies when the cell's code, name, or config changes. A new host+ * record with the same values leaves it unchanged. Each call creates an atom,+ * so keep it for as long as its subscription.+ */+export function selectCell(+ document: Atom<EditableDocument | null>,+ id: Protocol.CellId,+): Atom<EditableCell | undefined> {+ return selectAtom(+ document,+ (value) => value?.cells.get(id),+ (a, b) => a === b || (a !== undefined && b !== undefined && sameCell(a, b)),+ );+}++/** Select a document's cell order, null while the document is unavailable. */+export function selectOrder(+ document: Atom<EditableDocument | null>,+): Atom<readonly Protocol.CellId[] | null> {+ return selectAtom(document, (value) => value?.order ?? null, dequal);+}diff --git a/frontend/src/core/document/state.ts b/frontend/src/core/document/state.tsindex a621e8c5c6..afd870d9d8 100644--- a/frontend/src/core/document/state.ts+++ b/frontend/src/core/document/state.ts@@ -1,13 +1,11 @@/* Copyright 2026 Marimo. All rights reserved. */-import { dequal } from "dequal";import {atom,type Atom,type createStore,type WritableAtom,} from "jotai/vanilla";-import { selectAtom } from "jotai/vanilla/utils";import type { Document } from "../host/resources/document";import * as Protocol from "@marimo-team/client/protocol";import {@@ -16,14 +14,12 @@ import {createCell,deleteCell,type Draft,- type EditableCell,type EditableDocument,editCell,EMPTY_DRAFT,isEmptyDraft,type Placement,prune,- sameCell,setOrder,toChanges,viewDocument,@@ -70,12 +66,8 @@ interface ModelState {* Switching notebook identity invalidates it, retaining each notebook's draft.*/export interface DocumentState {- /** Hold onto the selector; its value is stable until the cell changes. */- cellAtom(id: Protocol.CellId): Atom<EditableCell | undefined>;- readonly orderAtom: Atom<readonly Protocol.CellId[] | null>;- readonly appConfigAtom: Atom<Readonly<- Protocol.Document["app_config"]- > | null>;+ /** Confirmed host state with local drafts applied, null while unavailable. */+ readonly documentAtom: Atom<EditableDocument | null>;/** Null when the document or source needed by a put is unavailable. */readonly changesAtom: Atom<readonly Protocol.Change[] | null>;/** Remains pending until both the response and its streamed revision arrive. */@@ -158,23 +150,6 @@ export function createDocumentState({? null: viewDocument(state.confirmed, draftOf(state));});- const cellAtom = (id: Protocol.CellId) =>- selectAtom(- documentAtom,- (document) => document?.cells.get(id),- (a, b) =>- a === b || (a !== undefined && b !== undefined && sameCell(a, b)),- );- const orderAtom = selectAtom(- documentAtom,- (document) => document?.order ?? null,- dequal,- );- const appConfigAtom = selectAtom(- stateAtom,- (state) => state.confirmed?.revision.app_config ?? null,- dequal,- );const changesAtom = atom((get): readonly Protocol.Change[] | null => {const state = get(stateAtom);return state.confirmed === null@@ -304,9 +279,7 @@ export function createDocumentState({}return {- cellAtom,- orderAtom,- appConfigAtom,+ documentAtom,changesAtom,pendingAtom,editAtom,diff --git a/frontend/src/core/document/sync.ts b/frontend/src/core/document/sync.tsindex 371af8e9d9..6a0f9dde74 100644--- a/frontend/src/core/document/sync.ts+++ b/frontend/src/core/document/sync.ts@@ -9,7 +9,7 @@ import type { DocumentState, DocumentSubmission } from "./state";/** The notebook state and operation needed by document editing. */export type DocumentHost = Pick<NotebookClient, "documentAtom" | "edit">;-export type DocumentSyncState =+export type DocumentSyncStatus =| {readonly status:| "idle"@@ -26,7 +26,7 @@ export type DocumentSyncState =};interface Submission {- readonly edit: DocumentSubmission;+ readonly submission: DocumentSubmission;readonly idempotencyKey: string;readonly startedAt: number;readonly controller: AbortController;@@ -85,7 +85,7 @@ export function createDocumentSync({}) {signal.throwIfAborted();const source = notebook.documentAtom;- const stateAtom = atom<DocumentSyncState>({ status: "idle" });+ const statusAtom = atom<DocumentSyncStatus>({ status: "idle" });const observed = atom((get) => ({document: get(source),pending: get(state.pendingAtom),@@ -93,7 +93,7 @@ export function createDocumentSync({}));let active: Submission | null = null;let running: Promise<Protocol.Document> | null = null;- let failure: Extract<DocumentSyncState, { status: "error" }> | null = null;+ let failure: Extract<DocumentSyncStatus, { status: "error" }> | null = null;let timer: ReturnType<typeof setTimeout> | undefined;let refreshing = false;@@ -118,7 +118,7 @@ export function createDocumentSync({if (active &¤t &&- current.revision.notebook_id !== active.edit.notebookId+ current.revision.notebook_id !== active.submission.notebookId) {active.controller.abort(new Error("The notebook changed during synchronization"),@@ -130,13 +130,13 @@ export function createDocumentSync({clearTimer();const changes = store.get(state.changesAtom);if (changes === null) {- store.set(stateAtom, { status: "unavailable" });+ store.set(statusAtom, { status: "unavailable" });} else if (changes.length === 0) {// Release unsent reversals instead of keeping an invisible override.store.set(state.submitAtom);- store.set(stateAtom, { status: "idle" });+ store.set(statusAtom, { status: "idle" });} else {- store.set(stateAtom, { status: "pending" });+ store.set(statusAtom, { status: "pending" });timer = setTimeout(() => {void flush().catch(() => undefined);}, DEBOUNCE_MS);@@ -155,7 +155,7 @@ export function createDocumentSync({"The edit's retry window expired; its outcome is unknown",);}- store.set(stateAtom, { status: "sending" });+ store.set(statusAtom, { status: "sending" });const controller = new AbortController();const abort = () => controller.abort(request.controller.signal.reason);request.controller.signal.addEventListener("abort", abort, {@@ -170,10 +170,14 @@ export function createDocumentSync({signal.throwIfAborted();request.controller.signal.throwIfAborted();result = await abortable(- notebook.edit(request.edit.notebookId, request.edit.changes, {- idempotencyKey: request.idempotencyKey,- signal: controller.signal,- }),+ notebook.edit(+ request.submission.notebookId,+ request.submission.changes,+ {+ idempotencyKey: request.idempotencyKey,+ signal: controller.signal,+ },+ ),controller.signal,);} catch (error) {@@ -198,17 +202,17 @@ export function createDocumentSync({cause: result.problem,});}- if (result.data.document.notebook_id !== request.edit.notebookId) {+ if (result.data.document.notebook_id !== request.submission.notebookId) {throw new Error("Edit response belongs to another notebook");}request.response = result.data.document;- store.set(state.settleAtom, request.edit, request.response);+ store.set(state.settleAtom, request.submission, request.response);return;}}function confirm(request: Submission): Promise<void> {- store.set(stateAtom, { status: "confirming" });+ store.set(statusAtom, { status: "confirming" });return new Promise((resolve, reject) => {const check = () => {if (signal.aborted || request.controller.signal.aborted) {@@ -216,7 +220,7 @@ export function createDocumentSync({reject(signal.aborted ? signal.reason : request.controller.signal.reason,);- } else if (store.get(state.pendingAtom) !== request.edit) {+ } else if (store.get(state.pendingAtom) !== request.submission) {cleanup();resolve();}@@ -247,12 +251,12 @@ export function createDocumentSync({if (current === null || store.get(state.changesAtom) === null) {throw unavailable();}- const edit = store.set(state.submitAtom);- if (edit === null) {+ const submission = store.set(state.submitAtom);+ if (submission === null) {return current.revision;}active = {- edit,+ submission,idempotencyKey: idempotencyKey(),startedAt: Date.now(),controller: new AbortController(),@@ -282,7 +286,7 @@ export function createDocumentSync({Date.now() - active.startedAt < RETRY_WINDOW_MS),};if (!signal.aborted) {- store.set(stateAtom, failure);+ store.set(statusAtom, failure);}throw error;} finally {@@ -305,7 +309,7 @@ export function createDocumentSync({return running;}const notebookId =- active?.edit.notebookId ?? store.get(source)?.revision.notebook_id;+ active?.submission.notebookId ?? store.get(source)?.revision.notebook_id;if (notebookId === undefined) {return Promise.reject(unavailable());}@@ -329,14 +333,14 @@ export function createDocumentSync({const rejectedAt = active.problem.edit?.document.version;if (!current ||- current.revision.notebook_id !== active.edit.notebookId ||+ current.revision.notebook_id !== active.submission.notebookId ||(rejectedAt !== undefined && current.revision.version < rejectedAt)) {return Promise.reject(new Error("Wait for the host's current document before retrying"),);}- store.set(state.settleAtom, active.edit, null);+ store.set(state.settleAtom, active.submission, null);active = null;}failure = null;@@ -355,5 +359,5 @@ export function createDocumentSync({stop();}refresh();- return { stateAtom, flush, retry };+ return { statusAtom, flush, retry };}