@marimo-team/islands 0.24.3-dev37 → 0.24.3-dev39

package/src/core/packages/package-data.ts

@@ -0,0 +1,35 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import type {
+  EditRequests,
+  PackageOperationResponse,
+  RunRequests,
+} from "@/core/network/types";
+import { store } from "@/core/state/jotai";
+
+export const packageDataVersionAtom = atom(0);
+export function invalidatePackageData() {
+  store.set(packageDataVersionAtom, (version) => version + 1);
+}
+
+/** Refresh package consumers regardless of which UI initiated a mutation. */
+export function withPackageInvalidation(
+  client: EditRequests & RunRequests,
+): EditRequests & RunRequests {
+  function invalidateAfter<Request, Response extends PackageOperationResponse>(
+    request: (body: Request) => Promise<Response>,
+  ) {
+    return async (body: Request) => {
+      const result = await request(body);
+      if (result.success || result.restartRequired) {
+        invalidatePackageData();
+      }
+      return result;
+    };
+  }
+  return {
+    ...client,
+    addPackage: invalidateAfter(client.addPackage),
+    removePackage: invalidateAfter(client.removePackage),
+  };
+}

package/src/core/packages/sandbox-state.ts

@@ -0,0 +1,15 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { atom } from "jotai";
+import type { SandboxResponse } from "@/core/network/types";
+
+export const sandboxAtom = atom<SandboxResponse | null>(null);
+export const sandboxSyncAtom = atom<{ pending: boolean; error: string | null }>(
+  {
+    pending: false,
+    error: null,
+  },
+);
+export const sandboxActionsAtom = atom<{
+  sync: () => Promise<boolean>;
+  editManifest: () => Promise<void>;
+} | null>(null);

package/src/core/packages/toast-components.tsx

@@ -29,6 +29,17 @@ export const showPackageRestartToast = () => {
   });
 };
 
+export const showSandboxSyncToast = () => {
+  toast({
+    title: "Sandbox environment synced",
+    description: (
+      <div className="text-xs text-muted-foreground">
+        Some Python packages may require a kernel restart to see changes.
+      </div>
+    ),
+  });
+};
+
 export const showAddPackageToast = (
   packageName: string | string[],
   error?: string | null,

package/src/core/packages/useInstallPackage.ts

@@ -37,10 +37,10 @@ export function useInstallPackages(): {
         showPackageRestartToast();
       } else if (response.success) {
         showAddPackageToast(packages);
+        onSuccess?.();
       } else {
         showAddPackageToast(packages, response.error);
       }
-      onSuccess?.();
     } catch (error) {
       Logger.error(error);
     } finally {

package/src/core/packages/usePackageAction.ts

@@ -0,0 +1,51 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useRef, useState } from "react";
+import useEvent from "react-use-event-hook";
+import { useRequestClient } from "@/core/network/requests";
+import type { DependencyTreeNode } from "@/core/network/types";
+import { prettyError } from "@/utils/errors";
+import {
+  showPackageRestartToast,
+  showRemovePackageToast,
+  showUpgradePackageToast,
+} from "./toast-components";
+
+/** Shared mutation lifecycle for package actions in both list and tree views. */
+export function usePackageAction(
+  action: "upgrade" | "remove",
+  packageName: string,
+  tags?: DependencyTreeNode["tags"],
+) {
+  const { addPackage, removePackage } = useRequestClient();
+  const [loading, setLoading] = useState(false);
+  const inFlight = useRef(false);
+  const run = useEvent(async () => {
+    if (inFlight.current) {
+      return;
+    }
+    inFlight.current = true;
+    setLoading(true);
+    const showResult =
+      action === "upgrade" ? showUpgradePackageToast : showRemovePackageToast;
+    try {
+      const group = tags?.find((tag) => tag.kind === "group")?.value;
+      const request = { package: packageName, group };
+      const response = await (action === "upgrade"
+        ? addPackage({ ...request, upgrade: true })
+        : removePackage(request));
+      if (response.restartRequired) {
+        showPackageRestartToast();
+      } else if (response.success) {
+        showResult(packageName);
+      } else {
+        showResult(packageName, response.error || "Package operation failed.");
+      }
+    } catch (error) {
+      showResult(packageName, prettyError(error));
+    } finally {
+      inFlight.current = false;
+      setLoading(false);
+    }
+  });
+  return { loading, run };
+}

