@marimo-team/frontend 0.25.3-dev103 → 0.25.3-dev105

package/package.json

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

package/src/core/document/__tests__/hooks.test.tsx

@@ -0,0 +1,386 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { act, render, renderHook } from "@testing-library/react";
+import { atom, createStore, Provider } from "jotai";
+import type { PropsWithChildren } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
+import type { Document } from "../../host/resources/document";
+import {
+  createDocumentModel,
+  DocumentProvider,
+  useCellCode,
+  useCellConfig,
+  useCellName,
+  useCellOrder,
+  useDocumentEdit,
+  useDocumentSync,
+  type DocumentHost,
+} from "..";
+import { cell, CONFIG, document, withCells } from "./fixtures";
+
+type HostEdit = DocumentHost["edit"];
+const lifetimes: AbortController[] = [];
+
+afterEach(() => {
+  act(() => lifetimes.splice(0).forEach((controller) => controller.abort()));
+});
+
+function setup(
+  initial: Document | null = document(),
+  edit: HostEdit = () => new Promise(() => {}),
+) {
+  const store = createStore();
+  const source = atom(initial);
+  const detached = vi.fn();
+  source.onMount = () => detached;
+  const controller = new AbortController();
+  lifetimes.push(controller);
+  const model = createDocumentModel({
+    store,
+    notebook: { documentAtom: source, edit },
+    signal: controller.signal,
+  });
+  const wrapper = ({ children }: PropsWithChildren) => (
+    <Provider store={store}>
+      <DocumentProvider model={model}>{children}</DocumentProvider>
+    </Provider>
+  );
+  return { store, source, model, controller, detached, wrapper };
+}
+
+describe("document hooks", () => {
+  it("flushes edits through the model and aborts work when the session ends", async () => {
+    const accepted = withCells(document(), { c1: cell("c1", "local") });
+    const edit = vi
+      .fn<HostEdit>()
+      .mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        data: { document: accepted.revision, cells: {} },
+      })
+      .mockImplementation(
+        () => new Deferred<Awaited<ReturnType<HostEdit>>>().promise,
+      );
+    const { store, source, wrapper, controller } = setup(document(), edit);
+    const { result, unmount } = renderHook(
+      () => ({
+        code: useCellCode("c1"),
+        edit: useDocumentEdit(),
+        sync: useDocumentSync(),
+      }),
+      { wrapper, reactStrictMode: true },
+    );
+    act(() => result.current.edit((tx) => tx.setCode("c1", "local")));
+    expect(result.current.sync.status).toEqual({ status: "pending" });
+    const { flush, retry } = result.current.sync;
+    await act(async () => {
+      const flushed = flush();
+      // Allow the response to arrive before publishing its confirmation.
+      await Promise.resolve();
+      store.set(source, accepted);
+      await expect(flushed).resolves.toEqual(accepted.revision);
+    });
+    expect(result.current.sync).toEqual({
+      status: { status: "idle" },
+      flush,
+      retry,
+    });
+    expect(result.current.code).toBe("local");
+    act(() => result.current.edit((tx) => tx.setCode("c1", "next")));
+    await act(async () => {
+      const rejected = (async () => {
+        await expect(flush()).rejects.toThrow("session ended");
+      })();
+      await Promise.resolve();
+      unmount();
+      controller.abort(new Error("session ended"));
+      await rejected;
+    });
+    expect(edit).toHaveBeenCalledTimes(2);
+    expect(edit.mock.calls[1][2].signal.aborted).toBe(true);
+  });
+
+  it("publishes compound edits atomically without changing host records", () => {
+    const initial = document();
+    const { store, source, wrapper } = setup(initial);
+    const seen = vi.fn();
+    const { result } = renderHook(
+      () => {
+        const value = {
+          code: useCellCode("c1"),
+          name: useCellName("c1"),
+          config: useCellConfig("c1"),
+          order: useCellOrder(),
+        };
+        seen(value);
+        return { ...value, edit: useDocumentEdit() };
+      },
+      { wrapper },
+    );
+    const edit = result.current.edit;
+    seen.mockClear();
+
+    act(() =>
+      edit((tx) => {
+        tx.setCode("c1", "edited");
+        tx.setName("c1", "renamed");
+        tx.updateConfig("c1", { hide_code: true });
+        tx.setOrder(["c2", "c1"]);
+      }),
+    );
+
+    const expected = {
+      code: "edited",
+      name: "renamed",
+      config: { ...CONFIG, hide_code: true },
+      order: ["c2", "c1"],
+    };
+    expect(result.current).toEqual({ ...expected, edit });
+    expect(seen.mock.calls.length).toBeGreaterThan(0);
+    for (const [value] of seen.mock.calls) {
+      expect(value).toEqual(expected);
+    }
+    expect(store.get(source)).toBe(initial);
+
+    expect(() =>
+      act(() =>
+        edit((tx) => {
+          tx.setCode("c1", "rolled back");
+          tx.deleteCell("missing");
+        }),
+      ),
+    ).toThrow("does not exist");
+    expect(result.current).toEqual({ ...expected, edit });
+  });
+
+  it("subscribes to individual fields and keeps the edit function stable", () => {
+    const { store, source, wrapper } = setup();
+    const onCode = vi.fn();
+    const onName = vi.fn();
+    const onConfig = vi.fn();
+    const onOrder = vi.fn();
+    const onEdit = vi.fn();
+    function Code() {
+      onCode(useCellCode("c1"));
+      return null;
+    }
+    function Name() {
+      onName(useCellName("c1"));
+      return null;
+    }
+    function Config() {
+      onConfig(useCellConfig("c1"));
+      return null;
+    }
+    function Order() {
+      onOrder(useCellOrder());
+      return null;
+    }
+    function Edit() {
+      onEdit(useDocumentEdit());
+      return null;
+    }
+    render(
+      <>
+        <Code />
+        <Name />
+        <Config />
+        <Order />
+        <Edit />
+      </>,
+      { wrapper },
+    );
+    const edit: ReturnType<typeof useDocumentEdit> = onEdit.mock.calls[0][0];
+    const clear = () =>
+      [onCode, onName, onConfig, onOrder, onEdit].forEach((fn) =>
+        fn.mockClear(),
+      );
+    clear();
+
+    act(() => edit((tx) => tx.setCode("c1", "local")));
+    expect(onCode).toHaveBeenCalledWith("local");
+    expect(onName).not.toHaveBeenCalled();
+    expect(onConfig).not.toHaveBeenCalled();
+    expect(onOrder).not.toHaveBeenCalled();
+    expect(onEdit).not.toHaveBeenCalled();
+    clear();
+
+    act(() => edit((tx) => tx.setCode("c2", "other")));
+    expect(
+      [onCode, onName, onConfig, onOrder, onEdit].map((fn) => fn.mock.calls),
+    ).toEqual([[], [], [], [], []]);
+
+    act(() =>
+      store.set(
+        source,
+        withCells(document(), {
+          c1: cell("c1", "remote", {
+            name: "host name",
+            config: { ...CONFIG },
+          }),
+        }),
+      ),
+    );
+    expect(onName).toHaveBeenCalledWith("host name");
+    expect(onCode).not.toHaveBeenCalled();
+    expect(onConfig).not.toHaveBeenCalled();
+    expect(onOrder).not.toHaveBeenCalled();
+    expect(onEdit).not.toHaveBeenCalled();
+    clear();
+
+    act(() =>
+      edit((tx) => {
+        tx.updateConfig("c1", { disabled: true });
+        tx.setOrder(["c2", "c1"]);
+      }),
+    );
+    expect(onConfig).toHaveBeenCalledWith({ ...CONFIG, disabled: true });
+    expect(onOrder).toHaveBeenCalledWith(["c2", "c1"]);
+    expect(onCode).not.toHaveBeenCalled();
+    expect(onName).not.toHaveBeenCalled();
+    expect(onEdit).not.toHaveBeenCalled();
+  });
+
+  it("switches field subscriptions when the cell id changes", () => {
+    const { wrapper } = setup();
+    const { result, rerender } = renderHook(
+      (id) => ({
+        code: useCellCode(id),
+        edit: useDocumentEdit(),
+      }),
+      { wrapper, initialProps: "c1" },
+    );
+    const edit = result.current.edit;
+    rerender("c2");
+    expect(result.current).toEqual({ code: "y = 2", edit });
+    act(() => edit((tx) => tx.setCode("c1", "old subscription")));
+    expect(result.current).toEqual({ code: "y = 2", edit });
+    act(() => edit((tx) => tx.setCode("c2", "new subscription")));
+    expect(result.current).toEqual({ code: "new subscription", edit });
+  });
+
+  it("distinguishes unavailable documents, hidden source, empty code, and deleted cells", () => {
+    const { store, source, wrapper } = setup(null);
+    const { result } = renderHook(
+      () => ({
+        order: useCellOrder(),
+        code: useCellCode("c1"),
+        name: useCellName("c1"),
+        config: useCellConfig("c1"),
+        edit: useDocumentEdit(),
+      }),
+      { wrapper },
+    );
+    const edit = result.current.edit;
+    const absent = {
+      code: undefined,
+      name: undefined,
+      config: undefined,
+      edit,
+    };
+    expect(result.current).toEqual({ ...absent, order: null });
+    const hidden = withCells(document(), {
+      c1: cell("c1", "", { code: null }),
+    });
+    act(() => store.set(source, hidden));
+    expect(result.current).toEqual({
+      code: null,
+      name: "_",
+      config: CONFIG,
+      order: ["c1", "c2"],
+      edit,
+    });
+    act(() => edit((tx) => tx.setCode("c1", "")));
+    expect(result.current.code).toBe("");
+    act(() => store.set(source, null));
+    expect(result.current).toEqual({ ...absent, order: null });
+    act(() => store.set(source, hidden));
+    expect(result.current.code).toBe("");
+    act(() =>
+      edit((tx) => {
+        tx.deleteCell("c1");
+        tx.deleteCell("c2");
+      }),
+    );
+    expect(result.current).toEqual({ ...absent, order: [] });
+  });
+
+  it("preserves drafts across Strict Mode remounts until the session ends", () => {
+    const { wrapper, controller, detached } = setup();
+    const useProbe = () => ({
+      code: useCellCode("c1"),
+      edit: useDocumentEdit(),
+    });
+    const first = renderHook(useProbe, { wrapper, reactStrictMode: true });
+    const edit = first.result.current.edit;
+    act(() => edit((tx) => tx.setCode("c1", "strict mode edit")));
+    expect(first.result.current.code).toBe("strict mode edit");
+    first.unmount();
+    expect(detached).not.toHaveBeenCalled();
+
+    const second = renderHook(useProbe, { wrapper, reactStrictMode: true });
+    expect(second.result.current.code).toBe("strict mode edit");
+    act(() => edit((tx) => tx.setCode("c1", "same session")));
+    expect(second.result.current.code).toBe("same session");
+    second.unmount();
+    controller.abort();
+    expect(detached).toHaveBeenCalledOnce();
+    const callback = vi.fn();
+    edit(callback);
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it("switches reads and edits to the supplied model and store", () => {
+    const first = setup();
+    const second = setup(
+      withCells(document("n2"), {
+        c1: cell("c1", "second source", { notebook_id: "n2" }),
+      }),
+    );
+    const seen = vi.fn();
+    function Probe() {
+      seen({ code: useCellCode("c1"), edit: useDocumentEdit() });
+      return null;
+    }
+    const tree = ({ store, model }: typeof first) => (
+      <Provider store={store}>
+        <DocumentProvider model={model}>
+          <Probe />
+        </DocumentProvider>
+      </Provider>
+    );
+    const { rerender } = render(tree(first));
+    const oldEdit: ReturnType<typeof useDocumentEdit> =
+      seen.mock.calls.at(-1)![0].edit;
+    act(() => oldEdit((tx) => tx.setCode("c1", "first draft")));
+    rerender(tree(second));
+    act(() => first.controller.abort());
+    expect(first.detached).toHaveBeenCalledOnce();
+    const latest: {
+      code: string | null | undefined;
+      edit: ReturnType<typeof useDocumentEdit>;
+    } = seen.mock.calls.at(-1)![0];
+    expect(latest.code).toBe("second source");
+    expect(latest.edit).not.toBe(oldEdit);
+    act(() => latest.edit((tx) => tx.setCode("c1", "second draft")));
+    expect(seen.mock.calls.at(-1)![0].code).toBe("second draft");
+    const stale = vi.fn();
+    oldEdit(stale);
+    expect(stale).not.toHaveBeenCalled();
+    seen.mockClear();
+    act(() =>
+      first.store.set(
+        first.source,
+        withCells(document(), {
+          c1: cell("c1", "stale host"),
+        }),
+      ),
+    );
+    expect(seen).not.toHaveBeenCalled();
+  });
+
+  it("requires a document provider", () => {
+    expect(() => renderHook(useDocumentEdit)).toThrow("DocumentProvider");
+  });
+});

