@marimo-team/islands 0.23.12-dev8 → 0.23.12

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
  */