@marimo-team/islands 0.25.3-dev92 → 0.25.3-dev94

package/dist/{useLifecycle-VVmz_24o.js → useLifecycle-Dum8WSXq.js}

@@ -4,7 +4,7 @@ import { t as i } from "./react-sHtZdjeP.js";
 import { t as a } from "./compiler-runtime-CldRdSsv.js";
 import { h as o } from "./tooltip-CKO1pHJo.js";
 import { t as s } from "./jsx-runtime-3BD1kT0s.js";
-import { E as c, w as l } from "./useTheme-DympCsQg.js";
+import { E as c, w as l } from "./useTheme-CfeaVw5D.js";
 var u = o("calendar", [
 	["path", {
 		d: "M8 2v4",

package/dist/{useTheme-DympCsQg.js → useTheme-CfeaVw5D.js}

@@ -562,7 +562,7 @@ function Ie(e, t) {
 	let n = (0, C.c)(5), r = V(), i, a;
 	n[0] !== e || n[1] !== t || n[2] !== r ? (i = () => {
 		let n = r.get(e);
-		r.sub(e, () => {
+		return r.sub(e, () => {
 			let i = r.get(e);
 			t(i, n), n = i;
 		});

package/dist/{vega-component-B8IjMdad.js → vega-component-DgytCKrL.js}

@@ -3,19 +3,19 @@ import { g as t, h as n, m as r, o as i } from "./button-BxB3RDjN.js";
 import { t as a } from "./react-sHtZdjeP.js";
 import { t as o } from "./compiler-runtime-CldRdSsv.js";
 import { t as s } from "./tooltip-CKO1pHJo.js";
-import { C as c, a as l } from "./toDate-C6BRw8i5.js";
+import { C as c, a as l } from "./toDate-DKH0_kMo.js";
 import { t as u } from "./jsx-runtime-3BD1kT0s.js";
 import { n as d } from "./error-banner-Sl2FlSJ4.js";
 import { t as f } from "./debounce-C3jyATpc.js";
-import { A as p, n as ee } from "./useTheme-DympCsQg.js";
+import { A as p, n as ee } from "./useTheme-CfeaVw5D.js";
 import { c as m, t as h } from "./arrays-R6JsImiT.js";
 import { t as te } from "./objects-DCmMvZtn.js";
-import { t as ne } from "./useAsyncData-ChgNtdmE.js";
-import { a as g, i as re, n as ie, t as ae } from "./formats-ZmooA-MD.js";
+import { t as ne } from "./useAsyncData-D0mLJstx.js";
+import { a as g, i as re, n as ie, t as ae } from "./formats-V8ifA0Bk.js";
 import { D as oe, n as _ } from "./vega-loader.browser-B9Pz0EGP.js";
 import { t as se } from "./react-vega-C4T9Rb_w.js";
 import { a as ce, n as le } from "./loader-Bm8cy3e8.js";
-import { t as ue } from "./useDeepCompareMemoize-Bet7kSsI.js";
+import { t as ue } from "./useDeepCompareMemoize-BpPWi3G3.js";
 import { t as v } from "./semaphore-89jsoHtS.js";
 import { t as de } from "./use-vega-container-remeasure-Bz4PZMtt.js";
 //#region src/plugins/impl/vega/fix-relative-url.ts

package/dist/{vennDiagram-4TSXK5OY-D36Zk7t-.js → vennDiagram-4TSXK5OY-eJOrTqqC.js}

@@ -3,7 +3,7 @@ import { t } from "./src-CA_m4ONl.js";
 import { n } from "./chunk-Y2CYZVJY-DKKS1VyV.js";
 import { $ as r, H as i, K as a, U as o, a as s, b as c, c as l, et as u, f as d, nt as f, tt as p, v as m, w as h, y as g } from "./chunk-DU6HZSFF-BwiyaNpg.js";
 import { t as _ } from "./rough.esm-CtV9AnV1.js";
-import { p as v } from "./mermaid-DKI0869I.js";
+import { p as v } from "./mermaid-B0fXpsNP.js";
 //#region ../node_modules/.pnpm/khroma@2.1.0/node_modules/khroma/dist/methods/transparentize.js
 var y = (e, t) => p(e, "a", -t), b = 1e-10;
 function x(e, t) {

package/dist/{wardleyDiagram-VM6X3IG4-BLBolvyQ.js → wardleyDiagram-VM6X3IG4-TILPvee6.js}

@@ -2,7 +2,7 @@ import { i as e } from "./chunk-75Z2AOVW-D7gxIs2Q.js";
 import { n as t } from "./src-CA_m4ONl.js";
 import { n } from "./chunk-Y2CYZVJY-DKKS1VyV.js";
 import { D as r, H as i, K as a, U as o, a as s, b as c, c as l, v as u, w as d, x as f, y as p } from "./chunk-DU6HZSFF-BwiyaNpg.js";
-import { p as m } from "./mermaid-DKI0869I.js";
+import { p as m } from "./mermaid-B0fXpsNP.js";
 import { n as h } from "./mermaid-parser.core-DxuSfYwJ.js";
 import { t as g } from "./chunk-JWPE2WC7-DJvv1t8U.js";
 //#region ../node_modules/.pnpm/mermaid@11.17.2/node_modules/mermaid/dist/chunks/mermaid.core/wardleyDiagram-VM6X3IG4.mjs

package/dist/{xychartDiagram-S5SC5T6Z-CfH57l0v.js → xychartDiagram-S5SC5T6Z-DUPvRwwJ.js}

@@ -9,7 +9,7 @@ import { n as s } from "./chunk-Y2CYZVJY-DKKS1VyV.js";
 import { D as c, H as l, K as u, U as d, a as f, b as p, c as m, f as h, v as g, w as _, y as v, z as y } from "./chunk-DU6HZSFF-BwiyaNpg.js";
 import "./chunk-PWAF6VOD-CQw5qATZ.js";
 import { t as b } from "./chunk-GMAD6QVW-BhaJx0X3.js";
-import { p as x } from "./mermaid-DKI0869I.js";
+import { p as x } from "./mermaid-B0fXpsNP.js";
 //#region ../node_modules/.pnpm/d3-scale@4.0.2/node_modules/d3-scale/src/band.js
 function S() {
 	var e = t().unknown(void 0), r = e.domain, i = e.range, o = 0, s = 1, c, l, u = !1, d = 0, f = 0, p = .5;

package/package.json

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

package/src/components/datasources/__tests__/table-list.test.tsx

@@ -0,0 +1,118 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { render, screen, waitFor } from "@testing-library/react";
+import { Provider } from "jotai";
+import type React from "react";
+import { describe, expect, it } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import type { SQLTableContext } from "@/core/datasets/data-source-connections";
+import { PreviewSQLTableList } from "@/core/datasets/request-registry";
+import type { SQLTableListPreview } from "@/core/kernel/messages";
+import type { RequestId } from "@/core/network/DeferredRequestRegistry";
+import { requestClientAtom } from "@/core/network/requests";
+import { store } from "@/core/state/jotai";
+import { TableList } from "../datasources";
+
+const wrapper = ({ children }: { children: React.ReactNode }) => (
+  <Provider store={store}>{children}</Provider>
+);
+
+const sqlTableContext: SQLTableContext = {
+  engine: "my_engine",
+  database: "my_db",
+  schema: "public",
+  dialect: "postgres",
+  schemaPath: ["public"],
+};
+
+// The kernel answers table-list requests over the websocket, so the mock
+// settles the deferred request instead of returning the response directly.
+function renderDeferredTableList(settle?: (requestId: RequestId) => void) {
+  const client = MockRequestClient.create();
+  client.previewSQLTableList.mockImplementation(async ({ requestId }) => {
+    settle?.(requestId);
+    return null;
+  });
+  store.set(requestClientAtom, client);
+  render(
+    <TableList
+      tables={[]}
+      tablesResolved={false}
+      sqlTableContext={sqlTableContext}
+    />,
+    { wrapper },
+  );
+  return client;
+}
+
+describe("TableList deferred discovery", () => {
+  it("shows the error when the request rejects", async () => {
+    renderDeferredTableList((requestId) =>
+      PreviewSQLTableList.reject(requestId, new Error("engine offline")),
+    );
+
+    expect(screen.getByText("Loading tables...")).toBeInTheDocument();
+
+    await waitFor(() => {
+      expect(screen.getByText("engine offline")).toBeInTheDocument();
+    });
+    expect(screen.queryByText("Loading tables...")).toBeNull();
+  });
+
+  it("shows the error when the response has no tables field", async () => {
+    renderDeferredTableList((requestId) =>
+      PreviewSQLTableList.resolve(requestId, {} as SQLTableListPreview),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("No tables available")).toBeInTheDocument();
+    });
+    expect(screen.queryByText("Loading tables...")).toBeNull();
+  });
+
+  it("shows the empty state for an empty table list", async () => {
+    renderDeferredTableList((requestId) =>
+      PreviewSQLTableList.resolve(requestId, {
+        tables: [],
+      } as unknown as SQLTableListPreview),
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText("No tables found")).toBeInTheDocument();
+    });
+    expect(screen.queryByText("Loading tables...")).toBeNull();
+  });
+
+  it("requests the table list with the table context and waits for the kernel", async () => {
+    let pendingRequestId: RequestId | undefined;
+    const client = renderDeferredTableList((requestId) => {
+      pendingRequestId = requestId;
+    });
+
+    await waitFor(() => {
+      expect(client.previewSQLTableList).toHaveBeenCalledTimes(1);
+    });
+    expect(client.previewSQLTableList).toHaveBeenCalledWith(
+      expect.objectContaining({
+        engine: "my_engine",
+        database: "my_db",
+        schema: "public",
+        schemaPath: ["public"],
+      }),
+    );
+    expect(screen.getByText("Loading tables...")).toBeInTheDocument();
+
+    // Settle the request so the process-wide registry does not keep the entry.
+    expect(pendingRequestId).toBeDefined();
+    PreviewSQLTableList.resolve(
+      pendingRequestId as RequestId,
+      {
+        tables: [],
+      } as unknown as SQLTableListPreview,
+    );
+    await waitFor(() => {
+      expect(screen.queryByText("Loading tables...")).toBeNull();
+    });
+    expect(PreviewSQLTableList.requests.size).toBe(0);
+  });
+});

package/src/components/datasources/datasources.tsx

@@ -702,7 +702,40 @@ const SchemaNode: React.FC<SchemaNodeProps> = (props) => {
   );
 };
 
-const TableList: React.FC<{
+// Kept outside the component because the React Compiler does not yet
+// support try/finally inside component bodies.
+async function loadTableList(
+  sqlTableContext: SQLTableContext,
+  addTableList: ReturnType<typeof useDataSourceActions>["addTableList"],
+  setLoading: (loading: boolean) => void,
+) {
+  setLoading(true);
+  try {
+    const { engine, database, schema, schemaPath } = sqlTableContext;
+    const previewTableList = await PreviewSQLTableList.request({
+      engine: engine,
+      database: database,
+      schema: schema,
+      schemaPath: schemaPath ?? [],
+    });
+
+    if (!previewTableList?.tables) {
+      throw new Error("No tables available");
+    }
+
+    addTableList({
+      tables: previewTableList.tables,
+      sqlTableContext: sqlTableContext,
+    });
+  } finally {
+    setLoading(false);
+  }
+}
+
+/**
+ * This is exported for testing purposes only.
+ */
+export const TableList: React.FC<{
   tables: DataTable[];
   sqlTableContext?: SQLTableContext;
   searchValue?: string;
@@ -731,26 +764,7 @@ const TableList: React.FC<{
   // resets tablesResolved to false).
   const { isPending, error } = useAsyncData(async () => {
     if (!tablesResolved && sqlTableContext) {
-      setTablesLoading(true);
-
-      const { engine, database, schema, schemaPath } = sqlTableContext;
-      const previewTableList = await PreviewSQLTableList.request({
-        engine: engine,
-        database: database,
-        schema: schema,
-        schemaPath: schemaPath ?? [],
-      });
-
-      if (!previewTableList?.tables) {
-        setTablesLoading(false);
-        throw new Error("No tables available");
-      }
-
-      addTableList({
-        tables: previewTableList.tables,
-        sqlTableContext: sqlTableContext,
-      });
-      setTablesLoading(false);
+      await loadTableList(sqlTableContext, addTableList, setTablesLoading);
     }
   }, [tablesResolved, sqlTableContext]);
 

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

@@ -0,0 +1,322 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import {
+  acknowledge,
+  createCell,
+  deleteCell,
+  type Draft,
+  type EditableCell,
+  editCell,
+  EMPTY_DRAFT,
+  setOrder,
+  toChanges,
+  viewDocument,
+} from "../draft";
+import { cell, CONFIG, document, withCells } from "./fixtures";
+
+const confirmed = document();
+
+function edits(...steps: Parameters<typeof editCell>[3][]): Draft {
+  return steps.reduce(
+    (draft, edit) => editCell(confirmed, draft, "c1", edit),
+    EMPTY_DRAFT,
+  );
+}
+
+describe("editCell", () => {
+  it("lets later fields win and merges config field by field", () => {
+    const draft = edits(
+      { code: "a", config: { hide_code: true } },
+      { name: "n", config: { column: 1, hide_code: undefined } },
+    );
+    expect(viewDocument(confirmed, draft).cells.get("c1")).toEqual({
+      id: "c1",
+      code: "a",
+      name: "n",
+      config: { ...CONFIG, hide_code: true, column: 1 },
+    });
+  });
+
+  it("keeps a reversal to the confirmed value as a draft", () => {
+    const draft = edits({ code: "local" }, { code: "x = 1" });
+    const remote = withCells(confirmed, { c1: cell("c1", "earlier edit") });
+    expect(viewDocument(remote, draft).cells.get("c1")?.code).toBe("x = 1");
+  });
+
+  it("accepts empty strings, false and null while ignoring undefined", () => {
+    const draft = edits(
+      { code: "", config: { column: 1, disabled: true } },
+      {
+        code: undefined,
+        config: { column: null, disabled: false, hide_code: undefined },
+      },
+    );
+    expect(viewDocument(confirmed, draft).cells.get("c1")).toEqual({
+      id: "c1",
+      code: "",
+      name: "_",
+      config: CONFIG,
+    });
+  });
+});
+
+describe("createCell and deleteCell", () => {
+  it("fills protocol defaults and places the cell in the view", () => {
+    const atEnd = createCell(EMPTY_DRAFT, { id: "c3", code: "3" });
+    const after = createCell(
+      EMPTY_DRAFT,
+      { id: "c3", code: "3" },
+      { after: "c1" },
+    );
+    const before = createCell(
+      EMPTY_DRAFT,
+      { id: "c3", code: "3" },
+      { before: "c1" },
+    );
+    const orphan = createCell(
+      EMPTY_DRAFT,
+      { id: "c3", code: "3" },
+      { after: "gone" },
+    );
+    expect(viewDocument(confirmed, atEnd).order).toEqual(["c1", "c2", "c3"]);
+    expect(viewDocument(confirmed, after).order).toEqual(["c1", "c3", "c2"]);
+    expect(viewDocument(confirmed, before).order).toEqual(["c3", "c1", "c2"]);
+    expect(viewDocument(confirmed, orphan).order).toEqual(["c1", "c2", "c3"]);
+    expect(viewDocument(confirmed, atEnd).cells.get("c3")).toEqual({
+      id: "c3",
+      code: "3",
+      name: "_",
+      config: CONFIG,
+    });
+  });
+
+  it("forgets a created cell when it is deleted", () => {
+    const draft = deleteCell(
+      createCell(EMPTY_DRAFT, { id: "c3", code: "" }),
+      "c3",
+    );
+    expect(toChanges(confirmed, draft)).toEqual([]);
+    expect(viewDocument(confirmed, draft).order).toEqual(["c1", "c2"]);
+  });
+});
+
+describe("viewDocument", () => {
+  it("preserves withheld source separately from an empty cell", () => {
+    const hidden = cell("c1", "", { code: null });
+    const empty = cell("c2", "");
+    const source = withCells(confirmed, { c1: hidden, c2: empty });
+    expect(viewDocument(source, EMPTY_DRAFT)).toEqual({
+      order: ["c1", "c2"],
+      cells: new Map([
+        ["c1", hidden],
+        ["c2", empty],
+      ]),
+    });
+    expect(toChanges(source, EMPTY_DRAFT)).toEqual([]);
+  });
+
+  it("follows the host for untouched fields, cells and order", () => {
+    const draft = edits({ code: "local", config: { hide_code: true } });
+    const remote = withCells(
+      confirmed,
+      {
+        c1: cell("c1", "remote", {
+          name: "renamed",
+          config: { ...CONFIG, disabled: true },
+          version: 2,
+        }),
+        c2: cell("c2", "remote too"),
+      },
+      ["c2", "c1"],
+    );
+    expect(viewDocument(remote, draft)).toEqual({
+      order: ["c2", "c1"],
+      cells: new Map<string, EditableCell | undefined>([
+        [
+          "c1",
+          {
+            id: "c1",
+            code: "local",
+            name: "renamed",
+            config: { ...CONFIG, disabled: true, hide_code: true },
+          },
+        ],
+        ["c2", remote.cells.get("c2")],
+      ]),
+    });
+  });
+});
+
+describe("toChanges", () => {
+  it.each([{ name: "renamed" }, { config: { hide_code: true } }])(
+    "withholds the whole request when an edited cell lacks source: %o",
+    (edit) => {
+      const hidden = withCells(confirmed, {
+        c1: cell("c1", "", { code: null }),
+      });
+      const created = createCell(EMPTY_DRAFT, { id: "c3", code: "" });
+      const draft = editCell(hidden, created, "c1", edit);
+      expect(toChanges(hidden, draft)).toBeNull();
+      expect(viewDocument(hidden, draft).cells.get("c1")?.code).toBeNull();
+    },
+  );
+
+  it.each(["replacement", ""])(
+    "uses explicitly supplied source %j when the host withholds it",
+    (code) => {
+      const hidden = withCells(confirmed, {
+        c1: cell("c1", "", { code: null }),
+      });
+      const draft = editCell(hidden, EMPTY_DRAFT, "c1", {
+        name: "renamed",
+        code,
+      });
+      expect(toChanges(hidden, draft)).toEqual([
+        {
+          kind: "put_cell",
+          base_etag: "c1-etag",
+          cell: { id: "c1", code, name: "renamed", config: CONFIG },
+        },
+      ]);
+    },
+  );
+
+  it("can delete and reorder cells without their source", () => {
+    const hidden = withCells(confirmed, {
+      c1: cell("c1", "", { code: null }),
+      c2: cell("c2", "", { code: null }),
+    });
+    expect(toChanges(hidden, deleteCell(EMPTY_DRAFT, "c1"))).toEqual([
+      { kind: "delete_cell", id: "c1", base_etag: "c1-etag" },
+    ]);
+    expect(toChanges(hidden, setOrder(EMPTY_DRAFT, ["c2", "c1"]))).toEqual([
+      { kind: "set_order", base_etag: "order-1", order: ["c2", "c1"] },
+    ]);
+  });
+
+  it("is empty for an empty draft and omits puts that change nothing", () => {
+    expect(toChanges(confirmed, EMPTY_DRAFT)).toEqual([]);
+    expect(
+      toChanges(confirmed, edits({ code: "local" }, { code: "x = 1" })),
+    ).toEqual([]);
+  });
+
+  it("puts the merged cell against the confirmed etag", () => {
+    const draft = edits({ code: "local" });
+    const remote = withCells(confirmed, {
+      c1: cell("c1", "remote", { name: "renamed", etag: "c1-etag-2" }),
+    });
+    expect(toChanges(remote, draft)).toEqual([
+      {
+        kind: "put_cell",
+        base_etag: "c1-etag-2",
+        cell: { id: "c1", code: "local", name: "renamed", config: CONFIG },
+      },
+    ]);
+  });
+
+  it.each([{ after: "c3" }, { before: "c3" }])(
+    "can anchor to a cell created earlier in the request: %o",
+    (placement) => {
+      let draft = createCell(EMPTY_DRAFT, { id: "c3", code: "3" });
+      draft = createCell(draft, { id: "c4", code: "4" }, placement);
+      expect(toChanges(confirmed, draft)).toEqual([
+        {
+          kind: "put_cell",
+          base_etag: null,
+          cell: { id: "c3", code: "3", name: "_", config: CONFIG },
+        },
+        {
+          kind: "put_cell",
+          base_etag: null,
+          cell: { id: "c4", code: "4", name: "_", config: CONFIG },
+          ...placement,
+        },
+      ]);
+    },
+  );
+
+  it.each([{ after: "c2" }, { before: "c2" }])(
+    "omits an anchor deleted earlier in the request: %o",
+    (placement) => {
+      let draft = deleteCell(EMPTY_DRAFT, "c2");
+      draft = createCell(draft, { id: "c3", code: "3" }, placement);
+      expect(toChanges(confirmed, draft)).toEqual([
+        { kind: "delete_cell", id: "c2", base_etag: "c2-etag" },
+        {
+          kind: "put_cell",
+          base_etag: null,
+          cell: { id: "c3", code: "3", name: "_", config: CONFIG },
+        },
+      ]);
+    },
+  );
+
+  it("creates, deletes, then sets the reconciled order", () => {
+    let draft = setOrder(EMPTY_DRAFT, ["c2", "c1"]);
+    draft = createCell(draft, { id: "c3", code: "3" }, { after: "c2" });
+    draft = deleteCell(draft, "c1");
+    expect(toChanges(confirmed, draft)).toEqual([
+      {
+        kind: "put_cell",
+        base_etag: null,
+        cell: { id: "c3", code: "3", name: "_", config: CONFIG },
+        after: "c2",
+      },
+      { kind: "delete_cell", id: "c1", base_etag: "c1-etag" },
+      { kind: "set_order", base_etag: "order-1", order: ["c2", "c3"] },
+    ]);
+  });
+});
+
+describe("acknowledge", () => {
+  it("releases accepted fields independently, keeping later code and config edits", () => {
+    const sent = edits({
+      code: "sent",
+      config: { hide_code: true, column: 1 },
+    });
+    const later = editCell(confirmed, sent, "c1", {
+      code: "typed more",
+      config: { column: 2 },
+    });
+    const remote = withCells(confirmed, {
+      c1: cell("c1", "remote", { config: { ...CONFIG, column: 1 } }),
+    });
+    expect(
+      viewDocument(remote, acknowledge(later, sent)).cells.get("c1"),
+    ).toEqual({
+      id: "c1",
+      code: "typed more",
+      name: "_",
+      config: { ...CONFIG, column: 2 },
+    });
+  });
+
+  it("turns an accepted creation into an edit of only the fields changed since", () => {
+    const sent = createCell(EMPTY_DRAFT, { id: "c3", code: "3" });
+    const later = editCell(confirmed, sent, "c3", { name: "named" });
+    const remote = withCells(confirmed, { c3: cell("c3", "remote code") });
+    expect(toChanges(remote, acknowledge(later, sent))).toEqual([
+      {
+        kind: "put_cell",
+        base_etag: "c3-etag",
+        cell: { id: "c3", code: "remote code", name: "named", config: CONFIG },
+      },
+    ]);
+  });
+
+  it("releases an accepted order but preserves a subsequent reorder", () => {
+    const sent = setOrder(EMPTY_DRAFT, ["c2", "c1"]);
+    const later = setOrder(sent, ["c1", "c2"]);
+    const remote = withCells(confirmed, {}, ["c2", "c1"]);
+    expect(toChanges(remote, acknowledge(sent, sent))).toEqual([]);
+    expect(toChanges(remote, acknowledge(later, sent))).toEqual([
+      {
+        kind: "set_order",
+        base_etag: remote.revision.order_etag,
+        order: ["c1", "c2"],
+      },
+    ]);
+  });
+});

package/src/core/document/__tests__/fixtures.ts

@@ -0,0 +1,92 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { Document } from "../../host/resources/document";
+import type * as Protocol from "@marimo-team/client/protocol";
+
+export const CONFIG: Protocol.CellConfig = {
+  column: null,
+  disabled: false,
+  hide_code: false,
+  expand_output: false,
+};
+
+export function cell(
+  id: Protocol.CellId,
+  code: string,
+  overrides: Partial<Protocol.Cell> = {},
+): Protocol.Cell {
+  return {
+    id,
+    notebook_id: "n1",
+    code,
+    name: "_",
+    config: CONFIG,
+    etag: `${id}-etag`,
+    code_hash: `${id}-hash`,
+    version: 1,
+    ...overrides,
+  };
+}
+
+/** A two-cell document, `c1` then `c2`. */
+export function document(notebookId: Protocol.NotebookId = "n1"): Document {
+  const cells = [
+    cell("c1", "x = 1", { notebook_id: notebookId }),
+    cell("c2", "y = 2", { notebook_id: notebookId }),
+  ];
+  return {
+    revision: {
+      notebook_id: notebookId,
+      order: cells.map((c) => c.id),
+      app_config: { width: "medium" },
+      etag: "document-1",
+      saved_etag: "document-1",
+      order_etag: "order-1",
+      app_config_etag: "config-1",
+      version: 1,
+    },
+    cells: new Map(cells.map((c) => [c.id, c])),
+  };
+}
+
+/** The document with some cells replaced or removed and the order updated. */
+export function withCells(
+  base: Document,
+  changes: Record<Protocol.CellId, Protocol.Cell | null>,
+  order?: readonly Protocol.CellId[],
+): Document {
+  const cells = new Map(base.cells);
+  for (const [id, next] of Object.entries(changes)) {
+    if (next === null) {
+      cells.delete(id);
+    } else {
+      cells.set(id, next);
+    }
+  }
+  const nextOrder = order
+    ? [...order]
+    : [
+        ...base.revision.order.filter((id) => cells.has(id)),
+        ...[...cells.keys()].filter((id) => !base.cells.has(id)),
+      ];
+  const orderChanged =
+    nextOrder.length !== base.revision.order.length ||
+    nextOrder.some((id, index) => id !== base.revision.order[index]);
+  const orderEtag = orderChanged
+    ? `order:${JSON.stringify(nextOrder)}`
+    : base.revision.order_etag;
+  return {
+    revision: {
+      ...base.revision,
+      order: nextOrder,
+      order_etag: orderEtag,
+      version: base.revision.version + 1,
+      etag: JSON.stringify([
+        orderEtag,
+        base.revision.app_config_etag,
+        ...nextOrder.map((id) => cells.get(id)?.etag),
+      ]),
+    },
+    cells,
+  };
+}