package/src/core/packages/usePackageDependencies.ts

@@ -0,0 +1,22 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtomValue } from "jotai";
+import { useResolvedMarimoConfig } from "@/core/config/config";
+import { useRequestClient } from "@/core/network/requests";
+import { useAsyncData } from "@/hooks/useAsyncData";
+import { packageDataVersionAtom } from "./package-data";
+
+/** Load the available package views and refresh them after package mutations. */
+export function usePackageDependencies() {
+  const packageDataVersion = useAtomValue(packageDataVersionAtom);
+  const [config] = useResolvedMarimoConfig();
+  const packageManager = config.package_management.manager;
+  const { getDependencyTree, getPackageList } = useRequestClient();
+
+  return useAsyncData(async () => {
+    const { context, tree } = await getDependencyTree();
+    // Both sandbox endpoints inspect the same environment; only fetch it once.
+    const list =
+      context.kind === "sandbox" ? [] : (await getPackageList()).packages;
+    return { list, context, tree };
+  }, [getDependencyTree, getPackageList, packageManager, packageDataVersion]);
+}

package/src/core/packages/useSandboxController.ts

@@ -0,0 +1,188 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { useAtom, useAtomValue, useSetAtom } from "jotai";
+import { useEffect, useRef, useState } from "react";
+import useEvent from "react-use-event-hook";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom } from "@/core/network/connection";
+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 { WebSocketState } from "@/core/websocket/types";
+import { HTTPError, prettyError } from "@/utils/errors";
+import { invalidatePackageData } from "./package-data";
+import {
+  sandboxActionsAtom,
+  sandboxAtom,
+  sandboxSyncAtom,
+} from "./sandbox-state";
+import {
+  showPackageRestartToast,
+  showSandboxSyncToast,
+} from "./toast-components";
+
+/** Mount once with the editor so manifest drafts survive closing Packages. */
+export function useSandboxController(onReconnect: () => Promise<void>) {
+  const requests = useRequestClient();
+  const filename = useFilename();
+  const connection = useAtomValue(connectionAtom);
+  const startupError = useAtomValue(kernelStartupErrorAtom);
+  const setSandbox = useSetAtom(sandboxAtom);
+  const [operation, setOperation] = useAtom(sandboxSyncAtom);
+  const setActions = useSetAtom(sandboxActionsAtom);
+  const [open, setOpen] = useState(false);
+  const [document, setDocument] = useState<{
+    original: string;
+    draft: string;
+  } | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [loading, setLoading] = useState(false);
+  const [conflict, setConflict] = useState(false);
+  const inFlight = useRef(false);
+  const dirty = document !== null && document.original !== document.draft;
+
+  useEffect(() => {
+    if (isWasm()) {
+      return;
+    }
+    let cancelled = false;
+    requests
+      .getSandbox({ fileKey: filename })
+      .then((value) => {
+        if (!cancelled) {
+          setSandbox(value);
+        }
+      })
+      .catch(() => {
+        /* A connection error is already shown by the editor. */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [requests, filename, connection.state, setSandbox]);
+
+  const sync = useEvent(async () => {
+    if (inFlight.current || connection.state === WebSocketState.CONNECTING) {
+      return false;
+    }
+    inFlight.current = true;
+    setOperation((value) => ({ ...value, pending: true, error: null }));
+    try {
+      const result = await requests.syncSandbox({ fileKey: filename });
+      if (result.restartRequired) {
+        showPackageRestartToast();
+      }
+      if (!result.success) {
+        throw new Error(result.error ?? "Sandbox sync failed.");
+      }
+      if (result.reconnect) {
+        await onReconnect();
+        const status = await waitFor(
+          connectionAtom,
+          (value) =>
+            value.state === WebSocketState.OPEN ||
+            value.state === WebSocketState.CLOSED,
+        );
+        if (status.state === WebSocketState.CLOSED) {
+          return false;
+        }
+      }
+      if (!result.reconnect) {
+        invalidatePackageData();
+      }
+      showSandboxSyncToast();
+      return true;
+    } catch (cause) {
+      setOperation((value) => ({ ...value, error: prettyError(cause) }));
+      return false;
+    } finally {
+      inFlight.current = false;
+      setOperation((value) => ({ ...value, pending: false }));
+    }
+  });
+
+  const loadManifest = useEvent(async () => {
+    setLoading(true);
+    setError(null);
+    setConflict(false);
+    try {
+      const result = await requests.getSandbox({ fileKey: filename });
+      setSandbox(result);
+      if (result.manifest === null) {
+        throw new Error("No notebook manifest is available yet.");
+      }
+      setDocument({ original: result.manifest, draft: result.manifest });
+    } catch (cause) {
+      setError(prettyError(cause));
+    } finally {
+      setLoading(false);
+    }
+  });
+
+  const editManifest = useEvent(async () => {
+    setOpen(true);
+    if (!dirty) {
+      await loadManifest();
+    }
+  });
+
+  useEffect(() => {
+    setActions({ sync, editManifest });
+    return () => {
+      setActions(null);
+    };
+  }, [sync, editManifest, setActions]);
+
+  const saveAndSync = async () => {
+    if (!document || loading || saving || operation.pending) {
+      return;
+    }
+    setSaving(true);
+    setError(null);
+    try {
+      if (dirty) {
+        const result = await requests.updateManifest({
+          fileKey: filename,
+          contents: document.draft,
+          previous: document.original,
+        });
+        setSandbox(result);
+        if (result.manifest !== null) {
+          setDocument({ original: result.manifest, draft: result.manifest });
+        }
+      }
+      if (await sync()) {
+        setOpen(false);
+      }
+    } catch (cause) {
+      setError(prettyError(cause));
+      setConflict(cause instanceof HTTPError && cause.status === 409);
+    } finally {
+      setSaving(false);
+    }
+  };
+  const pending =
+    saving ||
+    loading ||
+    operation.pending ||
+    connection.state === WebSocketState.CONNECTING;
+  const diagnostic = error ?? operation.error ?? startupError;
+  return {
+    filename,
+    open,
+    setOpen,
+    draft: document?.draft ?? null,
+    setDraft: (draft: string) =>
+      setDocument((value) => value && { ...value, draft }),
+    dirty,
+    loading,
+    saving,
+    pending,
+    error,
+    diagnostic,
+    conflict,
+    loadManifest,
+    saveAndSync,
+  };
+}

package/src/core/run-app.tsx

@@ -3,6 +3,7 @@
 import { atom, useAtomValue } from "jotai";
 import { ArrowLeftIcon } from "lucide-react";
 import { useEffect } from "react";
+import { KernelStartupErrorModal } from "@/components/editor/KernelStartupErrorModal";
 import { AppContainer } from "@/components/editor/app-container";
 import { AppHeader } from "@/components/editor/header/app-header";
 import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";
@@ -78,6 +79,7 @@ export const RunApp: React.FC<AppProps> = ({ appConfig, hideHeader }) => {
       width={appConfig.width}
       onReconnect={reconnect}
     >
+      <KernelStartupErrorModal />
       <AppHeader
         connection={connection}
         className={hideHeader ? "hidden" : "sm:pt-8"}

package/src/core/wasm/bridge.ts

@@ -640,6 +640,17 @@ export class PyodideBridge implements RunRequests, EditRequests {
     return response;
   };
 
+  getSandbox: EditRequests["getSandbox"] = async () => ({
+    backend: null,
+    manifest: null,
+    filename: null,
+  });
+  updateManifest: EditRequests["updateManifest"] = async () => {
+    throw new Error("Sandboxes are not supported in WebAssembly");
+  };
+  syncSandbox: EditRequests["syncSandbox"] = async () => {
+    throw new Error("Sandboxes are not supported in WebAssembly");
+  };
   getDependencyTree: EditRequests["getDependencyTree"] = async () => {
     // WASM doesn't support dependency trees yet
     return {

package/src/core/websocket/__tests__/useMarimoKernelConnection.hook.test.tsx

@@ -1,11 +1,25 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 // @vitest-environment jsdom
 
-import { act, renderHook } from "@testing-library/react";
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+} from "@testing-library/react";
 import { createStore, Provider as JotaiProvider } from "jotai";
 import type React from "react";
 import { ErrorBoundary } from "react-error-boundary";
-import { beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from "vitest";
 
 vi.mock("@/core/websocket/useWebSocket", async () => {
   const actual =
@@ -26,6 +40,13 @@ vi.mock("@/core/runtime/config", async () => {
   };
 });
 
+import { MockNotebook } from "@/__mocks__/notebook";
+import { cellId } from "@/__tests__/branded";
+import { notebookAtom } from "@/core/cells/cells";
+import { AppConfigSchema } from "@/core/config/config-schema";
+import { ConnectionNotice } from "@/components/editor/alerts/connection-notice";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import type { NotificationPayload } from "@/core/kernel/messages";
 import { useRuntimeManager } from "@/core/runtime/config";
 import { initialRunCompletedAtom } from "../../kernel/state";
 import { connectionAtom } from "../../network/connection";
@@ -188,3 +209,192 @@ describe("useMarimoKernelConnection messages", () => {
     expect(store.get(initialRunCompletedAtom)).toBe(true);
   });
 });
+
+it.each(["kernel-ready", "reconnected"])(
+  "waits for %s before marking the session connected",
+  async (op) => {
+    const store = createStore();
+    store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+    vi.mocked(useConnectionTransport).mockClear();
+    vi.mocked(useConnectionTransport).mockReturnValue(
+      makeTransport(WebSocket.OPEN),
+    );
+    vi.mocked(useRuntimeManager).mockReturnValue(
+      makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+    );
+    renderConnectionHook(store);
+    const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+
+    await act(async () => {
+      await options.onOpen(new Event("open"));
+    });
+    expect(store.get(connectionAtom).state).toBe(WebSocketState.CONNECTING);
+
+    act(() => {
+      options.onMessage(
+        new MessageEvent("message", {
+          data: JSON.stringify({
+            op,
+            data: {
+              op,
+              cell_ids: [],
+              codes: [],
+              names: [],
+              configs: [],
+              layout: null,
+              resumed: true,
+              ui_values: {},
+              last_executed_code: {},
+              last_execution_time: {},
+              app_config: { width: "normal" },
+              kiosk: false,
+              capabilities: { terminal: false },
+              auto_instantiated: false,
+              consumer_capabilities: { edit: true, interact: true },
+            },
+          }),
+        }),
+      );
+    });
+    expect(store.get(connectionAtom).state).toBe(WebSocketState.OPEN);
+  },
+);
+
+describe("connection notice", () => {
+  beforeEach(() => vi.useFakeTimers());
+  afterEach(() => vi.useRealTimers());
+
+  function renderNotice() {
+    const store = createStore();
+    store.set(connectionAtom, { state: WebSocketState.CONNECTING });
+    const transport = makeTransport(WebSocket.OPEN);
+    vi.mocked(useConnectionTransport).mockReturnValue(transport);
+    vi.mocked(useRuntimeManager).mockReturnValue(
+      makeRuntimeManager() as unknown as ReturnType<typeof useRuntimeManager>,
+    );
+    const Connection = () => {
+      const { reconnect } = useMarimoKernelConnection({
+        sessionId: "test-session" as SessionId,
+        autoInstantiate: false,
+        setCells: () => {},
+      });
+      return (
+        <ConnectionNotice
+          appConfig={AppConfigSchema.parse({})}
+          onRetry={reconnect}
+        />
+      );
+    };
+    render(
+      <JotaiProvider store={store}>
+        <ErrorBoundary fallback={null}>
+          <Connection />
+        </ErrorBoundary>
+      </JotaiProvider>,
+    );
+    const options = vi.mocked(useConnectionTransport).mock.calls.at(-1)![0];
+    const send = (data: NotificationPayload["data"]) =>
+      act(() => {
+        options.onMessage(
+          new MessageEvent("message", {
+            data: JSON.stringify({ op: data.op, data }),
+          }),
+        );
+      });
+    return { store, transport, options, send };
+  }
+
+  it("keeps elapsed time across startup phases and leaves reconnection to the footer once cells are available", () => {
+    const { store, options, send } = renderNotice();
+    send({ op: "startup-progress", phase: "preparing-environment" });
+    expect(
+      screen.queryByRole("region", { name: "Notebook startup" }),
+    ).not.toBeInTheDocument();
+    act(() => vi.advanceTimersByTime(500));
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "Preparing environment",
+    );
+    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" });
+    expect(screen.getByRole("status")).toHaveTextContent("Starting notebook");
+    expect(screen.getByText("Elapsed 35s")).toBeInTheDocument();
+    send({ op: "reconnected" });
+    expect(
+      screen.queryByRole("region", { name: "Notebook startup" }),
+    ).not.toBeInTheDocument();
+    act(() => options.onClose(new CloseEvent("close")));
+    act(() => vi.advanceTimersByTime(500));
+    expect(store.get(connectionAtom)).toEqual({
+      state: WebSocketState.CONNECTING,
+      phase: "reconnecting",
+    });
+    expect(
+      screen.queryByRole("region", { name: "Notebook startup" }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("does not flash a notice when startup finishes within the delay", () => {
+    const { send } = renderNotice();
+    send({ op: "startup-progress", phase: "preparing-environment" });
+    act(() => vi.advanceTimersByTime(200));
+    send({ op: "startup-progress", phase: "starting-kernel" });
+    act(() => vi.advanceTimersByTime(200));
+    expect(
+      screen.queryByRole("region", { name: "Notebook startup" }),
+    ).not.toBeInTheDocument();
+    send({ op: "reconnected" });
+    act(() => vi.advanceTimersByTime(500));
+    expect(
+      screen.queryByRole("region", { name: "Notebook startup" }),
+    ).not.toBeInTheDocument();
+  });
+
+  it.each([
+    ["preparing-environment", "Sandbox setup failed"],
+    ["starting-kernel", "Kernel failed to start"],
+  ] as const)(
+    "keeps a %s failure available until the user retries",
+    async (phase, title) => {
+      const { store, transport, options, send } = renderNotice();
+      send({ op: "startup-progress", phase });
+      const error = "A full diagnostic\nwith <stderr> details";
+      send({ op: "kernel-startup-error", error });
+      transport.readyState = WebSocket.CLOSED;
+      act(() =>
+        options.onClose(
+          new CloseEvent("close", { reason: "MARIMO_KERNEL_STARTUP_ERROR" }),
+        ),
+      );
+      expect(screen.getByRole("status")).toHaveTextContent(title);
+      act(() => vi.advanceTimersByTime(30_000));
+      expect(screen.getByRole("status")).toHaveTextContent(title);
+      expect(screen.getByLabelText("Error details")).toHaveTextContent(error, {
+        normalizeWhitespace: false,
+      });
+      expect(transport.reconnect).not.toHaveBeenCalled();
+      await act(async () =>
+        fireEvent.click(screen.getByRole("button", { name: "Try again" })),
+      );
+      expect(transport.reconnect).toHaveBeenCalledOnce();
+      expect(store.get(kernelStartupErrorAtom)).toBeNull();
+      expect(
+        screen.queryByRole("button", { name: "Try again" }),
+      ).not.toBeInTheDocument();
+      send({ op: "startup-progress", phase: "preparing-environment" });
+      act(() => vi.advanceTimersByTime(500));
+      expect(screen.getByRole("status")).toHaveTextContent(
+        "Preparing environment",
+      );
+      expect(screen.getByText("Elapsed 0s")).toBeInTheDocument();
+    },
+  );
+});

package/src/core/websocket/types.ts

@@ -1,5 +1,11 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import type { NotificationMessageData } from "../kernel/messages";
+
+type ConnectionPhase =
+  | NotificationMessageData<"startup-progress">["phase"]
+  | "reconnecting";
+
 // TODO: rename to ConnectionState
 export const WebSocketState = {
   NOT_STARTED: "NOT_STARTED",
@@ -28,10 +34,14 @@ export type ConnectionStatus =
        * Human-readable reason for closing the connection.
        */
       reason: string;
+      phase?: ConnectionPhase;
+    }
+  | {
+      state: typeof WebSocketState.CONNECTING;
+      phase?: ConnectionPhase;
     }
   | {
       state:
-        | typeof WebSocketState.CONNECTING
         | typeof WebSocketState.OPEN
         | typeof WebSocketState.CLOSING
         | typeof WebSocketState.NOT_STARTED;