@marimo-team/islands 0.24.3-dev9 → 0.25.0

package/src/core/websocket/transports/transport.ts

@@ -15,7 +15,7 @@ export type ConnectionTransportCallback<T extends ConnectionEvent> = (
 export interface IConnectionTransport {
   reconnect(code?: number | undefined, reason?: string | undefined): void;
   close(): void;
-  send(data: string | ArrayBuffer | Blob | ArrayBufferView): void;
+  send(data: string | ArrayBuffer | Blob | ArrayBufferView<ArrayBuffer>): void;
   addEventListener<T extends ConnectionEvent>(
     event: T,
     callback: ConnectionTransportCallback<T>,

package/src/core/websocket/transports/ws.ts

@@ -42,7 +42,7 @@ export class WsTransport implements IConnectionTransport {
     this.inner.close();
   }
 
-  send(data: string | ArrayBuffer | Blob | ArrayBufferView): void {
+  send(data: string | ArrayBuffer | Blob | ArrayBufferView<ArrayBuffer>): void {
     this.inner.send(data);
   }
 

package/src/core/websocket/types.ts

@@ -1,5 +1,11 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import type { NotificationMessageData } from "../kernel/messages";
+
+export type ConnectionPhase =
+  | NotificationMessageData<"startup-progress">["phase"]
+  | "reconnecting";
+
 // TODO: rename to ConnectionState
 export const WebSocketState = {
   NOT_STARTED: "NOT_STARTED",
@@ -28,10 +34,14 @@ export type ConnectionStatus =
        * Human-readable reason for closing the connection.
        */
       reason: string;
+      phase?: ConnectionPhase;
+    }
+  | {
+      state: typeof WebSocketState.CONNECTING;
+      phase?: ConnectionPhase;
     }
   | {
       state:
-        | typeof WebSocketState.CONNECTING
         | typeof WebSocketState.OPEN
         | typeof WebSocketState.CLOSING
         | typeof WebSocketState.NOT_STARTED;

package/src/core/websocket/useMarimoKernelConnection.tsx

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 
+import { invalidatePackageData } from "@/core/packages/package-data";
 import { useAtom, useAtomValue, useSetAtom } from "jotai";
 import { useRef } from "react";
 import { useErrorBoundary } from "react-error-boundary";
@@ -63,7 +64,7 @@ import type { SessionId } from "../kernel/session";
 import { initialRunCompletedAtom, kernelStateAtom } from "../kernel/state";
 import { type LayoutState, useLayoutActions } from "../layout/state";
 import { kioskModeAtom } from "../mode";
-import { connectionAtom } from "../network/connection";
+import { connectionAtom, startupProgressAtom } from "../network/connection";
 import type { RequestId } from "../network/DeferredRequestRegistry";
 import { useRuntimeManager } from "../runtime/config";
 import { SECRETS_REGISTRY } from "../secrets/request-registry";
@@ -221,8 +222,14 @@ export function useMarimoKernelConnection(opts: {
     useDataSourceActions();
   const { setLayoutData } = useLayoutActions();
   const [connection, setConnection] = useAtom(connectionAtom);
+  const updateStartupProgress = useSetAtom(startupProgressAtom);
   const { addBanner } = useBannersActions();
-  const { addPackageAlert, addStartupLog } = useAlertActions();
+  const {
+    addMissingPackageAlert,
+    updateEnvironment,
+    setEnvironment,
+    addStartupLog,
+  } = useAlertActions();
   const setKioskMode = useSetAtom(kioskModeAtom);
   const setCapabilities = useSetAtom(capabilitiesAtom);
   const runtimeManager = useRuntimeManager();
@@ -240,7 +247,21 @@ export function useMarimoKernelConnection(opts: {
       case "reload":
         reloadSafe();
         return;
+      case "startup-progress": {
+        const { phase } = msg.data;
+        updateStartupProgress(msg.data);
+        setConnection((previous) =>
+          previous.state === WebSocketState.OPEN ||
+          (previous.state === WebSocketState.CONNECTING &&
+            previous.phase === phase)
+            ? previous
+            : { state: WebSocketState.CONNECTING, phase },
+        );
+        return;
+      }
       case "kernel-ready": {
+        setKernelStartupError(null);
+        setConnection({ state: WebSocketState.OPEN });
         setInitialRunCompleted(
           Boolean(msg.data.resumed || msg.data.auto_instantiated),
         );
@@ -357,16 +378,25 @@ export function useMarimoKernelConnection(opts: {
         addBanner(msg.data);
         return;
       case "missing-package-alert":
-        addPackageAlert({
+        addMissingPackageAlert({
           ...msg.data,
           kind: "missing",
         });
         return;
-      case "installing-package-alert":
-        addPackageAlert({
-          ...msg.data,
-          kind: "installing",
-        });
+      case "environment-operation":
+        if (
+          msg.data.source === "kernel" &&
+          msg.data.status.kind !== "running"
+        ) {
+          invalidatePackageData();
+        }
+        updateEnvironment(msg.data);
+        return;
+      case "environment-state":
+        setEnvironment(msg.data);
+        if (msg.data.source === "kernel") {
+          invalidatePackageData();
+        }
         return;
       case "startup-logs":
         addStartupLog({
@@ -439,6 +469,8 @@ export function useMarimoKernelConnection(opts: {
         return;
 
       case "reconnected":
+        setKernelStartupError(null);
+        setConnection({ state: WebSocketState.OPEN });
         return;
 
       case "focus-cell":
@@ -482,6 +514,7 @@ export function useMarimoKernelConnection(opts: {
       return;
     }
     shouldTryReconnecting.current = true;
+    setKernelStartupError(null);
     setConnection({ state: WebSocketState.CONNECTING });
     const healthy = await runtimeManager.reconcileFromHealth();
     if (!healthy) {
@@ -513,17 +546,12 @@ export function useMarimoKernelConnection(opts: {
     headers: () => runtimeManager.headers(),
 
     /**
-     * Open callback. Set the connection status to open.
+     * The transport is open; kernel-ready establishes session readiness.
      */
     onOpen: async () => {
+      updateStartupProgress(null);
       // If we are open, we can reset our reconnecting flag.
       shouldTryReconnecting.current = true;
-
-      // DO NOT COMMIT THIS UNCOMMENTED
-      // Uncomment to emulate a slow connection
-      // await new Promise((resolve) => setTimeout(resolve, 10_000));
-
-      setConnection({ state: WebSocketState.OPEN });
     },
 
     /**
@@ -565,7 +593,26 @@ export function useMarimoKernelConnection(opts: {
     onClose: (e) => {
       Logger.warn("WebSocket closed", e.code, e.reason);
       const decision = classifyCloseEvent(e);
-      setConnection(decision.status);
+      setConnection((previous) => {
+        const status = decision.status;
+        if (
+          status.state === WebSocketState.CLOSED &&
+          status.code === WebSocketClosedReason.KERNEL_STARTUP_ERROR &&
+          (previous.state === WebSocketState.CONNECTING ||
+            previous.state === WebSocketState.CLOSED)
+        ) {
+          return { ...status, phase: previous.phase };
+        }
+        if (
+          status.state === WebSocketState.CONNECTING &&
+          (previous.state === WebSocketState.OPEN ||
+            (previous.state === WebSocketState.CONNECTING &&
+              previous.phase === "reconnecting"))
+        ) {
+          return { ...status, phase: "reconnecting" };
+        }
+        return status;
+      });
       if (decision.kind === "terminal" && decision.closeTransport) {
         ws.close(); // close to prevent reconnecting
         return;

package/src/hooks/useDebounce.ts

@@ -48,6 +48,8 @@ export function useDebounceControlledState<T>(opts: {
 
   // Handle external changes:
   useEffect(() => {
+    // TODO: Replace this synchronization with a controlled-state primitive.
+    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the debounced draft when the controlled value changes.
     setInternalValue(initialValue);
   }, [initialValue]);
 

package/src/mount.tsx

@@ -10,6 +10,7 @@ import {
   userConfigAtom,
 } from "@/core/config/config";
 import { KnownQueryParams } from "@/core/constants";
+import { pairPreviewAtom, pairPreviewSchema } from "@/core/config/pair";
 import { getFilenameFromDOM } from "@/core/dom/htmlUtils";
 import { getMarimoCode } from "@/core/meta/globals";
 import {
@@ -208,6 +209,7 @@ const mountOptionsSchema = z.object({
    * marimo config overrides
    */
   configOverrides: passthroughObject,
+  pairPreview: pairPreviewSchema.optional(),
   /**
    * marimo app config
    */
@@ -345,6 +347,7 @@ function initStore(options: unknown) {
   );
   store.set(userConfigAtom, parseUserConfig(parsedOptions.data.config));
   store.set(appConfigAtom, parseAppConfig(parsedOptions.data.appConfig));
+  store.set(pairPreviewAtom, parsedOptions.data.pairPreview);
 
   // Runtime config
   if (parsedOptions.data.runtimeConfig.length > 0) {

package/src/plugins/core/BadPlugin.tsx

@@ -9,21 +9,15 @@ const AccordionTrigger = AccordionPrimitive.Trigger;
 
 import type { JSX } from "react";
 import { ZodError } from "zod";
-import { EmotionCacheProvider } from "@/components/editor/output/EmotionCacheProvider";
 import { JsonOutput } from "@/components/editor/output/JsonOutput";
 import { Alert, AlertTitle } from "../../components/ui/alert";
 
 interface Props {
   error: ZodError | Error;
-  shadowRoot: ShadowRoot | null;
   badData: Record<string, unknown>;
 }
 
-export const BadPluginData: React.FC<Props> = ({
-  error,
-  badData,
-  shadowRoot,
-}) => {
+export const BadPluginData: React.FC<Props> = ({ error, badData }) => {
   if (error instanceof ZodError) {
     return (
       <Alert variant="destructive">
@@ -49,9 +43,7 @@ export const BadPluginData: React.FC<Props> = ({
               View Data:
             </AccordionTrigger>
             <AccordionContent className="text-[0.84375rem]">
-              <EmotionCacheProvider container={shadowRoot}>
-                <JsonOutput data={badData} />
-              </EmotionCacheProvider>
+              <JsonOutput data={badData} />
             </AccordionContent>
           </AccordionItem>
         </Accordion>
@@ -65,9 +57,6 @@ export const BadPluginData: React.FC<Props> = ({
 export function renderError(
   error: ZodError | Error,
   badData: Record<string, unknown>,
-  shadowRoot: ShadowRoot | null,
 ): JSX.Element {
-  return (
-    <BadPluginData error={error} badData={badData} shadowRoot={shadowRoot} />
-  );
+  return <BadPluginData error={error} badData={badData} />;
 }

package/src/plugins/core/RenderHTML.tsx

@@ -262,9 +262,29 @@ const wrapTooltipTargets: TransformFn = (
     if (tagName.startsWith("marimo-")) {
       return undefined;
     }
-    const tooltipContent = domNode.attribs["data-tooltip"];
+    const tooltipContent = domNode.attribs["data-tooltip"].replace(
+      /^[\r\n]+|[\r\n]+$/g,
+      "",
+    );
     return (
-      <Tooltip content={tooltipContent}>{reactNode as JSX.Element}</Tooltip>
+      <Tooltip
+        content={
+          tooltipContent.includes("\n") ? (
+            <span className="whitespace-pre-wrap">
+              {tooltipContent.split(/\r?\n/).map((line, i) => (
+                <React.Fragment key={i}>
+                  {i > 0 && <br />}
+                  {line}
+                </React.Fragment>
+              ))}
+            </span>
+          ) : (
+            tooltipContent
+          )
+        }
+      >
+        {reactNode as JSX.Element}
+      </Tooltip>
     );
   }
 };

package/src/plugins/core/__test__/RenderHTML.test.ts

@@ -1,5 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import type { ExtractAtomValue } from "jotai";
+import { isValidElement, type ReactNode } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
 import { afterEach, beforeEach, describe, expect, test } from "vitest";
 import { hasRunAnyCellAtom } from "@/components/editor/cell/useRunCells";
 import { userConfigAtom } from "@/core/config/config";
@@ -450,6 +452,191 @@ describe("wrapTooltipTargets", () => {
       </Tooltip>
     `);
   });
+
+  test("data-tooltip multiline via &#10; entity renders <br/>", () => {
+    const html =
+      '<span data-tooltip="Line A&#10;Line B&#10;Line C">hover</span>';
+    const result = parseHtml({ html });
+    expect(result).toMatchInlineSnapshot(`
+      <Tooltip
+        content={
+          <span
+            className="whitespace-pre-wrap"
+          >
+            <React.Fragment>
+              Line A
+            </React.Fragment>
+            <React.Fragment>
+              <br />
+              Line B
+            </React.Fragment>
+            <React.Fragment>
+              <br />
+              Line C
+            </React.Fragment>
+          </span>
+        }
+      >
+        <span
+          data-tooltip="Line A
+      Line B
+      Line C"
+        >
+          hover
+        </span>
+      </Tooltip>
+    `);
+  });
+
+  test("data-tooltip multiline via literal \\n renders <br/>", () => {
+    const html = '<span data-tooltip="Line A\nLine B">hover</span>';
+    expect(parseHtml({ html })).toMatchInlineSnapshot(`
+      <Tooltip
+        content={
+          <span
+            className="whitespace-pre-wrap"
+          >
+            <React.Fragment>
+              Line A
+            </React.Fragment>
+            <React.Fragment>
+              <br />
+              Line B
+            </React.Fragment>
+          </span>
+        }
+      >
+        <span
+          data-tooltip="Line A
+      Line B"
+        >
+          hover
+        </span>
+      </Tooltip>
+    `);
+  });
+
+  test("data-tooltip single line still works as before", () => {
+    const html = '<span data-tooltip="Single line">hover</span>';
+    expect(parseHtml({ html })).toMatchInlineSnapshot(`
+      <Tooltip
+        content="Single line"
+      >
+        <span
+          data-tooltip="Single line"
+        >
+          hover
+        </span>
+      </Tooltip>
+    `);
+  });
+
+  test.each([
+    ["CRLF", "A\r\nB", '<span class="whitespace-pre-wrap">A<br/>B</span>'],
+    [
+      "encoded CRLF",
+      "A&#13;&#10;B",
+      '<span class="whitespace-pre-wrap">A<br/>B</span>',
+    ],
+    ["leading newline", "\nA", "A"],
+    ["trailing newline", "A\n", "A"],
+    [
+      "boundary newlines",
+      "\n\nA\nB\n\n",
+      '<span class="whitespace-pre-wrap">A<br/>B</span>',
+    ],
+    [
+      "boundary CRLF",
+      "&#13;&#10;A&#13;&#10;B&#13;&#10;",
+      '<span class="whitespace-pre-wrap">A<br/>B</span>',
+    ],
+    ["only newlines", "\n\n", ""],
+    ["only CRLF", "&#13;&#10;&#13;&#10;", ""],
+    [
+      "internal blank line",
+      "A\n\nB",
+      '<span class="whitespace-pre-wrap">A<br/><br/>B</span>',
+    ],
+    [
+      "spaces and tabs",
+      "\n A\t\n\tB \n",
+      '<span class="whitespace-pre-wrap"> A\t<br/>\tB </span>',
+    ],
+    [
+      "HTML text",
+      "&lt;b&gt;A&lt;/b&gt;\nB",
+      '<span class="whitespace-pre-wrap">&lt;b&gt;A&lt;/b&gt;<br/>B</span>',
+    ],
+  ])("data-tooltip handles %s", (_, content, expected) => {
+    const result = parseHtml({
+      html: `<span data-tooltip="${content}">Hover me</span>`,
+    });
+    if (!isValidElement<{ content: ReactNode }>(result)) {
+      throw new Error("Expected a Tooltip element");
+    }
+    expect(renderToStaticMarkup(result.props.content)).toBe(expected);
+  });
+
+  test("data-tooltip with newline renders as line breaks", () => {
+    const html = '<span data-tooltip="Line one\nLine two">Hover me</span>';
+    expect(parseHtml({ html })).toMatchInlineSnapshot(`
+      <Tooltip
+        content={
+          <span
+            className="whitespace-pre-wrap"
+          >
+            <React.Fragment>
+              Line one
+            </React.Fragment>
+            <React.Fragment>
+              <br />
+              Line two
+            </React.Fragment>
+          </span>
+        }
+      >
+        <span
+          data-tooltip="Line one
+      Line two"
+        >
+          Hover me
+        </span>
+      </Tooltip>
+    `);
+  });
+
+  test("data-tooltip with multiple newlines renders all as line breaks", () => {
+    const html = '<span data-tooltip="A\nB\nC">Hover me</span>';
+    expect(parseHtml({ html })).toMatchInlineSnapshot(`
+      <Tooltip
+        content={
+          <span
+            className="whitespace-pre-wrap"
+          >
+            <React.Fragment>
+              A
+            </React.Fragment>
+            <React.Fragment>
+              <br />
+              B
+            </React.Fragment>
+            <React.Fragment>
+              <br />
+              C
+            </React.Fragment>
+          </span>
+        }
+      >
+        <span
+          data-tooltip="A
+      B
+      C"
+        >
+          Hover me
+        </span>
+      </Tooltip>
+    `);
+  });
 });
 
 describe("parseHtml with < nad >", () => {

package/src/plugins/core/registerReactComponent.tsx

@@ -274,7 +274,6 @@ function PluginSlotInternal<T>(
       Objects.mapValues(hostElement.dataset, (value) =>
         typeof value === "string" ? parseAttrValue(value) : value,
       ),
-      hostElement.shadowRoot,
     );
   }
 

package/src/plugins/impl/FileBrowserPlugin.tsx

@@ -218,7 +218,7 @@ export const FileBrowser = ({
 
   const { data, error, isPending } = useAsyncData(() => {
     return list_directory({ path: path });
-  }, [path, randomId]);
+  }, [path, randomId, list_directory]);
 
   useEffect(() => {
     if (!isPending) {
@@ -238,9 +238,15 @@ export const FileBrowser = ({
   // Reset the roving tabindex whenever the listing reloads (a new path or a
   // same-path refresh) so activeIndex never points past the current rows.
   const listingKey = `${path}::${randomId}`;
-  const [prevListingKey, setPrevListingKey] = useState(listingKey);
-  if (prevListingKey !== listingKey) {
-    setPrevListingKey(listingKey);
+  const [prevListing, setPrevListing] = useState({
+    listingKey,
+    list_directory,
+  });
+  if (
+    prevListing.listingKey !== listingKey ||
+    prevListing.list_directory !== list_directory
+  ) {
+    setPrevListing({ listingKey, list_directory });
     setActiveIndex(0);
   }
 

package/src/plugins/impl/FormPlugin.tsx

@@ -219,6 +219,8 @@ const Form = ({
   // The Form may be rendered before the child plugin is, so after mount
   // we lookup the plugin once again.
   useEffect(() => {
+    // TODO: Replace the post-mount registry lookup with reactive initialization.
+    // oxlint-disable-next-line react/no-deriving-state-in-effects -- The child registry entry may not exist until after the parent mounts.
     setInternalValue(UI_ELEMENT_REGISTRY.lookupValue(elementId));
   }, [elementId]);
 

package/src/plugins/impl/MatrixPlugin.tsx

@@ -126,6 +126,8 @@ const MatrixComponent = ({
   // which avoids stale-state bugs when the matrix shape changes.
   const [draft, setDraft] = useState(value);
   useEffect(() => {
+    // TODO: Model the active draft without synchronizing state in an effect.
+    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the editable draft when the controlled value changes.
     setDraft(value);
   }, [value]);
   const displayValue = activeCell == null ? value : draft;

package/src/plugins/impl/RangeSliderPlugin.tsx

@@ -90,6 +90,8 @@ const RangeSliderComponent = ({
 
   // Update internal value on prop change
   useEffect(() => {
+    // TODO: Replace this synchronization with a controlled-state primitive.
+    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the editable buffer when the controlled value changes.
     setInternalValue(value);
   }, [value]);
 

package/src/plugins/impl/SliderPlugin.tsx

@@ -158,6 +158,8 @@ const SliderComponent = ({
   const [internalValue, setInternalValue] = useState(value);
   // Update internal value on prop change
   useEffect(() => {
+    // TODO: Replace this synchronization with a controlled-state primitive.
+    // oxlint-disable-next-line react/no-deriving-state-in-effects -- Synchronize the editable buffer when the controlled value changes.
     setInternalValue(value);
   }, [value]);
 

package/src/plugins/impl/__tests__/FileBrowserPlugin.test.tsx

@@ -5,8 +5,9 @@ import { beforeAll, describe, expect, it, vi } from "vitest";
 import { SetupMocks } from "@/__mocks__/common";
 import { initialModeAtom } from "@/core/mode";
 import { store } from "@/core/state/jotai";
+import { CellNotInitializedError } from "@/utils/errors";
 import type { IPluginProps } from "../../types";
-import { FileBrowserPlugin } from "../FileBrowserPlugin";
+import { FileBrowser, FileBrowserPlugin } from "../FileBrowserPlugin";
 
 interface MockFile {
   id: string;
@@ -80,6 +81,54 @@ beforeAll(() => {
   store.set(initialModeAtom, "edit");
 });
 
+describe("FileBrowserPlugin session cache recovery", () => {
+  it("retries a failed cached listing when the plugin resets", async () => {
+    const host = document.createElement("marimo-file-browser");
+    const wrapper = document.createElement("marimo-ui-element");
+    wrapper.setAttribute("random-id", "cached-id");
+    wrapper.append(host);
+
+    const props = {
+      initialPath: "/home/user",
+      filetypes: [],
+      selectionMode: "directory",
+      multiple: false,
+      label: "Pick folder",
+      restrictNavigation: false,
+      value: [],
+      setValue: vi.fn(),
+      host,
+    };
+    const error = new CellNotInitializedError();
+    const cachedListDirectory = vi.fn().mockRejectedValue(error);
+    const { rerender } = render(
+      <FileBrowser {...props} list_directory={cachedListDirectory} />,
+    );
+    expect(await screen.findByText(error.message)).toBeInTheDocument();
+
+    // PluginSlot recreates the RPC functions on reset, even when the path
+    // and the host's attributes are unchanged.
+    const liveListDirectory = mockListDirectory(FILES);
+    rerender(<FileBrowser {...props} list_directory={liveListDirectory} />);
+
+    expect(await screen.findByText("docs")).toBeInTheDocument();
+    expect(screen.queryByText(error.message)).not.toBeInTheDocument();
+    expect(liveListDirectory.mock.calls).toEqual([[{ path: "/home/user" }]]);
+
+    fireEvent.click(screen.getByRole("checkbox", { name: "Select docs" }));
+    expect(props.setValue).toHaveBeenCalledWith([
+      { ...FILES[0], id: FILES[0].path },
+    ]);
+
+    fireEvent.keyDown(screen.getAllByRole("row")[0], { key: "End" });
+    rerender(
+      <FileBrowser {...props} list_directory={mockListDirectory([FILES[0]])} />,
+    );
+    await waitFor(() => expect(screen.getAllByRole("row")).toHaveLength(2));
+    expect(screen.getAllByRole("row")[0]).toHaveAttribute("tabindex", "0");
+  });
+});
+
 describe("FileBrowserPlugin keyboard accessibility", () => {
   it("renders a row per file plus the parent row", async () => {
     renderBrowser();