@marimo-team/frontend 0.25.3-dev10 → 0.25.3-dev13

package/dist/index.html

@@ -66,13 +66,13 @@
     <marimo-server-token data-token="{{ server_token }}" hidden></marimo-server-token>
     <!-- /TODO -->
     <title>{{ title }}</title>
-    <script type="module" crossorigin src="./assets/index-B3fcrmuf.js"></script>
+    <script type="module" crossorigin src="./assets/index-ptK1gxmo.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/rolldown-runtime-B0Z9INg1.js">
     <link rel="modulepreload" crossorigin href="./assets/react-DVplv7_D.js">
     <link rel="modulepreload" crossorigin href="./assets/compiler-runtime-BrajqUja.js">
     <link rel="modulepreload" crossorigin href="./assets/useEvent-Dfcbgjhg.js">
     <link rel="modulepreload" crossorigin href="./assets/react-dom-_LrxgvjW.js">
-    <link rel="modulepreload" crossorigin href="./assets/schemas-Dv42wLFq.js">
+    <link rel="modulepreload" crossorigin href="./assets/schemas-ChRqMOTL.js">
     <link rel="modulepreload" crossorigin href="./assets/isObject-BCaOs5rp.js">
     <link rel="modulepreload" crossorigin href="./assets/isSymbol-oX0TOjjx.js">
     <link rel="modulepreload" crossorigin href="./assets/now-Cmx0b_zA.js">
@@ -82,11 +82,11 @@
     <link rel="modulepreload" crossorigin href="./assets/objects-snlMn4yk.js">
     <link rel="modulepreload" crossorigin href="./assets/useEventListener-D9cftcHj.js">
     <link rel="modulepreload" crossorigin href="./assets/invariant-Ci2dTZ72.js">
-    <link rel="modulepreload" crossorigin href="./assets/config-VPSq73n8.js">
+    <link rel="modulepreload" crossorigin href="./assets/config-CA1V-wjh.js">
     <link rel="modulepreload" crossorigin href="./assets/utils-B4K466FK.js">
     <link rel="modulepreload" crossorigin href="./assets/session-DqoWmb7X.js">
     <link rel="modulepreload" crossorigin href="./assets/Deferred-CrTnjj37.js">
-    <link rel="modulepreload" crossorigin href="./assets/config-DX8Y2WbJ.js">
+    <link rel="modulepreload" crossorigin href="./assets/config-Dy28fDwn.js">
     <link rel="modulepreload" crossorigin href="./assets/clsx-DB0hHKMi.js">
     <link rel="modulepreload" crossorigin href="./assets/cn-ldLVeaqm.js">
     <link rel="modulepreload" crossorigin href="./assets/jsx-runtime-B74pBk57.js">
@@ -136,58 +136,58 @@
     <link rel="modulepreload" crossorigin href="./assets/dist-LSsCJjA3.js">
     <link rel="modulepreload" crossorigin href="./assets/dist-DusFODSa.js">
     <link rel="modulepreload" crossorigin href="./assets/stex-Dc5bKD4z.js">
-    <link rel="modulepreload" crossorigin href="./assets/useTheme-COhSHkCj.js">
+    <link rel="modulepreload" crossorigin href="./assets/useTheme-n8Dj1zH7.js">
     <link rel="modulepreload" crossorigin href="./assets/useAsyncData-C7aJJz0Y.js">
     <link rel="modulepreload" crossorigin href="./assets/purify.es--06brOip.js">
-    <link rel="modulepreload" crossorigin href="./assets/cells-rA_jsZCj.js">
-    <link rel="modulepreload" crossorigin href="./assets/coerce-CpE6kUdX.js">
+    <link rel="modulepreload" crossorigin href="./assets/cells-C6YGYGdi.js">
+    <link rel="modulepreload" crossorigin href="./assets/coerce-DWjFeXOY.js">
     <link rel="modulepreload" crossorigin href="./assets/get-DjNf4SIX.js">
     <link rel="modulepreload" crossorigin href="./assets/_hasPath-BmRQipI0.js">
     <link rel="modulepreload" crossorigin href="./assets/hasIn-yw4sIeJR.js">
     <link rel="modulepreload" crossorigin href="./assets/_baseSet-Bpdo9AvU.js">
     <link rel="modulepreload" crossorigin href="./assets/pick-DKIID_Mo.js">
