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
Name the notebook replica and narrow module entry points (#11509)
Trevor Manzb1b1125529ad
diff --git a/frontend/.oxlintrc.json b/frontend/.oxlintrc.jsonindex c4af8d50fe..2c23f280dd 100644--- a/frontend/.oxlintrc.json+++ b/frontend/.oxlintrc.json@@ -25,6 +25,7 @@"rules": {// === Marimo custom rules ==="marimo/host-imports": "error",+ "marimo/module-entry": "error","marimo/add-event-listener-object": "error","marimo/remove-event-listener-object": "error","marimo/prefer-object-params": "warn",diff --git a/frontend/lint/host-imports.js b/frontend/lint/host-imports.jsindex a4d32a0312..cf3838e70b 100644--- a/frontend/lint/host-imports.js+++ b/frontend/lint/host-imports.js@@ -2,7 +2,7 @@import NodePath from "node:path";-function isTest(path) {+export function isTest(path) {return (path.includes(`${NodePath.sep}__tests__${NodePath.sep}`) ||/\.(test|spec)(\.[cm]?[jt]sx?)?$/.test(path)@@ -52,37 +52,39 @@ export const hostImports = {"Host code may import only host modules, @marimo-team/client, jotai/vanilla, zod, and Logger.",});}- return {- ImportDeclaration(node) {- check(node.source, node);- },- ExportNamedDeclaration(node) {- if (node.source) {- check(node.source, node);- }- },- ExportAllDeclaration(node) {- check(node.source, node);- },- ImportExpression(node) {- check(node.source, node);- },- TSImportType(node) {- check(node.source, node);- },- TSImportEqualsDeclaration(node) {- if (node.moduleReference.type === "TSExternalModuleReference") {- check(node.moduleReference.expression, node);- }- },- CallExpression(node) {- if (- node.callee.type === "Identifier" &&- node.callee.name === "require"- ) {- check(node.arguments[0], node);- }- },- };+ return importVisitors(check);},};++/** Call `check` with the source of every import, export from, and require. */+export function importVisitors(check) {+ return {+ ImportDeclaration(node) {+ check(node.source, node);+ },+ ExportNamedDeclaration(node) {+ if (node.source) {+ check(node.source, node);+ }+ },+ ExportAllDeclaration(node) {+ check(node.source, node);+ },+ ImportExpression(node) {+ check(node.source, node);+ },+ TSImportType(node) {+ check(node.source, node);+ },+ TSImportEqualsDeclaration(node) {+ if (node.moduleReference.type === "TSExternalModuleReference") {+ check(node.moduleReference.expression, node);+ }+ },+ CallExpression(node) {+ if (node.callee.type === "Identifier" && node.callee.name === "require") {+ check(node.arguments[0], node);+ }+ },+ };+}diff --git a/frontend/lint/marimo-plugin.js b/frontend/lint/marimo-plugin.jsindex 52063f3e18..38a4471842 100644--- a/frontend/lint/marimo-plugin.js+++ b/frontend/lint/marimo-plugin.js@@ -1,6 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */import { hostImports } from "./host-imports.js";+import { moduleEntry } from "./module-entry.js";/*** Custom oxlint plugin with marimo-specific lint rules.@@ -331,6 +332,7 @@ const plugin = {},rules: {"host-imports": hostImports,+ "module-entry": moduleEntry,"add-event-listener-object": addEventListenerObject,"remove-event-listener-object": removeEventListenerObject,"prefer-object-params": preferObjectParams,diff --git a/frontend/lint/module-entry.js b/frontend/lint/module-entry.jsnew file mode 100644index 0000000000..58a7e4aa22--- /dev/null+++ b/frontend/lint/module-entry.js@@ -0,0 +1,46 @@+/* Copyright 2026 Marimo. All rights reserved. */++import NodePath from "node:path";+import { importVisitors, isTest } from "./host-imports.js";++/** Directories under `src/` that other code imports only through `index.ts`. */+const MODULES = ["core/host", "core/document"];++/** Keep each module's files private to it, behind its entry point. */+export const moduleEntry = {+ meta: {+ type: "problem",+ docs: { description: "Import a module through its entry point" },+ },+ createOnce(context) {+ function check(source, node) {+ const filename = context.filename;+ const marker = `${NodePath.sep}src${NodePath.sep}`;+ const index = filename.lastIndexOf(marker);+ const name = source?.value;+ if (index === -1 || isTest(filename) || typeof name !== "string") {+ return;+ }+ const src = filename.slice(0, index + marker.length);+ const target = name.startsWith(".")+ ? NodePath.resolve(NodePath.dirname(filename), name)+ : name.startsWith("@/")+ ? NodePath.resolve(src, name.slice(2))+ : null;+ if (target === null || isTest(target)) {+ return;+ }+ for (const module of MODULES) {+ const root = NodePath.resolve(src, module);+ const inside = (path) => path.startsWith(root + NodePath.sep);+ if (inside(target) && !inside(filename)) {+ context.report({+ node: source ?? node,+ message: `Import ${module} through its entry point, @/${module}.`,+ });+ }+ }+ }+ return importVisitors(check);+ },+};diff --git a/frontend/src/__tests__/module-entry.test.ts b/frontend/src/__tests__/module-entry.test.tsnew file mode 100644index 0000000000..0cce6665d2--- /dev/null+++ b/frontend/src/__tests__/module-entry.test.ts@@ -0,0 +1,32 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { expect, it } from "vitest";+import { moduleEntry } from "../../lint/module-entry.js";++/** Whether the rule reports importing `source` from `file`. */+function reports(file: string, source: string): boolean {+ let reported = false;+ const visitors = moduleEntry.createOnce({+ filename: `/repo/frontend/src/${file}`,+ report: () => {+ reported = true;+ },+ });+ visitors.ImportDeclaration({ source: { value: source } });+ return reported;+}++it.each([+ ["core/websocket/state.ts", "@/core/host", false],+ ["core/websocket/state.ts", "../host", false],+ ["core/websocket/state.ts", "@/core/document", false],+ ["core/host/replica.ts", "./resources/document", false],+ ["core/host/replica.ts", "@/core/host/backend", false],+ ["core/websocket/__tests__/a.test.ts", "../../host/replica", false],+ ["core/websocket/fixtures.ts", "../host/__tests__/fixtures", false],+ ["core/websocket/state.ts", "@/core/host/replica", true],+ ["core/websocket/state.ts", "../host/resources/document", true],+ ["core/websocket/state.ts", "../document/hooks", true],+])("from %s, importing %s reports %s", (file, source, expected) => {+ expect(reports(file, source)).toBe(expected);+});diff --git a/frontend/src/components/editor/chrome/wrapper/__tests__/attachment-status.test.tsx b/frontend/src/components/editor/chrome/wrapper/__tests__/attachment-status.test.tsxindex 83ec8ad3f5..76c75962ff 100644--- a/frontend/src/components/editor/chrome/wrapper/__tests__/attachment-status.test.tsx+++ b/frontend/src/components/editor/chrome/wrapper/__tests__/attachment-status.test.tsx@@ -16,14 +16,14 @@ import { TooltipProvider } from "@/components/ui/tooltip";import { toast } from "@/components/ui/use-toast";import type { Attachment } from "@/core/attachments/state";import { pairConfigAtom } from "@/core/config/pair";-import { createNotebookClient } from "@/core/host/notebook-client";+import { createNotebookReplica } from "@/core/host/replica";import {type StableSessionId,stableSessionIdAtom,} from "@/core/kernel/session";import { API } from "@/core/network/api";import { connectionAtom } from "@/core/network/connection";-import { notebookClientAtom } from "@/core/websocket/state";+import { notebookReplicaAtom } from "@/core/websocket/state";import { ConnectionState } from "@/core/websocket/types";import { Deferred } from "@/utils/Deferred";import { AttachmentStatus } from "../footer-items/attachment-status";@@ -45,8 +45,8 @@ function renderStatus(attachments: Attachment[] = [AGENT], preview = true) {const store = createStore();store.set(connectionAtom, { state: ConnectionState.OPEN });store.set(pairConfigAtom, { ...PAIR_CONFIG, hostEnabled: preview });- store.set(notebookClientAtom, {- ...createNotebookClient(store),+ store.set(notebookReplicaAtom, {+ ...createNotebookReplica(store),connectionAtom: atom({ state: ConnectionState.OPEN }),attachmentsAtom,});diff --git a/frontend/src/components/editor/errors/__tests__/send-error-report-button.test.tsx b/frontend/src/components/editor/errors/__tests__/send-error-report-button.test.tsxindex 4e16582982..94dbdaa5c0 100644--- a/frontend/src/components/editor/errors/__tests__/send-error-report-button.test.tsx+++ b/frontend/src/components/editor/errors/__tests__/send-error-report-button.test.tsx@@ -25,7 +25,7 @@ import {} from "@/core/cells/error-report";import { pairConfigAtom } from "@/core/config/pair";import { notebookStateFromSession } from "@/core/cells/session";-import { createNotebookClient } from "@/core/host/notebook-client";+import { createNotebookReplica } from "@/core/host/replica";import type { MarimoError, OutputMessage } from "@/core/kernel/messages";import {type StableSessionId,@@ -33,7 +33,7 @@ import {} from "@/core/kernel/session";import { API } from "@/core/network/api";import { connectionAtom } from "@/core/network/connection";-import { notebookClientAtom } from "@/core/websocket/state";+import { notebookReplicaAtom } from "@/core/websocket/state";import { ConnectionState } from "@/core/websocket/types";import { Deferred } from "@/utils/Deferred";import { HTTPError } from "@/utils/errors";@@ -97,8 +97,8 @@ function renderButton({const store = createStore();store.set(connectionAtom, { state: ConnectionState.OPEN });store.set(pairConfigAtom, { ...PAIR_CONFIG, hostEnabled: preview });- store.set(notebookClientAtom, {- ...createNotebookClient(store),+ store.set(notebookReplicaAtom, {+ ...createNotebookReplica(store),connectionAtom: atom({ state: ConnectionState.OPEN }),attachmentsAtom,});diff --git a/frontend/src/core/attachments/state.ts b/frontend/src/core/attachments/state.tsindex f9bb23b219..c46d2777f2 100644--- a/frontend/src/core/attachments/state.ts+++ b/frontend/src/core/attachments/state.ts@@ -2,12 +2,12 @@import { atom } from "jotai";import type { Attachment } from "@marimo-team/client/protocol";-import { notebookClientAtom } from "@/core/websocket/state";+import { notebookReplicaAtom } from "@/core/websocket/state";export type { Attachment } from "@marimo-team/client/protocol";export const agentAttachmentsAtom = atom((get) => {- const notebook = get(notebookClientAtom);+ const notebook = get(notebookReplicaAtom);return (notebook ? get(notebook.attachmentsAtom) : []).filter((attachment) => attachment.kind === "agent",);diff --git a/frontend/src/core/document/draft.ts b/frontend/src/core/document/draft.tsindex ae76a4b363..c0cadb73d5 100644--- a/frontend/src/core/document/draft.ts+++ b/frontend/src/core/document/draft.ts@@ -1,6 +1,6 @@/* Copyright 2026 Marimo. All rights reserved. */-import type { Document } from "../host/resources/document";+import type { Document } from "../host";import * as Protocol from "@marimo-team/client/protocol";/** The fields a client edits. Null code means the host withheld source. */diff --git a/frontend/src/core/document/index.ts b/frontend/src/core/document/index.tsindex d2be31de57..acf30e354c 100644--- a/frontend/src/core/document/index.ts+++ b/frontend/src/core/document/index.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */+/** The editable document, its drafts, and its synchronization with the host. */+export {DocumentProvider,useCellCode,@@ -10,12 +12,4 @@ export {useDocumentEdit,useDocumentSync,} from "./hooks";-export { createDocumentModel } from "./model";-export type {- DocumentEdit,- DocumentEditor,- DocumentModel,- DocumentSyncStatus,- EditableCell,- EditableDocument,-} from "./model";+export { createDocumentModel, type DocumentModel } from "./model";diff --git a/frontend/src/core/document/model.ts b/frontend/src/core/document/model.tsindex 70b0199d14..185d3acf17 100644--- a/frontend/src/core/document/model.ts+++ b/frontend/src/core/document/model.ts@@ -2,8 +2,7 @@import type * as Protocol from "@marimo-team/client/protocol";import type { Atom, createStore } from "jotai/vanilla";-import type { NotebookBackend } from "../host/backend";-import type { Document } from "../host/resources/document";+import type { Document, NotebookBackend } from "../host";import { createDocumentState, type DocumentState } from "./state";import { createDocumentSync, type DocumentSyncStatus } from "./sync";diff --git a/frontend/src/core/document/state.ts b/frontend/src/core/document/state.tsindex afd870d9d8..9a5c05cced 100644--- a/frontend/src/core/document/state.ts+++ b/frontend/src/core/document/state.ts@@ -6,7 +6,7 @@ import {type createStore,type WritableAtom,} from "jotai/vanilla";-import type { Document } from "../host/resources/document";+import type { Document } from "../host";import * as Protocol from "@marimo-team/client/protocol";import {acknowledge,diff --git a/frontend/src/core/document/sync.ts b/frontend/src/core/document/sync.tsindex 3bf516879c..b4265307ce 100644--- a/frontend/src/core/document/sync.ts+++ b/frontend/src/core/document/sync.ts@@ -3,8 +3,7 @@import { idempotencyKey, type Result } from "@marimo-team/client";import type * as Protocol from "@marimo-team/client/protocol";import { type Atom, atom, type createStore } from "jotai/vanilla";-import type { NotebookBackend } from "../host/backend";-import type { Document } from "../host/resources/document";+import type { Document, NotebookBackend } from "../host";import type { DocumentState, DocumentSubmission } from "./state";export type DocumentSyncStatus =diff --git a/frontend/src/core/host/AGENTS.md b/frontend/src/core/host/AGENTS.mdindex c2eafafdb3..5572f06be2 100644--- a/frontend/src/core/host/AGENTS.md+++ b/frontend/src/core/host/AGENTS.md@@ -4,13 +4,9 @@ Production code may import host modules, `@marimo-team/client`,`jotai/vanilla`, `zod`, and `@/utils/Logger`. Enforced by`marimo/host-imports`. Tests are exempt.+Code outside this directory imports it as `@/core/host`. Enforced by+`marimo/module-entry`.+The protocol schemas and types live in `@marimo-team/client/protocol`.Define interfaces here and inject application behavior through adapters.--`notebook-client.ts` follows the notebook with `NotebookEvents` from-`@marimo-team/client`, over a `NotebookTransport` the editor supplies. The-editor's transports for its session routes live in-`core/websocket/transports/notebook.ts`. Each kind of object is a `NotebookResource`-in `resources/` with pure handlers keyed by event name, composed with-`createNotebookReducer`. The client holds one state atom and exposes derived atoms.diff --git a/frontend/src/core/host/__tests__/notebook-client.test.ts b/frontend/src/core/host/__tests__/replica.test.tssimilarity index 98%rename from frontend/src/core/host/__tests__/notebook-client.test.tsrename to frontend/src/core/host/__tests__/replica.test.tsindex c54c2977f3..2517613153 100644--- a/frontend/src/core/host/__tests__/notebook-client.test.ts+++ b/frontend/src/core/host/__tests__/replica.test.ts@@ -7,7 +7,7 @@ import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";import { Deferred } from "@/utils/Deferred";import { ConnectionState } from "../../websocket/types";import type { ConnectionStatus } from "../connection";-import { createNotebookClient } from "../notebook-client";+import { createNotebookReplica } from "../replica";import { fakeBackend, fixtureEvents, fixtureMessages } from "./fixtures";/** One connection the fake transport opened. */@@ -41,7 +41,7 @@ function setup() {const checkHealth = vi.fn(async () => true);const store = createStore();const backend = fakeBackend({ transport, checkHealth });- const client = createNotebookClient(store);+ const client = createNotebookReplica(store);/** Follow the backend until `signal` aborts. */const connect = (signal: AbortSignal) => {const disconnect = client.connect(backend, {@@ -98,7 +98,7 @@ const notebook = {updated_at: null,};-describe("NotebookClient lifetime", () => {+describe("NotebookReplica lifetime", () => {it("ends the previous connection when it connects again", async () => {const { attempts, backend, client, opened, store } = setup();const first = client.connect(backend, { onNotification: vi.fn() });@@ -418,7 +418,7 @@ describe("NotebookClient lifetime", () => {});});-describe("NotebookClient attachments", () => {+describe("NotebookReplica attachments", () => {const [browser, agent] = fixtureEvents("notebook-events.sse").flatMap((event) => (event.event === "attachment" ? [event.data.attachment] : []),);diff --git a/frontend/src/core/host/backend.ts b/frontend/src/core/host/backend.tsindex bc42f2bcf9..de6ce62d11 100644--- a/frontend/src/core/host/backend.ts+++ b/frontend/src/core/host/backend.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */+/** A notebook's events and commands, from a host or a stand-in for one. */+import type { NotebookClient, NotebookTransport } from "@marimo-team/client";import type { NotebookId } from "@marimo-team/client/protocol";diff --git a/frontend/src/core/host/index.ts b/frontend/src/core/host/index.tsnew file mode 100644index 0000000000..cdd8d035a9--- /dev/null+++ b/frontend/src/core/host/index.ts@@ -0,0 +1,14 @@+/* Copyright 2026 Marimo. All rights reserved. */++/** Notebook backends and the replica that follows them. */++export type { NotebookBackend } from "./backend";+export {+ type CloseDecision,+ ConnectionClosedReason,+ ConnectionState,+ type ConnectionStatus,+} from "./connection";+export { createNotebookReplica, type NotebookReplica } from "./replica";+export type { Document } from "./resources/document";+export { createWasmNotebookBackend } from "./wasm";diff --git a/frontend/src/core/host/notebook-client.ts b/frontend/src/core/host/replica.tssimilarity index 93%rename from frontend/src/core/host/notebook-client.tsrename to frontend/src/core/host/replica.tsindex 7adcef8436..cc2a87f10f 100644--- a/frontend/src/core/host/notebook-client.ts+++ b/frontend/src/core/host/replica.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */+/** What a backend's stream has confirmed about a notebook, kept in atoms. */+import { Logger } from "@/utils/Logger";import {createNotebookReducer,@@ -27,9 +29,9 @@ type EditorEvent = NotebookEvent<(typeof TYPES)[number]>;/** A native marimo notification, passed through without interpretation. */const MarimoMessage = z.object({ marimo: z.unknown() });-/** A connection to a notebook on a marimo host. */-export interface NotebookClient {- /** Client connection status, independent of application session readiness. */+/** A notebook as its backend's stream reports it, kept current while connected. */+export interface NotebookReplica {+ /** Connection status, independent of application session readiness. */readonly connectionAtom: Atom<ConnectionStatus>;/** Identity and capabilities, available while the stream is connected and ready. */readonly notebookAtom: Atom<NotebookOutput | null>;@@ -42,7 +44,7 @@ export interface NotebookClient {*/readonly documentAtom: Atom<Document | null>;/**- * The backend this client follows, or null while not connected.+ * The backend this replica follows, or null while not connected.** Its commands reach the host that confirmed `documentAtom`. A temporary* disconnection keeps it. Connecting again or disconnecting replaces it.@@ -53,7 +55,7 @@ export interface NotebookClient {/*** Follow a backend, replacing any current connection.*- * The returned function ends this connection and clears the client's state.+ * The returned function ends this connection and clears the replica.* It does nothing once another connection has replaced this one.*/connect(@@ -98,10 +100,10 @@ function statusAfter(error: unknown): ConnectionStatus {return disconnected;}-/** Create a client without opening a connection. */-export function createNotebookClient(+/** Create a replica without connecting it. */+export function createNotebookReplica(store: ReturnType<typeof createStore>,-): NotebookClient {+): NotebookReplica {// `useNotebookSession` copies this into the editor's shared `connectionAtom`,// which gates features until MO-8051 derives availability separately.const connectionAtom = atom<ConnectionStatus>({@@ -128,7 +130,7 @@ export function createNotebookClient(: attachments.initial,);const backendAtom = atom<NotebookBackend | null>(null);- /** The connection this client follows. Connecting again ends it. */+ /** The connection this replica follows. Connecting again ends it. */let current: { end(): void; reconnect(): Promise<void> } | undefined;function setStatus(status: ConnectionStatus) {diff --git a/frontend/src/core/host/static.ts b/frontend/src/core/host/static.tsindex ed1c2ceb0b..e44cafbc90 100644--- a/frontend/src/core/host/static.ts+++ b/frontend/src/core/host/static.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */+/** A backend that serves a document snapshot without a host. */+import type * as Protocol from "@marimo-team/client/protocol";import type { NotebookBackend } from "./backend";diff --git a/frontend/src/core/host/wasm.ts b/frontend/src/core/host/wasm.tsindex 4b42abede4..b06d026f8e 100644--- a/frontend/src/core/host/wasm.ts+++ b/frontend/src/core/host/wasm.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */+/** A backend for the notebook running in the WASM worker. */+import {NotebookClient,StreamStopped,diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.tsindex 9f07fd52f9..941518032c 100644--- a/frontend/src/core/wasm/bridge.ts+++ b/frontend/src/core/wasm/bridge.ts@@ -11,7 +11,7 @@ import { reloadSafe } from "@/utils/reload-safe";import { generateUUID } from "@/utils/uuid";import { createModuleWorker } from "@/utils/worker";import { notebookIsRunningAtom } from "../cells/cells";-import { createWasmNotebookBackend } from "../host/wasm";+import { createWasmNotebookBackend } from "../host";import type { ClientCommand } from "../kernel/messages";import { getInitialAppMode } from "../mode";import { API } from "../network/api";diff --git a/frontend/src/core/websocket/__tests__/backend.test.ts b/frontend/src/core/websocket/__tests__/backend.test.tsindex af0ca8860a..bbabc5670b 100644--- a/frontend/src/core/websocket/__tests__/backend.test.ts+++ b/frontend/src/core/websocket/__tests__/backend.test.ts@@ -5,7 +5,7 @@ import { createStore } from "jotai/vanilla";import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";import { Deferred } from "@/utils/Deferred";import { ConnectionState } from "../../host/connection";-import { createNotebookClient } from "../../host/notebook-client";+import { createNotebookReplica } from "../../host/replica";import { createEditorBackend } from "../backend";const wasm = vi.hoisted(() => ({ enabled: false, consumer: vi.fn() }));@@ -132,7 +132,7 @@ describe("the session backend's startup", () => {.mockRejectedValue(new Error("Startup gave up"));const checkHealth = vi.fn().mockResolvedValue(healthy);const store = createStore();- const client = createNotebookClient(store);+ const client = createNotebookReplica(store);onTestFinished(client.connect(createEditorBackend({ ...options, waitUntilReady, checkHealth }),@@ -164,7 +164,7 @@ describe("the session backend's startup", () => {const ready = new Deferred<void>();const waitUntilReady = vi.fn(() => ready.promise);const backend = createEditorBackend({ ...options, waitUntilReady });- const client = createNotebookClient(createStore());+ const client = createNotebookReplica(createStore());// Strict Mode connects, disconnects, and connects again.client.connect(backend, { onNotification: vi.fn() })();onTestFinished(client.connect(backend, { onNotification: vi.fn() }));@@ -180,7 +180,7 @@ describe("the session backend's startup", () => {const opened = sockets();const ready = new Deferred<void>();const store = createStore();- const client = createNotebookClient(store);+ const client = createNotebookReplica(store);const disconnect = client.connect(createEditorBackend({ ...options, waitUntilReady: () => ready.promise }),{ onNotification: vi.fn() },diff --git a/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx b/frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsxsimilarity index 93%rename from frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsxrename to frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsxindex f793cb3f79..dde443a682 100644--- a/frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx+++ b/frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsx@@ -8,10 +8,10 @@ import { beforeEach, describe, expect, it, vi } from "vitest";import type { NotebookTransport } from "@marimo-team/client";import { ConnectionState } from "../types";import { createEditorBackend } from "../backend";-import { useNotebookClient } from "../useNotebookClient";+import { useNotebookReplica } from "../useNotebookReplica";import { fakeBackend, fixtureMessages } from "../../host/__tests__/fixtures";import { agentAttachmentsAtom } from "../../attachments/state";-import { notebookClientAtom } from "../state";+import { notebookReplicaAtom } from "../state";vi.mock("../backend", () => ({ createEditorBackend: vi.fn() }));@@ -56,7 +56,7 @@ function setup(strict = false) {const wrapper = ({ children }: PropsWithChildren) => (<Provider store={store}>{children}</Provider>);- const hook = renderHook((props) => useNotebookClient(props), {+ const hook = renderHook((props) => useNotebookReplica(props), {initialProps: options,reactStrictMode: strict,wrapper,@@ -68,7 +68,7 @@ beforeEach(() => {vi.mocked(createEditorBackend).mockReset();});-describe("useNotebookClient", () => {+describe("useNotebookReplica", () => {it("exposes host presence to the UI without waiting for kernel-ready", async () => {const fake = makeTransport();vi.mocked(createEditorBackend).mockReturnValue(@@ -76,7 +76,7 @@ describe("useNotebookClient", () => {);const { result, store, unmount } = setup();await act(async () => Promise.resolve());- expect(store.get(notebookClientAtom)).toBe(result.current);+ expect(store.get(notebookReplicaAtom)).toBe(result.current);const [connection] = fake.opened;act(() => {connection.open();@@ -92,7 +92,7 @@ describe("useNotebookClient", () => {},]);unmount();- expect(store.get(notebookClientAtom)).toBeNull();+ expect(store.get(notebookReplicaAtom)).toBeNull();expect(store.get(agentAttachmentsAtom)).toEqual([]);});diff --git a/frontend/src/core/websocket/backend.ts b/frontend/src/core/websocket/backend.tsindex 3f62bb7192..479339039a 100644--- a/frontend/src/core/websocket/backend.ts+++ b/frontend/src/core/websocket/backend.ts@@ -1,8 +1,10 @@/* Copyright 2026 Marimo. All rights reserved. */+/** The backend the editor follows, chosen once for its mode. */+import { NotebookClient, StreamStopped } from "@marimo-team/client";import type { NotebookId } from "@marimo-team/client/protocol";-import type { NotebookBackend } from "../host/backend";+import type { NotebookBackend } from "../host";import { PyodideBridge } from "../wasm/bridge";import { isWasm } from "../wasm/utils";import {diff --git a/frontend/src/core/websocket/connection-state.ts b/frontend/src/core/websocket/connection-state.tsindex 9f4116a99f..690f0459f4 100644--- a/frontend/src/core/websocket/connection-state.ts+++ b/frontend/src/core/websocket/connection-state.ts@@ -1,6 +1,6 @@/* Copyright 2026 Marimo. All rights reserved. */-import type { CloseDecision } from "../host/connection";+import type { CloseDecision } from "../host";import { Logger } from "@/utils/Logger";import { ConnectionState, WebSocketClosedReason } from "./types";diff --git a/frontend/src/core/websocket/state.ts b/frontend/src/core/websocket/state.tsindex 0aaa71538a..1cfdaf333b 100644--- a/frontend/src/core/websocket/state.ts+++ b/frontend/src/core/websocket/state.ts@@ -1,7 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */import { atom } from "jotai";-import type { NotebookClient } from "../host/notebook-client";+import type { NotebookReplica } from "../host";-/** The client owned by the mounted notebook session. */-export const notebookClientAtom = atom<NotebookClient | null>(null);+/** The replica owned by the mounted notebook session. */+export const notebookReplicaAtom = atom<NotebookReplica | null>(null);diff --git a/frontend/src/core/websocket/transports/__tests__/notebook.test.ts b/frontend/src/core/websocket/transports/__tests__/notebook.test.tsindex 39b8f3be76..5ff05ea6ba 100644--- a/frontend/src/core/websocket/transports/__tests__/notebook.test.ts+++ b/frontend/src/core/websocket/transports/__tests__/notebook.test.ts@@ -7,7 +7,7 @@ import {} from "@marimo-team/client";import { createStore } from "jotai/vanilla";import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";-import { createNotebookClient } from "../../../host/notebook-client";+import { createNotebookReplica } from "../../../host/replica";import { fakeBackend, fixtureMessages } from "../../../host/__tests__/fixtures";import { ConnectionState } from "../../../host/connection";import { Deferred } from "@/utils/Deferred";@@ -296,7 +296,7 @@ describe.each(["websocket", "sse"] as const)(const url = vi.fn(() => target);const connection = network(transportType, url);const store = createStore();- const client = createNotebookClient(store);+ const client = createNotebookReplica(store);onTestFinished(client.connect(connection.backend, { onNotification: vi.fn() }),);@@ -358,7 +358,7 @@ describe.each(["websocket", "sse"] as const)(let target = `${base}?session_id=s1&file=a.py&access_token=a`;const connection = network(transportType, () => target);const store = createStore();- const client = createNotebookClient(store);+ const client = createNotebookReplica(store);onTestFinished(client.connect(connection.backend, { onNotification: vi.fn() }),);diff --git a/frontend/src/core/websocket/types.ts b/frontend/src/core/websocket/types.tsindex cd0389684e..2029325b1d 100644--- a/frontend/src/core/websocket/types.ts+++ b/frontend/src/core/websocket/types.ts@@ -1,12 +1,12 @@/* Copyright 2026 Marimo. All rights reserved. */-import type { ConnectionStatus as HostConnectionStatus } from "../host/connection";+import type { ConnectionStatus as HostConnectionStatus } from "../host";import type { NotificationMessageData } from "../kernel/messages";export {ConnectionState,ConnectionClosedReason as WebSocketClosedReason,-} from "../host/connection";+} from "../host";export type ConnectionPhase =| NotificationMessageData<"startup-progress">["phase"]diff --git a/frontend/src/core/websocket/useNotebookClient.ts b/frontend/src/core/websocket/useNotebookReplica.tssimilarity index 69%rename from frontend/src/core/websocket/useNotebookClient.tsrename to frontend/src/core/websocket/useNotebookReplica.tsindex 4762b1701d..2693bfb3be 100644--- a/frontend/src/core/websocket/useNotebookClient.ts+++ b/frontend/src/core/websocket/useNotebookReplica.ts@@ -1,5 +1,7 @@/* Copyright 2026 Marimo. All rights reserved. */+/** The editor session's replica, following its backend while mounted. */+import { useStore } from "jotai";import { useEffect, useMemo } from "react";import useEvent from "react-use-event-hook";@@ -7,28 +9,25 @@ import type {NotificationMessage,NotificationPayload,} from "../kernel/messages";-import {- createNotebookClient,- type NotebookClient,-} from "../host/notebook-client";-import { notebookClientAtom } from "./state";+import { createNotebookReplica, type NotebookReplica } from "../host";+import { notebookReplicaAtom } from "./state";import { createEditorBackend, type EditorBackendOptions } from "./backend";type Options = EditorBackendOptions & {onNotification: (notification: NotificationPayload) => void;};-export function useNotebookClient(options: Options): NotebookClient {+export function useNotebookReplica(options: Options): NotebookReplica {const store = useStore();const { static: isStatic, transportType } = options;- const client = useMemo(() => createNotebookClient(store), [store]);+ const replica = useMemo(() => createNotebookReplica(store), [store]);const url = useEvent(options.url);const headers = useEvent(options.headers);const notebookUrl = useEvent(options.notebookUrl);const waitUntilReady = useEvent(options.waitUntilReady);const checkHealth = useEvent(options.checkHealth);const onNotification = useEvent(options.onNotification);- // Opens nothing until the client follows it.+ // Opens nothing until the replica follows it.const backend = useMemo(() =>createEditorBackend({@@ -52,19 +51,19 @@ export function useNotebookClient(options: Options): NotebookClient {);useEffect(() => {- store.set(notebookClientAtom, client);- const disconnect = client.connect(backend, {+ store.set(notebookReplicaAtom, replica);+ const disconnect = replica.connect(backend, {// The host validates the envelope, not the native notification contents.onNotification: (notification) =>onNotification({ data: notification as NotificationMessage }),});return () => {disconnect();- if (store.get(notebookClientAtom) === client) {- store.set(notebookClientAtom, null);+ if (store.get(notebookReplicaAtom) === replica) {+ store.set(notebookReplicaAtom, null);}};- }, [client, backend, store, onNotification]);+ }, [replica, backend, store, onNotification]);- return client;+ return replica;}diff --git a/frontend/src/core/websocket/useNotebookSession.tsx b/frontend/src/core/websocket/useNotebookSession.tsxindex 806684fdd4..e5464d91da 100644--- a/frontend/src/core/websocket/useNotebookSession.tsx+++ b/frontend/src/core/websocket/useNotebookSession.tsx@@ -12,7 +12,7 @@ import type {NotificationMessageData,NotificationPayload,} from "@/core/kernel/messages";-import { useNotebookClient } from "@/core/websocket/useNotebookClient";+import { useNotebookReplica } from "@/core/websocket/useNotebookReplica";import { renderHTML } from "@/plugins/core/RenderHTML";import {handleWidgetMessage,@@ -408,7 +408,7 @@ export function useNotebookSession(opts: {variant: "danger",});};- const notebook = useNotebookClient({+ const replica = useNotebookReplica({static: isStaticNotebook(),transportType,url: () =>@@ -438,7 +438,7 @@ export function useNotebookSession(opts: {// Subscribe before passive connection setup: static/WASM transports can emit synchronously.useLayoutEffect(() => {const updateConnection = () => {- const status = store.get(notebook.connectionAtom);+ const status = store.get(replica.connectionAtom);if (status.state === ConnectionState.NOT_STARTED) {return;}@@ -469,16 +469,16 @@ export function useNotebookSession(opts: {return status;});};- const unsubscribe = store.sub(notebook.connectionAtom, updateConnection);+ const unsubscribe = store.sub(replica.connectionAtom, updateConnection);updateConnection();return unsubscribe;}, [- notebook,+ replica,store,setConnection,setKernelStartupError,updateStartupProgress,]);- return { notebook, connection, reconnect: notebook.reconnect };+ return { replica, connection, reconnect: replica.reconnect };}