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

package/src/core/document/__tests__/scenario-fixture.ts

@@ -0,0 +1,42 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createStore } from "jotai/vanilla";
+import { test as baseTest, vi } from "vitest";
+import type { Document } from "../../host/resources/document";
+import { createDocumentModel } from "../model";
+import { initialDocument } from "./protocol-fixtures";
+import { createTestNotebook } from "./test-notebook";
+import { createUser } from "./user";
+
+function createSession(initial: Document, controller: AbortController) {
+  const store = createStore();
+  const { notebook, control } = createTestNotebook(store, initial);
+  const model = createDocumentModel({
+    store,
+    notebook,
+    signal: controller.signal,
+  });
+  return {
+    user: createUser(store, model),
+    host: control,
+    notebook,
+    controller,
+  };
+}
+
+export const test = baseTest.extend<{
+  initial: Document;
+  session: ReturnType<typeof createSession>;
+}>({
+  initial: initialDocument(),
+  session: async ({ initial }, provide) => {
+    vi.useFakeTimers({ now: 0 });
+    const controller = new AbortController();
+    try {
+      await provide(createSession(initial, controller));
+    } finally {
+      controller.abort();
+      vi.useRealTimers();
+    }
+  },
+});

package/src/core/document/__tests__/scenarios.test.ts

