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

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;
+}