@marimo-team/frontend 0.25.3-dev91 → 0.25.3-dev94

package/src/core/document/model.ts

@@ -0,0 +1,395 @@
+/* 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 {
+  acknowledge,
+  type CellEdit,
+  createCell,
+  deleteCell,
+  type Draft,
+  type EditableCell,
+  type EditableDocument,
+  editCell,
+  EMPTY_DRAFT,
+  isEmptyDraft,
+  type Placement,
+  prune,
+  sameCell,
+  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;
+  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 DocumentModel {
+  /** 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>;
+  /** 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
+  >;
+  /** Stop observing the source and invalidate pending work. Safe to repeat. */
+  dispose(): 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));
+}
+
+/** Create once per source and store; the owner must dispose the model. */
+export function createDocumentModel(
+  store: ReturnType<typeof createStore>,
+  source: Atom<Document | null>,
+): DocumentModel {
+  const stateAtom = atom<ModelState>({
+    confirmed: store.get(source),
+    drafts: new Map(),
+    pending: null,
+  });
+  let disposed = false;
+  const documentAtom = atom((get): EditableDocument | null => {
+    const state = get(stateAtom);
+    return state.confirmed === null
+      ? 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
+      ? 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 (disposed || state.confirmed === null) {
+      return;
+    }
+    editing = true;
+    try {
+      const draft = editDocument(
+        state.confirmed,
+        draftOf(state),
+        edit,
+        state.pending?.draft,
+      );
+      if (
+        disposed ||
+        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 (disposed || 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 (
+        disposed ||
+        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 },
+        }),
+      );
+    },
+  );
+
+  return {
+    cellAtom,
+    orderAtom,
+    appConfigAtom,
+    changesAtom,
+    pendingAtom,
+    editAtom,
+    submitAtom,
+    settleAtom,
+    dispose() {
+      if (!disposed) {
+        disposed = true;
+        unsubscribe();
+        store.set(stateAtom, {
+          confirmed: null,
+          drafts: new Map(),
+          pending: null,
+        });
+      }
+    },
+  };
+}
+
+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 (confirmed.cells.has(cell.id) || 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 = 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;
+  }
+}

package/src/core/kernel/__tests__/RuntimeState.test.ts

