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.

Use the same startup UI for all runtimes (#11085)

Trevor Manzbbe009c19eef
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 4a74ac817e..603c6dfc98 100644
--- a/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
+++ b/frontend/src/components/editor/alerts/__tests__/connection-notice.test.tsx
@@ -8,16 +8,22 @@ import { alertAtom, getPackageAlert } from "@/core/alerts/state";
import { notebookAtom } from "@/core/cells/cells";
import { CellId } from "@/core/cells/ids";
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, WebSocketState } from "@/core/websocket/types";
import { chromeAtom } from "../../chrome/state";
+import { runtimeDetailsExpandedAtom } from "../../chrome/panels/runtime-details-state";
import { ConnectionNotice } from "../connection-notice";
beforeEach(() => vi.useFakeTimers());
afterEach(() => vi.useRealTimers());
-function mount(existingCells = false) {
+function mount({
+ existingCells = false,
+ onRetry = vi.fn(),
+ canOpenPackages = true,
+} = {}) {
const store = createStore();
store.set(sandboxAtom, {
backend: "pixi",
@@ -40,7 +46,8 @@ function mount(existingCells = false) {
<Provider store={store}>
<ConnectionNotice
appConfig={AppConfigSchema.parse({})}
- onRetry={vi.fn()}
+ onRetry={onRetry}
+ canOpenPackages={canOpenPackages}
/>
</Provider>,
);
@@ -78,8 +85,122 @@ it("shows both stages in an empty notebook, checks them off, then dismisses Read
).not.toBeInTheDocument();
});
+it("uses the shared kernel stage for an ordinary connection and dismisses it when connected", () => {
+ const store = mount();
+ act(() => {
+ store.set(sandboxAtom, null);
+ store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+ });
+ act(() => vi.advanceTimersByTime(500));
+ const stages = within(
+ screen.getByRole("list", {
+ name: "Notebook startup stages",
+ }),
+ );
+ expect(stages.getAllByRole("listitem")).toHaveLength(1);
+ expect(stages.getByText("Starting kernel")).toBeVisible();
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ expect(screen.queryByRole("region", { name: "Notebook startup" })).toBeNull();
+});
+
+it("shows connection status until a sandbox reports its startup phase", () => {
+ const store = mount();
+ act(() => store.set(connectionAtom, { state: WebSocketState.CONNECTING }));
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByRole("heading", { name: "Connecting…" })).toBeVisible();
+ expect(screen.queryByRole("list")).not.toBeInTheDocument();
+
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ }),
+ );
+ expect(
+ screen.getByRole("heading", { name: "Kernel failed to start" }),
+ ).toBeVisible();
+ expect(screen.queryByRole("list")).not.toBeInTheDocument();
+
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "preparing-environment",
+ }),
+ );
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByRole("list")).toHaveTextContent("Preparing environment");
+});
+
+it("shows kernel startup while sandbox metadata is loading, then adds environment preparation", () => {
+ const store = mount();
+ const sandbox = store.get(sandboxAtom);
+ act(() => store.set(sandboxAtom, null));
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByText("Starting kernel")).toBeVisible();
+ expect(screen.getAllByRole("listitem")).toHaveLength(1);
+
+ act(() => store.set(sandboxAtom, sandbox));
+ const stages = within(screen.getByRole("list"));
+ expect(stages.getByText("Preparing environment")).toBeVisible();
+ expect(stages.getByText("Start kernel")).toBeVisible();
+});
+
+it("shows ordinary environment preparation failures in the kernel stage", () => {
+ const store = mount();
+ act(() => store.set(sandboxAtom, null));
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByText("Starting kernel")).toBeVisible();
+ expect(screen.getAllByRole("listitem")).toHaveLength(1);
+ act(() => {
+ store.set(
+ kernelStartupErrorAtom,
+ "Configured Python environment is missing",
+ );
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ phase: "preparing-environment",
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ });
+ });
+ expect(screen.getByRole("listitem")).toHaveTextContent(
+ "Kernel failed to start",
+ );
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Kernel failed to start",
+ );
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(
+ "Configured Python environment is missing",
+ );
+});
+
+it("reports the inline disclosure as expanded only when Packages and runtime details are open", () => {
+ const store = mount({ existingCells: true });
+ act(() => {
+ store.set(chromeAtom, (value) => ({
+ ...value,
+ isSidebarOpen: true,
+ selectedPanel: "packages",
+ }));
+ store.set(runtimeDetailsExpandedAtom, false);
+ });
+ act(() => vi.advanceTimersByTime(500));
+ const toggle = screen.getByRole("button", { name: /Open Packages/ });
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ fireEvent.click(toggle);
+ expect(toggle).toHaveAttribute("aria-expanded", "true");
+ act(() => store.set(runtimeDetailsExpandedAtom, false));
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ act(() => {
+ store.set(runtimeDetailsExpandedAtom, true);
+ store.set(chromeAtom, (value) => ({ ...value, isSidebarOpen: false }));
+ });
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+});
+
it("opens Packages from the minimal inline status when cells exist", () => {
- const store = mount(true);
+ const store = mount({ existingCells: true });
act(() => vi.advanceTimersByTime(500));
expect(screen.queryByRole("list")).not.toBeInTheDocument();
fireEvent.click(screen.getByRole("button", { name: /Open Packages/ }));
@@ -91,8 +212,94 @@ it("opens Packages from the minimal inline status when cells exist", () => {
expect(screen.getByRole("status")).toHaveTextContent(/^Ready$/);
});
+it("uses an inline notice for an existing ordinary notebook, opens collapsed details, and offers retry on failure", () => {
+ const onRetry = vi.fn();
+ const store = mount({ existingCells: true, onRetry });
+ act(() => {
+ store.set(sandboxAtom, null);
+ store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+ store.set(runtimeDetailsExpandedAtom, false);
+ });
+ act(() => vi.advanceTimersByTime(500));
+ const statusRow = screen.getByRole("region", {
+ name: "Notebook startup",
+ }).parentElement;
+ fireEvent.click(screen.getByRole("button", { name: /Open Packages/ }));
+ expect(store.get(chromeAtom)).toMatchObject({
+ isSidebarOpen: true,
+ selectedPanel: "packages",
+ });
+ expect(store.get(runtimeDetailsExpandedAtom)).toBe(true);
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ }),
+ );
+ expect(
+ screen.getByRole("button", {
+ name: /Kernel failed to start Open Packages/,
+ }),
+ ).toBeVisible();
+ fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+ expect(onRetry).toHaveBeenCalledOnce();
+ act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
+ expect(screen.queryByRole("region", { name: "Notebook startup" })).toBeNull();
+ expect(statusRow).not.toBeInTheDocument();
+});
+
+it.each([
+ { existingCells: false, sandbox: false },
+ { existingCells: true, sandbox: false },
+ { existingCells: false, sandbox: true },
+ { existingCells: true, sandbox: true },
+])(
+ "keeps errors in the notebook without chrome (cells=$existingCells, sandbox=$sandbox)",
+ ({ existingCells, sandbox }) => {
+ const onRetry = vi.fn();
+ const store = mount({ existingCells, onRetry, canOpenPackages: false });
+ act(() => {
+ if (!sandbox) {
+ store.set(sandboxAtom, null);
+ }
+ store.set(connectionAtom, {
+ state: WebSocketState.CONNECTING,
+ phase: "starting-kernel",
+ });
+ });
+ act(() => vi.advanceTimersByTime(500));
+ expect(screen.getByText("Starting kernel")).toBeVisible();
+ expect(screen.getByRole("status")).toHaveTextContent("Starting kernel…");
+ expect(screen.queryByRole("button")).not.toBeInTheDocument();
+
+ act(() => {
+ store.set(kernelStartupErrorAtom, "Could not import the runtime");
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ phase: "starting-kernel",
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ });
+ });
+ expect(screen.getByLabelText("Error details")).toHaveTextContent(
+ "Could not import the runtime",
+ );
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Kernel failed to start",
+ );
+ expect(
+ screen.queryByRole("button", { name: /Open Packages/ }),
+ ).not.toBeInTheDocument();
+ if (!sandbox) {
+ fireEvent.click(screen.getByRole("button", { name: "Try again" }));
+ }
+ expect(onRetry).toHaveBeenCalledTimes(sandbox ? 0 : 1);
+ },
+);
+
it("does not flash Ready for a startup that finished before the notice appeared", () => {
- const store = mount(true);
+ const store = mount({ existingCells: true });
act(() => vi.advanceTimersByTime(200));
act(() => store.set(connectionAtom, { state: WebSocketState.OPEN }));
expect(screen.queryByRole("status")).not.toBeInTheDocument();
@@ -128,7 +335,7 @@ it("replaces Ready with a new attempt and never dismisses a failure", () => {
});
it("shows a sync as a single operation, without pretending to restart the kernel", () => {
- const store = mount(true);
+ const store = mount({ existingCells: true });
act(() => {
store.set(connectionAtom, { state: WebSocketState.OPEN });
store.set(sandboxSyncAtom, { kind: "running" });
@@ -141,7 +348,7 @@ it("shows a sync as a single operation, without pretending to restart the kernel
});
it("restores syncing in the existing status and stays quiet for a completed snapshot", () => {
- const store = mount(true);
+ const store = mount({ existingCells: true });
const operation: EnvironmentOperation = {
operation_id: "sync",
action: "sync",
diff --git a/frontend/src/components/editor/alerts/connection-details.tsx b/frontend/src/components/editor/alerts/connection-details.tsx
new file mode 100644
index 0000000000..7640f718c4
--- /dev/null
+++ b/frontend/src/components/editor/alerts/connection-details.tsx
@@ -0,0 +1,61 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { PropsWithChildren } from "react";
+import type { DisplayConnectionNotice } from "@/core/network/useConnectionNotice";
+import { cn } from "@/utils/cn";
+import {
+ ConnectionStatusIcon,
+ hasStartupStages,
+ StartupProgress,
+} from "./startup-progress";
+
+export function ConnectionErrorOutput({ error }: { error: string }) {
+ return (
+ <pre
+ tabIndex={0}
+ aria-label="Error details"
+ className="mt-3 p-3 rounded border bg-muted/30 text-xs text-muted-foreground whitespace-pre min-w-0 max-w-full max-h-52 overflow-auto"
+ >
+ {error}
+ </pre>
+ );
+}
+
+export function ConnectionDetails({
+ notice,
+ surface = "sidebar",
+ children,
+}: PropsWithChildren<{
+ notice: DisplayConnectionNotice;
+ surface?: "notebook" | "sidebar";
+}>) {
+ const showSteps = hasStartupStages(notice);
+ const failed = !notice.pending && !notice.ready;
+ return (
+ <div className="min-w-0 text-sm">
+ {showSteps ? (
+ <StartupProgress notice={notice} surface={surface} />
+ ) : (
+ <div className="flex items-center gap-2" role="status">
+ <ConnectionStatusIcon notice={notice} />
+ <h2
+ className={cn(
+ surface === "notebook" && "text-base",
+ failed ? "font-medium text-(--red-11)" : "text-foreground",
+ )}
+ >
+ {notice.title}
+ </h2>
+ </div>
+ )}
+ {(failed || (!showSteps && surface === "notebook")) && (
+ <p className={cn("mt-2", failed && "text-foreground")}>
+ {notice.description}
+ </p>
+ )}
+ {notice.error && (surface === "sidebar" || !notice.sandbox) && (
+ <ConnectionErrorOutput error={notice.error} />
+ )}
+ {children}
+ </div>
+ );
+}
diff --git a/frontend/src/components/editor/alerts/connection-notice.tsx b/frontend/src/components/editor/alerts/connection-notice.tsx
index 2fe0356037..56f52e6605 100644
--- a/frontend/src/components/editor/alerts/connection-notice.tsx
+++ b/frontend/src/components/editor/alerts/connection-notice.tsx
@@ -1,5 +1,5 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import { useAtomValue } from "jotai";
+import { useAtom, useAtomValue } from "jotai";
import { ArrowRightIcon, ChevronRightIcon } from "lucide-react";
import { useState } from "react";
import { Button } from "@/components/ui/button";
@@ -11,22 +11,28 @@ import { sandboxAtom } from "@/core/packages/sandbox-state";
import { WebSocketState } from "@/core/websocket/types";
import { useInterval } from "@/hooks/useInterval";
import { cn } from "@/utils/cn";
-import { SandboxErrorOutput } from "../chrome/panels/sandbox-panel";
+import { runtimeDetailsExpandedAtom } from "../chrome/panels/runtime-details-state";
import { chromeAtom, useChromeActions } from "../chrome/state";
import { VerticalLayoutWrapper } from "../renderers/vertical-layout/vertical-layout-wrapper";
-import { ConnectionStatusIcon, StartupProgress } from "./startup-progress";
+import { ConnectionDetails } from "./connection-details";
+import { ConnectionStatusIcon, hasStartupStages } from "./startup-progress";
export const ConnectionNotice = ({
appConfig,
onRetry,
+ canOpenPackages = true,
}: {
appConfig: AppConfig;
onRetry: () => void;
+ canOpenPackages?: boolean;
}) => {
const notice = useConnectionNotice();
const connection = useAtomValue(connectionAtom);
const hasCells = useAtomValue(hasCellsAtom);
const sandbox = useAtomValue(sandboxAtom);
+ const [detailsExpanded, setDetailsExpanded] = useAtom(
+ runtimeDetailsExpandedAtom,
+ );
const chrome = useAtomValue(chromeAtom);
const packagesOpen =
(chrome.isSidebarOpen && chrome.selectedPanel === "packages") ||
@@ -39,45 +45,57 @@ export const ConnectionNotice = ({
connection.state === WebSocketState.CONNECTING &&
connection.phase === "reconnecting";
- if (sandbox?.backend && hasCells) {
+ const openDetails = () => {
+ setDetailsExpanded(true);
+ openApplication("packages");
+ };
+
+ if (!notice && !sandbox?.backend) {
+ return null;
+ }
+
+ if (hasCells && canOpenPackages) {
const title =
notice?.ready && notice.kind === "startup" ? "Ready" : notice?.title;
return (
<VerticalLayoutWrapper
appConfig={appConfig}
- // Reserve the status row and gutter so completion never shifts cells.
+ // Sandboxes retain this row for subsequent environment syncs.
className="shrink-0 h-12 pb-0 sm:pb-0 print:hidden"
innerClassName="pb-0 sm:pb-0 pr-4"
>
{notice && !reconnecting && (
- <section aria-label="Notebook startup">
+ <section
+ aria-label="Notebook startup"
+ className="flex items-center gap-4"
+ >
<button
type="button"
- onClick={() => openApplication("packages")}
+ onClick={openDetails}
aria-label={`${title} Open Packages`}
- aria-expanded={packagesOpen}
+ aria-expanded={packagesOpen && detailsExpanded}
className="flex h-6 items-center gap-2 whitespace-nowrap text-xs text-muted-foreground hover:text-foreground rounded focus-visible:outline-2 focus-visible:outline-ring"
>
<ConnectionStatusIcon notice={notice} />
<output>{title}</output>
<ChevronRightIcon className="size-3" aria-hidden={true} />
</button>
+ {!notice.pending && !notice.ready && !notice.sandbox && (
+ <Button variant="text" size="xs" onClick={onRetry}>
+ Try again
+ </Button>
+ )}
</section>
)}
</VerticalLayoutWrapper>
);
}
- if (!notice || (hasCells && reconnecting)) {
+ if (!notice) {
return null;
}
- const showSteps =
- notice.sandbox &&
- notice.kind === "startup" &&
- (notice.ready ||
- notice.phase === "preparing-environment" ||
- notice.phase === "starting-kernel");
+ const showSteps = hasStartupStages(notice);
return (
<VerticalLayoutWrapper
appConfig={appConfig}
@@ -87,51 +105,26 @@ export const ConnectionNotice = ({
<section
aria-label="Notebook startup"
className={cn(
- "text-muted-foreground",
- hasCells
- ? "mt-4 mb-8 border rounded-lg px-5 py-5"
- : "max-w-md mx-auto mt-16 sm:mt-24 px-4",
- hasCells && !notice.pending && "border-(--red-7)",
+ "text-muted-foreground max-w-md mx-auto px-4",
+ hasCells ? "mt-4 mb-8" : "mt-16 sm:mt-24",
)}
>
- {showSteps ? (
- <StartupProgress notice={notice} surface="notebook" />
- ) : (
- <div role="status" className="flex items-center gap-2.5">
- <ConnectionStatusIcon notice={notice} />
- <h2
- className={cn(
- "text-base",
- notice.pending || notice.ready
- ? "font-normal text-foreground"
- : "font-medium text-(--red-11)",
- )}
- >
- {notice.title}
- </h2>
- </div>
+ {!canOpenPackages && showSteps && (
+ <output className="sr-only">{notice.title}</output>
)}
+ <ConnectionDetails
+ notice={notice}
+ surface={canOpenPackages ? "notebook" : "sidebar"}
+ />
<div className={showSteps ? "mt-8" : "ml-6.5"}>
- {!showSteps && (
- <p
- className={cn(
- "mt-3 text-sm leading-7",
- !notice.pending && "text-foreground",
- )}
- >
- {notice.description}
- </p>
- )}
- {!notice.sandbox && notice.error && (
- <SandboxErrorOutput error={notice.error} />
- )}
<div
className={cn(
"flex flex-wrap items-center gap-x-6 gap-y-3",
showSteps ? "border-t border-border/60 pt-4" : "mt-5",
)}
>
- {!notice.ready &&
+ {canOpenPackages &&
+ !notice.ready &&
!packagesOpen &&
(notice.sandbox || notice.pending) && (
<Button
@@ -141,7 +134,7 @@ export const ConnectionNotice = ({
"p-0 text-xs gap-1.5",
showSteps ? "h-6" : "h-auto",
)}
- onClick={() => openApplication("packages")}
+ onClick={openDetails}
>
{notice.pending ? "View setup details" : "Open Packages"}
<ArrowRightIcon className="size-3" aria-hidden={true} />
diff --git a/frontend/src/components/editor/alerts/startup-progress.tsx b/frontend/src/components/editor/alerts/startup-progress.tsx
index 7683d42307..b6bc39ce58 100644
--- a/frontend/src/components/editor/alerts/startup-progress.tsx
+++ b/frontend/src/components/editor/alerts/startup-progress.tsx
@@ -1,41 +1,44 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { useAtomValue } from "jotai";
-import { AlertCircleIcon, CheckIcon, CircleIcon } from "lucide-react";
-import { Spinner } from "@/components/icons/spinner";
+import {
+ ProgressStages,
+ ProgressStatusIcon,
+ type ProgressStage,
+ type ProgressState,
+} from "@/components/ui/progress-stages";
import { preparationAtom } from "@/core/packages/sandbox-state";
import { startupProgressAtom } from "@/core/network/connection";
import type { DisplayConnectionNotice } from "@/core/network/useConnectionNotice";
-import { cn } from "@/utils/cn";
-import { StartupOutput, type StartupOutputState } from "./startup-output";
+import { StartupOutput } from "./startup-output";
const STEPS = [
{
phase: "preparing-environment",
titles: {
- complete: "Environment prepared",
+ succeeded: "Environment prepared",
failed: "Environment setup failed",
- pending: "Preparing environment",
+ running: "Preparing environment",
waiting: "Prepare environment",
},
descriptions: {
- complete: "Python and dependencies are available.",
+ succeeded: "Python and dependencies are available.",
failed: "Setup could not finish.",
- pending: "Set up Python and dependencies.",
+ running: "Set up Python and dependencies.",
waiting: "Set up Python and dependencies.",
},
},
{
phase: "starting-kernel",
titles: {
- complete: "Kernel started",
+ succeeded: "Kernel started",
failed: "Kernel failed to start",
- pending: "Starting kernel",
+ running: "Starting kernel",
waiting: "Start kernel",
},
descriptions: {
- complete: "The notebook is ready to run.",
+ succeeded: "The notebook is ready to run.",
failed: "The kernel could not connect.",
- pending: "Connecting to this notebook.",
+ running: "Connecting to this notebook.",
waiting: "After the environment is ready.",
},
},
@@ -46,31 +49,13 @@ interface StartupProgressProps {
surface: "notebook" | "sidebar";
}
-function StartupStepOutput({
- phase,
- state,
-}: {
- phase: (typeof STEPS)[number]["phase"];
- state: StartupOutputState;
-}) {
- const preparation = useAtomValue(preparationAtom);
- const progress = useAtomValue(startupProgressAtom);
- const preparing = phase === "preparing-environment";
- const logs = preparing
- ? (preparation?.logs.environment ?? "")
- : progress?.phase === phase
- ? progress.logs
- : "";
-
+export function hasStartupStages(notice: DisplayConnectionNotice): boolean {
return (
- <StartupOutput
- key={preparation?.operation_id}
- logs={logs}
- state={state}
- label={
- preparing ? "environment preparation output" : "kernel startup output"
- }
- />
+ notice.kind === "startup" &&
+ (!notice.sandbox ||
+ notice.ready ||
+ notice.phase === "preparing-environment" ||
+ notice.phase === "starting-kernel")
);
}
@@ -85,9 +70,13 @@ function StartupSummary({ notice }: { notice: DisplayConnectionNotice }) {
</h2>
<p className="text-muted-foreground mt-3 text-sm leading-6">
{notice.ready
- ? "Your environment and kernel are ready."
+ ? notice.sandbox
+ ? "Your environment and kernel are ready."
+ : "Your kernel is ready."
: notice.pending
- ? "Preparing Python and dependencies for this notebook."
+ ? notice.sandbox
+ ? "Preparing Python and dependencies for this notebook."
+ : "Connecting to this notebook’s Python kernel."
: "Review the setup details below to continue."}
</p>
</header>
@@ -99,106 +88,61 @@ export function ConnectionStatusIcon({
}: {
notice: DisplayConnectionNotice;
}) {
- if (notice.ready) {
- return (
- <CheckIcon
- className="size-4 shrink-0 text-(--grass-11)"
- aria-hidden={true}
- />
- );
- }
- if (notice.pending) {
- return (
- <Spinner
- className="size-4 shrink-0 motion-reduce:animate-none"
- aria-hidden={true}
- />
- );
- }
return (
- <AlertCircleIcon
- className="size-4 shrink-0 text-(--red-11)"
- aria-hidden={true}
+ <ProgressStatusIcon
+ state={notice.ready ? "succeeded" : notice.pending ? "running" : "failed"}
/>
);
}
export function StartupProgress({ notice, surface }: StartupProgressProps) {
+ const preparation = useAtomValue(preparationAtom);
+ const progress = useAtomValue(startupProgressAtom);
+ const activePhase = notice.sandbox ? notice.phase : "starting-kernel";
+ const stages: ProgressStage[] = STEPS.filter(
+ (step) => notice.sandbox || step.phase === "starting-kernel",
+ ).map(({ phase, titles, descriptions }) => {
+ const preparing = phase === "preparing-environment";
+ const state: ProgressState =
+ notice.ready || (preparing && activePhase === "starting-kernel")
+ ? "succeeded"
+ : activePhase === phase
+ ? notice.pending
+ ? "running"
+ : "failed"
+ : "waiting";
+ const logs = preparing
+ ? (preparation?.logs.environment ?? "")
+ : progress?.phase === phase
+ ? progress.logs
+ : "";
+ return {
+ id: phase,
+ state,
+ title: titles[state],
+ description: descriptions[state],
+ details: surface === "sidebar" && (
+ <StartupOutput
+ key={preparation?.operation_id}
+ logs={logs}
+ state={state === "waiting" ? "succeeded" : state}
+ label={
+ preparing
+ ? "environment preparation output"
+ : "kernel startup output"
+ }
+ />
+ ),
+ };
+ });
return (
<>
{surface === "notebook" && <StartupSummary notice={notice} />}
- <ol
- className={cn("space-y-6", surface === "notebook" && "mt-8")}
- aria-label="Notebook startup stages"
- >
- {STEPS.map(({ phase, titles, descriptions }, index) => {
- const complete =
- notice.ready || (index === 0 && notice.phase === "starting-kernel");
- const active = !notice.ready && notice.phase === phase;
- const failed = active && !notice.pending;
- const state = complete
- ? "complete"
- : failed
- ? "failed"
- : active
- ? "pending"
- : "waiting";
- return (
- <li
- key={phase}
- aria-current={active ? "step" : undefined}
- className="relative flex items-start gap-3"
- >
- {index === 0 && (
- <span
- aria-hidden={true}
- className="absolute left-2 top-6 -bottom-4 border-l border-border"
- />
- )}
- <span
- className={cn(
- "mt-0.5",
- complete ? "text-(--grass-11)" : "text-muted-foreground",
- )}
- >
- {complete ? (
- <CheckIcon className="size-4" aria-hidden={true} />
- ) : active ? (
- <ConnectionStatusIcon notice={notice} />
- ) : (
- <CircleIcon
- className="size-4 text-muted-foreground/50"
- aria-hidden={true}
- />
- )}
- </span>
- <div className="min-w-0 flex-1">
- <div
- className={cn(
- "text-sm",
- failed
- ? "text-(--red-11)"
- : complete || active
- ? "text-foreground"
- : "text-muted-foreground",
- )}
- >
- {titles[state]}
- </div>
- <p className="mt-1 text-xs text-muted-foreground">
- {descriptions[state]}
- </p>
- {surface === "sidebar" && (
- <StartupStepOutput
- phase={phase}
- state={failed ? "failed" : active ? "running" : "succeeded"}
- />
- )}
- </div>
- </li>
- );
- })}
- </ol>
+ <ProgressStages
+ stages={stages}
+ label="Notebook startup stages"
+ className={surface === "notebook" ? "mt-8" : undefined}
+ />
</>
);
}
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 a1a853009e..a5df5684fc 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 { store } from "@/core/state/jotai";
import { WebSocketState } from "@/core/websocket/types";
import PackagesPanel from "../packages-panel";
import { PanelSectionProvider } from "../panel-context";
-import { SandboxToggle } from "../sandbox-toggle";
+import { RuntimeStatusToggle } from "../runtime-status-toggle";
const { openSettings } = vi.hoisted(() => ({
openSettings: vi.fn(),
@@ -87,7 +87,7 @@ function renderPanel(
<Provider store={store}>
<TooltipProvider>
<PanelSectionProvider value="sidebar">
- <SandboxToggle section="sidebar" />
+ <RuntimeStatusToggle section="sidebar" />
<PackagesPanel />
</PanelSectionProvider>
</TooltipProvider>
@@ -201,7 +201,7 @@ it("refreshes an open panel when a package is installed elsewhere, after install
<Provider store={store}>
<TooltipProvider>
<PanelSectionProvider value="sidebar">
- <SandboxToggle section="sidebar" />
+ <RuntimeStatusToggle section="sidebar" />
<PackagesPanel />
</PanelSectionProvider>
<InstallElsewhere />
@@ -235,7 +235,7 @@ it("keeps packages and the install draft visible while blocking mutations during
expect(
screen.queryByRole("list", { name: "Notebook startup stages" }),
).not.toBeInTheDocument();
- const toggle = screen.getByRole("button", { name: "pixi sandbox" });
+ const toggle = screen.getByRole("button", { name: /^pixi sandbox, / });
fireEvent.click(toggle);
expect(toggle).toHaveAttribute("aria-expanded", "false");
act(() =>
diff --git a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-details.test.tsx b/frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx
similarity index 75%
rename from frontend/src/components/editor/chrome/panels/__tests__/sandbox-details.test.tsx
rename to frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx
index 86b6ae1ae8..6cbcb6bbd0 100644
--- a/frontend/src/components/editor/chrome/panels/__tests__/sandbox-details.test.tsx
+++ b/frontend/src/components/editor/chrome/panels/__tests__/runtime-details.test.tsx
@@ -14,7 +14,7 @@ import { sandboxAtom } from "@/core/packages/sandbox-state";
import { WebSocketClosedReason, WebSocketState } from "@/core/websocket/types";
import PackagesPanel from "../packages-panel";
import { PanelSectionProvider } from "../panel-context";
-import { SandboxToggle } from "../sandbox-toggle";
+import { RuntimeStatusToggle } from "../runtime-status-toggle";
vi.mock("@/utils/reload-safe", () => ({ reloadSafe: vi.fn() }));
@@ -89,7 +89,7 @@ function mount({
<Provider store={store}>
<TooltipProvider>
<ModalProvider>
- <SandboxToggle section="sidebar" />
+ <RuntimeStatusToggle section="sidebar" />
<PanelSectionProvider value="sidebar">
<PackagesPanel />
</PanelSectionProvider>
@@ -103,7 +103,7 @@ function mount({
it("opens restored preparation and kernel logs without reopening completed startup on refresh", async () => {
mount();
await screen.findByText("numpy");
- const toggle = screen.getByRole("button", { name: "uv sandbox" });
+ const toggle = screen.getByRole("button", { name: /^uv sandbox, / });
expect(toggle).toHaveAttribute("aria-expanded", "false");
expect(
screen.queryByRole("region", { name: "Sandbox details" }),
@@ -164,7 +164,9 @@ it("restores a restart-required sync with the kernel restart action", async () =
})),
);
await screen.findByText("numpy");
- expect(screen.getByText("Sandbox restart required")).toBeVisible();
+ expect(
+ screen.getByRole("heading", { name: "Sandbox restart required" }),
+ ).toBeVisible();
expect(
screen.queryByRole("button", { name: "Retry sync" }),
).not.toBeInTheDocument();
@@ -194,7 +196,9 @@ it("restores a restart-required sync with the kernel restart action", async () =
},
})),
);
- expect(screen.getByText("Sandbox restart required")).toBeVisible();
+ expect(
+ screen.getByRole("heading", { name: "Sandbox restart required" }),
+ ).toBeVisible();
fireEvent.click(screen.getByRole("button", { name: "Restart Kernel" }));
expect(screen.getByRole("alertdialog")).toHaveTextContent("Restart Kernel");
expect(client.sendRestart).not.toHaveBeenCalled();
@@ -251,7 +255,7 @@ it("keeps sync output open through completion and restores it quietly after refr
unmount();
const refreshed = mount();
act(() => refreshed.store.set(alertAtom, snapshot));
- const toggle = screen.getByRole("button", { name: "uv sandbox" });
+ const toggle = screen.getByRole("button", { name: /^uv sandbox, / });
expect(toggle).toHaveAttribute("aria-expanded", "false");
fireEvent.click(toggle);
fireEvent.click(
@@ -266,7 +270,7 @@ it.each([false, true])(
"retains the progression after completion with inspecting=%s",
async (inspecting) => {
const { store, client } = mount({ preparing: true });
- const toggle = screen.getByRole("button", { name: "uv sandbox" });
+ const toggle = screen.getByRole("button", { name: /^uv sandbox, / });
expect(toggle).toHaveAttribute("aria-expanded", "true");
expect(client.getDependencyTree).not.toHaveBeenCalled();
if (inspecting) {
@@ -308,7 +312,7 @@ it.each([false, true])(
it("opens a startup error even after collapsing preparation and keeps both step outputs available", () => {
const { store } = mount({ preparing: true, backend: "pixi" });
- const toggle = screen.getByRole("button", { name: "pixi sandbox" });
+ const toggle = screen.getByRole("button", { name: /^pixi sandbox, / });
fireEvent.click(toggle);
act(() => {
store.set(startupProgressAtom, {
@@ -325,6 +329,7 @@ it("opens a startup error even after collapsing preparation and keeps both step
});
});
expect(toggle).toHaveAttribute("aria-expanded", "true");
+ expect(toggle).toHaveTextContent("pixi sandbox");
expect(within(toggle).getByRole("status")).toHaveAccessibleName(
"Kernel failed to start",
);
@@ -346,13 +351,80 @@ it("opens a startup error even after collapsing preparation and keeps both step
expect(screen.getByLabelText("Error details")).toBeVisible();
});
-it("does not add a toggle or startup details to an existing environment", async () => {
- mount({ backend: null });
+it.each(["uv", "pixi"] as const)(
+ "shows connection status and errors before the %s startup phase arrives",
+ (backend) => {
+ const { store } = mount({ backend, preparing: true });
+ act(() => store.set(connectionAtom, { state: WebSocketState.CONNECTING }));
+ const details = within(
+ screen.getByRole("region", { name: "Sandbox details" }),
+ );
+ expect(details.getByRole("status")).toHaveTextContent("Connecting…");
+ expect(details.queryByRole("list")).not.toBeInTheDocument();
+
+ act(() => {
+ store.set(kernelStartupErrorAtom, "Kernel process exited unexpectedly");
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ });
+ });
+ expect(details.getByRole("status")).toHaveTextContent(
+ "Kernel failed to start",
+ );
+ expect(details.getByLabelText("Error details")).toHaveTextContent(
+ "Kernel process exited unexpectedly",
+ );
+ expect(details.queryByRole("list")).not.toBeInTheDocument();
+ },
+);
+
+it("uses the same disclosure for an existing environment and updates it through connection changes", async () => {
+ const { store } = mount({ backend: null });
await screen.findByText("numpy");
- expect(
- screen.queryByRole("button", { name: /sandbox/ }),
- ).not.toBeInTheDocument();
- expect(
- screen.queryByRole("region", { name: "Sandbox details" }),
- ).not.toBeInTheDocument();
+ const toggle = screen.getByRole("button", { name: /^Runtime details, / });
+ expect(toggle).toHaveTextContent(/^Runtime$/);
+ expect(toggle).toHaveAccessibleName("Runtime details, Kernel ready");
+ expect(within(toggle).getByRole("status")).toHaveAccessibleName(
+ "Kernel ready",
+ );
+ expect(toggle).toHaveAttribute("aria-expanded", "false");
+ fireEvent.click(toggle);
+ const details = screen.getByRole("region", { name: "Runtime details" });
+ expect(toggle).toHaveAttribute("aria-controls", details.id);
+ expect(within(details).getByText("Kernel started")).toBeVisible();
+ expect(within(details).getAllByRole("listitem")).toHaveLength(1);
+ expect(within(details).queryByRole("button", { name: "Sync" })).toBeNull();
+
+ act(() => store.set(connectionAtom, { state: WebSocketState.CONNECTING }));
+ expect(toggle).toHaveTextContent(/^Runtime$/);
+ expect(within(toggle).getByRole("status")).toHaveAccessibleName(
+ "Connecting…",
+ );
+ expect(within(details).getByText("Starting kernel")).toBeVisible();
+ fireEvent.click(toggle);
+ expect(details).not.toBeVisible();
+ act(() =>
+ store.set(connectionAtom, {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ reason: "Kernel startup failed",
+ }),
+ );
+ expect(toggle).toHaveAttribute("aria-expanded", "true");
+ expect(toggle).toHaveTextContent(/^Runtime$/);
+ expect(within(toggle).getByRole("status")).toHaveAccessibleName(
+ "Kernel failed to start",
+ );
+ expect(details).toBeVisible();
+ expect(toggle).toHaveAccessibleName(
+ "Runtime details, Kernel failed to start",
+ );
+
+ act(() => store.set(connectionAtom, { state: WebSocketState.NOT_STARTED }));
+ expect(toggle).toHaveTextContent(/^Runtime$/);
+ expect(within(toggle).getByRole("status")).toHaveAccessibleName(
+ "Kernel not connected",
+ );
});
diff --git a/frontend/src/components/editor/chrome/panels/packages-panel.tsx b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
index ec2e932c97..acbfa05b8b 100644
--- a/frontend/src/components/editor/chrome/panels/packages-panel.tsx
+++ b/frontend/src/components/editor/chrome/panels/packages-panel.tsx
@@ -7,7 +7,6 @@ import {
HelpCircleIcon,
} from "lucide-react";
import React from "react";
-import { useConnectionNotice } from "@/core/network/useConnectionNotice";
import { useOpenSettingsToTab } from "@/components/app-config/state";
import { Spinner } from "@/components/icons/spinner";
import { SearchInput } from "@/components/ui/input";
@@ -26,7 +25,7 @@ import type {
DependencyTreeNode,
DependencyTreeResponse,
} from "@/core/network/types";
-import { sandboxAtom, sandboxSyncAtom } from "@/core/packages/sandbox-state";
+import { sandboxSyncAtom } from "@/core/packages/sandbox-state";
import { stripPackageManagerPrefix } from "@/core/packages/package-input-utils";
import { usePackageAction } from "@/core/packages/usePackageAction";
import { usePackageDependencies } from "@/core/packages/usePackageDependencies";
@@ -36,7 +35,7 @@ import { ErrorBanner } from "@/plugins/impl/common/error-banner";
import { cn } from "@/utils/cn";
import { copyToClipboard } from "@/utils/copy";
import { Events } from "@/utils/events";
-import { SandboxDetails } from "./sandbox-panel";
+import { RuntimeDetails } from "./runtime-panel";
import { PanelEmptyState } from "./empty-state";
import { PACKAGES_INPUT_ID, packagesToInstallAtom } from "./packages-utils";
@@ -69,33 +68,13 @@ const PackageActionButton: React.FC<{
};
const PackagesPanel: React.FC = () => {
- const sandbox = useAtomValue(sandboxAtom);
const connected = useAtomValue(isConnectedAtom);
- const notice = useConnectionNotice(0);
- if (sandbox?.backend) {
- return (
- <div className="flex flex-col flex-1 min-h-0 overflow-hidden">
- <SandboxDetails />
- {connected && <PackageContents />}
- </div>
- );
- }
- if (notice) {
- return (
- <div className="p-4 text-sm text-muted-foreground">
- <div className="flex items-center gap-2">
- {notice.pending && <Spinner className="size-3" />}
- {notice.title}
- </div>
- {notice.error && (
- <pre className="mt-3 text-xs whitespace-pre-wrap break-words max-h-52 overflow-auto">
- {notice.error}
- </pre>
- )}
- </div>
- );
- }
- return <PackageContents />;
+ return (
+ <div className="flex flex-col flex-1 min-h-0 overflow-hidden">
+ <RuntimeDetails />
+ {connected && <PackageContents />}
+ </div>
+ );
};
const PackageContents: React.FC = () => {
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-details-state.ts b/frontend/src/components/editor/chrome/panels/runtime-details-state.ts
similarity index 96%
rename from frontend/src/components/editor/chrome/panels/sandbox-details-state.ts
rename to frontend/src/components/editor/chrome/panels/runtime-details-state.ts
index 94be867893..7c3dd7a705 100644
--- a/frontend/src/components/editor/chrome/panels/sandbox-details-state.ts
+++ b/frontend/src/components/editor/chrome/panels/runtime-details-state.ts
@@ -17,7 +17,7 @@ const disclosureContextAtom = atom((get) => {
};
});
-export const sandboxDetailsExpandedAtom = atom(
+export const runtimeDetailsExpandedAtom = atom(
(get) => {
const context = get(disclosureContextAtom);
const preference = get(preferenceAtom);
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx b/frontend/src/components/editor/chrome/panels/runtime-panel.tsx
similarity index 67%
rename from frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
rename to frontend/src/components/editor/chrome/panels/runtime-panel.tsx
index f2e5f3f05c..f3186b06ce 100644
--- a/frontend/src/components/editor/chrome/panels/sandbox-panel.tsx
+++ b/frontend/src/components/editor/chrome/panels/runtime-panel.tsx
@@ -1,13 +1,13 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { useAtom, useAtomValue } from "jotai";
import { RefreshCwIcon } from "lucide-react";
-import { connectionNoticeAtom } from "@/core/network/connection-notice";
import { Button } from "@/components/ui/button";
import { useRestartKernel } from "@/components/editor/actions/useRestartKernel";
import {
isConnectedAtom,
startupProgressAtom,
} from "@/core/network/connection";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
import type { DisplayConnectionNotice } from "@/core/network/useConnectionNotice";
import {
preparationAtom,
@@ -17,25 +17,10 @@ import {
sandboxSyncOperationAtom,
} from "@/core/packages/sandbox-state";
import { cn } from "@/utils/cn";
-import { usePanelSection } from "./panel-context";
-import { sandboxDetailsExpandedAtom } from "./sandbox-details-state";
import { StartupOutput } from "../../alerts/startup-output";
-import {
- ConnectionStatusIcon,
- StartupProgress,
-} from "../../alerts/startup-progress";
-
-export function SandboxErrorOutput({ error }: { error: string }) {
- return (
- <pre
- tabIndex={0}
- aria-label="Error details"
- className="mt-3 p-3 rounded border bg-muted/30 text-xs text-muted-foreground whitespace-pre min-w-0 max-w-full max-h-52 overflow-auto"
- >
- {error}
- </pre>
- );
-}
+import { ConnectionDetails } from "../../alerts/connection-details";
+import { usePanelSection } from "./panel-context";
+import { runtimeDetailsExpandedAtom } from "./runtime-details-state";
function SandboxRecovery({ notice }: { notice: DisplayConnectionNotice }) {
const sandbox = useAtomValue(sandboxAtom);
@@ -46,8 +31,6 @@ function SandboxRecovery({ notice }: { notice: DisplayConnectionNotice }) {
}
return (
<>
- <p className="mt-2 text-foreground">{notice.description}</p>
- {notice.error && <SandboxErrorOutput error={notice.error} />}
<div className="flex items-center gap-2 mt-3">
<Button
variant="outline"
@@ -88,36 +71,11 @@ function SandboxRestart() {
);
}
-function SandboxStartupPanel({ notice }: { notice: DisplayConnectionNotice }) {
- const showSteps =
- notice.kind === "startup" &&
- (notice.ready ||
- notice.phase === "preparing-environment" ||
- notice.phase === "starting-kernel");
- return (
- <div className="min-w-0 text-sm">
- {showSteps ? (
- <StartupProgress notice={notice} surface="sidebar" />
- ) : (
- <div className="flex items-center gap-2" role="status">
- <ConnectionStatusIcon notice={notice} />
- <h2>{notice.title}</h2>
- </div>
- )}
- <SandboxRecovery notice={notice} />
- </div>
- );
-}
-
-function SandboxSyncStatus({ notice }: { notice: DisplayConnectionNotice }) {
+function RuntimeNoticeDetails({ notice }: { notice: DisplayConnectionNotice }) {
return (
- <div className="mb-5 text-sm">
- <output className="flex items-center gap-2 text-xs">
- <ConnectionStatusIcon notice={notice} />
- <span>{notice.title}</span>
- </output>
- <SandboxRecovery notice={notice} />
- </div>
+ <ConnectionDetails notice={notice}>
+ {notice.sandbox && <SandboxRecovery notice={notice} />}
+ </ConnectionDetails>
);
}
@@ -133,7 +91,9 @@ function SandboxSyncDetails({
return (
<div className="mt-5 min-w-0">
{notice ? (
- <SandboxSyncStatus notice={notice} />
+ <div className="mb-5">
+ <RuntimeNoticeDetails notice={notice} />
+ </div>
) : (
<p className="text-sm">Environment synced</p>
)}
@@ -153,20 +113,25 @@ function SandboxSyncDetails({
);
}
-export function SandboxDetails() {
+export function RuntimeDetails() {
const section = usePanelSection();
+ const sandbox = Boolean(useAtomValue(sandboxAtom)?.backend);
const connected = useAtomValue(isConnectedAtom);
- const notice = useAtomValue(connectionNoticeAtom);
+ const connectionNotice = useAtomValue(connectionNoticeAtom);
+ const notice: DisplayConnectionNotice | null = connectionNotice && {
+ ...connectionNotice,
+ ready: false,
+ };
const preparation = useAtomValue(preparationAtom);
const progress = useAtomValue(startupProgressAtom);
- const [expanded, setExpanded] = useAtom(sandboxDetailsExpandedAtom);
+ const [expanded, setExpanded] = useAtom(runtimeDetailsExpandedAtom);
const startup: DisplayConnectionNotice | null =
notice?.kind === "startup"
- ? { ...notice, ready: false }
- : preparation || progress
+ ? notice
+ : preparation || progress || (connected && !sandbox)
? {
kind: "startup",
- sandbox: true,
+ sandbox,
title: "Notebook started",
description: "The notebook is ready to run.",
pending: false,
@@ -176,8 +141,8 @@ export function SandboxDetails() {
: null;
return (
<section
- id={`sandbox-details-${section}`}
- aria-label="Sandbox details"
+ id={`runtime-details-${section}`}
+ aria-label={sandbox ? "Sandbox details" : "Runtime details"}
hidden={!expanded}
className={cn(
"min-w-0 overflow-auto p-4",
@@ -187,15 +152,22 @@ export function SandboxDetails() {
onFocusCapture={() => setExpanded(true)}
>
{notice?.kind === "connection" && (
- <SandboxSyncStatus notice={{ ...notice, ready: false }} />
+ <div className="mb-5">
+ <RuntimeNoticeDetails notice={notice} />
+ </div>
)}
- {startup && <SandboxStartupPanel notice={startup} />}
- {connected && (
- <SandboxSyncDetails
- notice={notice?.kind === "sync" ? { ...notice, ready: false } : null}
- />
+ {startup && <RuntimeNoticeDetails notice={startup} />}
+ {sandbox && connected && (
+ <SandboxSyncDetails notice={notice?.kind === "sync" ? notice : null} />
+ )}
+ {sandbox && connected && (!notice || notice.pending) && (
+ <SandboxActions />
+ )}
+ {!notice && !startup && !sandbox && (
+ <p className="text-sm text-muted-foreground">
+ Not connected to a runtime.
+ </p>
)}
- {connected && (!notice || notice.pending) && <SandboxActions />}
</section>
);
}
diff --git a/frontend/src/components/editor/chrome/panels/runtime-status-toggle.tsx b/frontend/src/components/editor/chrome/panels/runtime-status-toggle.tsx
new file mode 100644
index 0000000000..d55fceb876
--- /dev/null
+++ b/frontend/src/components/editor/chrome/panels/runtime-status-toggle.tsx
@@ -0,0 +1,56 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtom, useAtomValue } from "jotai";
+import { ChevronDownIcon } from "lucide-react";
+import {
+ ProgressStatusIcon,
+ type ProgressState,
+} from "@/components/ui/progress-stages";
+import { isConnectedAtom } from "@/core/network/connection";
+import { connectionNoticeAtom } from "@/core/network/connection-notice";
+import { sandboxAtom } from "@/core/packages/sandbox-state";
+import { cn } from "@/utils/cn";
+import type { PanelSection } from "./panel-context";
+import { runtimeDetailsExpandedAtom } from "./runtime-details-state";
+
+export function RuntimeStatusToggle({ section }: { section: PanelSection }) {
+ const sandbox = useAtomValue(sandboxAtom);
+ const notice = useAtomValue(connectionNoticeAtom);
+ const [expanded, setExpanded] = useAtom(runtimeDetailsExpandedAtom);
+ const connected = useAtomValue(isConnectedAtom);
+ const label = sandbox?.backend ? `${sandbox.backend} sandbox` : "Runtime";
+ const statusLabel =
+ notice?.title ?? (connected ? "Kernel ready" : "Kernel not connected");
+ const status: ProgressState = notice
+ ? notice.pending
+ ? "running"
+ : "failed"
+ : connected
+ ? "succeeded"
+ : "waiting";
+ return (
+ <button
+ type="button"
+ aria-label={`${sandbox?.backend ? label : "Runtime details"}, ${statusLabel}`}
+ aria-expanded={expanded}
+ aria-controls={`runtime-details-${section}`}
+ title={statusLabel}
+ className={cn(
+ "flex min-w-0 items-center gap-1.5 rounded px-1.5 py-1 text-xs whitespace-nowrap hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring",
+ status === "failed" ? "text-(--red-11)" : "text-foreground",
+ )}
+ onClick={() => setExpanded(!expanded)}
+ >
+ <ProgressStatusIcon state={status} variant="dot" />
+ <output aria-label={statusLabel} className="truncate">
+ {label}
+ </output>
+ <ChevronDownIcon
+ aria-hidden={true}
+ className={cn(
+ "size-3 shrink-0 text-muted-foreground",
+ expanded && "rotate-180",
+ )}
+ />
+ </button>
+ );
+}
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx b/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx
index 632ad232ae..23ea0554af 100644
--- a/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx
+++ b/frontend/src/components/editor/chrome/panels/sandbox-controller.tsx
@@ -14,7 +14,7 @@ import { useSandboxController } from "@/core/packages/useSandboxController";
import { LazyAnyLanguageCodeMirror } from "@/plugins/impl/code/LazyAnyLanguageCodeMirror";
import { useTheme } from "@/theme/useTheme";
import { Paths } from "@/utils/paths";
-import { SandboxErrorOutput } from "./sandbox-panel";
+import { ConnectionErrorOutput } from "../../alerts/connection-details";
export function SandboxController({
onReconnect,
@@ -64,7 +64,7 @@ export function SandboxController({
) : (
!error && <Spinner />
)}
- {diagnostic && <SandboxErrorOutput error={diagnostic} />}
+ {diagnostic && <ConnectionErrorOutput error={diagnostic} />}
{conflict && (
<Button variant="text" size="sm" onClick={loadManifest}>
Discard draft and reload manifest
diff --git a/frontend/src/components/editor/chrome/panels/sandbox-toggle.tsx b/frontend/src/components/editor/chrome/panels/sandbox-toggle.tsx
deleted file mode 100644
index a393ab8003..0000000000
--- a/frontend/src/components/editor/chrome/panels/sandbox-toggle.tsx
+++ /dev/null
@@ -1,52 +0,0 @@
-/* Copyright 2026 Marimo. All rights reserved. */
-import { useAtom, useAtomValue } from "jotai";
-import { ChevronDownIcon } from "lucide-react";
-import { connectionNoticeAtom } from "@/core/network/connection-notice";
-import { sandboxAtom } from "@/core/packages/sandbox-state";
-import { cn } from "@/utils/cn";
-import type { PanelSection } from "./panel-context";
-import { sandboxDetailsExpandedAtom } from "./sandbox-details-state";
-
-export function SandboxToggle({ section }: { section: PanelSection }) {
- const sandbox = useAtomValue(sandboxAtom);
- const notice = useAtomValue(connectionNoticeAtom);
- const [expanded, setExpanded] = useAtom(sandboxDetailsExpandedAtom);
- if (!sandbox?.backend) {
- return null;
- }
- const status = notice ? (notice.pending ? "pending" : "error") : "healthy";
- return (
- <button
- type="button"
- aria-label={`${sandbox.backend} sandbox`}
- aria-expanded={expanded}
- aria-controls={`sandbox-details-${section}`}
- title={notice?.title ?? "Sandbox details"}
- className={cn(
- "flex items-center gap-1.5 rounded px-1.5 py-1 text-xs whitespace-nowrap hover:bg-accent focus-visible:outline-2 focus-visible:outline-ring",
- status === "error" ? "text-(--red-11)" : "text-foreground",
- )}
- onClick={() => setExpanded(!expanded)}
- >
- <output
- aria-label={notice?.title ?? "Sandbox healthy"}
- className={cn(
- "size-1.5 shrink-0 rounded-full",
- status === "error"
- ? "bg-(--red-9)"
- : status === "pending"
- ? "bg-muted-foreground motion-safe:animate-pulse"
- : "bg-(--grass-9)",
- )}
- />
- {sandbox.backend} sandbox
- <ChevronDownIcon
- aria-hidden={true}
- className={cn(
- "size-3 shrink-0 text-muted-foreground",
- expanded && "rotate-180",
- )}
- />
- </button>
- );
-}
diff --git a/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx b/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
index ab46cdce53..d64b61ccfc 100644
--- a/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
+++ b/frontend/src/components/editor/chrome/wrapper/app-chrome.tsx
@@ -34,7 +34,7 @@ import { ErrorBoundary } from "../../boundary/ErrorBoundary";
import { raf2 } from "../../navigation/focus-utils";
import { ContextAwarePanel } from "../panels/context-aware-panel/context-aware-panel";
import { PanelSectionProvider } from "../panels/panel-context";
-import { SandboxToggle } from "../panels/sandbox-toggle";
+import { RuntimeStatusToggle } from "../panels/runtime-status-toggle";
import { useTheme } from "@/theme/useTheme";
import {
LazyAgentPanel,
@@ -391,7 +391,7 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
</span>
)}
{selectedPanel === "packages" && (
- <SandboxToggle section="sidebar" />
+ <RuntimeStatusToggle section="sidebar" />
)}
<Button
data-testid="close-helper-pane"
@@ -549,7 +549,7 @@ export const AppChrome: React.FC<PropsWithChildren> = ({ children }) => {
<LspStatus />
<div className="flex-1" />
{selectedDeveloperPanelTab === "packages" && (
- <SandboxToggle section="developer-panel" />
+ <RuntimeStatusToggle section="developer-panel" />
)}
<Button
size="xs"
diff --git a/frontend/src/components/ui/progress-stages.tsx b/frontend/src/components/ui/progress-stages.tsx
new file mode 100644
index 0000000000..47821d3fe8
--- /dev/null
+++ b/frontend/src/components/ui/progress-stages.tsx
@@ -0,0 +1,114 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { AlertCircleIcon, CheckIcon, CircleIcon } from "lucide-react";
+import type { ReactNode } from "react";
+import { Spinner } from "@/components/icons/spinner";
+import { cn } from "@/utils/cn";
+
+export type ProgressState = "waiting" | "running" | "succeeded" | "failed";
+
+export interface ProgressStage {
+ id: string;
+ state: ProgressState;
+ title: string;
+ description: string;
+ details?: ReactNode;
+}
+
+export function ProgressStatusIcon({
+ state,
+ variant = "icon",
+}: {
+ state: ProgressState;
+ variant?: "icon" | "dot";
+}) {
+ if (variant === "dot") {
+ return (
+ <span
+ aria-hidden={true}
+ className={cn(
+ "size-1.5 shrink-0 rounded-full",
+ {
+ waiting: "bg-muted-foreground",
+ running: "bg-muted-foreground motion-safe:animate-pulse",
+ succeeded: "bg-(--grass-9)",
+ failed: "bg-(--red-9)",
+ }[state],
+ )}
+ />
+ );
+ }
+ const Icon = {
+ waiting: CircleIcon,
+ running: Spinner,
+ succeeded: CheckIcon,
+ failed: AlertCircleIcon,
+ }[state];
+ return (
+ <Icon
+ aria-hidden={true}
+ className={cn(
+ "size-4 shrink-0",
+ {
+ waiting: "text-muted-foreground/50",
+ running: "motion-reduce:animate-none",
+ succeeded: "text-(--grass-11)",
+ failed: "text-(--red-11)",
+ }[state],
+ )}
+ />
+ );
+}
+
+export function ProgressStages({
+ stages,
+ label,
+ className,
+}: {
+ stages: readonly ProgressStage[];
+ label: string;
+ className?: string;
+}) {
+ return (
+ <ol aria-label={label} className={cn("space-y-6", className)}>
+ {stages.map((stage, index) => (
+ <li
+ key={stage.id}
+ aria-current={
+ stage.state === "running" || stage.state === "failed"
+ ? "step"
+ : undefined
+ }
+ className="relative flex items-start gap-3"
+ >
+ {index < stages.length - 1 && (
+ <span
+ aria-hidden={true}
+ className="absolute left-2 top-4.5 -bottom-6.5 border-l border-border"
+ />
+ )}
+ <span className="mt-0.5 text-muted-foreground">
+ <ProgressStatusIcon state={stage.state} />
+ </span>
+ <div className="min-w-0 flex-1">
+ <div
+ className={cn(
+ "text-sm",
+ stage.state === "failed"
+ ? "text-(--red-11)"
+ : stage.state === "waiting"
+ ? "text-muted-foreground"
+ : "text-foreground",
+ )}
+ >
+ {stage.title}
+ </div>
+ <p className="mt-1 text-xs text-muted-foreground">
+ {stage.description}
+ </p>
+ {stage.details}
+ </div>
+ </li>
+ ))}
+ </ol>
+ );
+}
diff --git a/frontend/src/core/edit-app.tsx b/frontend/src/core/edit-app.tsx
index bbf5085d8f..67e070cf48 100644
--- a/frontend/src/core/edit-app.tsx
+++ b/frontend/src/core/edit-app.tsx
@@ -197,7 +197,11 @@ export const EditApp: React.FC<AppProps> = ({
)}
</div>
- <ConnectionNotice appConfig={appConfig} onRetry={reconnect} />
+ <ConnectionNotice
+ appConfig={appConfig}
+ onRetry={reconnect}
+ canOpenPackages={!hideControls}
+ />
{/* Don't render until we have a single cell. NotStartedConnectionAlert
still covers the "no remote runtime started" prompt. */}
diff --git a/frontend/src/core/network/connection-notice.ts b/frontend/src/core/network/connection-notice.ts
index f25f4602f5..82ef049ea8 100644
--- a/frontend/src/core/network/connection-notice.ts
+++ b/frontend/src/core/network/connection-notice.ts
@@ -92,7 +92,7 @@ export const connectionNoticeAtom = atom<ConnectionNotice | null>((get) => {
const startupFailed =
connection.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR;
const environmentFailed =
- startupFailed && connection.phase === "preparing-environment";
+ sandbox && startupFailed && connection.phase === "preparing-environment";
return {
kind: startupFailed ? "startup" : "connection",
phase: connection.phase,
diff --git a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
index 550211f036..d98e8160d5 100644
--- a/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
+++ b/frontend/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx
@@ -322,14 +322,6 @@ describe("connection notice", () => {
);
act(() => vi.advanceTimersByTime(35_000));
expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
- act(() =>
- store.set(
- notebookAtom,
- MockNotebook.notebookState({
- cellData: { [cellId("test")]: { code: "answer = 42" } },
- }),
- ),
- );
send({
op: "startup-progress",
phase: "starting-kernel",
@@ -338,6 +330,18 @@ describe("connection notice", () => {
});
expect(screen.getByRole("status")).toHaveTextContent("Starting kernel");
expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
+ act(() =>
+ store.set(
+ notebookAtom,
+ MockNotebook.notebookState({
+ cellData: { [cellId("test")]: { code: "answer = 42" } },
+ }),
+ ),
+ );
+ expect(
+ screen.getByRole("button", { name: "Starting kernel… Open Packages" }),
+ ).toBeVisible();
+ expect(screen.queryByText(/Elapsed/)).not.toBeInTheDocument();
send({ op: "reconnected" });
expect(
screen.queryByRole("region", { name: "Notebook startup" }),
@@ -429,12 +433,9 @@ describe("connection notice", () => {
).not.toBeInTheDocument();
});
- it.each([
- ["preparing-environment", "Sandbox setup failed"],
- ["starting-kernel", "Kernel failed to start"],
- ] as const)(
+ it.each(["preparing-environment", "starting-kernel"] as const)(
"keeps a %s failure available until the user retries",
- async (phase, title) => {
+ async (phase) => {
const { store, transport, options, send } = renderNotice();
send({ op: "startup-progress", phase, logs: "", log_mode: "replace" });
const error = "A full diagnostic\nwith <stderr> details";
@@ -445,9 +446,13 @@ describe("connection notice", () => {
new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),
),
);
- expect(screen.getByRole("status")).toHaveTextContent(title);
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Kernel failed to start",
+ );
act(() => vi.advanceTimersByTime(30_000));
- expect(screen.getByRole("status")).toHaveTextContent(title);
+ expect(screen.getByRole("status")).toHaveTextContent(
+ "Kernel failed to start",
+ );
expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {
normalizeWhitespace: false,
});
diff --git a/frontend/src/stories/progress-stages.stories.tsx b/frontend/src/stories/progress-stages.stories.tsx
new file mode 100644
index 0000000000..be32b757e3
--- /dev/null
+++ b/frontend/src/stories/progress-stages.stories.tsx
@@ -0,0 +1,62 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import {
+ ProgressStages,
+ type ProgressState,
+} from "@/components/ui/progress-stages";
+
+function ProgressStagesStory({
+ state,
+ completedStage,
+}: {
+ state: ProgressState;
+ completedStage: boolean;
+}) {
+ return (
+ <div className="w-80 space-y-6">
+ <p className="text-sm text-muted-foreground">
+ Isolated stage styling. For the actual notebook and sidebar, use the
+ walkthroughs under Runtime.
+ </p>
+ <ProgressStages
+ label="Example stages"
+ stages={[
+ ...(completedStage
+ ? [
+ {
+ id: "previous",
+ state: "succeeded" as const,
+ title: "Previous stage",
+ description: "This stage has finished.",
+ },
+ ]
+ : []),
+ {
+ id: "current",
+ state,
+ title: "Current stage",
+ description: "Change the state using the Storybook controls.",
+ },
+ ]}
+ />
+ </div>
+ );
+}
+
+const meta = {
+ title: "UI Primitives/ProgressStages",
+ component: ProgressStagesStory,
+ parameters: { layout: "centered" },
+ args: { state: "running", completedStage: true },
+ argTypes: {
+ state: {
+ control: "radio",
+ options: ["waiting", "running", "succeeded", "failed"],
+ },
+ },
+} satisfies Meta<typeof ProgressStagesStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const MultipleStages: Story = {};
+export const SingleStage: Story = { args: { completedStage: false } };
diff --git a/frontend/src/stories/runtime-existing.stories.tsx b/frontend/src/stories/runtime-existing.stories.tsx
new file mode 100644
index 0000000000..ca346aa7bb
--- /dev/null
+++ b/frontend/src/stories/runtime-existing.stories.tsx
@@ -0,0 +1,44 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type RuntimeStory, runtimeStoryMeta } from "./runtime-story";
+
+const meta = {
+ ...runtimeStoryMeta,
+ title: "Runtime/Existing environment",
+ args: { ...runtimeStoryMeta.args, backend: null, phase: "starting" },
+} satisfies Meta<typeof RuntimeStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Walkthrough: Story = {
+ name: "Walkthrough",
+ args: { manual: true, detailsOpen: true },
+};
+export const NotebookConnecting: Story = {
+ name: "Notebook — connecting",
+ args: {},
+};
+export const NotebookFailed: Story = {
+ name: "Notebook — failure and retry",
+ args: { phase: "failed" },
+};
+export const EmptyNotebook: Story = {
+ name: "Empty notebook — connecting",
+ args: { existingCells: false },
+};
+export const DetailsConnecting: Story = {
+ name: "Sidebar — connecting",
+ args: { surface: "packages" },
+};
+export const DetailsFailed: Story = {
+ name: "Sidebar — failure details",
+ args: { surface: "packages", phase: "failed" },
+};
+export const Ready: Story = {
+ name: "Sidebar — ready",
+ args: { surface: "packages", phase: "ready" },
+};
+export const Completion: Story = {
+ name: "Automatic completion",
+ args: { interactive: true },
+};
diff --git a/frontend/src/stories/runtime-maintenance.stories.tsx b/frontend/src/stories/runtime-maintenance.stories.tsx
new file mode 100644
index 0000000000..4f7c52deda
--- /dev/null
+++ b/frontend/src/stories/runtime-maintenance.stories.tsx
@@ -0,0 +1,40 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type RuntimeStory, runtimeStoryMeta } from "./runtime-story";
+
+const meta = {
+ ...runtimeStoryMeta,
+ title: "Runtime/Sandbox maintenance",
+ args: { ...runtimeStoryMeta.args, backend: "uv", surface: "packages" },
+} satisfies Meta<typeof RuntimeStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Syncing: Story = {
+ name: "Sync — in progress",
+ args: { phase: "syncing" },
+};
+export const SyncFailed: Story = {
+ name: "Sync — failed",
+ args: { phase: "sync-failed" },
+};
+export const Synced: Story = {
+ name: "Sync — completed",
+ args: { phase: "synced" },
+};
+export const RestartRequired: Story = {
+ name: "Sync — restart required",
+ args: { phase: "restart-required" },
+};
+export const ManifestEditor: Story = {
+ name: "Manifest — edit",
+ args: { surface: "manifest", phase: "failed" },
+};
+export const ManifestSyncFailed: Story = {
+ name: "Manifest — sync failed",
+ args: { surface: "manifest", phase: "failed", saveResult: "failure" },
+};
+export const ManifestChanged: Story = {
+ name: "Manifest — changed on disk",
+ args: { surface: "manifest", phase: "failed", saveResult: "stale" },
+};
diff --git a/frontend/src/stories/runtime-pixi.stories.tsx b/frontend/src/stories/runtime-pixi.stories.tsx
new file mode 100644
index 0000000000..1ece9870d6
--- /dev/null
+++ b/frontend/src/stories/runtime-pixi.stories.tsx
@@ -0,0 +1,28 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type RuntimeStory, runtimeStoryMeta } from "./runtime-story";
+
+const meta = {
+ ...runtimeStoryMeta,
+ title: "Runtime/pixi sandbox",
+ args: { ...runtimeStoryMeta.args, backend: "pixi" },
+} satisfies Meta<typeof RuntimeStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Walkthrough: Story = {
+ name: "Walkthrough",
+ args: { manual: true, detailsOpen: true },
+};
+export const Ready: Story = {
+ name: "Sidebar — ready",
+ args: { surface: "packages", phase: "ready" },
+};
+export const Completion: Story = {
+ name: "Notebook — automatic completion",
+ args: { interactive: true },
+};
+export const EmptyCompletion: Story = {
+ name: "Empty notebook — automatic completion",
+ args: { interactive: true, existingCells: false },
+};
diff --git a/frontend/src/stories/sandbox.stories.tsx b/frontend/src/stories/runtime-story.tsx
similarity index 61%
rename from frontend/src/stories/sandbox.stories.tsx
rename to frontend/src/stories/runtime-story.tsx
index d84bc2ab3d..6e995ac850 100644
--- a/frontend/src/stories/sandbox.stories.tsx
+++ b/frontend/src/stories/runtime-story.tsx
@@ -1,11 +1,12 @@
/* Copyright 2026 Marimo. All rights reserved. */
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { createStore, Provider, useAtomValue } from "jotai";
+import type { Meta } from "@storybook/react-vite";
+import { createStore, Provider, useAtomValue, useStore } from "jotai";
import { useEffect, useRef, useState } from "react";
+import { Button } from "@/components/ui/button";
import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
import PackagesPanel from "@/components/editor/chrome/panels/packages-panel";
import { PanelSectionProvider } from "@/components/editor/chrome/panels/panel-context";
-import { SandboxToggle } from "@/components/editor/chrome/panels/sandbox-toggle";
+import { RuntimeStatusToggle } from "@/components/editor/chrome/panels/runtime-status-toggle";
import { SandboxController } from "@/components/editor/chrome/panels/sandbox-controller";
import { chromeAtom } from "@/components/editor/chrome/state";
import { Cell } from "@/components/editor/notebook-cell";
@@ -70,13 +71,15 @@ interface Props {
| "synced"
| "restart-required";
existingCells: boolean;
- backend: "uv" | "pixi";
+ backend: "uv" | "pixi" | null;
saveResult: "success" | "failure" | "stale";
theme: "light" | "dark";
interactive: boolean;
+ manual: boolean;
+ detailsOpen: boolean;
}
-function SandboxPreview({
+function RuntimePreview({
props,
appConfig,
reconnect,
@@ -99,7 +102,7 @@ function SandboxPreview({
<aside className="flex flex-col w-[300px] shrink-0 border-r h-[520px]">
<div className="flex items-center justify-between px-3 py-2 border-b text-sm">
Packages
- <SandboxToggle section="sidebar" />
+ <RuntimeStatusToggle section="sidebar" />
</div>
<PanelSectionProvider value="sidebar">
<PackagesPanel />
@@ -130,6 +133,85 @@ function SandboxPreview({
);
}
+function LifecycleControls({ backend }: { backend: Props["backend"] }) {
+ const store = useStore();
+ const [position, setPosition] = useState(0);
+ const phases = backend
+ ? (["preparing", "starting", "failed", "retrying", "ready"] as const)
+ : (["starting", "failed", "retrying", "ready"] as const);
+ const next = phases[(position + 1) % phases.length];
+ const labels = {
+ preparing: "Restart walkthrough",
+ starting: "Start kernel",
+ failed: "Simulate kernel failure",
+ retrying: "Retry kernel",
+ ready: "Kernel connected",
+ };
+ const advance = () => {
+ setPosition((position + 1) % phases.length);
+ store.set(
+ kernelStartupErrorAtom,
+ next === "failed" ? "The kernel process exited before connecting." : null,
+ );
+ store.set(
+ connectionAtom,
+ next === "ready"
+ ? { state: WebSocketState.OPEN }
+ : next === "failed"
+ ? {
+ state: WebSocketState.CLOSED,
+ code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
+ phase: "starting-kernel",
+ reason: "Kernel failed to start",
+ }
+ : {
+ state: WebSocketState.CONNECTING,
+ phase:
+ next === "preparing"
+ ? "preparing-environment"
+ : "starting-kernel",
+ },
+ );
+ store.set(startupProgressAtom, {
+ phase: next === "preparing" ? "preparing-environment" : "starting-kernel",
+ logs:
+ next === "failed"
+ ? "Kernel process exited\n"
+ : next === "ready"
+ ? "Kernel connected\n"
+ : "Launching kernel process\n",
+ log_mode: "replace",
+ });
+ store.set(alertAtom, (value) => ({
+ ...value,
+ environments: {
+ ...value.environments,
+ kernel: {
+ ...value.environments.kernel,
+ operations: value.environments.kernel.operations.map((operation) => ({
+ ...operation,
+ status:
+ next === "preparing"
+ ? { kind: "running" }
+ : { kind: "succeeded" },
+ })),
+ },
+ },
+ }));
+ };
+ return (
+ <div className="mb-4 flex items-center gap-3 text-xs text-muted-foreground">
+ <Button variant="outline" size="xs" onClick={advance}>
+ {labels[next]}
+ </Button>
+ <span>
+ Story controls — advance the actual app through startup, failure, retry,
+ and completion.
+ </span>
+ </div>
+ );
+}
+
function OpenManifest() {
const actions = useAtomValue(sandboxActionsAtom);
const opened = useRef(false);
@@ -142,7 +224,7 @@ function OpenManifest() {
return null;
}
-function SandboxStory(props: Props) {
+export function RuntimeStory(props: Props) {
const [store] = useState(() => {
const state = createStore();
let currentManifest =
@@ -162,7 +244,7 @@ function SandboxStory(props: Props) {
});
state.set(chromeAtom, {
selectedPanel: "packages",
- isSidebarOpen: props.surface !== "notebook",
+ isSidebarOpen: props.surface !== "notebook" || props.detailsOpen,
isDeveloperPanelOpen: false,
selectedDeveloperPanelTab: "errors",
});
@@ -171,23 +253,28 @@ function SandboxStory(props: Props) {
props.phase === "preparing" || props.phase === "starting"
? {
state: WebSocketState.CONNECTING,
- phase:
- props.phase === "preparing"
+ phase: props.backend
+ ? props.phase === "preparing"
? "preparing-environment"
- : "starting-kernel",
+ : "starting-kernel"
+ : undefined,
}
: props.phase === "failed"
? {
state: WebSocketState.CLOSED,
code: WebSocketClosedReason.KERNEL_STARTUP_ERROR,
reason: "Kernel startup failed",
- phase: "preparing-environment",
+ phase: props.backend ? "preparing-environment" : undefined,
}
: { state: WebSocketState.OPEN },
);
state.set(
kernelStartupErrorAtom,
- props.phase === "failed" ? resolutionError : null,
+ props.phase === "failed"
+ ? props.backend
+ ? resolutionError
+ : "Python kernel exited before connecting.\nModuleNotFoundError: No module named 'ipykernel'"
+ : null,
);
const syncStatus: EnvironmentOperation["status"] | null =
props.phase === "syncing"
@@ -209,53 +296,56 @@ function SandboxStory(props: Props) {
...value.environments,
kernel: {
restart_required: props.phase === "restart-required",
- operations: [
- {
- operation_id: "story-preparation",
- action: "prepare",
- source: "kernel",
- status:
- props.phase === "failed"
- ? { kind: "failed", error: resolutionError }
- : props.phase === "preparing"
- ? { kind: "running" }
- : { kind: "succeeded" },
- packages: {},
- logs: {
- environment:
- props.phase === "failed"
- ? resolutionError
- : preparationOutput,
- },
- },
- ...(syncStatus
- ? [
- {
- operation_id: "story-sync",
- action: "sync" as const,
- source: "kernel" as const,
- status: syncStatus,
- packages: {},
- logs: {
- environment:
- "Reading notebook manifest\nResolving dependencies\nChecking Python version\n",
- },
+ operations: props.backend
+ ? [
+ {
+ operation_id: "story-preparation",
+ action: "prepare",
+ source: "kernel",
+ status:
+ props.phase === "failed"
+ ? { kind: "failed", error: resolutionError }
+ : props.phase === "preparing"
+ ? { kind: "running" }
+ : { kind: "succeeded" },
+ packages: {},
+ logs: {
+ environment:
+ props.phase === "failed"
+ ? resolutionError
+ : preparationOutput,
},
- ]
- : []),
- ],
+ },
+ ...(syncStatus
+ ? [
+ {
+ operation_id: "story-sync",
+ action: "sync" as const,
+ source: "kernel" as const,
+ status: syncStatus,
+ packages: {},
+ logs: {
+ environment:
+ "Reading notebook manifest\nResolving dependencies\nChecking Python version\n",
+ },
+ },
+ ]
+ : []),
+ ]
+ : [],
},
},
}));
+ const preparingEnvironment =
+ props.backend &&
+ (props.phase === "preparing" || props.phase === "failed");
state.set(startupProgressAtom, {
- phase:
- props.phase !== "preparing" && props.phase !== "failed"
- ? "starting-kernel"
- : "preparing-environment",
- logs:
- props.phase !== "preparing" && props.phase !== "failed"
- ? "Launching kernel process\nUsing /home/user/.cache/uv/environments-v2/bike-trips-a274bddc/bin/python\nWaiting for kernel connection\n"
- : "",
+ phase: preparingEnvironment ? "preparing-environment" : "starting-kernel",
+ logs: preparingEnvironment
+ ? ""
+ : props.backend
+ ? "Launching kernel process\nWaiting for kernel connection\n"
+ : "Launching kernel process\nConnecting to Python runtime\nWaiting for kernel connection\n",
log_mode: "replace",
});
if (props.existingCells) {
@@ -276,8 +366,16 @@ function SandboxStory(props: Props) {
manifest: currentManifest,
filename: "bike_trips.py",
}),
+ getPackageList: async () => ({
+ packages: [
+ { name: "marimo", version: "0.24.2" },
+ { name: "polars", version: "1.34.0" },
+ ],
+ }),
getDependencyTree: async () => ({
- context: { kind: "sandbox", backend: props.backend },
+ context: props.backend
+ ? { kind: "sandbox", backend: props.backend }
+ : { kind: "package-manager", name: "pip" },
tree: {
name: "<root>",
version: null,
@@ -374,7 +472,29 @@ function SandboxStory(props: Props) {
<Provider store={store}>
<SandboxController onReconnect={reconnect} />
{props.surface === "manifest" && <OpenManifest />}
- <SandboxPreview
+ <header className="mb-4 max-w-2xl space-y-1">
+ <h1 className="text-base font-medium">
+ {props.backend
+ ? `${props.backend} sandbox environment`
+ : "Existing Python environment"}
+ </h1>
+ <p className="text-sm text-muted-foreground">
+ {props.backend
+ ? "marimo prepares this notebook’s isolated environment, then starts its kernel. The button keeps the sandbox name while its status dot and details change."
+ : "Python is already available, so only the kernel needs to connect. The button stays labeled Runtime; there is no sandbox preparation stage."}
+ </p>
+ <p className="text-xs text-muted-foreground">
+ {props.surface === "packages"
+ ? "Packages sidebar."
+ : props.surface === "manifest"
+ ? "Sandbox manifest editor."
+ : props.existingCells
+ ? "Notebook with existing cells: inline status opens Packages for stages and logs."
+ : "Empty notebook: startup stages appear in the notebook until the kernel connects."}
+ </p>
+ </header>
+ {props.manual && <LifecycleControls backend={props.backend} />}
+ <RuntimePreview
props={props}
appConfig={appConfig}
reconnect={reconnect}
@@ -383,9 +503,8 @@ function SandboxStory(props: Props) {
);
}
-const meta = {
- title: "Sandbox/States",
- component: SandboxStory,
+export const runtimeStoryMeta = {
+ component: RuntimeStory,
parameters: { layout: "centered" },
args: {
surface: "notebook",
@@ -395,94 +514,14 @@ const meta = {
saveResult: "success",
theme: "light",
interactive: false,
+ manual: false,
+ detailsOpen: false,
},
render: (args, context) => (
- <SandboxStory
+ <RuntimeStory
key={JSON.stringify([args, context.globals.theme])}
{...args}
theme={context.globals.theme === "dark" ? "dark" : "light"}
/>
),
-} satisfies Meta<typeof SandboxStory>;
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const ExistingNotebookPreparing: Story = {
- name: "Startup notice / preparing",
-};
-export const EmptyNotebookPreparing: Story = {
- name: "Empty notebook / preparing",
- args: { existingCells: false },
-};
-export const StartingKernel: Story = {
- name: "Startup notice / starting kernel",
- args: { phase: "starting" },
-};
-export const StartupTransition: Story = {
- name: "Startup / completion transition",
- args: { interactive: true, backend: "pixi" },
-};
-export const EmptyStartupTransition: Story = {
- name: "Empty notebook / completion transition",
- args: { interactive: true, existingCells: false, backend: "pixi" },
-};
-export const ExistingNotebookFailed: Story = {
- name: "Startup notice / failed",
- args: { phase: "failed" },
-};
-export const EmptyNotebookFailed: Story = {
- name: "Empty notebook / failed",
- args: { phase: "failed", existingCells: false },
-};
-export const PackagesPreparing: Story = {
- name: "Setup details / preparing",
- args: { surface: "packages" },
-};
-export const PackagesStarting: Story = {
- name: "Setup details / starting kernel",
- args: { surface: "packages", phase: "starting" },
-};
-export const PackagesStartupTransition: Story = {
- name: "Setup details / live output",
- args: { surface: "packages", interactive: true },
-};
-export const PackagesFailed: Story = {
- name: "Setup details / failed",
- args: { surface: "packages", phase: "failed" },
-};
-export const PackagesReady: Story = {
- name: "Status row / ready",
- args: { surface: "packages", phase: "ready" },
-};
-export const PackagesSyncing: Story = {
- name: "Status row / syncing",
- args: { surface: "packages", phase: "syncing" },
-};
-export const PackagesSyncFailed: Story = {
- name: "Setup details / sync failed",
- args: { surface: "packages", phase: "sync-failed" },
-};
-export const PackagesSynced: Story = {
- name: "Setup details / sync completed",
- args: { surface: "packages", phase: "synced" },
-};
-export const PackagesRestartRequired: Story = {
- name: "Setup details / restart required",
- args: { surface: "packages", phase: "restart-required" },
-};
-export const PixiPackagesReady: Story = {
- name: "Status row / pixi",
- args: { surface: "packages", phase: "ready", backend: "pixi" },
-};
-export const ManifestEditor: Story = {
- name: "Manifest / edit",
- args: { surface: "manifest", phase: "failed" },
-};
-export const ManifestSyncFails: Story = {
- name: "Manifest / failed save",
- args: { surface: "manifest", phase: "failed", saveResult: "failure" },
-};
-export const ManifestChangedOnDisk: Story = {
- name: "Manifest / changed on disk",
- args: { surface: "manifest", phase: "failed", saveResult: "stale" },
-};
+} satisfies Meta<typeof RuntimeStory>;
diff --git a/frontend/src/stories/runtime-uv.stories.tsx b/frontend/src/stories/runtime-uv.stories.tsx
new file mode 100644
index 0000000000..8d0e206b36
--- /dev/null
+++ b/frontend/src/stories/runtime-uv.stories.tsx
@@ -0,0 +1,56 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { type RuntimeStory, runtimeStoryMeta } from "./runtime-story";
+
+const meta = {
+ ...runtimeStoryMeta,
+ title: "Runtime/uv sandbox",
+ args: { ...runtimeStoryMeta.args, backend: "uv" },
+} satisfies Meta<typeof RuntimeStory>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Walkthrough: Story = {
+ name: "Walkthrough",
+ args: { manual: true, detailsOpen: true },
+};
+export const NotebookPreparing: Story = {
+ name: "Notebook — preparing environment",
+ args: {},
+};
+export const NotebookStarting: Story = {
+ name: "Notebook — starting kernel",
+ args: { phase: "starting" },
+};
+export const NotebookFailed: Story = {
+ name: "Notebook — setup failed",
+ args: { phase: "failed" },
+};
+export const EmptyNotebook: Story = {
+ name: "Empty notebook — preparing",
+ args: { existingCells: false },
+};
+export const EmptyNotebookFailed: Story = {
+ name: "Empty notebook — setup failed",
+ args: { existingCells: false, phase: "failed" },
+};
+export const DetailsPreparing: Story = {
+ name: "Sidebar — preparing environment",
+ args: { surface: "packages" },
+};
+export const DetailsStarting: Story = {
+ name: "Sidebar — starting kernel",
+ args: { surface: "packages", phase: "starting" },
+};
+export const DetailsFailed: Story = {
+ name: "Sidebar — setup failed",
+ args: { surface: "packages", phase: "failed" },
+};
+export const Ready: Story = {
+ name: "Sidebar — ready",
+ args: { surface: "packages", phase: "ready" },
+};
+export const LiveOutput: Story = {
+ name: "Sidebar — live output",
+ args: { surface: "packages", interactive: true },
+};