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

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

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

@@ -0,0 +1,247 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createHash } from "node:crypto";
+import type { Result } from "@marimo-team/client";
+import * as Protocol from "@marimo-team/client/protocol";
+import type { Document } from "../../host/resources/document";
+
+export interface EditRequest {
+  readonly notebookId: Protocol.NotebookId;
+  readonly changes: readonly Protocol.Change[];
+  readonly idempotencyKey: string;
+}
+
+interface Outcome {
+  readonly result: Result<Protocol.EditResponseOutput>;
+  /** Only a new commit produces a stream update; replaying a receipt does not. */
+  readonly update?: Document;
+}
+
+const hash = (text: string) =>
+  createHash("sha256").update(text).digest("hex").slice(0, 16);
+
+function record(
+  input: Protocol.CellInput,
+  notebookId: Protocol.NotebookId,
+  version: number,
+): Protocol.Cell {
+  const cell = Protocol.CellInput.parse(input);
+  const config = Protocol.CellConfigInput.parse(cell.config ?? {});
+  const code = cell.code.replace(/\r\n?/g, "\n");
+  const codeHash = hash(code);
+  return {
+    id: cell.id,
+    notebook_id: notebookId,
+    name: cell.name,
+    code,
+    config,
+    code_hash: codeHash,
+    etag: hash(
+      [
+        codeHash,
+        cell.name,
+        ...[
+          config.column,
+          config.disabled,
+          config.hide_code,
+          config.expand_output,
+        ].map((value) => JSON.stringify(value)),
+      ].join("\n"),
+    ),
+    version,
+  };
+}
+
+function rejected(
+  status: number,
+  kind: string,
+  detail: string,
+  edit?: Protocol.Problem["edit"],
+): Outcome {
+  return {
+    result: {
+      ok: false,
+      status,
+      problem: {
+        type: `tag:marimo.io,2026:host/${kind}`,
+        title: kind === "conflict" ? "Conflict" : "Invalid request",
+        detail,
+        status,
+        ...(edit === undefined ? {} : { edit }),
+      },
+    },
+  };
+}
+
+/** An independent implementation of the document edit protocol, without client draft logic. */
+export function createTestHost(initial: Document) {
+  let current = initial;
+  const receipts = new Map<
+    string,
+    {
+      fingerprint: string;
+      result: Result<Protocol.EditResponseOutput>;
+      expiresAt: number;
+    }
+  >();
+
+  function apply(changes: readonly Protocol.Change[]): Outcome {
+    const cells = new Map(current.cells);
+    let order = [...current.revision.order];
+    const touched = new Set<Protocol.CellId>();
+    const version = current.revision.version + 1;
+    const matches = (id: Protocol.CellId, etag: string) =>
+      etag === "*" || current.cells.get(id)?.etag === etag;
+    const conflict = (change: number, id?: Protocol.CellId) =>
+      rejected(409, "conflict", `Edit conflict at change ${change}`, {
+        change,
+        cell: id === undefined ? null : (current.cells.get(id) ?? null),
+        document: current.revision,
+      });
+
+    for (const [index, change] of changes.entries()) {
+      switch (change.kind) {
+        case "put_cell": {
+          const { id } = change.cell;
+          if (change.base_etag === null) {
+            if (current.cells.has(id) || cells.has(id)) {
+              return conflict(index, id);
+            }
+            if (change.after !== undefined && change.before !== undefined) {
+              return rejected(
+                400,
+                "invalid-request",
+                "A cell cannot name both before and after",
+              );
+            }
+            const anchor = change.after ?? change.before;
+            if (anchor !== undefined && !order.includes(anchor)) {
+              return rejected(
+                400,
+                "invalid-request",
+                "The placement anchor does not exist",
+              );
+            }
+            const position =
+              anchor === undefined
+                ? order.length
+                : order.indexOf(anchor) + (change.after === undefined ? 0 : 1);
+            order.splice(position, 0, id);
+          } else if (!cells.has(id) || !matches(id, change.base_etag)) {
+            return conflict(index, id);
+          }
+          cells.set(
+            id,
+            record(change.cell, current.revision.notebook_id, version),
+          );
+          touched.add(id);
+          break;
+        }
+        case "delete_cell":
+          if (!cells.has(change.id) || !matches(change.id, change.base_etag)) {
+            return conflict(index, change.id);
+          }
+          cells.delete(change.id);
+          order = order.filter((id) => id !== change.id);
+          touched.add(change.id);
+          break;
+        case "set_order":
+          if (
+            change.base_etag !== "*" &&
+            change.base_etag !== current.revision.order_etag
+          ) {
+            return conflict(index);
+          }
+          if (
+            change.order.length !== cells.size ||
+            new Set(change.order).size !== cells.size ||
+            change.order.some((id) => !cells.has(id))
+          ) {
+            return rejected(
+              400,
+              "invalid-request",
+              "Order must name every cell exactly once",
+            );
+          }
+          order = [...change.order];
+          break;
+      }
+    }
+
+    for (const [id, cell] of cells) {
+      const previous = current.cells.get(id);
+      if (previous?.etag === cell.etag) {
+        cells.set(id, previous);
+      }
+    }
+    const orderEtag = hash(JSON.stringify(order));
+    const etag = hash(
+      [
+        orderEtag,
+        current.revision.app_config_etag,
+        ...order.map((id) => cells.get(id)!.etag),
+      ].join("\n"),
+    );
+    const changed = etag !== current.revision.etag;
+    if (changed) {
+      current = {
+        revision: {
+          ...current.revision,
+          order,
+          order_etag: orderEtag,
+          etag,
+          version,
+        },
+        cells,
+      };
+    }
+    const versions: Protocol.EditResponseOutput["cells"] = {};
+    for (const id of touched) {
+      const cell = current.cells.get(id);
+      versions[id] =
+        cell === undefined
+          ? null
+          : {
+              etag: cell.etag,
+              code_hash: cell.code_hash,
+              version: cell.version,
+            };
+    }
+    return {
+      result: {
+        ok: true,
+        status: 200,
+        data: { document: current.revision, cells: versions },
+      },
+      ...(changed ? { update: current } : {}),
+    };
+  }
+
+  return {
+    document: () => current,
+    apply,
+    process(request: EditRequest): Outcome {
+      const fingerprint = JSON.stringify([request.notebookId, request.changes]);
+      const receipt = receipts.get(request.idempotencyKey);
+      if (receipt !== undefined && Date.now() < receipt.expiresAt) {
+        return receipt.fingerprint === fingerprint
+          ? { result: receipt.result }
+          : rejected(
+              409,
+              "conflict",
+              "Idempotency key was used for another request",
+            );
+      }
+      const outcome =
+        request.notebookId === current.revision.notebook_id
+          ? apply(request.changes)
+          : rejected(404, "not-found", "Notebook does not exist");
+      receipts.set(request.idempotencyKey, {
+        fingerprint,
+        result: outcome.result,
+        expiresAt: Date.now() + 300_000,
+      });
+      return outcome;
+    },
+  };
+}

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

