@marimo-team/islands 0.23.14-dev3 → 0.23.14-dev31

package/src/core/lifecycle/render-policy.ts

@@ -0,0 +1,125 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { atom } from "jotai";
+import { hasCellsAtom, notebookAtom } from "../cells/cells";
+import { isOutputEmpty } from "../cells/outputs";
+import { KnownQueryParams } from "../constants";
+import { showCodeInRunModeAtom } from "../meta/state";
+import { type AppMode, initialModeAtom } from "../mode";
+import { hasQueryParam } from "@/utils/urls";
+
+export interface RenderPolicy {
+  /** False in `present` mode, and in `read` mode when the user has opted to hide code. */
+  showCode: boolean;
+  /** True only when there are real, non-empty cached outputs to display. */
+  showCachedOutputs: boolean;
+  /**
+   * Whether the current view has anything to paint without waiting on the
+   * runtime:
+   * - In edit/home/gallery mode, this is `hasCells` — the editor renders the
+   *   cell skeleton even when output is empty.
+   * - In read/present mode with code visible, the cell source is enough.
+   * - In headless read mode (code hidden), we need either cached outputs or a
+   *   settled notebook (all cells idle) — a completed but output-less notebook
+   *   is still "done" and shouldn't strand on an infinite spinner.
+   */
+  canPaint: boolean;
+}
+
+function readCodeVisibility(
+  mode: AppMode | undefined,
+  showAppCode: boolean,
+): boolean {
+  if (mode === "edit" || mode === "home" || mode === "gallery") {
+    return true;
+  }
+  if (mode === "present") {
+    return false;
+  }
+  // read mode (or undefined). If `marimo run` stripped the sources
+  // (`--include-code` off), there is no code to show regardless of any other
+  // signal — mirror `core/meta/code-visibility.ts` so the two don't drift.
+  if (hasQueryParam(KnownQueryParams.includeCode, "false")) {
+    return false;
+  }
+  // Otherwise the URL `show-code` param wins, then the view config.
+  if (hasQueryParam(KnownQueryParams.showCode, "false")) {
+    return false;
+  }
+  if (hasQueryParam(KnownQueryParams.showCode, "true")) {
+    return true;
+  }
+  return showAppCode;
+}
+
+function computeRenderPolicy(input: {
+  mode: AppMode | undefined;
+  showAppCode: boolean;
+  hasCells: boolean;
+  hasCachedOutputs: boolean;
+  /**
+   * True when every cell is idle. A settled notebook is paintable even with no
+   * visible outputs — otherwise a completed but output-less notebook viewed in
+   * headless read mode would strand on an infinite spinner. Mirrors the
+   * pre-framework `hasAnyOutputAtom` idle fallback.
+   */
+  allCellsIdle: boolean;
+}): RenderPolicy {
+  const showCode = readCodeVisibility(input.mode, input.showAppCode);
+  const showCachedOutputs = input.hasCells && input.hasCachedOutputs;
+  const canPaint =
+    input.hasCells && (showCode || showCachedOutputs || input.allCellsIdle);
+
+  return { showCode, showCachedOutputs, canPaint };
+}
+
+/**
+ * Both cell-runtime facts the render policy needs, computed in a single pass
+ * over `cellRuntime`:
+ * - `hasCachedOutputs`: any cell has a non-empty output.
+ * - `allCellsIdle`: every cell's status is idle — nothing queued or running.
+ *   Vacuously true for an empty notebook, so `canPaint` still gates on
+ *   `hasCells`.
+ *
+ * Fan out to two boolean selector atoms below so `renderPolicyAtom` only
+ * recomputes when one of the booleans actually flips, not on every notebook
+ * update.
+ */
+const cellRuntimeSummaryAtom = atom((get) => {
+  let hasCachedOutputs = false;
+  let allCellsIdle = true;
+  for (const runtime of Object.values(get(notebookAtom).cellRuntime)) {
+    if (!isOutputEmpty(runtime.output)) {
+      hasCachedOutputs = true;
+    }
+    if (runtime.status !== "idle") {
+      allCellsIdle = false;
+    }
+  }
+  return { hasCachedOutputs, allCellsIdle };
+});
+
+const hasCachedOutputsAtom = atom(
+  (get) => get(cellRuntimeSummaryAtom).hasCachedOutputs,
+);
+
+const allCellsIdleAtom = atom(
+  (get) => get(cellRuntimeSummaryAtom).allCellsIdle,
+);
+
+export const renderPolicyAtom = atom<RenderPolicy>((get) =>
+  computeRenderPolicy({
+    mode: get(initialModeAtom),
+    showAppCode: get(showCodeInRunModeAtom),
+    hasCells: get(hasCellsAtom),
+    hasCachedOutputs: get(hasCachedOutputsAtom),
+    allCellsIdle: get(allCellsIdleAtom),
+  }),
+);
+
+/** Sugar over `renderPolicyAtom.canPaint`. */
+export const canPaintAtom = atom((get) => get(renderPolicyAtom).canPaint);
+
+export const visibleForTesting = {
+  computeRenderPolicy,
+};

package/src/core/mime.ts

@@ -1,9 +1,16 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import type { OutputMessage } from "./kernel/messages";
 
+export function isMarimoErrorsMime(
+  mime: OutputMessage["mimetype"] | undefined,
+) {
+  return mime === "application/vnd.marimo+error";
+}
+
+export function isTracebackMime(mime: OutputMessage["mimetype"] | undefined) {
+  return mime === "application/vnd.marimo+traceback";
+}
+
 export function isErrorMime(mime: OutputMessage["mimetype"] | undefined) {
-  return (
-    mime === "application/vnd.marimo+error" ||
-    mime === "application/vnd.marimo+traceback"
-  );
+  return isMarimoErrorsMime(mime) || isTracebackMime(mime);
 }

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