feat: hydrate islands from JSON payloads

[peter-gy]

Adds JSON payloads to island exports. The islands runtime can hydrate from a structured payload instead of recovering source and metadata from each island's DOM. This reduces the island-contract logic we need to maintain in static exporters like https://github.com/marimo-team/quarto-marimo and https://github.com/marimo-team/jupyter-book-marimo.

What changed

• MarimoIslandGenerator now emits a JSON script tag on opt-in:

<script type="application/vnd.marimo.islands+json">{"schemaVersion":1,"appId":"main","cells":[...]}</script>

• Each cell payload includes code, outputHtml, outputMimetype, reactive, displayCode, and displayOutput.

{
  "cellId": "1faffc38-d97b-492e-9ffc-7c77d08d0d8fMJUe",
  "code": "mo.md(r\"\"\"\nI am static markdown.\n\"\"\")",
  "outputHtml": "<marimo-mime-renderer data-mime='&quot;text/markdown&quot;' data-data='&quot;&#92;u003cspan class=&#92;&quot;markdown prose dark:prose-invert contents&#92;&quot;&#92;u003e&#92;u003cspan class=&#92;&quot;paragraph&#92;&quot;&#92;u003eI am static markdown.&#92;u003c/span&#92;u003e&#92;u003c/span&#92;u003e&quot;'></marimo-mime-renderer>",
  "outputMimetype": "text/markdown",
  "reactive": true,
  "displayCode": false,
  "displayOutput": true
}

• The frontend island parser validates schema v1 payloads and builds payload-backed apps from JSON.
• DOM parsing remains the fallback for pages that do not include a payload.
• For payload-backed apps, the DOM still provides the visible island slots. The JSON payload provides the runtime cell code and output metadata.

Follow-ups

• size of outputHtml can be potentially huge. we could consider emitting a base64-encoded string inside <script type="application/vnd.marimo.islands+jsonb64"> if this becomes an issue. Quarto does the same for their ObservableJS support.
• to make the job of static exporters even easier, we could add a MarimoIslandGenerator.from_ir API which would accept a NotebookSerialization object

Demo

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
marimo-docs	Ready	Preview, Comment	Jun 26, 2026 8:01pm

[cubic-dev-ai]

1 issue found and verified against the latest diff

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="marimo/_islands/_island_generator.py">

<violation number="1" location="marimo/_islands/_island_generator.py:569">
P2: Default-on JSON payload duplicates island data already present in DOM, causing page-size and performance regressions for large outputs.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 1 file (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[Copilot]

Pull request overview

Adds an optional JSON “islands payload” export path so the frontend can hydrate island apps from structured data (cells/code/output metadata) instead of reconstructing everything from DOM attributes and encoded code blocks. This reduces the exporter/runtime contract surface for static HTML generators while preserving DOM parsing as a fallback.

Changes:

• Python: MarimoIslandGenerator can emit an inert <script type="application/vnd.marimo.islands+json">…</script> payload (opt-in via include_payload) with per-cell code/output metadata and HTML-sensitive escaping.
• Frontend: island parsing can consume schema v1 payloads to build “payload-backed” apps (with DOM anchors still used for visible slots), falling back to DOM parsing when payloads aren’t present/valid.
• Tests/docs: adds payload-focused tests, an HTML snapshot containing the payload, and documentation describing the payload contract.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
marimo/_islands/_island_generator.py	Adds payload schema/constants and payload/script rendering with JSON escaping; threads include_payload through HTML/body renderers.
tests/_islands/test_island_generator.py	Adds unit tests for payload generation, option behavior, and script escaping.
tests/_islands/snapshots/html-payload.txt	Snapshot of HTML output including the payload script tag.
frontend/src/core/islands/constants.ts	Defines the payload script MIME type constant.
frontend/src/core/islands/parse.ts	Adds payload parsing/validation + payload-backed hydration path and disabled-cell support in synthesized marimo files.
frontend/src/core/islands/bridge.ts	Ensures payload-backed apps don’t get overridden by full-notebook export context.
frontend/src/core/islands/__tests__/test-utils.tsx	Extends test helpers to support data-cell-id.
frontend/src/core/islands/__tests__/parse.test.ts	Adds extensive tests for payload parsing/materialization and disabled cell synthesis.
frontend/src/core/islands/__tests__/bridge.test.ts	Tests that export-context notebook code is ignored for payload-backed apps.
docs/guides/exporting/webassembly_html.md	Documents island payloads, escaping behavior, and post-processing guidance.

[peter-gy]

rebased this to resolve the merge conflict but now CI seems to fail due to fcf95a2 (?)

[mscolnick]

@peter-gy maybe there is a cycle or something off about the imports

[peter-gy]

Had to bump ruff to 0.15.18 in packages/pytest_changed/__init__.py as ruff@0.15.16 could not parse the D421 rule which was added in #9992.

Looks like this CI failure did not come up in other commits as other gh flows did not reach the branch where uvx ruff@0.15.16 analyze graph --detect-string-imports --direction dependents . got called.

[github-actions]

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