@marimo-team/islands 0.25.3-dev312 → 0.25.3-dev317

package/src/core/runtime/config.ts

@@ -1,13 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { atom, useAtom, useAtomValue } from "jotai";
-import useEvent from "react-use-event-hook";
-import { prettyError } from "@/utils/errors";
-import { Logger } from "@/utils/Logger";
-import { connectionAtom } from "../network/connection";
-import { ConnectionClosedReason } from "../notebook/replica";
+import { atom, useAtomValue } from "jotai";
 import { store } from "../state/jotai";
-import { isAppNotStarted } from "../session/connection-utils";
-import { ConnectionState } from "../session/types";
 import { RuntimeManager } from "./runtime";
 import type { RuntimeConfig } from "./types";
 
@@ -19,33 +12,18 @@ function getBaseURI(): string {
 }
 
 export const DEFAULT_RUNTIME_CONFIG: RuntimeConfig = {
-  lazy: true,
   url: getBaseURI(),
 };
 
 export const runtimeConfigAtom = atom<RuntimeConfig>(DEFAULT_RUNTIME_CONFIG);
-const runtimeManagerAtom = atom<RuntimeManager>((get) => {
-  const config = get(runtimeConfigAtom);
-  return new RuntimeManager(config, config.lazy);
-});
+const runtimeManagerAtom = atom<RuntimeManager>(
+  (get) => new RuntimeManager(get(runtimeConfigAtom)),
+);
 
 export function useRuntimeManager(): RuntimeManager {
   return useAtomValue(runtimeManagerAtom);
 }
 
-export function useConnectToRuntime(): () => Promise<void> {
-  const runtimeManager = useRuntimeManager();
-  const [connection, setConnection] = useAtom(connectionAtom);
-  return useEvent(async () => {
-    if (isAppNotStarted(connection.state)) {
-      setConnection({ state: ConnectionState.CONNECTING });
-      await runtimeManager.start();
-    } else {
-      Logger.log("Runtime already started or starting...");
-    }
-  });
-}
-
 /**
  * Prefer to use useRuntimeManager instead of this function.
  */
@@ -53,39 +31,6 @@ export function getRuntimeManager(): RuntimeManager {
   return store.get(runtimeManagerAtom);
 }
 
