@marimo-team/islands 0.23.14-dev9 → 0.23.15-dev0

package/src/core/network/__tests__/api.test.ts

@@ -1,6 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HTTPError } from "@/utils/errors";
 import { API } from "../api";
 
 // Mock fetch globally
@@ -77,4 +78,20 @@ describe("API", () => {
       expect.objectContaining({ method: "POST" }),
     );
   });
+
+  it("openapi-client error rejects with HTTPError carrying the status", async () => {
+    const body = { detail: "This connection is read-only for this action." };
+    await expect(
+      API.handleResponseReturnNull({
+        error: body,
+        response: { status: 403, statusText: "Forbidden" } as Response,
+      }),
+    ).rejects.toMatchObject({ status: 403, cause: body });
+    await expect(
+      API.handleResponseReturnNull({
+        error: body,
+        response: { status: 403, statusText: "Forbidden" } as Response,
+      }),
+    ).rejects.toBeInstanceOf(HTTPError);
+  });
 });

package/src/core/network/__tests__/requests-toasting.test.tsx

@@ -0,0 +1,46 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { HTTPError } from "@/utils/errors";
+
+const toastMock = vi.fn();
+vi.mock("@/components/ui/use-toast", () => ({
+  toast: (...args: unknown[]) => toastMock(...args),
+}));
+
+import { createErrorToastingRequests } from "../requests-toasting";
+import type { EditRequests, RunRequests } from "../types";
+
+function requestsThatReject(error: unknown): EditRequests & RunRequests {
+  return createErrorToastingRequests({
+    sendRun: vi.fn().mockRejectedValue(error),
+  } as unknown as EditRequests & RunRequests);
+}
+
+describe("createErrorToastingRequests", () => {
+  beforeEach(() => {
+    toastMock.mockClear();
+  });
+
+  it("suppresses the error toast for a capability 403", async () => {
+    const requests = requestsThatReject(
+      new HTTPError(403, "Forbidden", {
+        detail: "This connection is read-only for this action.",
+      }),
+    );
+    await expect(requests.sendRun({} as never)).rejects.toBeInstanceOf(
+      HTTPError,
+    );
+    expect(toastMock).not.toHaveBeenCalled();
+  });
+
+  it("shows a danger toast for other request errors", async () => {
+    const requests = requestsThatReject(new HTTPError(500, "Server Error"));
+    await expect(requests.sendRun({} as never)).rejects.toBeInstanceOf(
+      HTTPError,
+    );
+    expect(toastMock).toHaveBeenCalledWith(
+      expect.objectContaining({ variant: "danger" }),
+    );
+  });
+});

package/src/core/network/api.ts

@@ -1,6 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { createMarimoClient } from "@marimo-team/marimo-api";
+import { HTTPError } from "../../utils/errors";
 import { Logger } from "../../utils/Logger";
 import { Strings } from "../../utils/strings";
 import { getRuntimeManager } from "../runtime/config";
