@marimo-team/frontend 0.23.12-dev10 → 0.23.12-dev11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marimo-team/frontend",
-  "version": "0.23.12-dev10",
+  "version": "0.23.12-dev11",
   "main": "dist/main.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/src/core/islands/__tests__/bridge.test.ts

@@ -12,6 +12,7 @@ import {
 type Base64String = components["schemas"]["Base64String"];
 interface TestIslandApp {
   id: string;
+  payloadBacked?: boolean;
   cells: { code: string; idx: number; output: string }[];
 }
 interface TestExportContext {
@@ -142,6 +143,30 @@ describe("IslandsPyodideBridge", () => {
       });
     });
 
+    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>" }],
+      };
+      mockParseMarimoIslandApps.mockReturnValue([payloadApp]);
+      mockGetMarimoExportContext.mockReturnValue({
+        trusted: true,
+        notebookCode: "full notebook should be ignored",
+      });
+      mockCreateMarimoFile.mockReturnValue("generated payload app");
+
+      await (
+        bridge as unknown as { startSessionsForAllApps(): Promise<void> }
+      ).startSessionsForAllApps();
+
+      expect(mockCreateMarimoFile).toHaveBeenCalledWith(payloadApp);
+      expect(mockStartSessionRequest).toHaveBeenCalledWith({
+        appId: "app-1",
+        code: "generated payload app",
+      });
+    });
+
     it("should keep synthesized per-app files for multiple reactive apps even when export context exists", async () => {
       mockParseMarimoIslandApps.mockReturnValue([
         {

package/src/core/islands/__tests__/parse.test.ts

@@ -1,9 +1,12 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   ISLAND_DATA_ATTRIBUTES,
   ISLAND_TAG_NAMES,
+  ISLANDS_JSON_SCRIPT_TYPE,
 } from "@/core/islands/constants";
+import { Logger } from "@/utils/Logger";
 import {
   createMarimoFile,
   extractIslandCodeFromEmbed,
@@ -15,6 +18,43 @@ import {
 } from "../parse";
 import { createMockIslandElement, createMockIslands } from "./test-utils.tsx";
 
+function createPayloadCell(
+  overrides: Partial<{
+    cellId: string;
+    code: string;
+    outputHtml: string;
+    outputMimetype: string;
+    reactive: boolean;
+    displayCode: boolean;
+    displayOutput: boolean;
+  }> = {},
+) {
+  return {
+    cellId: "cell-1",
+    code: 'print("payload")',
+    outputHtml: "<div>payload</div>",
+    outputMimetype: "text/html",
+    reactive: true,
+    displayCode: false,
+    displayOutput: true,
+    ...overrides,
+  };
+}
+
+function appendPayload(
+  root: HTMLElement,
+  payload: {
+    schemaVersion: number;
+    appId: string;
+    cells: ReturnType<typeof createPayloadCell>[];
+  },
+) {
+  const script = document.createElement("script");
+  script.type = ISLANDS_JSON_SCRIPT_TYPE;
+  script.textContent = JSON.stringify(payload);
+  root.appendChild(script);
+}
+
 describe("createMarimoFile", () => {
   it("should return a string", () => {
     const app = {
@@ -90,6 +130,27 @@ describe("createMarimoFile", () => {
     `);
   });
 
+  it("should create disabled marimo cells", () => {
+    const app = {
+      cells: [{ code: "x = 0", disabled: true }, { code: "x = 1" }],
+    };
+
+    const result = createMarimoFile(app);
+
+    expect(result).toMatchInlineSnapshot(`
+      "import marimo
+      app = marimo.App()
+      @app.cell(disabled=True)
+      def __():
+          pass
+          return
+      @app.cell
+      def __():
+          x = 1
+          return"
+    `);
+  });
+
   it("should properly indent multi-line code", () => {
     const app = {
       cells: [{ code: "if True:\n    print('hello')\n    print('world')" }],
@@ -459,6 +520,7 @@ describe("parseMarimoIslandApps", () => {
 
   afterEach(() => {
     document.body.removeChild(container);
+    vi.restoreAllMocks();
   });
 
   it("should parse islands from document", () => {
@@ -528,4 +590,526 @@ describe("parseMarimoIslandApps", () => {
       ]
     `);
   });
+
+  it("should use supported JSON payload data for matched islands", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: 'print("dom")',
+      innerHTML: "<div>dom</div>",
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [createPayloadCell()],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result).toEqual([
+      {
+        id: "app1",
+        payloadBacked: true,
+        cells: [
+          {
+            cellId: "cell-1",
+            code: 'print("payload")',
+            idx: 0,
+            output: "<div>payload</div>",
+          },
+        ],
+      },
+    ]);
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID)).toBeNull();
+    expect(extractIslandCodeFromEmbed(island)).toBe('print("payload")');
+    expect(island.querySelector(ISLAND_TAG_NAMES.CELL_OUTPUT)?.innerHTML).toBe(
+      "<div>payload</div>",
+    );
+  });
+
+  it("should parse Python-generated island payload snapshots", () => {
+    const html = readFileSync(
+      new URL(
+        "../../../../../tests/_islands/snapshots/html-payload.txt",
+        import.meta.url,
+      ).pathname.replace(/^\/@fs/, ""),
+      "utf8",
+    );
+    container.innerHTML = html;
+
+    const result = parseMarimoIslandApps(container);
+    const islands = container.querySelectorAll<HTMLElement>(
+      ISLAND_TAG_NAMES.ISLAND,
+    );
+
+    expect(result).toEqual([
+      {
+        id: "main",
+        payloadBacked: true,
+        cells: [
+          {
+            cellId: "Hbol",
+            code: "import marimo as mo",
+            idx: 0,
+            output: "",
+          },
+          {
+            cellId: "MJUe",
+            code: "mo.md('Hello, HTML!')",
+            idx: 1,
+            output: "",
+          },
+        ],
+      },
+    ]);
+    expect(islands[0].getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBeNull();
+    expect(islands[1].getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");
+    expect(islands[2].getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("1");
+  });
+
+  it("should fall back to DOM islands for unsupported payload versions", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: 'print("dom")',
+      innerHTML: "<div>dom</div>",
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 2,
+      appId: "app1",
+      cells: [createPayloadCell()],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result).toEqual([
+      {
+        id: "app1",
+        cells: [
+          {
+            code: 'print("dom")',
+            idx: 0,
+            output: "<div>dom</div>",
+          },
+        ],
+      },
+    ]);
+  });
+
+  it("should ignore payload scripts rendered inside island output", () => {
+    const nestedPayload = {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          code: "payload_code_should_not_run = True",
+          outputHtml: "<div>payload</div>",
+        }),
+      ],
+    };
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: 'print("dom")',
+      innerHTML: `<div>dom</div><script type="${ISLANDS_JSON_SCRIPT_TYPE}">${JSON.stringify(nestedPayload)}</script>`,
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.appendChild(island);
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result).toEqual([
+      {
+        id: "app1",
+        cells: [
+          {
+            code: 'print("dom")',
+            idx: 0,
+            output: island.querySelector(ISLAND_TAG_NAMES.CELL_OUTPUT)
+              ?.innerHTML,
+          },
+        ],
+      },
+    ]);
+  });
+
+  it("should use payload order for runtime cell indices", () => {
+    const second = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-2",
+      code: "second_dom = True",
+      innerHTML: "<div>second dom</div>",
+    });
+    const first = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: "first_dom = True",
+      innerHTML: "<div>first dom</div>",
+    });
+    for (const island of [second, first]) {
+      island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+      container.appendChild(island);
+    }
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          cellId: "cell-1",
+          code: "first_payload = True",
+          outputHtml: "<div>first payload</div>",
+        }),
+        createPayloadCell({
+          cellId: "cell-2",
+          code: "second_payload = True",
+          outputHtml: "<div>second payload</div>",
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result[0].cells.map((cell) => cell.code)).toEqual([
+      "first_payload = True",
+      "second_payload = True",
+    ]);
+    expect(first.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");
+    expect(second.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("1");
+  });
+
+  it("should include payload-only runtime cells", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-2",
+      code: "value",
+      innerHTML: "<div>value</div>",
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          cellId: "cell-1",
+          code: "import marimo as mo",
+          outputHtml: "",
+        }),
+        createPayloadCell({
+          cellId: "cell-2",
+          code: "mo.md('visible')",
+          outputHtml: "<div>visible</div>",
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result[0].cells.map((cell) => cell.code)).toEqual([
+      "import marimo as mo",
+      "mo.md('visible')",
+    ]);
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("1");
+  });
+
+  it("should bind payload-backed islands by runtime index after static cells", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-2",
+      code: "visible_dom = True",
+      innerHTML: "<div>visible dom</div>",
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          cellId: "cell-1",
+          code: "",
+          outputHtml: "<div>static</div>",
+          reactive: false,
+        }),
+        createPayloadCell({
+          cellId: "cell-2",
+          code: "visible_payload = True",
+          outputHtml: "<div>visible payload</div>",
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result[0].cells).toEqual([
+      {
+        cellId: "cell-1",
+        code: "",
+        disabled: true,
+        idx: 0,
+        output: "<div>static</div>",
+      },
+      {
+        cellId: "cell-2",
+        code: "visible_payload = True",
+        idx: 1,
+        output: "<div>visible payload</div>",
+      },
+    ]);
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("1");
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID)).toBeNull();
+  });
+
+  it("should fall back to DOM when no payload cell matches an island", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "dom-only",
+      code: "dom_only = True",
+      innerHTML: "<div>dom only</div>",
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    island.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          cellId: "payload-only",
+          code: "payload_only = True",
+          outputHtml: "<div>payload only</div>",
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result).toEqual([
+      {
+        id: "app1",
+        cells: [
+          {
+            code: "dom_only = True",
+            idx: 0,
+            output: "<div>dom only</div>",
+          },
+        ],
+      },
+    ]);
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID)).toBe(
+      "dom-only",
+    );
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE)).toBe("true");
+  });
+
+  it("should ignore payloads without matching islands", () => {
+    const warn = vi.spyOn(Logger, "warn").mockImplementation(() => undefined);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [createPayloadCell()],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result).toEqual([]);
+    expect(warn).toHaveBeenCalledWith("No embedded marimo apps found.");
+  });
+
+  it("should still parse DOM-only apps when another app has payload", () => {
+    const payloadIsland = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: "payload_dom = True",
+      innerHTML: "<div>payload dom</div>",
+    });
+    const domIsland = createMockIslandElement({
+      appId: "app2",
+      code: "dom_app = True",
+      innerHTML: "<div>dom app</div>",
+    });
+    for (const island of [payloadIsland, domIsland]) {
+      island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+      container.appendChild(island);
+    }
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [createPayloadCell()],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result.map((app) => app.id)).toEqual(["app1", "app2"]);
+    expect(result[0].cells[0].code).toBe('print("payload")');
+    expect(result[1].cells[0].code).toBe("dom_app = True");
+  });
+
+  it("should materialize non-reactive payload islands without runtime cells", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: "static_dom = True",
+      innerHTML: "<div>static dom</div>",
+    });
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "false");
+    island.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          code: "",
+          outputHtml: "<div>static payload</div>",
+          reactive: false,
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result).toEqual([]);
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBeNull();
+    expect(island.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID)).toBeNull();
+    expect(island.querySelector(ISLAND_TAG_NAMES.CELL_OUTPUT)?.innerHTML).toBe(
+      "<div>static payload</div>",
+    );
+  });
+
+  it("should keep non-reactive display code out of runtime cells", () => {
+    const staticIsland = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: "x = 0",
+      innerHTML: "<div>static</div>",
+    });
+    const reactiveIsland = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-2",
+      code: "y = 1",
+      innerHTML: "<div>reactive</div>",
+    });
+    staticIsland.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "false");
+    reactiveIsland.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.append(staticIsland, reactiveIsland);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          cellId: "cell-1",
+          code: "x = 0",
+          outputHtml: "<div>static payload</div>",
+          reactive: false,
+          displayCode: true,
+        }),
+        createPayloadCell({
+          cellId: "cell-2",
+          code: "y = 1",
+          outputHtml: "<div>reactive payload</div>",
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+    const file = createMarimoFile(result[0]);
+
+    expect(result[0].cells).toEqual([
+      {
+        cellId: "cell-1",
+        code: "",
+        disabled: true,
+        idx: 0,
+        output: "<div>static payload</div>",
+      },
+      {
+        cellId: "cell-2",
+        code: "y = 1",
+        idx: 1,
+        output: "<div>reactive payload</div>",
+      },
+    ]);
+    expect(file).not.toContain("x = 0");
+    expect(file).toContain("@app.cell(disabled=True)\ndef __():\n    pass");
+    expect(reactiveIsland.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe(
+      "1",
+    );
+  });
+
+  it("should update editor initial values from payload code", () => {
+    const island = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: 'print("dom")',
+      innerHTML: "<div>dom</div>",
+    });
+    island.insertAdjacentHTML(
+      "beforeend",
+      '<div data-marimo-element><marimo-code-editor data-initial-value="\\"print(\\\\\\"dom\\\\\\")\\""></marimo-code-editor></div>',
+    );
+    island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+    container.appendChild(island);
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [createPayloadCell()],
+    });
+
+    parseMarimoIslandApps(container);
+
+    expect(
+      island
+        .querySelector(ISLAND_TAG_NAMES.CODE_EDITOR)
+        ?.getAttribute("data-initial-value"),
+    ).toBe(JSON.stringify('print("payload")'));
+  });
+
+  it("should match duplicate cell ids by occurrence", () => {
+    const first = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: "dom_first = True",
+      innerHTML: "<div>dom first</div>",
+    });
+    const second = createMockIslandElement({
+      appId: "app1",
+      cellId: "cell-1",
+      code: "dom_second = True",
+      innerHTML: "<div>dom second</div>",
+    });
+    for (const island of [first, second]) {
+      island.setAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE, "true");
+      container.appendChild(island);
+    }
+    appendPayload(container, {
+      schemaVersion: 1,
+      appId: "app1",
+      cells: [
+        createPayloadCell({
+          code: "payload_first = True",
+          outputHtml: "<div>payload first</div>",
+        }),
+        createPayloadCell({
+          code: "payload_second = True",
+          outputHtml: "<div>payload second</div>",
+        }),
+      ],
+    });
+
+    const result = parseMarimoIslandApps(container);
+
+    expect(result[0].cells.map((cell) => cell.code)).toEqual([
+      "payload_first = True",
+      "payload_second = True",
+    ]);
+    expect(first.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("0");
+    expect(second.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX)).toBe("1");
+  });
 });