@@ -25,7 +25,7 @@ describe("RuntimeState", () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
-    mockSendComponentValues = vi.fn((args) => Promise.resolve(null));
+    mockSendComponentValues = vi.fn(() => Promise.resolve(null));
     uiElementRegistry = UIElementRegistry.INSTANCE;
     uiElementRegistry.entries.clear();
 

package/src/core/state/__tests__/jotai.test.tsx

@@ -0,0 +1,108 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, renderHook } from "@testing-library/react";
+import { atom, Provider } from "jotai";
+import type React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { store, useJotaiEffect, waitFor } from "../jotai";
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <Provider store={store}>{children}</Provider>
+);
+
+describe("waitFor function", () => {
+  it("should resolve when the atom satisfies the predicate", async () => {
+    const testAtom = atom(0);
+    store.set(testAtom, 10);
+
+    const result = await waitFor(testAtom, (value) => value === 10);
+    expect(result).toBe(10);
+  });
+
+  it("should resolve when the atom changes to satisfy the predicate", async () => {
+    const testAtom = atom(0);
+
+    setTimeout(() => store.set(testAtom, 15), 5);
+    setTimeout(() => store.set(testAtom, 20), 10);
+
+    const result = await waitFor(testAtom, (value) => value === 20);
+    expect(result).toBe(20);
+  });
+});
+
+describe("useJotaiEffect", () => {
+  it("calls the effect with the new and previous values", () => {
+    const testAtom = atom(0);
+    const effect = vi.fn();
+    renderHook(() => useJotaiEffect(testAtom, effect), { wrapper });
+
+    act(() => store.set(testAtom, 1));
+    act(() => store.set(testAtom, 2));
+
+    expect(effect.mock.calls).toEqual([
+      [1, 0],
+      [2, 1],
+    ]);
+  });
+
+  it("calls only the latest callback after a rerender", () => {
+    const testAtom = atom(0);
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = renderHook(
+      ({ effect }) => useJotaiEffect(testAtom, effect),
+      { initialProps: { effect: first }, wrapper },
+    );
+
+    rerender({ effect: second });
+    act(() => store.set(testAtom, 1));
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it("subscribes once per rerender with an inline callback", () => {
+    const testAtom = atom(0);
+    const calls: number[] = [];
+    const { rerender } = renderHook(
+      () => useJotaiEffect(testAtom, (value) => calls.push(value)),
+      { wrapper },
+    );
+
+    rerender();
+    rerender();
+    act(() => store.set(testAtom, 1));
+
+    expect(calls).toEqual([1]);
+  });
+
+  it("stops listening to the previous atom when the atom changes", () => {
+    const firstAtom = atom(0);
+    const secondAtom = atom(0);
+    const effect = vi.fn();
+    const { rerender } = renderHook(
+      ({ target }) => useJotaiEffect(target, effect),
+      { initialProps: { target: firstAtom }, wrapper },
+    );
+
+    rerender({ target: secondAtom });
+    act(() => store.set(firstAtom, 1));
+    expect(effect).not.toHaveBeenCalled();
+
+    act(() => store.set(secondAtom, 1));
+    expect(effect).toHaveBeenCalledTimes(1);
+  });
+
+  it("unsubscribes on unmount", () => {
+    const testAtom = atom(0);
+    const effect = vi.fn();
+    const { unmount } = renderHook(() => useJotaiEffect(testAtom, effect), {
+      wrapper,
+    });
+
+    unmount();
+    act(() => store.set(testAtom, 1));
+
+    expect(effect).not.toHaveBeenCalled();
+  });
+});

package/src/core/state/jotai.ts

@@ -42,7 +42,7 @@ export function useJotaiEffect<T>(
   const store = useStore();
   useEffect(() => {
     let prevValue = store.get(atom);
-    store.sub(atom, () => {
+    return store.sub(atom, () => {
       const value = store.get(atom);
       effect(value, prevValue);
       prevValue = value;

package/src/core/wasm/bridge.ts

@@ -407,7 +407,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
     return response as Snippets;
   };
 
-  public openFile: EditRequests["openFile"] = async ({ path }) => {
+  public openFile: EditRequests["openFile"] = async () => {
     const url = createShareableLink({
       code: null,
       baseUrl: window.location.origin,
@@ -451,7 +451,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
     return null;
   };
 
-  public sendInstantiate: RunRequests["sendInstantiate"] = async (request) => {
+  public sendInstantiate: RunRequests["sendInstantiate"] = async () => {
     return null;
   };
 

package/src/core/wasm/store.ts

@@ -41,7 +41,7 @@ const urlFileStore: FileStore = {
 };
 
 export const domElementFileStore: FileStore = {
-  saveFile(contents: string) {
+  saveFile(_contents: string) {
     // Do nothing
   },
   readFile() {
@@ -54,7 +54,7 @@ export const domElementFileStore: FileStore = {
 };
 
 const remoteDefaultFileStore: FileStore = {
-  saveFile(contents: string) {
+  saveFile(_contents: string) {
     // Do nothing
   },
   readFile() {
@@ -79,7 +79,7 @@ export const mountConfigFileStore: FileStore = {
 };
 
 const emptyFileStore: FileStore = {
-  saveFile(contents: string) {
+  saveFile(_contents: string) {
     // Do nothing
   },
   readFile() {

package/src/core/wasm/worker/bootstrap.ts

@@ -85,7 +85,7 @@ export class DefaultWasmController implements WasmController {
         packages: [
           "micropip",
           "msgspec",
-          getMarimoWheel(opts.version),
+          getMarimoWheel(),
           "Markdown",
           "pymdown-extensions",
           "narwhals",

package/src/core/wasm/worker/getMarimoWheel.ts

@@ -1,6 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-export function getMarimoWheel(version: string) {
+export function getMarimoWheel() {
   if (import.meta.env.DEV && import.meta.env.VITE_WASM_MARIMO_PREBUILT_WHEEL) {
     return "marimo-base";
   }

package/src/plugins/impl/CodeEditorPlugin.tsx

@@ -71,7 +71,7 @@ const CodeEditorComponent = (props: CodeEditorComponentProps) => {
   });
 
   const handleChange = useEvent((newValue: string) => {
-    setLocalValue((_) => newValue);
+    setLocalValue(newValue);
     if (typeof props.debounce === "number") {
       setValueDebounced(newValue);
     } else if (!props.debounce) {

package/src/plugins/impl/RangeSliderPlugin.tsx

@@ -74,7 +74,6 @@ const RangeSliderComponent = ({
   start,
   stop,
   step,
-  steps,
   debounce,
   orientation,
   showValue,

package/src/plugins/impl/data-explorer/ConnectedDataExplorerComponent.tsx

@@ -47,7 +47,7 @@ const ConnectedDataExplorerComponent = (props: DataTableProps): JSX.Element => {
     // Subscribe to the store
     const unsub = store.sub(chartSpecAtom, () => {
       const value = store.get(chartSpecAtom);
-      const { schema, ...withoutSchema } = value;
+      const { schema: _schema, ...withoutSchema } = value;
       props.setValue(withoutSchema);
     });
 

package/src/plugins/impl/data-explorer/state/reducer.ts

@@ -47,7 +47,7 @@ const { valueAtom: chartSpecAtom, useActions } = createReducerAndAtoms(
     },
     set: (state, next: ChartSpec) => {
       // remove schema
-      const { schema, ...rest } = next;
+      const { schema: _schema, ...rest } = next;
       return { ...state, ...rest };
     },
   },

package/src/plugins/impl/data-frames/DataFramePlugin.tsx

@@ -192,7 +192,6 @@ const EMPTY: Transformations = {
 export const DataFrameComponent = memo(
   ({
     columns,
-    dataframeName,
     pageSize,
     showDownload,
     lazy,

package/src/plugins/impl/panel/PanelPlugin.tsx

@@ -78,7 +78,7 @@ type T = Record<string, unknown>;
 
 // oxlint-disable-next-line typescript/consistent-type-definitions
 type PluginFunctions = {
-  send_to_widget: <T>(req: {
+  send_to_widget: (req: {
     message?: unknown;
     buffers?: unknown;
   }) => Promise<null | undefined>;

package/src/plugins/impl/vega/make-selectable.ts

@@ -219,7 +219,7 @@ function removeSpecificParamsFromNestedSpecs(
     }
 
     if (filteredParams.length === 0) {
-      const { params, ...rest } = spec;
+      const { params: _params, ...rest } = spec;
       return rest as SpecWithParams;
     }
 

package/src/plugins/layout/RoutesPlugin.tsx

@@ -56,7 +56,7 @@ const RoutesComponent = ({
 
   useEffect(() => {
     // Listen for route changes
-    const listener = (e: PopStateEvent | HashChangeEvent) => {
+    const listener = () => {
       handleFindMatch(window.location);
     };
     window.addEventListener("hashchange", listener);

package/src/stories/form-wrapper.stories.tsx

@@ -20,7 +20,7 @@ type Story = StoryObj<typeof FormWrapper>;
 const props: FormWrapperProps<string> = {
   currentValue: "currentValue",
   newValue: "currentValue",
-  setValue: (v) => {
+  setValue: () => {
     toast({
       title: "Form submitted",
     });
@@ -133,7 +133,7 @@ export const Validate: Story = {
         <FormWrapper
           {...props}
           shouldValidate={true}
-          validate={async ({ value }) => {
+          validate={async () => {
             const random = Math.random();
             if (random < 0.8) {
               return `Failed to validate. Random number was ${random}`;