@marimo-team/islands 0.24.3-dev5 → 0.24.3-dev50

package/src/core/packages/__tests__/useSandboxController.test.tsx

@@ -0,0 +1,165 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { Provider } from "jotai";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
+import { kernelStartupErrorAtom } from "@/core/errors/state";
+import { connectionAtom } from "@/core/network/connection";
+import { requestClientAtom } from "@/core/network/requests";
+import type {
+  SandboxResponse,
+  SyncSandboxResponse,
+} from "@/core/network/types";
+import { filenameAtom } from "@/core/saving/file-state";
+import { store } from "@/core/state/jotai";
+import { WebSocketState } from "@/core/websocket/types";
+import { HTTPError } from "@/utils/errors";
+import { packageDataVersionAtom } from "../package-data";
+import {
+  sandboxActionsAtom,
+  sandboxAtom,
+  sandboxSyncAtom,
+} from "../sandbox-state";
+import { useSandboxController } from "../useSandboxController";
+
+vi.mock("../toast-components", () => ({
+  showPackageRestartToast: vi.fn(),
+  showSandboxSyncToast: vi.fn(),
+}));
+
+const manifest = 'dependencies = ["numpy"]';
+const sandbox: SandboxResponse = {
+  backend: "uv",
+  manifest,
+  filename: "notebook.py",
+};
+
+beforeEach(() => {
+  store.set(sandboxAtom, null);
+  store.set(sandboxSyncAtom, { pending: false, error: null });
+  store.set(sandboxActionsAtom, null);
+  store.set(connectionAtom, { state: WebSocketState.OPEN });
+  store.set(kernelStartupErrorAtom, null);
+  store.set(filenameAtom, "notebook.py");
+  store.set(packageDataVersionAtom, 0);
+});
+
+function setup() {
+  const client = MockRequestClient.create({
+    getSandbox: vi.fn().mockResolvedValue(sandbox),
+    updateManifest: vi.fn(async ({ contents }) => ({
+      ...sandbox,
+      manifest: contents,
+    })),
+    syncSandbox: vi.fn().mockResolvedValue({ success: true, reconnect: false }),
+  });
+  store.set(requestClientAtom, client);
+  const reconnect = vi.fn<() => Promise<void>>().mockResolvedValue(undefined);
+  return {
+    client,
+    reconnect,
+    ...renderHook(() => useSandboxController(reconnect), {
+      wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
+    }),
+  };
+}
+
+describe("useSandboxController", () => {
+  it("keeps a conflicting draft across closing and only discards it on explicit reload", async () => {
+    const { result, client } = setup();
+    vi.mocked(client.updateManifest).mockRejectedValue(
+      new HTTPError(409, "Conflict", { detail: "Manifest changed on disk" }),
+    );
+    await act(async () => {
+      await store.get(sandboxActionsAtom)?.editManifest();
+    });
+    act(() => result.current.setDraft("dependencies = []"));
+    await act(async () => {
+      await result.current.saveAndSync();
+    });
+    expect(client.updateManifest).toHaveBeenCalledExactlyOnceWith({
+      fileKey: "notebook.py",
+      previous: manifest,
+      contents: "dependencies = []",
+    });
+    expect(result.current).toMatchObject({
+      open: true,
+      draft: "dependencies = []",
+      dirty: true,
+      conflict: true,
+      diagnostic: "Manifest changed on disk",
+      pending: false,
+    });
+    expect(client.syncSandbox).not.toHaveBeenCalled();
+    act(() => result.current.setOpen(false));
+    await act(async () => {
+      await store.get(sandboxActionsAtom)?.editManifest();
+    });
+    expect(result.current.draft).toBe("dependencies = []");
+    await act(async () => {
+      await result.current.loadManifest();
+    });
+    expect(result.current).toMatchObject({
+      draft: manifest,
+      dirty: false,
+      conflict: false,
+      diagnostic: null,
+    });
+  });
+
+  it("shares sync progress across callers and refreshes packages without reconnecting", async () => {
+    const { client, reconnect } = setup();
+    const { promise, resolve } = Promise.withResolvers<SyncSandboxResponse>();
+    vi.mocked(client.syncSandbox).mockReturnValue(promise);
+    const actions = store.get(sandboxActionsAtom)!;
+    let pending: Promise<boolean>;
+    act(() => {
+      pending = actions.sync();
+    });
+    expect(store.get(sandboxSyncAtom)).toEqual({ pending: true, error: null });
+    await act(async () => {
+      expect(await actions.sync()).toBe(false);
+    });
+    expect(client.syncSandbox).toHaveBeenCalledTimes(1);
+    await act(async () => {
+      resolve({ success: true, reconnect: false });
+      expect(await pending).toBe(true);
+    });
+    expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });
+    expect(store.get(packageDataVersionAtom)).toBe(1);
+    expect(reconnect).not.toHaveBeenCalled();
+  });
+
+  it("reports sync failure and clears it when retrying", async () => {
+    const { client } = setup();
+    const actions = store.get(sandboxActionsAtom)!;
+    vi.mocked(client.syncSandbox).mockRejectedValueOnce(new Error("offline"));
+    await act(async () => {
+      expect(await actions.sync()).toBe(false);
+    });
+    expect(store.get(sandboxSyncAtom)).toEqual({
+      pending: false,
+      error: "offline",
+    });
+    await act(async () => {
+      expect(await actions.sync()).toBe(true);
+    });
+    expect(store.get(sandboxSyncAtom)).toEqual({ pending: false, error: null });
+  });
+
+  it("ignores stale metadata after a filename change and unregisters actions on unmount", async () => {
+    const { client, unmount } = setup();
+    await waitFor(() => expect(store.get(sandboxAtom)).toEqual(sandbox));
+    const { promise, resolve } = Promise.withResolvers<SandboxResponse>();
+    vi.mocked(client.getSandbox).mockReturnValueOnce(promise);
+    act(() => store.set(filenameAtom, "old.py"));
+    const current = { ...sandbox, filename: "current.py" };
+    vi.mocked(client.getSandbox).mockResolvedValue(current);
+    act(() => store.set(filenameAtom, "current.py"));
+    await waitFor(() => expect(store.get(sandboxAtom)).toEqual(current));
+    await act(async () => resolve({ ...sandbox, filename: "old.py" }));
+    expect(store.get(sandboxAtom)).toEqual(current);
+    unmount();
+    expect(store.get(sandboxActionsAtom)).toBeNull();
+  });
+});

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/runtime/__tests__/runtime.test.ts

@@ -276,6 +276,17 @@ describe("RuntimeManager", () => {
   });
 
   describe("getTerminalWsURL", () => {
+    it("should include dimensions in the terminal handshake", () => {
+      const runtime = new RuntimeManager(mockConfig);
+      const url = runtime.getTerminalWsURL({ rows: 30, cols: 140 });
+
+      expect(Object.fromEntries(url.searchParams)).toEqual({
+        access_token: "test-token",
+        rows: "30",
+        cols: "140",
+      });
+    });
+
     it("should return terminal WebSocket URL", () => {
       const runtime = new RuntimeManager(mockConfig);
       const url = runtime.getTerminalWsURL();

package/src/core/runtime/runtime.ts

@@ -183,8 +183,13 @@ export class RuntimeManager {
   /**
    * The WebSocket URL of the terminal.
    */
-  getTerminalWsURL(): URL {
-    return this.formatWsURL("/terminal/ws");
+  getTerminalWsURL(size?: { rows: number; cols: number }): URL {
+    const url = this.formatWsURL("/terminal/ws");
+    if (size) {
+      url.searchParams.set("rows", String(size.rows));
+      url.searchParams.set("cols", String(size.cols));
+    }
+    return url;
   }
 
   /**

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 {