feat: API for retained WASM island lifecycle by peter-gy · Pull Request #10207 · marimo-team/marimo

peter-gy · 2026-07-17T09:34:24Z

📝 Summary

Adds a retained-runtime lifecycle for static sites that navigate between pages containing marimo islands. Page transitions can replace the active Python app while keeping the worker and Pyodide environment ready.

The islands entry module exports:

canReplaceApp() returns whether the current document contains one replaceable app
stopApp(appId?) stops the matching active app session
initialize() starts, reuses, or replaces the app in the current document

Hosts can call these methods around client-side navigation:

await stopApp()
updatePage()
await initialize()

App transitions are serialized and scoped by app ID and session generation. Rapid or failed transitions preserve session ownership, prevent stale controls from reaching another app, and allow teardown or replacement to be retried.

Worker startup creates and tracks the Python resources for each session. Package loading is serialized, superseded sessions skip initialization, and successful teardown releases the session task and Python references while retaining Pyodide.

Also, island elements now support page content that is upgraded or reused during navigation. They bind after compiled cell IDs become available, refresh when an existing cell ID receives new source, and release static staging output after mounting.

Allow callers to inspect island apps without materializing payloads. Retain payload identities and rendered source so repeated initialization reconstructs the same app after custom elements take ownership of their children.

Own the Python session task and stop callable so an app can be cancelled and collected while Pyodide remains active. Serialize dependency loading and skip initialization work from superseded sessions.

Export canReplaceApp(), initialize(), and stopApp() for hosts that preserve the browser realm across page navigation. Reuse the global worker while serializing app replacement and scoping worker requests by app ID and session generation so stale work cannot reach the active app.

vercel · 2026-07-17T09:34:29Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jul 17, 2026 3:26pm

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

cubic-dev-ai

All reported issues were addressed across 10 files

Architecture diagram

sequenceDiagram
    participant Host as Host Page
    participant Bridge as IslandsPyodideBridge
    participant Worker as Worker Thread
    participant Controller as WasmController
    participant Pyodide as Pyodide Runtime
    participant DOM as DOM / Custom Elements

    Note over Host,DOM: NEW: Retained Island Lifecycle Flow

    Host->>Bridge: canReplaceApp()
    Bridge->>DOM: query islands & parse (materialize: false)
    DOM-->>Bridge: apps list
    alt exactly one app
        Bridge-->>Host: true
    else
        Bridge-->>Host: false
    end

    Host->>Bridge: initialize()
    Bridge->>Bridge: enqueueAppTransition()
    Bridge->>Worker: wait for workerReady
    Worker-->>Bridge: ready
    Bridge->>DOM: parseMarimoIslandApps()
    DOM-->>Bridge: apps with cells

    alt no previous session
        Bridge->>Bridge: generate new sessionGeneration, set session
        Bridge->>Worker: startSession({appId, code, sessionGeneration})
        Worker->>Controller: mountFilesystem & startSession
        Controller->>Pyodide: runPython (create session resources)
        Pyodide-->>Controller: bridge, init, packages, stop
        Controller->>Controller: loadNotebookDeps (serialized on packageLoadQueue)
        Controller-->>Worker: resolved bridge
        Worker-->>Bridge: session started
        Bridge->>Bridge: resolve sessionReady

    else previous session exists and code unchanged
        Bridge->>Bridge: skip (duplicate)
    else previous session exists and code changed (replace)
        Bridge->>Bridge: new sessionGeneration, create deferred sessionReady
        Bridge->>Worker: replaceSession({appId, code, sessionGeneration})
        Worker->>Worker: enqueueSession -> stopActiveSession()
        Worker->>Controller: stopSession()
        Controller->>Controller: increment sessionGeneration, destroy stopCurrentSession
        Controller->>Pyodide: stop() -> cancel kernel, gc
        Pyodide-->>Controller: done
        Controller-->>Worker: stopped
        Worker->>Controller: startSession (as above)
        Controller-->>Worker: new bridge
        Worker-->>Bridge: session replaced
        Bridge->>Bridge: resolve sessionReady (if pending)
    end

    Note over Host,Bridge: Stopping an app

    Host->>Bridge: stopApp(appId)
    Bridge->>Bridge: enqueueAppTransition
    Bridge->>Worker: stopSession({appId, sessionGeneration})
    Worker->>Worker: enqueueSession -> check activeSession matches
    Worker->>Controller: stopSession()
    Controller->>Pyodide: stop() + destroy resources
    Pyodide-->>Controller: done
    Controller-->>Worker: stopped
    Worker-->>Bridge: stopped
    Bridge->>Bridge: clear session

    Note over Host,DOM: Control requests scoped to session

    Host->>Bridge: sendComponentValues (ui-element update)
    Bridge->>Bridge: getActiveSession() -> wait for appTransition + sessionReady
    Bridge->>Worker: bridge({appId, sessionGeneration, functionName: "put_control_request", payload})
    Worker->>Worker: enqueueSession -> requireActiveBridge() validates generation
    Worker->>Pyodide: call bridge[functionName](payload)
    Pyodide-->>Worker: response
    Worker-->>Bridge: response
    Bridge-->>Host: result

    Note over Host,DOM: Replacement failure fallback

    alt replaceSession fails (error)
        Bridge->>Bridge: catch error, clear session if generation matches
        Bridge->>Bridge: keep previous session (fallback)
        Bridge-->>Host: throw error
        Host->>Bridge: initialize() retry
        Bridge->>Bridge: startApps -> sees no session, calls startSession (not replace)
        Bridge->>Worker: startSession (fresh start)
    end

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 12 files (changes from recent commits).

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