-    <link rel="modulepreload" crossorigin href="./assets/errors-DCrsa1nH.js">
-    <link rel="modulepreload" crossorigin href="./assets/config-DJLAC21v.js">
+    <link rel="modulepreload" crossorigin href="./assets/errors-CNsgAw6m.js">
+    <link rel="modulepreload" crossorigin href="./assets/config-DRIpOKqh.js">
     <link rel="modulepreload" crossorigin href="./assets/state-BAJYRhmO.js">
     <link rel="modulepreload" crossorigin href="./assets/state-C3oDoyFe.js">
-    <link rel="modulepreload" crossorigin href="./assets/LazyAnyLanguageCodeMirror-CKcCbG2G.js">
+    <link rel="modulepreload" crossorigin href="./assets/LazyAnyLanguageCodeMirror-B4fCknq1.js">
     <link rel="modulepreload" crossorigin href="./assets/copy-D8O_CYCG.js">
     <link rel="modulepreload" crossorigin href="./assets/micromark-factory-space-D9Dr-k4J.js">
     <link rel="modulepreload" crossorigin href="./assets/chunk-YOKDWASO-BIpRENEC.js">
-    <link rel="modulepreload" crossorigin href="./assets/markdown-renderer-Q5AhbRU3.js">
+    <link rel="modulepreload" crossorigin href="./assets/markdown-renderer-DX0Xrrfy.js">
     <link rel="modulepreload" crossorigin href="./assets/copy-Djr5m5ac.js">
     <link rel="modulepreload" crossorigin href="./assets/copy-icon-BIiRXh_3.js">
-    <link rel="modulepreload" crossorigin href="./assets/useRunCells-BFjFX3hz.js">
-    <link rel="modulepreload" crossorigin href="./assets/RenderHTML-9bMgbYmo.js">
-    <link rel="modulepreload" crossorigin href="./assets/blob-iOBwGaP9.js">
+    <link rel="modulepreload" crossorigin href="./assets/useRunCells-DSJPXE-j.js">
+    <link rel="modulepreload" crossorigin href="./assets/RenderHTML-DX6i99Op.js">
+    <link rel="modulepreload" crossorigin href="./assets/blob-BG8yoQmx.js">
     <link rel="modulepreload" crossorigin href="./assets/kbd-pdKBv96t.js">
-    <link rel="modulepreload" crossorigin href="./assets/useInstallPackage-iX1eufdl.js">
+    <link rel="modulepreload" crossorigin href="./assets/useInstallPackage-BW06eter.js">
     <link rel="modulepreload" crossorigin href="./assets/share-BZW3tzEX.js">
     <link rel="modulepreload" crossorigin href="./assets/events-CbeVJ6OD.js">
-    <link rel="modulepreload" crossorigin href="./assets/state-z3dlofZB.js">
-    <link rel="modulepreload" crossorigin href="./assets/ErrorBoundary-B4n9EnHB.js">
+    <link rel="modulepreload" crossorigin href="./assets/state-CbjBtkdd.js">
+    <link rel="modulepreload" crossorigin href="./assets/ErrorBoundary-CM13wrd8.js">
     <link rel="modulepreload" crossorigin href="./assets/chevron-right-eAtVhbNZ.js">
     <link rel="modulepreload" crossorigin href="./assets/dropdown-menu-C1rnl-0o.js">
     <link rel="modulepreload" crossorigin href="./assets/html-to-image-DK9Zl1lU.js">
