@marimo-team/frontend 0.23.14-dev1 → 0.23.14-dev10

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

@@ -0,0 +1,247 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { visibleForTesting } from "../render-policy";
+
+const { computeRenderPolicy } = visibleForTesting;
+
+const originalHref = window.location.href;
+function setSearch(search: string) {
+  window.history.replaceState(null, "", `/${search}`);
+}
+
+describe("computeRenderPolicy", () => {
+  it("shows code in edit mode", () => {
+    const policy = computeRenderPolicy({
+      mode: "edit",
+      showAppCode: false, // ignored in edit mode
+      hasCells: true,
+      hasCachedOutputs: false,
+      allCellsIdle: false,
+    });
+    expect(policy.showCode).toBe(true);
+  });
+
+  it("hides code in present mode regardless of config", () => {
+    const policy = computeRenderPolicy({
+      mode: "present",
+      showAppCode: true,
+      hasCells: true,
+      hasCachedOutputs: true,
+      allCellsIdle: false,
+    });
+    expect(policy.showCode).toBe(false);
+  });
+
+  it("respects showAppCode in read mode", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).showCode,
+    ).toBe(true);
+
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).showCode,
+    ).toBe(false);
+  });
+
+  it("reports showCachedOutputs when cells and cached outputs are present", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).showCachedOutputs,
+    ).toBe(true);
+  });
+
+  it("does not report showCachedOutputs when there are no cells", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: false,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).showCachedOutputs,
+    ).toBe(false);
+  });
+
+  it("only reports showCachedOutputs for real outputs, not an idle notebook", () => {
+    // Regression guard: `showCachedOutputs` must stay honest even when the
+    // notebook is settled with no outputs (that only affects `canPaint`).
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).showCachedOutputs,
+    ).toBe(false);
+  });
+});
+
+describe("computeRenderPolicy — read-mode code visibility", () => {
+  beforeEach(() => {
+    setSearch("");
+  });
+
+  afterEach(() => {
+    window.history.replaceState(null, "", originalHref);
+  });
+
+  it("hides code when the server stripped sources (?include-code=false)", () => {
+    setSearch("?include-code=false");
+    const policy = computeRenderPolicy({
+      mode: "read",
+      showAppCode: true, // config would show code, but sources are stripped
+      hasCells: true,
+      hasCachedOutputs: false,
+      allCellsIdle: false,
+    });
+    expect(policy.showCode).toBe(false);
+    // With no code, no outputs, and still running, there is nothing to paint.
+    expect(policy.canPaint).toBe(false);
+  });
+
+  it("include-code=false still paints when cached outputs exist", () => {
+    setSearch("?include-code=false");
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+});
+
+describe("computeRenderPolicy.canPaint", () => {
+  it("is false when no cells exist, even if all (zero) cells are vacuously idle", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: false,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).canPaint,
+    ).toBe(false);
+  });
+
+  it("is true in edit mode whenever cells exist", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "edit",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is true in read mode when code is visible", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is false in headless read mode while the notebook is still running with no outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(false);
+  });
+
+  it("is true in headless read mode with cached outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is true in headless read mode for a settled notebook with no outputs", () => {
+    // A notebook that ran to completion producing no outputs must still paint
+    // (empty) rather than sit on a spinner — parity with the pre-framework
+    // `hasAnyOutputAtom` idle fallback.
+    expect(
+      computeRenderPolicy({
+        mode: "read",
+        showAppCode: false,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  // In present mode `showCode` is always false, so `canPaint` rides entirely
+  // on cached outputs / a settled notebook.
+  it("is true in present mode with cached outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "present",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: true,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(true);
+  });
+
+  it("is false in present mode while still running with no outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "present",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: false,
+      }).canPaint,
+    ).toBe(false);
+  });
+
+  it("is true in present mode for a settled notebook with no outputs", () => {
+    expect(
+      computeRenderPolicy({
+        mode: "present",
+        showAppCode: true,
+        hasCells: true,
+        hasCachedOutputs: false,
+        allCellsIdle: true,
+      }).canPaint,
+    ).toBe(true);
+  });
+});

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