A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
Follow the editor's notebook stream with `NotebookEvents` (#11413)
Trevor Manzb0cac46962ac
diff --git a/frontend/src/core/host/__tests__/notebook-client.test.ts b/frontend/src/core/host/__tests__/notebook-client.test.tsindex f76ebe9850..d226ba5cb4 100644--- a/frontend/src/core/host/__tests__/notebook-client.test.ts+++ b/frontend/src/core/host/__tests__/notebook-client.test.ts@@ -1,42 +1,42 @@/* Copyright 2026 Marimo. All rights reserved. */// @vitest-environment jsdom-import { describe, expect, it, vi } from "vitest";+import { type NotebookTransport, StreamStopped } from "@marimo-team/client";import { createStore } from "jotai";-import { ConnectionState } from "../../websocket/types";+import { afterEach, describe, expect, it, vi } from "vitest";import { Deferred } from "@/utils/Deferred";-import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";-import { classifyCloseEvent } from "../../websocket/connection-state";+import { ConnectionState } from "../../websocket/types";+import type { ConnectionStatus } from "../connection";import { createNotebookClient } from "../notebook-client";import { fixtureEvents, fixtureMessages } from "./fixtures";-function notebookMessage(id: string) {- const notebook = {- id,- project_id: "p1",- path: null,- name: id,- operations: [],- updated_at: null,- };- return JSON.stringify({ event: "notebook", data: { notebook } });+/** One connection the fake transport opened. */+interface Attempt {+ readonly cursor: string | null;+ readonly signal: AbortSignal;+ open(): void;+ receive(message: unknown): void;+ /** End the connection so the stream reconnects. */+ drop(): void;+ /** End the stream, with the status the editor shows if the transport has one. */+ stop(status?: ConnectionStatus): void;}-function setup(url: () => string = () => "ws://localhost/ws") {- const events = new EventTarget();- const healthy = new Deferred<void>();- let provider = url;- const urls: URL[] = [];- const transport = {- readyState: WebSocket.CLOSED,- reconnect: vi.fn(() => {- urls.push(new URL(provider()));- }),- close: vi.fn(() => events.dispatchEvent(new CloseEvent("close"))),- send: vi.fn(),- addEventListener: events.addEventListener.bind(events),- removeEventListener: events.removeEventListener.bind(events),- };+function setup() {+ const attempts: Attempt[] = [];+ const transport: NotebookTransport = ({ cursor, signal }, handlers) =>+ new Promise((resolve, reject) => {+ attempts.push({+ cursor,+ signal,+ open: handlers.open,+ receive: handlers.message,+ drop: resolve,+ stop: (status) =>+ reject(new StreamStopped("stopped", { cause: status })),+ });+ signal.addEventListener("abort", () => resolve(), { once: true });+ });const onNotification = vi.fn();const checkHealth = vi.fn(async () => true);const store = createStore();@@ -44,51 +44,64 @@ function setup(url: () => string = () => "ws://localhost/ws") {const client = controller.client;const connect = (signal: AbortSignal) =>controller.connect({- createTransport: (next) => {- provider = next;- return transport;- },- url,+ transport,signal,- waitUntilReady: () => healthy.promise,checkHealth,onNotification: (notification) => onNotification({ data: notification }),- decodeJson: jsonParseWithSpecialChar,- classifyClose: classifyCloseEvent,});+ let next = 0;+ /** Wait for the next connection, and open it. */+ const opened = async () => {+ await vi.waitFor(() => expect(attempts.length).toBeGreaterThan(next));+ const attempt = attempts[next++];+ attempt.open();+ return attempt;+ };return {- events,- healthy,- transport,+ attempts,client,connect,onNotification,store,checkHealth,- urls,- receive: (message: unknown) =>- events.dispatchEvent(- new MessageEvent("message", { data: JSON.stringify(message) }),- ),+ opened,};}+const lifetimes: AbortController[] = [];+function lifetime() {+ const controller = new AbortController();+ lifetimes.push(controller);+ return controller;+}++afterEach(() => {+ lifetimes.splice(0).forEach((controller) => controller.abort());+ vi.useRealTimers();+});++/** Wait out the stream's backoff before it reconnects. */+const backoff = () => vi.advanceTimersByTimeAsync(2000);++const kernelReady = {+ event: "marimo",+ data: { marimo: { op: "kernel-ready", resumed: false } },+};++const notebook = {+ id: "nb/with space",+ project_id: "p1",+ path: null,+ name: "Notebook",+ operations: ["notebook.edit"],+ updated_at: null,+};+describe("NotebookClient lifetime", () => {it("exposes identity and capabilities only after the notebook is ready", async () => {- const { connect, healthy, events, receive, client, store } = setup();- const lifetime = new AbortController();- connect(lifetime.signal);- healthy.resolve();- await healthy.promise;- events.dispatchEvent(new Event("open"));- const notebook = {- id: "nb/with space",- project_id: "p1",- path: null,- name: "Notebook",- operations: ["notebook.edit"],- updated_at: null,- };+ const { connect, opened, client, store } = setup();+ connect(lifetime().signal);+ const { receive } = await opened();receive({ event: "notebook", data: { notebook } });expect(store.get(client.notebookAtom)).toBeNull();receive({ event: "ready", id: "1", data: {} });@@ -101,396 +114,401 @@ describe("NotebookClient lifetime", () => {expect(store.get(client.notebookAtom)?.operations).toEqual([]);receive({ event: "notebook.removed", id: "3", data: { id: notebook.id } });expect(store.get(client.notebookAtom)).toBeNull();- lifetime.abort();});it("rebuilds the replica after a reconnect reset selects a new notebook", async () => {- const notebookId = "n2";- const { connect, events, healthy, urls, receive, client, store } = setup(- () => "ws://localhost/ws?session_id=visitor",- );- const lifetime = new AbortController();- connect(lifetime.signal);- healthy.resolve();- await healthy.promise;- events.dispatchEvent(new Event("open"));- fixtureMessages("notebook-events.sse").forEach(receive);+ vi.useFakeTimers();+ const { connect, opened, client, store } = setup();+ connect(lifetime().signal);+ const first = await opened();+ fixtureMessages("notebook-events.sse").forEach(first.receive);expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n1");- events.dispatchEvent(new CloseEvent("close"));- expect(urls.at(-1)?.searchParams.get("cursor")).toBe("97");+ first.drop();+ await backoff();expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n1");expect(store.get(client.notebookAtom)).toBeNull();- events.dispatchEvent(new Event("open"));- receive({ event: "reset", data: {} });+ const second = await opened();+ expect(second.cursor).toBe("97");+ second.receive({ event: "reset", data: {} });expect(store.get(client.documentAtom)).toBeNull();for (const event of fixtureMessages("notebook-events.sse")) {- receive(- JSON.parse(- JSON.stringify(event).replaceAll('"n1"', JSON.stringify(notebookId)),- ),+ second.receive(+ JSON.parse(JSON.stringify(event).replaceAll('"n1"', '"n2"')),);}- expect(store.get(client.documentAtom)?.revision.notebook_id).toBe(- notebookId,- );+ expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n2");expect(store.get(client.connectionAtom).state).toBe(ConnectionState.OPEN);- expect(store.get(client.notebookAtom)?.id).toBe(notebookId);- lifetime.abort();+ expect(store.get(client.notebookAtom)?.id).toBe("n2");});- it.each(["{broken", JSON.stringify({ event: "ready", data: {} })])(- "stops consuming a malformed host stream: %s",- (data) => {- const { connect, events, client, store, transport, onNotification } =- setup();- const lifetime = new AbortController();- connect(lifetime.signal);- events.dispatchEvent(new Event("open"));- events.dispatchEvent(new MessageEvent("message", { data }));- events.dispatchEvent(- new MessageEvent("message", {- data: JSON.stringify({- event: "marimo",- data: { marimo: { op: "reconnected" } },- }),- }),- );- expect(store.get(client.connectionAtom)).toEqual({- state: ConnectionState.CLOSED,- code: "KERNEL_DISCONNECTED",- reason: "Failed to decode notebook message",+ it.each([+ ["a message that is not an event", "{broken"],+ ["an event from another notebook", "identity"],+ ])("stops consuming a stream on %s", async (_name, message) => {+ const { connect, opened, client, store, onNotification } = setup();+ connect(lifetime().signal);+ const attempt = await opened();+ if (message === "identity") {+ attempt.receive({ event: "notebook", data: { notebook } });+ attempt.receive({+ event: "notebook",+ data: { notebook: { ...notebook, id: "n2" } },});- expect(transport.close).toHaveBeenCalledOnce();- expect(onNotification).not.toHaveBeenCalled();- lifetime.abort();- },- );-- it("resumes from the last cursor until reset or a new session", async () => {- const session = { id: "first", token: "a" };- const { connect, events, healthy, urls, receive } = setup(- () =>- `ws://localhost/ws?session_id=${session.id}&access_token=${session.token}&cursor=999`,- );- const lifetime = new AbortController();- connect(lifetime.signal);- healthy.resolve();- await healthy.promise;- expect(urls[0].searchParams.get("cursor")).toBeNull();-- const snapshot = fixtureMessages("notebook-events.sse");- events.dispatchEvent(new Event("open"));- for (const message of snapshot) {- receive(message);+ } else {+ attempt.receive(message);}- session.token = "b";- events.dispatchEvent(new CloseEvent("close"));- expect(urls[1].searchParams.get("cursor")).toBe("97");- expect(urls[1].searchParams.get("access_token")).toBe("b");-- events.dispatchEvent(new Event("open"));- receive({ event: "reset", data: {} });- events.dispatchEvent(new CloseEvent("close"));- expect(urls[2].searchParams.get("cursor")).toBeNull();-- events.dispatchEvent(new Event("open"));- for (const message of snapshot) {- receive(message);- }- session.id = "second";- events.dispatchEvent(new CloseEvent("close"));- expect(urls[3].searchParams.get("cursor")).toBeNull();- expect(urls[3].searchParams.get("session_id")).toBe("second");- lifetime.abort();+ attempt.receive({+ event: "marimo",+ data: { marimo: { op: "reconnected" } },+ });+ await vi.waitFor(() =>+ expect(store.get(client.connectionAtom).state).toBe(+ ConnectionState.CLOSED,+ ),+ );+ expect(store.get(client.connectionAtom)).toMatchInlineSnapshot(`+ {+ "code": "KERNEL_DISCONNECTED",+ "reason": "Failed to decode notebook message",+ "state": "CLOSED",+ }+ `);+ expect(attempt.signal.aborted).toBe(true);+ expect(onNotification).not.toHaveBeenCalled();});it("exposes the confirmed document until the lifetime ends", async () => {- const { connect, events, client, store, healthy, receive } = setup();- const lifetime = new AbortController();- connect(lifetime.signal);- healthy.resolve();- await healthy.promise;- events.dispatchEvent(new Event("open"));+ vi.useFakeTimers();+ const { connect, opened, client, store } = setup();+ const current = lifetime();+ connect(current.signal);+ const attempt = await opened();const snapshot = fixtureMessages("notebook-events.sse");- for (const message of snapshot.slice(0, -3)) {- receive(message);- }+ snapshot.slice(0, -3).forEach(attempt.receive);expect(store.get(client.documentAtom)).toBeNull();- for (const message of snapshot.slice(-3)) {- receive(message);- }+ snapshot.slice(-3).forEach(attempt.receive);expect(store.get(client.documentAtom)?.revision.order).toEqual(["c1","c3","k7f2",]);- events.dispatchEvent(new CloseEvent("close"));+ attempt.drop();+ await backoff();expect(store.get(client.documentAtom)?.revision.order).toEqual(["c1","c3","k7f2",]);- lifetime.abort();+ current.abort();expect(store.get(client.documentAtom)).toBeNull();});- it("stops consuming a stream whose notebook changes", () => {- const { connect, events, client, store, transport } = setup();- const lifetime = new AbortController();- connect(lifetime.signal);- events.dispatchEvent(new Event("open"));- for (const id of ["n1", "n2"]) {- events.dispatchEvent(- new MessageEvent("message", { data: notebookMessage(id) }),- );- }- expect(store.get(client.connectionAtom)).toEqual({- state: ConnectionState.CLOSED,- code: "KERNEL_DISCONNECTED",- reason: "Failed to decode notebook message",- });- expect(transport.close).toHaveBeenCalledOnce();- lifetime.abort();- });+ it.each([+ ["a malformed native envelope", { event: "marimo", id: "98", data: {} }],+ ["null native event data", { event: "marimo", id: "98", data: null }],+ ["an invalid protocol record", { event: "cell", id: "98", data: {} }],+ ["an undecodable message", "{broken"],+ ["a changed notebook", { event: "notebook", id: "98", data: { notebook } }],+ ])(+ "rebuilds from a fresh snapshot after rejecting %s",+ async (_name, message) => {+ const { connect, opened, client, store, onNotification } = setup();+ connect(lifetime().signal);+ const first = await opened();+ const snapshot = fixtureMessages("notebook-events.sse");+ snapshot.forEach(first.receive);+ expect(store.get(client.documentAtom)).not.toBeNull();+ onNotification.mockClear();- it.each(["MARIMO_UNAUTHORIZED", "MARIMO_TRANSPORT_EXHAUSTED"])(- "stops automatic recovery after %s but permits an explicit reconnect",- async (reason) => {- const {- connect,- client,- store,- events,- transport,- healthy,- checkHealth,- } = setup();- const lifetime = new AbortController();- connect(lifetime.signal);- healthy.resolve();- await healthy.promise;- events.dispatchEvent(new CloseEvent("close", { reason }));- events.dispatchEvent(new Event("error"));- expect(store.get(client.connectionAtom).state).toBe(- ConnectionState.CLOSED,+ first.receive(message);+ first.receive(kernelReady);+ expect({+ connection: store.get(client.connectionAtom),+ document: store.get(client.documentAtom),+ attachments: store.get(client.attachmentsAtom),+ aborted: first.signal.aborted,+ notifications: onNotification.mock.calls,+ }).toEqual({+ connection: {+ state: ConnectionState.CLOSED,+ code: "KERNEL_DISCONNECTED",+ reason: "Failed to decode notebook message",+ },+ document: null,+ attachments: [],+ aborted: true,+ notifications: [],+ });++ await client.reconnect();+ const second = await opened();+ expect(second.cursor).toBeNull();+ snapshot.forEach(second.receive);+ expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n1");+ expect(store.get(client.connectionAtom)).toEqual({+ state: ConnectionState.OPEN,+ });+ },+ );++ it.each([+ [+ "a final close",+ {+ state: ConnectionState.CLOSED,+ code: "KERNEL_DISCONNECTED",+ reason: "not authorized",+ },+ ],+ ["the host giving up", undefined],+ ] as const)(+ "shows the stop after %s and resumes on an explicit reconnect",+ async (_name, status) => {+ const { connect, opened, attempts, client, store, checkHealth } = setup();+ connect(lifetime().signal);+ const first = await opened();+ first.receive({ event: "ready", id: "5", data: {} });+ first.stop(status);+ await vi.waitFor(() =>+ expect(store.get(client.connectionAtom)).toEqual(+ status ?? {+ state: ConnectionState.CLOSED,+ code: "KERNEL_DISCONNECTED",+ reason: "kernel not found",+ },+ ),);- expect(transport.reconnect).toHaveBeenCalledOnce();+ expect(attempts).toHaveLength(1);await client.reconnect();expect(checkHealth).toHaveBeenCalledOnce();- expect(transport.reconnect).toHaveBeenCalledTimes(2);- lifetime.abort();+ expect((await opened()).cursor).toBe("5");},);- it("only resets the automatic retry budget after an open event", () => {- const { connect, events, transport } = setup();- const lifetime = new AbortController();- connect(lifetime.signal);- events.dispatchEvent(new CloseEvent("close"));- events.dispatchEvent(new Event("error"));- events.dispatchEvent(new CloseEvent("close"));- expect(transport.reconnect).toHaveBeenCalledOnce();- events.dispatchEvent(new Event("open"));- events.dispatchEvent(new CloseEvent("close"));- expect(transport.reconnect).toHaveBeenCalledTimes(2);- lifetime.abort();- });-it("does not revive an aborted lifetime when a manual health check finishes", async () => {- const { connect, client, transport, checkHealth } = setup();+ const { connect, opened, attempts, client, checkHealth } = setup();const health = new Deferred<boolean>();checkHealth.mockReturnValue(health.promise);- const lifetime = new AbortController();- connect(lifetime.signal);+ const current = lifetime();+ connect(current.signal);+ const first = await opened();+ first.stop({+ state: ConnectionState.CLOSED,+ code: "KERNEL_DISCONNECTED",+ reason: "",+ });+ await vi.waitFor(() => expect(checkHealth).not.toHaveBeenCalled());const attempt = client.reconnect();- lifetime.abort();+ current.abort();health.resolve(true);await attempt;- expect(transport.reconnect).not.toHaveBeenCalled();+ expect(attempts).toHaveLength(1);});- it("does not connect after abort, even when the health check finishes", async () => {- const { client, connect, healthy, transport } = setup();- const controller = new AbortController();- connect(controller.signal);- controller.abort();- healthy.resolve();- await healthy.promise;- client.reconnect();- expect(transport.reconnect).not.toHaveBeenCalled();- expect(transport.close).toHaveBeenCalledOnce();+ it("discards an interrupted snapshot before a manual reconnect", async () => {+ const { connect, opened, client, store } = setup();+ connect(lifetime().signal);+ const first = await opened();+ const snapshot = fixtureEvents("notebook-events.sse");+ for (const event of snapshot) {+ if (event.event === "ready") {+ break;+ }+ first.receive(event);+ }+ first.stop();+ await vi.waitFor(() =>+ expect(store.get(client.connectionAtom).state).toBe(+ ConnectionState.CLOSED,+ ),+ );++ await client.reconnect();+ const second = await opened();+ expect(second.cursor).toBeNull();+ for (const event of snapshot) {+ if (event.event === "notebook") {+ second.receive(event);+ }+ if (event.event === "document") {+ second.receive({+ ...event,+ data: { document: { ...event.data.document, order: [] } },+ });+ }+ }+ second.receive({ event: "ready", id: "100", data: {} });+ expect({+ connection: store.get(client.connectionAtom),+ order: store.get(client.documentAtom)?.revision.order,+ attachments: store.get(client.attachmentsAtom),+ }).toEqual({+ connection: { state: ConnectionState.OPEN },+ order: [],+ attachments: [],+ });});- it("detaches listeners before closing so cleanup cannot trigger a session retry", () => {- const { connect, client, store, events, transport, onNotification } =- setup();- const controller = new AbortController();- connect(controller.signal);- controller.abort();- events.dispatchEvent(- new MessageEvent("message", {- data: JSON.stringify({ data: { op: "reconnected" } }),- }),- );- expect(transport.reconnect).not.toHaveBeenCalled();+ it("does not connect after abort", async () => {+ const { connect, attempts, client, store } = setup();+ const current = lifetime();+ connect(current.signal);+ current.abort();+ await client.reconnect();+ await new Promise((resolve) => setTimeout(resolve, 10));+ expect(attempts).toHaveLength(0);expect(store.get(client.connectionAtom)).toEqual({state: ConnectionState.NOT_STARTED,});- expect(onNotification).not.toHaveBeenCalled();});- it("can reconnect after effect cleanup without reviving the earlier client attempt", async () => {- const { connect, healthy, transport, events, onNotification } = setup();- const first = new AbortController();+ it("forwards notifications for the current lifetime only", async () => {+ const { connect, opened, onNotification } = setup();+ const first = lifetime();connect(first.signal);+ const earlier = await opened();first.abort();- const second = new AbortController();- connect(second.signal);- healthy.resolve();- await healthy.promise;- expect(transport.reconnect).toHaveBeenCalledOnce();- events.dispatchEvent(- new MessageEvent("message", {- data: JSON.stringify({- event: "marimo",- data: { marimo: { op: "reconnected" } },- }),- }),- );+ connect(lifetime().signal);+ const current = await opened();+ earlier.receive(kernelReady);+ current.receive({+ event: "marimo",+ data: { marimo: { op: "reconnected" } },+ });expect(onNotification).toHaveBeenCalledExactlyOnceWith({data: { op: "reconnected" },});- second.abort();});});-async function open() {- const url = vi.fn(() => "ws://localhost/ws?session_id=first&cursor=999");- const setupResult = setup(url);- const lifetime = new AbortController();- setupResult.connect(lifetime.signal);- setupResult.healthy.resolve();- await setupResult.healthy.promise;- setupResult.events.dispatchEvent(new Event("open"));- return { ...setupResult, lifetime, url };-}-describe("NotebookClient attachments", () => {const [browser, agent] = fixtureEvents("notebook-events.sse").flatMap((event) => (event.event === "attachment" ? [event.data.attachment] : []),);+ async function open() {+ const result = setup();+ result.connect(lifetime().signal);+ return { ...result, attempt: await result.opened() };+ }+it("publishes a complete snapshot and applies live changes independently of kernel readiness", async () => {- const { client, store, receive, lifetime } = await open();+ const { client, store, attempt } = await open();const snapshot = fixtureMessages("notebook-events.sse");const readyIndex = snapshot.findIndex((event) => event.event === "ready");- snapshot.slice(0, readyIndex).forEach(receive);+ snapshot.slice(0, readyIndex).forEach(attempt.receive);expect(store.get(client.attachmentsAtom)).toEqual([]);- snapshot.slice(readyIndex).forEach(receive);+ snapshot.slice(readyIndex).forEach(attempt.receive);expect(store.get(client.attachmentsAtom)).toEqual([browser, agent]);const renamed = { ...agent, name: "Renamed agent" };- receive({ event: "attachment", id: "98", data: { attachment: renamed } });- receive({+ attempt.receive({+ event: "attachment",+ id: "98",+ data: { attachment: renamed },+ });+ attempt.receive({event: "attachment.removed",id: "99",data: { id: browser.id },});expect(store.get(client.attachmentsAtom)).toEqual([renamed]);- receive({ data: { op: "kernel-ready", resumed: false } });+ attempt.receive(kernelReady);expect(store.get(client.attachmentsAtom)).toEqual([renamed]);- receive({ event: "attachment.removed", id: "100", data: { id: agent.id } });- expect(store.get(client.attachmentsAtom)).toEqual([]);- lifetime.abort();- });-- it("resumes attachments alongside an incomplete document and waits for replay ready", async () => {- const { client, store, receive, events, urls, lifetime } = await open();- expect(urls[0].searchParams.has("cursor")).toBe(false);- fixtureMessages("notebook-events.sse").forEach(receive);- const confirmed = store.get(client.documentAtom);- const edits = fixtureMessages("edits.sse");- edits.slice(0, 3).forEach(receive);- const renamed = { ...agent, name: "Renamed agent" };- receive({ event: "attachment", id: "112a", data: { attachment: renamed } });- expect(store.get(client.attachmentsAtom)).toEqual([browser, renamed]);- events.dispatchEvent(new CloseEvent("close"));- expect(store.get(client.attachmentsAtom)).toEqual([]);- expect(urls.at(-1)!.searchParams.get("cursor")).toBe("112a");- events.dispatchEvent(new Event("open"));- expect(store.get(client.attachmentsAtom)).toEqual([]);- expect(store.get(client.documentAtom)).toBe(confirmed);- edits.slice(3).forEach(receive);- receive({+ attempt.receive({event: "attachment.removed",- id: "115",- data: { id: browser.id },+ id: "100",+ data: { id: agent.id },});expect(store.get(client.attachmentsAtom)).toEqual([]);- receive({ event: "ready", id: "116", data: {} });- expect(store.get(client.attachmentsAtom)).toEqual([renamed]);- const revisions = fixtureEvents("edits.sse").flatMap((event) =>- event.event === "document" ? [event.data.document] : [],- );- expect(store.get(client.documentAtom)?.revision).toEqual(revisions.at(-1));- lifetime.abort();});- it("replaces stale attachments with an empty snapshot after reset", async () => {- const { client, store, receive, lifetime } = await open();- fixtureMessages("notebook-events.sse").forEach(receive);- receive({ event: "reset", data: {} });- expect(store.get(client.attachmentsAtom)).toEqual([]);- fixtureMessages("notebook-events.sse")- .filter((event) => event.event !== "attachment")- .forEach(receive);- expect(store.get(client.attachmentsAtom)).toEqual([]);- lifetime.abort();- });+ it.each(["automatic", "manual"])(+ "preserves an incomplete live document across %s reconnect and waits for replay ready",+ async (recovery) => {+ vi.useFakeTimers();+ const { client, store, attempt, opened } = await open();+ expect(attempt.cursor).toBeNull();+ fixtureMessages("notebook-events.sse").forEach(attempt.receive);+ const confirmed = store.get(client.documentAtom);+ const edits = fixtureMessages("edits.sse");+ edits.slice(0, 3).forEach(attempt.receive);+ const renamed = { ...agent, name: "Renamed agent" };+ attempt.receive({+ event: "attachment",+ id: "112a",+ data: { attachment: renamed },+ });+ expect(store.get(client.attachmentsAtom)).toEqual([browser, renamed]);+ if (recovery === "automatic") {+ attempt.drop();+ await backoff();+ } else {+ attempt.stop();+ await vi.advanceTimersByTimeAsync(0);+ await client.reconnect();+ }+ expect(store.get(client.attachmentsAtom)).toEqual([]);+ const replay = await opened();+ expect(replay.cursor).toBe("112a");+ expect(store.get(client.attachmentsAtom)).toEqual([]);+ expect(store.get(client.documentAtom)).toBe(confirmed);+ edits.slice(3).forEach(replay.receive);+ replay.receive({+ event: "attachment.removed",+ id: "115",+ data: { id: browser.id },+ });+ expect(store.get(client.attachmentsAtom)).toEqual([]);+ replay.receive({ event: "ready", id: "116", data: {} });+ expect(store.get(client.attachmentsAtom)).toEqual([renamed]);+ const revisions = fixtureEvents("edits.sse").flatMap((event) =>+ event.event === "document" ? [event.data.document] : [],+ );+ expect(store.get(client.documentAtom)?.revision).toEqual(+ revisions.at(-1),+ );+ },+ );- it.each(["close", "error", "malformed", "removed", "abort", "identity"])(+ it.each(["drop", "stop", "removed", "abort"])("clears presence on %s and ignores messages after disposal",async (reason) => {- const { client, store, receive, events, url, lifetime } = await open();- fixtureMessages("notebook-events.sse").forEach(receive);+ vi.useFakeTimers();+ const current = lifetime();+ const result = setup();+ result.connect(current.signal);+ const { client, store } = result;+ const attempt = await result.opened();+ fixtureMessages("notebook-events.sse").forEach(attempt.receive);expect(store.get(client.attachmentsAtom)).toEqual([browser, agent]);switch (reason) {- case "close":- events.dispatchEvent(- new CloseEvent("close", { reason: "MARIMO_UNAUTHORIZED" }),- );+ case "drop":+ attempt.drop();+ await backoff();break;- case "error":- events.dispatchEvent(new Event("error"));- break;- case "malformed":- receive({ event: "attachment", id: "98", data: {} });+ case "stop":+ attempt.stop({+ state: ConnectionState.CLOSED,+ code: "KERNEL_DISCONNECTED",+ reason: "not authorized",+ });+ await vi.advanceTimersByTimeAsync(0);break;case "removed":- receive({ event: "notebook.removed", id: "98", data: { id: "n1" } });- break;- case "identity":- url.mockReturnValue(- "ws://localhost/api/marimo/v1/notebooks/n2/events/ws",- );- events.dispatchEvent(new CloseEvent("close"));- receive({ event: "ready", id: "98", data: {} });+ attempt.receive({+ event: "notebook.removed",+ id: "98",+ data: { id: "n1" },+ });break;default:- lifetime.abort();+ current.abort();}expect(store.get(client.attachmentsAtom)).toEqual([]);- lifetime.abort();- fixtureMessages("notebook-events.sse").forEach(receive);+ current.abort();+ fixtureMessages("notebook-events.sse").forEach(attempt.receive);expect(store.get(client.attachmentsAtom)).toEqual([]);},);-- it("keeps host resources empty for notification-only WASM connections", async () => {- const { client, store, receive, lifetime } = await open();- receive({ data: { op: "kernel-ready" } });- receive({ data: { op: "reconnected" } });- expect(store.get(client.attachmentsAtom)).toEqual([]);- lifetime.abort();- });});diff --git a/frontend/src/core/host/notebook-client.ts b/frontend/src/core/host/notebook-client.tsindex c30a5e5be5..70e63d49de 100644--- a/frontend/src/core/host/notebook-client.ts+++ b/frontend/src/core/host/notebook-client.ts@@ -1,27 +1,31 @@/* Copyright 2026 Marimo. All rights reserved. */import { Logger } from "@/utils/Logger";+import {+ createNotebookReducer,+ type NotebookEvent,+ NotebookEvents,+ type NotebookTransport,+ StreamStopped,+} from "@marimo-team/client";import type { Attachment, NotebookOutput } from "@marimo-team/client/protocol";-import { createNotebookReducer } from "@marimo-team/client";import { type Atom, atom, type createStore } from "jotai/vanilla";+import { z } from "zod";import {- type ConnectionStatus,- ConnectionState,ConnectionClosedReason,- type CloseDecision,- type NotebookTransport,- TransportReadyState,+ ConnectionState,+ type ConnectionStatus,} from "./connection";-import { type NotebookEvent, parseNotebookEvent } from "./events";import { attachments } from "./resources/attachments";import { type Document, document } from "./resources/document";-/** Events that may arrive without a cursor after `ready`. */-const UNCURSORED = new Set<NotebookEvent["event"]>([- "reset",- "marimo",- "unknown",-]);+/** The kinds the editor reads, with marimo's own notifications. */+const TYPES = ["notebook", "cell", "document", "attachment", "marimo"] as const;++type EditorEvent = NotebookEvent<(typeof TYPES)[number]>;++/** A native marimo notification, passed through without interpretation. */+const MarimoMessage = z.object({ marimo: z.unknown() });/** A connection to a notebook on a marimo host. */export interface NotebookClient {@@ -43,28 +47,53 @@ export interface NotebookClient {reconnect(): Promise<void>;}-/** The transport and application callbacks needed to connect a notebook. */+/** The transport and application callbacks needed to follow a notebook. */export interface NotebookConnection {- /** Create a transport that reads the URL again on each connection attempt. */- createTransport: (url: () => string) => NotebookTransport;- /** The current stream URL, including authentication and subscription options. */- url: () => string;- /** Abort to close the transport and clear the client's state. */+ /** Opens one connection to the notebook's stream. */+ transport: NotebookTransport;+ /** Abort to close the stream and clear the client's state. */signal: AbortSignal;- /** Wait until the host can accept the initial connection. */- waitUntilReady: () => Promise<void>;/** Check whether the host is reachable before an explicit reconnect. */checkHealth: () => Promise<boolean>;- /** Decode wire text without interpreting its event type. */- decodeJson: (message: string) => unknown;/** Handle a native marimo notification. Its payload has not been validated. */onNotification: (notification: unknown) => void;- /** Choose the connection status and retry policy after the transport closes. */- classifyClose: (event: CloseEvent) => CloseDecision;+}++const disconnected = {+ state: ConnectionState.CLOSED,+ code: ConnectionClosedReason.KERNEL_DISCONNECTED,+ reason: "kernel not found",+} satisfies ConnectionStatus;++const malformed = {+ ...disconnected,+ reason: "Failed to decode notebook message",+} satisfies ConnectionStatus;++function isStatus(value: unknown): value is ConnectionStatus {+ return typeof value === "object" && value !== null && "state" in value;+}++/**+ * The status to show after the stream stopped.+ *+ * A transport says which status its stop means. An event the protocol+ * rejects is malformed. Anything else means the host was not reached.+ */+function statusAfter(error: unknown): ConnectionStatus {+ if (error instanceof StreamStopped && isStatus(error.cause)) {+ return error.cause;+ }+ if (error instanceof StreamStopped && error.cause instanceof z.ZodError) {+ return malformed;+ }+ return disconnected;}/** Create a client without opening a connection. */export function createNotebookClient(store: ReturnType<typeof createStore>) {+ // `useNotebookSession` copies this into the editor's shared `connectionAtom`,+ // which gates features until MO-8051 derives availability separately.const connectionAtom = atom<ConnectionStatus>({state: ConnectionState.NOT_STARTED,});@@ -73,16 +102,18 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {const streamAtom = atom(reducer.initial);// A resumed stream is live, but presence waits for this connection's ready.const readyAtom = atom(false);+ const presentAtom = atom(+ (get) =>+ get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN,+ );const notebookAtom = atom((get) =>- get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN- ? get(streamAtom).notebook- : null,+ get(presentAtom) ? get(streamAtom).notebook : null,);const documentAtom = atom((get) => get(streamAtom).resources.document.current,);const attachmentsAtom = atom((get) =>- get(readyAtom) && get(connectionAtom).state === ConnectionState.OPEN+ get(presentAtom)? get(streamAtom).resources.attachments: attachments.initial,);@@ -95,156 +126,97 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {reconnect: async () => reconnect?.(),};+ function setStatus(status: ConnectionStatus) {+ store.set(readyAtom, false);+ store.set(connectionAtom, status);+ }+function connect({- createTransport,- url,+ transport,signal,- waitUntilReady,checkHealth,onNotification,- decodeJson,- classifyClose,}: NotebookConnection) {if (signal.aborted) {return;}- let shouldRetry = true;- let terminal = false;+ let events: NotebookEvents<(typeof TYPES)[number]> | undefined;let checkingHealth = false;- let streamKey: string | undefined;- // The id of the last live event. Null before `ready` and after `reset`.- let cursor: string | null = null;- const transport = createTransport(() => {- const next = new URL(url());- next.searchParams.delete("cursor");- if (signal.aborted) {- return next.toString();- }- // A cursor is useful with the state that produced it, which a change- // of session or notebook invalidates. Authentication may change freely.- const identity = new URL(next);- identity.searchParams.delete("access_token");- identity.searchParams.sort();- const key = identity.toString();- const current = store.get(streamAtom);- // A live stream keeps its state and resumes from the cursor. An- // incomplete snapshot starts over.- const state =- key !== streamKey || current.phase === "snapshot"- ? reducer.initial- : current;- if (state.phase === "snapshot") {- cursor = null;- }- streamKey = key;- store.set(readyAtom, false);- store.set(streamAtom, state);- if (cursor !== null) {- next.searchParams.set("cursor", cursor);- }- return next.toString();- });- const setStatus = (status: ConnectionStatus) => {- store.set(readyAtom, false);- store.set(connectionAtom, status);- };- const disconnected = {- state: ConnectionState.CLOSED,- code: ConnectionClosedReason.KERNEL_DISCONNECTED,- reason: "kernel not found",- } satisfies ConnectionStatus;+ // Whether the replica still holds the state the last cursor describes.+ let resumable = true;- function retry(code?: number, reason?: string) {- if (!signal.aborted && !terminal && shouldRetry) {- shouldRetry = false;- transport.reconnect(code, reason);- }- }-- function onOpen() {- if (signal.aborted || terminal) {- return;- }- shouldRetry = true;- setStatus({ state: ConnectionState.OPEN });- }-- function onClose(event: CloseEvent) {- if (signal.aborted || terminal) {- return;- }- Logger.warn("Notebook connection closed", event.code, event.reason);- const decision = classifyClose(event);- setStatus(decision.status);- if (decision.kind === "terminal") {- terminal = true;- transport.close();- } else if (decision.kind === "retry") {- retry(event.code, event.reason);- } else {- terminal = true;+ /** Mirror one stream into the atoms until it closes. */+ function follow(cursor?: string) {+ if (cursor === undefined) {+ store.set(streamAtom, reducer.initial);}+ resumable = true;+ const current = new NotebookEvents(transport, {+ types: TYPES,+ cursor,+ signal,+ // TODO(MO-8051): Gate editing and running on the notebook's operations+ // and request results instead. The stream's status would then only+ // mark the view as stale.+ onStatus: (status) => {+ if (status === "connecting") {+ setStatus({ state: ConnectionState.CONNECTING });+ } else if (status === "connected") {+ setStatus({ state: ConnectionState.OPEN });+ }+ },+ });+ current.subscribe(+ (event) => apply(current, event),+ (error) => {+ if (!signal.aborted && current === events) {+ Logger.warn("Notebook stream stopped", error);+ const status = statusAfter(error);+ if (status === malformed) {+ stopMalformed(current);+ } else {+ setStatus(status);+ }+ }+ },+ );+ events = current;}- function onError(event: Event) {- if (signal.aborted || terminal) {- return;- }- Logger.warn("Notebook connection error", event);- setStatus(disconnected);- retry();+ function stopMalformed(source: NotebookEvents<string>) {+ source.close();+ // The cursor can already include an event the replica rejected.+ resumable = false;+ store.set(streamAtom, reducer.initial);+ setStatus(malformed);}- function onMessage(message: MessageEvent<string>) {- if (signal.aborted || terminal) {+ function apply(source: NotebookEvents<string>, event: EditorEvent) {+ if (event.event === "marimo") {+ const message = MarimoMessage.safeParse(event.data);+ if (message.success) {+ onNotification(message.data.marimo);+ } else {+ Logger.error("Failed to decode notebook message", event);+ stopMalformed(source);+ }return;}- let event;try {- event = parseNotebookEvent(decodeJson(message.data));- const state = store.get(streamAtom);- if (- state.phase === "live" &&- event.id === undefined &&- !UNCURSORED.has(event.event)- ) {- throw new Error("Live notebook event is missing its cursor");- }- if (event.event !== "marimo" && event.event !== "unknown") {- store.set(streamAtom, reducer.reduce(state, event));- }- if (event.event === "reset") {- cursor = null;- } else if (event.event === "ready" || state.phase === "live") {- cursor = event.id ?? cursor;- }- if (event.event === "ready" || event.event === "reset") {- store.set(readyAtom, event.event === "ready");- }+ store.set(streamAtom, reducer.reduce(store.get(streamAtom), event));} catch (error) {- Logger.error("Failed to decode notebook message", error);- store.set(streamAtom, reducer.initial);- cursor = null;- terminal = true;- setStatus({- ...disconnected,- reason: "Failed to decode notebook message",- });- transport.close();+ // An event the replica cannot apply, such as another notebook's.+ Logger.error("Failed to apply notebook event", error);+ stopMalformed(source);return;}- if (event.event === "marimo") {- onNotification(event.data.marimo);+ if (event.event === "ready" || event.event === "reset") {+ store.set(readyAtom, event.event === "ready");}}reconnect = async () => {- if (- signal.aborted ||- checkingHealth ||- transport.readyState === TransportReadyState.OPEN ||- transport.readyState === TransportReadyState.CONNECTING- ) {+ if (signal.aborted || checkingHealth || events?.status !== "closed") {return;}checkingHealth = true;@@ -255,17 +227,13 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {return;}if (!healthy) {- shouldRetry = false;setStatus(disconnected);return;}- terminal = false;- shouldRetry = true;- transport.reconnect();+ follow(resumable ? (events.cursor ?? undefined) : undefined);} catch (error) {if (!signal.aborted) {Logger.error("Notebook health check failed", error);- shouldRetry = false;setStatus(disconnected);}} finally {@@ -276,11 +244,6 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {signal.addEventListener("abort",() => {- transport.removeEventListener("open", onOpen);- transport.removeEventListener("close", onClose);- transport.removeEventListener("error", onError);- transport.removeEventListener("message", onMessage);- transport.close();reconnect = undefined;store.set(streamAtom, reducer.initial);setStatus({ state: ConnectionState.NOT_STARTED });@@ -288,28 +251,8 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {{ once: true },);- transport.addEventListener("open", onOpen);- transport.addEventListener("close", onClose);- transport.addEventListener("error", onError);- transport.addEventListener("message", onMessage);-- if (transport.readyState === TransportReadyState.CLOSED) {- setStatus({ state: ConnectionState.CONNECTING });- void waitUntilReady()- .then(() => {- if (!signal.aborted) {- transport.reconnect();- }- })- .catch((error) => {- if (!signal.aborted) {- Logger.error("Healthy connection never made", error);- terminal = true;- setStatus(disconnected);- transport.close();- }- });- }+ setStatus({ state: ConnectionState.CONNECTING });+ follow();}return { client, connect };diff --git a/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx b/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsxindex 316fcf02c9..98ac4d9206 100644--- a/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx+++ b/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx@@ -5,52 +5,48 @@ import { act, renderHook } from "@testing-library/react";import { createStore, Provider } from "jotai";import type { PropsWithChildren } from "react";import { beforeEach, describe, expect, it, vi } from "vitest";+import type { NotebookTransport } from "@marimo-team/client";import { ConnectionState } from "../types";-import { createConnectionTransport } from "../transports/create";-import type { IConnectionTransport } from "../transports/transport";+import { Deferred } from "@/utils/Deferred";+import { createNotebookTransport } from "../transports/notebook";import { useNotebookClient } from "../useNotebookClient";import { fixtureMessages } from "../../host/__tests__/fixtures";import { agentAttachmentsAtom } from "../../attachments/state";import { notebookClientAtom } from "../state";-vi.mock("../transports/create", () => ({ createConnectionTransport: vi.fn() }));+vi.mock("../transports/notebook", () => ({ createNotebookTransport: vi.fn() }));-function makeTransport(url?: () => string) {- const events = new EventTarget();- const transport: IConnectionTransport = {- readyState: WebSocket.CLOSED,- reconnect: vi.fn(() => {- url?.();- transport.readyState = WebSocket.OPEN;- events.dispatchEvent(new Event("open"));- }),- close: vi.fn(() => {- transport.readyState = WebSocket.CLOSED;- events.dispatchEvent(new CloseEvent("close"));- }),- send: vi.fn(),- addEventListener: events.addEventListener.bind(events),- removeEventListener: events.removeEventListener.bind(events),- };+/** A transport whose connections the test drives. */+function makeTransport() {+ const opened: {+ signal: AbortSignal;+ open(): void;+ receive(message: unknown): void;+ }[] = [];+ const transport: NotebookTransport = ({ signal }, handlers) =>+ new Promise((resolve) => {+ opened.push({ signal, open: handlers.open, receive: handlers.message });+ signal.addEventListener("abort", () => resolve(), { once: true });+ });return {transport,- receive: (message: unknown) =>- events.dispatchEvent(- new MessageEvent("message", { data: JSON.stringify(message) }),- ),+ opened,+ /** Open the latest connection and deliver a host-framed notification. */notify: () =>- events.dispatchEvent(- new MessageEvent("message", {- data: JSON.stringify({- event: "marimo",- data: { marimo: { op: "reconnected" } },- }),- }),- ),+ opened.at(-1)?.receive({+ event: "marimo",+ data: { marimo: { op: "reconnected" } },+ }),};}-function setup(strict = false) {+function setup(+ strict = false,+ readiness: {+ waitUntilReady?: () => Promise<void>;+ checkHealth?: () => Promise<boolean>;+ } = {},+) {const store = createStore();const options = {static: false,@@ -60,6 +56,7 @@ function setup(strict = false) {waitUntilReady: async () => undefined,checkHealth: async () => true,onNotification: vi.fn(),+ ...readiness,};const wrapper = ({ children }: PropsWithChildren) => (<Provider store={store}>{children}</Provider>@@ -73,19 +70,97 @@ function setup(strict = false) {}beforeEach(() => {- vi.mocked(createConnectionTransport).mockReset();+ vi.mocked(createNotebookTransport).mockReset();});describe("useNotebookClient", () => {+ it.each([true, false])(+ "rechecks health after failed startup (healthy: %s)",+ async (healthy) => {+ const fake = makeTransport();+ vi.mocked(createNotebookTransport).mockImplementation(+ ({ url }) =>+ async (attempt, handlers) => {+ if (typeof url === "function") {+ await url();+ }+ if (!attempt.signal.aborted) {+ return fake.transport(attempt, handlers);+ }+ },+ );+ const waitUntilReady = vi+ .fn()+ .mockRejectedValue(new Error("Startup gave up"));+ const checkHealth = vi.fn().mockResolvedValue(healthy);+ const { result, store, unmount } = setup(false, {+ waitUntilReady,+ checkHealth,+ });+ await act(async () => Promise.resolve());+ expect(store.get(result.current.connectionAtom).state).toBe(+ ConnectionState.CLOSED,+ );++ await act(async () => result.current.reconnect());+ expect({+ healthChecks: checkHealth.mock.calls.length,+ initialWaits: waitUntilReady.mock.calls.length,+ connections: fake.opened.length,+ state: store.get(result.current.connectionAtom).state,+ }).toEqual({+ healthChecks: 1,+ initialWaits: 1,+ connections: healthy ? 1 : 0,+ state: healthy ? ConnectionState.CONNECTING : ConnectionState.CLOSED,+ });+ act(() => fake.opened.at(-1)?.open());+ expect(store.get(result.current.connectionAtom).state).toBe(+ healthy ? ConnectionState.OPEN : ConnectionState.CLOSED,+ );+ unmount();+ },+ );++ it("waits for initial readiness without reviving an unmounted connection", async () => {+ const ready = new Deferred<void>();+ const resolvedUrl = vi.fn();+ vi.mocked(createNotebookTransport).mockImplementation(+ ({ url }) =>+ async () => {+ if (typeof url === "function") {+ await url();+ resolvedUrl();+ }+ },+ );+ const { result, store, unmount } = setup(false, {+ waitUntilReady: () => ready.promise,+ });+ await act(async () => Promise.resolve());+ expect(resolvedUrl).not.toHaveBeenCalled();+ expect(store.get(result.current.connectionAtom)).toEqual({+ state: ConnectionState.CONNECTING,+ });+ unmount();+ await act(async () => ready.resolve());+ expect(store.get(result.current.connectionAtom)).toEqual({+ state: ConnectionState.NOT_STARTED,+ });+ expect(store.get(notebookClientAtom)).toBeNull();+ });+it("exposes host presence to the UI without waiting for kernel-ready", async () => {- const transport = makeTransport();- vi.mocked(createConnectionTransport).mockReturnValue(transport.transport);+ const fake = makeTransport();+ vi.mocked(createNotebookTransport).mockReturnValue(fake.transport);const { result, store, unmount } = setup();await act(async () => Promise.resolve());expect(store.get(notebookClientAtom)).toBe(result.current);- act(() =>- fixtureMessages("notebook-events.sse").forEach(transport.receive),- );+ const [connection] = fake.opened;+ act(() => {+ connection.open();+ fixtureMessages("notebook-events.sse").forEach(connection.receive);+ });expect(store.get(agentAttachmentsAtom)).toEqual([{id: "a2",@@ -101,49 +176,48 @@ describe("useNotebookClient", () => {});it("uses current callbacks and URL providers without reconnecting on a rerender", async () => {- const first = makeTransport();- vi.mocked(createConnectionTransport).mockReturnValue(first.transport);+ const fake = makeTransport();+ vi.mocked(createNotebookTransport).mockReturnValue(fake.transport);const { rerender, options, unmount } = setup();await act(async () => Promise.resolve());const onNotification = vi.fn();rerender({ ...options, onNotification, url: () => "ws://redirected/ws" });- act(() => first.notify());+ act(() => fake.notify());expect(options.onNotification).not.toHaveBeenCalled();expect(onNotification).toHaveBeenCalledExactlyOnceWith({data: { op: "reconnected" },});- expect(createConnectionTransport).toHaveBeenCalledOnce();- expect(vi.mocked(createConnectionTransport).mock.calls[0][0].url()).toBe(+ expect(createNotebookTransport).toHaveBeenCalledOnce();+ const [{ url }] = vi.mocked(createNotebookTransport).mock.calls[0];+ expect(String(await (url as () => Promise<string>)())).toBe("ws://redirected/ws",);unmount();});- it("cleans up every transport under Strict Mode and only connects the active lifetime", async () => {- const transports: ReturnType<typeof makeTransport>[] = [];- vi.mocked(createConnectionTransport).mockImplementation(() => {+ it("closes every stream under Strict Mode and only follows the active lifetime", async () => {+ const fakes: ReturnType<typeof makeTransport>[] = [];+ vi.mocked(createNotebookTransport).mockImplementation(() => {const next = makeTransport();- transports.push(next);+ fakes.push(next);return next.transport;});const { result, store, options, unmount } = setup(true);await act(async () => Promise.resolve());- expect(transports).toHaveLength(2);- expect(transports[0].transport.reconnect).not.toHaveBeenCalled();- expect(transports[0].transport.close).toHaveBeenCalledOnce();- expect(transports[1].transport.reconnect).toHaveBeenCalledOnce();+ expect(fakes).toHaveLength(2);+ expect(fakes[0].opened.every((attempt) => attempt.signal.aborted)).toBe(+ true,+ );+ const [active] = fakes[1].opened;+ act(() => active.open());expect(store.get(result.current.connectionAtom)).toEqual({state: ConnectionState.OPEN,});- act(() => {- for (const transport of transports) {- transport.notify();- }- });+ act(() => fakes.forEach((fake) => fake.notify()));expect(options.onNotification).toHaveBeenCalledOnce();unmount();- expect(transports[1].transport.close).toHaveBeenCalledOnce();+ expect(active.signal.aborted).toBe(true);await result.current.reconnect();- expect(transports[1].transport.reconnect).toHaveBeenCalledOnce();+ expect(fakes[1].opened).toHaveLength(1);});});diff --git a/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx b/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsxindex bbacfe96a0..08850489ed 100644--- a/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx+++ b/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx@@ -21,8 +21,8 @@ import {vi,} from "vitest";-vi.mock("../transports/create", () => ({- createConnectionTransport: vi.fn(),+vi.mock("../transports/notebook", () => ({+ createNotebookTransport: vi.fn(),}));vi.mock("@/core/runtime/config", async () => {@@ -36,7 +36,6 @@ vi.mock("@/core/runtime/config", async () => {});import { MockNotebook } from "@/__mocks__/notebook";-import { Logger } from "@/utils/Logger";import { Deferred } from "@/utils/Deferred";import { cellId } from "@/__tests__/branded";import { alertAtom, getPackageAlert } from "@/core/alerts/state";@@ -44,7 +43,6 @@ import { notebookAtom } from "@/core/cells/cells";import { AppConfigSchema } from "@/core/config/config-schema";import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";import { kernelStartupErrorAtom } from "@/core/errors/state";-import type { RunEvent } from "@marimo-team/client/protocol";import type { NotificationPayload } from "@/core/kernel/messages";import { useRuntimeManager } from "@/core/runtime/config";import { initialRunCompletedAtom } from "../../kernel/state";@@ -52,54 +50,72 @@ import { connectionAtom, startupProgressAtom } from "../../network/connection";import { generateSessionId } from "../../kernel/session";import { RuntimeManager } from "../../runtime/runtime";import { WebSocketClosedReason, ConnectionState } from "../types";-import type { IConnectionTransport } from "../transports/transport";+import { classifyCloseEvent } from "../connection-state";+import { createNotebookTransport } from "../transports/notebook";import { useNotebookSession } from "../useNotebookSession";-import { createConnectionTransport } from "../transports/create";+import { type NotebookTransport, StreamStopped } from "@marimo-team/client";const SESSION_ID = generateSessionId();-interface MockTransport {- readyState: 0 | 1 | 2 | 3;- reconnect: Mock<IConnectionTransport["reconnect"]>;- close: Mock<IConnectionTransport["close"]>;- send: Mock<IConnectionTransport["send"]>;- addEventListener: Mock<IConnectionTransport["addEventListener"]>;- removeEventListener: Mock<IConnectionTransport["removeEventListener"]>;+/** One connection the fake transport opened. */+interface Attempt {+ open(): void;+ receive(message: unknown): void;+ drop(): void;+ stop(error: StreamStopped): void;}-function makeTransport(- readyState: 0 | 1 | 2 | 3 = WebSocket.CLOSED,-): MockTransport {- return {- readyState,- reconnect: vi.fn(),- close: vi.fn(),- send: vi.fn(),- addEventListener: vi.fn(),- removeEventListener: vi.fn(),- };+/** A transport the test drives, one connection at a time. */+function makeTransport() {+ const attempts: Attempt[] = [];+ const transport: NotebookTransport = ({ signal }, handlers) =>+ new Promise((resolve, reject) => {+ attempts.push({+ open: handlers.open,+ receive: handlers.message,+ drop: resolve,+ stop: reject,+ });+ signal.addEventListener("abort", () => resolve(), { once: true });+ });+ return { transport, attempts };}-function getTransportHandlers() {- const result = vi.mocked(createConnectionTransport).mock.results.at(-1);- if (!result || result.type !== "return") {- throw new Error("No connection transport was created");- }- const transport = result.value;- function emit(- event: "open" | "close" | "error" | "message",- message: Event | CloseEvent | MessageEvent,- ) {- const callback = vi- .mocked(transport.addEventListener)- .mock.calls.find(([name]) => name === event)?.[1];- callback?.(message);- }+type FakeTransport = ReturnType<typeof makeTransport>;++/** Use a fake transport for the next session the hook follows. */+function withTransport(fake: FakeTransport = makeTransport()) {+ vi.mocked(createNotebookTransport).mockReturnValue(fake.transport);+ return fake;+}++/** Let the stream open its first connection. */+const started = () => act(() => Promise.resolve());++/** Drive the latest connection the fake transport opened. */+function connection(fake: FakeTransport) {+ const current = () => {+ const attempt = fake.attempts.at(-1);+ if (attempt === undefined) {+ throw new Error("No connection was opened");+ }+ return attempt;+ };return {- onError: (event: Event) => emit("error", event),- onOpen: (event: Event) => emit("open", event),- onClose: (event: CloseEvent) => emit("close", event),- onMessage: (event: MessageEvent) => emit("message", event),+ open: () => current().open(),+ receive: (message: unknown) => current().receive(message),+ /** Deliver a notification as the session routes frame it. */+ send: (notification: unknown) =>+ current().receive({ event: "marimo", data: { marimo: notification } }),+ /** End the connection so the stream reconnects. */+ drop: () => current().drop(),+ /** Close the connection with a reason the editor treats as final. */+ close: (reason: string) =>+ current().stop(+ new StreamStopped(reason, {+ cause: classifyCloseEvent({ reason }).status,+ }),+ ),};}@@ -141,12 +157,12 @@ function renderConnectionHook(store: ReturnType<typeof createStore>) {}describe("useNotebookSession.reconnect()", () => {- let transport: MockTransport;+ let fake: FakeTransport;let isHealthy: Mock<() => Promise<boolean>>;let store: ReturnType<typeof createStore>;beforeEach(() => {- transport = makeTransport(WebSocket.CLOSED);+ fake = withTransport();isHealthy = vi.fn<() => Promise<boolean>>().mockResolvedValue(true);store = createStore();store.set(connectionAtom, {@@ -154,55 +170,53 @@ describe("useNotebookSession.reconnect()", () => {code: WebSocketClosedReason.KERNEL_DISCONNECTED,reason: "kernel not found",});- vi.mocked(createConnectionTransport).mockReturnValue(transport);vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager(isHealthy));});- function renderUseHook() {- return renderConnectionHook(store);+ async function renderStopped() {+ const hook = renderConnectionHook(store);+ await started();+ await act(async () => connection(fake).close("MARIMO_SHUTDOWN"));+ return hook;}- it("is a no-op when the transport is already OPEN", async () => {- transport.readyState = WebSocket.OPEN;- const { result } = renderUseHook();- await act(async () => {- await result.current.reconnect();- });- expect(isHealthy).not.toHaveBeenCalled();- expect(transport.reconnect).not.toHaveBeenCalled();- });-- it("is a no-op when the transport is already CONNECTING", async () => {- transport.readyState = WebSocket.CONNECTING;- const { result } = renderUseHook();- await act(async () => {- await result.current.reconnect();- });- expect(isHealthy).not.toHaveBeenCalled();- expect(transport.reconnect).not.toHaveBeenCalled();- });+ it.each(["connecting", "connected"])(+ "is a no-op while the stream is %s",+ async (state) => {+ const { result } = renderConnectionHook(store);+ await started();+ if (state === "connected") {+ act(() => connection(fake).open());+ }+ await act(async () => {+ await result.current.reconnect();+ });+ expect(isHealthy).not.toHaveBeenCalled();+ expect(fake.attempts).toHaveLength(1);+ },+ );it("probes /health and reconnects when the runtime is healthy", async () => {isHealthy.mockResolvedValue(true);- const { result } = renderUseHook();+ const { result } = await renderStopped();await act(async () => {await result.current.reconnect();});expect(isHealthy).toHaveBeenCalledOnce();- expect(transport.reconnect).toHaveBeenCalledOnce();+ expect(fake.attempts).toHaveLength(2);expect(store.get(connectionAtom)).toEqual({state: ConnectionState.CONNECTING,});});- it("transitions to CLOSED and does not call ws.reconnect when the probe fails", async () => {+ it("transitions to CLOSED and does not reconnect when the probe fails", async () => {isHealthy.mockResolvedValue(false);- const { result } = renderUseHook();+ const { result } = await renderStopped();await act(async () => {await result.current.reconnect();});expect(isHealthy).toHaveBeenCalledOnce();- expect(transport.reconnect).not.toHaveBeenCalled();+ expect(fake.attempts).toHaveLength(1);expect(store.get(connectionAtom)).toEqual({state: ConnectionState.CLOSED,code: WebSocketClosedReason.KERNEL_DISCONNECTED,@@ -213,115 +227,30 @@ describe("useNotebookSession.reconnect()", () => {describe("useNotebookSession messages", () => {let store: ReturnType<typeof createStore>;+ let fake: FakeTransport;- beforeEach(() => {+ beforeEach(async () => {store = createStore();- vi.mocked(createConnectionTransport).mockClear();- vi.mocked(createConnectionTransport).mockReturnValue(- makeTransport(WebSocket.OPEN),- );+ fake = withTransport();vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());renderConnectionHook(store);+ await started();});function receive(payload: unknown) {- const options = getTransportHandlers();- act(() => {- options.onMessage(- new MessageEvent("message", { data: JSON.stringify(payload) }),- );- });+ act(() => connection(fake).receive(payload));}- it.each(["{broken", "null"])(- "closes a malformed stream and ignores subsequent notifications: %s",- (data) => {- receive({ event: "marimo", data: { marimo: { op: "reconnected" } } });- act(() =>- getTransportHandlers().onMessage(new MessageEvent("message", { data })),- );- expect(store.get(connectionAtom)).toEqual({- state: ConnectionState.CLOSED,- code: "KERNEL_DISCONNECTED",- reason: "Failed to decode notebook message",- });- receive({- event: "marimo",- data: {- marimo: {- op: "completed-run",- run_id: "r1",- outcome: "succeeded",- error: null,- },- },- });- expect(store.get(initialRunCompletedAtom)).toBe(false);- },- );-- it.each(["session", "host"])(- "records completion of the initial run from the %s stream",- (stream) => {- const notification = {- op: "completed-run",- run_id: null,- outcome: "succeeded",- error: null,- } satisfies NotificationPayload["data"];- expect(store.get(initialRunCompletedAtom)).toBe(false);- receive(- stream === "host"- ? { id: "42", event: "marimo", data: { marimo: notification } }- : { op: notification.op, data: notification },- );- expect(store.get(initialRunCompletedAtom)).toBe(true);- },- );-- it("ignores other host events before handling the next notification", () => {- const errors = vi.spyOn(Logger, "error").mockImplementation(vi.fn());- try {- receive({ id: "1", event: "ready", data: {} });- receive({- id: "2",- event: "run",- data: {- run: {- id: "r1",- notebook_id: "n1",- caused_by: null,- status: "completed",- outcome: "succeeded",- started_at: "2026-10-19T12:00:00Z",- completed_at: "2026-10-19T12:00:01Z",- },- },- } satisfies RunEvent);- receive({- id: "3",- event: "future-event",- data: { marimo: { op: "completed-run", run_id: "r1" } },- });- receive({ id: "4", event: "another-event", data: null });- expect(store.get(initialRunCompletedAtom)).toBe(false);- receive({- id: "5",- event: "marimo",- data: {- marimo: {- op: "completed-run",- run_id: "r1",- outcome: "succeeded",- error: null,- },- },- });- expect(store.get(initialRunCompletedAtom)).toBe(true);- expect(errors).not.toHaveBeenCalled();- } finally {- errors.mockRestore();- }+ it("records completion of the initial run", () => {+ const notification = {+ op: "completed-run",+ run_id: null,+ outcome: "succeeded",+ error: null,+ } satisfies NotificationPayload["data"];+ expect(store.get(initialRunCompletedAtom)).toBe(false);+ receive({ id: "42", event: "marimo", data: { marimo: notification } });+ expect(store.get(initialRunCompletedAtom)).toBe(true);});});@@ -330,45 +259,34 @@ it.each(["kernel-ready", "reconnected"])(async (op) => {const store = createStore();store.set(connectionAtom, { state: ConnectionState.CONNECTING });- vi.mocked(createConnectionTransport).mockClear();- vi.mocked(createConnectionTransport).mockReturnValue(- makeTransport(WebSocket.OPEN),- );+ const fake = withTransport();vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());renderConnectionHook(store);- const options = getTransportHandlers();+ await started();+ const conn = connection(fake);- await act(async () => {- await options.onOpen(new Event("open"));- });+ await act(async () => conn.open());expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);- act(() => {- options.onMessage(- new MessageEvent("message", {- data: JSON.stringify({- op,- data: {- op,- cell_ids: [],- codes: [],- names: [],- configs: [],- layout: null,- resumed: true,- ui_values: {},- last_executed_code: {},- last_execution_time: {},- app_config: { width: "normal" },- kiosk: false,- capabilities: { terminal: false },- auto_instantiated: false,- consumer_capabilities: { edit: true, interact: true },- },- }),- }),- );- });+ act(() =>+ conn.send({+ op,+ cell_ids: [],+ codes: [],+ names: [],+ configs: [],+ layout: null,+ resumed: true,+ ui_values: {},+ last_executed_code: {},+ last_execution_time: {},+ app_config: { width: "normal" },+ kiosk: false,+ capabilities: { terminal: false },+ auto_instantiated: false,+ consumer_capabilities: { edit: true, interact: true },+ }),+ );expect(store.get(connectionAtom).state).toBe(ConnectionState.OPEN);},);@@ -377,11 +295,10 @@ describe("connection notice", () => {beforeEach(() => vi.useFakeTimers());afterEach(() => vi.useRealTimers());- function renderNotice() {+ async function renderNotice() {const store = createStore();store.set(connectionAtom, { state: ConnectionState.CONNECTING });- const transport = makeTransport(WebSocket.OPEN);- vi.mocked(createConnectionTransport).mockReturnValue(transport);+ const fake = withTransport();vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());const Connection = () => {const { reconnect } = useNotebookSession({@@ -403,20 +320,17 @@ describe("connection notice", () => {</ErrorBoundary></JotaiProvider>,);- const options = getTransportHandlers();+ await started();+ const conn = connection(fake);+ // Messages arrive on an open connection.+ act(() => conn.open());const send = (data: NotificationPayload["data"]) =>- act(() => {- options.onMessage(- new MessageEvent("message", {- data: JSON.stringify({ op: data.op, data }),- }),- );- });- return { store, transport, options, send };+ act(() => conn.send(data));+ return { store, fake, conn, send };}- it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", () => {- const { store, options, send } = renderNotice();+ it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", async () => {+ const { store, conn, send } = await renderNotice();send({op: "startup-progress",phase: "preparing-environment",@@ -456,7 +370,7 @@ describe("connection notice", () => {expect(screen.queryByRole("region", { name: "Notebook startup" }),).not.toBeInTheDocument();- act(() => options.onClose(new CloseEvent("close")));+ await act(async () => conn.drop());act(() => vi.advanceTimersByTime(500));expect(store.get(connectionAtom)).toEqual({state: ConnectionState.CONNECTING,@@ -467,8 +381,8 @@ describe("connection notice", () => {).not.toBeInTheDocument();});- it("restores startup output before appending live chunks and resets it for a new attempt", () => {- const { store, send } = renderNotice();+ it("restores startup output before appending live chunks and resets it for a new attempt", async () => {+ const { store, send } = await renderNotice();const snapshot = {op: "startup-progress",phase: "starting-kernel",@@ -494,7 +408,7 @@ describe("connection notice", () => {});it("restores completed startup output without putting a connected kernel back into startup", async () => {- const { store, options, send } = renderNotice();+ const { store, conn, send } = await renderNotice();send({ op: "reconnected" });send({op: "startup-progress",@@ -512,13 +426,15 @@ describe("connection notice", () => {screen.queryByRole("region", { name: "Notebook startup" }),).not.toBeInTheDocument();- // A new transport starts from the next session's authoritative snapshot.- await act(async () => options.onOpen(new Event("open")));+ // A new connection starts from the next session's authoritative snapshot.+ await act(async () => conn.drop());+ await act(async () => vi.advanceTimersByTime(2000));+ await act(async () => conn.open());expect(store.get(startupProgressAtom)).toBeNull();});- it("does not flash a notice when startup finishes within the delay", () => {- const { send } = renderNotice();+ it("does not flash a notice when startup finishes within the delay", async () => {+ const { send } = await renderNotice();send({op: "startup-progress",phase: "preparing-environment",@@ -546,16 +462,11 @@ describe("connection notice", () => {it.each(["preparing-environment", "starting-kernel"] as const)("keeps a %s failure available until the user retries",async (phase) => {- const { store, transport, options, send } = renderNotice();+ const { store, fake, conn, send } = await renderNotice();send({ op: "startup-progress", phase, logs: "", log_mode: "replace" });const error = "A full diagnostic\nwith <stderr> details";send({ op: "kernel-startup-error", error });- transport.readyState = WebSocket.CLOSED;- act(() =>- options.onClose(- new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),- ),- );+ await act(async () => conn.close("MARIMO_KERNEL_STARTUP_ERROR"));expect(screen.getByRole("status")).toHaveTextContent("Kernel failed to start",);@@ -566,11 +477,11 @@ describe("connection notice", () => {expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {normalizeWhitespace: false,});- expect(transport.reconnect).not.toHaveBeenCalled();+ expect(fake.attempts).toHaveLength(1);await act(async () =>fireEvent.click(screen.getByRole("button", { name: "Try again" })),);- expect(transport.reconnect).toHaveBeenCalledOnce();+ expect(fake.attempts).toHaveLength(2);expect(store.get(kernelStartupErrorAtom)).toBeNull();expect(screen.queryByRole("button", { name: "Try again" }),@@ -590,23 +501,14 @@ describe("connection notice", () => {);});-it("replaces environment state from snapshots, then continues live progress", () => {+it("replaces environment state from snapshots, then continues live progress", async () => {const store = createStore();- vi.mocked(createConnectionTransport).mockClear();- vi.mocked(createConnectionTransport).mockReturnValue(- makeTransport(WebSocket.OPEN),- );+ const fake = withTransport();vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());renderConnectionHook(store);- const options = getTransportHandlers();+ await started();function receive(data: NotificationPayload["data"]) {- act(() =>- options?.onMessage(- new MessageEvent("message", {- data: JSON.stringify({ op: data.op, data }),- }),- ),- );+ act(() => connection(fake).send(data));}receive({op: "environment-operation",diff --git a/frontend/src/core/websocket/transports/__tests__/notebook.test.ts b/frontend/src/core/websocket/transports/__tests__/notebook.test.tsnew file mode 100644index 0000000000..6f48eb2a9a--- /dev/null+++ b/frontend/src/core/websocket/transports/__tests__/notebook.test.ts@@ -0,0 +1,502 @@+/* Copyright 2026 Marimo. All rights reserved. */++import {+ NotebookEvents,+ StreamStopped,+ type StreamUrl,+} from "@marimo-team/client";+import { createStore } from "jotai/vanilla";+import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";+import { createNotebookClient } from "../../../host/notebook-client";+import { fixtureMessages } from "../../../host/__tests__/fixtures";+import { ConnectionState } from "../../../host/connection";+import { Deferred } from "@/utils/Deferred";+import {+ createNotebookTransport,+ pyodide,+ sessionSse,+ websocket,+} from "../notebook";++const wasm = vi.hoisted(() => ({ enabled: false, consumer: vi.fn() }));+vi.mock("../../../wasm/utils", () => ({ isWasm: () => wasm.enabled }));+vi.mock("../../../wasm/bridge", () => ({+ PyodideBridge: { INSTANCE: { attachMessageConsumer: wasm.consumer } },+}));++const encoder = new TextEncoder();++/** A WebSocket the test drives. */+class FakeSocket extends EventTarget {+ public static readonly opened: FakeSocket[] = [];+ public readonly url: string;+ public constructor(url: URL) {+ super();+ this.url = String(url);+ FakeSocket.opened.push(this);+ }+ public open() {+ this.dispatchEvent(new Event("open"));+ }+ public receive(text: string) {+ this.dispatchEvent(new MessageEvent("message", { data: text }));+ }+ public close(code = 1006, reason = "") {+ this.dispatchEvent(Object.assign(new Event("close"), { code, reason }));+ }+}++/** An SSE response body the test writes to. */+function body() {+ let controller!: ReadableStreamDefaultController<Uint8Array>;+ const stream = new ReadableStream<Uint8Array>({+ start(c) {+ controller = c;+ },+ });+ return {+ response: new Response(stream, {+ headers: { "Content-Type": "text/event-stream" },+ }),+ push: (text: string) => controller.enqueue(encoder.encode(text)),+ end: () => controller.close(),+ };+}++function collect(events: NotebookEvents<string>) {+ const received: unknown[] = [];+ events.subscribe((event) => received.push(event));+ return received;+}++/** Drive the real session adapter through either network protocol. */+function network(transportType: "websocket" | "sse", url: StreamUrl) {+ const requests: { request: Request; stream: ReturnType<typeof body> }[] = [];+ vi.stubGlobal("WebSocket", FakeSocket);+ vi.stubGlobal(+ "fetch",+ async (input: RequestInfo | URL, init?: RequestInit) => {+ const stream = body();+ requests.push({ request: new Request(input, init), stream });+ return stream.response;+ },+ );+ const count = () =>+ transportType === "websocket" ? FakeSocket.opened.length : requests.length;+ const transport = createNotebookTransport({+ static: false,+ transportType,+ url,+ headers: () => ({}),+ });+ let index = 0;+ return {+ transport,+ count,+ opened: async () => {+ await vi.waitFor(() => expect(count()).toBeGreaterThan(index));+ const next = index++;+ if (transportType === "websocket") {+ const socket = FakeSocket.opened[next];+ socket.open();+ return {+ cursor: new URL(socket.url).searchParams.get("cursor"),+ receive: (frame: { event: string; data: unknown; id?: string }) =>+ socket.receive(JSON.stringify(frame)),+ drop: () => socket.close(),+ stop: () => socket.close(1000, "MARIMO_SHUTDOWN"),+ };+ }+ const { request, stream } = requests[next];+ return {+ cursor: request.headers.get("Last-Event-ID"),+ receive: (frame: { event: string; data: unknown; id?: string }) =>+ stream.push(+ `${frame.id === undefined ? "" : `id: ${frame.id}\n`}event: ${frame.event}\ndata: ${JSON.stringify(frame.data)}\n\n`,+ ),+ drop: stream.end,+ stop: () =>+ stream.push(+ 'event: close\ndata: {"code":1000,"reason":"MARIMO_SHUTDOWN"}\n\n',+ ),+ };+ },+ };+}++afterEach(() => {+ FakeSocket.opened.length = 0;+ wasm.enabled = false;+ wasm.consumer.mockReset();+ vi.unstubAllGlobals();+ vi.useRealTimers();+});++describe("websocket", () => {+ it("resumes with the cursor and reads data with marimo's parser", async () => {+ vi.useFakeTimers();+ vi.stubGlobal("WebSocket", FakeSocket);+ const events = new NotebookEvents(+ websocket(() => "ws://localhost/ws?session_id=s1&cursor=stale"),+ { types: ["marimo"] },+ );+ const received = collect(events);+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));+ const [first] = FakeSocket.opened;+ first.open();+ first.receive(+ '{"event":"marimo","id":"7","data":{"marimo":{"value":NaN}}}',+ );+ first.close();+ await vi.advanceTimersByTimeAsync(2000);+ expect(FakeSocket.opened.map((socket) => socket.url))+ .toMatchInlineSnapshot(`+ [+ "ws://localhost/ws?session_id=s1",+ "ws://localhost/ws?session_id=s1&cursor=7",+ ]+ `);+ expect(received).toEqual([+ { event: "marimo", id: "7", data: { marimo: { value: Number.NaN } } },+ ]);+ events.close();+ });++ it("stops on a close the editor treats as final, with its status", async () => {+ vi.stubGlobal("WebSocket", FakeSocket);+ const events = new NotebookEvents(websocket(() => "ws://localhost/ws"));+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));+ FakeSocket.opened[0].open();+ FakeSocket.opened[0].close(3000, "MARIMO_UNAUTHORIZED");+ const error = await events.closed.catch((error: unknown) => error);+ expect(error).toBeInstanceOf(StreamStopped);+ expect((error as StreamStopped).cause).toMatchInlineSnapshot(`+ {+ "code": "KERNEL_DISCONNECTED",+ "reason": "not authorized",+ "state": "CLOSED",+ }+ `);+ });++ it("passes on a message it cannot read for the stream to reject", async () => {+ vi.stubGlobal("WebSocket", FakeSocket);+ const events = new NotebookEvents(websocket(() => "ws://localhost/ws"));+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));+ FakeSocket.opened[0].open();+ FakeSocket.opened[0].receive("{broken");+ await expect(events.closed).rejects.toThrow("not an event");+ });++ it("retries a socket that never opens", async () => {+ vi.useFakeTimers();+ vi.stubGlobal("WebSocket", FakeSocket);+ const events = new NotebookEvents(websocket(() => "ws://localhost/ws"));+ await vi.waitFor(() => expect(FakeSocket.opened).toHaveLength(1));+ await vi.advanceTimersByTimeAsync(10_000 + 2000);+ expect(FakeSocket.opened).toHaveLength(2);+ events.close();+ });+});++describe("sessionSse", () => {+ it("sends the runtime's headers and the cursor with each request", async () => {+ vi.useFakeTimers();+ const first = body();+ const fetch = vi.fn(+ async (_input: RequestInfo | URL, _init?: RequestInit) => first.response,+ );+ vi.stubGlobal("fetch", fetch);+ let token = "a";+ const events = new NotebookEvents(+ sessionSse(+ () => "http://localhost/sse?session_id=s1",+ () => ({ "Marimo-Server-Token": token }),+ ),+ );+ first.push("id: 9\nevent: ready\ndata: {}\n\n");+ await vi.waitFor(() => expect(events.cursor).toBe("9"));+ token = "b";+ first.end();+ fetch.mockImplementation(async () => body().response);+ await vi.advanceTimersByTimeAsync(2000);+ const requests = fetch.mock.calls.map(+ ([input, init]) => new Request(input, init),+ );+ expect(+ requests.map((request) => ({+ url: request.url,+ token: request.headers.get("Marimo-Server-Token"),+ cursor: request.headers.get("Last-Event-ID"),+ })),+ ).toMatchInlineSnapshot(`+ [+ {+ "cursor": null,+ "token": "a",+ "url": "http://localhost/sse?session_id=s1",+ },+ {+ "cursor": "9",+ "token": "b",+ "url": "http://localhost/sse?session_id=s1",+ },+ ]+ `);+ events.close();+ });++ it("stops on a session close frame the editor treats as final", async () => {+ const stream = body();+ vi.stubGlobal("fetch", async () => stream.response);+ const events = new NotebookEvents(+ sessionSse(+ () => "http://localhost/sse",+ () => ({}),+ ),+ );+ stream.push(+ 'event: close\ndata: {"code":1000,"reason":"MARIMO_SHUTDOWN"}\n\n',+ );+ const error = await events.closed.catch((error: unknown) => error);+ expect((error as StreamStopped).cause).toMatchInlineSnapshot(`+ {+ "code": "KERNEL_DISCONNECTED",+ "reason": "kernel not found",+ "state": "CLOSED",+ }+ `);+ });++ it.each([+ ["NaN", Number.NaN],+ ["Infinity", Number.POSITIVE_INFINITY],+ ["-Infinity", Number.NEGATIVE_INFINITY],+ ['{"$bigint":"9007199254740993"}', BigInt("9007199254740993")],+ ])("reads %s with marimo's parser", async (encoded, value) => {+ const stream = body();+ vi.stubGlobal("fetch", async () => stream.response);+ const events = new NotebookEvents(+ sessionSse(+ () => "http://localhost/sse",+ () => ({}),+ ),+ { types: ["marimo"] },+ );+ const received = collect(events);+ onTestFinished(() => events.close());+ stream.push(`event: marimo\ndata: {"marimo":{"value":${encoded}}}\n\n`);+ await vi.waitFor(() => expect(received).toHaveLength(1));+ expect(received).toEqual([+ { event: "marimo", data: { marimo: { value } } },+ ]);+ });+});++describe.each(["websocket", "sse"] as const)(+ "%s session identity",+ (transportType) => {+ const base =+ transportType === "websocket"+ ? "ws://localhost/ws"+ : "http://localhost/sse";++ it.each(["automatic", "manual"])(+ "discards the cursor and replica when the session changes on %s reconnect",+ async (recovery) => {+ vi.useFakeTimers();+ let target = `${base}?session_id=s1`;+ const url = vi.fn(() => target);+ const connection = network(transportType, url);+ const store = createStore();+ const { client, connect } = createNotebookClient(store);+ const lifetime = new AbortController();+ onTestFinished(() => lifetime.abort());+ connect({+ transport: connection.transport,+ signal: lifetime.signal,+ checkHealth: async () => true,+ onNotification: vi.fn(),+ });+ const first = await connection.opened();+ const snapshot = fixtureMessages("notebook-events.sse");+ snapshot.forEach(first.receive);+ await vi.waitFor(() =>+ expect(store.get(client.notebookAtom)?.id).toBe("n1"),+ );++ target = `${base}?session_id=s2`;+ if (recovery === "automatic") {+ first.drop();+ await vi.advanceTimersByTimeAsync(2000);+ } else {+ first.stop();+ await vi.waitUntil(+ () =>+ store.get(client.connectionAtom).state === ConnectionState.CLOSED,+ );+ await client.reconnect();+ }+ const second = await connection.opened();+ expect({+ cursor: second.cursor,+ notebook: store.get(client.notebookAtom),+ document: store.get(client.documentAtom),+ attachments: store.get(client.attachmentsAtom),+ }).toEqual({+ cursor: null,+ notebook: null,+ document: null,+ attachments: [],+ });++ // A second drop before any records must not resurrect the library's old cursor.+ second.drop();+ await vi.advanceTimersByTimeAsync(2000);+ const third = await connection.opened();+ expect(third.cursor).toBeNull();+ for (const frame of snapshot) {+ third.receive({+ ...frame,+ data: JSON.parse(+ JSON.stringify(frame.data).replaceAll('"n1"', '"n2"'),+ ),+ });+ }+ await vi.waitFor(() =>+ expect(store.get(client.notebookAtom)?.id).toBe("n2"),+ );+ expect(store.get(client.documentAtom)?.revision.notebook_id).toBe("n2");+ expect(url).toHaveBeenCalledTimes(3);+ },+ );++ it("keeps the replica and cursor when only authentication and query ordering change", async () => {+ vi.useFakeTimers();+ let target = `${base}?session_id=s1&file=a.py&access_token=a`;+ const connection = network(transportType, () => target);+ const store = createStore();+ const { client, connect } = createNotebookClient(store);+ const lifetime = new AbortController();+ onTestFinished(() => lifetime.abort());+ connect({+ transport: connection.transport,+ signal: lifetime.signal,+ checkHealth: async () => true,+ onNotification: vi.fn(),+ });+ const first = await connection.opened();+ fixtureMessages("notebook-events.sse").forEach(first.receive);+ await vi.waitFor(() =>+ expect(store.get(client.notebookAtom)?.id).toBe("n1"),+ );+ const document = store.get(client.documentAtom);+ const attachments = store.get(client.attachmentsAtom);++ target = `${base}?access_token=b&file=a.py&session_id=s1`;+ first.drop();+ await vi.advanceTimersByTimeAsync(2000);+ const second = await connection.opened();+ expect(second.cursor).toBe("97");+ expect(store.get(client.documentAtom)).toBe(document);+ second.receive({ event: "ready", id: "100", data: {} });+ await vi.waitFor(() =>+ expect(store.get(client.notebookAtom)?.id).toBe("n1"),+ );+ expect(store.get(client.attachmentsAtom)).toEqual(attachments);+ });++ it("does not open a connection after cancellation during URL resolution", async () => {+ vi.useFakeTimers();+ const target = new Deferred<string>();+ const url = vi.fn(() => target.promise);+ const connection = network(transportType, url);+ const events = new NotebookEvents(connection.transport);+ onTestFinished(() => events.close());+ const received = collect(events);+ await vi.waitFor(() => expect(url).toHaveBeenCalledOnce());+ events.close();+ target.resolve(base);+ await vi.advanceTimersByTimeAsync(0);+ expect({+ opened: connection.count(),+ events: received,+ status: events.status,+ }).toEqual({ opened: 0, events: [], status: "closed" });+ });+ },+);++describe("pyodide", () => {+ it("delivers worker notifications as marimo events and host events as they are", async () => {+ let consumer: ((message: MessageEvent<string>) => void) | undefined;+ const events = new NotebookEvents(+ pyodide((next) => {+ consumer = next;+ }),+ { types: ["notebook", "marimo"] },+ );+ const received = collect(events);+ await vi.waitFor(() => expect(consumer).toBeDefined());+ const send = (data: string) =>+ consumer?.(new MessageEvent("message", { data }));+ send('{"data":{"op":"kernel-ready"}}');+ send('{"event":"marimo","id":"3","data":{"marimo":{"op":"reconnected"}}}');+ expect(received).toMatchInlineSnapshot(`+ [+ {+ "data": {+ "marimo": {+ "op": "kernel-ready",+ },+ },+ "event": "marimo",+ },+ {+ "data": {+ "marimo": {+ "op": "reconnected",+ },+ },+ "event": "marimo",+ "id": "3",+ },+ ]+ `);+ events.close();+ });+});++describe("createNotebookTransport", () => {+ const options = {+ static: false,+ transportType: "websocket" as const,+ url: () => "ws://localhost/ws",+ headers: () => ({}),+ };++ it.each([+ ["a static notebook", { ...options, static: true }, "idle"],+ ["WASM", options, "wasm"],+ ["SSE", { ...options, transportType: "sse" as const }, "fetch"],+ ["the default", options, "socket"],+ ] as const)("follows %s", async (_name, chosen, expected) => {+ wasm.enabled = expected === "wasm";+ const fetch = vi.fn(() => new Promise<Response>(() => undefined));+ vi.stubGlobal("fetch", fetch);+ vi.stubGlobal("WebSocket", FakeSocket);+ const events = new NotebookEvents(createNotebookTransport(chosen));+ await vi.waitFor(() =>+ expect(+ {+ idle:+ events.status === "connected" && !wasm.consumer.mock.calls.length,+ wasm: wasm.consumer.mock.calls.length === 1,+ fetch: fetch.mock.calls.length === 1,+ socket: FakeSocket.opened.length === 1,+ }[expected],+ ).toBe(true),+ );+ events.close();+ });+});diff --git a/frontend/src/core/websocket/transports/notebook.ts b/frontend/src/core/websocket/transports/notebook.tsnew file mode 100644index 0000000000..aa5ce9c85d--- /dev/null+++ b/frontend/src/core/websocket/transports/notebook.ts@@ -0,0 +1,213 @@+/* Copyright 2026 Marimo. All rights reserved. */++import {+ type NotebookTransport,+ sse,+ StreamStopped,+ type StreamUrl,+} from "@marimo-team/client";+import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";+import { PyodideBridge } from "../../wasm/bridge";+import { isWasm } from "../../wasm/utils";+import { classifyCloseEvent } from "../connection-state";++/** The server can be slow to accept when many notebooks are open. */+const CONNECT_MS = 10_000;++/**+ * The error that ends a stream on this close, or none to retry.+ *+ * `cause` is the connection status the editor shows.+ */+function stopOn(close: { code?: number; reason?: string }) {+ const decision = classifyCloseEvent(close);+ if (decision.kind === "retry") {+ return undefined;+ }+ const reason = "reason" in decision.status ? decision.status.reason : "";+ return new StreamStopped(reason, { cause: decision.status });+}++/** Read a URL provider, stopping the stream when it gives up. */+async function resolve(url: StreamUrl): Promise<URL | undefined> {+ try {+ return new URL(typeof url === "function" ? await url() : url);+ } catch (error) {+ if (error instanceof StreamStopped) {+ throw error;+ }+ return undefined;+ }+}++/** A resume cursor and replica belong to the session that produced them. */+function withSessionIdentity(+ url: StreamUrl,+ connect: (target: URL) => NotebookTransport,+): NotebookTransport {+ let previous: string | undefined;+ return async (attempt, handlers) => {+ const target = await resolve(url);+ if (target === undefined || attempt.signal.aborted) {+ return;+ }+ target.searchParams.delete("cursor");+ const identity = new URL(target);+ identity.searchParams.delete("access_token");+ identity.searchParams.sort();+ identity.hash = "";+ const key = identity.toString();+ let { cursor } = attempt;+ if (previous !== undefined && previous !== key) {+ // Reset both the stream's cursor and its subscribers' state.+ handlers.message({ event: "reset", data: {} });+ cursor = null;+ }+ previous = key;+ if (!attempt.signal.aborted) {+ return connect(target)({ ...attempt, cursor }, handlers);+ }+ };+}++/**+ * Follow a marimo session over its WebSocket route.+ *+ * Each attempt opens one socket with the cursor as a query parameter. The+ * editor's close policy decides which closes end the stream.+ *+ * TODO: Notice a connection that died without closing, such as after a laptop+ * sleeps. `/sse` sends a heartbeat that its silence limit relies on, and+ * `/ws` drops it. Sending it on `/ws` would let this transport close a+ * silent socket.+ */+export function websocket(url: StreamUrl): NotebookTransport {+ return withSessionIdentity(+ url,+ (target) =>+ async ({ cursor, signal }, { open, message }) => {+ if (cursor !== null) {+ target.searchParams.set("cursor", cursor);+ }+ await new Promise<void>((settle, reject) => {+ const socket = new WebSocket(target);+ const timeout = setTimeout(() => socket.close(), CONNECT_MS);+ const abort = () => socket.close();+ signal.addEventListener("abort", abort, { once: true });+ socket.addEventListener("open", () => {+ clearTimeout(timeout);+ open();+ });+ socket.addEventListener("message", ({ data }) =>+ // marimo's parser reads `NaN`. A message it cannot read arrives as an+ // empty object, which `NotebookEvents` rejects as not an event.+ message(jsonParseWithSpecialChar(String(data))),+ );+ socket.addEventListener("close", (event) => {+ clearTimeout(timeout);+ signal.removeEventListener("abort", abort);+ const stopped = signal.aborted ? undefined : stopOn(event);+ if (stopped === undefined) {+ settle();+ } else {+ reject(stopped);+ }+ });+ });+ },+ );+}++/**+ * Follow a marimo session over its server-sent events route.+ *+ * The session's `close` frames carry the same reasons as WebSocket closes.+ * marimo's parser decodes tagged bigints and non-finite numbers in every frame.+ */+export function sessionSse(+ url: StreamUrl,+ headers: () => Record<string, string>,+): NotebookTransport {+ return withSessionIdentity(url, (target) =>+ sse(target, {+ parseData: jsonParseWithSpecialChar,+ fetch: (input, init) => {+ const sent = new Headers(init?.headers);+ for (const [name, value] of Object.entries(headers())) {+ sent.set(name, value);+ }+ return globalThis.fetch(input, { ...init, headers: sent });+ },+ stop: (frame) =>+ frame.event === "close"+ ? stopOn(frame.data as { code?: number; reason?: string })+ : undefined,+ }),+ );+}++/** A connection that opens and delivers nothing, for static notebooks. */+const idle: NotebookTransport = ({ signal }, { open }) =>+ new Promise((settle) => {+ open();+ signal.addEventListener("abort", () => settle(), { once: true });+ });++/**+ * Follow the notebook running in the WASM worker.+ *+ * The worker sends marimo notifications as `{ data: notification }`, which+ * arrive as `marimo` events.+ */+export function pyodide(+ attach: (consumer: (message: MessageEvent<string>) => void) => void,+): NotebookTransport {+ return ({ signal }, { open, message }) =>+ new Promise((settle) => {+ open();+ attach(({ data }) => {+ if (signal.aborted) {+ return;+ }+ const value = jsonParseWithSpecialChar(data);+ // The worker sends notifications without the host's event envelope.+ message(+ typeof value === "object" &&+ value !== null &&+ !("event" in value) &&+ "data" in value+ ? { event: "marimo", data: { marimo: value.data } }+ : value,+ );+ });+ signal.addEventListener("abort", () => settle(), { once: true });+ });+}++/** How the editor follows its notebook. */+export interface NotebookTransportOptions {+ static: boolean;+ transportType: "websocket" | "sse";+ /** The session route, read before each connection. */+ url: StreamUrl;+ /** The runtime's headers, read before each request. */+ headers: () => Record<string, string>;+}++/** Choose the transport for the editor's notebook. */+export function createNotebookTransport(+ options: NotebookTransportOptions,+): NotebookTransport {+ if (options.static) {+ return idle;+ }+ if (isWasm()) {+ return pyodide((consumer) =>+ PyodideBridge.INSTANCE.attachMessageConsumer(consumer),+ );+ }+ if (options.transportType === "sse") {+ return sessionSse(options.url, options.headers);+ }+ return websocket(options.url);+}diff --git a/frontend/src/core/websocket/useNotebookClient.ts b/frontend/src/core/websocket/useNotebookClient.tsindex c242df7f91..0d894f2a64 100644--- a/frontend/src/core/websocket/useNotebookClient.ts+++ b/frontend/src/core/websocket/useNotebookClient.ts@@ -1,9 +1,9 @@/* Copyright 2026 Marimo. All rights reserved. */+import { StreamStopped } from "@marimo-team/client";import { useStore } from "jotai";import { useEffect, useMemo } from "react";import useEvent from "react-use-event-hook";-import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";import type {NotificationMessage,NotificationPayload,@@ -12,14 +12,16 @@ import {createNotebookClient,type NotebookClient,} from "../host/notebook-client";-import { classifyCloseEvent } from "./connection-state";import { notebookClientAtom } from "./state";import {- createConnectionTransport,- type ConnectionTransportOptions,-} from "./transports/create";+ createNotebookTransport,+ type NotebookTransportOptions,+} from "./transports/notebook";-type Options = ConnectionTransportOptions & {+type Options = Omit<NotebookTransportOptions, "url"> & {+ /** The session route, read before each connection. */+ url: () => string;+ /** Wait until the host can accept a connection. */waitUntilReady: () => Promise<void>;checkHealth: () => Promise<boolean>;onNotification: (notification: NotificationPayload) => void;@@ -37,24 +39,33 @@ export function useNotebookClient(options: Options): NotebookClient {useEffect(() => {const lifetime = new AbortController();+ let needsInitialReadiness = true;store.set(notebookClientAtom, controller.client);controller.connect({- createTransport: (url) =>- createConnectionTransport({- url,- headers,- static: isStatic,- transportType,- }),- url,+ transport: createNotebookTransport({+ static: isStatic,+ transportType,+ url: async () => {+ if (needsInitialReadiness) {+ // Explicit retries check current health, even if startup failed.+ needsInitialReadiness = false;+ try {+ await waitUntilReady();+ } catch (error) {+ throw new StreamStopped("Healthy connection never made", {+ cause: error,+ });+ }+ }+ return url();+ },+ headers,+ }),signal: lifetime.signal,- waitUntilReady,checkHealth,// The host validates the envelope, not the native notification contents.onNotification: (notification) =>onNotification({ data: notification as NotificationMessage }),- decodeJson: jsonParseWithSpecialChar,- classifyClose: classifyCloseEvent,});return () => {lifetime.abort();diff --git a/packages/client/TRANSPORTS.md b/packages/client/TRANSPORTS.mdindex 3d1ad49e78..d4bac3fa7b 100644--- a/packages/client/TRANSPORTS.md+++ b/packages/client/TRANSPORTS.md@@ -15,7 +15,8 @@ is aborted.Resolve when the connection ends and another attempt makes sense. Rejectwhen the stream should stop. The stream's `closed` promise rejects with the-same error. Use `StreamStopped` to describe the failure.+same error. Use `StreamStopped` to describe the failure. Calls to `open()` or+`message(event)` after the promise settles are ignored.The stream validates events, tracks the cursor, delivers events tosubscribers, and reconnects. It delivers `reset` when an interrupted snapshot@@ -49,5 +50,9 @@ const events = new NotebookEvents(The URL function runs before each connection. A `StreamStopped` it throwsstops the stream.+Set `parseData` to decode each frame's raw data with a custom parser. It runs+before `stop` and event delivery. The default is `JSON.parse`; if the parser+throws, the frame keeps its original text.+See the [transport contract](src/transport/frame.ts) for the function andevent types.diff --git a/packages/client/src/__tests__/notebook-events.test.ts b/packages/client/src/__tests__/notebook-events.test.tsindex baa43c4d32..0b6c96f0e4 100644--- a/packages/client/src/__tests__/notebook-events.test.ts+++ b/packages/client/src/__tests__/notebook-events.test.ts@@ -55,6 +55,18 @@ function answering(...responses: Response[]) {return { fetch, sent };}+/** A transport whose connections deliver an event and drop after `uptime`. */+function dropsAfter(uptime: number) {+ let opened = 0;+ const transport: NotebookTransport = (_attempt, { open, message }) => {+ opened += 1;+ open();+ message({ event: "marimo", data: {}, id: String(opened) });+ return new Promise((resolve) => setTimeout(resolve, uptime));+ };+ return { transport, opened: () => opened };+}+function collect<K extends string>(events: NotebookEvents<K>) {const received: NotebookEvent<K>[] = [];events.subscribe((event) => received.push(event));@@ -253,6 +265,47 @@ describe("NotebookEvents", () => {events.close();});+ it("gives up on a host that drops each connection soon after opening", async () => {+ vi.useFakeTimers();+ const { transport, opened } = dropsAfter(1000);+ const events = new NotebookEvents(transport, { types: ["marimo"] });+ await vi.advanceTimersByTimeAsync(200_000);+ expect(events.status).toBe("closed");+ expect(opened()).toBe(11);+ });++ it("keeps following a host whose connections stay up", async () => {+ vi.useFakeTimers();+ const { transport, opened } = dropsAfter(5000);+ const events = new NotebookEvents(transport, { types: ["marimo"] });+ await vi.advanceTimersByTimeAsync(200_000);+ expect(events.status).not.toBe("closed");+ expect(opened()).toBeGreaterThan(11);+ events.close();+ });++ it("ignores a connection that reports after its attempt ended", async () => {+ let late: Parameters<NotebookTransport>[1] | undefined;+ const transport: NotebookTransport = async (_attempt, handlers) => {+ late ??= handlers;+ };+ const statuses: string[] = [];+ const events = new NotebookEvents(transport, {+ types: ["marimo"],+ onStatus: (status) => statuses.push(status),+ });+ const received = collect(events);+ await vi.waitFor(() => expect(late).toBeDefined());+ // Let the attempt end. The stream is then waiting to reconnect.+ await new Promise((resolve) => setTimeout(resolve, 10));+ late?.open();+ late?.message({ event: "marimo", data: {}, id: "9" });+ expect(statuses).toEqual([]);+ expect(received).toEqual([]);+ expect(events.cursor).toBeNull();+ events.close();+ });+it("delivers reset before replacing an interrupted snapshot", async () => {vi.useFakeTimers();const first = body();@@ -605,6 +658,33 @@ describe("NotebookEvents", () => {});describe("sse", () => {+ it("decodes raw data before stop and delivery, retaining text on parse errors", async () => {+ const stream = body();+ const message = vi.fn();+ const stop = vi.fn(() => undefined);+ const transport = sse(url, {+ fetch: answering(stream.response).fetch,+ parseData: (text) =>+ JSON.parse(text, (_key, value) =>+ typeof value === "number" ? BigInt(value) : value,+ ),+ stop,+ });+ stream.push('event: marimo\ndata: {"marimo":\ndata: {"value":42}}\n\n');+ stream.push("event: custom\ndata: plain text\n\n");+ stream.end();+ await transport(+ { cursor: null, signal: new AbortController().signal },+ { open: vi.fn(), message },+ );+ const frames = [+ { event: "marimo", data: { marimo: { value: 42n } } },+ { event: "custom", data: "plain text" },+ ];+ expect(stop.mock.calls).toEqual(frames.map((frame) => [frame]));+ expect(message.mock.calls).toEqual(frames.map((frame) => [frame]));+ });+it("reads a URL given as a function before each connection", async () => {vi.useFakeTimers();const first = body();diff --git a/packages/client/src/transport/events.ts b/packages/client/src/transport/events.tsindex f98e428e46..892cd926fc 100644--- a/packages/client/src/transport/events.ts+++ b/packages/client/src/transport/events.ts@@ -11,12 +11,21 @@ import {report,} from "./stream.ts";-/** Attempts in a row without an event before the stream gives up. */+/** Failed attempts in a row before the stream gives up. */const ATTEMPTS = 10;-/** The delay before reconnecting, which grows with each attempt in a row. */+/** How long a connection stays open after its first event to count as healthy. */+const HEALTHY_MS = 5000;++/**+ * The delay before reconnecting, which grows with each failed attempt in a row.+ *+ * Ten attempts wait about 77 seconds in all. Each delay varies by a quarter+ * either way, so clients that lost the same host do not reconnect in step.+ */function delay(attempt: number): number {- return Math.min(1000 * 1.3 ** attempt, 10_000);+ const backoff = Math.min(1000 * 1.5 ** (attempt - 1), 15_000);+ return backoff * (0.75 + Math.random() / 2);}/** Whether a stream is receiving events. */@@ -56,7 +65,8 @@ function sleep(ms: number, signal: AbortSignal): Promise<void> {** - It starts with a snapshot that ends in `ready`, then delivers changes.* - After a dropped connection it resumes from its cursor, backing off between- * attempts. It stops after ten attempts in a row without a message.+ * attempts. It stops after ten failed attempts in a row. An attempt fails+ * unless its connection stayed open for five seconds after its first event.* - When it cannot resume, it delivers `reset` and a fresh snapshot follows.* The caller discards what it built on `reset`.*/@@ -229,21 +239,27 @@ export class Events<const { signal } = this.#controller;let attempt = 0;while (!signal.aborted) {+ // Callbacks from an attempt that ended are ignored.+ let current = true;+ let healthy = false;+ let uptime: ReturnType<typeof setTimeout> | undefined;try {const cursor = this.#stream.resume();await transport({ cursor, signal },{open: () => {- if (this.#settle !== undefined) {+ if (current && this.#settle !== undefined) {this.#setStatus("connected");}},message: (message) => {- if (this.#settle === undefined) {+ if (!current || this.#settle === undefined) {return;}- attempt = 0;+ uptime ??= setTimeout(() => {+ healthy = true;+ }, HEALTHY_MS);try {this.#stream.receive(message);} catch (error) {@@ -257,12 +273,17 @@ export class Events<} catch (error) {this.#finish()?.reject(error);return;+ } finally {+ current = false;+ clearTimeout(uptime);}if (signal.aborted) {return;}this.#setStatus("connecting");- attempt += 1;+ // A host that drops each connection soon after opening it still runs+ // out of attempts.+ attempt = healthy ? 1 : attempt + 1;if (attempt > ATTEMPTS) {this.#finish()?.reject(new StreamStopped("The host could not be reached"),diff --git a/packages/client/src/transport/frame.ts b/packages/client/src/transport/frame.tsindex e0a376b37c..a1ab30a5ba 100644--- a/packages/client/src/transport/frame.ts+++ b/packages/client/src/transport/frame.ts@@ -45,9 +45,9 @@ export interface Handlers {* The event stream calls it again for each attempt. It resolves when the* connection ended and another attempt makes sense. It rejects when the* stream should stop, preferably with a `StreamStopped` that says why, and- * `closed` rejects with the same error. It sends the cursor however its host- * expects, and leaves reconnecting, validation, and the cursor's value to- * the event stream.+ * `closed` rejects with the same error. Calls to the handlers after it+ * settles are ignored. It sends the cursor however its host expects, and+ * leaves reconnecting, validation, and the cursor's value to the event stream.*/export type Transport = (attempt: Attempt, handlers: Handlers) => Promise<void>;diff --git a/packages/client/src/transport/sse.ts b/packages/client/src/transport/sse.tsindex e8be036df8..1cc4eb76ab 100644--- a/packages/client/src/transport/sse.ts+++ b/packages/client/src/transport/sse.ts@@ -9,7 +9,7 @@ const SILENCE_MS = 45_000;/** Parse server-sent events from decoded text. */export class ServerSentEventStream extends TransformStream<string, Frame> {- public constructor() {+ public constructor(parseData: (text: string) => unknown = JSON.parse) {let buffer = "";let event = "";let data: string[] = [];@@ -19,7 +19,7 @@ export class ServerSentEventStream extends TransformStream<string, Frame> {const text = data.join("\n");let value: unknown = text;try {- value = JSON.parse(text);+ value = parseData(text);} catch {// Unknown events need not carry JSON.}@@ -80,8 +80,10 @@ export type StreamUrl =| URL| (() => string | URL | Promise<string | URL>);-/** How `sse` reaches its host and which frames end the stream. */+/** How `sse` reaches its host, decodes data, and ends the stream. */export interface SseOptions extends ClientOptions {+ /** Decode each frame's data. Defaults to JSON.parse; on error, keep the text. */+ readonly parseData?: (text: string) => unknown;/*** Decide whether a frame outside the protocol ends the stream.*@@ -157,7 +159,7 @@ export function sse(url: StreamUrl, options: SseOptions = {}): Transport {const reader = response.body.pipeThrough(heard).pipeThrough(new TextDecoderStream())- .pipeThrough(new ServerSentEventStream())+ .pipeThrough(new ServerSentEventStream(options.parseData)).getReader();controller.signal.addEventListener("abort", () => void reader.cancel(), {once: true,