package/src/core/document/hooks.tsx

@@ -0,0 +1,118 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { CellId } from "@marimo-team/client/protocol";
+import { useAtomValue, useSetAtom, useStore } from "jotai";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { cellCodeBinding } from "./codemirror";
+import type { EditableCell } from "./draft";
+import type { DocumentModel } from "./model";
+import { selectCellField, selectOrder } from "./select";
+
+const DocumentContext = createContext<DocumentModel | null>(null);
+
+/**
+ * Expose a session-owned model to React. Construct the model with the same store
+ * as the enclosing Jotai Provider. The session owner controls its AbortSignal;
+ * mounting or unmounting this provider does not change the model's lifetime.
+ *
+ * ```tsx
+ * <Provider store={store}>
+ *   <DocumentProvider model={model}>
+ *     <Editor />
+ *   </DocumentProvider>
+ * </Provider>
+ * ```
+ */
+export function DocumentProvider({
+  model,
+  children,
+}: {
+  model: DocumentModel;
+  children: ReactNode;
+}) {
+  return (
+    <DocumentContext.Provider value={model}>
+      {children}
+    </DocumentContext.Provider>
+  );
+}
+
+function useDocumentModel() {
+  const model = useContext(DocumentContext);
+  if (model === null) {
+    throw new Error("Document hooks require a DocumentProvider");
+  }
+  return model;
+}
+
+/** Null while the document is unavailable; an empty array for an empty document. */
+export function useCellOrder() {
+  const { documentAtom } = useDocumentModel();
+  return useAtomValue(useMemo(() => selectOrder(documentAtom), [documentAtom]));
+}
+
+function useCellField<K extends keyof EditableCell>(id: CellId, field: K) {
+  const { documentAtom } = useDocumentModel();
+  return useAtomValue(
+    useMemo(
+      () => selectCellField(documentAtom, id, field),
+      [documentAtom, id, field],
+    ),
+  );
+}
+
+/** Undefined for an absent cell; null when the host withholds its source. */
+export function useCellCode(id: CellId) {
+  return useCellField(id, "code");
+}
+
+/** Undefined when the cell or document is unavailable. */
+export function useCellName(id: CellId) {
+  return useCellField(id, "name");
+}
+
+/** Undefined when the cell or document is unavailable. */
+export function useCellConfig(id: CellId) {
+  return useCellField(id, "config");
+}
+
+/**
+ * A CodeMirror extension that binds the editor's text to a cell's code.
+ * Stable until the cell id or document model changes.
+ *
+ * ```tsx
+ * const extension = useCellCodeExtension(cellId);
+ * ```
+ */
+export function useCellCodeExtension(id: CellId) {
+  const model = useDocumentModel();
+  const store = useStore();
+  return useMemo(
+    () => cellCodeBinding({ store, model, cellId: id }),
+    [model, store, id],
+  );
+}
+
+/**
+ * A stable edit function. Synchronous callbacks publish atomically or roll back.
+ *
+ * ```ts
+ * const edit = useDocumentEdit();
+ * edit((tx) => tx.setCode(cellId, code));
+ * ```
+ */
+export function useDocumentEdit() {
+  return useSetAtom(useDocumentModel().editAtom);
+}
+
+/**
+ * Sync status and explicit recovery. flush waits for edits, including newer
+ * typing, to reach the confirmed source and returns the revision for Run/Save.
+ * Rejections retain local edits; retry explicitly resubmits them. Requests
+ * with an unknown outcome reuse their original key within the retry window.
+ */
+export function useDocumentSync() {
+  const model = useDocumentModel();
+  const status = useAtomValue(model.syncStatusAtom);
+  return { status, flush: model.flush, retry: model.retry };
+}