-    <link rel="modulepreload" crossorigin href="./assets/download-Bx55LMki.js">
+    <link rel="modulepreload" crossorigin href="./assets/download-C03FOElq.js">
     <link rel="modulepreload" crossorigin href="./assets/switch-CTaiAjrz.js">
     <link rel="modulepreload" crossorigin href="./assets/tabs-BuQlZFbt.js">
     <link rel="modulepreload" crossorigin href="./assets/table-DG7Ap4H4.js">
     <link rel="modulepreload" crossorigin href="./assets/eye-off-CxVozGAC.js">
     <link rel="modulepreload" crossorigin href="./assets/refresh-cw-Qw1f8Jhy.js">
-    <link rel="modulepreload" crossorigin href="./assets/tree-actions-DAd80MbP.js">
+    <link rel="modulepreload" crossorigin href="./assets/tree-actions-DnUokmva.js">
     <link rel="modulepreload" crossorigin href="./assets/ellipsis-63DyBLHQ.js">
     <link rel="modulepreload" crossorigin href="./assets/external-link-UrX9KO36.js">
     <link rel="modulepreload" crossorigin href="./assets/spinner-DyNE-o8o.js">
     <link rel="modulepreload" crossorigin href="./assets/message-circle-C3rKm8_a.js">
     <link rel="modulepreload" crossorigin href="./assets/hat-glasses-C8RhSVii.js">
     <link rel="modulepreload" crossorigin href="./assets/package-GSoSTiIK.js">
-    <link rel="modulepreload" crossorigin href="./assets/datasource-Dr1xNKUn.js">
-    <link rel="modulepreload" crossorigin href="./assets/error-entries-DOWpdGvI.js">
+    <link rel="modulepreload" crossorigin href="./assets/datasource-DfbNb83e.js">
+    <link rel="modulepreload" crossorigin href="./assets/error-entries-CLnPDv7b.js">
     <link rel="modulepreload" crossorigin href="./assets/alert-DTaqCu_d.js">
-    <link rel="modulepreload" crossorigin href="./assets/state-Bfh_2SLl.js">
-    <link rel="modulepreload" crossorigin href="./assets/cell-link-1CynTVGQ.js">
-    <link rel="modulepreload" crossorigin href="./assets/MarimoErrorOutput-BTy4MOzX.js">
+    <link rel="modulepreload" crossorigin href="./assets/state-DtGB7xeJ.js">
+    <link rel="modulepreload" crossorigin href="./assets/cell-link-8Auigi8P.js">
+    <link rel="modulepreload" crossorigin href="./assets/MarimoErrorOutput-s_5GOX8k.js">
     <link rel="modulepreload" crossorigin href="./assets/useDateFormatter-DA-62E-Y.js">
     <link rel="modulepreload" crossorigin href="./assets/en-US-Buu61juQ.js">
     <link rel="modulepreload" crossorigin href="./assets/isValid-q_Ad80ug.js">
@@ -201,18 +201,18 @@
     <link rel="modulepreload" crossorigin href="./assets/extends-CvVTau-c.js">
     <link rel="modulepreload" crossorigin href="./assets/objectWithoutPropertiesLoose-Do6ywDBO.js">
     <link rel="modulepreload" crossorigin href="./assets/useIframeCapabilities-CwTkczVN.js">
-    <link rel="modulepreload" crossorigin href="./assets/error-banner-Cd69vvyX.js">
+    <link rel="modulepreload" crossorigin href="./assets/error-banner-COZ7SfYV.js">
     <link rel="modulepreload" crossorigin href="./assets/utils-CaQYvazl.js">
     <link rel="modulepreload" crossorigin href="./assets/formats-yZ06h1Pl.js">
     <link rel="modulepreload" crossorigin href="./assets/table-vrvqpuKJ.js">
     <link rel="modulepreload" crossorigin href="./assets/react-resizable-panels.browser.esm-Dbe0MrFr.js">