@@ -0,0 +1,139 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { Result } from "@marimo-team/client";
+import type * as Protocol from "@marimo-team/client/protocol";
+import { atom, type createStore } from "jotai/vanilla";
+import { vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
+import { invariant } from "@/utils/invariant";
+import type { Document } from "../../host/resources/document";
+import type { DocumentHost } from "../model";
+import { createTestHost, type EditRequest } from "./test-host";
+
+export interface PendingRequest extends EditRequest {
+  readonly signal: AbortSignal;
+  process(): void;
+  deliverResponse(): void;
+  loseResponse(): void;
+}
+
+export function createTestNotebook(
+  store: ReturnType<typeof createStore>,
+  initial: Document,
+) {
+  const host = createTestHost(initial);
+  const source = atom<Document | null>(initial);
+  const requests: PendingRequest[] = [];
+  const waiting: Deferred<PendingRequest>[] = [];
+  const documents: Document[] = [];
+  function apply(changes: readonly Protocol.Change[]) {
+    const { result, update } = host.apply(changes);
+    invariant(result.ok, "Another writer's edit was rejected");
+    if (update !== undefined) {
+      documents.push(update);
+    }
+  }
+  const edit = vi.fn<DocumentHost["edit"]>((notebookId, changes, options) => {
+    options.signal.throwIfAborted();
+    const reply = new Deferred<Result<Protocol.EditResponseOutput>>();
+    let outcome: Result<Protocol.EditResponseOutput> | undefined;
+    const abort = () => reply.reject(options.signal.reason);
+    const finish = () => options.signal.removeEventListener("abort", abort);
+    options.signal.addEventListener("abort", abort, { once: true });
+    void reply.promise.then(finish, finish);
+    const request: PendingRequest = {
+      notebookId,
+      changes: structuredClone(changes),
+      idempotencyKey: options.idempotencyKey,
+      signal: options.signal,
+      process() {
+        invariant(outcome === undefined, "Request was already processed");
+        // Cancellation of the client's wait does not roll back a server commit.
+        const processed = host.process(request);
+        outcome = processed.result;
+        if (processed.update !== undefined) {
+          documents.push(processed.update);
+        }
+      },
+      deliverResponse() {
+        invariant(
+          outcome !== undefined,
+          "Process the request before delivering its response",
+        );
+        reply.resolve(outcome);
+      },
+      loseResponse() {
+        reply.reject(new Error("Connection lost"));
+      },
+    };
+    const next = waiting.shift();
+    if (next === undefined) {
+      requests.push(request);
+    } else {
+      next.resolve(request);
+    }
+    return reply.promise;
+  });
+  const notebook = { documentAtom: source, edit } satisfies DocumentHost;
+  return {
+    notebook,
+    control: {
+      document: host.document,
+      nextRequest(): Promise<PendingRequest> {
+        const next = requests.shift();
+        if (next !== undefined) {
+          return Promise.resolve(next);
+        }
+        const deferred = new Deferred<PendingRequest>();
+        waiting.push(deferred);
+        return deferred.promise;
+      },
+      changeCell(
+        id: Protocol.CellId,
+        patch: Partial<Omit<Protocol.CellInput, "id">>,
+      ) {
+        const cell = host.document().cells.get(id);
+        invariant(
+          cell !== undefined && cell.code !== null,
+          `No host source for cell ${id}`,
+        );
+        apply([
+          {
+            kind: "put_cell",
+            base_etag: cell.etag,
+            cell: {
+              ...cell,
+              code: cell.code,
+              ...patch,
+              config: { ...cell.config, ...patch.config },
+            },
+          },
+        ]);
+      },
+      createCell(cell: Protocol.CellInput) {
+        apply([{ kind: "put_cell", base_etag: null, cell }]);
+      },
+      deleteCell(id: Protocol.CellId) {
+        const cell = host.document().cells.get(id);
+        invariant(cell !== undefined, `No host cell ${id}`);
+        apply([{ kind: "delete_cell", id, base_etag: cell.etag }]);
+      },
+      deliverDocument() {
+        const next = documents.shift();
+        invariant(
+          next !== undefined,
+          "No document update is waiting for delivery",
+        );
+        store.set(source, next);
+      },
+      reset() {
+        documents.length = 0;
+        store.set(source, null);
+      },
+      deliverSnapshot() {
+        documents.length = 0;
+        store.set(source, host.document());
+      },
+    },
+  };
+}