@@ -0,0 +1,205 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { vi } from "vitest";
+import { test } from "./scenario-fixture";
+
+test("waits for a pause in typing before sending the latest edit", async ({
+  expect,
+  session: { user, host, notebook },
+}) => {
+  user.changeCode("c3", "first");
+  await vi.advanceTimersByTimeAsync(300);
+  user.changeCode("c3", "latest");
+  await vi.advanceTimersByTimeAsync(399);
+  expect(notebook.edit).not.toHaveBeenCalled();
+  await vi.advanceTimersByTimeAsync(1);
+  expect(notebook.edit).toHaveBeenCalledOnce();
+  const request = await host.nextRequest();
+  request.process();
+  request.deliverResponse();
+  host.deliverDocument();
+  await expect(user.sync()).resolves.toEqual(host.document().revision);
+  expect(host.document().cells.get("c3")?.code).toBe("latest");
+});
+
+test.for(["response", "document"] as const)(
+  "preserves newer typing when the %s arrives first",
+  async (first, { expect, session: { user, host, notebook } }) => {
+    user.changeCells({ c3: { code: "sent", config: { hide_code: true } } });
+    const flushed = user.sync();
+    const finished = vi.fn();
+    void flushed.then(finished, () => undefined);
+    const request = await host.nextRequest();
+    request.process();
+    user.changeCode("c3", "still typing");
+
+    const deliver = {
+      response: () => request.deliverResponse(),
+      document: () => host.deliverDocument(),
+    };
+    deliver[first]();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(finished).not.toHaveBeenCalled();
+    expect(notebook.edit).toHaveBeenCalledOnce();
+    expect(user.cell("c3")?.code).toBe("still typing");
+
+    deliver[first === "response" ? "document" : "response"]();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(user.cell("c3")?.code).toBe("still typing");
+    const next = await host.nextRequest();
+    next.process();
+    next.deliverResponse();
+    host.deliverDocument();
+    await expect(flushed).resolves.toEqual(host.document().revision);
+    const expected = {
+      id: "c3",
+      code: "still typing",
+      name: "_",
+      config: {
+        column: null,
+        disabled: false,
+        hide_code: true,
+        expand_output: false,
+      },
+    };
+    expect(user.cell("c3")).toEqual(expected);
+    expect(host.document().cells.get("c3")).toMatchObject(expected);
+    expect(user.status()).toEqual({ status: "idle" });
+
+    host.changeCell("c3", {
+      code: "another writer",
+      config: { hide_code: false },
+    });
+    host.deliverDocument();
+    expect(user.cell("c3")?.code).toBe("another writer");
+    expect(user.cell("c3")?.config.hide_code).toBe(false);
+  },
+);
+
+test("uses a newer confirmed document for edits that have not been sent", async ({
+  expect,
+  session: { user, host },
+}) => {
+  user.changeCode("c3", "local");
+  host.changeCell("c3", { name: "remote name" });
+  host.deliverDocument();
+  const flushed = user.sync();
+  const request = await host.nextRequest();
+  request.process();
+  request.deliverResponse();
+  host.deliverDocument();
+  await expect(flushed).resolves.toEqual(host.document().revision);
+  expect(host.document().cells.get("c3")).toMatchObject({
+    code: "local",
+    name: "remote name",
+  });
+});
+
+test.for(["before reset", "during reset", "after snapshot"] as const)(
+  "recovers across reset when the response arrives %s",
+  async (arrival, { expect, session: { user, host } }) => {
+    user.changeCode("c3", "sent");
+    const flushed = user.sync();
+    const request = await host.nextRequest();
+    request.process();
+    user.changeCode("c3", "newer typing");
+    if (arrival === "before reset") {
+      request.deliverResponse();
+      await vi.advanceTimersByTimeAsync(0);
+    }
+    host.reset();
+    if (arrival === "during reset") {
+      request.deliverResponse();
+      await vi.advanceTimersByTimeAsync(0);
+    }
+    host.changeCell("c1", { code: "unrelated edit" });
+    host.deliverSnapshot();
+    if (arrival === "after snapshot") {
+      await vi.advanceTimersByTimeAsync(0);
+      request.deliverResponse();
+    }
+    expect(user.cell("c3")?.code).toBe("newer typing");
+    const next = await host.nextRequest();
+    next.process();
+    next.deliverResponse();
+    host.deliverDocument();
+    await expect(flushed).resolves.toEqual(host.document().revision);
+    expect(host.document().cells.get("c3")?.code).toBe("newer typing");
+    expect(user.cell("c1")?.code).toBe("unrelated edit");
+    expect(user.status()).toEqual({ status: "idle" });
+
+    host.changeCell("c3", { code: "another writer" });
+    host.deliverDocument();
+    expect(user.cell("c3")?.code).toBe("another writer");
+  },
+);
+
+test.for(["response", "document"] as const)(
+  "does not resurrect a cancelled creation when the %s arrives first",
+  async (first, { expect, session: { user, host } }) => {
+    user.createCell({ id: "new", code: "new cell" });
+    const flushed = user.sync();
+    const creation = await host.nextRequest();
+    user.deleteCell("new");
+    host.changeCell("c1", { code: "unrelated edit" });
+    host.deliverDocument();
+    creation.process();
+    const deliver = {
+      response: () => creation.deliverResponse(),
+      document: () => host.deliverDocument(),
+    };
+    deliver[first]();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(user.cell("new")).toBeUndefined();
+    expect(user.order()).toEqual(["c1", "c3", "k7f2"]);
+    deliver[first === "response" ? "document" : "response"]();
+    const deletion = await host.nextRequest();
+    deletion.process();
+    deletion.deliverResponse();
+    host.deliverDocument();
+    await expect(flushed).resolves.toEqual(host.document().revision);
+    expect(host.document().cells.has("new")).toBe(false);
+    expect(user.cell("new")).toBeUndefined();
+  },
+);
+
+test("releases an edit undone before sending and follows subsequent host changes", async ({
+  expect,
+  session: { user, host, notebook },
+}) => {
+  user.changeCode("c3", "temporary");
+  user.changeCode("c3", "x = 21");
+  expect(user.status()).toEqual({ status: "idle" });
+  await expect(user.sync()).resolves.toEqual(host.document().revision);
+
+  host.changeCell("c3", { code: "another writer" });
+  host.deliverDocument();
+  expect(user.cell("c3")?.code).toBe("another writer");
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(notebook.edit).not.toHaveBeenCalled();
+});
+
+test("flushes edits made while an earlier flush is finishing", async ({
+  expect,
+  session: { user, host, notebook },
+}) => {
+  const original = host.document().revision;
+  const first = user.sync();
+  // Let the first flush drain without awaiting its returned promise.
+  await Promise.resolve();
+  user.changeCode("c3", "new code");
+  const second = user.sync();
+  const settled = vi.fn();
+  void second.then(settled, settled);
+
+  await vi.advanceTimersByTimeAsync(0);
+  expect(notebook.edit).toHaveBeenCalledOnce();
+  expect(settled).not.toHaveBeenCalled();
+  const request = await host.nextRequest();
+  request.process();
+  expect(host.document().cells.get("c3")?.code).toBe("new code");
+  request.deliverResponse();
+  host.deliverDocument();
+  await expect(second).resolves.toEqual(host.document().revision);
+  await expect(first).resolves.toEqual(original);
+});

