@marimo-team/frontend 0.23.1-dev8 → 0.23.1

package/src/core/islands/components/web-components.tsx

@@ -11,73 +11,172 @@ import { UI_ELEMENT_REGISTRY } from "@/core/dom/uiregistry";
 import { LocaleProvider } from "@/core/i18n/locale-provider";
 import { renderHTML } from "@/plugins/core/RenderHTML";
 import { invariant } from "@/utils/invariant";
-import type { CellId } from "../../cells/ids";
+import type { CellId, UIElementId } from "../../cells/ids";
 import { store } from "../../state/jotai";
+import {
+  ISLAND_CSS_CLASSES,
+  ISLAND_DATA_ATTRIBUTES,
+  ISLAND_TAG_NAMES,
+} from "../constants";
 import { extractIslandCodeFromEmbed } from "../parse";
 import { MarimoOutputWrapper } from "./output-wrapper";
 
 /**
- * A custom element that renders the output of a marimo cell
+ * Configuration for rendering a marimo island
+ */
+export interface IslandRenderConfig {
+  html: string;
+  codeCallback: () => string;
+  editor: JSX.Element | null;
+  cellId: CellId | undefined;
+}
+
+/**
+ * A custom element that renders the output of a marimo cell.
+ *
+ * This web component wraps marimo cell outputs and provides interactive
+ * functionality like re-running cells and copying code.
  */
 export class MarimoIslandElement extends HTMLElement {
   private root?: Root;
 
-  public static readonly tagName = "marimo-island";
-  public static readonly outputTagName = "marimo-cell-output";
-  public static readonly codeTagName = "marimo-cell-code";
-  public static readonly editorTagName = "marimo-code-editor";
-  public static readonly styleNamespace = "marimo";
+  public static readonly tagName = ISLAND_TAG_NAMES.ISLAND;
+  public static readonly outputTagName = ISLAND_TAG_NAMES.CELL_OUTPUT;
+  public static readonly codeTagName = ISLAND_TAG_NAMES.CELL_CODE;
+  public static readonly editorTagName = ISLAND_TAG_NAMES.CODE_EDITOR;
+  public static readonly styleNamespace = ISLAND_CSS_CLASSES.NAMESPACE;
 
   constructor() {
     super();
     this.classList.add(MarimoIslandElement.styleNamespace);
   }
 
+  /**
+   * Gets the app ID from the element's data attribute
+   */
   get appId(): string {
-    invariant(this.dataset.appId, "Missing data-app-id attribute");
-    return this.dataset.appId;
+    const appId = this.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
+    invariant(appId, "Missing data-app-id attribute");
+    return appId;
+  }
+
+  /**
+   * Whether this island is reactive (has code sent to Python for execution)
+   */
+  get isReactive(): boolean {
+    return this.getAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE) === "true";
+  }
+
+  /**
+   * Gets the cell ID by looking up the cell index in the notebook state.
+   * Returns undefined for non-reactive islands (they have no corresponding cell).
+   */
+  get cellId(): CellId | undefined {
+    const cellId = this.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_ID);
+    if (cellId) {
+      return cellId as CellId;
+    }
+
+    const cellIdx = this.getAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX);
+    if (!cellIdx) {
+      return undefined;
+    }
+    return this.getCellIdFromIndex(Number.parseInt(cellIdx, 10));
   }
 