@@ -50,7 +51,7 @@ export const API = {
           const errorBody = isJson
             ? await response.json()
             : await response.text();
-          throw new Error(response.statusText, { cause: errorBody });
+          throw new HTTPError(response.status, response.statusText, errorBody);
         }
         if (isJson) {
           return response.json() as RESP;
@@ -83,7 +84,7 @@ export const API = {
     })
       .then((response) => {
         if (!response.ok) {
-          throw new Error(response.statusText);
+          throw new HTTPError(response.status, response.statusText);
         }
         if (
           response.headers.get("Content-Type")?.startsWith("application/json")
@@ -108,8 +109,13 @@ export const API = {
     response: Response;
   }): Promise<T> => {
     if (response.error) {
-      // oxlint-disable-next-line typescript/prefer-promise-reject-errors
-      return Promise.reject(response.error);
+      return Promise.reject(
+        new HTTPError(
+          response.response.status,
+          response.response.statusText,
+          response.error,
+        ),
+      );
     }
     return Promise.resolve(response.data as T);
   },
@@ -118,8 +124,13 @@ export const API = {
     response: Response;
   }): Promise<null> => {
     if (response.error) {
-      // oxlint-disable-next-line typescript/prefer-promise-reject-errors
-      return Promise.reject(response.error);
+      return Promise.reject(
+        new HTTPError(
+          response.response.status,
+          response.response.statusText,
+          response.error,
+        ),
+      );
     }
     return Promise.resolve(null);
   },

package/src/core/network/requests-lazy.ts

@@ -108,6 +108,7 @@ const ACTIONS: Record<keyof AllRequests, Action> = {
   sendStdin: "waitForConnectionOpen",
   sendInterrupt: "waitForConnectionOpen",
   sendPdb: "waitForConnectionOpen",
+  sendSetBreakpoints: "waitForConnectionOpen",
   sendInstallMissingPackages: "waitForConnectionOpen",
   readSnippets: "waitForConnectionOpen",
   previewDatasetColumn: "waitForConnectionOpen",

package/src/core/network/requests-network.ts

@@ -293,6 +293,14 @@ export function createNetworkRequests(): EditRequests & RunRequests {
         })
         .then(handleResponseReturnNull);
     },
