@marimo-team/islands 0.23.15-dev7 → 0.23.15-dev72

package/src/core/islands/parse.ts

@@ -2,6 +2,7 @@
 
 import {
   ISLAND_DATA_ATTRIBUTES,
+  ISLAND_SOURCE_CHANGED_EVENT,
   ISLAND_TAG_NAMES,
   ISLANDS_JSON_SCRIPT_TYPE,
 } from "@/core/islands/constants";
@@ -74,12 +75,15 @@ interface MarimoIslandPayloadCell {
   displayOutput: boolean;
 }
 
+const retainedPayloadCellIds = new WeakMap<HTMLElement, string>();
+
 /**
  * Parses marimo island apps from the DOM
  * @param root - Root element to search within (defaults to document)
  */
 export function parseMarimoIslandApps(
   root: Document | Element = document,
+  options: { materialize?: boolean } = {},
 ): MarimoIslandApp[] {
   const embeds = [
     ...root.querySelectorAll<HTMLElement>(ISLAND_TAG_NAMES.ISLAND),
@@ -90,11 +94,12 @@ export function parseMarimoIslandApps(
     return [];
   }
 
+  const materialize = options.materialize ?? true;
   if (payloads.length > 0) {
-    return parsePayloadBackedApps(embeds, payloads);
+    return parsePayloadBackedApps({ embeds, materialize, payloads });
   }
 
-  return parseIslandElementsIntoApps(embeds);
+  return parseIslandElementsIntoApps(embeds, materialize);
 }
 
 /**
@@ -103,6 +108,7 @@ export function parseMarimoIslandApps(
  */
 export function parseIslandElementsIntoApps(
   embeds: HTMLElement[],
+  materialize = true,
 ): MarimoIslandApp[] {
   const apps = new Map<string, MarimoIslandApp>();
 
@@ -140,16 +146,24 @@ export function parseIslandElementsIntoApps(
     });
 
     // Add data-cell-idx attribute to the island element
-    embed.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, idx.toString());
+    if (materialize) {
+      embed.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, idx.toString());
+      embed.dispatchEvent(new Event(ISLAND_SOURCE_CHANGED_EVENT));
+    }
   }
 
   return [...apps.values()];
 }
 
-function parsePayloadBackedApps(
-  embeds: HTMLElement[],
-  payloads: MarimoIslandPayload[],
-): MarimoIslandApp[] {
+function parsePayloadBackedApps({
+  embeds,
+  materialize,
+  payloads,
+}: {
+  embeds: HTMLElement[];
+  materialize: boolean;
+  payloads: MarimoIslandPayload[];
+}): MarimoIslandApp[] {
   const apps = new Map<string, MarimoIslandApp>();
   const matchedPayloadCells = new Map<MarimoIslandPayloadCell, HTMLElement>();
   const consumedEmbeds = new Set<HTMLElement>();
@@ -169,7 +183,9 @@ function parsePayloadBackedApps(
       }
       consumedEmbeds.add(embed);
       matchedPayloadCells.set(cell, embed);
-      materializeIslandPayload(embed, cell);
+      if (materialize) {
+        materializeIslandPayload(embed, cell);
+      }
       hasMatchedIsland = true;
     }
     // Only payloads matched to island anchors can start runtime apps.
@@ -215,7 +231,7 @@ function parsePayloadBackedApps(
         appCell.disabled = true;
       }
       app.cells.push(appCell);
-      if (cell.reactive) {
+      if (materialize && cell.reactive) {
         embed?.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, idx.toString());
       }
     }