-  get cellId(): CellId {
-    // Get the cell ID from the code
-    invariant(this.dataset.cellIdx, "Missing data-cell-idx attribute");
+  /**
+   * Gets the code for this island cell
+   */
+  get code(): string {
+    return extractIslandCodeFromEmbed(this);
+  }
+
+  /**
+   * Looks up a cell ID from the notebook state by index
+   */
+  private getCellIdFromIndex(idx: number): CellId {
     const { cellIds } = store.get(notebookAtom);
-    const idx = Number.parseInt(this.dataset.cellIdx, 10);
     const cellId = cellIds.inOrderIds.at(idx);
-    invariant(cellId, "Missing cell ID");
+    invariant(cellId, `Missing cell ID at index ${idx}`);
     return cellId;
   }
 
-  get code(): string {
-    return extractIslandCodeFromEmbed(this);
+  /**
+   * Called when the element is added to the DOM.
+   *
+   * Deferred to a microtask because `defineCustomElement` during
+   * `kernel-ready` upgrades all existing elements synchronously,
+   * which can happen inside a React render cycle. Rendering
+   * synchronously from there causes "unmount during render" warnings.
+   */
+  connectedCallback(): void {
+    // Capture config synchronously (before children get cleared by createRoot)
+    const config = this.extractRenderConfig();
+    queueMicrotask(() => {
+      // Guard against disconnect between connectedCallback and microtask
+      if (!this.isConnected) {
+        return;
+      }
+      this.root = ReactDOM.createRoot(this);
+      this.renderIsland(config);
+    });
   }
 
-  connectedCallback() {
+  /**
+   * Extracts configuration needed for rendering
+   */
+  private extractRenderConfig(): IslandRenderConfig {
     const output = this.querySelectorOrThrow(MarimoIslandElement.outputTagName);
     const initialOutput = output.innerHTML;
-
     const optionalEditor = this.getOptionalEditor();
     const code = this.code;
-    const codeCallback: () => string = optionalEditor
-      ? () =>
-          `${UI_ELEMENT_REGISTRY.lookupValue(
-            optionalEditor.props[OBJECT_ID_ATTR],
-          )}`
-      : () => code;
-
-    this.root = ReactDOM.createRoot(this);
-    this.render(initialOutput, codeCallback, optionalEditor);
+    const cellId = this.cellId;
+
+    // Read objectId directly from the DOM before createRoot clears children.
+    // optionalEditor is a <RenderHTML> wrapper, so its .props don't carry the
+    // underlying element's attributes — we must grab objectId here instead.
+    const editorElement = this.querySelector(MarimoIslandElement.editorTagName);
+    const editorObjectId = (
+      editorElement?.parentElement as Element | null
+    )?.getAttribute(OBJECT_ID_ATTR) as UIElementId | null;
+
+    const codeCallback: () => string =
+      optionalEditor && editorObjectId
+        ? () => {
+            const val = UI_ELEMENT_REGISTRY.lookupValue(editorObjectId);
+            return val !== undefined ? String(val) : code;
+          }
+        : () => code;
+
+    return {
+      html: initialOutput,
+      codeCallback,
+      editor: optionalEditor,
+      cellId,
+    };
   }
 
-  private render(
-    html: string,
-    codeCallback: () => string,
-    editor: JSX.Element | null,
-  ) {
+  /**
+   * Renders the island with React
+   */
+  private renderIsland(config: IslandRenderConfig): void {
+    const { html, codeCallback, editor, cellId } = config;
     const alwaysShowRun = !!editor;
-    html = html.trim();
-    const isEmpty = html === "<span></span>" || html === "";
-    const initialHtml = isEmpty ? null : renderHTML({ html });
+    const trimmedHtml = html.trim();
+    const isEmpty = trimmedHtml === "<span></span>" || trimmedHtml === "";
+    const initialHtml = isEmpty ? null : renderHTML({ html: trimmedHtml });
+
+    // Non-reactive islands have no cell in the kernel — just render static HTML
+    if (!cellId) {
+      this.root?.render(
+        <ErrorBoundary>
+          <Provider store={store}>
+            <LocaleProvider>{initialHtml}</LocaleProvider>
+          </Provider>
+        </ErrorBoundary>,
+      );
+      return;
+    }
 
     this.root?.render(
       <ErrorBoundary>
@@ -85,7 +184,7 @@ export class MarimoIslandElement extends HTMLElement {
           <LocaleProvider>
             <TooltipProvider>
               <MarimoOutputWrapper
-                cellId={this.cellId}
+                cellId={cellId}
                 codeCallback={codeCallback}
                 alwaysShowRun={alwaysShowRun}
               >
@@ -99,16 +198,30 @@ export class MarimoIslandElement extends HTMLElement {
     );
   }
 
+  /**
+   * Attempts to find and render an optional code editor.
+   *
+   * The DOM structure is:
+   *   <marimo-cell-output>
+   *     <div data-marimo-element> ← parent wrapper from Python render
+   *       <marimo-code-editor .../>
+   *     </div>
+   *   </marimo-cell-output>
+   *
+   * We take the parent's outerHTML (the wrapper div) so that the rendered
+   * React element includes the UI element registration attributes.
+   *
+   * @returns A React element for the editor, or null if not found
+   */
   private getOptionalEditor(): JSX.Element | null {
-    // TODO: Maybe add specificity with a [editor=island] selector or something.
     const optionalElement = this.querySelector(
       MarimoIslandElement.editorTagName,
     );
     const html = (optionalElement?.parentNode as Element)?.outerHTML;
     if (html) {
-      // Push back to virtual dom.
+      // Convert HTML to virtual DOM
       const virtualDom = renderHTML({ html });
-      // and prove that it's an element.
+      // Verify it's a valid React element
       if (isValidElement(virtualDom)) {
         return virtualDom;
       }
@@ -116,9 +229,24 @@ export class MarimoIslandElement extends HTMLElement {
     return null;
   }
 
-  private querySelectorOrThrow(selector: string) {
+  /**
+   * Queries for an element and throws if not found
+   */
+  private querySelectorOrThrow(selector: string): Element {
     const element = this.querySelector(selector);
     invariant(element, `Missing ${selector} element`);
     return element;
   }
+
+  /**
+   * Cleanup when element is removed from DOM
+   */
+  disconnectedCallback(): void {
+    const root = this.root;
+    this.root = undefined;
+    // Defer unmount to avoid "unmount during render" race
+    if (root) {
+      queueMicrotask(() => root.unmount());
+    }
+  }
 }

package/src/core/islands/constants.ts

@@ -0,0 +1,28 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+/**
+ * Custom element tag names for islands
+ */
+export const ISLAND_TAG_NAMES = {
+  ISLAND: "marimo-island",
+  CELL_OUTPUT: "marimo-cell-output",
+  CELL_CODE: "marimo-cell-code",
+  CODE_EDITOR: "marimo-code-editor",
+} as const;
+
+/**
+ * Data attributes for islands
+ */
+export const ISLAND_DATA_ATTRIBUTES = {
+  APP_ID: "data-app-id",
+  CELL_IDX: "data-cell-idx",
+  CELL_ID: "data-cell-id",
+  REACTIVE: "data-reactive",
+} as const;
+
+/**
+ * CSS classes for islands
+ */
+export const ISLAND_CSS_CLASSES = {
+  NAMESPACE: "marimo",
+} as const;

package/src/core/islands/main.ts

@@ -11,216 +11,18 @@ import "../../css/table.css";
 
 import "iconify-icon";
 
-import { toast } from "@/components/ui/use-toast";
-import { renderHTML } from "@/plugins/core/RenderHTML";
-import {
-  handleWidgetMessage,
-  MODEL_MANAGER,
-} from "@/plugins/impl/anywidget/model";
-import { initializePlugins } from "@/plugins/plugins";
-import { logNever } from "@/utils/assertNever";
-import { Functions } from "@/utils/functions";
-import { safeExtractSetUIElementMessageBuffers } from "@/utils/json/base64";
-import { jsonParseWithSpecialChar } from "@/utils/json/json-parser";
 import { Logger } from "@/utils/Logger";
-import {
-  createNotebookActions,
-  notebookAtom,
-  notebookReducer,
-} from "../cells/cells";
-import { defineCustomElement } from "../dom/defineCustomElement";
-import { MarimoValueInputEvent } from "../dom/events";
-import { UI_ELEMENT_REGISTRY } from "../dom/uiregistry";
-import { FUNCTIONS_REGISTRY } from "../functions/FunctionRegistry";
-import {
-  handleCellNotificationeration,
-  handleKernelReady,
-  handleRemoveUIElements,
-} from "../kernel/handlers";
-import { queryParamHandlers } from "../kernel/queryParamHandlers";
-import { RuntimeState } from "../kernel/RuntimeState";
-import { initialModeAtom } from "../mode";
-import { requestClientAtom } from "../network/requests";
-import { store } from "../state/jotai";
-import { IslandsPyodideBridge } from "./bridge";
-import { MarimoIslandElement } from "./components/web-components";
-import {
-  shouldShowIslandsWarningIndicatorAtom,
-  userTriedToInteractWithIslandsAtom,
-} from "./state";
-import { dismissIslandsLoadingToast, toastIslandsLoading } from "./toast";
+import { initializeIslands } from "./bootstrap";
+import { getGlobalBridge } from "./bridge";
 
 /**
  * Main entry point for the js bundle for embedded marimo apps.
  */
-
-/**
- * Initialize the Marimo app.
- */
 export async function initialize() {
-  // Setup networking
-  store.set(requestClientAtom, IslandsPyodideBridge.INSTANCE);
-  store.set(initialModeAtom, "read");
-
-  // This will display all the static HTML content.
-  initializePlugins();
-
-  // Find all `marimo-island` elements.
-  const islands = document.querySelectorAll<HTMLElement>(
-    MarimoIslandElement.tagName,
-  );
-
-  // If no islands are found, we can skip the rest of the initialization.
-  if (islands.length === 0) {
-    return;
-  }
-
-  // Add 'marimo' class name to all `marimo-island` elements.
-  // This makes our styles apply to the islands.
-  for (const island of islands) {
-    island.classList.add(MarimoIslandElement.styleNamespace);
-  }
-
-  const actions = createNotebookActions((action) => {
-    store.set(notebookAtom, (state) => notebookReducer(state, action));
-  });
-
-  // If the user has interacted with the islands before they are initialized,
-  // we show the loading toast.
-  store.sub(shouldShowIslandsWarningIndicatorAtom, () => {
-    const showing = store.get(shouldShowIslandsWarningIndicatorAtom);
-    if (showing) {
-      toastIslandsLoading();
-      // For each island, set the opacity to 0.5
-      for (const island of islands) {
-        island.style.setProperty("opacity", "0.5");
-      }
-    } else {
-      dismissIslandsLoadingToast();
-      // For each island, remove the opacity
-      for (const island of islands) {
-        island.style.removeProperty("opacity");
-      }
-    }
-  });
-
-  // Consume messages from the kernel
-  IslandsPyodideBridge.INSTANCE.consumeMessages((message) => {
-    const msg = jsonParseWithSpecialChar(message);
-    switch (msg.data.op) {
-      case "banner":
-      case "missing-package-alert":
-      case "installing-package-alert":
-      case "completion-result":
-      case "reload":
-      case "focus-cell":
-      case "variables":
-      case "variable-values":
-      case "data-column-preview":
-      case "sql-table-preview":
-      case "sql-table-list-preview":
-      case "sql-schema-list-preview":
-      case "datasets":
-      case "data-source-connections":
-      case "validate-sql-result":
-      case "storage-namespaces":
-      case "storage-entries":
-      case "storage-download-ready":
-      case "secret-keys-result":
-      case "startup-logs":
-        // Unsupported
-        return;
-      case "kernel-ready":
-        handleKernelReady(msg.data, {
-          autoInstantiate: true,
-          setCells: actions.setCells,
-          setLayoutData: Functions.NOOP,
-          setAppConfig: Functions.NOOP,
-          setCapabilities: Functions.NOOP,
-          setKernelState: Functions.NOOP,
-          onError: Logger.error,
-        });
-        // Define the custom element for the marimo-island tag.
-        // This comes after initializing since this reads from the store.
-        defineCustomElement(MarimoIslandElement.tagName, MarimoIslandElement);
-        return;
-      case "completed-run":
-        return;
-      case "interrupted":
-        return;
-      case "send-ui-element-message":
-        UI_ELEMENT_REGISTRY.broadcastMessage(
-          msg.data.ui_element,
-          msg.data.message,
-          safeExtractSetUIElementMessageBuffers(msg.data),
-        );
-        return;
-
-      case "remove-ui-elements":
-        handleRemoveUIElements(msg.data);
-        return;
-      case "function-call-result":
-        FUNCTIONS_REGISTRY.resolve(msg.data.function_call_id, msg.data);
-        return;
-      case "cell-op":
-        handleCellNotificationeration(msg.data, actions.handleCellMessage);
-        return;
-      case "alert":
-        // TODO: support toast with islands
-        toast({
-          title: msg.data.title,
-          description: renderHTML({
-            html: msg.data.description,
-          }),
-          variant: msg.data.variant,
-        });
-        return;
-      case "query-params-append":
-        queryParamHandlers.append(msg.data);
-        return;
-      case "query-params-set":
-        queryParamHandlers.set(msg.data);
-        return;
-      case "query-params-delete":
-        queryParamHandlers.delete(msg.data);
-        return;
-      case "query-params-clear":
-        queryParamHandlers.clear();
-        return;
-      case "reconnected":
-        return;
-      case "cache-cleared":
-        return;
-      case "cache-info":
-        return;
-      case "kernel-startup-error":
-        return;
-      case "notebook-document-transaction":
-        return;
-      case "model-lifecycle":
-        handleWidgetMessage(MODEL_MANAGER, msg.data);
-        return;
-      default:
-        logNever(msg.data);
-    }
-  });
-
-  // Set the user tried to interact with islands
-  // before they are initialized.
-  document.addEventListener(
-    MarimoValueInputEvent.TYPE,
-    () => {
-      store.set(userTriedToInteractWithIslandsAtom, true);
-    },
-    {
-      once: true,
-    },
-  );
-
-  // Start the runtime
-  RuntimeState.INSTANCE.start(
-    IslandsPyodideBridge.INSTANCE.sendComponentValues,
-  );
+  await initializeIslands({ bridge: getGlobalBridge() });
 }
 
-initialize();
+// Auto-initialize on module load
+void initialize().catch((error) => {
+  Logger.error("Failed to initialize islands:", error);
+});

package/src/core/islands/parse.ts

@@ -1,6 +1,9 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
-import { MarimoIslandElement } from "@/core/islands/components/web-components";
+import {
+  ISLAND_DATA_ATTRIBUTES,
+  ISLAND_TAG_NAMES,
+} from "@/core/islands/constants";
 import { Logger } from "@/utils/Logger";
 
 /**
@@ -41,53 +44,94 @@ interface MarimoIslandCell {
   idx: number;
 }
 
-export function parseMarimoIslandApps(): MarimoIslandApp[] {
-  const apps = new Map<string, MarimoIslandApp>();
-
-  const embeds = document.querySelectorAll<HTMLElement>(
-    MarimoIslandElement.tagName,
-  );
+/**
+ * Parses marimo island apps from the DOM
+ * @param root - Root element to search within (defaults to document)
+ */
+export function parseMarimoIslandApps(
+  root: Document | Element = document,
+): MarimoIslandApp[] {
+  const embeds = root.querySelectorAll<HTMLElement>(ISLAND_TAG_NAMES.ISLAND);
   if (embeds.length === 0) {
     Logger.warn("No embedded marimo apps found.");
     return [];
   }
 
+  // eslint-disable-next-line prefer-spread
+  return parseIslandElementsIntoApps(Array.from(embeds));
+}
+
+/**
+ * Pure function to parse island elements into app structures
+ * @param embeds - Array of island HTML elements
+ */
+export function parseIslandElementsIntoApps(
+  embeds: HTMLElement[],
+): MarimoIslandApp[] {
+  const apps = new Map<string, MarimoIslandApp>();
+
   for (const embed of embeds) {
-    const id = embed.dataset.appId;
-    if (!id) {
+    const appId = embed.getAttribute(ISLAND_DATA_ATTRIBUTES.APP_ID);
+    if (!appId) {
       Logger.warn("Embedded marimo cell missing data-app-id attribute.");
       continue;
     }
 
-    const cellOutput = embed.querySelector<HTMLElement>(
-      MarimoIslandElement.outputTagName,
-    );
-    const code = extractIslandCodeFromEmbed(embed);
+    // Non-reactive islands are static — they don't participate in the kernel
+    const reactive =
+      embed.getAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE) === "true";
+    if (!reactive) {
+      continue;
+    }
 
-    if (!cellOutput || !code) {
-      Logger.warn(`Embedded marimo app ${id} missing cell output or code.`);
+    const cellData = parseIslandElement(embed);
+    if (!cellData) {
+      Logger.warn(`Embedded marimo app ${appId} missing cell output or code.`);
       continue;
     }
 
-    if (!apps.has(id)) {
-      apps.set(id, { id, cells: [] });
+    if (!apps.has(appId)) {
+      apps.set(appId, { id: appId, cells: [] });
     }
-    // oxlint-disable-next-line typescript/no-non-null-assertion
-    const app = apps.get(id)!;
+
+    const app = apps.get(appId)!;
     const idx = app.cells.length;
     app.cells.push({
-      output: cellOutput.innerHTML,
-      code: code,
+      output: cellData.output,
+      code: cellData.code,
       idx: idx,
     });
 
     // Add data-cell-idx attribute to the island element
-    embed.dataset.cellIdx = idx.toString();
+    embed.setAttribute(ISLAND_DATA_ATTRIBUTES.CELL_IDX, idx.toString());
   }
 
   return [...apps.values()];
 }
 
+/**
+ * Parses a single island element into cell data
+ * @param embed - The island HTML element
+ * @returns Cell data or null if invalid
+ */
+export function parseIslandElement(
+  embed: HTMLElement,
+): { output: string; code: string } | null {
+  const cellOutput = embed.querySelector<HTMLElement>(
+    ISLAND_TAG_NAMES.CELL_OUTPUT,
+  );
+  const code = extractIslandCodeFromEmbed(embed);
+
+  if (!cellOutput || !code) {
+    return null;
+  }
+
+  return {
+    output: cellOutput.innerHTML,
+    code: code,
+  };
+}
+
 export function createMarimoFile(app: { cells: { code: string }[] }): string {
   const lines = [
     "import marimo",
@@ -134,7 +178,8 @@ export function parseIslandCode(code: string | undefined | null): string {
 }
 
 export function extractIslandCodeFromEmbed(embed: HTMLElement): string {
-  const reactive = embed.dataset.reactive === "true";
+  const reactive =
+    embed.getAttribute(ISLAND_DATA_ATTRIBUTES.REACTIVE) === "true";
   // Non-reactive cells are not guaranteed to have code, and should be treated as
   // such.
   if (!reactive) {
@@ -142,17 +187,19 @@ export function extractIslandCodeFromEmbed(embed: HTMLElement): string {
   }
 
   const cellCodeElement = embed.querySelector<HTMLElement>(
-    MarimoIslandElement.codeTagName,
+    ISLAND_TAG_NAMES.CELL_CODE,
   );
   if (cellCodeElement) {
     return parseIslandCode(cellCodeElement.textContent);
   }
 
   const editorCodeElement = embed.querySelector<HTMLElement>(
-    MarimoIslandElement.editorTagName,
+    ISLAND_TAG_NAMES.CODE_EDITOR,
   );
   if (editorCodeElement) {
-    return parseIslandEditor(editorCodeElement.dataset.initialValue);
+    return parseIslandEditor(
+      editorCodeElement.getAttribute("data-initial-value"),
+    );
   }
 
   return "";