@marimo-team/islands 0.24.3-dev4 → 0.24.3-dev41

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 {

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/transports/transport.ts

@@ -15,7 +15,7 @@ export type ConnectionTransportCallback<T extends ConnectionEvent> = (
 export interface IConnectionTransport {
   reconnect(code?: number | undefined, reason?: string | undefined): void;
   close(): void;
-  send(data: string | ArrayBuffer | Blob | ArrayBufferView): void;
+  send(data: string | ArrayBuffer | Blob | ArrayBufferView<ArrayBuffer>): void;
   addEventListener<T extends ConnectionEvent>(
     event: T,
     callback: ConnectionTransportCallback<T>,

package/src/core/websocket/transports/ws.ts

@@ -42,7 +42,7 @@ export class WsTransport implements IConnectionTransport {
     this.inner.close();
   }
 
-  send(data: string | ArrayBuffer | Blob | ArrayBufferView): void {
+  send(data: string | ArrayBuffer | Blob | ArrayBufferView<ArrayBuffer>): void {
     this.inner.send(data);
   }
 

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;

package/src/core/websocket/useMarimoKernelConnection.tsx

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import { invalidatePackageData } from "@/core/packages/package-data";
 import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { useRef } from "react";
 import { useErrorBoundary } from "react-error-boundary";
@@ -240,7 +241,15 @@ export function useMarimoKernelConnection(opts: {
       case "reload":
         reloadSafe();
         return;
+      case "startup-progress":
+        setConnection({
+          state: WebSocketState.CONNECTING,
+          phase: msg.data.phase,
+        });
+        return;
       case "kernel-ready": {
+        setKernelStartupError(null);
+        setConnection({ state: WebSocketState.OPEN });
         setInitialRunCompleted(
           Boolean(msg.data.resumed || msg.data.auto_instantiated),
         );
@@ -363,6 +372,16 @@ export function useMarimoKernelConnection(opts: {
         });
         return;
       case "installing-package-alert":
+        if (
+          msg.data.source !== "server" &&
+          msg.data.log_status !== "append" &&
+          msg.data.log_status !== "start" &&
+          Object.values(msg.data.packages).some(
+            (status) => status === "installed" || status === "restart-required",
+          )
+        ) {
+          invalidatePackageData();
+        }
         addPackageAlert({
           ...msg.data,
           kind: "installing",
@@ -439,6 +458,8 @@ export function useMarimoKernelConnection(opts: {
         return;
 
       case "reconnected":
+        setKernelStartupError(null);
+        setConnection({ state: WebSocketState.OPEN });
         return;
 
       case "focus-cell":
@@ -482,6 +503,7 @@ export function useMarimoKernelConnection(opts: {
       return;
     }
     shouldTryReconnecting.current = true;
+    setKernelStartupError(null);
     setConnection({ state: WebSocketState.CONNECTING });
     const healthy = await runtimeManager.reconcileFromHealth();
     if (!healthy) {
@@ -513,17 +535,11 @@ export function useMarimoKernelConnection(opts: {
     headers: () => runtimeManager.headers(),
 
     /**
-     * Open callback. Set the connection status to open.
+     * The transport is open; kernel-ready establishes session readiness.
      */
     onOpen: async () => {
       // If we are open, we can reset our reconnecting flag.
       shouldTryReconnecting.current = true;
-
-      // DO NOT COMMIT THIS UNCOMMENTED
-      // Uncomment to emulate a slow connection
-      // await new Promise((resolve) => setTimeout(resolve, 10_000));
-
-      setConnection({ state: WebSocketState.OPEN });
     },
 
     /**
@@ -565,7 +581,26 @@ export function useMarimoKernelConnection(opts: {
     onClose: (e) => {
       Logger.warn("WebSocket closed", e.code, e.reason);
       const decision = classifyCloseEvent(e);
-      setConnection(decision.status);
+      setConnection((previous) => {
+        const status = decision.status;
+        if (
+          status.state === WebSocketState.CLOSED &&
+          status.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR &&
+          (previous.state === WebSocketState.CONNECTING ||
+            previous.state === WebSocketState.CLOSED)
+        ) {
+          return { ...status, phase: previous.phase };
+        }
+        if (
+          status.state === WebSocketState.CONNECTING &&
+          (previous.state === WebSocketState.OPEN ||
+            (previous.state === WebSocketState.CONNECTING &&
+              previous.phase === "reconnecting"))
+        ) {
+          return { ...status, phase: "reconnecting" };
+        }
+        return status;
+      });
       if (decision.kind === "terminal" && decision.closeTransport) {
         ws.close(); // close to prevent reconnecting
         return;

package/src/css/app/Cell.css

@@ -82,6 +82,7 @@
     .console-output-area {
       max-height: 610px;
       overflow: auto;
+      overscroll-behavior: contain;
     }
 
     /* Special case for particular components */
@@ -521,6 +522,7 @@
   display: flow-root;
 
   overflow: auto;
+  overscroll-behavior: contain;
 }
 
 .marimo-output-stale,

package/src/hooks/useDebounce.ts

@@ -48,6 +48,8 @@ export function useDebounceControlledState<T>(opts: {
 
   // Handle external changes:
   useEffect(() => {
+    // TODO: Replace this synchronization with a controlled-state primitive.
+    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the debounced draft when the controlled value changes.
     setInternalValue(initialValue);
   }, [initialValue]);