package/src/core/islands/__tests__/test-utils.tsx

@@ -23,12 +23,14 @@ import type { WorkerFactory } from "@/core/islands/worker-factory";
 export function createMockIslandElement(options: {
   appId?: string;
   cellIdx?: string;
+  cellId?: string;
   code?: string;
   innerHTML?: string;
 }): HTMLElement {
   const {
     appId = "test-app",
     cellIdx = "0",
+    cellId,
     code = "import marimo as mo",
     innerHTML = "",
   } = options;
@@ -36,6 +38,9 @@ export function createMockIslandElement(options: {
   const element = document.createElement(ISLAND_TAG_NAMES.ISLAND);
   element.setAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID, appId);
   element.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, cellIdx);
+  if (cellId) {
+    element.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID, cellId);
+  }
 
   if (code) {
     const codeElement = document.createElement(ISLAND_TAG_NAMES.CELL_CODE);
@@ -146,6 +151,7 @@ export async function waitForNoError<T>(
 
 export interface IslandSpec {
   appId?: string;
+  cellId?: string;
   reactive?: boolean;
   code?: string;
   output?: string;
@@ -160,6 +166,9 @@ export function buildIslandHTML(islands: IslandSpec[]): string {
   return islands
     .map((spec) => {
       const appId = spec.appId ?? "test-app";
+      const cellId = spec.cellId
+        ? ` ${ISLAND_DATA_ATTRIBUTES.CELL_ID}="${spec.cellId}"`
+        : "";
       const reactive = spec.reactive ?? true;
       const output = spec.output ?? "<div>output</div>";
       const code = spec.code ?? 'print("hello")';
@@ -169,7 +178,7 @@ export function buildIslandHTML(islands: IslandSpec[]): string {
         : "";
       const outputTag = `<${ISLAND_TAG_NAMES.CELL_OUTPUT}>${output}</${ISLAND_TAG_NAMES.CELL_OUTPUT}>`;
 
-      return `<${ISLAND_TAG_NAMES.ISLAND} ${ISLAND_DATA_ATTRIBUTES.APP_ID}="${appId}" ${ISLAND_DATA_ATTRIBUTES.REACTIVE}="${reactive}">${outputTag}${codeTag}</${ISLAND_TAG_NAMES.ISLAND}>`;
+      return `<${ISLAND_TAG_NAMES.ISLAND} ${ISLAND_DATA_ATTRIBUTES.APP_ID}="${appId}"${cellId} ${ISLAND_DATA_ATTRIBUTES.REACTIVE}="${reactive}">${outputTag}${codeTag}</${ISLAND_TAG_NAMES.ISLAND}>`;
     })
     .join("\n");
 }

package/src/core/islands/bridge.ts

@@ -124,8 +124,13 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {
       `Starting sessions for ${apps.length} app(s):`,
       apps.map((a) => `${a.id} (${a.cells.length} cells)`),
     );
+    // Payload-backed apps already carry the exact runtime cells and order. The
+    // full-notebook export context may describe a different source and would
+    // override the payload contract for single-app pages.
     const exportContext =
-      apps.length === 1 ? getMarimoExportContext() : undefined;
+      apps.length === 1 && !apps[0]?.payloadBacked
+        ? getMarimoExportContext()
+        : undefined;
     const notebookCode = exportContext?.notebookCode;
     for (const app of apps) {
       const file = notebookCode || createMarimoFile(app);

package/src/core/islands/constants.ts

@@ -10,6 +10,8 @@ export const ISLAND_TAG_NAMES = {
   CODE_EDITOR: "marimo-code-editor",
 } as const;
 
+export const ISLANDS_JSON_SCRIPT_TYPE = "application/vnd.marimo.islands+json";
+
 /**
  * Data attributes for islands
  */

package/src/core/islands/parse.ts

@@ -3,6 +3,7 @@
 import {
   ISLAND_DATA_ATTRIBUTES,
   ISLAND_TAG_NAMES,
+  ISLANDS_JSON_SCRIPT_TYPE,
 } from "@/core/islands/constants";
 import { Logger } from "@/utils/Logger";
 
@@ -23,6 +24,10 @@ export interface MarimoIslandApp {
    * ID since we allow multiple apps on the same page.
    */
   id: string;
+  /**
+   * Whether cells came from a supported JSON payload instead of DOM parsing.
+   */
+  payloadBacked?: boolean;
   /**
    * Cells in the app.
    */
@@ -42,6 +47,30 @@ interface MarimoIslandCell {
    * Index of the cell.
    */
   idx: number;
+  /**
+   * Stable cell identifier, when provided by the island payload.
+   */
+  cellId?: string;
+  /**
+   * Whether the generated marimo cell should be present but not executed.
+   */
+  disabled?: boolean;
+}
+
+interface MarimoIslandPayload {
+  schemaVersion: 1;
+  appId: string;
+  cells: MarimoIslandPayloadCell[];
+}
+
+interface MarimoIslandPayloadCell {
+  cellId: string;
+  code: string;
+  outputHtml: string;
+  outputMimetype: string;
+  reactive: boolean;
+  displayCode: boolean;
+  displayOutput: boolean;
 }
 
 /**
@@ -51,14 +80,20 @@ interface MarimoIslandCell {
 export function parseMarimoIslandApps(
   root: Document | Element = document,
 ): MarimoIslandApp[] {
-  const embeds = root.querySelectorAll<HTMLElement>(ISLAND_TAG_NAMES.ISLAND);
+  const embeds = [
+    ...root.querySelectorAll<HTMLElement>(ISLAND_TAG_NAMES.ISLAND),
+  ];
+  const payloads = parseMarimoIslandPayloads(root);
   if (embeds.length === 0) {
     Logger.warn("No embedded marimo apps found.");
     return [];
   }
 
-  // eslint-disable-next-line prefer-spread
-  return parseIslandElementsIntoApps(Array.from(embeds));
+  if (payloads.length > 0) {
+    return parsePayloadBackedApps(embeds, payloads);
+  }
+
+  return parseIslandElementsIntoApps(embeds);
 }
 
 /**
@@ -90,11 +125,12 @@ export function parseIslandElementsIntoApps(
       continue;
     }
 
-    if (!apps.has(appId)) {
-      apps.set(appId, { id: appId, cells: [] });
+    let app = apps.get(appId);
+    if (!app) {
+      app = { id: appId, cells: [] };
+      apps.set(appId, app);
     }
 
-    const app = apps.get(appId)!;
     const idx = app.cells.length;
     app.cells.push({
       output: cellData.output,
@@ -109,6 +145,159 @@ export function parseIslandElementsIntoApps(
   return [...apps.values()];
 }
 
+function parsePayloadBackedApps(
+  embeds: HTMLElement[],
+  payloads: MarimoIslandPayload[],
+): MarimoIslandApp[] {
+  const apps = new Map<string, MarimoIslandApp>();
+  const matchedPayloadCells = new Map<MarimoIslandPayloadCell, HTMLElement>();
+  const consumedEmbeds = new Set<HTMLElement>();
+  const acceptedPayloads: MarimoIslandPayload[] = [];
+
+  for (const payload of payloads) {
+    let hasMatchedIsland = false;
+    for (const cell of payload.cells) {
+      const embed = findMatchingIsland({
+        embeds,
+        appId: payload.appId,
+        cell,
+        consumedEmbeds,
+      });
+      if (!embed) {
+        continue;
+      }
+      consumedEmbeds.add(embed);
+      matchedPayloadCells.set(cell, embed);
+      materializeIslandPayload(embed, cell);
+      hasMatchedIsland = true;
+    }
+    // Only payloads matched to island anchors can start runtime apps.
+    if (hasMatchedIsland) {
+      acceptedPayloads.push(payload);
+    }
+  }
+
+  const payloadAppIds = new Set(
+    acceptedPayloads.map((payload) => payload.appId),
+  );
+  const reactivePayloadAppIds = new Set(
+    acceptedPayloads
+      .filter((payload) => payload.cells.some((cell) => cell.reactive))
+      .map((payload) => payload.appId),
+  );
+
+  for (const payload of acceptedPayloads) {
+    for (const cell of payload.cells) {
+      const embed = matchedPayloadCells.get(cell);
+      // Static-only payload apps render from HTML and do not need a Pyodide
+      // session.
+      if (!reactivePayloadAppIds.has(payload.appId)) {
+        continue;
+      }
+
+      let app = apps.get(payload.appId);
+      if (!app) {
+        app = { id: payload.appId, payloadBacked: true, cells: [] };
+        apps.set(payload.appId, app);
+      }
+
+      const idx = app.cells.length;
+      const appCell: MarimoIslandCell = {
+        cellId: cell.cellId,
+        output: cell.outputHtml,
+        code: cell.reactive ? cell.code : "",
+        idx: idx,
+      };
+      // Keep static cells in the generated file so later reactive cells keep
+      // stable runtime indices without executing static code.
+      if (!cell.reactive) {
+        appCell.disabled = true;
+      }
+      app.cells.push(appCell);
+      if (cell.reactive) {
+        embed?.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, idx.toString());
+      }
+    }
+  }
+
+  // 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");
+    }
+  }
+
+  const domOnlyEmbeds = embeds.filter((embed) => {
+    const appId = embed.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
+    return !appId || !payloadAppIds.has(appId);
+  });
+
+  return [...apps.values(), ...parseIslandElementsIntoApps(domOnlyEmbeds)];
+}
+
+function findMatchingIsland({
+  embeds,
+  appId,
+  cell,
+  consumedEmbeds,
+}: {
+  embeds: HTMLElement[];
+  appId: string;
+  cell: MarimoIslandPayloadCell;
+  consumedEmbeds: Set<HTMLElement>;
+}): HTMLElement | undefined {
+  return embeds.find((embed) => {
+    if (consumedEmbeds.has(embed)) {
+      return false;
+    }
+    return (
+      embed.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID) === appId &&
+      embed.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID) === cell.cellId
+    );
+  });
+}
+
+function materializeIslandPayload(
+  embed: HTMLElement,
+  cell: MarimoIslandPayloadCell,
+): void {
+  embed.setAttribute(
+    ISLAND_DATA_ATTRIBUTES.REACTIVE,
+    JSON.stringify(cell.reactive),
+  );
+  // The runtime file is synthesized from payload order, so DOM anchors bind
+  // by index.
+  embed.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID);
+  if (!cell.reactive) {
+    embed.removeAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
+  }
+
+  const output = ensureIslandChild(embed, ISLAND_TAG_NAMES.CELL_OUTPUT);
+  output.innerHTML = cell.displayOutput ? cell.outputHtml : "";
+
+  const code = ensureIslandChild(embed, ISLAND_TAG_NAMES.CELL_CODE);
+  code.hidden = true;
+  code.textContent = encodeURIComponent(cell.code);
+
+  const editor = embed.querySelector<HTMLElement>(ISLAND_TAG_NAMES.CODE_EDITOR);
+  if (editor) {
+    editor.setAttribute("data-initial-value", JSON.stringify(cell.code));
+  }
+}
+
+function ensureIslandChild(embed: HTMLElement, tagName: string): HTMLElement {
+  let child = embed.querySelector<HTMLElement>(tagName);
+  if (!child) {
+    child = embed.ownerDocument.createElement(tagName);
+    embed.appendChild(child);
+  }
+  return child;
+}
+
 /**
  * Parses a single island element into cell data
  * @param embed - The island HTML element
@@ -132,26 +321,35 @@ export function parseIslandElement(
   };
 }
 
-export function createMarimoFile(app: { cells: { code: string }[] }): string {
+export function createMarimoFile(app: {
+  cells: { code: string; disabled?: boolean }[];
+}): string {
   const lines = [
     "import marimo",
     "app = marimo.App()",
     app.cells
       .map((cell) => {
-        // Add 4 spaces to each line
-        const code = cell.code
-          .split("\n")
-          .map((line) => `    ${line}`)
-          .join("\n");
+        // Disabled payload cells are placeholders. Emit pass so static code
+        // does not define names in the runtime graph.
+        const sourceCode = cell.disabled ? "" : cell.code;
+        const code = sourceCode
+          ? sourceCode
+              .split("\n")
+              .map((line) => `    ${line}`)
+              .join("\n")
+          : "    pass";
 
         // TODO: Handle async cells better
         // This is probably not the best way to check if the code is async
         // Ideally this is pushed into the Python code
         const isAsync = code.includes("await ");
         const prefix = isAsync ? "async def" : "def";
+        const decorator = cell.disabled
+          ? "@app.cell(disabled=True)"
+          : "@app.cell";
 
         // Wrap in a function
-        return `@app.cell\n${prefix} __():\n${code}\n    return`;
+        return `${decorator}\n${prefix} __():\n${code}\n    return`;
       })
       .join("\n"),
   ];
@@ -204,3 +402,85 @@ export function extractIslandCodeFromEmbed(embed: HTMLElement): string {
 
   return "";
 }
+
+function parseMarimoIslandPayloads(
+  root: Document | Element,
+): MarimoIslandPayload[] {
+  const scripts = root.querySelectorAll<HTMLScriptElement>(
+    `script[type="${ISLANDS_JSON_SCRIPT_TYPE}"]`,
+  );
+  const payloads: MarimoIslandPayload[] = [];
+
+  for (const script of scripts) {
+    if (isNestedIslandPayloadScript(script)) {
+      continue;
+    }
+    const payload = parseMarimoIslandPayload(script.textContent);
+    if (payload) {
+      payloads.push(payload);
+    }
+  }
+
+  return payloads;
+}
+
+function isNestedIslandPayloadScript(script: HTMLScriptElement): boolean {
+  return Boolean(
+    script.closest(ISLAND_TAG_NAMES.ISLAND) ||
+    script.closest(ISLAND_TAG_NAMES.CELL_OUTPUT),
+  );
+}
+
+function parseMarimoIslandPayload(
+  text: string | undefined | null,
+): MarimoIslandPayload | null {
+  if (!text) {
+    return null;
+  }
+
+  try {
+    const payload = JSON.parse(text);
+    if (isMarimoIslandPayload(payload)) {
+      return payload;
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+function isMarimoIslandPayload(
+  payload: unknown,
+): payload is MarimoIslandPayload {
+  if (!isRecord(payload)) {
+    return false;
+  }
+  return (
+    payload.schemaVersion === 1 &&
+    typeof payload.appId === "string" &&
+    Array.isArray(payload.cells) &&
+    payload.cells.every(isMarimoIslandPayloadCell)
+  );
+}
+
+function isMarimoIslandPayloadCell(
+  cell: unknown,
+): cell is MarimoIslandPayloadCell {
+  if (!isRecord(cell)) {
+    return false;
+  }
+  return (
+    typeof cell.cellId === "string" &&
+    typeof cell.code === "string" &&
+    typeof cell.outputHtml === "string" &&
+    typeof cell.outputMimetype === "string" &&
+    typeof cell.reactive === "boolean" &&
+    typeof cell.displayCode === "boolean" &&
+    typeof cell.displayOutput === "boolean"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}