@marimo-team/islands 0.25.3-dev47 → 0.25.3-dev48

package/src/plugins/impl/anywidget/widget-binding.ts

@@ -46,38 +46,80 @@ function abortSignalAny(signals: AbortSignal[]): AbortSignal {
   return controller.signal;
 }
 
+interface ModuleEntry {
+  promise: Promise<unknown>;
+  references: number;
+  dispose: () => void;
+}
+
 /**
  * Deduplicates ESM imports by jsHash.
  * A single import is shared across all widget instances using the same module.
  */
 class WidgetDefRegistry {
-  #cache = new Map<string, Promise<unknown>>();
+  #cache = new Map<string, ModuleEntry>();
 
   /**
    * Get (or start) the ESM import for a widget module, cached by
    * jsHash so multiple instances share one import. Pass
    * `kernelAuthored: true` only for URLs from an `EsmSpec`; it widens
-   * the import gate to remote and data URLs.
+   * the import gate to remote and data URLs. A lifetime retains the module's
+   * temporary URL until that signal aborts; omit it to retain the URL for
+   * the notebook's lifetime. The evaluated module itself stays cached.
    */
   public getModule(options: {
     jsUrl: string;
     jsHash: string;
     kernelAuthored?: boolean;
+    lifetime?: AbortSignal;
   }): Promise<unknown> {
-    const { jsUrl, jsHash, kernelAuthored = false } = options;
-    const cached = this.#cache.get(jsHash);
-    if (cached) {
-      return cached;
+    const { jsUrl, jsHash, kernelAuthored = false, lifetime } = options;
+    let entry = this.#cache.get(jsHash);
+    if (!entry) {
+      const imported = this.#doImport(jsUrl, { kernelAuthored });
+      const created: ModuleEntry = {
+        references: 0,
+        dispose: () => undefined,
+        promise: imported.then(
+          ({ module, dispose }) => {
+            created.dispose = dispose;
+            return module;
+          },
+          (error) => {
+            // An invalidated import must not evict its replacement.
+            if (this.#cache.get(jsHash) === created) {
+              this.#cache.delete(jsHash);
+            }
+            throw error;
+          },
+        ),
+      };
+      this.#cache.set(jsHash, created);
+      entry = created;
     }
-
-    const promise = this.#doImport(jsUrl, { kernelAuthored }).catch((error) => {
-      // On failure, remove from cache so a retry with a new URL can work
-      this.#cache.delete(jsHash);
-      throw error;
-    });
-
-    this.#cache.set(jsHash, promise);
-    return promise;
+    const retained = entry;
+    retained.references += 1;
+    const release = () => {
+      retained.references -= 1;
+      if (retained.references === 0) {
+        // Keep the evaluated module cached: re-importing would re-run its
+        // top-level side effects (e.g. `customElements.define`). Only the
+        // temporary URL is released.
+        void retained.promise.then(
+          () => {
+            retained.dispose();
+            retained.dispose = () => undefined;
+          },
+          () => undefined,
+        );
+      }
+    };
+    if (lifetime?.aborted) {
+      release();
+    } else {
+      lifetime?.addEventListener("abort", release, { once: true });
+    }
+    return retained.promise;
   }
 
   public invalidate(jsHash: string): void {
@@ -87,7 +129,7 @@ class WidgetDefRegistry {
   async #doImport(
     jsUrl: string,
     opts: { kernelAuthored?: boolean } = {},
-  ): Promise<unknown> {
+  ): Promise<{ module: unknown; dispose: () => void }> {
     // By default, only trust marimo virtual file paths: arbitrary URLs
     // would let markdown-injected elements import attacker-controlled
     // JavaScript. Kernel-authored URLs (from an `EsmSpec`) are exempt —
@@ -103,11 +145,23 @@ class WidgetDefRegistry {
         )}`,
       );
     }
-    let url = asRemoteURL(jsUrl).toString();
-    if (isStaticNotebook()) {
-      url = resolveVirtualFileURL(url);
+    const remoteUrl = asRemoteURL(jsUrl).toString();
+    const url = isStaticNotebook()
+      ? resolveVirtualFileURL(remoteUrl)
+      : remoteUrl;
+    const dispose = () => {
+      // Only the static-file resolver's newly created URL belongs to us.
+      if (url !== remoteUrl) {
+        URL.revokeObjectURL(url);
+      }
+    };
+    try {
+      const module = await import(/* @vite-ignore */ url);
+      return { module, dispose };
+    } catch (error) {
+      dispose();
+      throw error;
     }
-    return import(/* @vite-ignore */ url);
   }
 }
 
@@ -132,6 +186,7 @@ interface CreateWidgetBindingOptions<T extends ModelState> {
   model: Model<T>;
   createHost: HostFactory;
   controller?: AbortController;
+  onDestroy?: () => void;
 }
 
 async function safelyRunCleanup(cleanup: Cleanup, reason: string) {
@@ -159,6 +214,7 @@ export class WidgetBinding<T extends ModelState = ModelState> {
   #createHost: HostFactory;
   #cleanupTasks = new Set<Promise<void>>();
   #viewTasks = new Set<Promise<void>>();
+  #onDestroy?: () => void;
 
   private constructor(options: {
     widget: ResolvedWidget<T>;
@@ -166,12 +222,14 @@ export class WidgetBinding<T extends ModelState = ModelState> {
     exports: unknown;
     controller: AbortController;
     createHost: HostFactory;
+    onDestroy?: () => void;
   }) {
     this.#widget = options.widget;
     this.#model = options.model;
     this.#exports = options.exports;
     this.#controller = options.controller;
     this.#createHost = options.createHost;
+    this.#onDestroy = options.onDestroy;
   }
 
   /**
@@ -185,76 +243,94 @@ export class WidgetBinding<T extends ModelState = ModelState> {
     model,
     createHost,
     controller = new AbortController(),
+    onDestroy,
   }: CreateWidgetBindingOptions<T>): Promise<WidgetBinding<T>> {
     const signal = controller.signal;
-    const widget: ResolvedWidget<T> =
-      typeof widgetDef === "function" ? await widgetDef() : widgetDef;
+    let lateCleanup: Promise<void> | undefined;
+    try {
+      const widget: ResolvedWidget<T> =
+        typeof widgetDef === "function" ? await widgetDef() : widgetDef;
 
-    const initPromise = Promise.resolve(
-      widget.initialize?.({
-        model: modelProxy(model, signal),
-        experimental,
-        signal,
-      }),
-    );
-    // If destroyed mid-initialize, still run a late-arriving legacy
-    // cleanup callback: the widget acquired resources.
-    initPromise
-      .then(async (settled) => {
-        if (signal.aborted && isCleanup(settled)) {
-          await safelyRunCleanup(settled, "late initialize");
-        }
-      })
-      .catch(() => undefined);
+      if (signal.aborted) {
+        throw new Error("[anywidget] binding destroyed");
+      }
+      const initPromise = Promise.resolve(
+        widget.initialize?.({
+          model: modelProxy(model, signal),
+          experimental,
+          signal,
+        }),
+      );
+      // If destroyed mid-initialize, still run a late-arriving legacy
+      // cleanup callback: the widget acquired resources.
+      lateCleanup = initPromise
+        .then(async (settled) => {
+          if (signal.aborted && isCleanup(settled)) {
+            await safelyRunCleanup(settled, "late initialize");
+          }
+        })
+        .catch(() => undefined);
 
-    // Race against destruction so a hung `initialize` can't strand
-    // callers whose model already closed.
-    const result = await Promise.race([
-      initPromise,
-      new Promise<never>((_, reject) => {
-        const abort = () => reject(new Error("[anywidget] binding destroyed"));
-        if (signal.aborted) {
-          abort();
-          return;
-        }
-        signal.addEventListener("abort", abort, { once: true });
-      }),
-    ]);
+      // Race against destruction so a hung `initialize` can't strand
+      // callers whose model already closed.
+      const result = await Promise.race([
+        initPromise,
+        new Promise<never>((_, reject) => {
+          const abort = () =>
+            reject(new Error("[anywidget] binding destroyed"));
+          if (signal.aborted) {
+            abort();
+            return;
+          }
+          signal.addEventListener("abort", abort, { once: true });
+        }),
+      ]);
 
-    if (signal.aborted) {
-      throw new Error("[anywidget] binding destroyed");
-    }
+      if (signal.aborted) {
+        throw new Error("[anywidget] binding destroyed");
+      }
 
-    // Distinguish anywidget's three return shapes:
-    //   function → legacy cleanup callback (run on destroy)
-    //   object   → widget exports (anywidget>=0.11)
-    //   void     → nothing
-    let exports: unknown;
-    let initializeCleanup: Cleanup | undefined;
-    if (isCleanup(result)) {
-      initializeCleanup = result;
-      exports = undefined;
-    } else if (typeof result === "object" && result !== null) {
-      exports = result;
-    } else {
-      exports = undefined;
-    }
+      // Distinguish anywidget's three return shapes:
+      //   function → legacy cleanup callback (run on destroy)
+      //   object   → widget exports (anywidget>=0.11)
+      //   void     → nothing
+      let exports: unknown;
+      let initializeCleanup: Cleanup | undefined;
+      if (isCleanup(result)) {
+        initializeCleanup = result;
+        exports = undefined;
+      } else if (typeof result === "object" && result !== null) {
+        exports = result;
+      } else {
+        exports = undefined;
+      }
 
-    const binding = new WidgetBinding({
-      widget,
-      model,
-      exports,
-      controller,
-      createHost,
-    });
-    if (initializeCleanup) {
-      signal.addEventListener(
-        "abort",
-        () => void binding.#trackCleanup(initializeCleanup, "initialize"),
-        { once: true },
-      );
+      const binding = new WidgetBinding({
+        widget,
+        model,
+        exports,
+        controller,
+        createHost,
+        onDestroy,
+      });
+      if (initializeCleanup) {
+        signal.addEventListener(
+          "abort",
+          () => void binding.#trackCleanup(initializeCleanup, "initialize"),
+          { once: true },
+        );
+      }
+      return binding;
+    } catch (error) {
+      // A canceled initialize may still be using import.meta.url in its
+      // late cleanup. Keep the module alive until that work settles.
+      if (lateCleanup) {
+        void lateCleanup.then(() => onDestroy?.());
+      } else {
+        onDestroy?.();
+      }
+      throw error;
     }
-    return binding;
   }
 
   /**
@@ -353,6 +429,8 @@ export class WidgetBinding<T extends ModelState = ModelState> {
     while (this.#cleanupTasks.size > 0) {
       await Promise.all(this.#cleanupTasks);
     }
+    this.#onDestroy?.();
+    this.#onDestroy = undefined;
   }
 }
 

package/src/plugins/impl/mpl-interactive/MplInteractivePlugin.tsx

@@ -1,7 +1,7 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 /* oxlint-disable typescript/no-explicit-any */
 
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
 import { z } from "zod";
 import { useEventListener } from "@/hooks/useEventListener";
 import { createPlugin } from "@/plugins/core/builder";
@@ -186,12 +186,14 @@ const MplInteractiveSlot = (props: IPluginProps<ModelIdRef, Data>) => {
   // the figure is built once, and switching to a new model is the rebind
   // effect's job, not a reason to tear the canvas down.
   const modelIdRef = useRef(modelId);
-  modelIdRef.current = modelId;
   // The data attributes are re-parsed into fresh objects on every rerun, so
   // `toolbarImages` changes identity even when its contents do not. Read it
   // from a ref so it can't retrigger the mount effect and rebuild the canvas.
   const toolbarImagesRef = useRef(toolbarImages);
-  toolbarImagesRef.current = toolbarImages;
+  useLayoutEffect(() => {
+    modelIdRef.current = modelId;
+    toolbarImagesRef.current = toolbarImages;
+  }, [modelId, toolbarImages]);
 
   // Bind the already-rendered figure/socket to a backend model, leaving the
   // DOM, figure, and socket in place so they survive across reruns. Disposes

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 {
@@ -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/stories/__tests__/editor-story.test.tsx

@@ -0,0 +1,33 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { EditorView } from "@codemirror/view";
+import { composeStories } from "@storybook/react-vite";
+import { act, render } from "@testing-library/react";
+import { expect, it, vi } from "vitest";
+import * as stories from "../editor.stories";
+
+vi.mock("@/core/codemirror/cm", () => ({
+  basicBundle: () => [],
+}));
+
+const { Primary } = composeStories(stories);
+
+it("preserves editor changes when the story rerenders with the same theme", () => {
+  const { container, rerender } = render(<Primary />);
+  const editor = container.querySelector<HTMLElement>(".cm-editor");
+  expect(editor).not.toBeNull();
+  const view = editor && EditorView.findFromDOM(editor);
+  expect(view).toBeDefined();
+  if (!view) {
+    throw new Error("Editor view was not mounted");
+  }
+
+  act(() => {
+    view.dispatch({
+      changes: { from: 0, to: view.state.doc.length, insert: "user edit" },
+    });
+  });
+  rerender(<Primary />);
+
+  expect(container.querySelector(".cm-editor")).toBe(editor);
+  expect(view.state.doc.toString()).toBe("user edit");
+});

package/src/stories/editor.stories.tsx

@@ -5,7 +5,7 @@ import { EditorState, type Extension } from "@codemirror/state";
 import { EditorView } from "@codemirror/view";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import CodeMirror from "@uiw/react-codemirror";
-import { useEffect, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { CopilotConfig } from "@/core/codemirror/copilot/copilot-config";
 import { copilotBundle } from "@/core/codemirror/copilot/extension";
 import { OverridingHotkeyProvider } from "@/core/hotkeys/hotkeys";
@@ -52,28 +52,35 @@ const Editor = (opts: { extensions?: Extension[] }): React.ReactNode => {
     });
 
     return () => view.destroy();
-    // oxlint-disable-next-line react-hooks/exhaustive-deps
-  }, [ref.current]);
+  }, [opts.extensions]);
 
   return <div className="cm" ref={ref} />;
 };
 
-export const Primary: Story = {
-  render: (_args, ctx) => (
+const PrimaryEditor = ({ theme }: Pick<CodeMirrorSetupOpts, "theme">) => {
+  const extensions = useMemo(
+    () =>
+      basicBundle({
+        completionConfig: {
+          activate_on_typing: false,
+          copilot: false,
+          signature_hint_on_typing: false,
+        },
+        theme,
+        hotkeys: new OverridingHotkeyProvider({}),
+      } as unknown as CodeMirrorSetupOpts),
+    [theme],
+  );
+
+  return (
     <div className="Cell m-20 w-[60%] overflow-hidden">
-      <Editor
-        extensions={basicBundle({
-          completionConfig: {
-            activate_on_typing: false,
-            copilot: false,
-            signature_hint_on_typing: false,
-          },
-          theme: ctx.globals.theme,
-          hotkeys: new OverridingHotkeyProvider({}),
-        } as unknown as CodeMirrorSetupOpts)}
-      />
+      <Editor extensions={extensions} />
     </div>
-  ),
+  );
+};
+
+export const Primary: Story = {
+  render: (_args, ctx) => <PrimaryEditor theme={ctx.globals.theme} />,
 };
 
 export const DefaultPython: Story = {