@marimo-team/islands 0.25.3-dev3 → 0.25.3-dev301

package/src/plugins/impl/panel/PanelPlugin.tsx

@@ -1,7 +1,8 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 /* oxlint-disable typescript/no-explicit-any */
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import useEvent from "react-use-event-hook";
 import { z } from "zod";
 import { MarimoIncomingMessageEvent } from "@/core/dom/events";
 import {
@@ -77,7 +78,7 @@ type T = Record<string, unknown>;
 
 // oxlint-disable-next-line typescript/consistent-type-definitions
 type PluginFunctions = {
-  send_to_widget: <T>(req: {
+  send_to_widget: (req: {
     message?: unknown;
     buffers?: unknown;
   }) => Promise<null | undefined>;
@@ -146,17 +147,10 @@ const PanelSlot = (props: Props) => {
   > | null>(null);
   const [loaded, setLoaded] = useState<boolean>(false);
   const [rendered, setRendered] = useState<string | null>(null);
+  const eventBufferRef = useRef<EventBuffer<unknown> | null>(null);
 
-  // Store functions in a ref so the callback captured by EventBuffer stays current
-  const functionsRef = useRef(functions);
-  functionsRef.current = functions;
-
-  const processEvents = useCallback(() => {
-    if (!eventBufferRef.current) {
-      return;
-    }
-
-    const events = eventBufferRef.current.getAndClear();
+  const processEvents = useEvent(() => {
+    const events = eventBufferRef.current?.getAndClear() ?? [];
     if (events.length === 0) {
       return;
     }
@@ -182,14 +176,19 @@ const PanelSlot = (props: Props) => {
     );
     const buffers: ArrayBuffer[] = [];
     message.content = extractBuffers(message.content, buffers);
-    functionsRef.current.send_to_widget({ message, buffers }).catch((error) => {
+    functions.send_to_widget({ message, buffers }).catch((error) => {
       Logger.warn("Failed to send Panel event to backend", error);
     });
-  }, []);
+  });
 
-  const eventBufferRef = useRef<EventBuffer<unknown> | null>(
-    new EventBuffer(processEvents),
-  );
+  useEffect(() => {
+    const buffer = new EventBuffer(processEvents);
+    eventBufferRef.current = buffer;
+    return () => {
+      buffer.dispose();
+      eventBufferRef.current = null;
+    };
+  }, [processEvents]);
 
   // Load the bokeh extension
   useEffect(() => {

package/src/plugins/impl/panel/__tests__/utils.test.ts

@@ -1,5 +1,5 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-import { beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { EventBuffer, extractBuffers, MessageSchema } from "../utils";
 
 describe("MessageSchema", () => {
@@ -73,6 +73,44 @@ describe("EventBuffer", () => {
     eventBuffer = new EventBuffer(processEvents, 50);
   });
 
+  afterEach(() => {
+    eventBuffer.dispose();
+    vi.useRealTimers();
+  });
+
+  it("flushes queued events and cancels the pending timer on dispose", () => {
+    eventBuffer.add("event1");
+    eventBuffer.add("event2");
+    expect(vi.getTimerCount()).toBe(1);
+    expect(processEvents).toHaveBeenCalledOnce();
+
+    eventBuffer.dispose();
+    expect(processEvents).toHaveBeenCalledTimes(2);
+    eventBuffer.dispose();
+
+    expect(eventBuffer.size()).toBe(0);
+    expect(vi.getTimerCount()).toBe(0);
+    vi.advanceTimersByTime(100);
+    expect(processEvents).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not process an empty buffer on dispose", () => {
+    eventBuffer.dispose();
+    expect(processEvents).not.toHaveBeenCalled();
+  });
+
+  it("resets the blocked state when disposed", () => {
+    eventBuffer.add("event1");
+    // Emulate a real processEvents, which drains the buffer
+    eventBuffer.getAndClear();
+    eventBuffer.dispose();
+    eventBuffer.add("event2");
+
+    expect(processEvents).toHaveBeenCalledTimes(2);
+    expect(eventBuffer.getAndClear()).toEqual(["event2"]);
+    expect(vi.getTimerCount()).toBe(1);
+  });
+
   it("should add events to buffer", () => {
     eventBuffer.add("event1");
     eventBuffer.add("event2");

package/src/plugins/impl/panel/utils.ts

@@ -83,6 +83,7 @@ export class EventBuffer<T> {
       clearTimeout(this.timeout);
     }
     this.timeout = window.setTimeout(() => {
+      this.timeout = null;
       this.isBlocked = false;
       if (this.buffer.length > 0) {
         this.flush();
@@ -98,6 +99,22 @@ export class EventBuffer<T> {
     this.buffer = [];
   }
 
+  /**
+   * Cancel the pending timer, flushing any events still held by the block
+   * window so the last user interaction is not lost.
+   */
+  public dispose() {
+    if (this.timeout !== null) {
+      clearTimeout(this.timeout);
+      this.timeout = null;
+    }
+    this.isBlocked = false;
+    if (this.buffer.length > 0) {
+      this.processEvents();
+    }
+    this.clear();
+  }
+
   public getAndClear() {
     const events = this.buffer;
     this.buffer = [];

package/src/plugins/impl/plotly/PlotlyPlugin.tsx

@@ -58,11 +58,8 @@ export class PlotlyPlugin implements IPlugin<T, Data> {
   public tagName = "marimo-plotly";
 
   public validator = z.object({
-    figure: z
-      .object({})
-      .passthrough()
-      .transform((spec) => spec as unknown as Figure),
-    config: z.object({}).passthrough(),
+    figure: z.looseObject({}).transform((spec) => spec as unknown as Figure),
+    config: z.looseObject({}),
   });
 
   public render(props: IPluginProps<T, Data>): JSX.Element {

package/src/plugins/impl/plotly/selection.ts

@@ -208,13 +208,19 @@ export function hasAreaTrace(
   });
 }
 
-function createDragmodeButton(
-  name: string,
-  title: string,
-  svg: string,
-  dragmode: Plotly.Layout["dragmode"],
-  setDragmode: (dragmode: Plotly.Layout["dragmode"]) => void,
-): ModeBarButton {
+function createDragmodeButton({
+  name,
+  title,
+  svg,
+  dragmode,
+  setDragmode,
+}: {
+  name: string;
+  title: string;
+  svg: string;
+  dragmode: Plotly.Layout["dragmode"];
+  setDragmode: (dragmode: Plotly.Layout["dragmode"]) => void;
+}): ModeBarButton {
   return {
     name,
     title,
@@ -227,27 +233,27 @@ export function lineSelectionButtons(
   setDragmode: (dragmode: Plotly.Layout["dragmode"]) => void,
 ): ModeBarButton[] {
   return [
-    createDragmodeButton(
-      "line-box-select",
-      "Box select",
-      `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+    createDragmodeButton({
+      name: "line-box-select",
+      title: "Box select",
+      svg: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
         stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
         <rect x="4" y="4" width="16" height="16" stroke-dasharray="2 2" />
       </svg>`,
-      "select",
+      dragmode: "select",
       setDragmode,
-    ),
-    createDragmodeButton(
-      "line-lasso-select",
-      "Lasso select",
-      `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
+    }),
+    createDragmodeButton({
+      name: "line-lasso-select",
+      title: "Lasso select",
+      svg: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor"
         stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
         <path d="M6 8c0-2.2 2.2-4 5-4s5 1.8 5 4-2.2 4-5 4-5 1.8-5 4 2.2 4 5 4" />
         <circle cx="17.5" cy="16.5" r="1.5" />
       </svg>`,
-      "lasso",
+      dragmode: "lasso",
       setDragmode,
-    ),
+    }),
   ];
 }
 

package/src/plugins/impl/vega/VegaPlugin.tsx

@@ -16,14 +16,13 @@ export class VegaPlugin implements IPlugin<VegaComponentState, Data> {
 
   public validator = z.object({
     spec: z
-      .object({})
-      .passthrough()
+      .looseObject({})
       .transform((spec) => spec as unknown as VegaLiteSpec),
     chartSelection: z
       .union([z.boolean(), z.literal("point"), z.literal("interval")])
       .default(true),
     fieldSelection: z.union([z.boolean(), z.array(z.string())]).default(true),
-    embedOptions: z.object({}).passthrough().default({}),
+    embedOptions: z.looseObject({}).default({}),
   });
 
   public render(props: IPluginProps<VegaComponentState, Data>): JSX.Element {

package/src/plugins/impl/vega/make-selectable.ts

@@ -3,6 +3,7 @@
 import type { TopLevelSpec } from "vega-lite";
 import type { NonNormalizedSpec } from "vega-lite/types_unstable/spec/index.js";
 import type { TopLevelParameter } from "vega-lite/types_unstable/spec/toplevel.js";
+import { Arrays } from "@/utils/arrays";
 
 import { findEncodedFields, makeEncodingInteractive } from "./encodings";
 import { Marks } from "./marks";
@@ -218,7 +219,7 @@ function removeSpecificParamsFromNestedSpecs(
     }
 
     if (filteredParams.length === 0) {
-      const { params, ...rest } = spec;
+      const { params: _params, ...rest } = spec;
       return rest as SpecWithParams;
     }
 
@@ -357,9 +358,7 @@ export function makeSelectable<T extends VegaLiteSpec>(
 
       // If fieldSelection is an array, filter the fields
       if (Array.isArray(fieldSelection)) {
-        legendFields = legendFields.filter((field) =>
-          fieldSelection.includes(field),
-        );
+        legendFields = Arrays.intersection(legendFields, fieldSelection);
       }
     }
 
@@ -420,9 +419,7 @@ function makeLegendSelectable(
   let legendFields = findEncodedFields(spec);
   // If fieldSelection is an array, we filter the fields
   if (Array.isArray(fieldSelection)) {
-    legendFields = legendFields.filter((field) =>
-      fieldSelection.includes(field),
-    );
+    legendFields = Arrays.intersection(legendFields, fieldSelection);
   }
 
   const legendParams = legendFields.map((field) => Params.legend(field));

package/src/plugins/layout/DownloadPlugin.tsx

@@ -6,7 +6,7 @@ import { z } from "zod";
 import { buttonVariants } from "@/components/ui/button";
 import { toast } from "@/components/ui/use-toast";
 import { cn } from "@/utils/cn";
-import { downloadByURL } from "@/utils/download";
+import { downloadByURL, isDownloadUrl } from "@/utils/download";
 import { Logger } from "@/utils/Logger";
 import { createPlugin } from "../core/builder";
 import { renderHTML } from "../core/RenderHTML";
@@ -80,7 +80,7 @@ const DownloadButton = ({
   const [isLoading, setIsLoading] = useState(false);
 
   const handleClick = async (e: React.MouseEvent) => {
-    if (data.disabled) {
+    if (data.disabled || isLoading) {
       e.preventDefault();
       e.stopPropagation();
       return;
@@ -88,15 +88,11 @@ const DownloadButton = ({
 
     e.preventDefault();
 
-    if (!data.lazy) {
-      downloadByURL(data.data, data.filename ?? undefined);
-      return;
-    }
-
-    setIsLoading(true);
-
     try {
-      const loadedData = await load({});
+      if (data.lazy) {
+        setIsLoading(true);
+      }
+      const loadedData = data.lazy ? await load({}) : data;
       downloadByURL(
         loadedData.data || data.data,
         loadedData.filename ?? data.filename ?? undefined,
@@ -117,7 +113,7 @@ const DownloadButton = ({
 
   return (
     <a
-      href={data.data}
+      href={isDownloadUrl(data.data) ? data.data : undefined}
       download={data.filename ?? ""}
       onClick={handleClick}
       className={buttonVariants({

package/src/plugins/layout/LazyPlugin.tsx

@@ -2,7 +2,7 @@
 
 import { useIntersectionObserver } from "@uidotdev/usehooks";
 import { Loader2Icon } from "lucide-react";
-import type { JSX } from "react";
+import { type JSX, useEffect } from "react";
 import { z } from "zod";
 import { useAsyncData } from "@/hooks/useAsyncData";
 import { createPlugin } from "@/plugins/core/builder";
@@ -63,9 +63,12 @@ const LazyComponent = ({
     rootMargin: "0px",
   });
 
-  if (entry?.isIntersecting && !value) {
-    setValue(true);
-  }
+  const isVisible = entry?.isIntersecting ?? false;
+  useEffect(() => {
+    if (isVisible && !value) {
+      setValue(true);
+    }
+  }, [isVisible, value, setValue]);
 
   // For each re-render, we have to make a waterfall request
   // We could improve performance if the BE was able to know if the same

package/src/plugins/layout/RoutesPlugin.tsx

@@ -56,7 +56,7 @@ const RoutesComponent = ({
 
   useEffect(() => {
     // Listen for route changes
-    const listener = (e: PopStateEvent | HashChangeEvent) => {
+    const listener = () => {
       handleFindMatch(window.location);
     };
     window.addEventListener("hashchange", listener);

package/src/plugins/layout/__test__/DownloadPlugin.test.tsx

@@ -0,0 +1,205 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  waitFor,
+} from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Mocks } from "@/__mocks__/common";
+import { toast } from "@/components/ui/use-toast";
+import { assertExists } from "@/utils/assertExists";
+import { Deferred } from "@/utils/Deferred";
+import { registerReactComponent } from "../../core/registerReactComponent";
+import { sanitizeHtml } from "../../core/sanitize-html";
+import { DownloadPlugin } from "../DownloadPlugin";
+
+vi.mock("@/components/ui/use-toast", () => ({ toast: vi.fn() }));
+vi.mock("@/utils/Logger", () => ({ Logger: Mocks.quietLogger() }));
+
+type DownloadData = Parameters<typeof DownloadPlugin.render>[0]["data"];
+type Load = Parameters<typeof DownloadPlugin.render>[0]["functions"]["load"];
+
+function renderDownload(
+  data: Partial<DownloadData> = {},
+  load = vi.fn<Load>(),
+) {
+  const result = render(
+    DownloadPlugin.render({
+      host: document.createElement("div"),
+      value: null,
+      setValue: vi.fn(),
+      data: DownloadPlugin.validator.parse({
+        data: "./@file/123-results.csv",
+        filename: "results.csv",
+        ...data,
+      }),
+      functions: { load },
+    }),
+  );
+  const button = result.getByText("Download").closest("a");
+  assertExists(button);
+  return { ...result, load, button };
+}
+
+describe("DownloadPlugin", () => {
+  const downloads: { href: string | null; filename: string | null }[] = [];
+
+  beforeEach(() => {
+    downloads.length = 0;
+    vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(function (
+      this: HTMLAnchorElement,
+    ) {
+      downloads.push({
+        href: this.getAttribute("href"),
+        filename: this.getAttribute("download"),
+      });
+    });
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+    vi.clearAllMocks();
+  });
+
+  it("downloads immediately without calling load", () => {
+    const { button, load } = renderDownload();
+    fireEvent.click(button);
+
+    expect(downloads).toEqual([
+      { href: "./@file/123-results.csv", filename: "results.csv" },
+    ]);
+    expect(load).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { data: "data:text/plain,hello", filename: "loaded.txt" },
+    { data: "", filename: "renamed.csv" },
+    { data: "data:text/plain,hello", filename: null },
+    { data: "data:audio/x-wav;base64,AAA=", filename: "audio.wav" },
+    {
+      data: "data:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet;base64,AAA=",
+      filename: "results.xlsx",
+    },
+  ])("downloads lazy data with metadata fallbacks: %j", async (loadedData) => {
+    const load = vi.fn<Load>().mockResolvedValue(loadedData);
+    const { button } = renderDownload({ lazy: true }, load);
+    fireEvent.click(button);
+
+    await waitFor(() => {
+      expect(downloads).toEqual([
+        {
+          href: loadedData.data || "./@file/123-results.csv",
+          filename: loadedData.filename ?? "results.csv",
+        },
+      ]);
+    });
+    expect(load).toHaveBeenCalledExactlyOnceWith({});
+    expect(toast).not.toHaveBeenCalled();
+  });
+
+  it.each([false, true])("ignores disabled clicks (lazy=%s)", (lazy) => {
+    const { button, load } = renderDownload({ disabled: true, lazy });
+    fireEvent.click(button);
+    expect(downloads).toEqual([]);
+    expect(load).not.toHaveBeenCalled();
+    expect(toast).not.toHaveBeenCalled();
+  });
+
+  it.each([false, true])(
+    "handles an unsupported URL (lazy=%s)",
+    async (lazy) => {
+      const data = "java\nscript:alert(1)";
+      const load = vi.fn<Load>().mockResolvedValue({ data });
+      const { button } = renderDownload({ data, lazy }, load);
+      expect(button.hasAttribute("href")).toBe(false);
+      fireEvent.click(button);
+
+      await waitFor(() => {
+        expect(toast).toHaveBeenCalledWith({
+          title: "Failed to download",
+          description: "Please try again.",
+        });
+      });
+      expect(downloads).toEqual([]);
+    },
+  );
+
+  it.each([
+    "javascript:alert(1)",
+    "data:text/html,<h1>hello</h1>",
+    "data:image/svg+xml,<svg/>",
+    "data:application/x-javascript,alert(1)",
+  ])("validates the lazy response URL %s", async (data) => {
+    const load = vi.fn<Load>().mockResolvedValue({ data });
+    const { button } = renderDownload({ lazy: true }, load);
+    fireEvent.click(button);
+
+    await waitFor(() => expect(toast).toHaveBeenCalledOnce());
+    expect(downloads).toEqual([]);
+  });
+
+  it("validates the fallback URL when lazy loading only returns a filename", async () => {
+    const load = vi
+      .fn<Load>()
+      .mockResolvedValue({ data: "", filename: "file.txt" });
+    const { button } = renderDownload(
+      { data: "javascript:alert(1)", lazy: true },
+      load,
+    );
+    fireEvent.click(button);
+
+    await waitFor(() => expect(toast).toHaveBeenCalledOnce());
+    expect(downloads).toEqual([]);
+  });
+
+  it("ignores clicks while loading and allows retry after a failed load", async () => {
+    const pendingLoad = new Deferred<Awaited<ReturnType<Load>>>();
+    const load = vi
+      .fn<Load>()
+      .mockReturnValueOnce(pendingLoad.promise)
+      .mockResolvedValue({ data: "data:text/plain,retry" });
+    const { button } = renderDownload({ data: "", lazy: true }, load);
+    fireEvent.click(button);
+    fireEvent.click(button);
+    expect(load).toHaveBeenCalledOnce();
+
+    await act(async () => pendingLoad.reject(new Error("Load failed")));
+    expect(toast).toHaveBeenCalledOnce();
+    expect(downloads).toEqual([]);
+
+    fireEvent.click(button);
+    await waitFor(() =>
+      expect(downloads).toEqual([
+        { href: "data:text/plain,retry", filename: "results.csv" },
+      ]),
+    );
+    expect(load).toHaveBeenCalledTimes(2);
+  });
+
+  it("rejects an unsupported URL restored from sanitized output", async () => {
+    registerReactComponent(DownloadPlugin);
+    const container = document.createElement("div");
+    container.innerHTML = sanitizeHtml(
+      `<marimo-download data-data='"javascript:alert(1)"' data-initial-value='null' data-disabled='false' data-lazy='false'></marimo-download>`,
+    );
+    try {
+      await act(async () => {
+        document.body.append(container);
+      });
+      const button = container
+        .querySelector("marimo-download")
+        ?.shadowRoot?.querySelector("a");
+      assertExists(button);
+      expect(button.hasAttribute("href")).toBe(false);
+      fireEvent.click(button);
+      expect(toast).toHaveBeenCalledOnce();
+      expect(downloads).toEqual([]);
+    } finally {
+      await act(async () => container.remove());
+    }
+  });
+});

package/src/plugins/layout/__tests__/LazyPlugin.test.tsx

@@ -0,0 +1,98 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { render } from "@testing-library/react";
+import { afterEach, describe, expect, test, vi } from "vitest";
+import type { IPluginProps } from "../../types";
+import { LazyPlugin } from "../LazyPlugin";
+
+const intersection = vi.hoisted(() => ({
+  entry: null as { isIntersecting: boolean } | null,
+}));
+
+vi.mock("@uidotdev/usehooks", () => ({
+  useIntersectionObserver: () => [vi.fn(), intersection.entry],
+}));
+
+type Props = IPluginProps<
+  boolean,
+  { showLoadingIndicator: boolean },
+  { load: (req: {}) => Promise<{ html: string }> }
+>;
+
+function lazyElement(value: boolean, setValue: Props["setValue"]) {
+  const load = vi.fn().mockResolvedValue({ html: "<p>loaded</p>" });
+  const props: Props = {
+    value,
+    setValue,
+    data: { showLoadingIndicator: false },
+    functions: { load },
+    host: document.createElement("div"),
+  };
+  return <>{LazyPlugin.render(props)}</>;
+}
+
+function renderLazy(value: boolean, setValue: Props["setValue"]) {
+  return render(lazyElement(value, setValue));
+}
+
+describe("LazyPlugin visibility", () => {
+  afterEach(() => {
+    intersection.entry = null;
+  });
+
+  test("does not change the value while hidden", () => {
+    intersection.entry = { isIntersecting: false };
+    const setValue = vi.fn();
+    renderLazy(false, setValue);
+    expect(setValue).not.toHaveBeenCalled();
+  });
+
+  test("marks the plugin loaded once when it becomes visible", () => {
+    intersection.entry = null;
+    const setValue = vi.fn();
+    const { rerender } = renderLazy(false, setValue);
+    expect(setValue).not.toHaveBeenCalled();
+
+    intersection.entry = { isIntersecting: true };
+    rerender(lazyElement(false, setValue));
+    expect(setValue).toHaveBeenCalledTimes(1);
+    expect(setValue).toHaveBeenCalledWith(true);
+
+    rerender(lazyElement(false, setValue));
+    expect(setValue).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not change an already loaded value", () => {
+    intersection.entry = { isIntersecting: true };
+    const setValue = vi.fn();
+    renderLazy(true, setValue);
+    expect(setValue).not.toHaveBeenCalled();
+  });
+
+  test("calls the setter after render, never during it", () => {
+    intersection.entry = { isIntersecting: true };
+    let renderCount = 0;
+    const calls: number[] = [];
+    const setValue = vi.fn(() => calls.push(renderCount));
+    const Probe = () => {
+      renderCount++;
+      return null;
+    };
+    const load = vi.fn().mockResolvedValue({ html: "" });
+    render(
+      <>
+        {LazyPlugin.render({
+          value: false,
+          setValue,
+          data: { showLoadingIndicator: false },
+          functions: { load },
+          host: document.createElement("div"),
+        })}
+        <Probe />
+      </>,
+    );
+    // A render-time call happens before the sibling Probe renders (count 0).
+    // An effect runs after the whole tree commits (count 1).
+    expect(calls).toEqual([1]);
+  });
+});