@marimo-team/islands 0.25.3-dev19 → 0.25.3-dev20

package/dist/{ErrorBoundary-CBHB755J.js → ErrorBoundary-DAPIRYqd.js}

@@ -135,7 +135,7 @@ function F(e) {
 }
 //#endregion
 //#region src/components/editor/boundary/ErrorBoundary.tsx
-var I = (0, T.lazy)(() => import("./feedback-button-_f7fx7zj.js").then((e) => ({ default: e.FeedbackModal }))), L = (e) => {
+var I = (0, T.lazy)(() => import("./feedback-button-wnAMXOGA.js").then((e) => ({ default: e.FeedbackModal }))), L = (e) => {
 	let t = (0, w.c)(2), n;
 	return t[0] === e.children ? n = t[1] : (n = /* @__PURE__ */ (0, j.jsx)(O, {
 		FallbackComponent: R,

package/dist/{code-visibility-CEXXuuOE.js → code-visibility-DkCqn-PO.js}

@@ -18,7 +18,7 @@ function x() {
 		return e.warn("Failed to get version from mount config"), null;
 	}
 }
-var S = x() || "0.25.3-dev19", C = u(S), w = u(!0);
+var S = x() || "0.25.3-dev20", C = u(S), w = u(!0);
 u(null);
 //#endregion
 //#region src/core/wasm/state.ts

package/dist/{common-OLE92qsR.js → common-DsUPhkD6.js}

@@ -12,7 +12,7 @@ import { t as dt } from "./check-EDwSwP89.js";
 import { A as ft, C as pt, M as mt, O as ht, S as gt, _ as _t, b as vt, c as yt, d as bt, g as xt, h as St, i as Ct, l as wt, m as Tt, n as Et, p as Dt, s as Ot, t as kt, u as At, v as jt, y as Mt } from "./select-BButFi-d.js";
 import { $ as Nt, $t as Pt, A as Ft, At as It, B as Lt, Bt as Rt, Ct as zt, D as Bt, Dt as Vt, E as Ht, Et as Ut, F as Wt, Ft as Gt, G as Kt, Gt as qt, H as Jt, Ht as Yt, I as Xt, It as Zt, J as Qt, Jt as $t, Kt as en, L as tn, Lt as nn, M as rn, Mt as an, N as on, Nt as sn, O as cn, Ot as ln, P as un, Pt as dn, Q as fn, Qt as pn, R as mn, Rt as hn, S as gn, St as _n, T as vn, Tt as yn, U as bn, Ut as xn, V as Sn, Vt as Cn, W as wn, Wt as Tn, X as En, Xt as Dn, Y as On, Yt as kn, Z as An, Zt as jn, _ as Mn, _n as Nn, _t as Pn, a as Fn, at as In, b as Ln, bt as Rn, cn as zn, ct as Bn, d as Vn, dn as Hn, dt as Un, et as Wn, f as Gn, fn as Kn, ft as qn, gn as Jn, gt as Yn, h as Xn, hn as Zn, ht as Qn, i as $n, in as er, it as tr, j as nr, jt as rr, k as ir, kt as ar, l as or, lt as sr, mn as cr, mt as lr, n as ur, nn as dr, nt as fr, o as pr, on as mr, ot as hr, pn as gr, pt as _r, qt as vr, rn as yr, rt as br, s as xr, sn as Sr, st as Cr, t as wr, tn as Tr, tt as Er, u as Dr, un as Or, vn as kr, vt as Ar, w as jr, wt as Mr, x as Nr, xt as Pr, y as Fr, yt as Ir, z as Lr, zt as Rr } from "./dropdown-menu-CP_qCYHC.js";
 import { a as zr, c as Br, d as Vr, i as Hr, l as Ur, n as Wr, o as Gr, r as Kr, t as qr, v as Jr, x as Yr, y as Xr } from "./toDate-UtiwmnH2.js";
-import { n as Zr, t as Qr } from "./ErrorBoundary-CBHB755J.js";
+import { n as Zr, t as Qr } from "./ErrorBoundary-DAPIRYqd.js";
 import { t as $r } from "./clsx-CoeGtWvn.js";
 import { t as ei } from "./react-dom-DUmH0GXv.js";
 import { t as ti } from "./jsx-runtime-3BD1kT0s.js";

package/dist/{data-grid-overlay-editor-CpHX98zN.js → data-grid-overlay-editor-D7UuVsgB.js}

@@ -2,7 +2,7 @@ import { a as e } from "./rolldown-runtime-Cb76FRpK.js";
 import { t } from "./react-sHtZdjeP.js";
 import { t as n } from "./react-dom-DUmH0GXv.js";
 import { c as r, l as i, u as a } from "./data-grid-types-BH_r7g7l.js";
-import { a as o, i as s, n as c, r as l } from "./glide-data-editor-Cmu4vWKD.js";
+import { a as o, i as s, n as c, r as l } from "./glide-data-editor-KvS90MGh.js";
 //#region ../node_modules/.pnpm/@glideapps+glide-data-grid@6.0.4-alpha24_lodash@4.17.21_marked@15.0.12_react-dom@19.3.0_aca11a353ce3b112922852200b9c160f/node_modules/@glideapps/glide-data-grid/dist/esm/internal/data-grid-overlay-editor/data-grid-overlay-editor-style.js
 var u = /* @__PURE__ */ e(t(), 1), d = /* @__PURE__ */ e(n(), 1), f = /*#__PURE__*/ o("div")({
 	name: "DataGridOverlayEditorStyle",

package/dist/{feedback-button-_f7fx7zj.js → feedback-button-wnAMXOGA.js}

@@ -5,12 +5,12 @@ import { t as i } from "./compiler-runtime-CldRdSsv.js";
 import { t as a } from "./copy-icon-Ft7t9bqz.js";
 import { G as o, Lt as s, Ot as c, V as l, fn as u, h as d, i as f, n as p, q as m, zt as h } from "./error-entries-Bv6bZPF3.js";
 import { b as g } from "./select-BButFi-d.js";
-import { n as ee, t as te } from "./globals-1Hfhz6Dx.js";
+import { n as ee, t as te } from "./globals-yruoELTW.js";
 import { t as _ } from "./jsx-runtime-3BD1kT0s.js";
 import { C as v, _ as ne, i as y } from "./useTheme-CRnjkku0.js";
 import { a as re, i as ie, n as ae, r as oe } from "./dialog-CEBFZNyc.js";
 import { t as se } from "./useAsyncData-Deh5kszT.js";
-import { t as ce } from "./code-visibility-CEXXuuOE.js";
+import { t as ce } from "./code-visibility-DkCqn-PO.js";
 //#region src/components/ui/skeleton.tsx
 var b = /* @__PURE__ */ e(r(), 1), x = i(), S = _(), le = (e) => {
 	let n = (0, x.c)(8), r, i;

package/dist/{glide-data-editor-Cmu4vWKD.js → glide-data-editor-KvS90MGh.js}

@@ -6,7 +6,7 @@ import { i as s, n as c, r as l } from "./copy-icon-Ft7t9bqz.js";
 import { C as u, c as d, i as f, n as p, s as m, t as h, x as g } from "./select-BButFi-d.js";
 import { d as _, h as v, i as y, l as b, n as x, o as S, s as C, t as w, u as T } from "./dropdown-menu-CP_qCYHC.js";
 import { c as E, d as D, l as O, n as k, o as A, s as ee, t as j, u as te } from "./glide-utils-DJyqh0EM.js";
-import { n as ne, t as re } from "./ErrorBoundary-CBHB755J.js";
+import { n as ne, t as re } from "./ErrorBoundary-DAPIRYqd.js";
 import { t as M } from "./react-dom-DUmH0GXv.js";
 import { t as N } from "./jsx-runtime-3BD1kT0s.js";
 import { t as ie } from "./label-BDKF3Afc.js";
@@ -7062,7 +7062,7 @@ function rs(e, t, n, r, i) {
 }
 //#endregion
 //#region ../node_modules/.pnpm/@glideapps+glide-data-grid@6.0.4-alpha24_lodash@4.17.21_marked@15.0.12_react-dom@19.3.0_aca11a353ce3b112922852200b9c160f/node_modules/@glideapps/glide-data-grid/dist/esm/data-editor/data-editor.js
-var is = /* @__PURE__ */ e(_r(), 1), as = /* @__PURE__ */ e(xr(), 1), os = K.lazy(async () => await import("./data-grid-overlay-editor-CpHX98zN.js")), ss = 0;
+var is = /* @__PURE__ */ e(_r(), 1), as = /* @__PURE__ */ e(xr(), 1), os = K.lazy(async () => await import("./data-grid-overlay-editor-D7UuVsgB.js")), ss = 0;
 function cs(e) {
 	return (0, is.default)((0, as.default)((0, as.default)(e).filter((e) => e.span !== void 0).map((e) => (0, Za.default)((e.span?.[0] ?? 0) + 1, (e.span?.[1] ?? 0) + 1))));
 }
@@ -9293,7 +9293,7 @@ function Vs(e, t, n, r, i) {
 }
 //#endregion
 //#region ../node_modules/.pnpm/@glideapps+glide-data-grid@6.0.4-alpha24_lodash@4.17.21_marked@15.0.12_react-dom@19.3.0_aca11a353ce3b112922852200b9c160f/node_modules/@glideapps/glide-data-grid/dist/esm/cells/number-cell.js
-var Hs = K.lazy(async () => await import("./number-overlay-editor-BQN3-Nye.js")), Us = {
+var Hs = K.lazy(async () => await import("./number-overlay-editor-R2i0FdxV.js")), Us = {
 	getAccessibilityString: (e) => e.data?.toString() ?? "",
 	kind: W.Number,
 	needsHover: (e) => e.hoverEffect === !0,

package/dist/{globals-1Hfhz6Dx.js → globals-yruoELTW.js}

@@ -1,6 +1,6 @@
 import { h as e } from "./tooltip-BO1REbqs.js";
 import { _ as t } from "./useTheme-CRnjkku0.js";
-import { r as n } from "./code-visibility-CEXXuuOE.js";
+import { r as n } from "./code-visibility-DkCqn-PO.js";
 var r = e("triangle-alert", [
 	["path", {
 		d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3",

package/dist/main.js

@@ -7,7 +7,7 @@ import { C as w, F as T, G as E, I as D, J as O, K as k, L as A, P as j, R as M,
 import { a as oe, d as se, f as ce, h as V, i as le, n as ue, o as de, r as fe, t as pe } from "./tooltip-BO1REbqs.js";
 import { $ as me, At as he, B as ge, Bt as _e, D as ve, Dt as ye, E as be, Ht as xe, It as Se, J as Ce, Jt as we, Kt as Te, M as Ee, Mt as De, N as Oe, Nt as ke, O as Ae, Ot as je, Q as Me, R as Ne, S as Pe, Tt as Fe, V as Ie, Vt as Le, W as Re, Wt as ze, X as Be, Xt as Ve, Y as He, Yt as Ue, _ as We, _n as Ge, _t as Ke, an as qe, b as Je, cn as Ye, ct as Xe, dn as Ze, dt as Qe, en as $e, f as et, ft as tt, g as nt, gn as rt, gt as it, h as at, it as ot, j as st, jt as ct, k as lt, kt as ut, ln as dt, m as ft, mn as pt, nn as mt, o as ht, p as gt, pn as _t, pt as vt, qt as yt, rn as bt, rt as xt, s as St, tn as Ct, u as wt, un as Tt, v as Et, xt as Dt, y as Ot, z as kt } from "./error-entries-Bv6bZPF3.js";
 import { D as At, E as jt, O as Mt, S as Nt, T as Pt, _ as Ft, a as It, c as Lt, d as Rt, f as zt, g as Bt, h as Vt, i as Ht, l as Ut, m as Wt, n as Gt, o as Kt, p as qt, r as Jt, s as Yt, t as Xt, u as Zt, v as Qt, w as $t, x as en, y as tn } from "./spec-BwarBpUJ.js";
-import { $t as nn, A as rn, At as an, B as on, Bt as sn, C as cn, Ct as ln, D as un, Dt as dn, E as fn, Et as pn, F as mn, Ft as hn, G as gn, Gt as _n, H as vn, Ht as yn, I as bn, It as xn, J as Sn, Jt as Cn, K as wn, Kt as Tn, L as En, Lt as Dn, M as On, Mt as kn, N as An, Nt as jn, O as Mn, Ot as Nn, P as Pn, Pt as Fn, Qt as In, R as Ln, Rt as Rn, S as zn, St as Bn, T as Vn, Tt as Hn, U as Un, Ut as Wn, V as Gn, Vt as Kn, W as qn, Wt as Jn, X as Yn, Xt as Xn, Y as Zn, Yt as Qn, Zt as $n, _ as er, _t as tr, an as nr, at as rr, b as ir, c as ar, cn as or, ct as sr, d as cr, dn as lr, dt as ur, en as dr, et as fr, f as pr, fn as mr, ft as hr, g as gr, gt as _r, h as vr, hn as yr, ht as br, in as xr, it as Sr, j as Cr, jt as wr, k as Tr, kt as Er, ln as Dr, lt as Or, m as kr, mn as Ar, mt as jr, nn as Mr, nt as Nr, ot as Pr, p as Fr, pn as Ir, pt as Lr, q as Rr, qt as zr, r as Br, rn as Vr, rt as Hr, sn as Ur, st as Wr, t as Gr, tn as Kr, tt as qr, u as Jr, un as Yr, ut as Xr, v as Zr, vt as Qr, w as $r, wt as ei, x as ti, y as ni, yt as ri, z as ii, zt as ai } from "./common-OLE92qsR.js";
+import { $t as nn, A as rn, At as an, B as on, Bt as sn, C as cn, Ct as ln, D as un, Dt as dn, E as fn, Et as pn, F as mn, Ft as hn, G as gn, Gt as _n, H as vn, Ht as yn, I as bn, It as xn, J as Sn, Jt as Cn, K as wn, Kt as Tn, L as En, Lt as Dn, M as On, Mt as kn, N as An, Nt as jn, O as Mn, Ot as Nn, P as Pn, Pt as Fn, Qt as In, R as Ln, Rt as Rn, S as zn, St as Bn, T as Vn, Tt as Hn, U as Un, Ut as Wn, V as Gn, Vt as Kn, W as qn, Wt as Jn, X as Yn, Xt as Xn, Y as Zn, Yt as Qn, Zt as $n, _ as er, _t as tr, an as nr, at as rr, b as ir, c as ar, cn as or, ct as sr, d as cr, dn as lr, dt as ur, en as dr, et as fr, f as pr, fn as mr, ft as hr, g as gr, gt as _r, h as vr, hn as yr, ht as br, in as xr, it as Sr, j as Cr, jt as wr, k as Tr, kt as Er, ln as Dr, lt as Or, m as kr, mn as Ar, mt as jr, nn as Mr, nt as Nr, ot as Pr, p as Fr, pn as Ir, pt as Lr, q as Rr, qt as zr, r as Br, rn as Vr, rt as Hr, sn as Ur, st as Wr, t as Gr, tn as Kr, tt as qr, u as Jr, un as Yr, ut as Xr, v as Zr, vt as Qr, w as $r, wt as ei, x as ti, y as ni, yt as ri, z as ii, zt as ai } from "./common-DsUPhkD6.js";
 import { c as oi, i as si, n as ci, o as li, t as ui } from "./useLifecycle-j7D9uD1o.js";
 import { t as di } from "./check-EDwSwP89.js";
 import { A as fi, C as pi, D as mi, E as hi, M as gi, O as _i, S as vi, T as yi, a as bi, b as xi, c as Si, i as Ci, k as wi, l as Ti, n as Ei, o as Di, r as Oi, s as ki, t as Ai, w as ji, x as Mi } from "./select-BButFi-d.js";
@@ -15,8 +15,8 @@ import { $ as Ni, C as Pi, Et as Fi, J as Ii, K as Li, R as Ri, S as zi, U as Bi
 import { C as ua, _ as da, a as fa, b as pa, c as ma, f as ha, h as ga, m as _a, p as va, s as ya, u as ba, x as xa, y as Sa } from "./toDate-UtiwmnH2.js";
 import { a as Ca, c as wa, d as Ta, f as Ea, i as Da, l as Oa, n as ka, o as Aa, r as ja, s as Ma, t as Na } from "./process-output-BZg56CCb.js";
 import { a as Pa, c as Fa, d as Ia, i as La, l as Ra, r as za, u as Ba } from "./glide-utils-DJyqh0EM.js";
-import { n as Va, t as Ha } from "./ErrorBoundary-CBHB755J.js";
-import { n as Ua, t as Wa } from "./globals-1Hfhz6Dx.js";
+import { n as Va, t as Ha } from "./ErrorBoundary-DAPIRYqd.js";
+import { n as Ua, t as Wa } from "./globals-yruoELTW.js";
 import { t as Ga } from "./react-dom-DUmH0GXv.js";
 import { t as Ka } from "./jsx-runtime-3BD1kT0s.js";
 import { B as qa, C as H, Ct as Ja, D as Ya, E as Xa, F as U, G as Za, H as Qa, I as $a, L as eo, M as W, N as to, O as no, P as ro, Q as io, R as ao, S as G, St as oo, Tt as so, U as co, W as lo, Y as uo, Z as fo, _ as po, _t as mo, a as ho, b as go, bt as _o, c as vo, d as yo, f as bo, g as xo, h as So, ht as Co, i as wo, j as K, k as To, l as Eo, m as Do, n as Oo, o as ko, p as Ao, r as jo, s as Mo, u as No, ut as Po, v as Fo, vt as Io, w as Lo, wt as Ro, x as zo, xt as Bo, y as Vo, yt as Ho } from "./use-restore-focus-BEM7sFWl.js";
@@ -39,7 +39,7 @@ import { t as Ms } from "./useAsyncData-Deh5kszT.js";
 import { i as Ns, n as Ps, r as Fs } from "./formats-27CW_UP4.js";
 import { M as Is, N as Ls } from "./vega-loader.browser-DNST6uVf.js";
 import { a as Rs, n as zs } from "./loader-BQOfjTIJ.js";
-import { c as Bs, d as Vs, i as Hs, l as Us, o as Ws, s as Gs, t as Ks, u as qs } from "./code-visibility-CEXXuuOE.js";
+import { c as Bs, d as Vs, i as Hs, l as Us, o as Ws, s as Gs, t as Ks, u as qs } from "./code-visibility-DkCqn-PO.js";
 import { t as Js } from "./useDeepCompareMemoize-DXwzRINI.js";
 import { t as Ys } from "./esm-D2gTsXEV.js";
 //#region ../node_modules/.pnpm/iconify-icon@2.3.0/node_modules/iconify-icon/dist/iconify-icon.mjs
@@ -10533,7 +10533,7 @@ function VC(e, t) {
 }
 //#endregion
 //#region src/plugins/impl/DataEditorPlugin.tsx
-var HC = J.lazy(() => import("./glide-data-editor-Cmu4vWKD.js").then((e) => e.t)), UC = wS("marimo-data-editor", { cssStyles: [qS] }).withData(W({
+var HC = J.lazy(() => import("./glide-data-editor-KvS90MGh.js").then((e) => e.t)), UC = wS("marimo-data-editor", { cssStyles: [qS] }).withData(W({
 	initialValue: W({ edits: G(W({
 		rowIdx: K(),
 		columnId: U(),
@@ -30107,7 +30107,7 @@ function OR(e) {
 }
 //#endregion
 //#region src/components/editor/renderers/slides-layout/slides-layout.tsx
-var kR = J.lazy(() => import("./reveal-component-nqUW7zgn.js")), AR = (e) => {
+var kR = J.lazy(() => import("./reveal-component-C42-YBfQ.js")), AR = (e) => {
 	let t = (0, X.c)(33), { layout: n, setLayout: r, cells: i, mode: a } = e, o = ns(da), s = a === "read" || o, c = ns(We) > 1, [l, u] = (0, J.useState)(null), d;
 	t[0] !== i || t[1] !== n ? (d = EP(i, n), t[0] = i, t[1] = n, t[2] = d) : d = t[2];
 	let { slideCells: f, skippedIds: p, noOutputIds: m, slideTypes: h, startCellIndex: g } = d, _;

package/dist/{number-overlay-editor-BQN3-Nye.js → number-overlay-editor-R2i0FdxV.js}

@@ -1,6 +1,6 @@
 import { a as e } from "./rolldown-runtime-Cb76FRpK.js";
 import { t } from "./react-sHtZdjeP.js";
-import { a as n } from "./glide-data-editor-Cmu4vWKD.js";
+import { a as n } from "./glide-data-editor-KvS90MGh.js";
 //#region ../node_modules/.pnpm/@glideapps+glide-data-grid@6.0.4-alpha24_lodash@4.17.21_marked@15.0.12_react-dom@19.3.0_aca11a353ce3b112922852200b9c160f/node_modules/@glideapps/glide-data-grid/dist/esm/internal/data-grid-overlay-editor/private/number-overlay-editor-style.js
 var r = /* @__PURE__ */ e(t()), i = /*#__PURE__*/ n("div")({
 	name: "NumberOverlayEditorStyle",

package/dist/{reveal-component-nqUW7zgn.js → reveal-component-C42-YBfQ.js}

@@ -4,14 +4,14 @@ import { t as o } from "./react-sHtZdjeP.js";
 import { t as s } from "./compiler-runtime-CldRdSsv.js";
 import { h as c, t as l } from "./tooltip-BO1REbqs.js";
 import { O as u } from "./error-entries-Bv6bZPF3.js";
-import { $ as d, Q as f, Z as p, an as m, i as h, l as g, ln as _, n as v, on as y, r as b, t as x, u as S } from "./common-OLE92qsR.js";
+import { $ as d, Q as f, Z as p, an as m, i as h, l as g, ln as _, n as v, on as y, r as b, t as x, u as S } from "./common-DsUPhkD6.js";
 import { M as C } from "./select-BButFi-d.js";
 import { q as ee } from "./dropdown-menu-CP_qCYHC.js";
 import { _ as w } from "./toDate-UtiwmnH2.js";
 import { t as T } from "./jsx-runtime-3BD1kT0s.js";
 import { q as E } from "./use-restore-focus-BEM7sFWl.js";
 import { A as D, C as O, b as k } from "./useTheme-CRnjkku0.js";
-import { a as A, n as te, t as ne } from "./code-visibility-CEXXuuOE.js";
+import { a as A, n as te, t as ne } from "./code-visibility-DkCqn-PO.js";
 /* empty css                */
 var j = c("sticky-note", [["path", {
 	d: "M21 9a2.4 2.4 0 0 0-.706-1.706l-3.588-3.588A2.4 2.4 0 0 0 15 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2z",

package/package.json

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

package/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.

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

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

package/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) => {

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

package/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 },

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

package/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>;
+}

package/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;
+    },
+  };
+}