@marimo-team/islands 0.25.3-dev14 → 0.25.3-dev140

package/src/core/islands/bootstrap.ts

@@ -9,11 +9,7 @@ import {
 } from "@/plugins/impl/anywidget/registry";
 import { initializePlugins } from "@/plugins/plugins";
 import { Functions } from "@/utils/functions";
-import {
-  safeExtractSetUIElementMessageBuffers,
-  type JsonString,
-} from "@/utils/json/base64";
-import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
+import { safeExtractSetUIElementMessageBuffers } from "@/utils/json/base64";
 import { Logger } from "@/utils/Logger";
 import { logNever } from "@/utils/assertNever";
 import {
@@ -30,10 +26,7 @@ import {
   handleKernelReady,
   handleRemoveUIElements,
 } from "../kernel/handlers";
-import type {
-  NotificationMessage,
-  NotificationMessageType,
-} from "../kernel/messages";
+import type { NotificationMessage } from "../kernel/messages";
 import { queryParamHandlers } from "../kernel/queryParamHandlers";
 import { RuntimeState } from "../kernel/RuntimeState";
 import { initialModeAtom } from "../mode";
@@ -126,19 +119,9 @@ export async function initializeIslands(
     }
   });
 
-  // Wire up kernel message handling
-  // The wire format is {"op": "...", "data": {"op": "...", ...}} — both
-  // the envelope and the payload carry the op. The bridge types the message
-  // as NotificationPayload (just {data}), but the actual wire format
-  // includes the outer op too.
-  // Worker metadata identifies the session that emitted the message.
-  bridge.consumeMessages(({ message, sessionGeneration }) => {
-    handleMessage(
-      message as unknown as JsonString<IslandsNotificationMessage>,
-      actions,
-      store,
-      sessionGeneration,
-    );
+  // Each notification names the session that sent it.
+  bridge.consumeNotifications((notification, sessionGeneration) => {
+    handleNotification(notification, actions, store, sessionGeneration);
   });
 
   // Track first user interaction before initialization completes
@@ -154,27 +137,15 @@ export async function initializeIslands(
   RuntimeState.INSTANCE.start(bridge.sendComponentValues);
 }
 
-type IslandsNotificationMessage = {
-  [K in NotificationMessageType]: {
-    data: Extract<NotificationMessage, { op: K }>;
-    op: K;
-  };
-}[NotificationMessageType];
-
-/**
- * Handles a single message from the kernel.
- *
- * Wire format from Python: {"op": "<name>", "data": {"op": "<name>", ...}}
- */
+/** Handles a single notification from the kernel. */
 // oxlint-disable-next-line marimo/prefer-object-params
-function handleMessage(
-  message: JsonString<IslandsNotificationMessage>,
+function handleNotification(
+  msg: NotificationMessage,
   actions: NotebookActions,
   store: Store,
   sessionGeneration: number,
 ): void {
   try {
-    const msg = jsonParseWithSpecialChar(message);
     Logger.debug("Islands received message:", msg.op);
 
     switch (msg.op) {
@@ -209,7 +180,6 @@ function handleMessage(
       case "cache-info":
       case "kernel-startup-error":
       case "notebook-document-transaction":
-      case "attachments":
         return;
 
       case "completed-run":
@@ -224,7 +194,7 @@ function handleMessage(
         return;
 
       case "kernel-ready":
-        handleKernelReady(msg.data, {
+        handleKernelReady(msg, {
           autoInstantiate: true,
           setCells: actions.setCells,
           setLayoutData: Functions.NOOP,
@@ -240,47 +210,47 @@ function handleMessage(
 
       case "send-ui-element-message":
         UI_ELEMENT_REGISTRY.broadcastMessage(
-          msg.data.ui_element,
-          msg.data.message,
-          safeExtractSetUIElementMessageBuffers(msg.data),
+          msg.ui_element,
+          msg.message,
+          safeExtractSetUIElementMessageBuffers(msg),
         );
         return;
 
       case "remove-ui-elements":
-        handleRemoveUIElements(msg.data);
+        handleRemoveUIElements(msg);
         return;
 
       case "function-call-result":
-        FUNCTIONS_REGISTRY.resolve(msg.data.function_call_id, msg.data);
+        FUNCTIONS_REGISTRY.resolve(msg.function_call_id, msg);
         return;
 
       case "cell-op":
-        handleCellNotificationeration(msg.data, actions.handleCellMessage);
+        handleCellNotificationeration(msg, actions.handleCellMessage);
         return;
 
       case "alert":
         toast({
-          title: msg.data.title,
-          description: renderHTML({ html: msg.data.description }),
-          variant: msg.data.variant,
+          title: msg.title,
+          description: renderHTML({ html: msg.description }),
+          variant: msg.variant,
         });
         return;
 
       case "query-params-append":
-        queryParamHandlers.append(msg.data);
+        queryParamHandlers.append(msg);
         return;
       case "query-params-set":
-        queryParamHandlers.set(msg.data);
+        queryParamHandlers.set(msg);
         return;
       case "query-params-delete":
-        queryParamHandlers.delete(msg.data);
+        queryParamHandlers.delete(msg);
         return;
       case "query-params-clear":
         queryParamHandlers.clear();
         return;
 
       case "model-lifecycle":
-        handleWidgetMessage(WIDGET_REGISTRY, msg.data);
+        handleWidgetMessage(WIDGET_REGISTRY, msg);
         return;
 
       case "consumer-capabilities":

package/src/core/islands/bridge.ts

@@ -5,15 +5,16 @@ import { getWorkerRPC } from "@/core/wasm/rpc";
 import { Deferred } from "@/utils/Deferred";
 import { throwNotImplemented } from "@/utils/functions";
 import { Logger } from "@/utils/Logger";
+import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
 import { generateUUID } from "@/utils/uuid";
 import { initialNotebookState, notebookAtom } from "../cells/cells";
-import type { ClientCommand } from "../kernel/messages";
+import type { ClientCommand, NotificationMessage } from "../kernel/messages";
 import type { EditRequests, RunRequests } from "../network/types";
 import { store as defaultStore } from "../state/jotai";
 import { getMarimoExportContext } from "../static/export-context";
 import { createMarimoFile, parseMarimoIslandApps } from "./parse";
 import { islandsInitializedAtom, islandsPendingInitialRunsAtom } from "./state";
-import type { IslandsKernelMessage, WorkerSchema } from "./worker/worker";
+import type { WorkerSchema } from "./worker/worker";
 import type { WorkerFactory } from "./worker-factory";
 import { DefaultWorkerFactory } from "./worker-factory";
 
@@ -52,14 +53,14 @@ interface AppSession {
  * @example
  * ```ts
  * const bridge = new IslandsPyodideBridge();
- * bridge.consumeMessages(message => console.log(message));
+ * bridge.consumeNotifications((notification) => console.log(notification.op));
  * await bridge.initializeApps();
  * ```
  */
 export class IslandsPyodideBridge implements RunRequests, EditRequests {
   private rpc: ReturnType<typeof getWorkerRPC<WorkerSchema>>;
-  private messageConsumer:
-    | ((message: IslandsKernelMessage) => void)
+  private notificationConsumer:
+    | ((notification: NotificationMessage, sessionGeneration: number) => void)
     | undefined;
   private readonly store: typeof defaultStore;
   private readonly root: Document | Element;
@@ -110,14 +111,24 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
       },
     );
 
-    this.rpc.addMessageListener("kernelMessage", (message) => {
-      // A stopped session can still have messages in transit after the next
-      // app takes ownership of the shared frontend state.
-      if (!this.activeSessionGenerations.has(message.sessionGeneration)) {
-        return;
-      }
-      this.messageConsumer?.(message);
-    });
+    this.rpc.addMessageListener(
+      "notebookEvent",
+      ({ event, sessionGeneration }) => {
+        // A stopped session can still have events in transit after the next
+        // app takes ownership of the shared frontend state.
+        if (!this.activeSessionGenerations.has(sessionGeneration)) {
+          return;
+        }
+        // Islands follow only the notebook's marimo notifications.
+        const frame = jsonParseWithSpecialChar(event) as {
+          event: string;
+          data: { marimo?: NotificationMessage };
+        };
+        if (frame.event === "marimo" && frame.data.marimo) {
+          this.notificationConsumer?.(frame.data.marimo, sessionGeneration);
+        }
+      },
+    );
   }
 
   public async initializeApps(): Promise<void> {
@@ -246,14 +257,14 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
     await this.rpc.proxy.request.startSession(opts);
   }
 
-  /**
-   * Sets up a consumer for kernel messages
-   */
-  public consumeMessages(
-    consumer: (message: IslandsKernelMessage) => void,
+  /** Receive each running session's marimo notifications. */
+  public consumeNotifications(
+    consumer: (
+      notification: NotificationMessage,
+      sessionGeneration: number,
+    ) => void,
   ): void {
-    this.messageConsumer = consumer;
-    this.rpc.proxy.send.consumerReady({});
+    this.notificationConsumer = consumer;
   }
 
   // ============================================================================

package/src/core/islands/components/__tests__/IslandControls.test.tsx

@@ -2,6 +2,7 @@
 
 import { fireEvent, render, screen } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import { MockRequestClient } from "@/__mocks__/requests";
 import { TooltipProvider } from "@/components/ui/tooltip";
 import type { CellId } from "@/core/cells/ids";
 import * as requestsModule from "@/core/network/requests";
@@ -18,7 +19,8 @@ vi.mock("@/utils/copy", () => ({
 }));
 
 describe("IslandControls", () => {
-  const mockSendRun = vi.fn();
+  const mockSendRun =
+    vi.fn<ReturnType<typeof requestsModule.useRequestClient>["sendRun"]>();
   const mockCopyToClipboard = vi.fn();
   const mockCodeCallback = vi.fn(() => "print('test code')");
   const cellId = "test-cell-id" as CellId;
@@ -30,11 +32,11 @@ describe("IslandControls", () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
-    mockSendRun.mockResolvedValue(undefined);
+    mockSendRun.mockResolvedValue(null);
 
-    vi.spyOn(requestsModule, "useRequestClient").mockReturnValue({
-      sendRun: mockSendRun,
-    } as any);
+    vi.spyOn(requestsModule, "useRequestClient").mockReturnValue(
+      MockRequestClient.create({ sendRun: mockSendRun }),
+    );
 
     vi.spyOn(copyModule, "copyToClipboard").mockImplementation(
       mockCopyToClipboard,

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

@@ -2,6 +2,7 @@
 
 import type { PyodideInterface } from "pyodide";
 import { describe, expect, it, vi } from "vitest";
+import { Deferred } from "@/utils/Deferred";
 import { ReadonlyWasmController } from "../controller";
 
 class TestController extends ReadonlyWasmController {
@@ -50,15 +51,71 @@ function createPyodideStub(
   };
 }
 
-function startSession(controller: TestController, code: string) {
-  return controller.startSession({
+function prepareSession(controller: TestController, code: string) {
+  return controller.prepareSession({
     code,
     filename: `${code}.py`,
-    onMessage: vi.fn(),
   });
 }
 
+async function startSession(controller: TestController, code: string) {
+  const session = await prepareSession(controller, code);
+  void session.start();
+  return session;
+}
+
 describe("WASM controller session lifecycle", () => {
+  it("releases a prepared session and ignores start after stop", async () => {
+    const { init, pyodide } = createPyodideStub();
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+
+    const session = await prepareSession(controller, "current");
+    await session.stop();
+    expect(init.destroy).toHaveBeenCalledOnce();
+    await session.start();
+    expect(init).not.toHaveBeenCalled();
+  });
+
+  it.each(["resolve", "reject"] as const)(
+    "releases a stopped session before its dependencies %s",
+    async (outcome) => {
+      const dependencies = new Deferred<void>();
+      const { init, loadPackagesFromImports, pyodide, bridge, stop } =
+        createPyodideStub();
+      loadPackagesFromImports.mockReturnValue(dependencies.promise);
+      const controller = new TestController();
+      controller.setPyodide(pyodide);
+      const session = await prepareSession(controller, "current");
+      const starting = session.start();
+      expect(init).not.toHaveBeenCalled();
+      await session.stop();
+      expect(init.destroy).toHaveBeenCalledOnce();
+      expect(bridge.destroy).toHaveBeenCalledOnce();
+      if (outcome === "resolve") {
+        dependencies.resolve();
+      } else {
+        dependencies.reject(new Error("Loading failed after stop"));
+      }
+      await starting;
+      await session.stop();
+      expect(stop).toHaveBeenCalledOnce();
+      expect(init).not.toHaveBeenCalled();
+    },
+  );
+
+  it("reports dependency failures when starting an active session", async () => {
+    const { init, loadPackagesFromImports, pyodide } = createPyodideStub();
+    loadPackagesFromImports.mockRejectedValue(new Error("Dependency failed"));
+    const controller = new TestController();
+    controller.setPyodide(pyodide);
+    const session = await prepareSession(controller, "current");
+    await expect(session.start()).rejects.toThrow("Dependency failed");
+    expect(init).not.toHaveBeenCalled();
+    expect(init.destroy).toHaveBeenCalledOnce();
+    await session.stop();
+  });
+
   it("stops and releases the active session", async () => {
     const { init, packages, pyodide, sessionResources, stop } =
       createPyodideStub();
@@ -116,7 +173,6 @@ describe("WASM controller session lifecycle", () => {
 
     await startSession(controller, "first");
     await startSession(controller, "second");
-    second.bridge.destroy();
 
     expect(first.stop.destroy).not.toHaveBeenCalled();
 
@@ -126,6 +182,8 @@ describe("WASM controller session lifecycle", () => {
     expect(second.stop).toHaveBeenCalledOnce();
     expect(first.stop.destroy).toHaveBeenCalledOnce();
     expect(second.stop.destroy).toHaveBeenCalledOnce();
+    expect(first.bridge.destroy).toHaveBeenCalledOnce();
+    expect(second.bridge.destroy).toHaveBeenCalledOnce();
   });
 
   it("continues stopping sessions after one stop fails", async () => {

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

@@ -1,11 +1,9 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import type { PyodideInterface } from "pyodide";
 import { defaultUserConfig } from "@/core/config/config-schema";
-import type { NotificationPayload } from "@/core/kernel/messages";
 import { DefaultWasmController } from "@/core/wasm/worker/bootstrap";
 import { WasmFileSystem } from "@/core/wasm/worker/fs";
-import type { SerializedBridge } from "@/core/wasm/worker/types";
-import type { JsonString } from "@/utils/json/base64";
+import type { WasmSession } from "@/core/wasm/worker/types";
 import { Logger } from "../../../utils/Logger";
 
 export class ReadonlyWasmController extends DefaultWasmController {
@@ -37,19 +35,15 @@ export class ReadonlyWasmController extends DefaultWasmController {
     return { code, filename };
   }
 
-  public override async startSession(opts: {
+  public override async prepareSession(opts: {
     code: string;
     filename: string | null;
-    onMessage: (message: JsonString<NotificationPayload>) => void;
-  }): Promise<SerializedBridge> {
-    const bridge = super.startSession({
+  }): Promise<WasmSession> {
+    return super.prepareSession({
       queryParameters: {},
       code: opts.code,
       filename: opts.filename,
-      onMessage: opts.onMessage,
       userConfig: defaultUserConfig(),
     });
-
-    return bridge;
   }
 }

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

@@ -1,21 +1,17 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
 import type { PyodideInterface } from "pyodide";
-import type { PyProxy } from "pyodide/ffi";
 import {
   createRPC,
   createRPCRequestHandler,
   createWorkerParentTransport,
   type RPCSchema,
 } from "rpc-anywhere";
-import type { NotificationPayload } from "@/core/kernel/messages";
 import type { ParentSchema } from "@/core/wasm/rpc";
 import { shouldLoadDuckDBPackages } from "@/core/wasm/utils";
 import { TRANSPORT_ID } from "@/core/wasm/worker/constants";
 import { getPyodideVersion } from "@/core/wasm/worker/getPyodideVersion";
-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 { prettyError } from "../../../utils/errors";
 import { invariant } from "../../../utils/invariant";
@@ -45,14 +41,11 @@ async function loadPyodideAndPackages() {
 }
 
 const pyodideReadyPromise = loadPyodideAndPackages();
-export interface IslandsKernelMessage {
-  message: JsonString<NotificationPayload>;
+/** An event of one session's notebook stream. */
+export interface IslandsNotebookEvent {
+  event: string;
   sessionGeneration: number;
 }
-
-const messageBuffer = new MessageBuffer<IslandsKernelMessage>((payload) => {
-  rpc.send.kernelMessage(payload);
-});
 interface SessionRequest {
   code: string;
   appId: string;
@@ -79,21 +72,22 @@ async function startSession(
       code: opts.code,
       filename: `app-${opts.appId}.py`,
     });
-    const nextBridge = await self.controller.startSession({
-      ...notebook,
-      onMessage: (message) => {
-        messageBuffer.push({
-          message,
-          sessionGeneration: opts.sessionGeneration,
-        });
-      },
+    const session = await self.controller.prepareSession(notebook);
+    // Follow before the session instantiates. Each subscription begins with
+    // its own kernel-ready and the session's retained notifications.
+    try {
+      await follow(session.bridge, opts.sessionGeneration);
+    } catch (error) {
+      await session.stop();
+      throw error;
+    }
+    void session.start().catch((error: unknown) => {
+      rpc.send.initializedError({ error: prettyError(error) });
     });
-    if (activeSession) {
-      (nextBridge as unknown as PyProxy).destroy();
-    } else {
+    if (!activeSession) {
       activeSession = {
         appId: opts.appId,
-        bridge: nextBridge,
+        bridge: session.bridge,
         sessionGeneration: opts.sessionGeneration,
       };
     }
@@ -107,10 +101,23 @@ async function startSession(
 }
 
 async function stopActiveSession(): Promise<void> {
-  const session = activeSession;
+  // Stopping closes every session and its notebook subscriptions.
   await self.controller.stopSession();
   activeSession = undefined;
-  (session?.bridge as unknown as PyProxy | undefined)?.destroy();
+}
+
+async function follow(
+  bridge: SerializedBridge,
+  sessionGeneration: number,
+): Promise<void> {
+  const notebook = bridge.notebook;
+  try {
+    await notebook.subscribe(`island-${sessionGeneration}`, null, (event) => {
+      rpc.send.notebookEvent({ event, sessionGeneration });
+    });
+  } finally {
+    notebook.destroy();
+  }
 }
 
 function enqueueSession<T>(operation: () => Promise<T>): Promise<T> {
@@ -243,8 +250,8 @@ export type WorkerSchema = RPCSchema<
     messages: {
       // Emitted when the worker is ready
       ready: {};
-      // Emitted when the kernel sends a message
-      kernelMessage: IslandsKernelMessage;
+      // Emitted for each event of a session's notebook stream
+      notebookEvent: IslandsNotebookEvent;
       // Emitted when the Pyodide is initialized
       initialized: {};
       // Emitted when the Pyodide fails to initialize
@@ -263,13 +270,6 @@ const rpc = createRPC<WorkerSchema, ParentSchema>({
 
 rpc.send("ready", {});
 
-/// Listeners
-// When the consumer is ready, start the message buffer
-rpc.addMessageListener("consumerReady", async () => {
-  await pyodideReadyPromise; // Make sure loading is done
-  messageBuffer.start();
-});
-
 function getMarimoVersion() {
   return self.name; // We store the version in the worker name
 }

package/src/core/kernel/__tests__/RuntimeState.test.ts

@@ -25,7 +25,7 @@ describe("RuntimeState", () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
-    mockSendComponentValues = vi.fn((args) => Promise.resolve(null));
+    mockSendComponentValues = vi.fn(() => Promise.resolve(null));
     uiElementRegistry = UIElementRegistry.INSTANCE;
     uiElementRegistry.entries.clear();
 

package/src/core/network/connection.ts

@@ -7,8 +7,10 @@ import { waitFor } from "../state/jotai";
 import { type ConnectionStatus, ConnectionState } from "../websocket/types";
 
 /**
- * Atom for storing the connection status.
- * Initialized to NOT_STARTED.
+ * Shared application state, not the actual event-stream status.
+ *
+ * TODO(MO-8051) Expose read-only connection state and derive UI availability
+ * separately.
  */
 export const connectionAtom = atom<ConnectionStatus>({
   state: ConnectionState.NOT_STARTED,

package/src/core/network/useConnectionNotice.ts

@@ -17,11 +17,17 @@ export function useConnectionNotice(
   const notice = useAtomValue(connectionNoticeAtom);
   const connected = useAtomValue(isConnectedAtom);
   const elapsed = useDelayElapsed(notice?.pending ? delayMs : 0);
-  const [previous, setPrevious] = useState<ConnectionNotice | null>(null);
+  const [previous, setPrevious] = useState<ConnectionNotice | null>(
+    elapsed ? notice : null,
+  );
+
+  const visibleNotice = elapsed ? notice : null;
+  if ((notice || !connected) && previous !== visibleNotice) {
+    setPrevious(visibleNotice);
+  }
 
   useEffect(() => {
     if (notice || !connected) {
-      setPrevious(elapsed ? notice : null);
       return;
     }
     const timeout = setTimeout(() => setPrevious(null), 1500);