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

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]);
 

package/src/mount.tsx

@@ -10,6 +10,7 @@ import {
   userConfigAtom,
 } from "@/core/config/config";
 import { KnownQueryParams } from "@/core/constants";
+import { pairPreviewAtom, pairPreviewSchema } from "@/core/config/pair";
 import { getFilenameFromDOM } from "@/core/dom/htmlUtils";
 import { getMarimoCode } from "@/core/meta/globals";
 import {
@@ -208,6 +209,7 @@ const mountOptionsSchema = z.object({
    * marimo config overrides
    */
   configOverrides: passthroughObject,
+  pairPreview: pairPreviewSchema.optional(),
   /**
    * marimo app config
    */
@@ -345,6 +347,7 @@ function initStore(options: unknown) {
   );
   store.set(userConfigAtom, parseUserConfig(parsedOptions.data.config));
   store.set(appConfigAtom, parseAppConfig(parsedOptions.data.appConfig));
+  store.set(pairPreviewAtom, parsedOptions.data.pairPreview);
 
   // Runtime config
   if (parsedOptions.data.runtimeConfig.length > 0) {

package/src/plugins/core/BadPlugin.tsx

@@ -9,21 +9,15 @@ const AccordionTrigger = AccordionPrimitive.Trigger;
 
 import type { JSX } from "react";
 import { ZodError } from "zod";
-import { EmotionCacheProvider } from "@/components/editor/output/EmotionCacheProvider";
 import { JsonOutput } from "@/components/editor/output/JsonOutput";
 import { Alert, AlertTitle } from "../../components/ui/alert";
 
 interface Props {
   error: ZodError | Error;
-  shadowRoot: ShadowRoot | null;
   badData: Record<string, unknown>;
 }
 
-export const BadPluginData: React.FC<Props> = ({
-  error,
-  badData,
-  shadowRoot,
-}) => {
+export const BadPluginData: React.FC<Props> = ({ error, badData }) => {
   if (error instanceof ZodError) {
     return (
       <Alert variant="destructive">
@@ -49,9 +43,7 @@ export const BadPluginData: React.FC<Props> = ({
               View Data:
             </AccordionTrigger>
             <AccordionContent className="text-[0.84375rem]">
-              <EmotionCacheProvider container={shadowRoot}>
-                <JsonOutput data={badData} />
-              </EmotionCacheProvider>
+              <JsonOutput data={badData} />
             </AccordionContent>
           </AccordionItem>
         </Accordion>
@@ -65,9 +57,6 @@ export const BadPluginData: React.FC<Props> = ({
 export function renderError(
   error: ZodError | Error,
   badData: Record<string, unknown>,
-  shadowRoot: ShadowRoot | null,
 ): JSX.Element {
-  return (
-    <BadPluginData error={error} badData={badData} shadowRoot={shadowRoot} />
-  );
+  return <BadPluginData error={error} badData={badData} />;
 }

package/src/plugins/core/RenderHTML.tsx

@@ -262,9 +262,29 @@ const wrapTooltipTargets: TransformFn = (
     if (tagName.startsWith("marimo-")) {
       return undefined;
     }
-    const tooltipContent = domNode.attribs["data-tooltip"];
+    const tooltipContent = domNode.attribs["data-tooltip"].replace(
+      /^[\r\n]+|[\r\n]+$/g,
+      "",
+    );
     return (
-      <Tooltip content={tooltipContent}>{reactNode as JSX.Element}</Tooltip>
+      <Tooltip
+        content={
+          tooltipContent.includes("\n") ? (
+            <span className="whitespace-pre-wrap">
+              {tooltipContent.split(/\r?\n/).map((line, i) => (
+                <React.Fragment key={i}>
+                  {i > 0 && <br />}
+                  {line}
+                </React.Fragment>
+              ))}
+            </span>
+          ) : (
+            tooltipContent
+          )
+        }
+      >
+        {reactNode as JSX.Element}
+      </Tooltip>
     );
   }
 };