+    sendSetBreakpoints: (request) => {
+      return getClient()
+        .POST("/api/kernel/pdb/breakpoints", {
+          body: request,
+          params: getParams(),
+        })
+        .then(handleResponseReturnNull);
+    },
     sendListFiles: async (request) => {
       await waitForConnectionOpen();
       return getClient()

package/src/core/network/requests-static.ts

@@ -68,6 +68,7 @@ export function createStaticRequests(): EditRequests & RunRequests {
     sendListFiles: throwNotInEditMode,
     sendSearchFiles: throwNotInEditMode,
     sendPdb: throwNotInEditMode,
+    sendSetBreakpoints: throwNotInEditMode,
     sendCreateFileOrFolder: throwNotInEditMode,
     sendDeleteFileOrFolder: throwNotInEditMode,
     sendCopyFileOrFolder: throwNotInEditMode,

package/src/core/network/requests-toasting.tsx

@@ -5,7 +5,7 @@ import { useAtomValue } from "jotai";
 import { Spinner } from "@/components/icons/spinner";
 import { Button } from "@/components/ui/button";
 import { toast } from "@/components/ui/use-toast";
-import { NoKernelConnectedError, prettyError } from "@/utils/errors";
+import { HTTPError, NoKernelConnectedError, prettyError } from "@/utils/errors";
 import { Logger } from "@/utils/Logger";
 import { useConnectToRuntime } from "../runtime/config";
 import { store } from "../state/jotai";
@@ -49,6 +49,7 @@ export function createErrorToastingRequests(
     sendListFiles: "Failed to list files",
     sendSearchFiles: "Failed to search files",
     sendPdb: "Failed to start debug session",
+    sendSetBreakpoints: "", // No toast
     sendCreateFileOrFolder: "Failed to create file or folder",
     sendDeleteFileOrFolder: "Failed to delete file or folder",
     sendCopyFileOrFolder: "Failed to duplicate file or folder",
@@ -109,6 +110,14 @@ export function createErrorToastingRequests(
           throw error;
         }
 
+        // A capability 403: the connection is read-only for this action. The
+        // live capability notification already moved the UI to viewer state,
+        // so don't alarm the user with an error toast.
+        if (error instanceof HTTPError && error.status === 403) {
+          Logger.warn(`Request refused, connection is read-only: ${key}`);
+          throw error;
+        }
+
         const title = MESSAGES[keyString];
         const message = prettyError(error);
         if (title) {

package/src/core/network/types.ts

@@ -66,6 +66,7 @@ export type ListDataSourceConnectionRequest =
   schemas["ListDataSourceConnectionRequest"];
 export type ValidateSQLRequest = schemas["ValidateSQLRequest"];
 export type DebugCellRequest = schemas["DebugCellRequest"];
+export type SetBreakpointsRequest = schemas["SetBreakpointsRequest"];
 export type ReadCodeResponse = schemas["ReadCodeResponse"];
 export type RecentFilesResponse = schemas["RecentFilesResponse"];
 export type RenameNotebookRequest = schemas["RenameNotebookRequest"];
@@ -172,6 +173,7 @@ export interface EditRequests {
   getUsageStats: () => Promise<UsageResponse>;
   // Debugger
   sendPdb: (request: DebugCellRequest) => Promise<null>;
+  sendSetBreakpoints: (request: SetBreakpointsRequest) => Promise<null>;
   // File explorer requests
   sendListFiles: (request: FileListRequest) => Promise<FileListResponse>;
   sendSearchFiles: (request: FileSearchRequest) => Promise<FileSearchResponse>;

package/src/core/run-app.tsx

@@ -1,13 +1,13 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { useAtomValue } from "jotai";
+import { atom, useAtomValue } from "jotai";
 import { ArrowLeftIcon } from "lucide-react";
 import { useEffect } from "react";
 import { AppContainer } from "@/components/editor/app-container";
 import { AppHeader } from "@/components/editor/header/app-header";
+import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";
 import { Spinner } from "@/components/icons/spinner";
 import { buttonVariants } from "@/components/ui/button";
-import { DelayMount } from "@/components/utils/delay-mount";
 import { cn } from "@/utils/cn";
 import { CellsRenderer } from "../components/editor/renderers/cells-renderer";
 import {
@@ -18,6 +18,7 @@ import {
 import type { AppConfig } from "./config/config-schema";
 import { RuntimeState } from "./kernel/RuntimeState";
 import { getSessionId } from "./kernel/session";
+import { connectionAtom } from "./network/connection";
 import { useRequestClient } from "./network/requests";
 import { isAppConnecting } from "./websocket/connection-utils";
 import { useMarimoKernelConnection } from "./websocket/useMarimoKernelConnection";
@@ -26,6 +27,16 @@ interface AppProps {
   appConfig: AppConfig;
 }
 
+/**
+ * Paint the (possibly empty) app once we have cells, or as soon as we are no
+ * longer actively connecting. Without the connection check, a connected or
+ * disconnected notebook with no cells would sit on a misleading "Connecting…"
+ * spinner instead of rendering the empty app.
+ */
+const canPaintRunAppAtom = atom(
+  (get) => get(hasCellsAtom) || !isAppConnecting(get(connectionAtom).state),
+);
+
 export const RunApp: React.FC<AppProps> = ({ appConfig }) => {
   const { setCells } = useCellActions();
   const { sendComponentValues } = useRequestClient();
@@ -45,26 +56,6 @@ export const RunApp: React.FC<AppProps> = ({ appConfig }) => {
   });
 
   const isRunning = useAtomValue(notebookIsRunningAtom);
-  const isConnecting = isAppConnecting(connection.state);
-  // Skip the "Connecting..." gate when we already have cells to show — from
-  // an embedded snapshot or a prior connection.
-  const hasExistingCells = useAtomValue(hasCellsAtom);
-
-  const renderCells = () => {
-    // If we are connecting for more than 2 seconds, show a spinner
-    if (isConnecting && !hasExistingCells) {
-      return (
-        <DelayMount milliseconds={2000} fallback={null}>
-          <Spinner className="mx-auto" />
-          <p className="text-center text-sm text-muted-foreground mt-2">
-            Connecting...
-          </p>
-        </DelayMount>
-      );
-    }
-
-    return <CellsRenderer appConfig={appConfig} mode="read" />;
-  };
 
   const galleryHref = (() => {
     if (typeof window === "undefined") {
@@ -103,7 +94,20 @@ export const RunApp: React.FC<AppProps> = ({ appConfig }) => {
           </div>
         )}
       </AppHeader>
-      {renderCells()}
+      <ProgressiveBoundary
+        requires={canPaintRunAppAtom}
+        delay={2000}
+        fallback={
+          <>
+            <Spinner className="mx-auto" />
+            <p className="text-center text-sm text-muted-foreground mt-2">
+              Connecting...
+            </p>
+          </>
+        }
+      >
+        <CellsRenderer appConfig={appConfig} mode="read" />
+      </ProgressiveBoundary>
     </AppContainer>
   );
 };

package/src/core/runtime/__tests__/adapter.test.ts

@@ -0,0 +1,160 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { createStore } from "jotai";
+import { describe, expect, it } from "vitest";
+import { islandsInitializedAtom } from "../../islands/state";
+import { kernelStateAtom } from "../../kernel/state";
+import { connectionAtom } from "../../network/connection";
+import { wasmInitStateAtom } from "../../wasm/state";
+import { WebSocketState } from "../../websocket/types";
+import {
+  canRunCellsAtom,
+  islandsAdapter,
+  remoteAdapter,
+  runtimeAdapterAtom,
+  staticAdapter,
+  wasmAdapter,
+} from "../adapter";
+
+describe("wasmAdapter", () => {
+  it("reports connecting with the progress label while loading", () => {
+    const store = createStore();
+    store.set(wasmInitStateAtom, {
+      kind: "loading",
+      message: "Loading Pyodide…",
+    });
+    expect(store.get(wasmAdapter.state)).toEqual({
+      kind: "connecting",
+      progress: { label: "Loading Pyodide…" },
+    });
+  });
+
+  it("reports ready when initialized", () => {
+    const store = createStore();
+    store.set(wasmInitStateAtom, { kind: "ready" });
+    expect(store.get(wasmAdapter.state)).toEqual({ kind: "ready" });
+  });
+
+  it("exposes the real error message on failure", () => {
+    const store = createStore();
+    store.set(wasmInitStateAtom, {
+      kind: "error",
+      message: "ImportError: numpy",
+    });
+    expect(store.get(wasmAdapter.state)).toEqual({
+      kind: "failed",
+      error: { message: "ImportError: numpy", errorKind: "init" },
+    });
+  });
+});
+
+describe("remoteAdapter", () => {
+  it.each([
+    [{ state: WebSocketState.OPEN }, { kind: "ready" }],
+    [
+      { state: WebSocketState.CONNECTING },
+      { kind: "connecting", progress: { label: "Connecting…" } },
+    ],
+    [
+      { state: WebSocketState.NOT_STARTED },
+      { kind: "connecting", progress: { label: "Not connected" } },
+    ],
+  ] as const)("maps %j to %j", (conn, expected) => {
+    const store = createStore();
+    store.set(connectionAtom, conn as never);
+    expect(store.get(remoteAdapter.state)).toEqual(expected);
+  });
+
+  it("surfaces the close reason when closed", () => {
+    const store = createStore();
+    store.set(connectionAtom, {
+      state: WebSocketState.CLOSED,
+      code: "KERNEL_DISCONNECTED",
+      reason: "Kernel went away",
+    });
+    expect(store.get(remoteAdapter.state)).toEqual({
+      kind: "failed",
+      error: { message: "Kernel went away", errorKind: "runtime" },
+    });
+  });
+});
+
+describe("staticAdapter", () => {
+  it("is always ready", () => {
+    const store = createStore();
+    expect(store.get(staticAdapter.state)).toEqual({ kind: "ready" });
+  });
+
+  it("advertises no capabilities", () => {
+    expect(staticAdapter.capabilities).toEqual({
+      canHealthCheck: false,
+      canShutdown: false,
+      canRestart: false,
+      supportsLsp: false,
+    });
+  });
+});
+
+describe("islandsAdapter", () => {
+  it("is connecting before islands report initialization", () => {
+    const store = createStore();
+    store.set(islandsInitializedAtom, false);
+    expect(store.get(islandsAdapter.state)).toEqual({
+      kind: "connecting",
+      progress: { label: "Initializing islands…" },
+    });
+  });
+
+  it("is ready once islands initialize", () => {
+    const store = createStore();
+    store.set(islandsInitializedAtom, true);
+    expect(store.get(islandsAdapter.state)).toEqual({ kind: "ready" });
+  });
+
+  it("surfaces the error string when islands fail", () => {
+    const store = createStore();
+    store.set(islandsInitializedAtom, "wheel download failed");
+    expect(store.get(islandsAdapter.state)).toEqual({
+      kind: "failed",
+      error: { message: "wheel download failed", errorKind: "init" },
+    });
+  });
+});
+
+describe("canRunCellsAtom", () => {
+  it("is false on a remote adapter until kernel acks", () => {
+    const store = createStore();
+    // Default adapter in test env is remote.
+    store.set(connectionAtom, { state: WebSocketState.OPEN });
+    expect(store.get(canRunCellsAtom)).toBe(false);
+
+    store.set(kernelStateAtom, { isInstantiated: true, error: null });
+    expect(store.get(canRunCellsAtom)).toBe(true);
+  });
+
+  it("is true on WASM as soon as the adapter is ready (no separate kernel ack)", () => {
+    const store = createStore();
+    store.set(runtimeAdapterAtom, wasmAdapter);
+    store.set(wasmInitStateAtom, { kind: "loading", message: "…" });
+    expect(store.get(canRunCellsAtom)).toBe(false);
+
+    store.set(wasmInitStateAtom, { kind: "ready" });
+    expect(store.get(canRunCellsAtom)).toBe(true);
+  });
+
+  it("is always false on a static notebook", () => {
+    const store = createStore();
+    store.set(runtimeAdapterAtom, staticAdapter);
+    expect(store.get(canRunCellsAtom)).toBe(false);
+  });
+
+  it("is true on islands once initialized", () => {
+    const store = createStore();
+    store.set(runtimeAdapterAtom, islandsAdapter);
+    store.set(islandsInitializedAtom, false);
+    expect(store.get(canRunCellsAtom)).toBe(false);
+
+    store.set(islandsInitializedAtom, true);
+    expect(store.get(canRunCellsAtom)).toBe(true);
+  });
+});

package/src/core/runtime/__tests__/runtime.test.ts

@@ -154,6 +154,51 @@ describe("RuntimeManager", () => {
     });
   });
 
+  describe("getSseURL", () => {
+    it("should return an http(s) URL with the session ID", () => {
+      const runtime = new RuntimeManager(mockConfig);
+      const url = runtime.getSseURL("1234" as SessionId);
+
+      expect(url.protocol).toBe("https:");
+      expect(url.pathname).toBe("/sse");
+      expect(url.searchParams.get("session_id")).toBe("1234");
+    });
+
+    it("should never put the auth token in the URL, even cross-origin", () => {
+      // SSE requests can send headers, so auth travels in the
+      // Authorization header; a token in the URL would leak into
+      // proxy and server logs.
+      const runtime = new RuntimeManager(
+        {
+          url: "https://sandbox.example.com",
+          lazy: true,
+          authToken: "my-secret-token",
+        },
+        true,
+      );
+      const url = runtime.getSseURL("s_123" as SessionId);
+
+      expect(url.searchParams.get("access_token")).toBeNull();
+      expect(url.toString()).not.toContain("my-secret-token");
+    });
+
+    it("should strip an access_token forwarded from the page URL", () => {
+      // The page URL can briefly carry access_token before auth cleanup
+      // removes it; it must not be forwarded to /sse.
+      const original = window.location.href;
+      window.history.pushState({}, "", "/?access_token=page-token&foo=bar");
+      try {
+        const runtime = new RuntimeManager(mockConfig);
+        const url = runtime.getSseURL("s_123" as SessionId);
+
+        expect(url.searchParams.get("access_token")).toBeNull();
+        expect(url.searchParams.get("foo")).toBe("bar");
+      } finally {
+        window.history.pushState({}, "", original);
+      }
+    });
+  });
+
   describe("getWsSyncURL", () => {
     it("should return WebSocket Sync URL", () => {
       const runtime = new RuntimeManager(mockConfig);