-    <link rel="modulepreload" crossorigin href="./assets/JsonOutput-BxB0NL8w.js">
+    <link rel="modulepreload" crossorigin href="./assets/JsonOutput-Cx1iyibB.js">
     <link rel="modulepreload" crossorigin href="./assets/chart-no-axes-column-C4_v6fQW.js">
     <link rel="modulepreload" crossorigin href="./assets/square-function-_W_Lo0P4.js">
     <link rel="modulepreload" crossorigin href="./assets/spec-BfSBcO5B.js">
     <link rel="modulepreload" crossorigin href="./assets/semaphore-BjoL5P0h.js">
     <link rel="modulepreload" crossorigin href="./assets/fileToBase64-BgBraYAr.js">
-    <link rel="modulepreload" crossorigin href="./assets/useBoolean-BDD6_xQQ.js">
+    <link rel="modulepreload" crossorigin href="./assets/useBoolean-d0Tty94N.js">
     <link rel="modulepreload" crossorigin href="./assets/code-xml-SQaZqvcO.js">
     <link rel="modulepreload" crossorigin href="./assets/file-headphone-Dl35U6h3.js">
     <link rel="modulepreload" crossorigin href="./assets/file-BPBVl9pl.js">
@@ -220,23 +220,23 @@
     <link rel="modulepreload" crossorigin href="./assets/file-icons-CdJgUy-I.js">
     <link rel="modulepreload" crossorigin href="./assets/globe-UdPdIbF7.js">
     <link rel="modulepreload" crossorigin href="./assets/esm-CI_o7NhW.js">
-    <link rel="modulepreload" crossorigin href="./assets/useAddCell-DGstJK0S.js">
-    <link rel="modulepreload" crossorigin href="./assets/readonly-python-code-CadgXgRu.js">
+    <link rel="modulepreload" crossorigin href="./assets/useAddCell-IN24thff.js">
+    <link rel="modulepreload" crossorigin href="./assets/readonly-python-code-ggs4hAzC.js">
     <link rel="modulepreload" crossorigin href="./assets/data-grid-types-DgHVN_Zz.js">
     <link rel="modulepreload" crossorigin href="./assets/glide-utils-CIrAxdjv.js">
-    <link rel="modulepreload" crossorigin href="./assets/column-preview-DU6dT80y.js">
+    <link rel="modulepreload" crossorigin href="./assets/column-preview-BZ_iNhtJ.js">
     <link rel="modulepreload" crossorigin href="./assets/square-BPmgQFnh.js">
     <link rel="modulepreload" crossorigin href="./assets/triangle-alert-DmIqR8sY.js">
     <link rel="modulepreload" crossorigin href="./assets/prop-types-Djf4O40e.js">
     <link rel="modulepreload" crossorigin href="./assets/es-Cqst59WX.js">
     <link rel="modulepreload" crossorigin href="./assets/package-data-dv4FBHxR.js">
     <link rel="modulepreload" crossorigin href="./assets/markdown-export-DzhB1FrN.js">
-    <link rel="modulepreload" crossorigin href="./assets/renderShortcut-BkVJQ_Zh.js">
+    <link rel="modulepreload" crossorigin href="./assets/renderShortcut-C1JwYcqW.js">
     <link rel="modulepreload" crossorigin href="./assets/bundle.esm-D3tw5rqW.js">
     <link rel="modulepreload" crossorigin href="./assets/icons-CiZ_8zS-.js">
     <link rel="modulepreload" crossorigin href="./assets/useDeepCompareMemoize-DFIVN9dn.js">
     <link rel="modulepreload" crossorigin href="./assets/pathUtils-DPmlLd-r.js">
-    <link rel="modulepreload" crossorigin href="./assets/floating-outline-MYqQW4Vp.js">
+    <link rel="modulepreload" crossorigin href="./assets/floating-outline-B5MaM1JS.js">
     <link rel="stylesheet" crossorigin href="./assets/cells-0PFKL3SH.css">
     <link rel="stylesheet" crossorigin href="./assets/markdown-renderer-DjIHoF9Z.css">
     <link rel="stylesheet" crossorigin href="./assets/JsonOutput-B0GmlMnR.css">