@@ -223,12 +239,15 @@ function parsePayloadBackedApps(
 
   // A supported payload is the runtime source for its app. Extra same-app DOM
   // islands are disconnected from runtime binding.
-  for (const embed of embeds) {
-    const appId = embed.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
-    if (appId && payloadAppIds.has(appId) && !consumedEmbeds.has(embed)) {
-      embed.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID);
-      embed.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
-      embed.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "false");
+  if (materialize) {
+    for (const embed of embeds) {
+      const appId = embed.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
+      if (appId && payloadAppIds.has(appId) && !consumedEmbeds.has(embed)) {
+        embed.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID);
+        embed.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
+        embed.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "false");
+        consumedEmbeds.add(embed);
+      }
     }
   }
 
@@ -237,7 +256,16 @@ function parsePayloadBackedApps(
     return !appId || !payloadAppIds.has(appId);
   });
 
-  return [...apps.values(), ...parseIslandElementsIntoApps(domOnlyEmbeds)];
+  if (materialize) {
+    for (const embed of consumedEmbeds) {
+      embed.dispatchEvent(new Event(ISLAND_SOURCE_CHANGED_EVENT));
+    }
+  }
+
+  return [
+    ...apps.values(),
+    ...parseIslandElementsIntoApps(domOnlyEmbeds, materialize),
+  ];
 }
 
 function findMatchingIsland({
@@ -257,7 +285,8 @@ function findMatchingIsland({
     }
     return (
       embed.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID) === appId &&
-      embed.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID) === cell.cellId
+      (embed.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID) ??
+        retainedPayloadCellIds.get(embed)) === cell.cellId
     );
   });
 }