-/**
- * Start a lazy runtime the first time something needs it.
- *
- * The connection can already read as connecting before anyone has asked
- * for the runtime, because the notebook stream waits for the runtime's
- * health and the editor mirrors that wait. So whether the runtime has
- * been asked to start is the runtime's own business, and this only keeps
- * the connection state honest around the attempt. A start that gives up
- * closes the connection with the reason, which leaves the user a way to
- * reconnect instead of a connection that looks like it is still coming up.
- */
-export async function startRuntimeIfLazy(): Promise<void> {
-  const runtimeManager = getRuntimeManager();
-  if (runtimeManager.isServerless || !runtimeManager.isLazy) {
-    return;
-  }
-  if (isAppNotStarted(store.get(connectionAtom).state)) {
-    store.set(connectionAtom, { state: ConnectionState.CONNECTING });
-  }
-  try {
-    await runtimeManager.start();
-  } catch (error) {
-    if (store.get(connectionAtom).state === ConnectionState.CONNECTING) {
-      store.set(connectionAtom, {
-        state: ConnectionState.CLOSED,
-        code: ConnectionClosedReason.KERNEL_STARTUP_ERROR,
-        reason: prettyError(error),
-      });
-    }
-    throw error;
-  }
-}
-
 export function asRemoteURL(path: string): URL {
   if (path.startsWith("http")) {
     return new URL(path);

package/src/core/runtime/runtime.ts

@@ -14,13 +14,10 @@ const knownQueryParams = new Set(Object.values(KnownQueryParams));
 
 export class RuntimeManager {
   private initialHealthyCheck = new Deferred<void>();
-  private starting: Promise<void> | undefined;
   private config: RuntimeConfig;
-  private lazy: boolean;
 
-  public constructor(config: RuntimeConfig, lazy = false) {
+  public constructor(config: RuntimeConfig) {
     this.config = config;
-    this.lazy = lazy;
     // Validate the URL on construction
     try {
       new URL(this.config.url);
@@ -30,14 +27,6 @@ export class RuntimeManager {
         { cause: error },
       );
     }
-
-    if (!this.lazy) {
-      this.init();
-    }
-  }
-
-  public get isLazy(): boolean {
-    return this.lazy;
   }
 
   public get httpURL(): URL {
@@ -346,25 +335,6 @@ export class RuntimeManager {
     return this.initialHealthyCheck.promise;
   }
 
-  /**
-   * Start the runtime once and wait until it is healthy.
-   *
-   * A run, the connect button, and the notebook stream can each ask for
-   * the runtime, so the first call starts it and later calls join that
-   * attempt. An attempt that gave up is forgotten, so the next call tries
-   * again instead of failing on the old result.
-   */
-  public start(): Promise<void> {
-    this.starting ??= this.init()
-      .then(() => this.waitForHealthy())
-      .catch((error: unknown) => {
-        this.starting = undefined;
-        this.initialHealthyCheck = new Deferred<void>();
-        throw error;
-      });
-    return this.starting;
-  }
-
   public headers(): KnownHeaders {
     const headers: KnownHeaders = {
       "Marimo-Session-Id": getSessionId(),

package/src/core/runtime/types.ts

@@ -5,11 +5,6 @@ export interface RuntimeConfig {
    * The URL of the runtime server.
    */
   url: string;
-  /**
-   * If true, the runtime will not be loaded until the user interacts with the notebook.
-   * If false, the runtime will be loaded immediately.
-   */
-  readonly lazy: boolean;
   /**
    * The server token for the runtime (Skew protection token)
    */

package/src/core/session/__tests__/useNotebookReplica.hook.test.tsx

@@ -20,9 +20,9 @@ import { activeNotebookReplicaAtom } from "../active-notebook";
 vi.mock("../backend", () => ({ createEditorBackend: vi.fn() }));
 
 /** A host-framed native notification. */
-const reconnected = {
+const notification = {
   event: "marimo",
-  data: { marimo: { op: "reconnected" } },
+  data: { marimo: { op: "interrupted" } },
 };
 
 /** A transport whose connections the test drives. */
@@ -41,7 +41,7 @@ function makeTransport() {
     transport,
     opened,
     /** Open the latest connection and deliver a host-framed notification. */
-    notify: () => opened.at(-1)?.receive(reconnected),
+    notify: () => opened.at(-1)?.receive(notification),
   };
 }
 
@@ -153,7 +153,7 @@ describe("useNotebookReplica", () => {
     act(() => fake.notify());
     expect(options.onNotification).not.toHaveBeenCalled();
     expect(onNotification).toHaveBeenCalledExactlyOnceWith({
-      data: { op: "reconnected" },
+      data: { op: "interrupted" },
     });
     const [{ url }] = vi.mocked(createEditorBackend).mock.calls[0];
     expect(url()).toBe("ws://redirected/ws");
@@ -175,7 +175,7 @@ describe("useNotebookReplica", () => {
     expect(store.get(result.current.connectionAtom)).toEqual({
       state: ConnectionState.OPEN,
     });
-    act(() => fake.opened.forEach((attempt) => attempt.receive(reconnected)));
+    act(() => fake.opened.forEach((attempt) => attempt.receive(notification)));
     expect(options.onNotification).toHaveBeenCalledOnce();
     unmount();
     expect(active.signal.aborted).toBe(true);

package/src/core/session/__tests__/useNotebookSession.hook.test.tsx

@@ -55,6 +55,7 @@ import { classifyCloseEvent } from "../../transports/connection-state";
 import { createEditorBackend } from "../backend";
 import {
   fakeBackend,
+  fixtureEvents,
   fixtureMessages,
 } from "../../notebook/replica/__tests__/fixtures";
 import { useNotebookSession } from "../useNotebookSession";
@@ -114,6 +115,15 @@ function connection(fake: FakeTransport) {
     /** Deliver a notification as the session routes frame it. */
     send: (notification: unknown) =>
       current().receive({ event: "marimo", data: { marimo: notification } }),
+    /** Deliver a snapshot of the notebook, ending in the stream's `ready`. */
+    ready: () => {
+      for (const message of fixtureMessages("notebook-events.sse")) {
+        current().receive(message);
+        if (message.event === "ready") {
+          break;
+        }
+      }
+    },
     /** End the connection so the stream reconnects. */
     drop: () => current().drop(),
     /** Close the connection with a reason the editor treats as final. */
@@ -129,10 +139,7 @@ function connection(fake: FakeTransport) {
 function makeRuntimeManager(
   reconcileFromHealth = vi.fn<() => Promise<boolean>>().mockResolvedValue(true),
 ) {
-  const runtime = new RuntimeManager(
-    { url: "http://localhost", lazy: true },
-    true,
-  );
+  const runtime = new RuntimeManager({ url: "http://localhost" });
   vi.spyOn(runtime, "reconcileFromHealth").mockImplementation(
     reconcileFromHealth,
   );
@@ -350,11 +357,67 @@ describe("useNotebookSession messages", () => {
   });
 });
 
-it.each(["kernel-ready", "reconnected"])(
-  "waits for %s before marking the session connected",
-  async (op) => {
+it("waits for the stream's snapshot before marking the session connected", async () => {
+  const store = createStore();
+  store.set(connectionAtom, { state: ConnectionState.CONNECTING });
+  const fake = withTransport();
+  vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
+  renderConnectionHook(store);
+  await started();
+  const conn = connection(fake);
+
+  await act(async () => conn.open());
+  expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);
+
+  // A host that is not marimo never sends kernel-ready.
+  for (const message of fixtureMessages("notebook-events.sse")) {
+    act(() => conn.receive(message));
+    if (message.event === "ready") {
+      break;
+    }
+    expect(store.get(connectionAtom)).toEqual({
+      state: ConnectionState.CONNECTING,
+    });
+  }
+  expect(store.get(connectionAtom)).toEqual({ state: ConnectionState.OPEN });
+});
+
+it("waits for another ready snapshot after the stream resets", async () => {
+  const store = createStore();
+  const fake = withTransport();
+  vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
+  renderConnectionHook(store);
+  await started();
+  const conn = connection(fake);
+  act(() => {
+    conn.open();
+    conn.ready();
+  });
+  expect(store.get(connectionAtom)).toEqual({ state: ConnectionState.OPEN });
+
+  act(() => conn.receive({ event: "reset", data: {} }));
+  expect(store.get(connectionAtom)).toEqual({
+    state: ConnectionState.CONNECTING,
+    phase: "reconnecting",
+  });
+
+  for (const message of fixtureMessages("notebook-events.sse")) {
+    act(() => conn.receive(message));
+    if (message.event === "ready") {
+      break;
+    }
+    expect(store.get(connectionAtom)).toEqual({
+      state: ConnectionState.CONNECTING,
+      phase: "reconnecting",
+    });
+  }
+  expect(store.get(connectionAtom)).toEqual({ state: ConnectionState.OPEN });
+});
+
+it("does not mark a static page connected", async () => {
+  window.__MARIMO_STATIC__ = { files: {} };
+  try {
     const store = createStore();
-    store.set(connectionAtom, { state: ConnectionState.CONNECTING });
     const fake = withTransport();
     vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
     renderConnectionHook(store);
@@ -362,24 +425,38 @@ it.each(["kernel-ready", "reconnected"])(
     const conn = connection(fake);
 
     await act(async () => conn.open());
-    expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);
+    act(() => conn.ready());
+    expect(store.get(connectionAtom).state).not.toBe(ConnectionState.OPEN);
+  } finally {
+    delete window.__MARIMO_STATIC__;
+  }
+});
 
-    act(() =>
-      conn.send({
-        op,
-        layout: null,
-        resumed: true,
-        ui_values: {},
-        app_config: { width: "normal" },
-        kiosk: false,
-        capabilities: { terminal: false },
-        auto_instantiated: false,
-        consumer_capabilities: { edit: true, interact: true },
-      }),
-    );
-    expect(store.get(connectionAtom).state).toBe(ConnectionState.OPEN);
-  },
-);
+it("does not mark the session connected on kernel-ready alone", async () => {
+  const store = createStore();
+  store.set(connectionAtom, { state: ConnectionState.CONNECTING });
+  const fake = withTransport();
+  vi.mocked(useRuntimeManager).mockReturnValue(makeRuntimeManager());
+  renderConnectionHook(store);
+  await started();
+  const conn = connection(fake);
+  await act(async () => conn.open());
+
+  act(() =>
+    conn.send({
+      op: "kernel-ready",
+      layout: null,
+      resumed: true,
+      ui_values: {},
+      app_config: { width: "normal" },
+      kiosk: false,
+      capabilities: { terminal: false },
+      auto_instantiated: false,
+      consumer_capabilities: { edit: true, interact: true },
+    }),
+  );
+  expect(store.get(connectionAtom).state).toBe(ConnectionState.CONNECTING);
+});
 
 describe("connection notice", () => {
   beforeEach(() => vi.useFakeTimers());
@@ -455,7 +532,7 @@ describe("connection notice", () => {
       screen.getByRole("button", { name: "Starting kernel… Open Packages" }),
     ).toBeVisible();
     expect(screen.queryByText(/Elapsed/)).not.toBeInTheDocument();
-    send({ op: "reconnected" });
+    act(() => conn.ready());
     expect(
       screen.queryByRole("region", { name: "Notebook startup" }),
     ).not.toBeInTheDocument();
@@ -498,7 +575,7 @@ describe("connection notice", () => {
 
   it("restores completed startup output without putting a connected kernel back into startup", async () => {
     const { store, conn, send } = await renderNotice();
-    send({ op: "reconnected" });
+    act(() => conn.ready());
     send({
       op: "startup-progress",
       phase: "starting-kernel",
@@ -515,6 +592,25 @@ describe("connection notice", () => {
       screen.queryByRole("region", { name: "Notebook startup" }),
     ).not.toBeInTheDocument();
 
+    const notebook = fixtureEvents("notebook-events.sse").find(
+      (event) => event.event === "notebook",
+    );
+    if (!notebook) {
+      throw new Error("Missing notebook fixture");
+    }
+    act(() =>
+      conn.receive({
+        ...notebook,
+        data: {
+          notebook: { ...notebook.data.notebook, name: "Renamed notebook" },
+        },
+      }),
+    );
+    expect(store.get(startupProgressAtom)).toEqual({
+      phase: "starting-kernel",
+      logs: "Kernel startup output\n",
+    });
+
     // A new connection starts from the next session's authoritative snapshot.
     await act(async () => conn.drop());
     await act(async () => vi.advanceTimersByTime(2000));
@@ -523,7 +619,7 @@ describe("connection notice", () => {
   });
 
   it("does not flash a notice when startup finishes within the delay", async () => {
-    const { send } = await renderNotice();
+    const { conn, send } = await renderNotice();
     send({
       op: "startup-progress",
       phase: "preparing-environment",
@@ -541,7 +637,7 @@ describe("connection notice", () => {
     expect(
       screen.queryByRole("region", { name: "Notebook startup" }),
     ).not.toBeInTheDocument();
-    send({ op: "reconnected" });
+    act(() => conn.ready());
     act(() => vi.advanceTimersByTime(500));
     expect(
       screen.queryByRole("region", { name: "Notebook startup" }),

package/src/core/session/connection-utils.ts

@@ -22,13 +22,6 @@ export function isAppConnected(state: ConnectionState): boolean {
   return state === ConnectionState.OPEN;
 }
 
-/**
- * Check if the app is in a closing state
- */
-export function isAppClosing(state: ConnectionState): boolean {
-  return state === ConnectionState.CLOSING;
-}
-
 /**
  * Check if the app is in a not started state
  */
@@ -41,9 +34,7 @@ export function isAppNotStarted(state: ConnectionState): boolean {
  */
 export function isAppInteractionDisabled(state: ConnectionState): boolean {
   return (
-    state === ConnectionState.CLOSED ||
-    state === ConnectionState.CLOSING ||
-    state === ConnectionState.CONNECTING
+    state === ConnectionState.CLOSED || state === ConnectionState.CONNECTING
   );
 }
 
@@ -56,12 +47,9 @@ export function getConnectionTooltip(state: ConnectionState): string {
       return "App disconnected";
     case ConnectionState.CONNECTING:
       return "Connecting to a runtime ...";
-    case ConnectionState.CLOSING:
-      return "App disconnecting...";
     case ConnectionState.OPEN:
-      return "";
     case ConnectionState.NOT_STARTED:
-      return "Click to connect to a runtime";
+      return "";
     default:
       return "";
   }

package/src/core/session/useNotebookSession.tsx

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import { invalidatePackageData } from "@/core/packages/package-data";
-import { useAtom, useAtomValue, useSetAtom, useStore } from "jotai";
+import { atom, useAtom, useAtomValue, useSetAtom, useStore } from "jotai";
 import { useEffect, useLayoutEffect, useMemo } from "react";
 import { useErrorBoundary } from "react-error-boundary";
 import { toast } from "@/components/ui/use-toast";
@@ -142,8 +142,6 @@ export function useNotebookSession(opts: {
         return;
       }
       case "kernel-ready": {
-        setKernelStartupError(null);
-        setConnection({ state: ConnectionState.OPEN });
         setInitialRunCompleted(
           Boolean(msg.data.resumed || msg.data.auto_instantiated),
         );
@@ -359,11 +357,6 @@ export function useNotebookSession(opts: {
         DownloadStorage.resolve(msg.data.request_id as RequestId, msg.data);
         return;
 
-      case "reconnected":
-        setKernelStartupError(null);
-        setConnection({ state: ConnectionState.OPEN });
-        return;
-
       case "focus-cell":
         focusAndScrollCellOutputIntoView(msg.data.cell_id);
         return;
@@ -454,14 +447,25 @@ export function useNotebookSession(opts: {
 
   // Subscribe before passive connection setup: static/WASM transports can emit synchronously.
   useLayoutEffect(() => {
+    const readyAtom = atom((get) => get(replica.notebookAtom) !== null);
     const updateConnection = () => {
-      const status = store.get(replica.connectionAtom);
+      let status = store.get(replica.connectionAtom);
       if (status.state === ConnectionState.NOT_STARTED) {
         return;
       }
       if (status.state === ConnectionState.OPEN) {
         updateStartupProgress(null);
-        return; // kernel-ready, not the socket, establishes session readiness.
+        // The stream's snapshot, not the socket, establishes readiness. A
+        // static page has a snapshot but no host to be connected to.
+        if (isStaticNotebook()) {
+          return;
+        }
+        if (store.get(readyAtom)) {
+          setKernelStartupError(null);
+          setConnection({ state: ConnectionState.OPEN });
+          return;
+        }
+        status = { state: ConnectionState.CONNECTING };
       }
       if (status.state === ConnectionState.CONNECTING) {
         setKernelStartupError(null);
@@ -486,9 +490,12 @@ export function useNotebookSession(opts: {
         return status;
       });
     };
-    const unsubscribe = store.sub(replica.connectionAtom, updateConnection);
+    const unsubscribes = [
+      store.sub(replica.connectionAtom, updateConnection),
+      store.sub(readyAtom, updateConnection),
+    ];
     updateConnection();
-    return unsubscribe;
+    return () => unsubscribes.forEach((unsubscribe) => unsubscribe());
   }, [
     replica,
     store,

package/src/mount.tsx

@@ -40,11 +40,11 @@ import {
   viewStateAtom,
 } from "./core/mode";
 import { cleanupAuthQueryParams } from "./core/network/auth";
-import { connectionAtom } from "./core/network/connection";
 import { requestClientAtom } from "./core/network/requests";
 import { resolveRequestClient } from "./core/network/resolve";
 import {
   DEFAULT_RUNTIME_CONFIG,
+  getRuntimeManager,
   runtimeConfigAtom,
 } from "./core/runtime/config";
 import {
@@ -63,7 +63,6 @@ import { maybeRegisterVSCodeBindings } from "./core/vscode/vscode-bindings";
 import type { FileStore } from "./core/wasm/store";
 import { notebookFileStore } from "./core/wasm/store";
 import { embeddedSnapshotAtom } from "./core/session/embedded";
-import { ConnectionState } from "./core/session/types";
 import {
   handleWidgetMessage,
   WIDGET_REGISTRY,
@@ -282,8 +281,6 @@ const mountOptionsSchema = z.object({
     .array(
       z.looseObject({
         url: z.string(),
-        // Lazy by default, but can be overridden by the runtime config
-        lazy: z.boolean().default(true),
         authToken: z.string().nullish(),
       }),
     )
@@ -359,17 +356,14 @@ function initStore(options: unknown) {
       ...firstRuntimeConfig,
       serverToken: parsedOptions.data.serverToken,
     });
-    // If the remote runtime is not lazy, start it in CONNECTING
-    if (!firstRuntimeConfig.lazy && !isStaticNotebook()) {
-      store.set(connectionAtom, { state: ConnectionState.CONNECTING });
-    }
   } else {
     store.set(runtimeConfigAtom, {
       ...DEFAULT_RUNTIME_CONFIG,
-      lazy: false,
       serverToken: parsedOptions.data.serverToken,
     });
   }
+  // The page's runtime is known from here on, so look for it now.
+  void getRuntimeManager().init();
 
   // The notebook the page was served with shows until the host answers.
   const { snapshot, cellRuntime } = readExport({

package/src/utils/errors.ts

@@ -94,10 +94,3 @@ export class FunctionNotFoundError extends Error {
     this.name = "FunctionNotFoundError";
   }
 }
-
-export class NoKernelConnectedError extends Error {
-  public constructor(message = "Not yet connected to a kernel.") {
-    super(message);
-    this.name = "NoKernelConnectedError";
-  }
-}