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
Keep the confirmed document in `NotebookClient` (#11349)
Trevor Manz01644d67ec15
diff --git a/frontend/src/core/host/AGENTS.md b/frontend/src/core/host/AGENTS.mdindex 3357d7bca1..376c9249f6 100644--- a/frontend/src/core/host/AGENTS.md+++ b/frontend/src/core/host/AGENTS.md@@ -4,3 +4,8 @@ Production code may import host modules, `jotai/vanilla`, `zod`, and`@/utils/Logger`. Enforced by `marimo/host-imports`. Tests are exempt.Define interfaces here and inject application behavior through adapters.++`stream.ts` reduces stream events into one state. Each kind of object is a+`Resource` in `resources/` with pure handlers keyed by event name. The stream+handles phase, notebook identity, and control events itself. The client holds+one state atom and exposes derived atoms.diff --git a/frontend/src/core/host/__tests__/document.test.ts b/frontend/src/core/host/__tests__/document.test.tsnew file mode 100644index 0000000000..b2a8fc97ab--- /dev/null+++ b/frontend/src/core/host/__tests__/document.test.ts@@ -0,0 +1,124 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { describe, expect, it } from "vitest";+import type { NotebookEvent } from "../events";+import { document } from "../resources/document";+import { createStream } from "../stream";+import { fixtureEvents } from "./fixtures";++const stream = createStream({ document });+const snapshot = fixtureEvents("notebook-events.sse");+const edits = fixtureEvents("edits.sse");++function replay(events: readonly NotebookEvent[], from = stream.initial) {+ return events.reduce((state, event) => stream.reduce(state, event), from);+}++const confirmed = () => replay(snapshot);+const current = (state: ReturnType<typeof replay>) =>+ state.resources.document.current;++describe("document resource", () => {+ it("publishes the snapshot at ready, then each completed edit and save", () => {+ const ready = snapshot.findIndex((event) => event.event === "ready");+ const opening = replay(snapshot.slice(0, ready));+ expect(current(opening)).toBeNull();+ const first = current(replay(snapshot.slice(ready), opening));+ expect(first?.revision.order).toEqual(["c1", "c3", "k7f2"]);+ expect([...first!.cells.keys()]).toEqual(first?.revision.order);++ const [edit, save] = edits.filter((event) => event.event === "document");+ const pending = replay(+ edits.filter((event) => event.event !== "document"),+ confirmed(),+ );+ expect(current(pending)).toEqual(first);+ const changed = stream.reduce(pending, edit);+ expect(current(changed)?.revision).toEqual(edit.data.document);+ expect([...current(changed)!.cells.keys()].toSorted()).toEqual(+ edit.data.document.order.toSorted(),+ );+ const saved = current(stream.reduce(changed, save));+ expect(saved?.revision).toEqual(save.data.document);+ expect(saved?.cells.get("c3")?.code).toBe("x = 22");+ expect(saved?.cells.has("k7f2")).toBe(false);+ expect(saved?.revision.saved_etag).toBe(saved?.revision.etag);+ expect(first?.cells.get("c3")?.code).toBe("x = 21");+ expect(first?.cells.has("k7f2")).toBe(true);+ });++ it("applies order-only changes and distinguishes an empty notebook from no document", () => {+ const state = confirmed();+ const revision = current(state)!.revision;+ const reordered = {+ ...revision,+ order: revision.order.toReversed(),+ version: revision.version + 1,+ };+ const changed = stream.reduce(state, {+ event: "document",+ data: { document: reordered },+ id: "200",+ });+ expect(current(changed)).toEqual({+ revision: reordered,+ cells: current(state)?.cells,+ });++ const empty = { ...revision, order: [] };+ const opening = stream.reduce(stream.initial, {+ event: "document",+ data: { document: empty },+ });+ expect(current(opening)).toBeNull();+ expect(+ current(stream.reduce(opening, { event: "ready", data: {}, id: "0" })),+ ).toEqual({ revision: empty, cells: new Map() });+ expect(+ current(+ stream.reduce(stream.initial, { event: "ready", data: {}, id: "0" }),+ ),+ ).toBeNull();+ });++ it("keeps the document while a live update is pending and after a replay completes it", () => {+ const state = confirmed();+ const [cell, , removed, published] = edits;+ if (published.event !== "document") {+ throw new Error("Fixture does not publish a document");+ }+ const partial = replay([cell, removed], state);+ expect(current(partial)).toBe(current(state));+ expect(stream.resume(partial)).toBe(partial);+ const completed = replay(+ [published, { event: "ready", data: {}, id: "113" }],+ partial,+ );+ expect(current(completed)?.revision).toEqual(published.data.document);+ });++ it("removes a notebook without waiting for individual cell removals", () => {+ const removed = stream.reduce(confirmed(), {+ event: "notebook.removed",+ data: { id: "n1", time: "2026-10-01T09:30:00Z" },+ id: "200",+ });+ expect(current(removed)).toBeNull();+ });++ it("rejects records that cannot form a complete revision", () => {+ const state = confirmed();+ const revision = current(state)!.revision;+ expect(() =>+ stream.reduce(state, {+ event: "document",+ data: { document: { ...revision, order: ["missing"] } },+ id: "200",+ }),+ ).toThrow("Document records do not match");+ const partial = stream.reduce(state, edits[0]);+ expect(() =>+ stream.reduce(partial, { event: "ready", data: {}, id: "200" }),+ ).toThrow("incomplete document update");+ });+});diff --git a/frontend/src/core/host/__tests__/fixtures.ts b/frontend/src/core/host/__tests__/fixtures.tsnew file mode 100644index 0000000000..69f4fd370b--- /dev/null+++ b/frontend/src/core/host/__tests__/fixtures.ts@@ -0,0 +1,39 @@+/* Copyright 2026 Marimo. All rights reserved. */++import NodeFs from "node:fs";+import NodeUrl from "node:url";+import { parseNotebookEvent, type NotebookEvent } from "../events";++/** Read the protocol's portable examples as transport messages. */+export function fixtureMessages(name: string) {+ const path = new NodeUrl.URL(+ `../../../../../protocols/host/fixtures/${name}`,+ import.meta.url,+ );+ return NodeFs.readFileSync(path, "utf8")+ .split(/\r?\n\r?\n/)+ .flatMap((frame) => {+ const event = /^event: (.+)$/m.exec(frame)?.[1];+ if (!event) {+ return [];+ }+ const data = frame+ .split(/\r?\n/)+ .filter((line) => line.startsWith("data:"))+ .map((line) => line.slice(5).trimStart())+ .join("\n");+ const payload: unknown = JSON.parse(data);+ return [+ {+ event,+ id: /^id: (.+)$/m.exec(frame)?.[1],+ data: payload,+ },+ ];+ });+}++/** Read the protocol's portable examples as decoded notebook events. */+export function fixtureEvents(name: string): NotebookEvent[] {+ return fixtureMessages(name).map(parseNotebookEvent);+}diff --git a/frontend/src/core/host/__tests__/notebook-client.test.ts b/frontend/src/core/host/__tests__/notebook-client.test.tsindex 0fc964742c..68bbaf9153 100644--- a/frontend/src/core/host/__tests__/notebook-client.test.ts+++ b/frontend/src/core/host/__tests__/notebook-client.test.ts@@ -8,13 +8,30 @@ import { Deferred } from "@/utils/Deferred";import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";import { classifyCloseEvent } from "../../websocket/connection-state";import { createNotebookClient } from "../notebook-client";+import { fixtureMessages } from "./fixtures";-function setup() {+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 } });+}++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(),+ reconnect: vi.fn(() => {+ urls.push(new URL(provider()));+ }),close: vi.fn(() => events.dispatchEvent(new CloseEvent("close"))),send: vi.fn(),addEventListener: events.addEventListener.bind(events),@@ -27,8 +44,11 @@ function setup() {const client = controller.client;const connect = (signal: AbortSignal) =>controller.connect({- createTransport: () => transport,- url: () => "ws://localhost/ws",+ createTransport: (next) => {+ provider = next;+ return transport;+ },+ url,messageFormat: "host",signal,waitUntilReady: () => healthy.promise,@@ -47,6 +67,11 @@ function setup() {onNotification,store,checkHealth,+ urls,+ receive: (message: unknown) =>+ events.dispatchEvent(+ new MessageEvent("message", { data: JSON.stringify(message) }),+ ),};}@@ -79,6 +104,93 @@ describe("NotebookClient lifetime", () => {},);+ 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);+ }+ 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();+ });++ 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"));+ const snapshot = fixtureMessages("notebook-events.sse");+ for (const message of snapshot.slice(0, -3)) {+ receive(message);+ }+ expect(store.get(client.documentAtom)).toBeNull();+ for (const message of snapshot.slice(-3)) {+ receive(message);+ }+ expect(store.get(client.documentAtom)?.revision.order).toEqual([+ "c1",+ "c3",+ "k7f2",+ ]);+ events.dispatchEvent(new CloseEvent("close"));+ expect(store.get(client.documentAtom)?.revision.order).toEqual([+ "c1",+ "c3",+ "k7f2",+ ]);+ lifetime.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(["MARIMO_UNAUTHORIZED", "MARIMO_TRANSPORT_EXHAUSTED"])("stops automatic recovery after %s but permits an explicit reconnect",async (reason) => {diff --git a/frontend/src/core/host/__tests__/stream.test.ts b/frontend/src/core/host/__tests__/stream.test.tsnew file mode 100644index 0000000000..ffe80690a2--- /dev/null+++ b/frontend/src/core/host/__tests__/stream.test.ts@@ -0,0 +1,211 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { describe, expect, it } from "vitest";+import type { NotebookEvent } from "../events";+import type { Resource } from "../resources/resource";+import { createStream, type Stream, type StreamState } from "../stream";+import { fixtureEvents } from "./fixtures";++interface CellIds {+ readonly ids: readonly string[];+}++/** A resource whose events are complete on their own. */+const cells: Resource<CellIds> = {+ initial: { ids: [] },+ on: {+ cell: (state, event) =>+ state.ids.includes(event.data.cell.id)+ ? state+ : { ids: [...state.ids, event.data.cell.id] },+ "cell.removed": (state, event) =>+ state.ids.includes(event.data.id)+ ? { ids: state.ids.filter((id) => id !== event.data.id) }+ : state,+ },+};++interface Revisions {+ /** Cells changed since the last revision. */+ readonly pending: readonly string[];+ readonly published: readonly (readonly string[])[];+}++function publish(state: Revisions): Revisions {+ return { pending: [], published: [...state.published, state.pending] };+}++/** A resource assembled from groups of events, like a document from its cells. */+const revisions: Resource<Revisions> = {+ initial: { pending: [], published: [] },+ on: {+ cell: (state, event) => ({+ ...state,+ pending: [...state.pending, event.data.cell.id],+ }),+ "cell.removed": (state, event) => ({+ ...state,+ pending: [...state.pending, event.data.id],+ }),+ // A live revision completes a group. A snapshot's revision waits for ready.+ document: (state, _event, { phase }) =>+ phase === "live" ? publish(state) : state,+ ready: publish,+ },+};++interface Resources {+ cells: CellIds;+ revisions: Revisions;+}+type State = StreamState<Resources>;++function replay(+ stream: Stream<Resources>,+ events: readonly NotebookEvent[],+ from: State = stream.initial,+): State {+ return events.reduce((state, event) => stream.reduce(state, event), from);+}++const snapshot = fixtureEvents("notebook-events.sse");+const ready = snapshot.findIndex((event) => event.event === "ready");+const cellEvent = snapshot.find((event) => event.event === "cell");+if (cellEvent?.event !== "cell") {+ throw new Error("Fixture is missing a cell event");+}++describe("notebook stream", () => {+ it("reads the snapshot, goes live at ready, and rebuilds after reset", () => {+ const stream = createStream({ cells, revisions });+ const partial = replay(stream, snapshot.slice(0, ready));+ expect(partial).toMatchObject({+ phase: "snapshot",+ notebookId: "n1",+ cursor: null,+ });+ expect(partial.resources.cells.ids).toEqual(["c1", "c3", "k7f2"]);+ expect(partial.resources.revisions).toEqual({+ pending: ["c1", "c3", "k7f2"],+ published: [],+ });++ const live = replay(stream, snapshot.slice(ready), partial);+ expect(live).toMatchObject({ phase: "live", cursor: "97" });+ expect(live.resources.cells).toBe(partial.resources.cells);+ expect(live.resources.revisions).toEqual({+ pending: [],+ published: [["c1", "c3", "k7f2"]],+ });++ const resetEvents = fixtureEvents("events-reset.sse");+ const afterReset = stream.reduce(live, resetEvents[0]);+ expect(afterReset).toEqual({ ...stream.initial, notebookId: "n1" });+ expect(replay(stream, resetEvents, live).phase).toBe("live");+ });++ it("keeps resource state by reference when an event does not apply", () => {+ const stream = createStream({ cells, revisions });+ const state = replay(stream, snapshot);+ const runtime = snapshot.find((event) => event.event === "runtime");+ const unhandled = stream.reduce(state, { ...runtime!, id: "100" });+ expect(unhandled.resources).toBe(state.resources);+ expect(unhandled.cursor).toBe("100");+ expect(+ stream.reduce(state, { event: "unknown", name: "x", id: "101" })+ .resources,+ ).toBe(state.resources);+ expect(+ stream.reduce(state, { event: "marimo", data: { marimo: {} } }),+ ).toBe(state);+ });++ it("clears resources when its notebook is removed and ignores other notebooks", () => {+ const stream = createStream({ cells, revisions });+ const state = replay(stream, snapshot);+ const time = "2026-10-01T09:30:00Z";+ expect(+ stream.reduce(state, {+ event: "notebook.removed",+ id: "100",+ data: { id: "n2", time },+ }).resources,+ ).toBe(state.resources);+ const removed = stream.reduce(state, {+ event: "notebook.removed",+ id: "100",+ data: { id: "n1", time },+ });+ expect(removed).toMatchObject({ phase: "live", notebookId: "n1" });+ expect(removed.resources).toBe(stream.initial.resources);+ });++ it("rejects objects from another notebook", () => {+ const stream = createStream({ cells, revisions });+ const state = replay(stream, snapshot.slice(0, ready));+ const notebook = snapshot[0];+ if (notebook.event !== "notebook") {+ throw new Error("Fixture does not start with its notebook");+ }+ expect(() =>+ stream.reduce(state, {+ ...notebook,+ data: { notebook: { ...notebook.data.notebook, id: "n2" } },+ }),+ ).toThrow("changed identity");+ expect(() =>+ stream.reduce(state, {+ ...cellEvent,+ data: { cell: { ...cellEvent.data.cell, notebook_id: "n2" } },+ }),+ ).toThrow("changed identity");+ });++ it("records each live event's cursor and resumes in place", () => {+ const stream = createStream({ cells, revisions });+ const partial = replay(stream, snapshot.slice(0, ready));+ expect(stream.resume(partial)).toEqual({+ ...stream.initial,+ notebookId: "n1",+ });++ const live = replay(stream, snapshot.slice(ready), partial);+ const [cell, , removed, published, saved] = fixtureEvents("edits.sse");+ const editing = replay(stream, [cell], live);+ expect(editing.cursor).toBe("110");+ expect(editing.resources.revisions.pending).toEqual(["c2"]);+ expect(stream.resume(editing)).toBe(editing);++ const edited = replay(stream, [removed, published], editing);+ expect(edited.cursor).toBe("113");+ expect(edited.resources.revisions).toEqual({+ pending: [],+ published: [+ ["c1", "c3", "k7f2"],+ ["c2", "k7f2"],+ ],+ });+ expect(stream.reduce(edited, saved).cursor).toBe("114");+ expect(+ stream.reduce(edited, { event: "ready", id: "116", data: {} }).cursor,+ ).toBe("116");+ expect(stream.reduce(edited, { event: "reset", data: {} }).cursor).toBe(+ null,+ );+ });++ it("requires a cursor on live events other than reset and notifications", () => {+ const stream = createStream({ cells, revisions });+ const state = replay(stream, snapshot);+ expect(() => stream.reduce(state, cellEvent)).toThrow("cursor");+ expect(+ stream.reduce(state, { ...cellEvent, id: "100" }).resources.cells,+ ).toBe(state.resources.cells);+ expect(stream.reduce(state, { event: "reset", data: {} }).phase).toBe(+ "snapshot",+ );+ expect(+ stream.reduce(state, { event: "marimo", data: { marimo: null } }),+ ).toBe(state);+ });+});diff --git a/frontend/src/core/host/notebook-client.ts b/frontend/src/core/host/notebook-client.tsindex 54318a352f..51fbe73eee 100644--- a/frontend/src/core/host/notebook-client.ts+++ b/frontend/src/core/host/notebook-client.ts@@ -11,11 +11,21 @@ import {TransportReadyState,} from "./connection";import { parseNotebookEvent } from "./events";+import { type Document, document } from "./resources/document";+import { createStream } from "./stream";/** A connection to a notebook on a marimo host. */export interface NotebookClient {/** Client connection status, independent of application session readiness. */readonly connectionAtom: Atom<ConnectionStatus>;+ /**+ * The most recently confirmed document.+ *+ * Null until a snapshot is complete, after reset or removal, and on+ * connections without host document events. A temporary disconnection+ * retains the last document. Partial updates are not exposed.+ */+ readonly documentAtom: Atom<Document | null>;/** Attempt to restore a closed connection after checking host health. */reconnect(): Promise<void>;}@@ -49,9 +59,16 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {const connectionAtom = atom<ConnectionStatus>({state: ConnectionState.NOT_STARTED,});+ // One atom holds the whole stream, which resource atoms derive from.+ const stream = createStream({ document });+ const streamAtom = atom(stream.initial);+ const documentAtom = atom(+ (get) => get(streamAtom).resources.document.current,+ );let reconnect: (() => Promise<void>) | undefined;const client: NotebookClient = {connectionAtom,+ documentAtom,reconnect: async () => reconnect?.(),};@@ -73,7 +90,33 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {let shouldRetry = true;let terminal = false;let checkingHealth = false;- const transport = createTransport(url);+ let streamKey: string | undefined;+ const transport = createTransport(() => {+ if (messageFormat === "session") {+ return url();+ }+ 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 state =+ key === streamKey+ ? stream.resume(store.get(streamAtom))+ : stream.initial;+ streamKey = key;+ store.set(streamAtom, state);+ if (state.cursor !== null) {+ next.searchParams.set("cursor", state.cursor);+ }+ return next.toString();+ });const setStatus = (status: ConnectionStatus) =>store.set(connectionAtom, status);const disconnected = {@@ -130,12 +173,14 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {let event;try {event = parseNotebookEvent(decodeJson(message.data));+ store.set(streamAtom, stream.reduce(store.get(streamAtom), event));} catch (error) {Logger.error("Failed to decode notebook message", error);if (messageFormat === "session") {onMessageError(error);return;}+ store.set(streamAtom, stream.initial);terminal = true;setStatus({...disconnected,@@ -193,6 +238,7 @@ export function createNotebookClient(store: ReturnType<typeof createStore>) {transport.removeEventListener("message", onMessage);transport.close();reconnect = undefined;+ store.set(streamAtom, stream.initial);setStatus({ state: ConnectionState.NOT_STARTED });},{ once: true },diff --git a/frontend/src/core/host/resources/document.ts b/frontend/src/core/host/resources/document.tsnew file mode 100644index 0000000000..a048b307ff--- /dev/null+++ b/frontend/src/core/host/resources/document.ts@@ -0,0 +1,101 @@+/* Copyright 2026 Marimo. All rights reserved. */++import type * as Protocol from "../protocol";+import type { Resource } from "./resource";++/**+ * The notebook's content at one revision.+ *+ * The revision record carries the cell order, app config, etags, and+ * version. Each cell in its order has a record in `cells`.+ */+export interface Document {+ readonly revision: Protocol.Document;+ readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;+}++/** The records of a revision still being received. */+interface PendingDocument {+ /** Null until the `document` event that closes the group arrives. */+ readonly revision: Protocol.Document | null;+ readonly cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>;+}++/**+ * The confirmed document and the revision being assembled after it.+ *+ * A snapshot's records are pending until `ready`. A live revision is pending+ * from its first cell until its `document` event.+ */+export interface DocumentState {+ readonly current: Document | null;+ readonly pending: PendingDocument | null;+}++function pendingOf(state: DocumentState): PendingDocument {+ return (+ state.pending ?? {+ revision: state.current?.revision ?? null,+ cells: state.current?.cells ?? new Map(),+ }+ );+}++/** Confirm a revision whose records are complete. */+function publish(+ revision: Protocol.Document,+ cells: ReadonlyMap<Protocol.CellId, Protocol.Cell>,+): DocumentState {+ const order = new Set(revision.order);+ if (+ order.size !== revision.order.length ||+ order.size !== cells.size ||+ [...order].some((id) => !cells.has(id)) ||+ [...cells.values()].some((cell) => cell.version > revision.version)+ ) {+ throw new Error("Document records do not match its revision and order");+ }+ return { current: { revision, cells }, pending: null };+}++export const document: Resource<DocumentState> = {+ initial: { current: null, pending: null },+ on: {+ cell: (state, { data }) => {+ const pending = pendingOf(state);+ return {+ ...state,+ pending: {+ revision: pending.revision,+ cells: new Map(pending.cells).set(data.cell.id, data.cell),+ },+ };+ },+ "cell.removed": (state, { data }) => {+ const pending = pendingOf(state);+ if (!pending.cells.has(data.id)) {+ return state;+ }+ const cells = new Map(pending.cells);+ cells.delete(data.id);+ return { ...state, pending: { ...pending, cells } };+ },+ document: (state, { data }, { phase }) => {+ const { cells } = pendingOf(state);+ return phase === "snapshot"+ ? { ...state, pending: { revision: data.document, cells } }+ : publish(data.document, cells);+ },+ ready: (state, _event, { phase }) => {+ if (state.pending === null) {+ return state;+ }+ if (phase === "live") {+ throw new Error("Stream ended with an incomplete document update");+ }+ return state.pending.revision === null+ ? { current: null, pending: null }+ : publish(state.pending.revision, state.pending.cells);+ },+ },+};diff --git a/frontend/src/core/host/resources/resource.ts b/frontend/src/core/host/resources/resource.tsnew file mode 100644index 0000000000..4164bdae1d--- /dev/null+++ b/frontend/src/core/host/resources/resource.ts@@ -0,0 +1,59 @@+/* Copyright 2026 Marimo. All rights reserved. */++import type * as Protocol from "../protocol";++/** An event name from the protocol. */+export type EventName = Protocol.EventOutput["event"];++/** The decoded event with the given name. */+export type EventOf<Name extends EventName> = Extract<+ Protocol.EventOutput,+ { event: Name }+>;++/**+ * Events the stream handles itself.+ *+ * They identify the notebook, discard state, or carry a native+ * notification. Resources do not receive them.+ */+export type StreamEventName =+ | "reset"+ | "notebook"+ | "notebook.removed"+ | "marimo";++/** Events a resource may handle. `ready` marks the end of the snapshot. */+export type ResourceEventName = Exclude<EventName, StreamEventName>;++/** `snapshot` until `ready` arrives and `live` after it. */+export type StreamPhase = "snapshot" | "live";++/** What a handler may know about the stream beyond the event. */+export interface HandlerContext {+ readonly phase: StreamPhase;+}++/**+ * A pure handler for each event the resource reads.+ *+ * A handler returns `state` when the event does not apply to it.+ */+export type EventHandlers<State> = {+ readonly [Name in ResourceEventName]?: (+ state: State,+ event: EventOf<Name>,+ context: HandlerContext,+ ) => State;+};++/**+ * One kind of object assembled from its events.+ *+ * The stream returns a resource to `initial` on `reset` and when the+ * notebook is removed.+ */+export interface Resource<State> {+ readonly initial: State;+ readonly on: EventHandlers<State>;+}diff --git a/frontend/src/core/host/stream.ts b/frontend/src/core/host/stream.tsnew file mode 100644index 0000000000..4f009b3cb9--- /dev/null+++ b/frontend/src/core/host/stream.ts@@ -0,0 +1,213 @@+/* Copyright 2026 Marimo. All rights reserved. */++import type { NotebookEvent } from "./events";+import type * as Protocol from "./protocol";+import type {+ EventOf,+ HandlerContext,+ Resource,+ ResourceEventName,+ StreamPhase,+} from "./resources/resource";++/** A resource for each entry of a state map under the same name. */+export type Resources<States> = {+ readonly [Name in keyof States]: Resource<States[Name]>;+};++/**+ * The state of one notebook stream.+ *+ * Holds the phase, the notebook identity, the resume cursor, and the state+ * of each resource.+ */+export interface StreamState<States> {+ readonly phase: StreamPhase;+ /**+ * The notebook the stream describes.+ *+ * Retained across `reset`.+ */+ readonly notebookId: Protocol.NotebookIdOutput | null;+ /**+ * The id of the last live event.+ *+ * Null before `ready` and after `reset`.+ */+ readonly cursor: string | null;+ /** The state of each resource by name. */+ readonly resources: States;+}++/** A reducer over the events of one notebook stream. */+export interface Stream<States> {+ readonly initial: StreamState<States>;+ /**+ * Apply one event.+ *+ * Throws on a live event without a cursor or on an object from another+ * notebook.+ */+ reduce(state: StreamState<States>, event: NotebookEvent): StreamState<States>;+ /**+ * The state to hold while reconnecting.+ *+ * A live stream keeps its state and resumes from `cursor`. An incomplete+ * snapshot starts over.+ */+ resume(state: StreamState<States>): StreamState<States>;+}++/** Events that may arrive without a cursor after `ready`. */+const UNCURSORED = new Set<NotebookEvent["event"]>([+ "reset",+ "marimo",+ "unknown",+]);++/**+ * The notebook the event's object belongs to.+ *+ * Undefined for objects that do not name one.+ */+function notebookIdOf(+ event: EventOf<ResourceEventName>,+): Protocol.NotebookIdOutput | undefined {+ switch (event.event) {+ case "document":+ return event.data.document.notebook_id;+ case "cell":+ return event.data.cell.notebook_id;+ case "analysis":+ return event.data.analysis.notebook_id;+ case "runtime":+ return event.data.runtime.notebook_id;+ case "attachment":+ return event.data.attachment.notebook_id;+ case "run":+ return event.data.run.notebook_id;+ default:+ return undefined;+ }+}++/** Compose resources into one stream. */+export function createStream<States extends object>(+ resources: Resources<States>,+): Stream<States> {+ const names = Object.keys(resources) as (keyof States & string)[];+ const initialResources = Object.fromEntries(+ names.map((name) => [name, resources[name].initial]),+ ) as States;+ const initial: StreamState<States> = {+ phase: "snapshot",+ notebookId: null,+ cursor: null,+ resources: initialResources,+ };++ function identify(+ state: StreamState<States>,+ notebookId: Protocol.NotebookIdOutput,+ ): StreamState<States> {+ if (state.notebookId === notebookId) {+ return state;+ }+ if (state.notebookId !== null) {+ throw new Error("Notebook stream changed identity");+ }+ return { ...state, notebookId };+ }++ function clear(state: StreamState<States>): StreamState<States> {+ return state.resources === initialResources+ ? state+ : { ...state, resources: initialResources };+ }++ function fanOut(+ state: StreamState<States>,+ event: EventOf<ResourceEventName>,+ ): StreamState<States> {+ const context: HandlerContext = { phase: state.phase };+ let next = state.resources;+ for (const name of names) {+ type State = States[typeof name];+ // Handlers are keyed by the event name they accept.+ const handler = resources[name].on[event.event] as+ | ((+ state: State,+ event: Protocol.EventOutput,+ context: HandlerContext,+ ) => State)+ | undefined;+ if (handler === undefined) {+ continue;+ }+ const before = next[name];+ const after = handler(before, event, context);+ if (after !== before) {+ next = { ...next, [name]: after };+ }+ }+ return next === state.resources ? state : { ...state, resources: next };+ }++ /** Record the position of a live event. */+ function advance(+ state: StreamState<States>,+ id: string | undefined,+ ): StreamState<States> {+ return state.phase === "live" && id !== undefined && id !== state.cursor+ ? { ...state, cursor: id }+ : state;+ }++ return {+ initial,+ reduce(state, event) {+ if (+ state.phase === "live" &&+ event.id === undefined &&+ !UNCURSORED.has(event.event)+ ) {+ throw new Error("Live notebook event is missing its cursor");+ }+ switch (event.event) {+ case "marimo":+ case "unknown":+ return advance(state, event.id);+ case "reset":+ return { ...initial, notebookId: state.notebookId };+ case "ready":+ // Handlers see the phase that ended, so a snapshot's ready differs+ // from one that ends a replay.+ return { ...fanOut(state, event), phase: "live", cursor: event.id };+ case "notebook":+ return advance(identify(state, event.data.notebook.id), event.id);+ case "notebook.removed":+ return advance(+ state.notebookId !== null && event.data.id !== state.notebookId+ ? state+ : clear(state),+ event.id,+ );+ default: {+ const notebookId = notebookIdOf(event);+ return advance(+ fanOut(+ notebookId === undefined ? state : identify(state, notebookId),+ event,+ ),+ event.id,+ );+ }+ }+ },+ resume(state) {+ return state.phase === "snapshot"+ ? { ...initial, notebookId: state.notebookId }+ : state;+ },+ };+}