package/package.json

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

package/src/__tests__/mount.test.ts

@@ -6,6 +6,7 @@ import { initialLayoutState, layoutStateAtom } from "@/core/layout/state";
 import { kioskModeAtom } from "@/core/mode";
 import { connectionAtom } from "@/core/network/connection";
 import { store } from "@/core/state/jotai";
+import { runtimeConfigAtom } from "@/core/runtime/config";
 import { isStaticNotebook } from "@/core/static/static-state";
 import { ConnectionState } from "@/core/websocket/types";
 import { pairConfigAtom } from "@/core/config/pair";
@@ -101,6 +102,25 @@ describe("mount", () => {
   });
 
   describe("connection state initialization", () => {
+    it("passes the host notebook identity to the local runtime", () => {
+      mount({ ...baseOptions, notebookId: "nb_local" }, mockElement);
+      expect(store.get(runtimeConfigAtom).notebookId).toBe("nb_local");
+    });
+
+    it("uses a remote runtime's own notebook identity", () => {
+      mount(
+        {
+          ...baseOptions,
+          notebookId: "nb_local",
+          runtimeConfig: [
+            { url: "https://remote.example", notebookId: "nb_remote" },
+          ],
+        },
+        mockElement,
+      );
+      expect(store.get(runtimeConfigAtom).notebookId).toBe("nb_remote");
+    });
+
     it("should set connection to CONNECTING when runtimeConfig has lazy=false", () => {
       mount(
         {

package/src/core/edit-app.tsx

@@ -41,7 +41,7 @@ import { viewStateAtom } from "./mode";
 import { useRequestClient } from "./network/requests";
 import { useFilename } from "./saving/filename";
 import { lastSavedNotebookAtom } from "./saving/state";
-import { useMarimoKernelConnection } from "./websocket/useMarimoKernelConnection";
+import { useNotebookSession } from "./websocket/useNotebookSession";
 
 interface AppProps {
   /**
@@ -83,7 +83,7 @@ export const EditApp: React.FC<AppProps> = ({
     };
   }, []);
 
-  const { connection, reconnect } = useMarimoKernelConnection({
+  const { connection, reconnect } = useNotebookSession({
     autoInstantiate: userConfig.runtime.auto_instantiate,
     setCells: (cells, layout) => {
       setCells(cells);

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

@@ -0,0 +1,46 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { parseNotebookEvent } from "../events";
+
+describe("notebook messages", () => {
+  it("normalizes session and host envelopes for native marimo messages", () => {
+    const notification = {
+      op: "variables",
+      variables: [{ name: "x", value: Number.NaN }],
+    };
+    const host = { event: "marimo", data: { marimo: notification } };
+    expect(parseNotebookEvent({ data: notification })).toEqual(host);
+    expect(parseNotebookEvent({ ...host, id: "42" })).toEqual({
+      ...host,
+      id: "42",
+    });
+  });
+
+  it("retains unknown event cursors without interpreting their payloads", () => {
+    expect(
+      parseNotebookEvent({ event: "future", id: "42", data: null }),
+    ).toEqual({ event: "unknown", name: "future", id: "42" });
+  });
+
+  it("decodes known events outside the client's subscription filters", () => {
+    const event = {
+      event: "run.removed",
+      id: "42",
+      data: { id: "r1", time: "2026-10-19T12:00:00Z" },
+    };
+    expect(parseNotebookEvent(event)).toEqual(event);
+  });
+
+  it.each([
+    { event: "cell", id: "42", data: { cell: { id: "c1" } } },
+    { event: "run.removed", id: "42", data: {} },
+    { event: "ready", data: {} },
+    { event: "marimo", data: {} },
+    {},
+    null,
+  ])("rejects malformed known messages: %j", (message) => {
+    expect(() => parseNotebookEvent(message)).toThrow(z.ZodError);
+  });
+});

package/src/core/host/__tests__/notebook-client.test.ts

@@ -0,0 +1,191 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+// @vitest-environment jsdom
+
+import { describe, expect, it, vi } from "vitest";
+import { createStore } from "jotai";
+import { ConnectionState } from "../../websocket/types";
+import { Deferred } from "@/utils/Deferred";
+import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
+import { classifyCloseEvent } from "../../websocket/connection-state";
+import { createNotebookClient } from "../notebook-client";
+
+function setup() {
+  const events = new EventTarget();
+  const healthy = new Deferred<void>();
+  const transport = {
+    readyState: WebSocket.CLOSED,
+    reconnect: vi.fn(),
+    close: vi.fn(() => events.dispatchEvent(new CloseEvent("close"))),
+    send: vi.fn(),
+    addEventListener: events.addEventListener.bind(events),
+    removeEventListener: events.removeEventListener.bind(events),
+  };
+  const onNotification = vi.fn();
+  const checkHealth = vi.fn(async () => true);
+  const store = createStore();
+  const controller = createNotebookClient(store);
+  const client = controller.client;
+  const connect = (signal: AbortSignal) =>
+    controller.connect({
+      createTransport: () => transport,
+      url: () => "ws://localhost/ws",
+      messageFormat: "host",
+      signal,
+      waitUntilReady: () => healthy.promise,
+      checkHealth,
+      onNotification: (notification) => onNotification({ data: notification }),
+      onMessageError: vi.fn(),
+      decodeJson: jsonParseWithSpecialChar,
+      classifyClose: classifyCloseEvent,
+    });
+  return {
+    events,
+    healthy,
+    transport,
+    client,
+    connect,
+    onNotification,
+    store,
+    checkHealth,
+  };
+}
+
+describe("NotebookClient lifetime", () => {
+  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",
+      });
+      expect(transport.close).toHaveBeenCalledOnce();
+      expect(onNotification).not.toHaveBeenCalled();
+      lifetime.abort();
+    },
+  );
+
+  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,
+      );
+      expect(transport.reconnect).toHaveBeenCalledOnce();
+      await client.reconnect();
+      expect(checkHealth).toHaveBeenCalledOnce();
+      expect(transport.reconnect).toHaveBeenCalledTimes(2);
+      lifetime.abort();
+    },
+  );
+
+  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 health = new Deferred<boolean>();
+    checkHealth.mockReturnValue(health.promise);
+    const lifetime = new AbortController();
+    connect(lifetime.signal);
+    const attempt = client.reconnect();
+    lifetime.abort();
+    health.resolve(true);
+    await attempt;
+    expect(transport.reconnect).not.toHaveBeenCalled();
+  });
+
+  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("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();
+    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();
+    connect(first.signal);
+    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" } },
+        }),
+      }),
+    );
+    expect(onNotification).toHaveBeenCalledExactlyOnceWith({
+      data: { op: "reconnected" },
+    });
+    second.abort();
+  });
+});

package/src/core/host/connection.ts

@@ -0,0 +1,81 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+export const ConnectionState = {
+  NOT_STARTED: "NOT_STARTED",
+  CONNECTING: "CONNECTING",
+  OPEN: "OPEN",
+  CLOSING: "CLOSING",
+  CLOSED: "CLOSED",
+} as const;
+
+export type ConnectionState =
+  (typeof ConnectionState)[keyof typeof ConnectionState];
+
+export const ConnectionClosedReason = {
+  KERNEL_DISCONNECTED: "KERNEL_DISCONNECTED",
+  KERNEL_STARTUP_ERROR: "KERNEL_STARTUP_ERROR",
+} as const;
+
+export type ConnectionClosedReason =
+  (typeof ConnectionClosedReason)[keyof typeof ConnectionClosedReason];
+
+export type ConnectionStatus =
+  | {
+      state: typeof ConnectionState.CLOSED;
+      code: ConnectionClosedReason;
+      reason: string;
+    }
+  | {
+      state: typeof ConnectionState.CONNECTING;
+    }
+  | {
+      state:
+        | typeof ConnectionState.OPEN
+        | typeof ConnectionState.CLOSING
+        | typeof ConnectionState.NOT_STARTED;
+    };
+
+/** The recovery policy for a closed connection. */
+export interface CloseDecision {
+  kind: "terminal" | "gave-up" | "retry";
+  status: ConnectionStatus;
+}
+
+export type ConnectionEvent = "open" | "close" | "message" | "error";
+
+export interface IConnectionTransportMap {
+  open: WebSocketEventMap["open"];
+  message: WebSocketEventMap["message"];
+  close: WebSocketEventMap["close"];
+  error: WebSocketEventMap["error"];
+}
+
+export type ConnectionTransportCallback<T extends ConnectionEvent> = (
+  data: IConnectionTransportMap[T],
+) => void;
+
+/** Transport readiness, using the WebSocket readyState values. */
+export const TransportReadyState = {
+  CONNECTING: 0,
+  OPEN: 1,
+  CLOSING: 2,
+  CLOSED: 3,
+} as const;
+
+export type TransportReadyState =
+  (typeof TransportReadyState)[keyof typeof TransportReadyState];
+
+/** A reconnectable source of notebook messages. */
+export interface NotebookTransport {
+  reconnect(code?: number | undefined, reason?: string | undefined): void;
+  close(): void;
+  addEventListener<T extends ConnectionEvent>(
+    event: T,
+    callback: ConnectionTransportCallback<T>,
+  ): void;
+  removeEventListener<T extends ConnectionEvent>(
+    event: T,
+    callback: ConnectionTransportCallback<T>,
+  ): void;
+  readyState: TransportReadyState;
+}

package/src/core/host/events.ts

@@ -0,0 +1,60 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { z } from "zod";
+import * as Protocol from "./protocol";
+
+/**
+ * Notebook stream events, including native marimo notifications.
+ *
+ * Known events follow the generated protocol. Unknown events retain their name
+ * and cursor so clients can skip them without losing their place in the stream.
+ */
+
+/** Event kinds requested by the client; removals and controls are implicit. */
+export const NOTEBOOK_EVENT_TYPES = [
+  "notebook",
+  "document",
+  "cell",
+  "marimo",
+] as const satisfies readonly (Protocol.ObjectType | "marimo")[];
+
+const envelope = z.object({
+  event: z.string().min(1),
+  data: z.unknown(),
+  id: z.string().min(1).optional(),
+});
+
+const knownNames = new Set<string>(
+  Protocol.Event.options.flatMap((schema) => schema.shape.event.options),
+);
+
+/** A decoded event, or the name and cursor of an unrecognized event. */
+export type NotebookEvent =
+  | Protocol.EventOutput
+  | {
+      readonly event: "unknown";
+      readonly name: string;
+      readonly id?: string;
+    };
+
+const sessionEnvelope = z.object({ data: Protocol.MarimoNotification });
+
+/**
+ * Decode a host event or a legacy `{ data: notification }` session message.
+ *
+ * Throws if the envelope or a known event is malformed. Native notification
+ * payloads are passed through for the session handler to interpret.
+ */
+export function parseNotebookEvent(value: unknown): NotebookEvent {
+  if (typeof value === "object" && value !== null && !("event" in value)) {
+    return {
+      event: "marimo",
+      data: { marimo: sessionEnvelope.parse(value).data },
+    };
+  }
+  const parsed = envelope.parse(value);
+  if (knownNames.has(parsed.event)) {
+    return Protocol.Event.parse(parsed);
+  }
+  return { event: "unknown", name: parsed.event, id: parsed.id };
+}