A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat: API for retained WASM island lifecycle (#10207)
Péter Gyarmatif37839f7af97
diff --git a/frontend/src/core/islands/__tests__/bridge.test.ts b/frontend/src/core/islands/__tests__/bridge.test.tsindex cac5fa2e9c..4115c0ee01 100644--- a/frontend/src/core/islands/__tests__/bridge.test.ts+++ b/frontend/src/core/islands/__tests__/bridge.test.ts@@ -45,14 +45,22 @@ vi.stubGlobal("URL", MockURL);const {mockBridge,mockLoadPackages,+ mockReplaceSessionRequest,+ mockStopSessionRequest,mockStartSessionRequest,+ mockMessageListeners,+ mockStoreSet,mockParseMarimoIslandApps,mockCreateMarimoFile,mockGetMarimoExportContext,} = vi.hoisted(() => ({mockBridge: vi.fn(),mockLoadPackages: vi.fn(),+ mockReplaceSessionRequest: vi.fn(),+ mockStopSessionRequest: vi.fn(),mockStartSessionRequest: vi.fn(),+ mockMessageListeners: new Map<string, (payload: never) => void>(),+ mockStoreSet: vi.fn(),mockParseMarimoIslandApps: vi.fn<() => TestIslandApp[]>(() => []),mockCreateMarimoFile: vi.fn(),mockGetMarimoExportContext: vi.fn<() => TestExportContext | undefined>(@@ -66,13 +74,19 @@ vi.mock("@/core/wasm/rpc", () => ({request: {bridge: mockBridge,loadPackages: mockLoadPackages,+ replaceSession: mockReplaceSessionRequest,startSession: mockStartSessionRequest,+ stopSession: mockStopSessionRequest,},send: {consumerReady: vi.fn(),},},- addMessageListener: vi.fn(),+ addMessageListener: vi.fn(+ (name: string, listener: (payload: never) => void) => {+ mockMessageListeners.set(name, listener);+ },+ ),}),}));@@ -97,10 +111,11 @@ vi.mock("@/core/meta/globals", () => ({}));// Mock the jotai store-vi.mock("@/core/state/jotai", () => ({+vi.mock("@/core/state/jotai", async (importOriginal) => ({+ ...(await importOriginal<typeof import("@/core/state/jotai")>()),store: {get: vi.fn(),- set: vi.fn(),+ set: mockStoreSet,},}));@@ -115,40 +130,69 @@ describe("IslandsPyodideBridge", () => {mockParseMarimoIslandApps.mockReturnValue([]);mockCreateMarimoFile.mockReset();mockGetMarimoExportContext.mockReturnValue(undefined);- bridge = new IslandsPyodideBridge({ autoStartSessions: false });+ mockMessageListeners.clear();+ bridge = new IslandsPyodideBridge();});- describe("startSessionsForAllApps", () => {+ function signalWorkerReady() {+ const listener = mockMessageListeners.get("ready");+ if (!listener) {+ throw new Error("Missing worker ready listener");+ }+ listener({} as never);+ }++ function app(id = "app-1"): TestIslandApp {+ return {+ id,+ cells: [{ code: "x = 1", idx: 0, output: "<div>1</div>" }],+ };+ }++ function setSingleApp(file = "generated app 1", appId = "app-1") {+ mockParseMarimoIslandApps.mockReturnValue([app(appId)]);+ mockCreateMarimoFile.mockReturnValue(file);+ }++ function mockSingleApp(file = "generated app 1", appId = "app-1") {+ setSingleApp(file, appId);+ signalWorkerReady();+ }++ function sendSlider() {+ return bridge.sendComponentValues({+ objectIds: [uiElementId("slider-1")],+ values: [2],+ });+ }++ async function initializeSingleApp() {+ mockSingleApp();+ await bridge.initializeApps();+ }++ describe("app initialization", () => {it("should prefer trusted export notebook code when there is exactly one reactive app", async () => {- mockParseMarimoIslandApps.mockReturnValue([- {- id: "app-1",- cells: [{ code: "x = 1", idx: 0, output: "<div>1</div>" }],- },- ]);+ mockParseMarimoIslandApps.mockReturnValue([app()]);mockGetMarimoExportContext.mockReturnValue({trusted: true,notebookCode:"import marimo\napp = marimo.App()\[email protected]\ndef __():\n x = 1\n return",});- await (- bridge as unknown as { startSessionsForAllApps(): Promise<void> }- ).startSessionsForAllApps();+ signalWorkerReady();+ await bridge.initializeApps();expect(mockCreateMarimoFile).not.toHaveBeenCalled();expect(mockStartSessionRequest).toHaveBeenCalledWith({appId: "app-1",code: "import marimo\napp = marimo.App()\[email protected]\ndef __():\n x = 1\n return",+ sessionGeneration: 1,});});it("should ignore trusted export notebook code for a payload-backed app", async () => {- const payloadApp = {- id: "app-1",- payloadBacked: true,- cells: [{ code: "x = 1", idx: 0, output: "<div>1</div>" }],- };+ const payloadApp = { ...app(), payloadBacked: true };mockParseMarimoIslandApps.mockReturnValue([payloadApp]);mockGetMarimoExportContext.mockReturnValue({trusted: true,@@ -156,28 +200,19 @@ describe("IslandsPyodideBridge", () => {});mockCreateMarimoFile.mockReturnValue("generated payload app");- await (- bridge as unknown as { startSessionsForAllApps(): Promise<void> }- ).startSessionsForAllApps();+ signalWorkerReady();+ await bridge.initializeApps();expect(mockCreateMarimoFile).toHaveBeenCalledWith(payloadApp);expect(mockStartSessionRequest).toHaveBeenCalledWith({appId: "app-1",code: "generated payload app",+ sessionGeneration: 1,});});it("should keep synthesized per-app files for multiple reactive apps even when export context exists", async () => {- mockParseMarimoIslandApps.mockReturnValue([- {- id: "app-1",- cells: [{ code: "x = 1", idx: 0, output: "<div>1</div>" }],- },- {- id: "app-2",- cells: [{ code: "y = 2", idx: 0, output: "<div>2</div>" }],- },- ]);+ mockParseMarimoIslandApps.mockReturnValue([app(), app("app-2")]);mockGetMarimoExportContext.mockReturnValue({trusted: true,notebookCode: "full notebook should be ignored",@@ -186,43 +221,281 @@ describe("IslandsPyodideBridge", () => {.mockReturnValueOnce("generated app 1").mockReturnValueOnce("generated app 2");- await (- bridge as unknown as { startSessionsForAllApps(): Promise<void> }- ).startSessionsForAllApps();+ signalWorkerReady();+ await bridge.initializeApps();expect(mockCreateMarimoFile).toHaveBeenCalledTimes(2);expect(mockStartSessionRequest).toHaveBeenNthCalledWith(1, {appId: "app-1",code: "generated app 1",+ sessionGeneration: 1,});expect(mockStartSessionRequest).toHaveBeenNthCalledWith(2, {appId: "app-2",code: "generated app 2",+ sessionGeneration: 2,+ });++ await sendSlider();+ await bridge.stopSession();++ expect(mockReplaceSessionRequest).not.toHaveBeenCalled();+ expect(mockStopSessionRequest).not.toHaveBeenCalled();+ expect(mockBridge).toHaveBeenCalledWith({+ appId: "app-1",+ functionName: "put_control_request",+ payload: {+ objectIds: ["slider-1"],+ token: "test-uuid-12345",+ type: "update-ui-element",+ values: [2],+ },+ sessionGeneration: 1,});});it("should synthesize a file for a single app when no trusted export context is present", async () => {- mockParseMarimoIslandApps.mockReturnValue([- {- id: "app-1",- cells: [{ code: "x = 1", idx: 0, output: "<div>1</div>" }],- },- ]);- mockCreateMarimoFile.mockReturnValue("generated app 1");+ setSingleApp();- await (- bridge as unknown as { startSessionsForAllApps(): Promise<void> }- ).startSessionsForAllApps();+ signalWorkerReady();+ await bridge.initializeApps();expect(mockCreateMarimoFile).toHaveBeenCalledTimes(1);expect(mockStartSessionRequest).toHaveBeenCalledWith({appId: "app-1",code: "generated app 1",+ sessionGeneration: 1,+ });+ });+ });++ describe("app lifecycle", () => {+ it("holds controls until the first app session is ready", async () => {+ setSingleApp();++ const initialization = bridge.initializeApps();+ const control = sendSlider();+ await Promise.resolve();++ expect(mockBridge).not.toHaveBeenCalled();++ signalWorkerReady();+ await Promise.all([initialization, control]);+ expect(mockBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ appId: "app-1",+ sessionGeneration: 1,+ }),+ );+ });++ it("starts the first app, skips duplicates, and replaces changed source", async () => {+ mockSingleApp();++ await bridge.initializeApps();+ await bridge.initializeApps();+ await sendSlider();++ expect(mockStartSessionRequest).toHaveBeenCalledOnce();+ expect(mockStartSessionRequest).toHaveBeenCalledWith({+ appId: "app-1",+ code: "generated app 1",+ sessionGeneration: 1,+ });+ expect(mockReplaceSessionRequest).not.toHaveBeenCalled();+ expect(mockBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ appId: "app-1",+ sessionGeneration: 1,+ }),+ );+ mockCreateMarimoFile.mockReturnValue("generated app 2");+ await bridge.initializeApps();++ expect(mockReplaceSessionRequest).toHaveBeenCalledOnce();+ expect(mockReplaceSessionRequest).toHaveBeenCalledWith({+ appId: "app-1",+ code: "generated app 2",+ sessionGeneration: 2,+ });+ expect(mockStoreSet).toHaveBeenCalledOnce();+ });++ it("stops the matching active app", async () => {+ mockSingleApp();+ await bridge.initializeApps();++ await bridge.stopSession("other-app");+ await bridge.stopSession("app-1");++ expect(mockStopSessionRequest).toHaveBeenCalledOnce();+ expect(mockStopSessionRequest).toHaveBeenCalledWith({+ appId: "app-1",+ sessionGeneration: 1,+ });++ mockBridge.mockClear();+ const control = sendSlider();+ await Promise.resolve();+ expect(mockBridge).not.toHaveBeenCalled();++ mockSingleApp("generated app 2");+ await bridge.initializeApps();+ await control;++ expect(mockBridge).toHaveBeenCalledWith(+ expect.objectContaining({ sessionGeneration: 2 }),+ );+ });++ it("replaces the active session after stop fails", async () => {+ mockSingleApp();+ await bridge.initializeApps();+ mockStopSessionRequest.mockRejectedValueOnce(new Error("stop failed"));++ await expect(bridge.stopSession("app-1")).rejects.toThrow("stop failed");++ mockSingleApp("generated app 2", "app-2");++ await bridge.initializeApps();++ expect(mockStartSessionRequest).toHaveBeenCalledOnce();+ expect(mockReplaceSessionRequest).toHaveBeenCalledWith({+ appId: "app-2",+ code: "generated app 2",+ sessionGeneration: 2,+ });+ });++ it("keeps controls sent during stop scoped to the stopped app", async () => {+ mockSingleApp();+ await bridge.initializeApps();+ mockBridge.mockClear();+ let finishStop!: () => void;+ mockStopSessionRequest.mockReturnValueOnce(+ new Promise<void>((resolve) => {+ finishStop = resolve;+ }),+ );++ const stop = bridge.stopSession("app-1");+ await vi.waitFor(() =>+ expect(mockStopSessionRequest).toHaveBeenCalledOnce(),+ );+ const control = sendSlider();+ mockSingleApp("generated app 2", "app-2");+ const nextInitialization = bridge.initializeApps();++ finishStop();+ await Promise.all([stop, control, nextInitialization]);++ expect(mockBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ appId: "app-1",+ sessionGeneration: 1,+ }),+ );+ });++ it("allows initialization to retry after replacement fails", async () => {+ mockSingleApp();+ await bridge.initializeApps();+ mockCreateMarimoFile.mockReturnValue("generated app 2");+ mockReplaceSessionRequest.mockRejectedValueOnce(+ new Error("replacement failed"),+ );++ await expect(bridge.initializeApps()).rejects.toThrow(+ "replacement failed",+ );+ await bridge.initializeApps();++ expect(mockStartSessionRequest).toHaveBeenCalledOnce();+ expect(mockReplaceSessionRequest).toHaveBeenCalledTimes(2);+ expect(mockReplaceSessionRequest).toHaveBeenLastCalledWith({+ appId: "app-1",+ code: "generated app 2",+ sessionGeneration: 3,});});++ it("scopes controls to the replacement active when they were sent", async () => {+ mockSingleApp();+ await bridge.initializeApps();+ mockBridge.mockClear();+ mockCreateMarimoFile.mockReturnValue("generated app 2");+ let finishSecondApp!: () => void;+ let finishThirdApp!: () => void;+ mockReplaceSessionRequest+ .mockReturnValueOnce(+ new Promise<void>((resolve) => {+ finishSecondApp = resolve;+ }),+ )+ .mockReturnValueOnce(+ new Promise<void>((resolve) => {+ finishThirdApp = resolve;+ }),+ );++ const secondInitialization = bridge.initializeApps();+ await vi.waitFor(() =>+ expect(mockReplaceSessionRequest).toHaveBeenCalledOnce(),+ );+ const control = sendSlider();+ mockSingleApp("generated app 3", "app-2");+ const thirdInitialization = bridge.initializeApps();++ expect(mockBridge).not.toHaveBeenCalled();++ finishSecondApp();+ await vi.waitFor(() => expect(mockBridge).toHaveBeenCalledOnce());+ expect(mockBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ appId: "app-1",+ sessionGeneration: 2,+ }),+ );++ finishThirdApp();+ await Promise.all([secondInitialization, thirdInitialization, control]);+ });++ it("keeps controls from a failed replacement out of the next app", async () => {+ mockSingleApp();+ await bridge.initializeApps();+ mockBridge.mockClear();+ mockCreateMarimoFile.mockReturnValue("generated app 2");+ let failReplacement!: (error: Error) => void;+ mockReplaceSessionRequest.mockReturnValueOnce(+ new Promise<void>((_resolve, reject) => {+ failReplacement = reject;+ }),+ );++ const failedInitialization = bridge.initializeApps();+ await vi.waitFor(() =>+ expect(mockReplaceSessionRequest).toHaveBeenCalledOnce(),+ );+ const control = sendSlider();+ failReplacement(new Error("replacement failed"));+ await expect(failedInitialization).rejects.toThrow("replacement failed");++ mockSingleApp("generated app 3", "app-2");+ await Promise.all([bridge.initializeApps(), control]);++ expect(mockBridge).toHaveBeenCalledWith(+ expect.objectContaining({+ appId: "app-1",+ sessionGeneration: 2,+ }),+ );+ });});describe("sendComponentValues", () => {+ beforeEach(initializeSingleApp);+it("should include type field and token in control request", async () => {const request = {objectIds: [uiElementId("Hbol-0")],@@ -232,6 +505,7 @@ describe("IslandsPyodideBridge", () => {await bridge.sendComponentValues(request);expect(mockBridge).toHaveBeenCalledWith({+ appId: "app-1",functionName: "put_control_request",payload: {type: "update-ui-element",@@ -239,6 +513,7 @@ describe("IslandsPyodideBridge", () => {values: [58],token: "test-uuid-12345",},+ sessionGeneration: 1,});});@@ -251,17 +526,21 @@ describe("IslandsPyodideBridge", () => {await bridge.sendComponentValues(request);expect(mockBridge).toHaveBeenCalledWith({+ appId: "app-1",functionName: "put_control_request",payload: expect.objectContaining({type: "update-ui-element",objectIds: ["slider-1", "slider-2"],values: [10, 20],}),+ sessionGeneration: 1,});});});describe("sendFunctionRequest", () => {+ beforeEach(initializeSingleApp);+it("should include type field in control request", async () => {const request = {functionCallId: requestId("call-123"),@@ -273,6 +552,7 @@ describe("IslandsPyodideBridge", () => {await bridge.sendFunctionRequest(request);expect(mockBridge).toHaveBeenCalledWith({+ appId: "app-1",functionName: "put_control_request",payload: {type: "invoke-function",@@ -281,11 +561,14 @@ describe("IslandsPyodideBridge", () => {functionName: "my_function",args: { x: 1, y: 2 },},+ sessionGeneration: 1,});});});describe("sendRun", () => {+ beforeEach(initializeSingleApp);+it("should include type field in control request", async () => {const request = {cellIds: [cellId("cell-1"), cellId("cell-2")],@@ -295,12 +578,14 @@ describe("IslandsPyodideBridge", () => {await bridge.sendRun(request);expect(mockBridge).toHaveBeenCalledWith({+ appId: "app-1",functionName: "put_control_request",payload: {type: "execute-cells",cellIds: ["cell-1", "cell-2"],codes: ["print('hello')", "print('world')"],},+ sessionGeneration: 1,});});@@ -313,7 +598,11 @@ describe("IslandsPyodideBridge", () => {await bridge.sendRun(request);// Verify loadPackages was called with joined codes- expect(mockLoadPackages).toHaveBeenCalledWith("import pandas");+ expect(mockLoadPackages).toHaveBeenCalledWith({+ appId: "app-1",+ code: "import pandas",+ sessionGeneration: 1,+ });// Verify order: loadPackages should be called before bridgeconst loadPackagesCallOrder =@@ -324,6 +613,8 @@ describe("IslandsPyodideBridge", () => {});describe("sendModelValue", () => {+ beforeEach(initializeSingleApp);+it("should include type field in control request", async () => {const request = {modelId: widgetModelId("widget-1"),@@ -338,6 +629,7 @@ describe("IslandsPyodideBridge", () => {await bridge.sendModelValue(request);expect(mockBridge).toHaveBeenCalledWith({+ appId: "app-1",functionName: "put_control_request",payload: {type: "model",@@ -349,11 +641,14 @@ describe("IslandsPyodideBridge", () => {},buffers: [],},+ sessionGeneration: 1,});});});describe("control request message format", () => {+ beforeEach(initializeSingleApp);+it("should always include the type field required by msgspec", async () => {// Test all methods to ensure they include the type fieldawait bridge.sendComponentValues({ objectIds: [], values: [] });diff --git a/frontend/src/core/islands/__tests__/parse.test.ts b/frontend/src/core/islands/__tests__/parse.test.tsindex 593170e28f..96ecef186e 100644--- a/frontend/src/core/islands/__tests__/parse.test.ts+++ b/frontend/src/core/islands/__tests__/parse.test.ts@@ -15,6 +15,7 @@ import {parseIslandElement,parseIslandElementsIntoApps,parseMarimoIslandApps,+ retainIslandSource,} from "../parse";import { createMockIslandElement, createMockIslands } from "./test-utils.tsx";@@ -53,6 +54,7 @@ function appendPayload(script.type = ISLANDS_JSON_SCRIPT_TYPE;script.textContent = JSON.stringify(payload);root.appendChild(script);+ return script;}describe("createMarimoFile", () => {@@ -317,6 +319,39 @@ describe("parseIslandElement", () => {expect(result).toBeNull();});++ it("uses retained source after the custom element renders", () => {+ const element = document.createElement(ISLAND_TAG_NAMES.ISLAND);+ retainIslandSource(element, {+ code: 'print("retained")',+ output: "<div>retained output</div>",+ });++ expect(parseIslandElement(element)).toEqual({+ code: 'print("retained")',+ output: "<div>retained output</div>",+ });++ retainIslandSource(element, { code: "", output: "<div>static</div>" });+ expect(parseIslandElement(element)).toBeNull();+ });++ it("prefers new live source when an island element is reused", () => {+ const element = createMockIslandElement({+ code: 'print("new")',+ innerHTML: "<div>new output</div>",+ });+ element.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");+ retainIslandSource(element, {+ code: 'print("retained")',+ output: "<div>retained output</div>",+ });++ expect(parseIslandElement(element)).toEqual({+ code: 'print("new")',+ output: "<div>new output</div>",+ });+ });});describe("parseIslandElementsIntoApps", () => {@@ -630,6 +665,76 @@ describe("parseMarimoIslandApps", () => {);});+ it("preserves payload-backed cells after a non-materializing capability probe", () => {+ const island = createMockIslandElement({+ appId: "app1",+ cellId: "cell-2",+ code: "dom_code = True",+ innerHTML: "<div>dom output</div>",+ });+ island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");+ container.appendChild(island);+ appendPayload(container, {+ schemaVersion: 1,+ appId: "app1",+ cells: [createPayloadCell({ cellId: "cell-2" })],+ });+ const originalIsland = island.outerHTML;++ const probed = parseMarimoIslandApps(container, { materialize: false });++ expect(probed).toHaveLength(1);+ expect(island.outerHTML).toBe(originalIsland);++ expect(parseMarimoIslandApps(container)).toEqual(probed);+ expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID)).toBeNull();+ expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");+ });++ it("refreshes a reused payload anchor when its content changes", () => {+ const island = createMockIslandElement({+ appId: "app1",+ cellId: "cell-1",+ code: 'print("dom")',+ innerHTML: "<div>dom output</div>",+ });+ island.insertAdjacentHTML(+ "beforeend",+ '<div data-marimo-element><marimo-code-editor data-initial-value="old"></marimo-code-editor></div>',+ );+ island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");+ container.appendChild(island);+ const script = appendPayload(container, {+ schemaVersion: 1,+ appId: "app1",+ cells: [createPayloadCell()],+ });+ parseMarimoIslandApps(container);++ script.textContent = JSON.stringify({+ schemaVersion: 1,+ appId: "app1",+ cells: [+ createPayloadCell({+ code: 'print("updated")',+ outputHtml: "<div>updated output</div>",+ }),+ ],+ });++ parseMarimoIslandApps(container);++ expect(extractIslandCodeFromEmbed(island)).toBe('print("updated")');+ expect(island.querySelector(ISLAND_TAG_NAMES.CELL_OUTPUT)?.innerHTML).toBe(+ "<div>updated output</div>",+ );+ expect(+ island+ .querySelector(ISLAND_TAG_NAMES.CODE_EDITOR)+ ?.getAttribute("data-initial-value"),+ ).toBe(JSON.stringify('print("updated")'));+ });+it("should parse Python-generated island payload snapshots", () => {const html = readFileSync(new URL(diff --git a/frontend/src/core/islands/bootstrap.ts b/frontend/src/core/islands/bootstrap.tsindex be1eaa0086..f132080665 100644--- a/frontend/src/core/islands/bootstrap.ts+++ b/frontend/src/core/islands/bootstrap.ts@@ -108,14 +108,17 @@ export async function initializeIslands(// Loading indicator: dim islands while Pyodide initializesstore.sub(shouldShowIslandsWarningIndicatorAtom, () => {const showing = store.get(shouldShowIslandsWarningIndicatorAtom);+ const currentIslands = root.querySelectorAll<HTMLElement>(+ ISLAND_TAG_NAMES.ISLAND,+ );if (showing) {toastIslandsLoading();- for (const island of islands) {+ for (const island of currentIslands) {island.style.setProperty("opacity", "0.5");}} else {dismissIslandsLoadingToast();- for (const island of islands) {+ for (const island of currentIslands) {island.style.removeProperty("opacity");}}@@ -208,7 +211,9 @@ function handleMessage(setKernelState: Functions.NOOP,onError: Logger.error,});- defineCustomElement(ISLAND_TAG_NAMES.ISLAND, MarimoIslandElement);+ if (!window.customElements?.get(ISLAND_TAG_NAMES.ISLAND)) {+ defineCustomElement(ISLAND_TAG_NAMES.ISLAND, MarimoIslandElement);+ }return;case "send-ui-element-message":diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.tsindex e3ed684d3f..2ccc781618 100644--- a/frontend/src/core/islands/bridge.ts+++ b/frontend/src/core/islands/bridge.ts@@ -7,6 +7,7 @@ import { throwNotImplemented } from "@/utils/functions";import type { JsonString } from "@/utils/json/base64";import { Logger } from "@/utils/Logger";import { generateUUID } from "@/utils/uuid";+import { initialNotebookState, notebookAtom } from "../cells/cells";import type { CommandMessage, NotificationPayload } from "../kernel/messages";import type { EditRequests, RunRequests } from "../network/types";import { store as defaultStore } from "../state/jotai";@@ -35,11 +36,12 @@ export interface IslandsBridgeConfig {* Optional root element for parsing islands (for testing)*/root?: Document | Element;+}- /**- * Whether to auto-start sessions on worker ready (default: true)- */- autoStartSessions?: boolean;+interface AppSession {+ appId: string;+ code?: string;+ sessionGeneration: number;}/**@@ -51,8 +53,8 @@ export interface IslandsBridgeConfig {* @example* ```ts* const bridge = new IslandsPyodideBridge();- * await bridge.initialized;* bridge.consumeMessages(message => console.log(message));+ * await bridge.initializeApps();* ```*/export class IslandsPyodideBridge implements RunRequests, EditRequests {@@ -62,14 +64,17 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {| undefined;private readonly store: typeof defaultStore;private readonly root: Document | Element;- private readonly autoStartSessions: boolean;+ private session: AppSession | undefined;+ private sessionReady = new Deferred<AppSession>();+ private nextSessionGeneration = 0;+ private appTransition = Promise.resolve();+ private workerReady = new Deferred<void>();public initialized = new Deferred<void>();constructor(config: IslandsBridgeConfig = {}) {this.store = config.store || defaultStore;this.root = config.root || document;- this.autoStartSessions = config.autoStartSessions ?? true;try {const factory = config.workerFactory || new DefaultWorkerFactory();@@ -88,9 +93,7 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {*/private setupMessageListeners(): void {this.rpc.addMessageListener("ready", () => {- if (this.autoStartSessions) {- this.startSessionsForAllApps();- }+ this.workerReady.resolve();});this.rpc.addMessageListener("initialized", () => {@@ -115,11 +118,16 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {);}- /**- * Starts sessions for all apps found in the DOM- */- private startSessionsForAllApps(): void {+ async initializeApps(): Promise<void> {+ await this.enqueueAppTransition(async () => {+ await this.workerReady.promise;+ await this.startApps();+ });+ }++ private async startApps(): Promise<void> {const apps = parseMarimoIslandApps(this.root);+ const managesSingleApp = apps.length === 1;Logger.debug(`Starting sessions for ${apps.length} app(s):`,apps.map((a) => `${a.id} (${a.cells.length} cells)`),@@ -134,20 +142,83 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {const notebookCode = exportContext?.notebookCode;for (const app of apps) {const file = notebookCode || createMarimoFile(app);+ if (+ managesSingleApp &&+ this.session?.appId === app.id &&+ this.session.code === file+ ) {+ return;+ }Logger.debug(`App ${app.id} marimo file:\n`, file);- this.startSession({+ const request = {code: file,appId: app.id,- }).catch((error) => {+ sessionGeneration: ++this.nextSessionGeneration,+ };+ const previousSession = this.session;+ const replacesSession = managesSingleApp && previousSession !== undefined;+ if (replacesSession) {+ this.store.set(notebookAtom, initialNotebookState());+ }+ if (managesSingleApp || !previousSession) {+ if (managesSingleApp && this.sessionReady.status !== "pending") {+ this.sessionReady = new Deferred<AppSession>();+ }+ this.session = {+ ...request,+ code: managesSingleApp ? file : undefined,+ };+ }+ const operation = replacesSession+ ? this.rpc.proxy.request.replaceSession(request)+ : this.startSession(request);+ try {+ await operation;+ if (this.sessionReady.status === "pending" && this.session) {+ this.sessionReady.resolve(this.session);+ }+ } catch (error) {+ if (this.session?.sessionGeneration === request.sessionGeneration) {+ this.session = previousSession;+ }Logger.error(`Failed to start session for app ${app.id}:`, error);- });+ if (managesSingleApp) {+ throw error;+ }+ }}}+ async stopSession(appId?: string): Promise<void> {+ await this.enqueueAppTransition(async () => {+ const session = this.session;+ if (session?.code === undefined || (appId && session.appId !== appId)) {+ return;+ }+ await this.rpc.proxy.request.stopSession({+ appId: session.appId,+ sessionGeneration: session.sessionGeneration,+ });+ this.session = undefined;+ this.sessionReady = new Deferred<AppSession>();+ this.store.set(notebookAtom, initialNotebookState());+ });+ }++ private enqueueAppTransition(operation: () => Promise<void>): Promise<void> {+ const result = this.appTransition.then(operation);+ this.appTransition = result.catch(() => undefined);+ return result;+ }+/*** Starts a new Python session for an app*/- async startSession(opts: { code: string; appId: string }): Promise<void> {+ async startSession(opts: {+ code: string;+ appId: string;+ sessionGeneration: number;+ }): Promise<void> {await this.rpc.proxy.request.startSession(opts);}@@ -203,11 +274,19 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {// ============================================================================sendRun: EditRequests["sendRun"] = async (request): Promise<null> => {- await this.rpc.proxy.request.loadPackages(request.codes.join("\n"));- await this.putControlRequest({- type: "execute-cells",- ...request,+ const session = await this.getActiveSession();+ await this.rpc.proxy.request.loadPackages({+ appId: session.appId,+ code: request.codes.join("\n"),+ sessionGeneration: session.sessionGeneration,});+ await this.putControlRequest(+ {+ type: "execute-cells",+ ...request,+ },+ session,+ );return null;};@@ -278,13 +357,27 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {// The kernel uses msgspec to parse control requests, which requires a 'type'// field for discriminated union deserialization.- private async putControlRequest(operation: CommandMessage): Promise<void> {+ private async putControlRequest(+ operation: CommandMessage,+ session?: AppSession,+ ): Promise<void> {+ session ??= await this.getActiveSession();await this.rpc.proxy.request.bridge({+ appId: session.appId,functionName: "put_control_request",payload: operation,+ sessionGeneration: session.sessionGeneration,});}+ private async getActiveSession(): Promise<AppSession> {+ const transition = this.appTransition;+ const session = this.session;+ const ready = this.sessionReady;+ await transition;+ return session ?? ready.promise;+ }+/*** Cleans up resources (for testing)*/diff --git a/frontend/src/core/islands/components/__tests__/web-components.test.tsx b/frontend/src/core/islands/components/__tests__/web-components.test.tsxnew file mode 100644index 0000000000..68895dd3fb--- /dev/null+++ b/frontend/src/core/islands/components/__tests__/web-components.test.tsx@@ -0,0 +1,214 @@+/* Copyright 2026 Marimo. All rights reserved. */++import { act } from "react";+import {+ afterAll,+ afterEach,+ beforeAll,+ beforeEach,+ describe,+ expect,+ it,+} from "vitest";+import { cellId } from "@/__tests__/branded";+import { MockNotebook } from "@/__mocks__/notebook";+import { MockRequestClient } from "@/__mocks__/requests";+import { notebookAtom } from "@/core/cells/cells";+import {+ ISLAND_DATA_ATTRIBUTES,+ ISLAND_TAG_NAMES,+ ISLANDS_JSON_SCRIPT_TYPE,+} from "@/core/islands/constants";+import { requestClientAtom } from "@/core/network/requests";+import { store } from "@/core/state/jotai";+import { parseMarimoIslandApps } from "../../parse";+import { MarimoIslandElement } from "../web-components";++beforeAll(() => {+ setReactActEnvironment(true);+ if (!customElements.get(ISLAND_TAG_NAMES.ISLAND)) {+ customElements.define(ISLAND_TAG_NAMES.ISLAND, MarimoIslandElement);+ }+});++afterAll(() => {+ setReactActEnvironment(false);+});++beforeEach(() => {+ store.set(notebookAtom, MockNotebook.notebookState({ cellData: {} }));+ store.set(requestClientAtom, MockRequestClient.create());+});++afterEach(async () => {+ await actAndFlush(() => document.body.replaceChildren());+ store.set(requestClientAtom, null);+});++describe("MarimoIslandElement lifecycle", () => {+ it("binds a reactive island after its runtime cell index is materialized", async () => {+ setNotebook("outgoing-cell", "outgoing runtime output");+ const container = document.createElement("div");+ container.innerHTML = `+ <marimo-island data-app-id="app-1" data-reactive="true">+ <marimo-cell-output><div>initial output</div></marimo-cell-output>+ <marimo-cell-code hidden>${encodeURIComponent("value = 1")}</marimo-cell-code>+ </marimo-island>+ `;+ await actAndFlush(() => document.body.append(container));++ const island = container.querySelector<HTMLElement>(+ ISLAND_TAG_NAMES.ISLAND,+ );+ expect(island).not.toBeNull();+ expect(island?.getAttribute("data-status")).toBeNull();++ await actAndFlush(() => {+ parseMarimoIslandApps(container);+ });++ expect(island?.textContent).toContain("outgoing runtime output");++ await actAndFlush(() => {+ setNotebook("runtime-cell");+ });++ expect(island?.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");+ expect(island?.getAttribute("data-status")).toBe("idle");++ await actAndFlush(() => {+ island?.remove();+ if (island) {+ container.append(island);+ }+ });+ expect(island?.textContent).toContain("initial output");++ island?.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID, "source-cell");+ island?.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "false");+ expect((island as MarimoIslandElement | null)?.cellId).toBeUndefined();+ });++ it("refreshes a reused payload island and clears an old app binding", async () => {+ const container = document.createElement("div");+ container.innerHTML = `+ <marimo-island+ data-app-id="app-1"+ data-cell-id="cell-1"+ data-reactive="true"+ >+ <marimo-cell-output><div>old output</div></marimo-cell-output>+ <marimo-cell-code hidden>${encodeURIComponent('print("old")')}</marimo-cell-code>+ </marimo-island>+ `;+ const script = document.createElement("script");+ script.type = ISLANDS_JSON_SCRIPT_TYPE;+ script.textContent = payloadSource({+ code: 'print("unchanged")',+ outputHtml: "<div>old output</div>",+ });+ container.append(script);+ await actAndFlush(() => document.body.append(container));++ await actAndFlush(() => {+ parseMarimoIslandApps(container);+ script.textContent = payloadSource({+ code: 'print("unchanged")',+ outputHtml: "<div>updated output</div>",+ });+ parseMarimoIslandApps(container);+ });++ const island = container.querySelector<HTMLElement>(+ ISLAND_TAG_NAMES.ISLAND,+ );+ expect(island?.textContent).toContain("updated output");+ expect(island?.textContent).not.toContain("old output");+ expect(island?.querySelector(ISLAND_TAG_NAMES.CELL_OUTPUT)).toBeNull();++ await actAndFlush(() => {+ setNotebook("outgoing-cell", "outgoing runtime output");+ });+ expect(island?.textContent).toContain("outgoing runtime output");++ await actAndFlush(() => {+ island?.setAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID, "app-2");+ island?.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID, "cell-2");+ script.textContent = payloadSource({+ appId: "app-2",+ cellId: "cell-2",+ code: 'print("next")',+ outputHtml: "<div>next app output</div>",+ });+ parseMarimoIslandApps(container);+ });++ expect(island?.textContent).toContain("next app output");+ expect(island?.textContent).not.toContain("outgoing runtime output");+ });+});++function setNotebook(id: string, output?: string): void {+ const runtimeCellId = cellId(id);+ store.set(+ notebookAtom,+ MockNotebook.notebookState({+ cellData: { [runtimeCellId]: {} },+ cellRuntime: output+ ? {+ [runtimeCellId]: {+ output: {+ channel: "output",+ data: `<div>${output}</div>`,+ mimetype: "text/html",+ timestamp: 0,+ },+ },+ }+ : undefined,+ }),+ );+}++function payloadSource({+ appId = "app-1",+ cellId = "cell-1",+ code,+ outputHtml,+}: {+ appId?: string;+ cellId?: string;+ code: string;+ outputHtml: string;+}): string {+ return JSON.stringify({+ schemaVersion: 1,+ appId,+ cells: [+ {+ cellId,+ code,+ outputHtml,+ outputMimetype: "text/html",+ reactive: true,+ displayCode: false,+ displayOutput: true,+ },+ ],+ });+}++async function actAndFlush(action: () => void): Promise<void> {+ await act(async () => {+ action();+ await Promise.resolve();+ });+}++function setReactActEnvironment(value: boolean): void {+ (+ globalThis as typeof globalThis & {+ IS_REACT_ACT_ENVIRONMENT: boolean;+ }+ ).IS_REACT_ACT_ENVIRONMENT = value;+}diff --git a/frontend/src/core/islands/components/web-components.tsx b/frontend/src/core/islands/components/web-components.tsxindex 557b5e9002..121941129a 100644--- a/frontend/src/core/islands/components/web-components.tsx+++ b/frontend/src/core/islands/components/web-components.tsx@@ -5,7 +5,7 @@ import { isValidElement, type JSX } from "react";import ReactDOM, { type Root } from "react-dom/client";import { ErrorBoundary } from "@/components/editor/boundary/ErrorBoundary";import { TooltipProvider } from "@/components/ui/tooltip";-import { notebookAtom } from "@/core/cells/cells";+import { cellIdsAtom, notebookAtom } from "@/core/cells/cells";import { OBJECT_ID_ATTR } from "@/core/dom/ui-element-constants";import { UI_ELEMENT_REGISTRY } from "@/core/dom/uiregistry";import { LocaleProvider } from "@/core/i18n/locale-provider";@@ -16,9 +16,10 @@ import { store } from "../../state/jotai";import {ISLAND_CSS_CLASSES,ISLAND_DATA_ATTRIBUTES,+ ISLAND_SOURCE_CHANGED_EVENT,ISLAND_TAG_NAMES,} from "../constants";-import { extractIslandCodeFromEmbed } from "../parse";+import { extractIslandCodeFromEmbed, retainIslandSource } from "../parse";import { MarimoOutputWrapper } from "./output-wrapper";/**@@ -28,7 +29,6 @@ export interface IslandRenderConfig {html: string;codeCallback: () => string;editor: JSX.Element | null;- cellId: CellId | undefined;}/**@@ -38,7 +38,12 @@ export interface IslandRenderConfig {* functionality like re-running cells and copying code.*/export class MarimoIslandElement extends HTMLElement {+ private connectionGeneration = 0;private root?: Root;+ private renderConfig?: IslandRenderConfig;+ private runtimeAppId?: string;+ private runtimeCellId?: CellId;+ private unsubscribeCellIds?: () => void;public static readonly tagName = ISLAND_TAG_NAMES.ISLAND;public static readonly outputTagName = ISLAND_TAG_NAMES.CELL_OUTPUT;@@ -72,6 +77,9 @@ export class MarimoIslandElement extends HTMLElement {* Returns undefined for non-reactive islands (they have no corresponding cell).*/get cellId(): CellId | undefined {+ if (!this.isReactive) {+ return undefined;+ }const cellId = this.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID);if (cellId) {return cellId as CellId;@@ -94,11 +102,9 @@ export class MarimoIslandElement extends HTMLElement {/*** Looks up a cell ID from the notebook state by index*/- private getCellIdFromIndex(idx: number): CellId {+ private getCellIdFromIndex(idx: number): CellId | undefined {const { cellIds } = store.get(notebookAtom);- const cellId = cellIds.inOrderIds.at(idx);- invariant(cellId, `Missing cell ID at index ${idx}`);- return cellId;+ return cellIds.inOrderIds.at(idx);}/**@@ -110,18 +116,62 @@ export class MarimoIslandElement extends HTMLElement {* synchronously from there causes "unmount during render" warnings.*/connectedCallback(): void {- // Capture config synchronously (before children get cleared by createRoot)- const config = this.extractRenderConfig();+ const connectionGeneration = ++this.connectionGeneration;+ this.addEventListener(+ ISLAND_SOURCE_CHANGED_EVENT,+ this.handleSourceChanged,+ );+ // Capture config synchronously (before children get cleared by createRoot).+ // A reconnected element reuses the source captured on its first mount.+ if (this.querySelector(MarimoIslandElement.outputTagName)) {+ this.renderConfig = this.extractRenderConfig();+ }+ invariant(this.renderConfig, "Missing island render source");+ this.runtimeAppId = this.appId;+ this.runtimeCellId = this.hasAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)+ ? this.cellId+ : undefined;+ this.syncCellIdsSubscription();queueMicrotask(() => {// Guard against disconnect between connectedCallback and microtask- if (!this.isConnected) {+ if (+ !this.isConnected ||+ connectionGeneration !== this.connectionGeneration+ ) {return;}this.root = ReactDOM.createRoot(this);- this.renderIsland(config);+ this.renderIsland();});}+ private handleSourceChanged = (): void => {+ if (this.querySelector(MarimoIslandElement.outputTagName)) {+ this.renderConfig = this.extractRenderConfig();+ this.querySelector(MarimoIslandElement.outputTagName)?.remove();+ this.querySelector(MarimoIslandElement.codeTagName)?.remove();+ }+ this.runtimeCellId =+ this.isReactive && this.runtimeAppId === this.appId+ ? this.cellId+ : undefined;+ this.runtimeAppId = this.appId;+ this.syncCellIdsSubscription();+ this.renderIsland();+ };++ private syncCellIdsSubscription(): void {+ if (this.isReactive) {+ this.unsubscribeCellIds ??= store.sub(cellIdsAtom, () => {+ this.runtimeCellId = this.cellId;+ this.renderIsland();+ });+ return;+ }+ this.unsubscribeCellIds?.();+ this.unsubscribeCellIds = undefined;+ }+/*** Extracts configuration needed for rendering*/@@ -130,7 +180,7 @@ export class MarimoIslandElement extends HTMLElement {const initialOutput = output.innerHTML;const optionalEditor = this.getOptionalEditor();const code = this.code;- const cellId = this.cellId;+ retainIslandSource(this, { code, output: initialOutput });// Read objectId directly from the DOM before createRoot clears children.// optionalEditor is a <RenderHTML> wrapper, so its .props don't carry the@@ -152,15 +202,19 @@ export class MarimoIslandElement extends HTMLElement {html: initialOutput,codeCallback,editor: optionalEditor,- cellId,};}/*** Renders the island with React*/- private renderIsland(config: IslandRenderConfig): void {- const { html, codeCallback, editor, cellId } = config;+ private renderIsland(): void {+ const config = this.renderConfig;+ if (!config) {+ return;+ }+ const { html, codeCallback, editor } = config;+ const cellId = this.runtimeCellId;const alwaysShowRun = !!editor;const trimmedHtml = html.trim();const isEmpty = trimmedHtml === "<span></span>" || trimmedHtml === "";@@ -168,6 +222,7 @@ export class MarimoIslandElement extends HTMLElement {// Non-reactive islands have no cell in the kernel — just render static HTMLif (!cellId) {+ this.removeAttribute("data-status");this.root?.render(<ErrorBoundary><Provider store={store}>@@ -242,6 +297,12 @@ export class MarimoIslandElement extends HTMLElement {* Cleanup when element is removed from DOM*/disconnectedCallback(): void {+ this.removeEventListener(+ ISLAND_SOURCE_CHANGED_EVENT,+ this.handleSourceChanged,+ );+ this.unsubscribeCellIds?.();+ this.unsubscribeCellIds = undefined;const root = this.root;this.root = undefined;// Defer unmount to avoid "unmount during render" racediff --git a/frontend/src/core/islands/constants.ts b/frontend/src/core/islands/constants.tsindex a54ca97d1d..9167b2d942 100644--- a/frontend/src/core/islands/constants.ts+++ b/frontend/src/core/islands/constants.ts@@ -11,6 +11,7 @@ export const ISLAND_TAG_NAMES = {} as const;export const ISLANDS_JSON_SCRIPT_TYPE = "application/vnd.marimo.islands+json";+export const ISLAND_SOURCE_CHANGED_EVENT = "marimo-island-source-changed";/*** Data attributes for islandsdiff --git a/frontend/src/core/islands/main.ts b/frontend/src/core/islands/main.tsindex 21dd168b8d..e2721cad75 100644--- a/frontend/src/core/islands/main.ts+++ b/frontend/src/core/islands/main.ts@@ -14,12 +14,44 @@ import "iconify-icon";import { Logger } from "@/utils/Logger";import { initializeIslands } from "./bootstrap";import { getGlobalBridge } from "./bridge";+import { ISLAND_CSS_CLASSES, ISLAND_TAG_NAMES } from "./constants";+import { parseMarimoIslandApps } from "./parse";++const bridge = getGlobalBridge();+let bootstrapPromise: Promise<void> | undefined;++/** Returns whether the current document can replace its app in this worker. */+export function canReplaceApp(): boolean {+ if (!document.querySelector(ISLAND_TAG_NAMES.ISLAND)) {+ return false;+ }+ return parseMarimoIslandApps(document, { materialize: false }).length === 1;+}/**- * Main entry point for the js bundle for embedded marimo apps.+ * Mounts marimo custom elements and starts the apps in the current document.*/-export async function initialize() {- await initializeIslands({ bridge: getGlobalBridge() });+export async function initialize(): Promise<void> {+ const islands = document.querySelectorAll<HTMLElement>(+ ISLAND_TAG_NAMES.ISLAND,+ );+ if (islands.length === 0) {+ return;+ }+ for (const island of islands) {+ island.classList.add(ISLAND_CSS_CLASSES.NAMESPACE);+ }+ bootstrapPromise ??= initializeIslands({ bridge }).catch((error: unknown) => {+ bootstrapPromise = undefined;+ throw error;+ });+ await bootstrapPromise;+ await bridge.initializeApps();+}++/** Stops the matching active app session. */+export async function stopApp(appId?: string): Promise<void> {+ await bridge.stopSession(appId);}// Auto-initialize on module loaddiff --git a/frontend/src/core/islands/parse.ts b/frontend/src/core/islands/parse.tsindex 6662b70f66..d6237caa16 100644--- a/frontend/src/core/islands/parse.ts+++ b/frontend/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: {diff --git a/frontend/src/core/islands/worker/__tests__/controller.test.ts b/frontend/src/core/islands/worker/__tests__/controller.test.tsnew file mode 100644index 0000000000..1fc00ec518--- /dev/null+++ b/frontend/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();+ });+});diff --git a/frontend/src/core/islands/worker/worker.tsx b/frontend/src/core/islands/worker/worker.tsxindex 090236f9b8..f17668c6e6 100644--- a/frontend/src/core/islands/worker/worker.tsx+++ b/frontend/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";@@ -50,59 +50,128 @@ const messageBuffer = new MessageBuffer(rpc.send.kernelMessage({ message });},);-const bridgeReady = new Deferred<SerializedBridge>();+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: messageBuffer.push,+ });+ 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 requestsconst 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));+ },- try {+ replaceSession: async (opts: SessionRequest) => {+ await enqueueSession(() => startSession(opts, true));+ },++ 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);++ 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}`;+ 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 +179,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 doneconst { 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 schemaexport type WorkerSchema = RPCSchema<{diff --git a/frontend/src/core/wasm/worker/bootstrap.ts b/frontend/src/core/wasm/worker/bootstrap.tsindex 8339b42225..91ae31d88e 100644--- a/frontend/src/core/wasm/worker/bootstrap.ts+++ b/frontend/src/core/wasm/worker/bootstrap.ts@@ -1,5 +1,6 @@/* Copyright 2026 Marimo. All rights reserved. */import { loadPyodide, type PyodideInterface } from "pyodide";+import type { PyCallable, PyProxy } from "pyodide/ffi";import type { UserConfig } from "@/core/config/config-schema";import type { NotificationPayload } from "@/core/kernel/messages";import type { JsonString } from "@/utils/json/base64";@@ -12,6 +13,12 @@ import type { SerializedBridge, WasmController } from "./types";import { shouldLoadDuckDBPackages } from "../utils";const MAKE_SNAPSHOT = false;+type SessionResources = [+ bridge: PyProxy,+ init: PyCallable,+ packages: PyProxy,+ stop: PyCallable,+];// This class initializes the wasm environment// We would like this initialization to be parallelizable@@ -25,6 +32,9 @@ const MAKE_SNAPSHOT = false;export class DefaultWasmController implements WasmController {protected pyodide: PyodideInterface | null = null;+ private packageLoadQueue = Promise.resolve();+ private sessionGeneration = 0;+ private activeSessionStops = new Set<PyCallable>();get requirePyodide() {invariant(this.pyodide, "Pyodide not loaded");@@ -111,6 +121,7 @@ export class DefaultWasmController implements WasmController {onMessage: (message: JsonString<NotificationPayload>) => void;userConfig: UserConfig;}): Promise<SerializedBridge> {+ const sessionGeneration = this.sessionGeneration;const { code, filename, onMessage, queryParameters, userConfig } = opts;// We pass down a messenger object to the code// This is used to have synchronous communication between the JS and Python code@@ -126,47 +137,129 @@ export class DefaultWasmController implements WasmController {const span = t.startSpan("startSession.runPython");const nbFilename = filename || WasmFileSystem.NOTEBOOK_FILENAME;- const [bridge, init, packages] = this.requirePyodide.runPython(+ const sessionResources = this.requirePyodide.runPython(`print("[py] Starting marimo...")import asyncio+ import gcimport jsfrom marimo._pyodide.bootstrap import create_session, instantiateassert js.messenger, "messenger is not defined"assert js.query_params, "query_params is not defined"- session, bridge = create_session(- filename="${nbFilename}",- query_params=js.query_params.to_py(),- message_callback=js.messenger.callback,- user_config=js.user_config.to_py(),- )+ def create_session_resources():+ session, bridge = create_session(+ filename="${nbFilename}",+ query_params=js.query_params.to_py(),+ message_callback=js.messenger.callback,+ user_config=js.user_config.to_py(),+ )+ session_task = None- def init(auto_instantiate=True):- instantiate(session, auto_instantiate)- asyncio.create_task(session.start())+ def init(auto_instantiate=True):+ nonlocal session_task+ instantiate(session, auto_instantiate)+ session_task = asyncio.create_task(session.start())- # Find the packages to install- with open("${nbFilename}", "r") as f:- packages = session.find_packages(f.read())+ async def stop():+ nonlocal bridge, session, session_task+ task = session_task+ kernel_task = getattr(session, "kernel_task", None)+ if kernel_task is None:+ if task is not None:+ task.cancel()+ else:+ kernel_task.stop()+ if task is not None:+ await asyncio.gather(task, return_exceptions=True)+ if bridge is not None:+ bridge.session = None+ task = None+ kernel_task = None+ session_task = None+ session = None+ bridge = None+ gc.collect()- bridge, init, packages`,- );- span.end();+ with open("${nbFilename}", "r") as f:+ packages = session.find_packages(f.read())- const foundPackages = new Set<string>(packages.toJs());+ return bridge, init, packages, stop++ create_session_resources()`,+ ) as PyProxy;+ span.end();+ let bridgeProxy!: PyProxy;+ let initSession!: PyCallable;+ let packagesProxy!: PyProxy;+ let stopSession!: PyCallable;+ try {+ [bridgeProxy, initSession, packagesProxy, stopSession] =+ sessionResources as unknown as SessionResources;+ } finally {+ sessionResources.destroy();+ }+ let foundPackages: Set<string>;+ try {+ foundPackages = new Set<string>(packagesProxy.toJs());+ } catch (error) {+ bridgeProxy.destroy();+ initSession.destroy();+ stopSession.destroy();+ throw error;+ } finally {+ packagesProxy.destroy();+ }+ this.activeSessionStops.add(stopSession);// Fire and forget:// Load notebook dependencies and instantiate the session// We don't want to wait for this to finish,// so we can show the initial code immediately giving// a sense of responsiveness.- void this.loadNotebookDeps(code, foundPackages).then(() => {- return init(userConfig.runtime.auto_instantiate);+ const dependenciesReady = this.packageLoadQueue.then(() => {+ if (sessionGeneration !== this.sessionGeneration) {+ return;+ }+ return this.loadNotebookDeps(code, foundPackages);});+ this.packageLoadQueue = dependenciesReady.catch(() => undefined);+ void dependenciesReady+ .then(() => {+ if (sessionGeneration !== this.sessionGeneration) {+ return;+ }+ return initSession(userConfig.runtime.auto_instantiate);+ })+ .catch((error: unknown) => {+ Logger.error("Failed to load notebook dependencies", error);+ })+ .finally(() => initSession.destroy());++ return bridgeProxy as unknown as SerializedBridge;+ }- return bridge;+ async stopSession(): Promise<void> {+ this.sessionGeneration += 1;+ const stops = [...this.activeSessionStops];+ let hasFailure = false;+ let firstFailure: unknown;+ for (const stop of stops) {+ try {+ await stop();+ this.activeSessionStops.delete(stop);+ stop.destroy();+ } catch (error) {+ if (!hasFailure) {+ hasFailure = true;+ firstFailure = error;+ }+ }+ }+ if (hasFailure) {+ throw firstFailure;+ }}private async loadNotebookDeps(code: string, foundPackages: Set<string>) {