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

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/adapter.ts

@@ -0,0 +1,182 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { type Atom, atom } from "jotai";
+import { kernelStateAtom } from "../kernel/state";
+import { islandsInitializedAtom } from "../islands/state";
+import { isIslands } from "../islands/utils";
+import { connectionAtom } from "../network/connection";
+import { isStaticNotebook } from "../static/static-state";
+import { wasmInitStateAtom } from "../wasm/state";
+import { isWasm } from "../wasm/utils";
+import { WebSocketState } from "../websocket/types";
+
+export type RuntimeKind = "wasm" | "remote" | "static" | "islands";
+
+export type AdapterState =
+  | { kind: "connecting"; progress?: { label: string; percent?: number } }
+  | { kind: "ready" }
+  | {
+      kind: "failed";
+      error: { message: string; errorKind: "init" | "runtime" };
+    };
+
+export interface RuntimeCapabilities {
+  canHealthCheck: boolean;
+  canShutdown: boolean;
+  canRestart: boolean;
+  supportsLsp: boolean;
+}
+
+/** Runtimes with no server-side kernel to manage (wasm, static, islands). */
+const NO_CAPABILITIES: RuntimeCapabilities = {
+  canHealthCheck: false,
+  canShutdown: false,
+  canRestart: false,
+  supportsLsp: false,
+};
+
+/**
+ * One adapter per runtime so consumers don't branch on `isWasm()` /
+ * `isStaticNotebook()` / `isIslands()` at the call site.
+ */
+export interface RuntimeAdapter {
+  readonly kind: RuntimeKind;
+  /** Short label suitable for status pills, e.g. "Kernel", "Pyodide". */
+  readonly label: string;
+  readonly capabilities: RuntimeCapabilities;
+  state: Atom<AdapterState>;
+}
+
+// --- WASM ------------------------------------------------------------------
+
+const wasmStateAtom = atom<AdapterState>((get) => {
+  const s = get(wasmInitStateAtom);
+  switch (s.kind) {
+    case "loading":
+      return { kind: "connecting", progress: { label: s.message } };
+    case "ready":
+      return { kind: "ready" };
+    case "error":
+      return {
+        kind: "failed",
+        error: { message: s.message, errorKind: "init" },
+      };
+  }
+});
+
+export const wasmAdapter: RuntimeAdapter = {
+  kind: "wasm",
+  label: "Pyodide",
+  capabilities: NO_CAPABILITIES,
+  state: wasmStateAtom,
+};
+
+// --- Remote ----------------------------------------------------------------
+
+const remoteStateAtom = atom<AdapterState>((get) => {
+  const conn = get(connectionAtom);
+  switch (conn.state) {
+    case WebSocketState.OPEN:
+      return { kind: "ready" };
+    case WebSocketState.CONNECTING:
+      return { kind: "connecting", progress: { label: "Connecting…" } };
+    case WebSocketState.NOT_STARTED:
+      return { kind: "connecting", progress: { label: "Not connected" } };
+    case WebSocketState.CLOSING:
+    case WebSocketState.CLOSED:
+      return {
+        kind: "failed",
+        error: {
+          message:
+            conn.state === WebSocketState.CLOSED
+              ? conn.reason
+              : "Disconnecting",
+          errorKind: "runtime",
+        },
+      };
+  }
+});
+
+export const remoteAdapter: RuntimeAdapter = {
+  kind: "remote",
+  label: "Kernel",
+  capabilities: {
+    canHealthCheck: true,
+    canShutdown: true,
+    canRestart: true,
+    supportsLsp: true,
+  },
+  state: remoteStateAtom,
+};
+
+// --- Static ----------------------------------------------------------------
+
+const staticStateAtom = atom<AdapterState>({ kind: "ready" });
+
+export const staticAdapter: RuntimeAdapter = {
+  kind: "static",
+  label: "Static",
+  capabilities: NO_CAPABILITIES,
+  state: staticStateAtom,
+};
+
+// --- Islands ---------------------------------------------------------------
+
+const islandsStateAtom = atom<AdapterState>((get) => {
+  const status = get(islandsInitializedAtom);
+  if (status === true) {
+    return { kind: "ready" };
+  }
+  if (typeof status === "string") {
+    return {
+      kind: "failed",
+      error: { message: status, errorKind: "init" },
+    };
+  }
+  return {
+    kind: "connecting",
+    progress: { label: "Initializing islands…" },
+  };
+});
+
+export const islandsAdapter: RuntimeAdapter = {
+  kind: "islands",
+  label: "Islands",
+  capabilities: NO_CAPABILITIES,
+  state: islandsStateAtom,
+};
+
+function selectAdapter(): RuntimeAdapter {
+  if (isStaticNotebook()) {
+    return staticAdapter;
+  }
+  if (isIslands()) {
+    return islandsAdapter;
+  }
+  if (isWasm()) {
+    return wasmAdapter;
+  }
+  return remoteAdapter;
+}
+
+/** Picked once at module load; the choice doesn't change after page load. */
+export const runtimeAdapterAtom = atom<RuntimeAdapter>(selectAdapter());
+
+/**
+ * Remote runtimes require both the WS to be open *and* the kernel to have
+ * ack'd instantiation. WASM/islands have no separate kernel handshake.
+ * Static notebooks never run cells.
+ */
+export const canRunCellsAtom = atom<boolean>((get) => {
+  const adapter = get(runtimeAdapterAtom);
+  if (get(adapter.state).kind !== "ready") {
+    return false;
+  }
+  if (adapter.kind === "static") {
+    return false;
+  }
+  if (adapter.kind === "remote") {
+    return get(kernelStateAtom).isInstantiated;
+  }
+  return true;
+});