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.

Organize notebook state, hooks, sessions, and transports (#11531)

Trevor Manz78ded0dc98ba
diff --git a/frontend/.oxlintrc.json b/frontend/.oxlintrc.json
index 2c23f280dd..a2f3990cfc 100644
--- a/frontend/.oxlintrc.json
+++ b/frontend/.oxlintrc.json
@@ -24,7 +24,7 @@
},
"rules": {
// === Marimo custom rules ===
- "marimo/host-imports": "error",
+ "marimo/replica-imports": "error",
"marimo/module-entry": "error",
"marimo/add-event-listener-object": "error",
"marimo/remove-event-listener-object": "error",
diff --git a/frontend/lint/marimo-plugin.js b/frontend/lint/marimo-plugin.js
index 38a4471842..7d06dab40c 100644
--- a/frontend/lint/marimo-plugin.js
+++ b/frontend/lint/marimo-plugin.js
@@ -1,6 +1,6 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { hostImports } from "./host-imports.js";
+import { replicaImports } from "./replica-imports.js";
import { moduleEntry } from "./module-entry.js";
/**
@@ -331,7 +331,7 @@ const plugin = {
name: "marimo",
},
rules: {
- "host-imports": hostImports,
+ "replica-imports": replicaImports,
"module-entry": moduleEntry,
"add-event-listener-object": addEventListenerObject,
"remove-event-listener-object": removeEventListenerObject,
diff --git a/frontend/lint/module-entry.js b/frontend/lint/module-entry.js
index 58a7e4aa22..5dd3e41099 100644
--- a/frontend/lint/module-entry.js
+++ b/frontend/lint/module-entry.js
@@ -1,10 +1,14 @@
/* Copyright 2026 Marimo. All rights reserved. */
import NodePath from "node:path";
-import { importVisitors, isTest } from "./host-imports.js";
+import { importVisitors, isTest } from "./replica-imports.js";
/** Directories under `src/` that other code imports only through `index.ts`. */
-const MODULES = ["core/host", "core/document"];
+const MODULES = [
+ "core/notebook",
+ "core/notebook/replica",
+ "core/notebook/document",
+];
/** Keep each module's files private to it, behind its entry point. */
export const moduleEntry = {
@@ -27,7 +31,11 @@ export const moduleEntry = {
: name.startsWith("@/")
? NodePath.resolve(src, name.slice(2))
: null;
- if (target === null || isTest(target)) {
+ if (
+ target === null ||
+ isTest(target) ||
+ MODULES.some((module) => target === NodePath.resolve(src, module))
+ ) {
return;
}
for (const module of MODULES) {
diff --git a/frontend/lint/host-imports.js b/frontend/lint/replica-imports.js
similarity index 81%
rename from frontend/lint/host-imports.js
rename to frontend/lint/replica-imports.js
index cf3838e70b..37c3ec47cb 100644
--- a/frontend/lint/host-imports.js
+++ b/frontend/lint/replica-imports.js
@@ -9,16 +9,16 @@ export function isTest(path) {
);
}
-/** Keep the host core independent of application implementations. */
-export const hostImports = {
+/** Keep the notebook replica independent of application implementations. */
+export const replicaImports = {
meta: {
type: "problem",
- docs: { description: "Restrict dependencies of the host core" },
+ docs: { description: "Restrict dependencies of the notebook replica" },
},
createOnce(context) {
function check(source, node) {
const filename = context.filename;
- const marker = `${NodePath.sep}src${NodePath.sep}core${NodePath.sep}host${NodePath.sep}`;
+ const marker = `${NodePath.sep}src${NodePath.sep}core${NodePath.sep}notebook${NodePath.sep}replica${NodePath.sep}`;
const index = filename.lastIndexOf(marker);
if (index === -1 || isTest(filename.slice(index))) {
return;
@@ -37,19 +37,19 @@ export const hostImports = {
const target = name.startsWith(".")
? NodePath.resolve(NodePath.dirname(filename), name)
: name.startsWith("@/")
- ? NodePath.resolve(root, "../..", name.slice(2))
+ ? NodePath.resolve(root, "../../..", name.slice(2))
: null;
if (target?.startsWith(root) && !isTest(target)) {
return;
}
- if (target === NodePath.resolve(root, "../../utils/Logger")) {
+ if (target === NodePath.resolve(root, "../../../utils/Logger")) {
return;
}
}
context.report({
node: source ?? node,
message:
- "Host code may import only host modules, @marimo-team/client, jotai/vanilla, zod, and Logger.",
+ "Replica code may import only replica modules, @marimo-team/client, jotai/vanilla, zod, and Logger.",
});
}
return importVisitors(check);
diff --git a/frontend/src/__tests__/module-entry.test.ts b/frontend/src/__tests__/module-entry.test.ts
index 0cce6665d2..92094088d6 100644
--- a/frontend/src/__tests__/module-entry.test.ts
+++ b/frontend/src/__tests__/module-entry.test.ts
@@ -17,16 +17,28 @@ function reports(file: string, source: string): boolean {
}
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],
+ ["components/editor.tsx", "@/core/notebook", false],
+ ["components/editor.tsx", "@/core/notebook/attachments", true],
+ ["core/notebook/index.ts", "./attachments", false],
+ ["core/notebook/index.ts", "./document/hooks", true],
+ ["core/session/active-notebook.ts", "@/core/notebook/replica", false],
+ ["core/session/active-notebook.ts", "../notebook/replica", false],
+ ["core/session/active-notebook.ts", "@/core/notebook/document", false],
+ ["core/notebook/replica/replica.ts", "./resources/document", false],
+ [
+ "core/notebook/replica/replica.ts",
+ "@/core/notebook/replica/backend",
+ false,
+ ],
+ ["core/session/__tests__/a.test.ts", "../../notebook/replica/replica", false],
+ ["core/session/fixtures.ts", "../notebook/replica/__tests__/fixtures", false],
+ ["core/session/active-notebook.ts", "@/core/notebook/replica/replica", true],
+ [
+ "core/session/active-notebook.ts",
+ "../notebook/replica/resources/document",
+ true,
+ ],
+ ["core/session/active-notebook.ts", "../notebook/document/hooks", true],
])("from %s, importing %s reports %s", (file, source, expected) => {
expect(reports(file, source)).toBe(expected);
});
diff --git a/frontend/src/__tests__/mount.test.ts b/frontend/src/__tests__/mount.test.ts
index 72140c4b80..8a2f6b474c 100644
--- a/frontend/src/__tests__/mount.test.ts
+++ b/frontend/src/__tests__/mount.test.ts
@@ -7,7 +7,7 @@ import { kioskModeAtom } from "@/core/mode";
import { connectionAtom } from "@/core/network/connection";
import { store } from "@/core/state/jotai";
import { isStaticNotebook } from "@/core/static/static-state";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { pairConfigAtom } from "@/core/config/pair";
import { PAIR_CONFIG } from "./fixtures/pair-config";
import { mount, visibleForTesting } from "../mount";
diff --git a/frontend/src/__tests__/host-imports.test.ts b/frontend/src/__tests__/replica-imports.test.ts
similarity index 81%
rename from frontend/src/__tests__/host-imports.test.ts
rename to frontend/src/__tests__/replica-imports.test.ts
index bb12b59080..89458633eb 100644
--- a/frontend/src/__tests__/host-imports.test.ts
+++ b/frontend/src/__tests__/replica-imports.test.ts
@@ -8,31 +8,31 @@ import NodeUrl from "node:url";
import { expect, it } from "vitest";
import { z } from "zod";
-it("enforces host dependencies for runtime and type imports", () => {
+it("enforces replica dependencies for runtime and type imports", () => {
const frontend = NodeUrl.fileURLToPath(
- new NodeUrl.URL("../../", import.meta.url),
+ new NodeUrl.URL("../..", import.meta.url),
);
const directory = NodeFs.mkdtempSync(
- NodePath.join(NodeOs.tmpdir(), "host-imports-"),
+ NodePath.join(NodeOs.tmpdir(), "replica-imports-"),
);
const files = {
- "src/core/host/allowed.ts": `
+ "src/core/notebook/replica/allowed.ts": `
import { atom } from "jotai/vanilla";
import { z } from "zod";
import * as Protocol from "@marimo-team/client/protocol";
import { Logger } from "@/utils/Logger";
import type { Document } from "./document";
- export * from "@/core/host/events";
+ export * from "@/core/notebook/replica/events";
type Event = import("./events").NotebookEvent;
void import("./protocol");
`,
- "src/core/host/protocol.ts": `
+ "src/core/notebook/replica/protocol.ts": `
import type { NotificationMessage as A } from "../kernel/messages";
import { type NotificationMessage as B } from "@/core/kernel/messages";
import { NotificationMessage as C } from "../kernel/messages";
import type { NotificationPayload } from "../kernel/messages";
`,
- "src/core/host/forbidden.ts": `
+ "src/core/notebook/replica/forbidden.ts": `
import { useEffect } from "react";
import type { NotificationMessage } from "../kernel/messages";
export * from "../kernel/messages";
@@ -44,10 +44,10 @@ it("enforces host dependencies for runtime and type imports", () => {
import "./__tests__/allowed";
import "./allowed.test";
`,
- "src/core/host/__tests__/allowed.ts": `import { useEffect } from "react";`,
- "src/core/host/allowed.test.ts": `import { useEffect } from "react";`,
- "src/core/host/allowed.spec.ts": `import { useEffect } from "react";`,
- "src/core/websocket/allowed.ts": `import { useEffect } from "react";`,
+ "src/core/notebook/replica/__tests__/allowed.ts": `import { useEffect } from "react";`,
+ "src/core/notebook/replica/allowed.test.ts": `import { useEffect } from "react";`,
+ "src/core/notebook/replica/allowed.spec.ts": `import { useEffect } from "react";`,
+ "src/core/session/allowed.ts": `import { useEffect } from "react";`,
};
try {
for (const [path, source] of Object.entries(files)) {
diff --git a/frontend/src/core/attachments/__tests__/toast.test.tsx b/frontend/src/components/editor/__tests__/agent-toast.test.tsx
similarity index 97%
rename from frontend/src/core/attachments/__tests__/toast.test.tsx
rename to frontend/src/components/editor/__tests__/agent-toast.test.tsx
index 3df9cd5f13..bd062b284e 100644
--- a/frontend/src/core/attachments/__tests__/toast.test.tsx
+++ b/frontend/src/components/editor/__tests__/agent-toast.test.tsx
@@ -5,7 +5,7 @@ import { act, render, renderHook } from "@testing-library/react";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { Toaster } from "@/components/ui/toaster";
import { clearToasts, toast, useToast } from "@/components/ui/use-toast";
-import { agentToast } from "../toast";
+import { agentToast } from "../agent-toast";
describe("agent notifications", () => {
beforeEach(() => {
diff --git a/frontend/src/components/editor/actions/useRestartKernel.tsx b/frontend/src/components/editor/actions/useRestartKernel.tsx
index 517c2aef94..e7714b56bc 100644
--- a/frontend/src/components/editor/actions/useRestartKernel.tsx
+++ b/frontend/src/components/editor/actions/useRestartKernel.tsx
@@ -5,7 +5,7 @@ import { useImperativeModal } from "@/components/modal/ImperativeModal";
import { AlertDialogDestructiveAction } from "@/components/ui/alert-dialog";
import { connectionAtom } from "@/core/network/connection";
import { useRequestClient } from "@/core/network/requests";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { reloadSafe } from "@/utils/reload-safe";
export function useRestartKernel() {
diff --git a/frontend/src/core/attachments/toast.ts b/frontend/src/components/editor/agent-toast.ts
similarity index 100%
rename from frontend/src/core/attachments/toast.ts
rename to frontend/src/components/editor/agent-toast.ts
diff --git a/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx b/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
index 216644526b..e77ad6099d 100644
--- a/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
+++ b/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
@@ -11,7 +11,7 @@ import { AppConfigSchema } from "@/core/config/config-schema";
import { kernelStartupErrorAtom } from "@/core/errors/state";
import { connectionAtom } from "@/core/network/connection";
import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
-import { WebSocketClosedReason, ConnectionState } from "@/core/websocket/types";
+import { WebSocketClosedReason, ConnectionState } from "@/core/session/types";
import { chromeAtom } from "../../chrome/state";
import { runtimeDetailsExpandedAtom } from "../../chrome/panels/runtime-details-state";
import { ConnectionNotice } from "../connection-notice";
diff --git a/frontend/src/components/editor/alerts/connection-notice.tsx b/frontend/src/components/editor/alerts/connection-notice.tsx
index bc67a7783c..163f4aeafb 100644
--- a/frontend/src/components/editor/alerts/connection-notice.tsx
+++ b/frontend/src/components/editor/alerts/connection-notice.tsx
@@ -8,7 +8,7 @@ import type { AppConfig } from "@/core/config/config-schema";
import { connectionAtom } from "@/core/network/connection";
import { useConnectionNotice } from "@/core/network/useConnectionNotice";
import { sandboxAtom } from "@/core/packages/sandbox-state";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { useInterval } from "@/hooks/useInterval";
import { cn } from "@/utils/cn";
import { runtimeDetailsExpandedAtom } from "../chrome/panels/runtime-details-state";
diff --git a/frontend/src/components/editor/app-container.tsx b/frontend/src/components/editor/app-container.tsx
index d26f0ada67..510b11795c 100644
--- a/frontend/src/components/editor/app-container.tsx
+++ b/frontend/src/components/editor/app-container.tsx
@@ -8,7 +8,7 @@ import {
type ConnectionStatus,
WebSocketClosedReason,
ConnectionState,
-} from "@/core/websocket/types";
+} from "@/core/session/types";
import { cn } from "@/utils/cn";
import { DynamicFavicon } from "./dynamic-favicon";
import { StatusOverlay } from "./header/status";
diff --git a/frontend/src/components/editor/boundary/__tests__/ErrorBoundary.test.tsx b/frontend/src/components/editor/boundary/__tests__/ErrorBoundary.test.tsx
index b7dd5dbd7d..2dedcf0937 100644
--- a/frontend/src/components/editor/boundary/__tests__/ErrorBoundary.test.tsx
+++ b/frontend/src/components/editor/boundary/__tests__/ErrorBoundary.test.tsx
@@ -14,7 +14,7 @@ import { requestClientAtom } from "@/core/network/requests";
import type { EnvironmentInfo } from "@/core/network/types";
import { filenameAtom } from "@/core/saving/file-state";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { ErrorBoundary } from "../ErrorBoundary";
vi.mock("@/utils/copy", () => ({
diff --git a/frontend/src/components/editor/cell/CreateCellButton.tsx b/frontend/src/components/editor/cell/CreateCellButton.tsx
index a351dca0c4..de5adb00eb 100644
--- a/frontend/src/components/editor/cell/CreateCellButton.tsx
+++ b/frontend/src/components/editor/cell/CreateCellButton.tsx
@@ -16,8 +16,8 @@ import { MARKDOWN_INITIAL_HIDE_CODE } from "@/core/codemirror/language/languages
import {
getConnectionTooltip,
isAppInteractionDisabled,
-} from "@/core/websocket/connection-utils";
-import type { ConnectionState } from "@/core/websocket/types";
+} from "@/core/session/connection-utils";
+import type { ConnectionState } from "@/core/session/types";
import { cn } from "@/utils/cn";
import { Tooltip } from "../../ui/tooltip";
import { MarkdownIcon, PythonIcon } from "./code/icons";
diff --git a/frontend/src/components/editor/cell/DeleteButton.tsx b/frontend/src/components/editor/cell/DeleteButton.tsx
index 4950702159..64c997e8b2 100644
--- a/frontend/src/components/editor/cell/DeleteButton.tsx
+++ b/frontend/src/components/editor/cell/DeleteButton.tsx
@@ -5,8 +5,8 @@ import type { RuntimeState } from "@/core/network/types";
import {
getConnectionTooltip,
isAppInteractionDisabled,
-} from "@/core/websocket/connection-utils";
-import type { ConnectionState } from "@/core/websocket/types";
+} from "@/core/session/connection-utils";
+import type { ConnectionState } from "@/core/session/types";
import { cn } from "@/utils/cn";
import { Events } from "@/utils/events";
import { Button } from "../../ui/button";
diff --git a/frontend/src/components/editor/cell/RunButton.tsx b/frontend/src/components/editor/cell/RunButton.tsx
index 04284ac2ca..1394155e62 100644
--- a/frontend/src/components/editor/cell/RunButton.tsx
+++ b/frontend/src/components/editor/cell/RunButton.tsx
@@ -5,8 +5,8 @@ import type { CellConfig, RuntimeState } from "@/core/network/types";
import {
getConnectionTooltip,
isAppInteractionDisabled,
-} from "@/core/websocket/connection-utils";
-import type { ConnectionState } from "@/core/websocket/types";
+} from "@/core/session/connection-utils";
+import type { ConnectionState } from "@/core/session/types";
import { renderShortcut } from "../../shortcuts/renderShortcut";
import { ToolbarItem } from "./toolbar";
diff --git a/frontend/src/components/editor/cell/StopButton.tsx b/frontend/src/components/editor/cell/StopButton.tsx
index 2c08164f72..f003dc51e5 100644
--- a/frontend/src/components/editor/cell/StopButton.tsx
+++ b/frontend/src/components/editor/cell/StopButton.tsx
@@ -3,8 +3,8 @@ import { SquareIcon } from "lucide-react";
import type { JSX } from "react";
import { useRequestClient } from "@/core/network/requests";
import type { RuntimeState } from "@/core/network/types";
-import { isAppInteractionDisabled } from "@/core/websocket/connection-utils";
-import type { ConnectionState } from "@/core/websocket/types";
+import { isAppInteractionDisabled } from "@/core/session/connection-utils";
+import type { ConnectionState } from "@/core/session/types";
import { Functions } from "@/utils/functions";
import { renderShortcut } from "../../shortcuts/renderShortcut";
import { ToolbarItem } from "./toolbar";
diff --git a/frontend/src/components/editor/cell/code/cell-editor.tsx b/frontend/src/components/editor/cell/code/cell-editor.tsx
index 41a81579bb..80e837d88d 100644
--- a/frontend/src/components/editor/cell/code/cell-editor.tsx
+++ b/frontend/src/components/editor/cell/code/cell-editor.tsx
@@ -41,7 +41,7 @@ import { connectionAtom } from "@/core/network/connection";
import { useRequestClient } from "@/core/network/requests";
import { canUseRtc, isRtcEnabled } from "@/core/rtc/state";
import { useSaveNotebook } from "@/core/saving/save-component";
-import { isAppConnecting } from "@/core/websocket/connection-utils";
+import { isAppConnecting } from "@/core/session/connection-utils";
import type { Theme } from "@/theme/useTheme";
import { cn } from "@/utils/cn";
import { invariant } from "@/utils/invariant";
diff --git a/frontend/src/components/editor/chrome/components/__tests__/feedback-button.test.tsx b/frontend/src/components/editor/chrome/components/__tests__/feedback-button.test.tsx
index 0007b17f1b..eddd0476b0 100644
--- a/frontend/src/components/editor/chrome/components/__tests__/feedback-button.test.tsx
+++ b/frontend/src/components/editor/chrome/components/__tests__/feedback-button.test.tsx
@@ -14,7 +14,7 @@ import { requestClientAtom } from "@/core/network/requests";
import type { EnvironmentInfo } from "@/core/network/types";
import { filenameAtom } from "@/core/saving/file-state";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import * as copyModule from "@/utils/copy";
import { FeedbackModal } from "../feedback-button";
diff --git a/frontend/src/components/editor/chrome/components/feedback-button.tsx b/frontend/src/components/editor/chrome/components/feedback-button.tsx
index cacd17f5fc..cd67980c8c 100644
--- a/frontend/src/components/editor/chrome/components/feedback-button.tsx
+++ b/frontend/src/components/editor/chrome/components/feedback-button.tsx
@@ -39,7 +39,7 @@ import { connectionAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
import { filenameAtom } from "@/core/saving/file-state";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { useAsyncData } from "@/hooks/useAsyncData";
import { useLocalStorage } from "@/hooks/useLocalStorage";
import { cn } from "@/utils/cn";
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
index e825643198..cda8ece724 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/packages-panel.test.tsx
@@ -25,7 +25,7 @@ import {
import { useInstallPackages } from "@/core/packages/useInstallPackage";
import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import PackagesPanel from "../packages-panel";
import { PanelSectionProvider } from "../panel-context";
import { RuntimeStatusToggle } from "../runtime-status-toggle";
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx
index daeb6c5f18..d547846e47 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx
@@ -11,7 +11,7 @@ import { kernelStartupErrorAtom } from "@/core/errors/state";
import { connectionAtom, startupProgressAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
import { sandboxAtom } from "@/core/packages/sandbox-state";
-import { WebSocketClosedReason, ConnectionState } from "@/core/websocket/types";
+import { WebSocketClosedReason, ConnectionState } from "@/core/session/types";
import PackagesPanel from "../packages-panel";
import { PanelSectionProvider } from "../panel-context";
import { RuntimeStatusToggle } from "../runtime-status-toggle";
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
index 12135601ba..10e9c1ab8e 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/sandbox-recovery.test.tsx
@@ -24,7 +24,7 @@ import {
} from "@/core/packages/sandbox-state";
import { filenameAtom } from "@/core/saving/file-state";
import { store } from "@/core/state/jotai";
-import { WebSocketClosedReason, ConnectionState } from "@/core/websocket/types";
+import { WebSocketClosedReason, ConnectionState } from "@/core/session/types";
import { chromeAtom } from "../../state";
import PackagesPanel from "../packages-panel";
import { PanelSectionProvider } from "../panel-context";
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 76c75962ff..9fc6468082 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
@@ -14,17 +14,15 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { PAIR_CONFIG } from "@/__tests__/fixtures/pair-config";
import { TooltipProvider } from "@/components/ui/tooltip";
import { toast } from "@/components/ui/use-toast";
-import type { Attachment } from "@/core/attachments/state";
+import type { Attachment } from "@/core/notebook/attachments";
import { pairConfigAtom } from "@/core/config/pair";
-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 { notebookReplicaAtom } from "@/core/websocket/state";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { Deferred } from "@/utils/Deferred";
import { AttachmentStatus } from "../footer-items/attachment-status";
@@ -32,6 +30,10 @@ vi.mock("@/components/ui/use-toast", () => ({ toast: vi.fn() }));
vi.mock("@/core/network/api", () => ({ API: { post: vi.fn() } }));
const attachmentsAtom = atom<Attachment[]>([]);
+vi.mock("@/core/session/active-notebook", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@/core/session/active-notebook")>()),
+ activeNotebookReplicaAtom: atom(() => ({ attachmentsAtom })),
+}));
const AGENT: Attachment = {
id: "a1",
@@ -45,11 +47,6 @@ 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(notebookReplicaAtom, {
- ...createNotebookReplica(store),
- connectionAtom: atom({ state: ConnectionState.OPEN }),
- attachmentsAtom,
- });
store.set(attachmentsAtom, attachments);
store.set(stableSessionIdAtom, "stable/test" as StableSessionId);
return {
diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/attachment-status.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/attachment-status.tsx
index e44a17232d..c29ed9bbc5 100644
--- a/frontend/src/components/editor/chrome/wrapper/footer-items/attachment-status.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/attachment-status.tsx
@@ -17,10 +17,10 @@ import {
} from "@/components/ui/popover";
import {
type Attachment,
- agentAttachmentsAtom,
attachmentLabel,
-} from "@/core/attachments/state";
-import { agentToast } from "@/core/attachments/toast";
+ useNotebookAttachments,
+} from "@/core/notebook";
+import { agentToast } from "@/components/editor/agent-toast";
import { pairConfigAtom } from "@/core/config/pair";
import { stableSessionIdAtom } from "@/core/kernel/session";
import { API } from "@/core/network/api";
@@ -29,7 +29,7 @@ import { FooterItem } from "../footer-item";
export function AttachmentStatus() {
const hostEnabled = useAtomValue(pairConfigAtom)?.hostEnabled;
- const agents = useAtomValue(agentAttachmentsAtom);
+ const agents = useNotebookAttachments("agent");
const [open, setOpen] = useState(false);
const previous = useRef(new Set<string>());
const automatic = useRef(false);
diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx
index ff0b17fafa..dbaf073eda 100644
--- a/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/backend-status.tsx
@@ -14,7 +14,7 @@ import {
isAppConnected,
isAppConnecting,
isAppNotStarted,
-} from "@/core/websocket/connection-utils";
+} from "@/core/session/connection-utils";
import { useAsyncData } from "@/hooks/useAsyncData";
import { useInterval } from "@/hooks/useInterval";
import { Strings } from "@/utils/strings";
diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/lsp-status.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/lsp-status.tsx
index 521a7d743a..f6f6a82189 100644
--- a/frontend/src/components/editor/chrome/wrapper/footer-items/lsp-status.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/lsp-status.tsx
@@ -14,7 +14,7 @@ import type {
LspRestartResponse,
} from "@/core/network/types";
import { isWasm } from "@/core/wasm/utils";
-import { isAppConnected } from "@/core/websocket/connection-utils";
+import { isAppConnected } from "@/core/session/connection-utils";
import { useAsyncData } from "@/hooks/useAsyncData";
import { useInterval } from "@/hooks/useInterval";
diff --git a/frontend/src/components/editor/chrome/wrapper/footer-items/machine-stats.tsx b/frontend/src/components/editor/chrome/wrapper/footer-items/machine-stats.tsx
index 8aba5c50ca..6574aa0bc0 100644
--- a/frontend/src/components/editor/chrome/wrapper/footer-items/machine-stats.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/footer-items/machine-stats.tsx
@@ -10,7 +10,7 @@ import { connectionAtom } from "@/core/network/connection";
import { useRequestClient } from "@/core/network/requests";
import type { UsageResponse } from "@/core/network/types";
import { isWasm } from "@/core/wasm/utils";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { useAsyncData } from "@/hooks/useAsyncData";
import { useInterval } from "@/hooks/useInterval";
import { cn } from "@/utils/cn";
diff --git a/frontend/src/components/editor/controls/Controls.tsx b/frontend/src/components/editor/controls/Controls.tsx
index 68ae0f97f5..dc0441d374 100644
--- a/frontend/src/components/editor/controls/Controls.tsx
+++ b/frontend/src/components/editor/controls/Controls.tsx
@@ -20,8 +20,8 @@ import { SaveComponent } from "@/core/saving/save-component";
import {
getConnectionTooltip,
isAppInteractionDisabled,
-} from "@/core/websocket/connection-utils";
-import { ConnectionState } from "@/core/websocket/types";
+} from "@/core/session/connection-utils";
+import { ConnectionState } from "@/core/session/types";
import { cn } from "@/utils/cn";
import { Functions } from "@/utils/functions";
import {
diff --git a/frontend/src/components/editor/controls/__tests__/notebook-menu-dropdown.test.tsx b/frontend/src/components/editor/controls/__tests__/notebook-menu-dropdown.test.tsx
index 2246f087ac..b9d3f11630 100644
--- a/frontend/src/components/editor/controls/__tests__/notebook-menu-dropdown.test.tsx
+++ b/frontend/src/components/editor/controls/__tests__/notebook-menu-dropdown.test.tsx
@@ -26,7 +26,7 @@ import { requestClientAtom } from "@/core/network/requests";
import { filenameAtom } from "@/core/saving/file-state";
import { store } from "@/core/state/jotai";
import { isWasm } from "@/core/wasm/utils";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import {
DEFAULT_EXPORT_OPTIONS,
exportOptionsAtom,
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 94dbdaa5c0..a7fc2e1876 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
@@ -16,7 +16,7 @@ import { cellId } from "@/__tests__/branded";
import { PAIR_CONFIG } from "@/__tests__/fixtures/pair-config";
import { TooltipProvider } from "@/components/ui/tooltip";
import { toast } from "@/components/ui/use-toast";
-import type { Attachment } from "@/core/attachments/state";
+import type { Attachment } from "@/core/notebook/attachments";
import { exportedForTesting, notebookAtom } from "@/core/cells/cells";
import {
type CellOutputMessage,
@@ -25,7 +25,6 @@ import {
} from "@/core/cells/error-report";
import { pairConfigAtom } from "@/core/config/pair";
import { notebookStateFromSession } from "@/core/cells/session";
-import { createNotebookReplica } from "@/core/host/replica";
import type { MarimoError, OutputMessage } from "@/core/kernel/messages";
import {
type StableSessionId,
@@ -33,8 +32,7 @@ import {
} from "@/core/kernel/session";
import { API } from "@/core/network/api";
import { connectionAtom } from "@/core/network/connection";
-import { notebookReplicaAtom } from "@/core/websocket/state";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { Deferred } from "@/utils/Deferred";
import { HTTPError } from "@/utils/errors";
import { MarimoErrorOutput } from "../../output/MarimoErrorOutput";
@@ -51,6 +49,10 @@ vi.mock("@/components/editor/chrome/wrapper/useOpenAiAssistant", () => ({
const CELL_ID = cellId("test-cell");
const STABLE_ID = "stable/test" as StableSessionId;
const attachmentsAtom = atom<Attachment[]>([]);
+vi.mock("@/core/session/active-notebook", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@/core/session/active-notebook")>()),
+ activeNotebookReplicaAtom: atom(() => ({ attachmentsAtom })),
+}));
const AGENT: Attachment = {
id: "a1",
@@ -97,11 +99,6 @@ function renderButton({
const store = createStore();
store.set(connectionAtom, { state: ConnectionState.OPEN });
store.set(pairConfigAtom, { ...PAIR_CONFIG, hostEnabled: preview });
- store.set(notebookReplicaAtom, {
- ...createNotebookReplica(store),
- connectionAtom: atom({ state: ConnectionState.OPEN }),
- attachmentsAtom,
- });
store.set(attachmentsAtom, attachments);
store.set(stableSessionIdAtom, stableId);
const wrapper = ({ children }: { children: React.ReactNode }) => (
diff --git a/frontend/src/components/editor/errors/send-error-report-button.tsx b/frontend/src/components/editor/errors/send-error-report-button.tsx
index b8ad1afd19..bbbd2ab1f8 100644
--- a/frontend/src/components/editor/errors/send-error-report-button.tsx
+++ b/frontend/src/components/editor/errors/send-error-report-button.tsx
@@ -4,11 +4,8 @@ import { useAtomValue } from "jotai";
import { SendIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
-import {
- agentAttachmentsAtom,
- attachmentLabel,
-} from "@/core/attachments/state";
-import { agentToast } from "@/core/attachments/toast";
+import { attachmentLabel, useNotebookAttachments } from "@/core/notebook";
+import { agentToast } from "@/components/editor/agent-toast";
import { pairConfigAtom } from "@/core/config/pair";
import { stableSessionIdAtom } from "@/core/kernel/session";
import { API } from "@/core/network/api";
@@ -20,7 +17,7 @@ export function SendErrorReportButton({
getContent: () => unknown;
}) {
const hostEnabled = useAtomValue(pairConfigAtom)?.hostEnabled;
- const agents = useAtomValue(agentAttachmentsAtom);
+ const agents = useNotebookAttachments("agent");
const stableSessionId = useAtomValue(stableSessionIdAtom);
const [sending, setSending] = useState(false);
diff --git a/frontend/src/components/editor/header/__tests__/status.test.tsx b/frontend/src/components/editor/header/__tests__/status.test.tsx
index 09768c7209..d564390d8a 100644
--- a/frontend/src/components/editor/header/__tests__/status.test.tsx
+++ b/frontend/src/components/editor/header/__tests__/status.test.tsx
@@ -11,7 +11,7 @@ import {
type ConnectionStatus,
WebSocketClosedReason,
ConnectionState,
-} from "@/core/websocket/types";
+} from "@/core/session/types";
import { StatusOverlay } from "../status";
function renderOverlay(
@@ -55,7 +55,7 @@ describe("StatusOverlay disconnect indicator", () => {
expect(onReconnect).toHaveBeenCalledTimes(1);
});
- it("renders a disabled button when no onReconnect is provided", () => {
+ it("keeps the unavailable reconnect button focusable for its tooltip", () => {
const { getByTestId } = renderOverlay({
state: ConnectionState.CLOSED,
code: WebSocketClosedReason.KERNEL_DISCONNECTED,
@@ -63,7 +63,9 @@ describe("StatusOverlay disconnect indicator", () => {
});
const button = getByTestId("disconnected-indicator");
- expect((button as HTMLButtonElement).disabled).toBe(true);
+ expect(button).toHaveAttribute("aria-disabled", "true");
+ button.focus();
+ expect(button).toHaveFocus();
});
it("leaves editor startup failures to the inline notice", () => {
diff --git a/frontend/src/components/editor/header/app-header.tsx b/frontend/src/components/editor/header/app-header.tsx
index 033dc8d574..1134866907 100644
--- a/frontend/src/components/editor/header/app-header.tsx
+++ b/frontend/src/components/editor/header/app-header.tsx
@@ -1,7 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import React, { type PropsWithChildren } from "react";
-import { type ConnectionStatus, ConnectionState } from "@/core/websocket/types";
+import { type ConnectionStatus, ConnectionState } from "@/core/session/types";
import { Disconnected } from "../Disconnected";
interface Props {
diff --git a/frontend/src/components/editor/header/status.tsx b/frontend/src/components/editor/header/status.tsx
index 74925a8389..75ebc0c710 100644
--- a/frontend/src/components/editor/header/status.tsx
+++ b/frontend/src/components/editor/header/status.tsx
@@ -11,7 +11,7 @@ import {
type ConnectionStatus,
WebSocketClosedReason,
ConnectionState,
-} from "@/core/websocket/types";
+} from "@/core/session/types";
import { cn } from "@/utils/cn";
export const StatusOverlay: React.FC<{
@@ -61,20 +61,17 @@ const DisconnectedIcon: React.FC<{ onReconnect?: () => void }> = ({
disabled ? "App disconnected" : "App disconnected — click to reconnect"
}
>
- {/* Wrapper span keeps the tooltip reachable when the button is
- disabled — a disabled <button> swallows pointer events. */}
- <span tabIndex={disabled ? 0 : -1}>
- <button
- type="button"
- className={cn(topLeftStatus, "bg-transparent border-0 p-0")}
- aria-label={disabled ? "App disconnected" : "Reconnect to app"}
- data-testid="disconnected-indicator"
- onClick={onReconnect}
- disabled={disabled}
- >
- <UnlinkIcon className="w-[25px] h-[25px] text-(--red-11)" />
- </button>
- </span>
+ <button
+ type="button"
+ className={cn(topLeftStatus, "bg-transparent border-0 p-0")}
+ aria-label={disabled ? "App disconnected" : "Reconnect to app"}
+ data-testid="disconnected-indicator"
+ onClick={onReconnect}
+ // Keep the tooltip reachable by keyboard when reconnection is unavailable.
+ aria-disabled={disabled}
+ >
+ <UnlinkIcon className="w-[25px] h-[25px] text-(--red-11)" />
+ </button>
</Tooltip>
);
};
diff --git a/frontend/src/components/editor/notebook-cell.tsx b/frontend/src/components/editor/notebook-cell.tsx
index c215aac2b3..88652bbac4 100644
--- a/frontend/src/components/editor/notebook-cell.tsx
+++ b/frontend/src/components/editor/notebook-cell.tsx
@@ -59,7 +59,7 @@ import {
shouldHidePublishedCell,
} from "../../core/cells/utils";
import type { UserConfig } from "../../core/config/config-schema";
-import { isAppInteractionDisabled } from "../../core/websocket/connection-utils";
+import { isAppInteractionDisabled } from "../../core/session/connection-utils";
import { useCellRenderCount } from "../../hooks/useCellRenderCount";
import type { Theme } from "../../theme/useTheme";
import { Functions } from "../../utils/functions";
diff --git a/frontend/src/core/attachments/state.ts b/frontend/src/core/attachments/state.ts
deleted file mode 100644
index c46d2777f2..0000000000
--- a/frontend/src/core/attachments/state.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-
-import { atom } from "jotai";
-import type { Attachment } from "@marimo-team/client/protocol";
-import { notebookReplicaAtom } from "@/core/websocket/state";
-
-export type { Attachment } from "@marimo-team/client/protocol";
-
-export const agentAttachmentsAtom = atom((get) => {
- const notebook = get(notebookReplicaAtom);
- return (notebook ? get(notebook.attachmentsAtom) : []).filter(
- (attachment) => attachment.kind === "agent",
- );
-});
-
-export function attachmentLabel(attachment: Attachment): string {
- return attachment.name || "Agent";
-}
diff --git a/frontend/src/core/codemirror/readonly/__tests__/extension.test.ts b/frontend/src/core/codemirror/readonly/__tests__/extension.test.ts
index 8920eb7c54..681f081d9c 100644
--- a/frontend/src/core/codemirror/readonly/__tests__/extension.test.ts
+++ b/frontend/src/core/codemirror/readonly/__tests__/extension.test.ts
@@ -4,7 +4,7 @@ import { EditorState } from "@codemirror/state";
import { EditorView } from "@codemirror/view";
import { createStore } from "jotai";
import { describe, expect, it } from "vitest";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { connectionAtom } from "../../../network/connection";
import { dynamicReadonly, isEditorReadonly } from "../extension";
diff --git a/frontend/src/core/codemirror/readonly/extension.ts b/frontend/src/core/codemirror/readonly/extension.ts
index ef186e500c..7b7da2921b 100644
--- a/frontend/src/core/codemirror/readonly/extension.ts
+++ b/frontend/src/core/codemirror/readonly/extension.ts
@@ -5,9 +5,9 @@ import type { createStore } from "jotai";
import {
isAppConnected,
isAppConnecting,
-} from "@/core/websocket/connection-utils";
+} from "@/core/session/connection-utils";
import { connectionAtom } from "../../network/connection";
-import { ConnectionState } from "../../websocket/types";
+import { ConnectionState } from "../../session/types";
/**
* State effect for updating readonly status based on connection
diff --git a/frontend/src/core/datasets/__tests__/data-source-discovery.test.ts b/frontend/src/core/datasets/__tests__/data-source-discovery.test.ts
index fa9c0268e7..1c810cfd6c 100644
--- a/frontend/src/core/datasets/__tests__/data-source-discovery.test.ts
+++ b/frontend/src/core/datasets/__tests__/data-source-discovery.test.ts
@@ -4,7 +4,7 @@ import { requestId } from "@/__tests__/branded";
import type { DataSourceDiscoveryResult } from "@/core/kernel/messages";
import { connectionAtom } from "@/core/network/connection";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import {
fetchDataSourceDiscovery,
invalidateDataSourceDiscovery,
diff --git a/frontend/src/core/edit-app.tsx b/frontend/src/core/edit-app.tsx
index 846b355ea1..3d369e0e27 100644
--- a/frontend/src/core/edit-app.tsx
+++ b/frontend/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 { useNotebookSession } from "./websocket/useNotebookSession";
+import { useNotebookSession } from "./session/useNotebookSession";
interface AppProps {
/**
@@ -81,7 +81,7 @@ export const EditApp: React.FC<AppProps> = ({
return () => {
RuntimeState.INSTANCE.stop();
};
- }, []);
+ }, [sendComponentValues]);
const { connection, reconnect } = useNotebookSession({
autoInstantiate: userConfig.runtime.auto_instantiate,
diff --git a/frontend/src/core/export/hooks.ts b/frontend/src/core/export/hooks.ts
index 3606dddc6b..7528f8fc39 100644
--- a/frontend/src/core/export/hooks.ts
+++ b/frontend/src/core/export/hooks.ts
@@ -16,7 +16,7 @@ import { connectionAtom } from "../network/connection";
import { useRequestClient } from "../network/requests";
import type { UpdateCellOutputsRequest } from "../network/types";
import { VirtualFileTracker } from "../static/virtual-file-tracker";
-import { ConnectionState } from "../websocket/types";
+import { ConnectionState } from "../session/types";
const DELAY = 5000; // 5 seconds;
diff --git a/frontend/src/core/host/AGENTS.md b/frontend/src/core/host/AGENTS.md
deleted file mode 100644
index 5572f06be2..0000000000
--- a/frontend/src/core/host/AGENTS.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# Host core
-
-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.
diff --git a/frontend/src/core/network/__tests__/connection.test.ts b/frontend/src/core/network/__tests__/connection.test.ts
index 7d532b9693..ed4b880f08 100644
--- a/frontend/src/core/network/__tests__/connection.test.ts
+++ b/frontend/src/core/network/__tests__/connection.test.ts
@@ -3,7 +3,7 @@
import { afterEach, describe, expect, it } from "vitest";
import { initialModeAtom } from "@/core/mode";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "../../websocket/types";
+import { ConnectionState } from "../../session/types";
import { connectionAtom, waitForConnectionOpenIfNotebook } from "../connection";
const NEVER = Symbol("never");
diff --git a/frontend/src/core/network/connection-notice.ts b/frontend/src/core/network/connection-notice.ts
index dc96120010..df6f5c825c 100644
--- a/frontend/src/core/network/connection-notice.ts
+++ b/frontend/src/core/network/connection-notice.ts
@@ -6,7 +6,7 @@ import {
type ConnectionPhase,
WebSocketClosedReason,
ConnectionState,
-} from "@/core/websocket/types";
+} from "@/core/session/types";
import { connectionAtom } from "./connection";
export interface ConnectionNotice {
diff --git a/frontend/src/core/network/connection.ts b/frontend/src/core/network/connection.ts
index ed96a27f23..baaad0ce69 100644
--- a/frontend/src/core/network/connection.ts
+++ b/frontend/src/core/network/connection.ts
@@ -4,7 +4,7 @@ import { atomWithReducer } from "jotai/utils";
import type { NotificationMessageData } from "../kernel/messages";
import { isNotebookPage } from "../mode";
import { waitFor } from "../state/jotai";
-import { type ConnectionStatus, ConnectionState } from "../websocket/types";
+import { type ConnectionStatus, ConnectionState } from "../session/types";
/**
* Shared application state, not the actual event-stream status.
diff --git a/frontend/src/core/network/requests-lazy.ts b/frontend/src/core/network/requests-lazy.ts
index dbbac0619e..4cf30925a9 100644
--- a/frontend/src/core/network/requests-lazy.ts
+++ b/frontend/src/core/network/requests-lazy.ts
@@ -7,7 +7,7 @@ import { memoizeLastValue } from "@/utils/once";
import { waitForKernelToBeInstantiated } from "../kernel/state";
import type { RuntimeManager } from "../runtime/runtime";
import { store } from "../state/jotai";
-import { ConnectionState } from "../websocket/types";
+import { ConnectionState } from "../session/types";
import { connectionAtom, waitForConnectionOpen } from "./connection";
import type { EditRequests, RunRequests } from "./types";
diff --git a/frontend/src/core/notebook/attachments.ts b/frontend/src/core/notebook/attachments.ts
new file mode 100644
index 0000000000..d91b92bc89
--- /dev/null
+++ b/frontend/src/core/notebook/attachments.ts
@@ -0,0 +1,38 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { dequal } from "dequal";
+import { atom, useAtomValue } from "jotai";
+import { selectAtom } from "jotai/vanilla/utils";
+import { useMemo } from "react";
+import type { Attachment } from "@marimo-team/client/protocol";
+import { activeNotebookReplicaAtom } from "../session/active-notebook";
+
+export type { Attachment } from "@marimo-team/client/protocol";
+
+const EMPTY_ATTACHMENTS: readonly Attachment[] = [];
+
+/** Attachments visible to this session, empty while no notebook is available. */
+export const notebookAttachmentsAtom = atom((get) => {
+ const replica = get(activeNotebookReplicaAtom);
+ return replica ? get(replica.attachmentsAtom) : EMPTY_ATTACHMENTS;
+});
+
+/** Current notebook attachments, optionally restricted to one kind. */
+export function useNotebookAttachments(kind?: Attachment["kind"]) {
+ const attachments = useMemo(
+ () =>
+ kind === undefined
+ ? notebookAttachmentsAtom
+ : selectAtom(
+ notebookAttachmentsAtom,
+ (value) => value.filter((attachment) => attachment.kind === kind),
+ dequal,
+ ),
+ [kind],
+ );
+ return useAtomValue(attachments);
+}
+
+export function attachmentLabel(attachment: Attachment): string {
+ return attachment.name || "Agent";
+}
diff --git a/frontend/src/core/document/__tests__/codemirror.test.ts b/frontend/src/core/notebook/document/__tests__/codemirror.test.ts
similarity index 96%
rename from frontend/src/core/document/__tests__/codemirror.test.ts
rename to frontend/src/core/notebook/document/__tests__/codemirror.test.ts
index 8fa9cc6453..560103be5b 100644
--- a/frontend/src/core/document/__tests__/codemirror.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/codemirror.test.ts
@@ -9,22 +9,22 @@ import { afterEach, describe, expect, it, vi } from "vitest";
import { cellId as brandedCellId } from "@/__tests__/branded";
import { createNotebookActions } from "@/core/cells/cells";
import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
-import { cellActionsState } from "../../codemirror/cells/state";
-import { cellConfigExtension } from "../../codemirror/config/extension";
+import { cellActionsState } from "../../../codemirror/cells/state";
+import { cellConfigExtension } from "../../../codemirror/config/extension";
import {
adaptiveLanguageConfiguration,
languageAdapterState,
switchLanguage,
-} from "../../codemirror/language/extension";
+} from "../../../codemirror/language/extension";
import {
languageMetadataField,
setLanguageMetadata,
-} from "../../codemirror/language/metadata";
-import { SCHEMA_CACHE } from "../../codemirror/language/languages/sql/completion-store";
-import type { Document } from "../../host/resources/document";
+} from "../../../codemirror/language/metadata";
+import { SCHEMA_CACHE } from "../../../codemirror/language/languages/sql/completion-store";
+import type { Document } from "../../replica/resources/document";
import { cellCodeBinding } from "../codemirror";
import { createDocumentModel } from "../model";
-import { fakeBackend } from "../../host/__tests__/fixtures";
+import { fakeBackend } from "../../replica/__tests__/fixtures";
import { cell, document, withCells } from "./fixtures";
const views: EditorView[] = [];
diff --git a/frontend/src/core/document/__tests__/draft.test.ts b/frontend/src/core/notebook/document/__tests__/draft.test.ts
similarity index 100%
rename from frontend/src/core/document/__tests__/draft.test.ts
rename to frontend/src/core/notebook/document/__tests__/draft.test.ts
diff --git a/frontend/src/core/document/__tests__/fixtures.ts b/frontend/src/core/notebook/document/__tests__/fixtures.ts
similarity index 97%
rename from frontend/src/core/document/__tests__/fixtures.ts
rename to frontend/src/core/notebook/document/__tests__/fixtures.ts
index 252b1ac5f5..5ae3b71af8 100644
--- a/frontend/src/core/document/__tests__/fixtures.ts
+++ b/frontend/src/core/notebook/document/__tests__/fixtures.ts
@@ -1,6 +1,6 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import type { Document } from "../../host/resources/document";
+import type { Document } from "../../replica/resources/document";
import type * as Protocol from "@marimo-team/client/protocol";
export const CONFIG: Protocol.CellConfig = {
diff --git a/frontend/src/core/document/__tests__/hooks.test.tsx b/frontend/src/core/notebook/document/__tests__/hooks.test.tsx
similarity index 86%
rename from frontend/src/core/document/__tests__/hooks.test.tsx
rename to frontend/src/core/notebook/document/__tests__/hooks.test.tsx
index 339fa8cbfe..00c2037119 100644
--- a/frontend/src/core/document/__tests__/hooks.test.tsx
+++ b/frontend/src/core/notebook/document/__tests__/hooks.test.tsx
@@ -5,19 +5,18 @@ import { atom, createStore, Provider } from "jotai";
import type { PropsWithChildren } from "react";
import { afterEach, describe, expect, it, vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
-import type { Document } from "../../host/resources/document";
+import type { Document } from "../../replica/resources/document";
import {
- createDocumentModel,
- DocumentProvider,
- useCellCode,
- useCellConfig,
- useCellName,
- useCellOrder,
- useDocumentEdit,
- useDocumentSync,
-} from "..";
+ useNotebookCellCode,
+ useNotebookCellConfig,
+ useNotebookCellName,
+ useNotebookCellOrder,
+ useNotebookDocumentEdit,
+ useNotebookDocumentSync,
+} from "@/core/notebook";
+import { createDocumentModel, DocumentProvider } from "..";
import { cell, CONFIG, document, withCells } from "./fixtures";
-import { type FakeEdit, fakeBackend } from "../../host/__tests__/fixtures";
+import { type FakeEdit, fakeBackend } from "../../replica/__tests__/fixtures";
const lifetimes: AbortController[] = [];
@@ -65,9 +64,9 @@ describe("document hooks", () => {
const { store, source, wrapper, controller } = setup(document(), edit);
const { result, unmount } = renderHook(
() => ({
- code: useCellCode("c1"),
- edit: useDocumentEdit(),
- sync: useDocumentSync(),
+ code: useNotebookCellCode("c1"),
+ edit: useNotebookDocumentEdit(),
+ sync: useNotebookDocumentSync(),
}),
{ wrapper, reactStrictMode: true },
);
@@ -108,13 +107,13 @@ describe("document hooks", () => {
const { result } = renderHook(
() => {
const value = {
- code: useCellCode("c1"),
- name: useCellName("c1"),
- config: useCellConfig("c1"),
- order: useCellOrder(),
+ code: useNotebookCellCode("c1"),
+ name: useNotebookCellName("c1"),
+ config: useNotebookCellConfig("c1"),
+ order: useNotebookCellOrder(),
};
seen(value);
- return { ...value, edit: useDocumentEdit() };
+ return { ...value, edit: useNotebookDocumentEdit() };
},
{ wrapper },
);
@@ -162,23 +161,23 @@ describe("document hooks", () => {
const onOrder = vi.fn();
const onEdit = vi.fn();
function Code() {
- onCode(useCellCode("c1"));
+ onCode(useNotebookCellCode("c1"));
return null;
}
function Name() {
- onName(useCellName("c1"));
+ onName(useNotebookCellName("c1"));
return null;
}
function Config() {
- onConfig(useCellConfig("c1"));
+ onConfig(useNotebookCellConfig("c1"));
return null;
}
function Order() {
- onOrder(useCellOrder());
+ onOrder(useNotebookCellOrder());
return null;
}
function Edit() {
- onEdit(useDocumentEdit());
+ onEdit(useNotebookDocumentEdit());
return null;
}
render(
@@ -191,7 +190,8 @@ describe("document hooks", () => {
</>,
{ wrapper },
);
- const edit: ReturnType<typeof useDocumentEdit> = onEdit.mock.calls[0][0];
+ const edit: ReturnType<typeof useNotebookDocumentEdit> =
+ onEdit.mock.calls[0][0];
const clear = () =>
[onCode, onName, onConfig, onOrder, onEdit].forEach((fn) =>
fn.mockClear(),
@@ -246,8 +246,8 @@ describe("document hooks", () => {
const { wrapper } = setup();
const { result, rerender } = renderHook(
(id) => ({
- code: useCellCode(id),
- edit: useDocumentEdit(),
+ code: useNotebookCellCode(id),
+ edit: useNotebookDocumentEdit(),
}),
{ wrapper, initialProps: "c1" },
);
@@ -264,11 +264,11 @@ describe("document hooks", () => {
const { store, source, wrapper } = setup(null);
const { result } = renderHook(
() => ({
- order: useCellOrder(),
- code: useCellCode("c1"),
- name: useCellName("c1"),
- config: useCellConfig("c1"),
- edit: useDocumentEdit(),
+ order: useNotebookCellOrder(),
+ code: useNotebookCellCode("c1"),
+ name: useNotebookCellName("c1"),
+ config: useNotebookCellConfig("c1"),
+ edit: useNotebookDocumentEdit(),
}),
{ wrapper },
);
@@ -309,8 +309,8 @@ describe("document hooks", () => {
it("preserves drafts across Strict Mode remounts until the session ends", () => {
const { wrapper, controller, detached } = setup();
const useProbe = () => ({
- code: useCellCode("c1"),
- edit: useDocumentEdit(),
+ code: useNotebookCellCode("c1"),
+ edit: useNotebookDocumentEdit(),
});
const first = renderHook(useProbe, { wrapper, reactStrictMode: true });
const edit = first.result.current.edit;
@@ -340,7 +340,10 @@ describe("document hooks", () => {
);
const seen = vi.fn();
function Probe() {
- seen({ code: useCellCode("c1"), edit: useDocumentEdit() });
+ seen({
+ code: useNotebookCellCode("c1"),
+ edit: useNotebookDocumentEdit(),
+ });
return null;
}
const tree = ({ store, model }: typeof first) => (
@@ -351,7 +354,7 @@ describe("document hooks", () => {
</Provider>
);
const { rerender } = render(tree(first));
- const oldEdit: ReturnType<typeof useDocumentEdit> =
+ const oldEdit: ReturnType<typeof useNotebookDocumentEdit> =
seen.mock.calls.at(-1)![0].edit;
act(() => oldEdit((tx) => tx.setCode("c1", "first draft")));
rerender(tree(second));
@@ -359,7 +362,7 @@ describe("document hooks", () => {
expect(first.detached).toHaveBeenCalledOnce();
const latest: {
code: string | null | undefined;
- edit: ReturnType<typeof useDocumentEdit>;
+ edit: ReturnType<typeof useNotebookDocumentEdit>;
} = seen.mock.calls.at(-1)![0];
expect(latest.code).toBe("second source");
expect(latest.edit).not.toBe(oldEdit);
@@ -381,6 +384,8 @@ describe("document hooks", () => {
});
it("requires a document provider", () => {
- expect(() => renderHook(useDocumentEdit)).toThrow("DocumentProvider");
+ expect(() => renderHook(useNotebookDocumentEdit)).toThrow(
+ "DocumentProvider",
+ );
});
});
diff --git a/frontend/src/core/document/__tests__/lifecycle-scenarios.test.ts b/frontend/src/core/notebook/document/__tests__/lifecycle-scenarios.test.ts
similarity index 100%
rename from frontend/src/core/document/__tests__/lifecycle-scenarios.test.ts
rename to frontend/src/core/notebook/document/__tests__/lifecycle-scenarios.test.ts
diff --git a/frontend/src/core/document/__tests__/model.test.ts b/frontend/src/core/notebook/document/__tests__/model.test.ts
similarity index 96%
rename from frontend/src/core/document/__tests__/model.test.ts
rename to frontend/src/core/notebook/document/__tests__/model.test.ts
index 54a68fe918..48eccf97a7 100644
--- a/frontend/src/core/document/__tests__/model.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/model.test.ts
@@ -5,10 +5,10 @@ import type * as Protocol from "@marimo-team/client/protocol";
import { atom, createStore } from "jotai/vanilla";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
-import type { NotebookBackend } from "../../host/backend";
-import type { Document } from "../../host/resources/document";
+import type { NotebookBackend } from "../../replica/backend";
+import type { Document } from "../../replica/resources/document";
import { createDocumentModel } from "../model";
-import { type FakeEdit, fakeBackend } from "../../host/__tests__/fixtures";
+import { type FakeEdit, fakeBackend } from "../../replica/__tests__/fixtures";
import { cell, document, withCells } from "./fixtures";
function response(confirmed: Document): Result<Protocol.EditResponseOutput> {
diff --git a/frontend/src/core/document/__tests__/protocol-fixtures.ts b/frontend/src/core/notebook/document/__tests__/protocol-fixtures.ts
similarity index 83%
rename from frontend/src/core/document/__tests__/protocol-fixtures.ts
rename to frontend/src/core/notebook/document/__tests__/protocol-fixtures.ts
index 22fbc0b800..3cf62e9f34 100644
--- a/frontend/src/core/document/__tests__/protocol-fixtures.ts
+++ b/frontend/src/core/notebook/document/__tests__/protocol-fixtures.ts
@@ -4,14 +4,14 @@ import { readFileSync } from "node:fs";
import NodeUrl from "node:url";
import type * as Protocol from "@marimo-team/client/protocol";
import { invariant } from "@/utils/invariant";
-import { fixtureEvents } from "../../host/__tests__/fixtures";
-import type { Document } from "../../host/resources/document";
+import { fixtureEvents } from "../../replica/__tests__/fixtures";
+import type { Document } from "../../replica/resources/document";
export function protocolFixture(name: string): unknown {
return JSON.parse(
readFileSync(
new NodeUrl.URL(
- `../../../../../protocols/host/fixtures/${name}`,
+ `../../../../../../protocols/host/fixtures/${name}`,
import.meta.url,
),
"utf8",
diff --git a/frontend/src/core/document/__tests__/recovery-scenarios.test.ts b/frontend/src/core/notebook/document/__tests__/recovery-scenarios.test.ts
similarity index 100%
rename from frontend/src/core/document/__tests__/recovery-scenarios.test.ts
rename to frontend/src/core/notebook/document/__tests__/recovery-scenarios.test.ts
diff --git a/frontend/src/core/document/__tests__/scenario-fixture.ts b/frontend/src/core/notebook/document/__tests__/scenario-fixture.ts
similarity index 94%
rename from frontend/src/core/document/__tests__/scenario-fixture.ts
rename to frontend/src/core/notebook/document/__tests__/scenario-fixture.ts
index ac4d6602ac..14e4f323c1 100644
--- a/frontend/src/core/document/__tests__/scenario-fixture.ts
+++ b/frontend/src/core/notebook/document/__tests__/scenario-fixture.ts
@@ -2,7 +2,7 @@
import { createStore } from "jotai/vanilla";
import { test as baseTest, vi } from "vitest";
-import type { Document } from "../../host/resources/document";
+import type { Document } from "../../replica/resources/document";
import { createDocumentModel } from "../model";
import { initialDocument } from "./protocol-fixtures";
import { createTestNotebook } from "./test-notebook";
diff --git a/frontend/src/core/document/__tests__/scenarios.test.ts b/frontend/src/core/notebook/document/__tests__/scenarios.test.ts
similarity index 100%
rename from frontend/src/core/document/__tests__/scenarios.test.ts
rename to frontend/src/core/notebook/document/__tests__/scenarios.test.ts
diff --git a/frontend/src/core/document/__tests__/state.test.ts b/frontend/src/core/notebook/document/__tests__/state.test.ts
similarity index 99%
rename from frontend/src/core/document/__tests__/state.test.ts
rename to frontend/src/core/notebook/document/__tests__/state.test.ts
index d79e2de7da..5a7366668d 100644
--- a/frontend/src/core/document/__tests__/state.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/state.test.ts
@@ -2,7 +2,7 @@
import { atom, createStore } from "jotai/vanilla";
import { afterEach, describe, expect, it, vi } from "vitest";
-import type { Document } from "../../host/resources/document";
+import type { Document } from "../../replica/resources/document";
import {
createDocumentState,
type DocumentEdit,
diff --git a/frontend/src/core/document/__tests__/submission.test.ts b/frontend/src/core/notebook/document/__tests__/submission.test.ts
similarity index 99%
rename from frontend/src/core/document/__tests__/submission.test.ts
rename to frontend/src/core/notebook/document/__tests__/submission.test.ts
index 0a6423935e..44fdb101aa 100644
--- a/frontend/src/core/document/__tests__/submission.test.ts
+++ b/frontend/src/core/notebook/document/__tests__/submission.test.ts
@@ -2,7 +2,7 @@
import { atom, createStore } from "jotai/vanilla";
import { afterEach, describe, expect, it, vi } from "vitest";
-import type { Document } from "../../host/resources/document";
+import type { Document } from "../../replica/resources/document";
import { selectCell } from "../select";
import { createDocumentState, type DocumentSubmission } from "../state";
import { cell, document, withCells } from "./fixtures";
diff --git a/frontend/src/core/document/__tests__/test-host.test.ts b/frontend/src/core/notebook/document/__tests__/test-host.test.ts
similarity index 100%
rename from frontend/src/core/document/__tests__/test-host.test.ts
rename to frontend/src/core/notebook/document/__tests__/test-host.test.ts
diff --git a/frontend/src/core/document/__tests__/test-host.ts b/frontend/src/core/notebook/document/__tests__/test-host.ts
similarity index 99%
rename from frontend/src/core/document/__tests__/test-host.ts
rename to frontend/src/core/notebook/document/__tests__/test-host.ts
index ca49e24100..732a9f0d48 100644
--- a/frontend/src/core/document/__tests__/test-host.ts
+++ b/frontend/src/core/notebook/document/__tests__/test-host.ts
@@ -3,7 +3,7 @@
import { createHash } from "node:crypto";
import type { Result } from "@marimo-team/client";
import * as Protocol from "@marimo-team/client/protocol";
-import type { Document } from "../../host/resources/document";
+import type { Document } from "../../replica/resources/document";
export interface EditRequest {
readonly notebookId: Protocol.NotebookId;
diff --git a/frontend/src/core/document/__tests__/test-notebook.ts b/frontend/src/core/notebook/document/__tests__/test-notebook.ts
similarity index 96%
rename from frontend/src/core/document/__tests__/test-notebook.ts
rename to frontend/src/core/notebook/document/__tests__/test-notebook.ts
index c9829ef65f..08fd9248b6 100644
--- a/frontend/src/core/document/__tests__/test-notebook.ts
+++ b/frontend/src/core/notebook/document/__tests__/test-notebook.ts
@@ -6,8 +6,8 @@ import { atom, type createStore } from "jotai/vanilla";
import { vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
import { invariant } from "@/utils/invariant";
-import { type FakeEdit, fakeBackend } from "../../host/__tests__/fixtures";
-import type { Document } from "../../host/resources/document";
+import { type FakeEdit, fakeBackend } from "../../replica/__tests__/fixtures";
+import type { Document } from "../../replica/resources/document";
import { createTestHost, type EditRequest } from "./test-host";
export interface PendingRequest extends EditRequest {
diff --git a/frontend/src/core/document/__tests__/user.ts b/frontend/src/core/notebook/document/__tests__/user.ts
similarity index 100%
rename from frontend/src/core/document/__tests__/user.ts
rename to frontend/src/core/notebook/document/__tests__/user.ts
diff --git a/frontend/src/core/document/codemirror.ts b/frontend/src/core/notebook/document/codemirror.ts
similarity index 98%
rename from frontend/src/core/document/codemirror.ts
rename to frontend/src/core/notebook/document/codemirror.ts
index f08f42f384..dc7be954af 100644
--- a/frontend/src/core/document/codemirror.ts
+++ b/frontend/src/core/notebook/document/codemirror.ts
@@ -44,12 +44,12 @@ import {
languageAdapterFromCode,
languageAdapterState,
switchLanguage,
-} from "../codemirror/language/extension";
-import { initializeSQLDialect } from "../codemirror/language/languages/sql/sql";
+} from "../../codemirror/language/extension";
+import { initializeSQLDialect } from "../../codemirror/language/languages/sql/sql";
import {
languageMetadataField,
setLanguageMetadata,
-} from "../codemirror/language/metadata";
+} from "../../codemirror/language/metadata";
import type { DocumentModel } from "./model";
import { selectCellField } from "./select";
diff --git a/frontend/src/core/document/draft.ts b/frontend/src/core/notebook/document/draft.ts
similarity index 99%
rename from frontend/src/core/document/draft.ts
rename to frontend/src/core/notebook/document/draft.ts
index c0cadb73d5..dc1f2591fb 100644
--- a/frontend/src/core/document/draft.ts
+++ b/frontend/src/core/notebook/document/draft.ts
@@ -1,6 +1,6 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import type { Document } from "../host";
+import type { Document } from "../replica";
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/hooks.tsx b/frontend/src/core/notebook/document/hooks.tsx
similarity index 87%
rename from frontend/src/core/document/hooks.tsx
rename to frontend/src/core/notebook/document/hooks.tsx
index a8063f7d0d..f06b3cc8fa 100644
--- a/frontend/src/core/document/hooks.tsx
+++ b/frontend/src/core/notebook/document/hooks.tsx
@@ -46,7 +46,7 @@ function useDocumentModel() {
}
/** Null while the document is unavailable; an empty array for an empty document. */
-export function useCellOrder() {
+export function useNotebookCellOrder() {
const { documentAtom } = useDocumentModel();
return useAtomValue(useMemo(() => selectOrder(documentAtom), [documentAtom]));
}
@@ -62,17 +62,17 @@ function useCellField<K extends keyof EditableCell>(id: CellId, field: K) {
}
/** Undefined for an absent cell; null when the host withholds its source. */
-export function useCellCode(id: CellId) {
+export function useNotebookCellCode(id: CellId) {
return useCellField(id, "code");
}
/** Undefined when the cell or document is unavailable. */
-export function useCellName(id: CellId) {
+export function useNotebookCellName(id: CellId) {
return useCellField(id, "name");
}
/** Undefined when the cell or document is unavailable. */
-export function useCellConfig(id: CellId) {
+export function useNotebookCellConfig(id: CellId) {
return useCellField(id, "config");
}
@@ -81,10 +81,10 @@ export function useCellConfig(id: CellId) {
* Stable until the cell id or document model changes.
*
* ```tsx
- * const extension = useCellCodeExtension(cellId);
+ * const extension = useNotebookCellCodeExtension(cellId);
* ```
*/
-export function useCellCodeExtension(id: CellId) {
+export function useNotebookCellCodeExtension(id: CellId) {
const model = useDocumentModel();
const store = useStore();
return useMemo(
@@ -97,11 +97,11 @@ export function useCellCodeExtension(id: CellId) {
* A stable edit function. Synchronous callbacks publish atomically or roll back.
*
* ```ts
- * const edit = useDocumentEdit();
+ * const edit = useNotebookDocumentEdit();
* edit((tx) => tx.setCode(cellId, code));
* ```
*/
-export function useDocumentEdit() {
+export function useNotebookDocumentEdit() {
return useSetAtom(useDocumentModel().editAtom);
}
@@ -111,7 +111,7 @@ export function useDocumentEdit() {
* Rejections retain local edits; retry explicitly resubmits them. Requests
* with an unknown outcome reuse their original key within the retry window.
*/
-export function useDocumentSync() {
+export function useNotebookDocumentSync() {
const model = useDocumentModel();
const status = useAtomValue(model.syncStatusAtom);
return { status, flush: model.flush, retry: model.retry };
diff --git a/frontend/src/core/document/index.ts b/frontend/src/core/notebook/document/index.ts
similarity index 57%
rename from frontend/src/core/document/index.ts
rename to frontend/src/core/notebook/document/index.ts
index acf30e354c..48d9ec8a0f 100644
--- a/frontend/src/core/document/index.ts
+++ b/frontend/src/core/notebook/document/index.ts
@@ -4,12 +4,12 @@
export {
DocumentProvider,
- useCellCode,
- useCellCodeExtension,
- useCellConfig,
- useCellName,
- useCellOrder,
- useDocumentEdit,
- useDocumentSync,
+ useNotebookCellCode,
+ useNotebookCellCodeExtension,
+ useNotebookCellConfig,
+ useNotebookCellName,
+ useNotebookCellOrder,
+ useNotebookDocumentEdit,
+ useNotebookDocumentSync,
} from "./hooks";
export { createDocumentModel, type DocumentModel } from "./model";
diff --git a/frontend/src/core/document/model.ts b/frontend/src/core/notebook/document/model.ts
similarity index 96%
rename from frontend/src/core/document/model.ts
rename to frontend/src/core/notebook/document/model.ts
index 185d3acf17..6dabaa55be 100644
--- a/frontend/src/core/document/model.ts
+++ b/frontend/src/core/notebook/document/model.ts
@@ -2,7 +2,7 @@
import type * as Protocol from "@marimo-team/client/protocol";
import type { Atom, createStore } from "jotai/vanilla";
-import type { Document, NotebookBackend } from "../host";
+import type { Document, NotebookBackend } from "../replica";
import { createDocumentState, type DocumentState } from "./state";
import { createDocumentSync, type DocumentSyncStatus } from "./sync";
diff --git a/frontend/src/core/document/select.ts b/frontend/src/core/notebook/document/select.ts
similarity index 100%
rename from frontend/src/core/document/select.ts
rename to frontend/src/core/notebook/document/select.ts
diff --git a/frontend/src/core/document/state.ts b/frontend/src/core/notebook/document/state.ts
similarity index 99%
rename from frontend/src/core/document/state.ts
rename to frontend/src/core/notebook/document/state.ts
index 9a5c05cced..c51934552c 100644
--- a/frontend/src/core/document/state.ts
+++ b/frontend/src/core/notebook/document/state.ts
@@ -6,7 +6,7 @@ import {
type createStore,
type WritableAtom,
} from "jotai/vanilla";
-import type { Document } from "../host";
+import type { Document } from "../replica";
import * as Protocol from "@marimo-team/client/protocol";
import {
acknowledge,
diff --git a/frontend/src/core/document/sync.ts b/frontend/src/core/notebook/document/sync.ts
similarity index 99%
rename from frontend/src/core/document/sync.ts
rename to frontend/src/core/notebook/document/sync.ts
index b4265307ce..81b6fb9a78 100644
--- a/frontend/src/core/document/sync.ts
+++ b/frontend/src/core/notebook/document/sync.ts
@@ -3,7 +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 { Document, NotebookBackend } from "../host";
+import type { Document, NotebookBackend } from "../replica";
import type { DocumentState, DocumentSubmission } from "./state";
export type DocumentSyncStatus =
diff --git a/frontend/src/core/notebook/index.ts b/frontend/src/core/notebook/index.ts
new file mode 100644
index 0000000000..35f2d6ef04
--- /dev/null
+++ b/frontend/src/core/notebook/index.ts
@@ -0,0 +1,18 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/** React hooks for the current notebook. */
+
+export {
+ useNotebookAttachments,
+ attachmentLabel,
+ type Attachment,
+} from "./attachments";
+export {
+ useNotebookCellCode,
+ useNotebookCellCodeExtension,
+ useNotebookCellConfig,
+ useNotebookCellName,
+ useNotebookCellOrder,
+ useNotebookDocumentEdit,
+ useNotebookDocumentSync,
+} from "./document";
diff --git a/frontend/src/core/notebook/replica/AGENTS.md b/frontend/src/core/notebook/replica/AGENTS.md
new file mode 100644
index 0000000000..d4d791f6e6
--- /dev/null
+++ b/frontend/src/core/notebook/replica/AGENTS.md
@@ -0,0 +1,11 @@
+# Notebook replica
+
+Production code may import replica modules, `@marimo-team/client`,
+`jotai/vanilla`, `zod`, and `@/utils/Logger`. Enforced by
+`marimo/replica-imports`. Tests are exempt.
+
+Code outside this directory imports it as `@/core/notebook/replica`.
+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.
diff --git a/frontend/src/core/host/__tests__/attachments.test.ts b/frontend/src/core/notebook/replica/__tests__/attachments.test.ts
similarity index 100%
rename from frontend/src/core/host/__tests__/attachments.test.ts
rename to frontend/src/core/notebook/replica/__tests__/attachments.test.ts
diff --git a/frontend/src/core/host/__tests__/document.test.ts b/frontend/src/core/notebook/replica/__tests__/document.test.ts
similarity index 100%
rename from frontend/src/core/host/__tests__/document.test.ts
rename to frontend/src/core/notebook/replica/__tests__/document.test.ts
diff --git a/frontend/src/core/host/__tests__/fixtures.ts b/frontend/src/core/notebook/replica/__tests__/fixtures.ts
similarity index 97%
rename from frontend/src/core/host/__tests__/fixtures.ts
rename to frontend/src/core/notebook/replica/__tests__/fixtures.ts
index f8d8131530..0b289fdf7a 100644
--- a/frontend/src/core/host/__tests__/fixtures.ts
+++ b/frontend/src/core/notebook/replica/__tests__/fixtures.ts
@@ -45,7 +45,7 @@ export function fakeBackend({
/** Read the protocol's portable examples as transport messages. */
export function fixtureMessages(name: string) {
const path = new NodeUrl.URL(
- `../../../../../protocols/host/fixtures/${name}`,
+ `../../../../../../protocols/host/fixtures/${name}`,
import.meta.url,
);
return NodeFs.readFileSync(path, "utf8")
diff --git a/frontend/src/core/host/__tests__/replica.test.ts b/frontend/src/core/notebook/replica/__tests__/replica.test.ts
similarity index 99%
rename from frontend/src/core/host/__tests__/replica.test.ts
rename to frontend/src/core/notebook/replica/__tests__/replica.test.ts
index 2517613153..e8b23a53d7 100644
--- a/frontend/src/core/host/__tests__/replica.test.ts
+++ b/frontend/src/core/notebook/replica/__tests__/replica.test.ts
@@ -5,7 +5,7 @@ import { type NotebookTransport, StreamStopped } from "@marimo-team/client";
import { createStore } from "jotai";
import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
-import { ConnectionState } from "../../websocket/types";
+import { ConnectionState } from "../../../session/types";
import type { ConnectionStatus } from "../connection";
import { createNotebookReplica } from "../replica";
import { fakeBackend, fixtureEvents, fixtureMessages } from "./fixtures";
diff --git a/frontend/src/core/host/backend.ts b/frontend/src/core/notebook/replica/backend.ts
similarity index 100%
rename from frontend/src/core/host/backend.ts
rename to frontend/src/core/notebook/replica/backend.ts
diff --git a/frontend/src/core/host/connection.ts b/frontend/src/core/notebook/replica/connection.ts
similarity index 100%
rename from frontend/src/core/host/connection.ts
rename to frontend/src/core/notebook/replica/connection.ts
diff --git a/frontend/src/core/host/index.ts b/frontend/src/core/notebook/replica/index.ts
similarity index 75%
rename from frontend/src/core/host/index.ts
rename to frontend/src/core/notebook/replica/index.ts
index cdd8d035a9..8b3f7a0545 100644
--- a/frontend/src/core/host/index.ts
+++ b/frontend/src/core/notebook/replica/index.ts
@@ -1,6 +1,6 @@
/* Copyright 2026 Marimo. All rights reserved. */
-/** Notebook backends and the replica that follows them. */
+/** Backend-confirmed notebook state, independent of React and transports. */
export type { NotebookBackend } from "./backend";
export {
@@ -11,4 +11,3 @@ export {
} 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/replica.ts b/frontend/src/core/notebook/replica/replica.ts
similarity index 100%
rename from frontend/src/core/host/replica.ts
rename to frontend/src/core/notebook/replica/replica.ts
diff --git a/frontend/src/core/host/resources/attachments.ts b/frontend/src/core/notebook/replica/resources/attachments.ts
similarity index 100%
rename from frontend/src/core/host/resources/attachments.ts
rename to frontend/src/core/notebook/replica/resources/attachments.ts
diff --git a/frontend/src/core/host/resources/document.ts b/frontend/src/core/notebook/replica/resources/document.ts
similarity index 100%
rename from frontend/src/core/host/resources/document.ts
rename to frontend/src/core/notebook/replica/resources/document.ts
diff --git a/frontend/src/core/packages/__tests__/useSandboxController.test.tsx b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
index 9e132b4da8..df9829601c 100644
--- a/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
+++ b/frontend/src/core/packages/__tests__/useSandboxController.test.tsx
@@ -17,7 +17,7 @@ import type {
} from "@/core/network/types";
import { filenameAtom } from "@/core/saving/file-state";
import { store } from "@/core/state/jotai";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { HTTPError } from "@/utils/errors";
import { packageDataVersionAtom } from "../package-data";
import {
diff --git a/frontend/src/core/packages/useSandboxController.ts b/frontend/src/core/packages/useSandboxController.ts
index fc39164ae8..cf390fff1f 100644
--- a/frontend/src/core/packages/useSandboxController.ts
+++ b/frontend/src/core/packages/useSandboxController.ts
@@ -8,7 +8,7 @@ import { useRequestClient } from "@/core/network/requests";
import { useFilename } from "@/core/saving/filename";
import { waitFor } from "@/core/state/jotai";
import { isWasm } from "@/core/wasm/utils";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { HTTPError, prettyError } from "@/utils/errors";
import { invalidatePackageData } from "./package-data";
import {
diff --git a/frontend/src/core/run-app.tsx b/frontend/src/core/run-app.tsx
index dc2aa38b26..bc3c17311f 100644
--- a/frontend/src/core/run-app.tsx
+++ b/frontend/src/core/run-app.tsx
@@ -21,8 +21,8 @@ import { RuntimeState } from "./kernel/RuntimeState";
import { getSessionId } from "./kernel/session";
import { connectionAtom } from "./network/connection";
import { useRequestClient } from "./network/requests";
-import { isAppConnecting } from "./websocket/connection-utils";
-import { useNotebookSession } from "./websocket/useNotebookSession";
+import { isAppConnecting } from "./session/connection-utils";
+import { useNotebookSession } from "./session/useNotebookSession";
interface AppProps {
appConfig: AppConfig;
@@ -49,7 +49,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
return () => {
RuntimeState.INSTANCE.stop();
};
- }, []);
+ }, [sendComponentValues]);
const { connection, reconnect } = useNotebookSession({
autoInstantiate: true,
diff --git a/frontend/src/core/runtime/__tests__/adapter.test.ts b/frontend/src/core/runtime/__tests__/adapter.test.ts
index 78d550e9b7..d29734b720 100644
--- a/frontend/src/core/runtime/__tests__/adapter.test.ts
+++ b/frontend/src/core/runtime/__tests__/adapter.test.ts
@@ -6,7 +6,7 @@ import { islandsInitializedAtom } from "../../islands/state";
import { kernelStateAtom } from "../../kernel/state";
import { connectionAtom } from "../../network/connection";
import { wasmInitStateAtom } from "../../wasm/state";
-import { ConnectionState } from "../../websocket/types";
+import { ConnectionState } from "../../session/types";
import {
canRunCellsAtom,
islandsAdapter,
diff --git a/frontend/src/core/runtime/adapter.ts b/frontend/src/core/runtime/adapter.ts
index 64b86ae64e..548fb891a9 100644
--- a/frontend/src/core/runtime/adapter.ts
+++ b/frontend/src/core/runtime/adapter.ts
@@ -8,7 +8,7 @@ import { connectionAtom } from "../network/connection";
import { isStaticNotebook } from "../static/static-state";
import { wasmInitStateAtom } from "../wasm/state";
import { isWasm } from "../wasm/utils";
-import { ConnectionState } from "../websocket/types";
+import { ConnectionState } from "../session/types";
export type RuntimeKind = "wasm" | "remote" | "static" | "islands";
diff --git a/frontend/src/core/runtime/config.ts b/frontend/src/core/runtime/config.ts
index 9e30f0808d..eea0c9ca51 100644
--- a/frontend/src/core/runtime/config.ts
+++ b/frontend/src/core/runtime/config.ts
@@ -4,8 +4,8 @@ import useEvent from "react-use-event-hook";
import { Logger } from "@/utils/Logger";
import { connectionAtom } from "../network/connection";
import { store } from "../state/jotai";
-import { isAppNotStarted } from "../websocket/connection-utils";
-import { ConnectionState } from "../websocket/types";
+import { isAppNotStarted } from "../session/connection-utils";
+import { ConnectionState } from "../session/types";
import { RuntimeManager } from "./runtime";
import type { RuntimeConfig } from "./types";
diff --git a/frontend/src/core/saving/filename.ts b/frontend/src/core/saving/filename.ts
index 26a773c42a..9dd21eae80 100644
--- a/frontend/src/core/saving/filename.ts
+++ b/frontend/src/core/saving/filename.ts
@@ -9,7 +9,7 @@ import { getAppConfig } from "../config/config";
import { KnownQueryParams } from "../constants";
import { connectionAtom } from "../network/connection";
import { useRequestClient } from "../network/requests";
-import { ConnectionState } from "../websocket/types";
+import { ConnectionState } from "../session/types";
import { filenameAtom } from "./file-state";
export function useFilename() {
diff --git a/frontend/src/core/saving/save-component.tsx b/frontend/src/core/saving/save-component.tsx
index bdbfaa52d9..4eca9be682 100644
--- a/frontend/src/core/saving/save-component.tsx
+++ b/frontend/src/core/saving/save-component.tsx
@@ -34,7 +34,7 @@ import { layoutStateAtom } from "../layout/state";
import { kioskModeAtom } from "../mode";
import { connectionAtom } from "../network/connection";
import { useRequestClient } from "../network/requests";
-import { ConnectionState } from "../websocket/types";
+import { ConnectionState } from "../session/types";
import { isWasm } from "../wasm/utils";
import { filenameAtom } from "./file-state";
import { useFilename, useUpdateFilename } from "./filename";
diff --git a/frontend/src/core/saving/useAutoSave.ts b/frontend/src/core/saving/useAutoSave.ts
index 4a42752ad2..62a115c18c 100644
--- a/frontend/src/core/saving/useAutoSave.ts
+++ b/frontend/src/core/saving/useAutoSave.ts
@@ -2,7 +2,7 @@
import { useEffect, useRef } from "react";
import type { UserConfig } from "../config/config-schema";
import type { CellConfig } from "../network/types";
-import { type ConnectionStatus, ConnectionState } from "../websocket/types";
+import { type ConnectionStatus, ConnectionState } from "../session/types";
export function useAutoSave(opts: {
codes: string[];
diff --git a/frontend/src/core/websocket/__tests__/backend.test.ts b/frontend/src/core/session/__tests__/backend.test.ts
similarity index 97%
rename from frontend/src/core/websocket/__tests__/backend.test.ts
rename to frontend/src/core/session/__tests__/backend.test.ts
index 71990a884e..a93dd65471 100644
--- a/frontend/src/core/websocket/__tests__/backend.test.ts
+++ b/frontend/src/core/session/__tests__/backend.test.ts
@@ -4,13 +4,13 @@ import { NotebookEvents, StreamStopped } from "@marimo-team/client";
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 { ConnectionState } from "../../notebook/replica/connection";
import {
type FakeEdit,
type FakeSave,
fakeBackend,
-} from "../../host/__tests__/fixtures";
-import { createNotebookReplica } from "../../host/replica";
+} from "../../notebook/replica/__tests__/fixtures";
+import { createNotebookReplica } from "../../notebook/replica/replica";
import { createEditorBackend } from "../backend";
const wasm = vi.hoisted(() => ({ enabled: false, create: vi.fn() }));
diff --git a/frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsx b/frontend/src/core/session/__tests__/useNotebookReplica.hook.test.tsx
similarity index 73%
rename from frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsx
rename to frontend/src/core/session/__tests__/useNotebookReplica.hook.test.tsx
index dde443a682..9e248b48af 100644
--- a/frontend/src/core/websocket/__tests__/useNotebookReplica.hook.test.tsx
+++ b/frontend/src/core/session/__tests__/useNotebookReplica.hook.test.tsx
@@ -9,9 +9,12 @@ import type { NotebookTransport } from "@marimo-team/client";
import { ConnectionState } from "../types";
import { createEditorBackend } from "../backend";
import { useNotebookReplica } from "../useNotebookReplica";
-import { fakeBackend, fixtureMessages } from "../../host/__tests__/fixtures";
-import { agentAttachmentsAtom } from "../../attachments/state";
-import { notebookReplicaAtom } from "../state";
+import {
+ fakeBackend,
+ fixtureMessages,
+} from "../../notebook/replica/__tests__/fixtures";
+import { useNotebookAttachments } from "@/core/notebook";
+import { activeNotebookReplicaAtom } from "../active-notebook";
vi.mock("../backend", () => ({ createEditorBackend: vi.fn() }));
@@ -75,14 +78,25 @@ describe("useNotebookReplica", () => {
fakeBackend({ transport: fake.transport }),
);
const { result, store, unmount } = setup();
+ const attachments = renderHook(
+ () => ({
+ all: useNotebookAttachments(),
+ agents: useNotebookAttachments("agent"),
+ }),
+ {
+ wrapper: ({ children }: PropsWithChildren) => (
+ <Provider store={store}>{children}</Provider>
+ ),
+ },
+ );
await act(async () => Promise.resolve());
- expect(store.get(notebookReplicaAtom)).toBe(result.current);
+ expect(store.get(activeNotebookReplicaAtom)).toBe(result.current);
const [connection] = fake.opened;
act(() => {
connection.open();
fixtureMessages("notebook-events.sse").forEach(connection.receive);
});
- expect(store.get(agentAttachmentsAtom)).toEqual([
+ expect(attachments.result.current.agents).toEqual([
{
id: "a2",
notebook_id: "n1",
@@ -91,9 +105,37 @@ describe("useNotebookReplica", () => {
since: "2026-10-01T09:20:03Z",
},
]);
+ expect(attachments.result.current.all).toEqual(
+ store.get(result.current.attachmentsAtom),
+ );
+ expect(attachments.result.current.all.length).toBeGreaterThan(
+ attachments.result.current.agents.length,
+ );
+ const agents = attachments.result.current.agents;
+ const browser = attachments.result.current.all.find(
+ (attachment) => attachment.kind === "browser",
+ )!;
+ act(() =>
+ connection.receive({
+ event: "attachment",
+ data: { attachment: { ...browser, name: "Firefox" } },
+ }),
+ );
+ expect(attachments.result.current.agents).toBe(agents);
+
+ const renamedAgent = { ...agents[0], name: "Renamed agent" };
+ act(() =>
+ connection.receive({
+ event: "attachment",
+ data: { attachment: renamedAgent },
+ }),
+ );
+ expect(attachments.result.current.agents).toEqual([renamedAgent]);
+
unmount();
- expect(store.get(notebookReplicaAtom)).toBeNull();
- expect(store.get(agentAttachmentsAtom)).toEqual([]);
+ expect(store.get(activeNotebookReplicaAtom)).toBeNull();
+ expect(attachments.result.current).toEqual({ all: [], agents: [] });
+ attachments.unmount();
});
it("uses current callbacks and URL providers without reconnecting on a rerender", async () => {
diff --git a/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx b/frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx
similarity index 99%
rename from frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx
rename to frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx
index 5165eeef2e..925eb912b2 100644
--- a/frontend/src/core/websocket/__tests__/useNotebookSession.hook.test.tsx
+++ b/frontend/src/core/session/__tests__/useNotebookSession.hook.test.tsx
@@ -50,9 +50,9 @@ import { connectionAtom, startupProgressAtom } from "../../network/connection";
import { generateSessionId } from "../../kernel/session";
import { RuntimeManager } from "../../runtime/runtime";
import { WebSocketClosedReason, ConnectionState } from "../types";
-import { classifyCloseEvent } from "../connection-state";
+import { classifyCloseEvent } from "../../transports/connection-state";
import { createEditorBackend } from "../backend";
-import { fakeBackend } from "../../host/__tests__/fixtures";
+import { fakeBackend } from "../../notebook/replica/__tests__/fixtures";
import { useNotebookSession } from "../useNotebookSession";
import { type NotebookTransport, StreamStopped } from "@marimo-team/client";
diff --git a/frontend/src/core/websocket/state.ts b/frontend/src/core/session/active-notebook.ts
similarity index 50%
rename from frontend/src/core/websocket/state.ts
rename to frontend/src/core/session/active-notebook.ts
index 1cfdaf333b..ec0901d812 100644
--- a/frontend/src/core/websocket/state.ts
+++ b/frontend/src/core/session/active-notebook.ts
@@ -1,7 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { atom } from "jotai";
-import type { NotebookReplica } from "../host";
+import type { NotebookReplica } from "../notebook/replica";
/** The replica owned by the mounted notebook session. */
-export const notebookReplicaAtom = atom<NotebookReplica | null>(null);
+export const activeNotebookReplicaAtom = atom<NotebookReplica | null>(null);
diff --git a/frontend/src/core/websocket/backend.ts b/frontend/src/core/session/backend.ts
similarity index 95%
rename from frontend/src/core/websocket/backend.ts
rename to frontend/src/core/session/backend.ts
index c0f0e01abd..b7f9b77f80 100644
--- a/frontend/src/core/websocket/backend.ts
+++ b/frontend/src/core/session/backend.ts
@@ -4,15 +4,11 @@
import { NotebookClient, StreamStopped } from "@marimo-team/client";
import type { NotebookId } from "@marimo-team/client/protocol";
-import type { NotebookBackend } from "../host";
+import type { NotebookBackend } from "../notebook/replica";
import { PyodideBridge } from "../wasm/bridge";
import { isWasm } from "../wasm/utils";
-import {
- idle,
- sessionSse,
- websocket,
- withHeaders,
-} from "./transports/notebook";
+import { sessionSse, websocket, withHeaders } from "../transports/server";
+import { idle } from "../transports/static";
/** How the editor follows its notebook. */
export interface EditorBackendOptions {
diff --git a/frontend/src/core/websocket/connection-utils.ts b/frontend/src/core/session/connection-utils.ts
similarity index 100%
rename from frontend/src/core/websocket/connection-utils.ts
rename to frontend/src/core/session/connection-utils.ts
diff --git a/frontend/src/core/websocket/types.ts b/frontend/src/core/session/types.ts
similarity index 89%
rename from frontend/src/core/websocket/types.ts
rename to frontend/src/core/session/types.ts
index 2029325b1d..dcb8a5abe7 100644
--- a/frontend/src/core/websocket/types.ts
+++ b/frontend/src/core/session/types.ts
@@ -1,12 +1,12 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import type { ConnectionStatus as HostConnectionStatus } from "../host";
+import type { ConnectionStatus as HostConnectionStatus } from "../notebook/replica";
import type { NotificationMessageData } from "../kernel/messages";
export {
ConnectionState,
ConnectionClosedReason as WebSocketClosedReason,
-} from "../host";
+} from "../notebook/replica";
export type ConnectionPhase =
| NotificationMessageData<"startup-progress">["phase"]
diff --git a/frontend/src/core/websocket/useNotebookReplica.ts b/frontend/src/core/session/useNotebookReplica.ts
similarity index 85%
rename from frontend/src/core/websocket/useNotebookReplica.ts
rename to frontend/src/core/session/useNotebookReplica.ts
index 2693bfb3be..1ad3e2a6dc 100644
--- a/frontend/src/core/websocket/useNotebookReplica.ts
+++ b/frontend/src/core/session/useNotebookReplica.ts
@@ -9,8 +9,11 @@ import type {
NotificationMessage,
NotificationPayload,
} from "../kernel/messages";
-import { createNotebookReplica, type NotebookReplica } from "../host";
-import { notebookReplicaAtom } from "./state";
+import {
+ createNotebookReplica,
+ type NotebookReplica,
+} from "../notebook/replica";
+import { activeNotebookReplicaAtom } from "./active-notebook";
import { createEditorBackend, type EditorBackendOptions } from "./backend";
type Options = EditorBackendOptions & {
@@ -51,7 +54,7 @@ export function useNotebookReplica(options: Options): NotebookReplica {
);
useEffect(() => {
- store.set(notebookReplicaAtom, replica);
+ store.set(activeNotebookReplicaAtom, replica);
const disconnect = replica.connect(backend, {
// The host validates the envelope, not the native notification contents.
onNotification: (notification) =>
@@ -59,8 +62,8 @@ export function useNotebookReplica(options: Options): NotebookReplica {
});
return () => {
disconnect();
- if (store.get(notebookReplicaAtom) === replica) {
- store.set(notebookReplicaAtom, null);
+ if (store.get(activeNotebookReplicaAtom) === replica) {
+ store.set(activeNotebookReplicaAtom, null);
}
};
}, [replica, backend, store, onNotification]);
diff --git a/frontend/src/core/websocket/useNotebookSession.tsx b/frontend/src/core/session/useNotebookSession.tsx
similarity index 99%
rename from frontend/src/core/websocket/useNotebookSession.tsx
rename to frontend/src/core/session/useNotebookSession.tsx
index 6b66552bd8..5291020879 100644
--- a/frontend/src/core/websocket/useNotebookSession.tsx
+++ b/frontend/src/core/session/useNotebookSession.tsx
@@ -12,7 +12,7 @@ import type {
NotificationMessageData,
NotificationPayload,
} from "@/core/kernel/messages";
-import { useNotebookReplica } from "@/core/websocket/useNotebookReplica";
+import { useNotebookReplica } from "@/core/session/useNotebookReplica";
import { renderHTML } from "@/plugins/core/RenderHTML";
import {
handleWidgetMessage,
diff --git a/frontend/src/core/websocket/__tests__/connection-state.test.ts b/frontend/src/core/transports/__tests__/connection-state.test.ts
similarity index 96%
rename from frontend/src/core/websocket/__tests__/connection-state.test.ts
rename to frontend/src/core/transports/__tests__/connection-state.test.ts
index 8cbfcb4075..a72b3966b4 100644
--- a/frontend/src/core/websocket/__tests__/connection-state.test.ts
+++ b/frontend/src/core/transports/__tests__/connection-state.test.ts
@@ -2,7 +2,7 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { Logger } from "@/utils/Logger";
-import { WebSocketClosedReason, ConnectionState } from "../types";
+import { WebSocketClosedReason, ConnectionState } from "../../session/types";
import { classifyCloseEvent } from "../connection-state";
function classify(reason: string | undefined) {
diff --git a/frontend/src/core/websocket/transports/__tests__/notebook.test.ts b/frontend/src/core/transports/__tests__/server.test.ts
similarity index 97%
rename from frontend/src/core/websocket/transports/__tests__/notebook.test.ts
rename to frontend/src/core/transports/__tests__/server.test.ts
index 665f22ab2e..bfdd5ed191 100644
--- a/frontend/src/core/websocket/transports/__tests__/notebook.test.ts
+++ b/frontend/src/core/transports/__tests__/server.test.ts
@@ -7,11 +7,14 @@ import {
} from "@marimo-team/client";
import { createStore } from "jotai/vanilla";
import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
-import { createNotebookReplica } from "../../../host/replica";
-import { fakeBackend, fixtureMessages } from "../../../host/__tests__/fixtures";
-import { ConnectionState } from "../../../host/connection";
+import { createNotebookReplica } from "../../notebook/replica/replica";
+import {
+ fakeBackend,
+ fixtureMessages,
+} from "../../notebook/replica/__tests__/fixtures";
+import { ConnectionState } from "../../notebook/replica/connection";
import { Deferred } from "@/utils/Deferred";
-import { sessionSse, websocket } from "../notebook";
+import { sessionSse, websocket } from "../server";
const encoder = new TextEncoder();
diff --git a/frontend/src/core/host/__tests__/static.test.ts b/frontend/src/core/transports/__tests__/static.test.ts
similarity index 97%
rename from frontend/src/core/host/__tests__/static.test.ts
rename to frontend/src/core/transports/__tests__/static.test.ts
index 63a01384e3..08601bcd25 100644
--- a/frontend/src/core/host/__tests__/static.test.ts
+++ b/frontend/src/core/transports/__tests__/static.test.ts
@@ -3,12 +3,12 @@
import { createNotebookReducer, NotebookEvents } from "@marimo-team/client";
import * as Protocol from "@marimo-team/client/protocol";
import { afterEach, assert, describe, expect, it, vi } from "vitest";
-import { document as documentResource } from "../resources/document";
+import { document as documentResource } from "../../notebook/replica/resources/document";
import {
createStaticNotebookBackend,
type StaticNotebookSnapshot,
} from "../static";
-import { fixtureEvents } from "./fixtures";
+import { fixtureEvents } from "../../notebook/replica/__tests__/fixtures";
function snapshot(): StaticNotebookSnapshot {
const events = fixtureEvents("notebook-events.sse");
diff --git a/frontend/src/core/host/__tests__/wasm.test.ts b/frontend/src/core/transports/__tests__/wasm.test.ts
similarity index 98%
rename from frontend/src/core/host/__tests__/wasm.test.ts
rename to frontend/src/core/transports/__tests__/wasm.test.ts
index 1b3aca59f9..ab495abe53 100644
--- a/frontend/src/core/host/__tests__/wasm.test.ts
+++ b/frontend/src/core/transports/__tests__/wasm.test.ts
@@ -4,7 +4,7 @@ import { NotebookEvents, StreamStopped } from "@marimo-team/client";
import { afterEach, assert, describe, expect, it, vi } from "vitest";
import { Deferred } from "@/utils/Deferred";
import { createWasmNotebookBackend, type WasmNotebookBridge } from "../wasm";
-import { fixtureEvents } from "./fixtures";
+import { fixtureEvents } from "../../notebook/replica/__tests__/fixtures";
const streams: NotebookEvents[] = [];
afterEach(async () => {
diff --git a/frontend/src/core/websocket/connection-state.ts b/frontend/src/core/transports/connection-state.ts
similarity index 80%
rename from frontend/src/core/websocket/connection-state.ts
rename to frontend/src/core/transports/connection-state.ts
index 690f0459f4..b370e35841 100644
--- a/frontend/src/core/websocket/connection-state.ts
+++ b/frontend/src/core/transports/connection-state.ts
@@ -1,8 +1,11 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import type { CloseDecision } from "../host";
+import {
+ type CloseDecision,
+ ConnectionState,
+ ConnectionClosedReason,
+} from "../notebook/replica";
import { Logger } from "@/utils/Logger";
-import { ConnectionState, WebSocketClosedReason } from "./types";
// Keep server reasons in sync with ws_endpoint.py and ws/*.py.
// SSE carries the same reasons in close events. Unclassified reasons retry.
@@ -16,7 +19,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
kind: "terminal",
status: {
state: ConnectionState.CLOSED,
- code: WebSocketClosedReason.KERNEL_DISCONNECTED,
+ code: ConnectionClosedReason.KERNEL_DISCONNECTED,
reason: "kernel not found",
},
};
@@ -25,7 +28,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
kind: "terminal",
status: {
state: ConnectionState.CLOSED,
- code: WebSocketClosedReason.KERNEL_DISCONNECTED,
+ code: ConnectionClosedReason.KERNEL_DISCONNECTED,
reason: "not authorized",
},
};
@@ -34,7 +37,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
kind: "terminal",
status: {
state: ConnectionState.CLOSED,
- code: WebSocketClosedReason.KERNEL_DISCONNECTED,
+ code: ConnectionClosedReason.KERNEL_DISCONNECTED,
reason: "kiosk mode is not available for this session",
},
};
@@ -43,7 +46,7 @@ export function classifyCloseEvent(event: { reason?: string }): CloseDecision {
kind: "terminal",
status: {
state: ConnectionState.CLOSED,
- code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ code: ConnectionClosedReason.KERNEL_STARTUP_ERROR,
reason: "Failed to start kernel sandbox",
},
};
diff --git a/frontend/src/core/websocket/transports/notebook.ts b/frontend/src/core/transports/server.ts
similarity index 94%
rename from frontend/src/core/websocket/transports/notebook.ts
rename to frontend/src/core/transports/server.ts
index ca4cfdd658..859568b6ed 100644
--- a/frontend/src/core/websocket/transports/notebook.ts
+++ b/frontend/src/core/transports/server.ts
@@ -7,7 +7,7 @@ import {
type StreamUrl,
} from "@marimo-team/client";
import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
-import { classifyCloseEvent } from "../connection-state";
+import { classifyCloseEvent } from "./connection-state";
/** The server can be slow to accept when many notebooks are open. */
const CONNECT_MS = 10_000;
@@ -150,10 +150,3 @@ export function sessionSse(
}),
);
}
-
-/** A connection that opens and delivers nothing, for static notebooks. */
-export const idle: NotebookTransport = ({ signal }, { open }) =>
- new Promise((settle) => {
- open();
- signal.addEventListener("abort", () => settle(), { once: true });
- });
diff --git a/frontend/src/core/host/static.ts b/frontend/src/core/transports/static.ts
similarity index 85%
rename from frontend/src/core/host/static.ts
rename to frontend/src/core/transports/static.ts
index c86f305f01..0db4f1b9f7 100644
--- a/frontend/src/core/host/static.ts
+++ b/frontend/src/core/transports/static.ts
@@ -2,9 +2,9 @@
/** A backend that serves a document snapshot without a host. */
-import type { NotebookClient } from "@marimo-team/client";
+import type { NotebookClient, NotebookTransport } from "@marimo-team/client";
import type * as Protocol from "@marimo-team/client/protocol";
-import type { NotebookBackend } from "./backend";
+import type { NotebookBackend } from "../notebook/replica";
/** A document snapshot with its own identity and revision metadata. */
export interface StaticNotebookSnapshot {
@@ -75,3 +75,10 @@ export function createStaticNotebookBackend(
},
};
}
+
+/** A connection that opens and delivers nothing, for static notebooks. */
+export const idle: NotebookTransport = ({ signal }, { open }) =>
+ new Promise((settle) => {
+ open();
+ signal.addEventListener("abort", () => settle(), { once: true });
+ });
diff --git a/frontend/src/core/host/wasm.ts b/frontend/src/core/transports/wasm.ts
similarity index 97%
rename from frontend/src/core/host/wasm.ts
rename to frontend/src/core/transports/wasm.ts
index 89dc47a7c1..c679315927 100644
--- a/frontend/src/core/host/wasm.ts
+++ b/frontend/src/core/transports/wasm.ts
@@ -7,7 +7,7 @@ import {
StreamStopped,
type unstable_NotebookCall,
} from "@marimo-team/client";
-import type { NotebookBackend } from "./backend";
+import type { NotebookBackend } from "../notebook/replica";
/** The worker owns the notebook; this interface only carries commands and events. */
export interface WasmNotebookBridge {
diff --git a/frontend/src/core/wasm/__tests__/bridge.test.ts b/frontend/src/core/wasm/__tests__/bridge.test.ts
index 51d75928b2..235f6d3459 100644
--- a/frontend/src/core/wasm/__tests__/bridge.test.ts
+++ b/frontend/src/core/wasm/__tests__/bridge.test.ts
@@ -109,10 +109,10 @@ vi.mock("@/core/cells/document-changes", () => ({
// Import after all mocks are set up
import { store } from "@/core/state/jotai";
import { initialModeAtom } from "@/core/mode";
-import { fixtureEvents } from "@/core/host/__tests__/fixtures";
-import { createNotebookReplica } from "@/core/host";
-import { notebookReplicaAtom } from "@/core/websocket/state";
-import { createEditorBackend } from "@/core/websocket/backend";
+import { fixtureEvents } from "@/core/notebook/replica/__tests__/fixtures";
+import { createNotebookReplica } from "@/core/notebook/replica";
+import { activeNotebookReplicaAtom } from "@/core/session/active-notebook";
+import { createEditorBackend } from "@/core/session/backend";
import { fallbackFileStore, notebookFileStore } from "../store";
import { getWasmWorkerName, PyodideBridge } from "../bridge";
@@ -232,7 +232,7 @@ describe("PyodideBridge.sendSave", () => {
}
});
const replica = createNotebookReplica(store);
- store.set(notebookReplicaAtom, replica);
+ store.set(activeNotebookReplicaAtom, replica);
const backend = createEditorBackend({
static: false,
transportType: "sse",
@@ -250,7 +250,7 @@ describe("PyodideBridge.sendSave", () => {
afterEach(() => {
disconnect();
- store.set(notebookReplicaAtom, null);
+ store.set(activeNotebookReplicaAtom, null);
store.set(initialModeAtom, undefined);
});
@@ -272,9 +272,9 @@ describe("PyodideBridge.sendSave", () => {
"does not save when the notebook is %s",
async (state) => {
if (state === "unmounted") {
- store.set(notebookReplicaAtom, null);
+ store.set(activeNotebookReplicaAtom, null);
} else if (state === "not ready") {
- store.set(notebookReplicaAtom, createNotebookReplica(store));
+ store.set(activeNotebookReplicaAtom, createNotebookReplica(store));
} else {
disconnect();
}
diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.ts
index c7d8339393..ef4cf9fcb2 100644
--- a/frontend/src/core/wasm/bridge.ts
+++ b/frontend/src/core/wasm/bridge.ts
@@ -14,7 +14,7 @@ import { generateUUID } from "@/utils/uuid";
import { createModuleWorker } from "@/utils/worker";
import { notebookIsRunningAtom } from "../cells/cells";
import { flushDocumentChanges } from "../cells/document-changes";
-import { createWasmNotebookBackend } from "../host";
+import { createWasmNotebookBackend } from "../transports/wasm";
import type { ClientCommand } from "../kernel/messages";
import { getInitialAppMode } from "../mode";
import { API } from "../network/api";
@@ -42,7 +42,7 @@ import type {
} from "../network/types";
import { filenameAtom } from "../saving/file-state";
import { store } from "../state/jotai";
-import { notebookReplicaAtom } from "../websocket/state";
+import { activeNotebookReplicaAtom } from "../session/active-notebook";
import { PyodideRouter } from "./router";
import { getWorkerRPC, type PersistNotebookRequest } from "./rpc";
import { getWasmRuntimeConfig } from "./runtime-config";
@@ -267,7 +267,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
};
private async saveHostNotebook() {
- const replica = store.get(notebookReplicaAtom);
+ const replica = store.get(activeNotebookReplicaAtom);
const notebook = replica && store.get(replica.notebookAtom);
const backend = replica && store.get(replica.backendAtom);
if (!notebook || !backend) {
diff --git a/frontend/src/mount.tsx b/frontend/src/mount.tsx
index 213da3ea2a..5ec0f0a2f1 100644
--- a/frontend/src/mount.tsx
+++ b/frontend/src/mount.tsx
@@ -62,7 +62,7 @@ import {
import { maybeRegisterVSCodeBindings } from "./core/vscode/vscode-bindings";
import type { FileStore } from "./core/wasm/store";
import { notebookFileStore } from "./core/wasm/store";
-import { ConnectionState } from "./core/websocket/types";
+import { ConnectionState } from "./core/session/types";
import {
handleWidgetMessage,
WIDGET_REGISTRY,
diff --git a/frontend/src/stories/cell.stories.tsx b/frontend/src/stories/cell.stories.tsx
index 1e85bf8ddf..e61b587493 100644
--- a/frontend/src/stories/cell.stories.tsx
+++ b/frontend/src/stories/cell.stories.tsx
@@ -14,7 +14,7 @@ import { connectionAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
import { resolveRequestClient } from "@/core/network/resolve";
import type { CellConfig } from "@/core/network/types";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { MultiColumn } from "@/utils/id-tree";
import type { Milliseconds, Seconds } from "@/utils/time";
import { Cell as EditorCell } from "../components/editor/notebook-cell";
diff --git a/frontend/src/stories/layout/vertical/one-column.stories.tsx b/frontend/src/stories/layout/vertical/one-column.stories.tsx
index fba331a7ea..9cfdfffbd3 100644
--- a/frontend/src/stories/layout/vertical/one-column.stories.tsx
+++ b/frontend/src/stories/layout/vertical/one-column.stories.tsx
@@ -11,7 +11,7 @@ import { showCodeInRunModeAtom } from "@/core/meta/state";
import { connectionAtom } from "@/core/network/connection";
import { requestClientAtom } from "@/core/network/requests";
import { resolveRequestClient } from "@/core/network/resolve";
-import { ConnectionState } from "@/core/websocket/types";
+import { ConnectionState } from "@/core/session/types";
import { MultiColumn } from "@/utils/id-tree";
import type { Milliseconds, Seconds } from "@/utils/time";
import { CellArray } from "../../../components/editor/renderers/cell-array";
diff --git a/frontend/src/stories/runtime-story.tsx b/frontend/src/stories/runtime-story.tsx
index 1625b52363..2b49dd98c1 100644
--- a/frontend/src/stories/runtime-story.tsx
+++ b/frontend/src/stories/runtime-story.tsx
@@ -30,7 +30,7 @@ import { requestClientAtom } from "@/core/network/requests";
import { createStaticRequests } from "@/core/network/requests-static";
import { sandboxActionsAtom, sandboxAtom } from "@/core/packages/sandbox-state";
import { filenameAtom } from "@/core/saving/file-state";
-import { WebSocketClosedReason, ConnectionState } from "@/core/websocket/types";
+import { WebSocketClosedReason, ConnectionState } from "@/core/session/types";
import { HTTPError } from "@/utils/errors";
const manifest = `requires-python = ">=3.13"