package/src/core/document/__tests__/submission.test.ts

@@ -25,7 +25,6 @@ function setup() {
     store,
     source,
     ...model,
-    abort: () => controller.abort(),
     submit() {
       const submission = store.set(model.submitAtom);
       if (submission === null) {
@@ -104,106 +103,39 @@ describe("document submissions", () => {
   );
 
   it.each(["response", "stream"] as const)(
-    "preserves later typing when the %s arrives first",
+    "does not notify cell subscribers when the %s acknowledges a superseded draft",
     (first) => {
-      const {
-        store,
-        source,
-        editAtom,
-        cellAtom,
-        changesAtom,
-        submitAtom,
-        submit,
-        settle,
-      } = setup();
+      const { store, source, editAtom, cellAtom, submit, settle } = setup();
       store.set(editAtom, (tx) => {
         tx.setCode("c1", "sent");
-        tx.updateConfig("c1", { hide_code: true });
+        tx.createCell({ id: "c3", code: "new" });
       });
       const sent = submit();
-      store.set(editAtom, (tx) => tx.setCode("c1", "still typing"));
-      const confirmed = withCells(document(), {
-        c1: cell("c1", "sent", {
-          etag: "accepted",
-          config: { ...cell("c1", "").config, hide_code: true },
-        }),
+      store.set(editAtom, (tx) => {
+        tx.setCode("c1", "still typing");
+        tx.deleteCell("c3");
       });
-      const onCell = vi.fn();
-      store.sub(cellAtom("c1"), onCell);
-      const arrivals = {
-        response: () => settle(sent, confirmed),
-        stream: () => store.set(source, confirmed),
-      };
-      arrivals[first]();
-      expect(store.set(submitAtom)).toBeNull();
-      arrivals[first === "response" ? "stream" : "response"]();
-      expect(onCell).not.toHaveBeenCalled();
-      expect(store.get(cellAtom("c1"))?.code).toBe("still typing");
-      expect(store.get(changesAtom)).toEqual([
-        {
-          kind: "put_cell",
-          base_etag: "accepted",
-          cell: {
-            id: "c1",
-            code: "still typing",
-            name: "_",
-            config: confirmed.cells.get("c1")?.config,
-          },
-        },
-      ]);
-      const next = submit();
-      settle(sent, confirmed);
-      expect(store.set(submitAtom)).toBeNull();
-      const updated = withCells(confirmed, {
-        c1: cell("c1", "still typing", {
-          config: confirmed.cells.get("c1")!.config,
-        }),
+      const onCode = vi.fn();
+      const onCreation = vi.fn();
+      const unsubscribeCode = store.sub(cellAtom("c1"), onCode);
+      const unsubscribeCreation = store.sub(cellAtom("c3"), onCreation);
+      const confirmed = withCells(document(), {
+        c1: cell("c1", "sent", { etag: "accepted", version: 2 }),
+        c3: cell("c3", "new"),
       });
-      settle(next, updated);
-      store.set(source, updated);
-      expect(store.get(changesAtom)).toEqual([]);
-    },
-  );
-
-  it.each(["response", "stream"] as const)(
-    "never shows a cancelled creation when the %s arrives first",
-    (first) => {
-      const {
-        store,
-        source,
-        editAtom,
-        cellAtom,
-        orderAtom,
-        changesAtom,
-        submit,
-        settle,
-      } = setup();
-      store.set(editAtom, (tx) => tx.createCell({ id: "c3", code: "new" }));
-      const sent = submit();
-      store.set(editAtom, (tx) => tx.deleteCell("c3"));
-      const onCell = vi.fn();
-      store.sub(cellAtom("c3"), onCell);
-      // An unrelated revision before the creation must not forget the deletion.
-      const intermediate = withCells(document(), { c2: cell("c2", "remote") });
-      store.set(source, intermediate);
-      const confirmed = withCells(intermediate, { c3: cell("c3", "new") });
       const arrivals = {
         response: () => settle(sent, confirmed),
         stream: () => store.set(source, confirmed),
       };
-      arrivals[first]();
-      arrivals[first === "response" ? "stream" : "response"]();
-      expect(onCell).not.toHaveBeenCalled();
-      expect(store.get(orderAtom)).toEqual(["c1", "c2"]);
-      expect(store.get(changesAtom)).toEqual([
-        { kind: "delete_cell", id: "c3", base_etag: "c3-etag" },
-      ]);
-      const deletion = submit();
-      const removed = withCells(confirmed, { c3: null });
-      store.set(source, removed);
-      settle(deletion, removed);
-      settle(sent, confirmed);
-      expect(store.get(changesAtom)).toEqual([]);
+      try {
+        arrivals[first]();
+        arrivals[first === "response" ? "stream" : "response"]();
+        expect(onCode).not.toHaveBeenCalled();
+        expect(onCreation).not.toHaveBeenCalled();
+      } finally {
+        unsubscribeCode();
+        unsubscribeCreation();
+      }
     },
   );
 
@@ -227,36 +159,6 @@ describe("document submissions", () => {
     expect(store.set(submitAtom)).toBeNull();
   });
 
-  it.each(["before reset", "during reset", "after snapshot"] as const)(
-    "confirms a submission across reset when its response arrives %s",
-    (arrival) => {
-      const { store, source, editAtom, cellAtom, submit, settle } = setup();
-      store.set(editAtom, (tx) => tx.setCode("c1", "unsaved"));
-      const sent = submit();
-      const old = withCells(document(), { c1: cell("c1", "unsaved") });
-      store.set(editAtom, (tx) => tx.setCode("c1", "newer typing"));
-      if (arrival === "before reset") {
-        settle(sent, old);
-      }
-      store.set(source, null);
-      if (arrival === "during reset") {
-        settle(sent, old);
-      }
-      const fresh = withCells(old, { c2: cell("c2", "unrelated") });
-      store.set(source, fresh);
-      if (arrival === "after snapshot") {
-        settle(sent, old);
-      }
-      expect(store.get(cellAtom("c1"))?.code).toBe("newer typing");
-      const retried = submit();
-      const accepted = withCells(fresh, { c1: cell("c1", "newer typing") });
-      settle(retried, accepted);
-      store.set(source, accepted);
-      store.set(source, withCells(accepted, { c1: cell("c1", "remote") }));
-      expect(store.get(cellAtom("c1"))?.code).toBe("remote");
-    },
-  );
-
   it("invalidates submissions when switching notebooks, retaining each draft", () => {
     const { store, source, editAtom, cellAtom, submit, settle } = setup();
     store.set(editAtom, (tx) => tx.setCode("c1", "first"));
@@ -296,51 +198,4 @@ describe("document submissions", () => {
     settle(sent, remote);
     expect(store.set(submitAtom)).toBeNull();
   });
-
-  it("does not treat a response for another notebook as acceptance", () => {
-    const { store, editAtom, settleAtom, submitAtom, submit } = setup();
-    store.set(editAtom, (tx) => tx.setCode("c1", "local"));
-    const sent = submit();
-    expect(() => store.set(settleAtom, sent, document("n2").revision)).toThrow(
-      "another notebook",
-    );
-    expect(store.set(submitAtom)).toBeNull();
-  });
-
-  it("releases an unsent reversal without making a request", () => {
-    const { store, source, editAtom, cellAtom, submitAtom } = setup();
-    store.set(editAtom, (tx) => tx.setCode("c1", "local"));
-    store.set(editAtom, (tx) => tx.setCode("c1", "x = 1"));
-    expect(store.set(submitAtom)).toBeNull();
-    store.set(source, withCells(document(), { c1: cell("c1", "remote") }));
-    expect(store.get(cellAtom("c1"))?.code).toBe("remote");
-  });
-
-  it("stops observing and accepting work after disposal", () => {
-    const {
-      store,
-      source,
-      editAtom,
-      orderAtom,
-      submitAtom,
-      submit,
-      settle,
-      abort,
-    } = setup();
-    store.set(editAtom, (tx) => tx.setCode("c1", "local"));
-    const sent = submit();
-    abort();
-    const onOrder = vi.fn();
-    store.sub(orderAtom, onOrder);
-    const confirmed = withCells(document(), { c1: cell("c1", "local") });
-    store.set(source, confirmed);
-    settle(sent, confirmed);
-    const edit = vi.fn();
-    store.set(editAtom, edit);
-    abort();
-    expect(edit).not.toHaveBeenCalled();
-    expect(onOrder).not.toHaveBeenCalled();
-    expect(store.get(orderAtom)).toBeNull();
-    expect(store.set(submitAtom)).toBeNull();
-  });
 });

package/src/core/document/__tests__/test-host.test.ts

@@ -0,0 +1,92 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import * as Protocol from "@marimo-team/client/protocol";
+import { afterEach, expect, it, vi } from "vitest";
+import { initialDocument, protocolFixture } from "./protocol-fixtures";
+import { createTestHost } from "./test-host";
+
+afterEach(() => vi.useRealTimers());
+
+it("matches the portable host examples for accepted and conflicting edits", () => {
+  const host = createTestHost(initialDocument());
+  const accepted = host.process({
+    notebookId: "n1",
+    idempotencyKey: "accepted",
+    changes: Protocol.EditRequest.parse(protocolFixture("edit.json")).changes,
+  });
+  const expected = Protocol.EditResponse.parse(
+    protocolFixture("edit-response.json"),
+  );
+  expect(accepted.result).toEqual({ ok: true, status: 200, data: expected });
+  expect(accepted.update).toEqual(host.document());
+
+  const rejected = host.process({
+    notebookId: "n1",
+    idempotencyKey: "rejected",
+    changes: Protocol.EditRequest.parse(
+      protocolFixture("edit-conflict-request.json"),
+    ).changes,
+  });
+  const problem = Protocol.Problem.parse(
+    protocolFixture("problems/edit-conflict.json"),
+  );
+  expect(rejected).toEqual({
+    result: {
+      ok: false,
+      status: 409,
+      problem: { ...problem, detail: expect.any(String) },
+    },
+  });
+  expect(host.document().revision).toEqual(expected.document);
+});
+
+it("rejects an entire batch when a later precondition is stale", () => {
+  const initial = initialDocument();
+  const host = createTestHost(initial);
+  const result = host.apply([
+    { kind: "put_cell", base_etag: null, cell: { id: "created", code: "new" } },
+    { kind: "delete_cell", id: "c3", base_etag: "stale" },
+  ]);
+  expect(result).toMatchObject({
+    result: { ok: false, status: 409, problem: { edit: { change: 1 } } },
+  });
+  expect(host.document()).toEqual(initial);
+  expect(result.update).toBeUndefined();
+});
+
+it("keeps successful and rejected receipts tied to their original payload and revision", () => {
+  vi.useFakeTimers({ now: 0 });
+  const host = createTestHost(initialDocument());
+  const request = {
+    notebookId: "n1",
+    idempotencyKey: "original",
+    changes: Protocol.EditRequest.parse(protocolFixture("edit.json")).changes,
+  };
+  const accepted = host.process(request);
+  const stale = {
+    notebookId: "n1",
+    idempotencyKey: "stale",
+    changes: Protocol.EditRequest.parse(
+      protocolFixture("edit-conflict-request.json"),
+    ).changes,
+  };
+  const rejected = host.process(stale);
+  host.apply([
+    { kind: "put_cell", base_etag: "*", cell: { id: "c3", code: "later" } },
+  ]);
+  const latest = host.document();
+  expect(host.process(request)).toEqual({ result: accepted.result });
+  expect(host.process(stale)).toEqual({ result: rejected.result });
+  expect(host.process({ ...request, changes: [] }).result).toMatchObject({
+    ok: false,
+    status: 409,
+  });
+  expect(host.document()).toEqual(latest);
+
+  vi.advanceTimersByTime(300_000);
+  expect(host.process(request).result).toMatchObject({
+    ok: false,
+    status: 409,
+  });
+  expect(host.document()).toEqual(latest);
+});