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

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,

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