@@ -266,6 +295,7 @@ function materializeIslandPayload(
   embed: HTMLElement,
   cell: MarimoIslandPayloadCell,
 ): void {
+  retainedPayloadCellIds.set(embed, cell.cellId);
   embed.setAttribute(
     ISLAND_DATA_ATTRIBUTES.REACTIVE,
     JSON.stringify(cell.reactive),
@@ -304,6 +334,22 @@ function ensureIslandChild(embed: HTMLElement, tagName: string): HTMLElement {
  * @param embed - The island HTML element
  * @returns Cell data or null if invalid
  */
+const retainedIslandSources = new WeakMap<
+  HTMLElement,
+  { output: string; code: string }
+>();
+
+export function retainIslandSource(
+  embed: HTMLElement,
+  source: { output: string; code: string },
+): void {
+  if (source.code) {
+    retainedIslandSources.set(embed, source);
+  } else {
+    retainedIslandSources.delete(embed);
+  }
+}
+
 export function parseIslandElement(
   embed: HTMLElement,
 ): { output: string; code: string } | null {
@@ -312,14 +358,15 @@ export function parseIslandElement(
   );
   const code = extractIslandCodeFromEmbed(embed);
 
-  if (!cellOutput || !code) {
-    return null;
+  if (cellOutput && code) {
+    return {
+      output: cellOutput.innerHTML,
+      code: code,
+    };
   }
 
-  return {
-    output: cellOutput.innerHTML,
-    code: code,
-  };
+  const retained = retainedIslandSources.get(embed);
+  return retained?.code ? retained : null;
 }
 
 export function createMarimoFile(app: {

package/src/core/islands/state.ts

@@ -11,6 +11,15 @@ import { atom } from "jotai";
  */
 export const islandsInitializedAtom = atom<boolean | string>(false);
 
+/** Pending initial session generations. Null waits for a session to start. */
+export const islandsPendingInitialRunsAtom = atom<ReadonlySet<number> | null>(
+  new Set<number>(),
+);
+
+export const islandsHydratedAtom = atom(
+  (get) => get(islandsPendingInitialRunsAtom)?.size === 0,
+);
+
 /**
  * Whether the user has tried to interact with the islands.
  */

package/src/core/islands/worker/__tests__/controller.test.ts

@@ -0,0 +1,173 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { PyodideInterface } from "pyodide";
+import { describe, expect, it, vi } from "vitest";
+import { ReadonlyWasmController } from "../controller";
+
+class TestController extends ReadonlyWasmController {
+  setPyodide(pyodide: PyodideInterface) {
+    this.pyodide = pyodide;
+  }
+}
+
+function createSessionResources(
+  stopImplementation: () => Promise<void> = () => Promise.resolve(),
+) {
+  const bridge = { destroy: vi.fn() };
+  const init = Object.assign(vi.fn(), { destroy: vi.fn() });
+  const stop = Object.assign(vi.fn(stopImplementation), {
+    destroy: vi.fn(),
+  });
+  const packages = { destroy: vi.fn(), toJs: () => [] };
+  const sessionResources = Object.assign([bridge, init, packages, stop], {
+    destroy: vi.fn(),
+  });
+
+  return { bridge, init, packages, sessionResources, stop };
+}
+
+function createPyodideStub(
+  sessions = Array.from({ length: 4 }, () => createSessionResources()),
+) {
+  const [first] = sessions;
+  if (!first) {
+    throw new Error("At least one session is required");
+  }
+  const loadPackagesFromImports = vi.fn().mockResolvedValue(undefined);
+  const pyodide = {
+    runPython: vi
+      .fn()
+      .mockImplementation(() => sessions.shift()?.sessionResources),
+    loadPackagesFromImports,
+    loadedPackages: {},
+    runPythonAsync: vi.fn(),
+  } as unknown as PyodideInterface;
+
+  return {
+    ...first,
+    loadPackagesFromImports,
+    pyodide,
+  };
+}
+
+function startSession(controller: TestController, code: string) {
+  return controller.startSession({
+    code,
+    filename: `${code}.py`,
+    onMessage: vi.fn(),
+  });
+}
+
+describe("WASM controller session lifecycle", () => {
+  it("stops and releases the active session", async () => {
+    const { init, packages, pyodide, sessionResources, stop } =
+      createPyodideStub();
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+
+    await startSession(controller, "current");
+    await vi.waitFor(() => expect(init).toHaveBeenCalledOnce());
+    await controller.stopSession();
+
+    expect(stop).toHaveBeenCalledOnce();
+    expect(stop.destroy).toHaveBeenCalledOnce();
+    expect(sessionResources.destroy).toHaveBeenCalledOnce();
+    expect(packages.destroy).toHaveBeenCalledOnce();
+    expect(init.destroy).toHaveBeenCalledOnce();
+  });
+
+  it("loads dependencies serially and skips superseded sessions", async () => {
+    let finishFirstLoad!: () => void;
+    const { loadPackagesFromImports, pyodide } = createPyodideStub();
+    loadPackagesFromImports
+      .mockReturnValueOnce(
+        new Promise<void>((resolve) => {
+          finishFirstLoad = resolve;
+        }),
+      )
+      .mockResolvedValueOnce(undefined);
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+
+    await startSession(controller, "first_dependency");
+    await startSession(controller, "superseded_dependency");
+    await controller.stopSession();
+    await startSession(controller, "current_dependency");
+
+    expect(loadPackagesFromImports).toHaveBeenCalledOnce();
+    finishFirstLoad();
+    await vi.waitFor(() =>
+      expect(loadPackagesFromImports).toHaveBeenCalledTimes(2),
+    );
+
+    const loadedSources = loadPackagesFromImports.mock.calls.map(
+      ([source]) => source as string,
+    );
+    expect(loadedSources[1]).toContain("current_dependency");
+    expect(loadedSources.join("\n")).not.toContain("superseded_dependency");
+  });
+
+  it("stops every session created for a multi-app page", async () => {
+    const first = createSessionResources();
+    const second = createSessionResources();
+    const { pyodide } = createPyodideStub([first, second]);
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+
+    await startSession(controller, "first");
+    await startSession(controller, "second");
+    second.bridge.destroy();
+
+    expect(first.stop.destroy).not.toHaveBeenCalled();
+
+    await controller.stopSession();
+
+    expect(first.stop).toHaveBeenCalledOnce();
+    expect(second.stop).toHaveBeenCalledOnce();
+    expect(first.stop.destroy).toHaveBeenCalledOnce();
+    expect(second.stop.destroy).toHaveBeenCalledOnce();
+  });
+
+  it("continues stopping sessions after one stop fails", async () => {
+    const failure = new Error("stop failed");
+    const first = createSessionResources(() => Promise.reject(failure));
+    const second = createSessionResources();
+    const { pyodide } = createPyodideStub([first, second]);
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+
+    await startSession(controller, "first");
+    await startSession(controller, "second");
+
+    await expect(controller.stopSession()).rejects.toThrow("stop failed");
+    expect(first.stop).toHaveBeenCalledOnce();
+    expect(second.stop).toHaveBeenCalledOnce();
+    expect(first.stop.destroy).not.toHaveBeenCalled();
+    expect(second.stop.destroy).toHaveBeenCalledOnce();
+
+    first.stop.mockResolvedValueOnce(undefined);
+    await controller.stopSession();
+
+    expect(first.stop).toHaveBeenCalledTimes(2);
+    expect(first.stop.destroy).toHaveBeenCalledOnce();
+    expect(second.stop).toHaveBeenCalledOnce();
+  });
+
+  it("reports and retries a falsy stop failure", async () => {
+    const session = createSessionResources(() => Promise.reject(false));
+    const { pyodide } = createPyodideStub([session]);
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+
+    await startSession(controller, "current");
+
+    await expect(controller.stopSession()).rejects.toBe(false);
+    expect(session.stop.destroy).not.toHaveBeenCalled();
+
+    session.stop.mockResolvedValueOnce(undefined);
+    await controller.stopSession();
+
+    expect(session.stop).toHaveBeenCalledTimes(2);
+    expect(session.stop.destroy).toHaveBeenCalledOnce();
+  });
+});

package/src/core/islands/worker/worker.tsx

@@ -1,6 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import type { PyodideInterface } from "pyodide";
+import type { PyProxy } from "pyodide/ffi";
 import {
   createRPC,
   createRPCRequestHandler,
@@ -16,7 +17,6 @@ import { MessageBuffer } from "@/core/wasm/worker/message-buffer";
 import type { RawBridge, SerializedBridge } from "@/core/wasm/worker/types";
 import type { JsonString } from "@/utils/json/base64";
 import { Logger } from "@/utils/Logger";
-import { Deferred } from "../../../utils/Deferred";
 import { prettyError } from "../../../utils/errors";
 import { invariant } from "../../../utils/invariant";
 import { ReadonlyWasmController } from "./controller";
@@ -45,64 +45,141 @@ async function loadPyodideAndPackages() {
 }
 
 const pyodideReadyPromise = loadPyodideAndPackages();
-const messageBuffer = new MessageBuffer(
-  (message: JsonString<NotificationPayload>) => {
-    rpc.send.kernelMessage({ message });
-  },
-);
-const bridgeReady = new Deferred<SerializedBridge>();
+export interface IslandsKernelMessage {
+  message: JsonString<NotificationPayload>;
+  sessionGeneration: number;
+}
+
+const messageBuffer = new MessageBuffer<IslandsKernelMessage>((payload) => {
+  rpc.send.kernelMessage(payload);
+});
+interface SessionRequest {
+  code: string;
+  appId: string;
+  sessionGeneration: number;
+}
+
+let activeSession:
+  | (Omit<SessionRequest, "code"> & { bridge: SerializedBridge })
+  | undefined;
+let sessionQueue = Promise.resolve();
+
+async function startSession(
+  opts: SessionRequest,
+  replace: boolean,
+): Promise<void> {
+  await pyodideReadyPromise;
+
+  try {
+    invariant(self.controller, "Controller not loaded");
+    if (replace) {
+      await stopActiveSession();
+    }
+    const notebook = await self.controller.mountFilesystem({
+      code: opts.code,
+      filename: `app-${opts.appId}.py`,
+    });
+    const nextBridge = await self.controller.startSession({
+      ...notebook,
+      onMessage: (message) => {
+        messageBuffer.push({
+          message,
+          sessionGeneration: opts.sessionGeneration,
+        });
+      },
+    });
+    if (activeSession) {
+      (nextBridge as unknown as PyProxy).destroy();
+    } else {
+      activeSession = {
+        appId: opts.appId,
+        bridge: nextBridge,
+        sessionGeneration: opts.sessionGeneration,
+      };
+    }
+    rpc.send.initialized({});
+  } catch (error) {
+    rpc.send.initializedError({
+      error: prettyError(error),
+    });
+    throw error;
+  }
+}
+
+async function stopActiveSession(): Promise<void> {
+  const session = activeSession;
+  await self.controller.stopSession();
+  activeSession = undefined;
+  (session?.bridge as unknown as PyProxy | undefined)?.destroy();
+}
+
+function enqueueSession<T>(operation: () => Promise<T>): Promise<T> {
+  const result = sessionQueue.then(operation);
+  sessionQueue = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  return result;
+}
 
 // Handle RPC requests
 const requestHandler = createRPCRequestHandler({
   /**
    * Start the session
    */
-  startSession: async (opts: { code: string; appId: string }) => {
-    await pyodideReadyPromise; // Make sure loading is done
+  startSession: async (opts: SessionRequest) => {
+    await enqueueSession(() => startSession(opts, false));
+  },
+
+  replaceSession: async (opts: SessionRequest) => {
+    await enqueueSession(() => startSession(opts, true));
+  },
 
-    try {
+  stopSession: async (opts: { appId: string; sessionGeneration: number }) => {
+    await enqueueSession(async () => {
+      if (
+        activeSession?.appId !== opts.appId ||
+        activeSession?.sessionGeneration !== opts.sessionGeneration
+      ) {
+        return;
+      }
       invariant(self.controller, "Controller not loaded");
-      const notebook = await self.controller.mountFilesystem({
-        code: opts.code,
-        filename: `app-${opts.appId}.py`,
-      });
-      const bridge = await self.controller.startSession({
-        ...notebook,
-        onMessage: messageBuffer.push,
-      });
-      bridgeReady.resolve(bridge);
-      rpc.send.initialized({});
-    } catch (error) {
-      rpc.send.initializedError({
-        error: prettyError(error),
-      });
-    }
-    return;
+      await stopActiveSession();
+    });
   },
 
   /**
    * Load packages
    */
-  loadPackages: async (code: string) => {
+  loadPackages: async (opts: {
+    appId: string;
+    code: string;
+    sessionGeneration: number;
+  }) => {
     await pyodideReadyPromise; // Make sure loading is done
+    await enqueueSession(async () => {
+      requireActiveBridge(opts);
 
-    if (shouldLoadDuckDBPackages(code)) {
-      // Add pandas and duckdb to the code for mo.sql and for remote duckdb sources
-      code = `import pandas\n${code}`;
-      code = `import duckdb\n${code}`;
-      code = `import sqlglot\n${code}`;
-
-      // Polars + SQL requires pyarrow, and installing
-      // after notebook load does not work. As a heuristic,
-      // if it appears that the notebook uses polars, add pyarrow.
-      if (code.includes("polars")) {
-        code = `import pyarrow\n${code}`;
+      let { code } = opts;
+
+      if (shouldLoadDuckDBPackages(code)) {
+        // Add pandas and duckdb to the code for mo.sql and for remote duckdb sources
+        code = `import pandas\n${code}`;
+        code = `import duckdb\n${code}`;
+        code = `import sqlglot\n${code}`;
+
+        // Polars + SQL requires pyarrow, and installing
+        // after notebook load does not work. As a heuristic,
+        // if it appears that the notebook uses polars, add pyarrow.
+        if (code.includes("polars")) {
+          code = `import pyarrow\n${code}`;
+        }
       }
-    }
 
-    await self.pyodide.loadPackagesFromImports(code, {
-      messageCallback: Logger.log,
-      errorCallback: Logger.error,
+      await self.pyodide.loadPackagesFromImports(code, {
+        messageCallback: Logger.log,
+        errorCallback: Logger.error,
+      });
     });
   },
 
@@ -110,37 +187,56 @@ const requestHandler = createRPCRequestHandler({
    * Call a function on the bridge
    */
   bridge: async (opts: {
+    appId: string;
     functionName: keyof RawBridge;
     payload: {} | undefined | null;
+    sessionGeneration: number;
   }) => {
     await pyodideReadyPromise; // Make sure loading is done
 
     const { functionName, payload } = opts;
 
     // Perform the function call to the Python bridge
-    const bridge = await bridgeReady.promise;
-
-    // Serialize the payload
-    const payloadString =
-      payload == null
-        ? null
-        : typeof payload === "string"
-          ? payload
-          : JSON.stringify(payload);
-
-    // Make the request
-    const response =
-      payloadString == null
-        ? // @ts-expect-error ehh TypeScript
-          await bridge[functionName]()
-        : // @ts-expect-error ehh TypeScript
-          await bridge[functionName](payloadString);
-
-    // Post the response back to the main thread
-    return typeof response === "string" ? JSON.parse(response) : response;
+    return enqueueSession(async () => {
+      const bridge = requireActiveBridge(opts);
+
+      // Serialize the payload
+      const payloadString =
+        payload == null
+          ? null
+          : typeof payload === "string"
+            ? payload
+            : JSON.stringify(payload);
+
+      // Make the request
+      const response =
+        payloadString == null
+          ? // @ts-expect-error ehh TypeScript
+            await bridge[functionName]()
+          : // @ts-expect-error ehh TypeScript
+            await bridge[functionName](payloadString);
+
+      // Post the response back to the main thread
+      return typeof response === "string" ? JSON.parse(response) : response;
+    });
   },
 });
 
+function requireActiveBridge(opts: {
+  appId: string;
+  sessionGeneration: number;
+}): SerializedBridge {
+  const session = activeSession;
+  if (
+    !session ||
+    opts.appId !== session.appId ||
+    opts.sessionGeneration !== session.sessionGeneration
+  ) {
+    throw new Error("The marimo app session is no longer active.");
+  }
+  return session.bridge;
+}
+
 // create the iframe's schema
 export type WorkerSchema = RPCSchema<
   {
@@ -148,7 +244,7 @@ export type WorkerSchema = RPCSchema<
       // Emitted when the worker is ready
       ready: {};
       // Emitted when the kernel sends a message
-      kernelMessage: { message: JsonString<NotificationPayload> };
+      kernelMessage: IslandsKernelMessage;
       // Emitted when the Pyodide is initialized
       initialized: {};
       // Emitted when the Pyodide fails to initialize

package/src/core/network/__tests__/requests-lazy.test.ts

@@ -54,6 +54,24 @@ describe("createLazyRequests", () => {
     } as unknown as EditRequests & RunRequests;
   });
 
+  it("passes server-only requests through without starting a kernel", async () => {
+    const environment = { marimo: "1.2.3" };
+    mockDelegate.getEnvironmentInfo = vi
+      .fn()
+      .mockResolvedValue(environment) as EditRequests["getEnvironmentInfo"];
+
+    const lazyRequests = createLazyRequests(
+      mockDelegate,
+      mockGetRuntimeManager,
+    );
+
+    await expect(lazyRequests.getEnvironmentInfo()).resolves.toEqual(
+      environment,
+    );
+    expect(mockInit).not.toHaveBeenCalled();
+    expect(mockDelegate.getEnvironmentInfo).toHaveBeenCalledOnce();
+  });
+
   it("should call init once before first request", async () => {
     const lazyRequests = createLazyRequests(
       mockDelegate,