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.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 &&
current &&
- 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 };
}