mscolnick · 2026-07-17T15:08:29Z

   * Cleanup when element is removed from DOM
   */
  disconnectedCallback(): void {
+    this.connectionGeneration += 1;


are we incrementing on connection and disconnection?

the idea was for connectedCallback() to start a new lifecycle and disconnectedCallback() to explicitly invalidate its pending work, so every lifecycle transition advances the epoch. looking at it again it is probably overkill though because isConnected and the next connection generation already cover the same race.

i think thats actually fine and makes total sense now that i think about it

mscolnick · 2026-07-17T15:17:17Z

 import { shouldLoadDuckDBPackages } from "../utils";

 const MAKE_SNAPSHOT = false;
+type SessionResources = [PyProxy, PyCallable, PyProxy, PyCallable];


nit: could do a typed tuple here [one: PyProxy, two: PyCallable, three: PyProxy, four: PyCallable]

mscolnick

looks great! minor comments

mscolnick

ship!

mscolnick · 2026-07-17T15:27:08Z

oh one last idea, could we add a test that validates the exports and possible the typedef API and snapshots it? since now its a public API that cannot break.

can do in a followup

peter-gy · 2026-07-17T15:54:07Z

oh one last idea, could we add a test that validates the exports and possible the typedef API and snapshots it? since now its a public API that cannot break.

can do in a followup

Oh yes I'll do it in a next pr

github-actions · 2026-07-17T17:32:40Z

🚀 Development release published. You may be able to view the changes at https://marimo.app?v=0.23.15-dev32

peter-gy added 6 commits July 17, 2026 07:49

refactor(islands): make app discovery repeatable

4faa829

Allow callers to inspect island apps without materializing payloads. Retain payload identities and rendered source so repeated initialization reconstructs the same app after custom elements take ownership of their children.

feat(wasm): add session teardown for retained runtimes

4aa58ab

Own the Python session task and stop callable so an app can be cancelled and collected while Pyodide remains active. Serialize dependency loading and skip initialization work from superseded sessions.

feat(islands): make lifecycle initialization repeatable

913aac1

feat(islands): scope controls to app transitions

abd9f55

feat(islands): refresh reused island source

70e0966

Copilot AI review requested due to automatic review settings July 17, 2026 09:34

peter-gy added the internal A refactor or improvement that is not user facing label Jul 17, 2026

Copilot AI reviewed Jul 17, 2026

vercel Bot deployed to Preview July 17, 2026 09:35 View deployment

peter-gy added the api-change label Jul 17, 2026

peter-gy changed the title ~~feat: retained WASM island lifecycle~~ feat: API for retained WASM island lifecycle Jul 17, 2026

cubic-dev-ai Bot reviewed Jul 17, 2026

View reviewed changes

peter-gy added 3 commits July 17, 2026 12:59

feat(wasm): make retained session teardown retryable

77c1b1c

feat(islands): preserve session ownership across transitions

da792ec

feat(islands): refresh retained page bindings

03c6f96

vercel Bot deployed to Preview July 17, 2026 11:19 View deployment

cubic-dev-ai Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread frontend/src/core/wasm/worker/bootstrap.ts Outdated

fix(wasm): propagate falsy teardown failures

fa1a3fc

vercel Bot deployed to Preview July 17, 2026 11:49 View deployment

peter-gy requested a review from mscolnick July 17, 2026 12:05

mscolnick reviewed Jul 17, 2026

View reviewed changes

peter-gy added 2 commits July 17, 2026 17:23

simplify connection lifecycle guard

4e220f0

use typed tuple

4eec1e6

peter-gy requested a review from mscolnick July 17, 2026 15:25

vercel Bot deployed to Preview July 17, 2026 15:26 View deployment

mscolnick approved these changes Jul 17, 2026

View reviewed changes

mscolnick merged commit f37839f into marimo-team:main Jul 17, 2026
27 checks passed

Uh oh!

Conversation

peter-gy commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Summary

Uh oh!

vercel Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mscolnick Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

peter-gy Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

mscolnick Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

mscolnick Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

mscolnick left a comment

Choose a reason for hiding this comment

Uh oh!

mscolnick left a comment

Choose a reason for hiding this comment

Uh oh!

mscolnick commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

peter-gy commented Jul 17, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

peter-gy commented Jul 17, 2026 •

edited

Loading

vercel Bot commented Jul 17, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

mscolnick commented Jul 17, 2026 •

edited

Loading