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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marimo-team/frontend",
-  "version": "0.25.3-dev101",
+  "version": "0.25.3-dev102",
   "main": "dist/main.js",
   "types": "dist/index.d.ts",
   "type": "module",

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

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