@marimo-team/frontend 0.25.3-dev101 → 0.25.3-dev103

package/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 });
   });
 });

package/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());
   });
 

package/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) {

package/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()),
   };

package/src/core/document/codemirror.ts

@@ -0,0 +1,311 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * A CodeMirror binding between an editor and one cell's code.
+ *
+ * The editor and the document model each hold the code, and the binding keeps
+ * them equal in both directions.
+ *
+ * - Push. An update that could change the code writes it to the model before
+ *   the update returns, so the model keeps pace with typing.
+ * - Pull. A model change reaches the editor in a microtask, because a view
+ *   cannot dispatch while it is constructing or updating. The binding keeps
+ *   the code both sides last agreed on, so the model's echo of a push is
+ *   skipped while a different value, even one written during that push, is
+ *   pulled. A real change is marked remote, stays out of undo history, and
+ *   waits for IME composition to end.
+ *
+ * The editor shows code through marimo's language adapters, so a markdown
+ * cell edits the text inside `mo.md`. Both directions compare the cell's
+ * Python code rather than the editor text, so an adapter that normalizes what
+ * it reads back leaves typing alone.
+ *
+ * A pulled change replaces only what differs, using `diff` from
+ * `@codemirror/merge`. Separate edits stay separate, so the selection, folds,
+ * and diagnostics between them keep their place. The diff uses a scan limit of
+ * 500, as the merge view does. Past it, the search trades precision for speed,
+ * so a rewrite of a large cell costs microseconds and maps the selection
+ * coarsely instead of blocking the editor.
+ */
+
+import { diff } from "@codemirror/merge";
+import {
+  type ChangeSpec,
+  type EditorState,
+  type Extension,
+  type StateEffect,
+  Transaction,
+} from "@codemirror/state";
+import { type EditorView, ViewPlugin, type ViewUpdate } from "@codemirror/view";
+import type { CellId } from "@marimo-team/client/protocol";
+import { dequal } from "dequal";
+import type { Atom, createStore } from "jotai/vanilla";
+import {
+  languageAdapterFromCode,
+  languageAdapterState,
+  switchLanguage,
+} from "../codemirror/language/extension";
+import { initializeSQLDialect } from "../codemirror/language/languages/sql/sql";
+import {
+  languageMetadataField,
+  setLanguageMetadata,
+} from "../codemirror/language/metadata";
+import type { DocumentModel } from "./model";
+import { selectCellField } from "./select";
+
+/** The diff scan limit, matching the default of the merge view. */
+const SCAN_LIMIT = 500;
+
+interface Binding {
+  readonly store: ReturnType<typeof createStore>;
+  readonly model: DocumentModel;
+  readonly cellId: CellId;
+  /** Undefined while the cell is absent, null while its source is withheld. */
+  readonly code: Atom<string | null | undefined>;
+}
+
+/**
+ * Bind an editor to one cell's code.
+ *
+ * Editors without marimo's language configuration bind their text as is.
+ */
+export function cellCodeBinding({
+  store,
+  model,
+  cellId,
+}: {
+  store: ReturnType<typeof createStore>;
+  model: DocumentModel;
+  cellId: CellId;
+}): Extension {
+  const binding: Binding = {
+    store,
+    model,
+    cellId,
+    code: selectCellField(model.documentAtom, cellId, "code"),
+  };
+  return ViewPlugin.define((view) => new CellCodeSync(view, binding), {
+    eventObservers: {
+      compositionend() {
+        this.compositionEnded();
+      },
+    },
+  });
+}
+
+class CellCodeSync {
+  #scheduled = false;
+  /** A pull arrived during IME composition and runs once it ends. */
+  #deferred = false;
+  /**
+   * A pull is dispatching to the editor.
+   *
+   * A language switch dispatches transactions of its own before the text, and
+   * their in-between states represent the wrong code. Until the switch can be
+   * part of the pull's one remote transaction, this keeps them from pushing.
+   */
+  #pulling = false;
+  /**
+   * The code the editor and the model last agreed on.
+   *
+   * A change the model cannot take clears it, so once the cell is available
+   * again its code is pulled even if it matches what was agreed before.
+   */
+  #synced: string | undefined;
+  #destroyed = false;
+  readonly #view: EditorView;
+  readonly #binding: Binding;
+  readonly #unsubscribe: () => void;
+
+  public constructor(view: EditorView, binding: Binding) {
+    this.#view = view;
+    this.#binding = binding;
+    // A change to the agreed code is the echo of a push and needs no pull.
+    this.#unsubscribe = binding.store.sub(binding.code, () => {
+      if (binding.store.get(binding.code) !== this.#synced) {
+        this.#schedule();
+      }
+    });
+    this.#schedule();
+  }
+
+  public update(update: ViewUpdate) {
+    if (!this.#pulling && changesCode(update)) {
+      this.#push(update.state);
+    }
+    if (this.#deferred && !update.view.composing) {
+      this.#schedule();
+    }
+  }
+
+  /**
+   * Run a pull that waited for the composition.
+   *
+   * A composition that ends without changing the text need not produce an
+   * update. CodeMirror finishes handling the end in a microtask, so the pull
+   * waits for the next task.
+   */
+  public compositionEnded() {
+    if (this.#deferred) {
+      setTimeout(() => this.#schedule(), 0);
+    }
+  }
+
+  public destroy() {
+    this.#destroyed = true;
+    this.#unsubscribe();
+  }
+
+  /** Write the editor's code to the model unless the editor already shows it. */
+  #push(state: EditorState) {
+    const { store, model, cellId, code } = this.#binding;
+    const current = store.get(code);
+    if (typeof current !== "string") {
+      this.#synced = undefined;
+      return;
+    }
+    if (shows(state, current)) {
+      this.#synced = current;
+      return;
+    }
+    const next = codeOf(state);
+    this.#synced = next;
+    store.set(model.editAtom, (tx) => tx.setCode(cellId, next));
+  }
+
+  /** Show the model's code unless the editor already shows it. */
+  #pull() {
+    this.#scheduled = false;
+    const next = this.#binding.store.get(this.#binding.code);
+    if (this.#destroyed || typeof next !== "string") {
+      return;
+    }
+    if (this.#view.composing) {
+      this.#deferred = true;
+      return;
+    }
+    this.#deferred = false;
+    if (next !== this.#synced && !shows(this.#view.state, next)) {
+      this.#pulling = true;
+      try {
+        replaceCode(this.#view, next);
+      } finally {
+        this.#pulling = false;
+      }
+    }
+    this.#synced = next;
+  }
+
+  /** Pull once after the current update, however many changes arrive. */
+  #schedule() {
+    if (!this.#scheduled) {
+      this.#scheduled = true;
+      queueMicrotask(() => this.#pull());
+    }
+  }
+}
+
+/**
+ * The cell code an editor state represents.
+ *
+ * With a language adapter, this is the adapter's Python for the editor text.
+ */
+function codeOf(state: EditorState): string {
+  const text = state.doc.toString();
+  const adapter = state.field(languageAdapterState, false);
+  return adapter
+    ? adapter.transformOut(
+        text,
+        state.field(languageMetadataField, false) ?? {},
+      )[0]
+    : text;
+}
+
+/**
+ * Whether an editor state shows the given cell code.
+ *
+ * An adapter can spell the same code more than one way, such as `mo.md("hi")`
+ * and its canonical form, so a state shows code that reads into its text and
+ * metadata as well as the code its own spelling produces.
+ */
+function shows(state: EditorState, code: string): boolean {
+  if (codeOf(state) === code) {
+    return true;
+  }
+  const adapter = state.field(languageAdapterState, false);
+  if (!adapter) {
+    return false;
+  }
+  const [text, , metadata] = adapter.transformIn(code);
+  return (
+    text === state.doc.toString() &&
+    dequal(metadata, state.field(languageMetadataField, false))
+  );
+}
+
+/**
+ * Whether an update could change the code an editor represents.
+ *
+ * Language metadata, such as an SQL cell's output name, changes the code
+ * without changing the text.
+ */
+function changesCode(update: ViewUpdate): boolean {
+  return (
+    update.docChanged ||
+    update.state.field(languageAdapterState, false) !==
+      update.startState.field(languageAdapterState, false) ||
+    update.state.field(languageMetadataField, false) !==
+      update.startState.field(languageMetadataField, false)
+  );
+}
+
+/**
+ * Show cell code in the language it implies.
+ *
+ * The language switch happens first, in its own transactions, and clears undo
+ * history because its entries edit the previous language's text. The text and
+ * metadata follow in one remote transaction that undo history leaves out. An
+ * SQL dialect depends on the engine in the metadata, so it is set again after.
+ */
+function replaceCode(view: EditorView, code: string) {
+  let text = code;
+  const effects: StateEffect<unknown>[] = [];
+  let sql = false;
+  const adapter = view.state.field(languageAdapterState, false);
+  if (adapter) {
+    const target = languageAdapterFromCode(code);
+    sql = target.type === "sql";
+    if (target.type !== adapter.type) {
+      switchLanguage(view, { language: target.type, keepCodeAsIs: true });
+    }
+    const [inner, , metadata] = target.transformIn(code);
+    text = inner;
+    if (!dequal(metadata, view.state.field(languageMetadataField, false))) {
+      effects.push(setLanguageMetadata.of(metadata));
+    }
+  }
+  const current = view.state.doc.toString();
+  if (current === text && effects.length === 0) {
+    return;
+  }
+  view.dispatch({
+    changes: changesBetween(current, text),
+    effects,
+    annotations: [
+      Transaction.remote.of(true),
+      Transaction.addToHistory.of(false),
+    ],
+  });
+  if (sql && effects.length > 0) {
+    initializeSQLDialect(view);
+  }
+}
+
+/** The changes that turn one text into another, one per edited range. */
+function changesBetween(from: string, to: string): ChangeSpec {
+  return diff(from, to, { scanLimit: SCAN_LIMIT }).map((change) => ({
+    from: change.fromA,
+    to: change.toA,
+    insert: to.slice(change.fromB, change.toB),
+  }));
+}

package/src/core/document/index.ts

@@ -6,5 +6,7 @@ export type {
   DocumentEditor,
   DocumentHost,
   DocumentModel,
-  DocumentSyncState,
+  DocumentSyncStatus,
+  EditableCell,
+  EditableDocument,
 } from "./model";

package/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,
   };

package/src/core/document/select.ts

@@ -0,0 +1,41 @@
+/* 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);
+}
+
+/** Select one field of a cell, unchanged until that field's value changes. */
+export function selectCellField<K extends keyof EditableCell>(
+  document: Atom<EditableDocument | null>,
+  id: Protocol.CellId,
+  field: K,
+): Atom<EditableCell[K] | undefined> {
+  return selectAtom(document, (value) => value?.cells.get(id)?.[field], dequal);
+}

package/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,