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
/* Copyright 2026 Marimo. All rights reserved. */
import {
atom,
type Atom,
type createStore,
type WritableAtom,
} from "jotai/vanilla";
import type { Document } from "../replica";
import * as Protocol from "@marimo-team/client/protocol";
import {
acknowledge,
type CellEdit,
createCell,
deleteCell,
restoreCell,
type Draft,
type EditableDocument,
editCell,
EMPTY_DRAFT,
isEmptyDraft,
type Placement,
prune,
setOrder,
toChanges,
viewDocument,
} from "./draft";
/** Operations on a working draft, valid only during the edit callback. */
export interface DocumentEditor {
setCode(id: Protocol.CellId, code: string): void;
setName(id: Protocol.CellId, name: string): void;
updateConfig(id: Protocol.CellId, patch: Partial<Protocol.CellConfig>): void;
/** Create a cell, or bring back one this draft deletes with this content. */
createCell(cell: Protocol.CellInput, placement?: Placement): void;
deleteCell(id: Protocol.CellId): void;
/** A permutation of the cells present at this point in the transaction. */
setOrder(order: readonly Protocol.CellId[]): void;
}
/** Synchronous; a thrown error discards the entire transaction. */
export type DocumentEdit = (editor: DocumentEditor) => void;
/** A captured edit request. Return this same object when reporting its result. */
export interface DocumentSubmission {
readonly notebookId: Protocol.NotebookId;
readonly changes: readonly Protocol.Change[];
}
type ResponseRevision = Pick<Protocol.Document, "notebook_id" | "version">;
interface PendingSubmission {
readonly submission: DocumentSubmission;
readonly draft: Draft;
readonly responseRevision: ResponseRevision | null;
}
interface ModelState {
readonly confirmed: Document | null;
readonly drafts: ReadonlyMap<Protocol.NotebookId, Draft>;
readonly pending: PendingSubmission | null;
}
/**
* Local edits over confirmed host state, with one submission in flight.
*
* A reset retains the submission so its receipt can reconcile a new snapshot.
* Switching notebook identity invalidates it, retaining each notebook's draft.
*/
export interface DocumentState {
/** 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. */
readonly pendingAtom: Atom<DocumentSubmission | null>;
readonly editAtom: WritableAtom<null, [edit: DocumentEdit], void>;
/** Capture a request, or null when unavailable, unchanged, or already sending. */
readonly submitAtom: WritableAtom<null, [], DocumentSubmission | null>;
/**
* Report the response revision, or null for a rejected request.
*
* Success waits for a complete streamed document at that version or later.
* Duplicate replies and replies for another notebook are ignored. Retry an
* uncertain request with the same body and idempotency key; do not reject it
* or capture a new request until its outcome is known.
*/
readonly settleAtom: WritableAtom<
null,
[submission: DocumentSubmission, responseRevision: ResponseRevision | null],
void
>;
}
function draftOf(state: ModelState): Draft {
return state.confirmed === null
? EMPTY_DRAFT
: (state.drafts.get(state.confirmed.revision.notebook_id) ?? EMPTY_DRAFT);
}
function withDraft(state: ModelState, draft: Draft): ModelState {
if (state.confirmed === null || draft === draftOf(state)) {
return state;
}
const drafts = new Map(state.drafts);
const notebookId = state.confirmed.revision.notebook_id;
if (isEmptyDraft(draft)) {
drafts.delete(notebookId);
} else {
drafts.set(notebookId, draft);
}
return { ...state, drafts };
}
/** Publish the confirmed document and any released fields together. */
function reconcile(state: ModelState): ModelState {
const { confirmed, pending } = state;
if (confirmed === null) {
return state;
}
let draft = draftOf(state);
if (
pending !== null &&
pending.responseRevision !== null &&
confirmed.revision.version >= pending.responseRevision.version
) {
draft = acknowledge(draft, pending.draft);
state = { ...state, pending: null };
}
return withDraft(state, prune(confirmed, draft, state.pending?.draft));
}
/** Internal draft and submission state for one editing lifetime. */
export function createDocumentState({
store,
source,
signal,
}: {
store: ReturnType<typeof createStore>;
source: Atom<Document | null>;
signal: AbortSignal;
}): DocumentState {
signal.throwIfAborted();
const stateAtom = atom<ModelState>({
confirmed: store.get(source),
drafts: new Map(),
pending: null,
});
const documentAtom = atom((get): EditableDocument | null => {
const state = get(stateAtom);
return state.confirmed === null
? null
: viewDocument(state.confirmed, draftOf(state));
});
const changesAtom = atom((get): readonly Protocol.Change[] | null => {
const state = get(stateAtom);
return state.confirmed === null
? null
: toChanges(state.confirmed, draftOf(state));
});
const pendingAtom = atom((get) => get(stateAtom).pending?.submission ?? null);
const unsubscribe = store.sub(source, () => {
const confirmed = store.get(source);
store.set(stateAtom, (state) =>
reconcile({
...state,
confirmed,
pending:
confirmed !== null &&
state.pending !== null &&
confirmed.revision.notebook_id !== state.pending.submission.notebookId
? null
: state.pending,
}),
);
});
let editing = false;
const editAtom = atom(null, (get, set, edit: DocumentEdit) => {
if (editing) {
throw new Error("Document transactions cannot be nested");
}
const state = get(stateAtom);
if (signal.aborted || state.confirmed === null) {
return;
}
editing = true;
try {
const draft = editDocument(
state.confirmed,
draftOf(state),
edit,
state.pending?.draft,
);
if (
signal.aborted ||
get(stateAtom) !== state ||
get(source) !== state.confirmed
) {
throw new Error("The document changed during the transaction");
}
set(stateAtom, withDraft(state, draft));
} finally {
editing = false;
}
});
const submitAtom = atom(null, (get, set): DocumentSubmission | null => {
const state = get(stateAtom);
if (signal.aborted || state.confirmed === null || state.pending !== null) {
return null;
}
const draft = draftOf(state);
const changes = toChanges(state.confirmed, draft);
if (changes === null) {
return null;
}
if (changes.length === 0) {
set(stateAtom, withDraft(state, EMPTY_DRAFT));
return null;
}
const submission = {
notebookId: state.confirmed.revision.notebook_id,
changes,
};
set(stateAtom, {
...state,
pending: { submission, draft, responseRevision: null },
});
return submission;
});
const settleAtom = atom(
null,
(
get,
set,
submission: DocumentSubmission,
responseRevision: ResponseRevision | null,
) => {
const state = get(stateAtom);
if (
signal.aborted ||
state.pending?.submission !== submission ||
state.pending.responseRevision !== null
) {
return;
}
if (
responseRevision !== null &&
responseRevision.notebook_id !== submission.notebookId
) {
throw new Error("Edit response belongs to another notebook");
}
set(
stateAtom,
reconcile({
...state,
pending:
responseRevision === null
? null
: { ...state.pending, responseRevision },
}),
);
},
);
function stop() {
unsubscribe();
signal.removeEventListener("abort", stop);
store.set(stateAtom, {
confirmed: null,
drafts: new Map(),
pending: null,
});
}
signal.addEventListener("abort", stop, { once: true });
if (signal.aborted) {
stop();
}
return {
documentAtom,
changesAtom,
pendingAtom,
editAtom,
submitAtom,
settleAtom,
};
}
function editDocument(
confirmed: Document,
draft: Draft,
edit: DocumentEdit,
sent: Draft = EMPTY_DRAFT,
): Draft {
let next = draft;
let active = true;
function assertActive() {
if (!active) {
throw new Error("The document transaction has ended");
}
}
function hasCell(id: Protocol.CellId): boolean {
const local = next.cells.get(id);
return (
local?.kind === "create" ||
(local?.kind !== "delete" && confirmed.cells.has(id))
);
}
function requireCell(id: Protocol.CellId) {
assertActive();
if (!hasCell(id)) {
throw new Error(`Cell ${id} does not exist`);
}
}
function updateCell(id: Protocol.CellId, patch: CellEdit) {
requireCell(id);
next = editCell(confirmed, next, id, patch);
}
const editor: DocumentEditor = {
setCode: (id, code) => updateCell(id, { code }),
setName: (id, name) => updateCell(id, { name }),
updateConfig: (id, patch) =>
updateCell(id, { config: Protocol.CellConfig.partial().parse(patch) }),
createCell: (cell, placement = {}) => {
assertActive();
if (hasCell(cell.id)) {
throw new Error(`Cell ${cell.id} already exists`);
}
if (placement.after !== undefined && placement.before !== undefined) {
throw new Error("Specify either before or after for cell placement");
}
const anchor = placement.after ?? placement.before;
if (anchor !== undefined) {
requireCell(anchor);
}
next = confirmed.cells.has(cell.id)
? restoreCell(confirmed, next, cell, { ...placement }, sent)
: createCell(next, cell, { ...placement });
},
deleteCell: (id) => {
requireCell(id);
next = deleteCell(next, id, sent);
},
setOrder: (order) => {
assertActive();
const { cells } = viewDocument(confirmed, next);
if (
order.length !== cells.size ||
new Set(order).size !== cells.size ||
order.some((id) => !cells.has(id))
) {
throw new Error("Cell order must contain every cell exactly once");
}
next = setOrder(next, order);
},
};
try {
const result: unknown = edit(editor);
if (result instanceof Promise) {
// Observe a rejected async callback without publishing its partial draft.
result.catch(() => undefined);
throw new Error("Document edit callbacks must be synchronous");
}
return next;
} finally {
active = false;
}
}