package/src/core/document/index.ts

@@ -1,5 +1,15 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+export {
+  DocumentProvider,
+  useCellCode,
+  useCellCodeExtension,
+  useCellConfig,
+  useCellName,
+  useCellOrder,
+  useDocumentEdit,
+  useDocumentSync,
+} from "./hooks";
 export { createDocumentModel } from "./model";
 export type {
   DocumentEdit,

package/src/core/host/__tests__/static.test.ts

@@ -0,0 +1,167 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createNotebookReducer, NotebookEvents } from "@marimo-team/client";
+import * as Protocol from "@marimo-team/client/protocol";
+import { afterEach, assert, describe, expect, it, vi } from "vitest";
+import { document as documentResource } from "../resources/document";
+import {
+  createStaticNotebookBackend,
+  type StaticNotebookSnapshot,
+} from "../static";
+import { fixtureEvents } from "./fixtures";
+
+function snapshot(): StaticNotebookSnapshot {
+  const events = fixtureEvents("notebook-events.sse");
+  const notebook = events.find((event) => event.event === "notebook")?.data
+    .notebook;
+  const document = events.find((event) => event.event === "document")?.data
+    .document;
+  assert(notebook && document);
+  return {
+    notebook,
+    document,
+    cells: events.flatMap((event) =>
+      event.event === "cell" ? [event.data.cell] : [],
+    ),
+  };
+}
+
+const streams: NotebookEvents[] = [];
+afterEach(async () => {
+  const closed = streams.splice(0);
+  closed.forEach((stream) => stream.close());
+  await Promise.all(closed.map((stream) => stream.closed));
+  vi.useRealTimers();
+});
+
+async function read(
+  backend: ReturnType<typeof createStaticNotebookBackend>,
+  cursor?: string,
+) {
+  const stream = new NotebookEvents(backend.transport, { cursor });
+  streams.push(stream);
+  const events: Protocol.EventOutput[] = [];
+  await new Promise<void>((resolve, reject) => {
+    stream.subscribe((event) => {
+      events.push(Protocol.Event.parse(event));
+      if (event.event === "ready") {
+        resolve();
+      }
+    }, reject);
+  });
+  return { stream, events };
+}
+
+describe("static notebook backend", () => {
+  it("supplies a complete document through the normal event reader and reducer", async () => {
+    const source = snapshot();
+    const { stream, events } = await read(createStaticNotebookBackend(source));
+    const reducer = createNotebookReducer({ document: documentResource });
+    const state = events.reduce(reducer.reduce, reducer.initial);
+    expect(events.map((event) => event.event)).toEqual([
+      "notebook",
+      "cell",
+      "cell",
+      "cell",
+      "document",
+      "ready",
+    ]);
+    expect(state.notebook).toEqual({ ...source.notebook, operations: [] });
+    expect(state.resources.document.current).toEqual({
+      revision: source.document,
+      cells: new Map(source.cells.map((cell) => [cell.id, cell])),
+    });
+    expect(stream.status).toBe("connected");
+  });
+
+  it("preserves withheld source and its revision metadata", async () => {
+    const source = snapshot();
+    const cells = source.cells.map((cell) => ({ ...cell, code: null }));
+    const { events } = await read(
+      createStaticNotebookBackend({ ...source, cells }),
+    );
+    expect(
+      events
+        .filter((event) => event.event === "cell")
+        .map((event) => event.data.cell),
+    ).toEqual(cells);
+    expect(
+      events.find((event) => event.event === "document")?.data.document,
+    ).toEqual(source.document);
+  });
+
+  it("serves an empty document as available", async () => {
+    const source = snapshot();
+    const document = { ...source.document, order: [] };
+    const { events } = await read(
+      createStaticNotebookBackend({ ...source, document, cells: [] }),
+    );
+    const reducer = createNotebookReducer({ document: documentResource });
+    expect(
+      events.reduce(reducer.reduce, reducer.initial).resources.document.current,
+    ).toEqual({
+      revision: document,
+      cells: new Map(),
+    });
+  });
+
+  it("keeps independent readers open without polling or reconnecting", async () => {
+    vi.useFakeTimers();
+    const backend = createStaticNotebookBackend(snapshot());
+    const first = await read(backend);
+    const second = await read(backend);
+    first.stream.close();
+    await first.stream.closed;
+    await vi.advanceTimersByTimeAsync(60_000);
+    expect(second.events).toEqual(first.events);
+    expect(second.stream.status).toBe("connected");
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("resets a resume cursor before replaying its snapshot", async () => {
+    const { events } = await read(
+      createStaticNotebookBackend(snapshot()),
+      "previous-10",
+    );
+    expect(events[0]).toEqual({ event: "reset", data: {} });
+    expect(events.at(-1)).toEqual({ event: "ready", id: "static", data: {} });
+  });
+
+  it("advertises no mutations and returns a protocol failure for direct edits", async () => {
+    const backend = createStaticNotebookBackend(snapshot());
+    expect(await backend.client.edit([])).toEqual({
+      ok: false,
+      status: 501,
+      problem: {
+        type: "tag:marimo.io,2026:host/unsupported-operation",
+        title: "Unsupported operation",
+        status: 501,
+        detail: "Static notebooks do not support editing",
+      },
+    });
+  });
+
+  it("respects cancellation before opening, during delivery, and for commands", async () => {
+    const backend = createStaticNotebookBackend(snapshot());
+    const before = new AbortController();
+    before.abort();
+    const open = vi.fn();
+    const message = vi.fn();
+    await backend.transport(
+      { cursor: null, signal: before.signal },
+      { open, message },
+    );
+    expect(open).not.toHaveBeenCalled();
+    expect(message).not.toHaveBeenCalled();
+    await expect(
+      backend.client.edit([], { signal: before.signal }),
+    ).rejects.toBe(before.signal.reason);
+    const during = new AbortController();
+    message.mockImplementation(() => during.abort());
+    await backend.transport(
+      { cursor: null, signal: during.signal },
+      { open, message },
+    );
+    expect(message).toHaveBeenCalledOnce();
+  });
+});

package/src/core/host/backend.ts

@@ -0,0 +1,10 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { NotebookClient, NotebookTransport } from "@marimo-team/client";
+
+/** Events and commands for the same notebook, independent of React or a replica. */
+export interface NotebookBackend {
+  readonly transport: NotebookTransport;
+  /** Method presence is not permission; the notebook advertises its operations. */
+  readonly client: Pick<NotebookClient, "edit">;
+}

package/src/core/host/static.ts

@@ -0,0 +1,70 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type * as Protocol from "@marimo-team/client/protocol";
+import type { NotebookBackend } from "./backend";
+
+/** A document snapshot with its own identity and revision metadata. */
+export interface StaticNotebookSnapshot {
+  readonly notebook: Omit<Protocol.Notebook, "operations">;
+  readonly document: Protocol.Document;
+  readonly cells: readonly Protocol.Cell[];
+}
+
+/**
+ * Serve a document without a server, runtime, or mutation operations.
+ * Callers and readers must treat the snapshot records as immutable.
+ */
+export function createStaticNotebookBackend(
+  snapshot: StaticNotebookSnapshot,
+): NotebookBackend {
+  const frames: Protocol.Event[] = [
+    {
+      event: "notebook",
+      data: { notebook: { ...snapshot.notebook, operations: [] } },
+    },
+    ...snapshot.cells.map((cell): Protocol.CellEvent => ({
+      event: "cell",
+      data: { cell },
+    })),
+    { event: "document", data: { document: snapshot.document } },
+    { event: "ready", id: "static", data: {} },
+  ];
+
+  return {
+    transport: ({ cursor, signal }, { open, message }) =>
+      new Promise((resolve) => {
+        if (signal.aborted) {
+          resolve();
+          return;
+        }
+        // Finishing would ask NotebookEvents to reconnect. A snapshot stays open
+        // until its reader closes, even though there are no more updates.
+        signal.addEventListener("abort", () => resolve(), { once: true });
+        open();
+        if (cursor !== null && !signal.aborted) {
+          message({ event: "reset", data: {} });
+        }
+        for (const frame of frames) {
+          if (signal.aborted) {
+            return;
+          }
+          message(frame);
+        }
+      }),
+    client: {
+      edit: async (_changes, options) => {
+        options?.signal?.throwIfAborted();
+        return {
+          ok: false,
+          status: 501,
+          problem: {
+            type: "tag:marimo.io,2026:host/unsupported-operation",
+            title: "Unsupported operation",
+            status: 501,
+            detail: "Static notebooks do not support editing",
+          },
+        };
+      },
+    },
+  };
+}