Skip to content

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.

Name the notebook replica and narrow module entry points (#11509)

Trevor Manzb1b1125529ad
diff --git a/frontend/.oxlintrc.json b/frontend/.oxlintrc.json
index 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.js
index 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.js
index 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.js
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.md
index 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.ts
similarity index 98%
rename from frontend/src/core/host/__tests__/notebook-client.test.ts
rename to frontend/src/core/host/__tests__/replica.test.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
similarity index 93%
rename from frontend/src/core/host/notebook-client.ts
rename to frontend/src/core/host/replica.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
similarity index 93%
rename from frontend/src/core/websocket/__tests__/useNotebookClient.hook.test.tsx
rename to frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
similarity index 69%
rename from frontend/src/core/websocket/useNotebookClient.ts
rename to frontend/src/core/websocket/useNotebookReplica.ts
index 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.tsx
index 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 };
}