@marimo-team/islands 0.23.14-dev6 → 0.23.14-dev61

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;
+});

package/src/core/runtime/runtime.ts

@@ -107,9 +107,10 @@ export class RuntimeManager {
   }
 
   /**
-   * The WebSocket URL of the runtime.
+   * Search params for a session connection: the base URL's params, merged
+   * with the current page's, plus the session id.
    */
-  getWsURL(sessionId: SessionId): URL {
+  private getSessionSearchParams(sessionId: SessionId): URLSearchParams {
     const baseUrl = new URL(this.config.url);
     const searchParams = new URLSearchParams(baseUrl.search);
 
@@ -123,27 +124,40 @@ export class RuntimeManager {
     });
 
     searchParams.set(KnownQueryParams.sessionId, sessionId);
-    return this.formatWsURL("/ws", searchParams);
+    return searchParams;
   }
 
   /**
-   * The WebSocket Sync URL of the runtime, for real-time updates.
+   * The WebSocket URL of the runtime.
    */
-  getWsSyncURL(sessionId: SessionId): URL {
-    const baseUrl = new URL(this.config.url);
-    const searchParams = new URLSearchParams(baseUrl.search);
+  getWsURL(sessionId: SessionId): URL {
+    return this.formatWsURL("/ws", this.getSessionSearchParams(sessionId));
+  }
 
-    // Merge in current page's query parameters
-    const currentParams = new URLSearchParams(window.location.search);
-    currentParams.forEach((value, key) => {
-      // Don't override base URL params
-      if (!searchParams.has(key)) {
-        searchParams.set(key, value);
-      }
+  /**
+   * The SSE URL of the runtime; the http(s) alternative to `getWsURL`
+   * when `server.transport` is `"sse"`. Unlike WebSockets, SSE requests
+   * can send headers, so auth travels in the Authorization header
+   * (see `headers()`) instead of the URL.
+   */
+  getSseURL(sessionId: SessionId): URL {
+    const url = this.formatHttpURL({
+      path: "/sse",
+      searchParams: this.getSessionSearchParams(sessionId),
+      restrictToKnownQueryParams: false,
     });
+    // The page URL can still carry access_token (merged in from the
+    // current page's params, before auth cleanup strips it); never
+    // forward it — a token in the URL leaks into proxy/server logs.
+    url.searchParams.delete(KnownQueryParams.accessToken);
+    return url;
+  }
 
-    searchParams.set(KnownQueryParams.sessionId, sessionId);
-    return this.formatWsURL("/ws_sync", searchParams);
+  /**
+   * The WebSocket Sync URL of the runtime, for real-time updates.
+   */
+  getWsSyncURL(sessionId: SessionId): URL {
+    return this.formatWsURL("/ws_sync", this.getSessionSearchParams(sessionId));
   }
 
   /**

package/src/core/wasm/PyodideLoader.tsx

@@ -5,54 +5,41 @@ import type React from "react";
 import type { PropsWithChildren } from "react";
 import { useEffect, useRef } from "react";
 import { LargeSpinner } from "@/components/icons/large-spinner";
+import { ProgressiveBoundary } from "@/components/lifecycle/ProgressiveBoundary";
 import { toast } from "@/components/ui/use-toast";
-import { hasCellsAtom } from "@/core/cells/cells";
-import { showCodeInRunModeAtom } from "@/core/meta/state";
-import { store } from "@/core/state/jotai";
+import { canPaintAtom } from "@/core/lifecycle/render-policy";
+import { wasmInitStateAtom } from "@/core/wasm/state";
 import { useAsyncData } from "@/hooks/useAsyncData";
 import { prettyError } from "@/utils/errors";
 import { Logger } from "@/utils/Logger";
-import { hasQueryParam } from "@/utils/urls";
-import { KnownQueryParams } from "../constants";
-import { type AppMode, getInitialAppMode } from "../mode";
 import { PyodideBridge } from "./bridge";
-import { hasAnyOutputAtom, wasmInitializationAtom } from "./state";
 import { isWasm } from "./utils";
 
 /**
- * HOC to load Pyodide before rendering children, if necessary.
+ * Paints the snapshot (or hydrated cells) immediately and lets Pyodide
+ * finish downloading in the background. UI elements aren't interactive
+ * until Pyodide is ready.
  */
 export const PyodideLoader: React.FC<PropsWithChildren> = ({ children }) => {
   if (!isWasm()) {
     return children;
   }
-
   return <PyodideLoaderInner>{children}</PyodideLoaderInner>;
 };
 
 const PyodideLoaderInner: React.FC<PropsWithChildren> = ({ children }) => {
-  // Don't block render on Pyodide: a hydrated snapshot can paint immediately
-  // while Pyodide downloads in the background.
   const { error } = useAsyncData(async () => {
     await PyodideBridge.INSTANCE.initialized.promise;
     return true;
   }, []);
 
-  const hasCells = useAtomValue(hasCellsAtom);
-  const hasOutput = useAtomValue(hasAnyOutputAtom);
-  const nothingToShow = shouldShowSpinner({
-    hasCells,
-    hasOutput,
-    mode: getInitialAppMode(),
-    codeHidden: isCodeHidden(),
-  });
+  const canPaint = useAtomValue(canPaintAtom);
 
+  // If the snapshot is already on screen, toast instead of throwing so we
+  // don't tear it down. With nothing painted, throw to surface the error UI.
   const didToastErrorRef = useRef(false);
   useEffect(() => {
-    // With snapshot content on-screen, toast instead of throwing so the
-    // snapshot stays readable. The ref ensures we only toast once even if
-    // nothingToShow toggles later.
-    if (error && !nothingToShow && !didToastErrorRef.current) {
+    if (error && canPaint && !didToastErrorRef.current) {
       didToastErrorRef.current = true;
       Logger.error("Pyodide failed to initialize", error);
       toast({
@@ -61,50 +48,21 @@ const PyodideLoaderInner: React.FC<PropsWithChildren> = ({ children }) => {
         variant: "danger",
       });
     }
-  }, [error, nothingToShow]);
+  }, [error, canPaint]);
 
-  if (error && nothingToShow) {
+  if (error && !canPaint) {
     throw error;
   }
 
-  if (nothingToShow) {
-    return <WasmSpinner />;
-  }
-
-  return children;
-};
-
-function isCodeHidden() {
-  // Code is hidden if ANY are true:
-  // - the query param is set to false
-  // - the view.showAppCode is false
   return (
-    hasQueryParam(KnownQueryParams.showCode, "false") ||
-    !store.get(showCodeInRunModeAtom)
+    <ProgressiveBoundary requires={canPaintAtom} fallback={<WasmSpinner />}>
+      {children}
+    </ProgressiveBoundary>
   );
-}
-
-/**
- * Pure predicate: should the WASM loader render a spinner instead of its
- * children? We block render only when nothing user-visible would appear:
- *   - no cells have been hydrated (Pyodide hasn't parsed the notebook), or
- *   - we are in headless run mode (code hidden) with no outputs to display.
- */
-export function shouldShowSpinner(input: {
-  hasCells: boolean;
-  hasOutput: boolean;
-  mode: AppMode;
-  codeHidden: boolean;
-}): boolean {
-  const { hasCells, hasOutput, mode, codeHidden } = input;
-  if (!hasCells) {
-    return true;
-  }
-  return !hasOutput && mode === "read" && codeHidden;
-}
-
-export const WasmSpinner: React.FC<PropsWithChildren> = ({ children }) => {
-  const wasmInitialization = useAtomValue(wasmInitializationAtom);
+};
 
-  return <LargeSpinner title={wasmInitialization} />;
+const WasmSpinner: React.FC = () => {
+  const state = useAtomValue(wasmInitStateAtom);
+  const title = state.kind === "loading" ? state.message : "Loading…";
+  return <LargeSpinner title={title} />;
 };

package/src/core/wasm/bridge.ts

@@ -38,7 +38,7 @@ import type { IConnectionTransport } from "../websocket/transports/transport";
 import { PyodideRouter } from "./router";
 import { getWorkerRPC } from "./rpc";
 import { createShareableLink } from "./share";
-import { wasmInitializationAtom, wasmInitStatusAtom } from "./state";
+import { wasmInitStateAtom } from "./state";
 import { fallbackFileStore, notebookFileStore } from "./store";
 import { isWasm } from "./utils";
 import type { SaveWorkerSchema } from "./worker/save-worker";
@@ -120,11 +120,16 @@ export class PyodideBridge implements RunRequests, EditRequests {
       // By initializing after, we get hits on cached network requests
       this.saveRpc = this.getSaveWorker();
       this.setInterruptBuffer();
-      store.set(wasmInitStatusAtom, "ready");
+      store.set(wasmInitStateAtom, { kind: "ready" });
       this.initialized.resolve();
     });
     this.rpc.addMessageListener("initializingMessage", ({ message }) => {
-      store.set(wasmInitializationAtom, message);
+      // Only bump the progress label while still loading — if we've already
+      // reached "ready" or "error", a late message shouldn't roll us back.
+      const current = store.get(wasmInitStateAtom);
+      if (current.kind === "loading") {
+        store.set(wasmInitStateAtom, { kind: "loading", message });
+      }
     });
     this.rpc.addMessageListener("initializedError", ({ error }) => {
       // If already initialized, surface as a toast and leave the deferred /
@@ -138,7 +143,7 @@ export class PyodideBridge implements RunRequests, EditRequests {
         });
         return;
       }
-      store.set(wasmInitStatusAtom, "error");
+      store.set(wasmInitStateAtom, { kind: "error", message: error });
       this.initialized.reject(new Error(error));
     });
     this.rpc.addMessageListener("kernelMessage", ({ message }) => {
@@ -252,6 +257,10 @@ export class PyodideBridge implements RunRequests, EditRequests {
     throwNotImplemented();
   };
 
+  sendSetBreakpoints: EditRequests["sendSetBreakpoints"] = async () => {
+    throwNotImplemented();
+  };
+
   sendRun: EditRequests["sendRun"] = async (request) => {
     await this.rpc.proxy.request.loadPackages(request.codes.join("\n"));
 

package/src/core/wasm/state.ts

@@ -1,24 +1,13 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { atom } from "jotai";
-import { notebookAtom } from "../cells/cells";
-import { isOutputEmpty } from "../cells/outputs";
 
-export const wasmInitializationAtom = atom<string>("Initializing...");
+/** Tagged so the progress label and error message can't drift apart. */
+export type WasmInitState =
+  | { kind: "loading"; message: string }
+  | { kind: "ready" }
+  | { kind: "error"; message: string };
 
-export type WasmInitStatus = "loading" | "ready" | "error";
-export const wasmInitStatusAtom = atom<WasmInitStatus>("loading");
-
-export const hasAnyOutputAtom = atom<boolean>((get) => {
-  const notebook = get(notebookAtom);
-  const runtimeStates = Object.values(notebook.cellRuntime);
-  // First check if there is any output
-  const hasOutput = runtimeStates.some(
-    (runtime) => !isOutputEmpty(runtime.output),
-  );
-  if (hasOutput) {
-    return true;
-  }
-  // If there is no output, check if they have all run to completion
-  // in case this notebook doesn't contain outputs
-  return runtimeStates.every((runtime) => runtime.status === "idle");
+export const wasmInitStateAtom = atom<WasmInitState>({
+  kind: "loading",
+  message: "Initializing...",
 });

package/src/core/websocket/__tests__/useMarimoKernelConnection.test.ts

@@ -36,6 +36,10 @@ describe("classifyCloseEvent", () => {
       "MARIMO_NO_SESSION_ID",
       "MARIMO_NO_SESSION",
       "MARIMO_SHUTDOWN",
+      // Delivered as in-band close events by the SSE transport; must be
+      // terminal or a rejected client would reconnect forever.
+      "MARIMO_UNAUTHORIZED",
+      "MARIMO_KIOSK_NOT_ALLOWED",
     ])("%s → terminal with KERNEL_DISCONNECTED, closes transport", (reason) => {
       const decision = classify(reason);
       expect(decision.kind).toBe("terminal");

package/src/core/websocket/__tests__/useWebSocket.test.ts

@@ -0,0 +1,49 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { BasicTransport } from "../transports/basic";
+import { SseTransport } from "../transports/sse";
+import { WsTransport } from "../transports/ws";
+import { createConnectionTransport } from "../useWebSocket";
+
+vi.mock("../../wasm/utils", () => ({
+  isWasm: () => false,
+}));
+
+describe("createConnectionTransport", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const options = {
+    url: () => "http://localhost/ws",
+    headers: () => ({}),
+  };
+
+  it("uses BasicTransport for static notebooks", () => {
+    const transport = createConnectionTransport({
+      ...options,
+      static: true,
+      transportType: "websocket",
+    });
+    expect(transport).toBeInstanceOf(BasicTransport);
+  });
+
+  it("uses WsTransport by default", () => {
+    const transport = createConnectionTransport({
+      ...options,
+      static: false,
+      transportType: "websocket",
+    });
+    expect(transport).toBeInstanceOf(WsTransport);
+  });
+
+  it("uses SseTransport when the transport type is sse", () => {
+    const transport = createConnectionTransport({
+      ...options,
+      static: false,
+      transportType: "sse",
+    });
+    expect(transport).toBeInstanceOf(SseTransport);
+  });
+});