@marimo-team/islands 0.23.15-dev4 → 0.23.15-dev40

package/src/core/wasm/worker/bootstrap.ts

@@ -1,5 +1,6 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import { loadPyodide, type PyodideInterface } from "pyodide";
+import type { PyCallable, PyProxy } from "pyodide/ffi";
 import type { UserConfig } from "@/core/config/config-schema";
 import type { NotificationPayload } from "@/core/kernel/messages";
 import type { JsonString } from "@/utils/json/base64";
@@ -12,6 +13,12 @@ import type { SerializedBridge, WasmController } from "./types";
 import { shouldLoadDuckDBPackages } from "../utils";
 
 const MAKE_SNAPSHOT = false;
+type SessionResources = [
+  bridge: PyProxy,
+  init: PyCallable,
+  packages: PyProxy,
+  stop: PyCallable,
+];
 
 // This class initializes the wasm environment
 // We would like this initialization to be parallelizable
@@ -25,6 +32,9 @@ const MAKE_SNAPSHOT = false;
 
 export class DefaultWasmController implements WasmController {
   protected pyodide: PyodideInterface | null = null;
+  private packageLoadQueue = Promise.resolve();
+  private sessionGeneration = 0;
+  private activeSessionStops = new Set<PyCallable>();
 
   get requirePyodide() {
     invariant(this.pyodide, "Pyodide not loaded");
@@ -111,6 +121,7 @@ export class DefaultWasmController implements WasmController {
     onMessage: (message: JsonString<NotificationPayload>) => void;
     userConfig: UserConfig;
   }): Promise<SerializedBridge> {
+    const sessionGeneration = this.sessionGeneration;
     const { code, filename, onMessage, queryParameters, userConfig } = opts;
     // We pass down a messenger object to the code
     // This is used to have synchronous communication between the JS and Python code
@@ -126,47 +137,129 @@ export class DefaultWasmController implements WasmController {
 
     const span = t.startSpan("startSession.runPython");
     const nbFilename = filename || WasmFileSystem.NOTEBOOK_FILENAME;
-    const [bridge, init, packages] = this.requirePyodide.runPython(
+    const sessionResources = this.requirePyodide.runPython(
       `
       print("[py] Starting marimo...")
       import asyncio
+      import gc
       import js
       from marimo._pyodide.bootstrap import create_session, instantiate
 
       assert js.messenger, "messenger is not defined"
       assert js.query_params, "query_params is not defined"
 
-      session, bridge = create_session(
-        filename="${nbFilename}",
-        query_params=js.query_params.to_py(),
-        message_callback=js.messenger.callback,
-        user_config=js.user_config.to_py(),
-      )
+      def create_session_resources():
+        session, bridge = create_session(
+          filename="${nbFilename}",
+          query_params=js.query_params.to_py(),
+          message_callback=js.messenger.callback,
+          user_config=js.user_config.to_py(),
+        )
+        session_task = None
 
-      def init(auto_instantiate=True):
-        instantiate(session, auto_instantiate)
-        asyncio.create_task(session.start())
+        def init(auto_instantiate=True):
+          nonlocal session_task
+          instantiate(session, auto_instantiate)
+          session_task = asyncio.create_task(session.start())
 
-      # Find the packages to install
-      with open("${nbFilename}", "r") as f:
-        packages = session.find_packages(f.read())
+        async def stop():
+          nonlocal bridge, session, session_task
+          task = session_task
+          kernel_task = getattr(session, "kernel_task", None)
+          if kernel_task is None:
+            if task is not None:
+              task.cancel()
+          else:
+            kernel_task.stop()
+          if task is not None:
+            await asyncio.gather(task, return_exceptions=True)
+          if bridge is not None:
+            bridge.session = None
+          task = None
+          kernel_task = None
+          session_task = None
+          session = None
+          bridge = None
+          gc.collect()
 
-      bridge, init, packages`,
-    );
-    span.end();
+        with open("${nbFilename}", "r") as f:
+          packages = session.find_packages(f.read())
 
-    const foundPackages = new Set<string>(packages.toJs());
+        return bridge, init, packages, stop
+
+      create_session_resources()`,
+    ) as PyProxy;
+    span.end();
+    let bridgeProxy!: PyProxy;
+    let initSession!: PyCallable;
+    let packagesProxy!: PyProxy;
+    let stopSession!: PyCallable;
+    try {
+      [bridgeProxy, initSession, packagesProxy, stopSession] =
+        sessionResources as unknown as SessionResources;
+    } finally {
+      sessionResources.destroy();
+    }
+    let foundPackages: Set<string>;
+    try {
+      foundPackages = new Set<string>(packagesProxy.toJs());
+    } catch (error) {
+      bridgeProxy.destroy();
+      initSession.destroy();
+      stopSession.destroy();
+      throw error;
+    } finally {
+      packagesProxy.destroy();
+    }
+    this.activeSessionStops.add(stopSession);
 
     // Fire and forget:
     // Load notebook dependencies and instantiate the session
     // We don't want to wait for this to finish,
     // so we can show the initial code immediately giving
     // a sense of responsiveness.
-    void this.loadNotebookDeps(code, foundPackages).then(() => {
-      return init(userConfig.runtime.auto_instantiate);
+    const dependenciesReady = this.packageLoadQueue.then(() => {
+      if (sessionGeneration !== this.sessionGeneration) {
+        return;
+      }
+      return this.loadNotebookDeps(code, foundPackages);
     });
+    this.packageLoadQueue = dependenciesReady.catch(() => undefined);
+    void dependenciesReady
+      .then(() => {
+        if (sessionGeneration !== this.sessionGeneration) {
+          return;
+        }
+        return initSession(userConfig.runtime.auto_instantiate);
+      })
+      .catch((error: unknown) => {
+        Logger.error("Failed to load notebook dependencies", error);
+      })
+      .finally(() => initSession.destroy());
+
+    return bridgeProxy as unknown as SerializedBridge;
+  }
 
-    return bridge;
+  async stopSession(): Promise<void> {
+    this.sessionGeneration += 1;
+    const stops = [...this.activeSessionStops];
+    let hasFailure = false;
+    let firstFailure: unknown;
+    for (const stop of stops) {
+      try {
+        await stop();
+        this.activeSessionStops.delete(stop);
+        stop.destroy();
+      } catch (error) {
+        if (!hasFailure) {
+          hasFailure = true;
+          firstFailure = error;
+        }
+      }
+    }
+    if (hasFailure) {
+      throw firstFailure;
+    }
   }
 
   private async loadNotebookDeps(code: string, foundPackages: Set<string>) {

package/src/css/app/Cell.css

@@ -255,6 +255,12 @@
     border: none;
     box-shadow: none;
 
+    /* No dividers between sections. Tailwind v4's divide-y is structural
+     * (`> :not(:last-child)`), so hidden-but-mounted children (e.g. the tray
+     * while presenting) still count as siblings and would otherwise draw a
+     * stray rule under the output. */
+    @apply divide-y-0;
+
     .output-area {
       /* flow-root interferes with margin collapsing, but appears to be unneeded
             * when cell outlines are hidden; clear:both is sufficient.
@@ -443,6 +449,10 @@
   /* Set a fixed gutter width to ensure the hover area is always wide enough */
   /* And make the gutter bigger when the window is super wide */
   --gutter-width: 100px;
+
+  /* Vertical gap between notebook cells (gap-5). Overridable via custom css;
+   * zeroed while presenting, when published cells flow together. */
+  --notebook-cell-gap: 1.25rem;
 }
 
 /* ------------------------ CodeMirror Editor ----------------------------- */

package/src/hooks/__tests__/useHotkey.test.tsx

@@ -0,0 +1,88 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { renderHook } from "@testing-library/react";
+import { createStore, Provider } from "jotai";
+import { describe, expect, it, vi } from "vitest";
+import { Functions } from "@/utils/functions";
+import { useHotkey } from "../useHotkey";
+
+// global.hideCode is bound to "Mod-." by default; "mod" accepts ctrl or meta.
+const SHORTCUT = "global.hideCode";
+
+function createWrapper() {
+  const store = createStore();
+  return ({ children }: { children: React.ReactNode }) => (
+    <Provider store={store}>{children}</Provider>
+  );
+}
+
+function press() {
+  const event = new KeyboardEvent("keydown", {
+    key: ".",
+    ctrlKey: true,
+    cancelable: true,
+    bubbles: true,
+  });
+  document.dispatchEvent(event);
+  return event;
+}
+
+describe("useHotkey", () => {
+  it("invokes the callback and prevents default", () => {
+    const callback = vi.fn();
+    renderHook(() => useHotkey(SHORTCUT, callback), {
+      wrapper: createWrapper(),
+    });
+
+    const event = press();
+    expect(callback).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("does not prevent default when the callback returns false", () => {
+    const callback = vi.fn(() => false);
+    renderHook(() => useHotkey(SHORTCUT, callback), {
+      wrapper: createWrapper(),
+    });
+
+    const event = press();
+    expect(callback).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("still swallows the keystroke for NOOP catch-all handlers", () => {
+    renderHook(() => useHotkey(SHORTCUT, Functions.NOOP), {
+      wrapper: createWrapper(),
+    });
+
+    const event = press();
+    expect(event.defaultPrevented).toBe(true);
+  });
+
+  it("neither runs the callback nor prevents default when disabled", () => {
+    const callback = vi.fn();
+    renderHook(() => useHotkey(SHORTCUT, callback, { disabled: true }), {
+      wrapper: createWrapper(),
+    });
+
+    const event = press();
+    expect(callback).not.toHaveBeenCalled();
+    expect(event.defaultPrevented).toBe(false);
+  });
+
+  it("re-enables when disabled flips back to false", () => {
+    const callback = vi.fn();
+    const { rerender } = renderHook(
+      ({ disabled }: { disabled: boolean }) =>
+        useHotkey(SHORTCUT, callback, { disabled }),
+      { wrapper: createWrapper(), initialProps: { disabled: true } },
+    );
+
+    press();
+    expect(callback).not.toHaveBeenCalled();
+
+    rerender({ disabled: false });
+    const event = press();
+    expect(callback).toHaveBeenCalledOnce();
+    expect(event.defaultPrevented).toBe(true);
+  });
+});

package/src/hooks/useHotkey.ts

@@ -17,13 +17,31 @@ type HotkeyHandler = (
   // oxlint-disable-next-line typescript/no-invalid-void-type
 ) => boolean | void | undefined | Promise<void>;
 
+interface HotkeyOptions {
+  /**
+   * If true, the hotkey is not handled at all: the callback does not run, the
+   * event's default is not prevented, and the action is not registered in the
+   * shortcut registry.
+   *
+   * This differs from passing `Functions.NOOP` as the callback, which still
+   * swallows the keystroke (preventDefault) to suppress native browser/OS
+   * behavior.
+   */
+  disabled?: boolean;
+}
+
 /**
  * Registers a hotkey listener for the given shortcut.
  *
  * @param callback The callback to run when the shortcut is pressed. It does not need to be memoized as this hook will always use the latest callback.
  * If the callback returns false, preventDefault will not be called on the event.
  */
-export function useHotkey(shortcut: HotkeyAction, callback: HotkeyHandler) {
+export function useHotkey(
+  shortcut: HotkeyAction,
+  callback: HotkeyHandler,
+  options: HotkeyOptions = {},
+) {
+  const { disabled = false } = options;
   const { registerAction, unregisterAction } = useSetRegisteredAction();
   const hotkeys = useAtomValue(hotkeysAtom);
 
@@ -31,7 +49,7 @@ export function useHotkey(shortcut: HotkeyAction, callback: HotkeyHandler) {
   const memoizeCallback = useEvent((evt?: KeyboardEvent) => callback(evt));
 
   const listener = useEvent((e: KeyboardEvent) => {
-    if (e.defaultPrevented) {
+    if (disabled || e.defaultPrevented) {
       return;
     }
 
@@ -51,11 +69,18 @@ export function useHotkey(shortcut: HotkeyAction, callback: HotkeyHandler) {
 
   // Register with the shortcut registry
   useEffect(() => {
-    if (!isNOOP) {
+    if (!isNOOP && !disabled) {
       registerAction(shortcut, memoizeCallback);
       return () => unregisterAction(shortcut);
     }
-  }, [memoizeCallback, shortcut, isNOOP, registerAction, unregisterAction]);
+  }, [
+    memoizeCallback,
+    shortcut,
+    isNOOP,
+    disabled,
+    registerAction,
+    unregisterAction,
+  ]);
 }
 
 /**

package/src/plugins/impl/anywidget/__tests__/host.test.ts

@@ -277,25 +277,22 @@ describe("WidgetBinding receives a host in render props", () => {
   });
 });
 
-describe("host-mounted views hydrate like display-mounted ones", () => {
-  it("replays current state to a child's render listeners", async () => {
-    const childId = asModelId("host-hydration-child");
+describe("host-mounted views", () => {
+  it("render with the child's current model state", async () => {
+    const childId = asModelId("host-child-state");
     const parentController = new AbortController();
     const getModuleSpy = vi.spyOn(WIDGET_DEF_REGISTRY, "getModule");
     try {
       const childWidget = {
         render: vi.fn(({ model, el }) => {
-          el.textContent = "count is 5";
-          model.on("change:count", () => {
-            el.textContent = `count is ${model.get("count")}`;
-          });
+          el.textContent = `count is ${model.get("count")}`;
         }),
       };
       const childModel = new Model<ModelState>({ count: 8 }, createMockComm());
       WIDGET_REGISTRY.setModel(childId, childModel);
       WIDGET_REGISTRY.setSpec(childId, {
-        url: "./@file/10-host-hydration-child.js",
-        hash: "hash-host-hydration-child",
+        url: "./@file/10-host-child-state.js",
+        hash: "hash-host-child-state",
       });
       getModuleSpy.mockResolvedValue({ default: childWidget });
 

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

@@ -337,13 +337,12 @@ describe("WidgetBinding", () => {
       { el: document.createElement("div") },
       { signal: controller.signal },
     );
-    // Called once by the hydration replay at mount, once by the set.
     model.set("count", 1);
-    expect(onCount).toHaveBeenCalledTimes(2);
+    expect(onCount).toHaveBeenCalledTimes(1);
 
     controller.abort();
     model.set("count", 2);
-    expect(onCount).toHaveBeenCalledTimes(2);
+    expect(onCount).toHaveBeenCalledTimes(1);
   });
 
   it("should auto-clear initialize listeners on destroy", async () => {
@@ -366,92 +365,54 @@ describe("WidgetBinding", () => {
   });
 });
 
-describe("WidgetBinding hydration replay", () => {
-  it("replays current state to render listeners exactly once", async () => {
+describe("WidgetBinding render listeners", () => {
+  it("fire only for changes after mount, never for pre-existing state", async () => {
     const model = new Model<ModelState>({ count: 8 }, createMockComm());
-    const el = document.createElement("div");
-    const widgetDef = {
-      render: vi.fn(({ model, el }) => {
-        // A widget view that starts with a local default and relies on
-        // change events for hydration.
-        el.textContent = "count is 5";
-        model.on("change:count", () => {
-          el.textContent = `count is ${model.get("count")}`;
-        });
-      }),
-    };
-    const binding = await createBinding(widgetDef, model);
-
-    const controller = new AbortController();
-    await binding.createView({ el }, { signal: controller.signal });
-    expect(el.textContent).toBe("count is 8");
-  });
-
-  it("does not re-fire listeners of already-mounted views", async () => {
-    // Mounting view B must not double-paint view A: the replay is
-    // scoped to the listeners the new render attached.
-    const model = new Model<ModelState>({ count: 0 }, createMockComm());
-    const listeners: Array<ReturnType<typeof vi.fn>> = [];
+    const onCount = vi.fn();
+    const onAnyChange = vi.fn();
     const widgetDef = {
       render: vi.fn(({ model }) => {
-        const listener = vi.fn();
-        listeners.push(listener);
-        model.on("change:count", listener);
+        model.on("change:count", onCount);
+        model.on("change", onAnyChange);
       }),
     };
     const binding = await createBinding(widgetDef, model);
     const controller = new AbortController();
-
     await binding.createView(
       { el: document.createElement("div") },
       { signal: controller.signal },
     );
-    expect(listeners[0]).toHaveBeenCalledTimes(1);
+    expect(onCount).not.toHaveBeenCalled();
+    expect(onAnyChange).not.toHaveBeenCalled();
 
-    await binding.createView(
-      { el: document.createElement("div") },
-      { signal: controller.signal },
-    );
-    // View B's listener hydrated once; view A's was left alone.
-    expect(listeners[1]).toHaveBeenCalledTimes(1);
-    expect(listeners[0]).toHaveBeenCalledTimes(1);
+    model.set("count", 9);
+    expect(onCount).toHaveBeenCalledTimes(1);
+    expect(onCount).toHaveBeenCalledWith(9);
   });
 
-  it("replays the any-change event to its listeners", async () => {
-    const model = new Model<ModelState>({ count: 1 }, createMockComm());
-    const onAnyChange = vi.fn();
+  it("mounting a second view does not fire the first view's listeners", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const listeners: Array<ReturnType<typeof vi.fn>> = [];
     const widgetDef = {
       render: vi.fn(({ model }) => {
-        model.on("change", onAnyChange);
+        const listener = vi.fn();
+        listeners.push(listener);
+        model.on("change:count", listener);
       }),
     };
     const binding = await createBinding(widgetDef, model);
     const controller = new AbortController();
+
     await binding.createView(
       { el: document.createElement("div") },
       { signal: controller.signal },
     );
-    expect(onAnyChange).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not replay initialize listeners", async () => {
-    // The guarantee is per-view: initialize listeners existed before
-    // any view, and replaying at them would fire once per mount.
-    const model = new Model<ModelState>({ count: 1 }, createMockComm());
-    const initListener = vi.fn();
-    const widgetDef = {
-      initialize: vi.fn(({ model }) => {
-        model.on("change:count", initListener);
-      }),
-      render: vi.fn(),
-    };
-    const binding = await createBinding(widgetDef, model);
-    const controller = new AbortController();
     await binding.createView(
       { el: document.createElement("div") },
       { signal: controller.signal },
     );
-    expect(initListener).not.toHaveBeenCalled();
+    expect(listeners[0]).not.toHaveBeenCalled();
+    expect(listeners[1]).not.toHaveBeenCalled();
   });
 
   it("clears the element before rendering into it", async () => {

package/src/plugins/impl/anywidget/model-proxy.ts

@@ -5,15 +5,6 @@ import type { ModelState } from "./types";
 
 type ModelEventCallback = Parameters<AnyModel<ModelState>["on"]>[1];
 
-/**
- * A listener registered through a model proxy (see the hydration
- * replay in `WidgetBinding.createView`).
- */
-export interface ProxyRegistration {
-  event: string;
-  callback: ModelEventCallback;
-}
-
 /**
  * Wrap a model so every `on()` call from inside `initialize` or `render`
  * is auto-tied to a lifetime `AbortSignal`. When the signal aborts,
@@ -27,14 +18,11 @@ export interface ProxyRegistration {
  * The proxy is purely a host-side ergonomic helper. The widget author
  * still writes `model.on("change:foo", handler)` exactly as before; the
  * cleanup signal is supplied transparently.
- *
- * `onRegister`, when given, observes each `on()` registration.
  */
 // oxlint-disable-next-line marimo/prefer-object-params -- concise internal helper used at protocol call sites
 export function modelProxy<T extends ModelState>(
   model: AnyModel<T>,
   signal: AbortSignal,
-  onRegister?: (registration: ProxyRegistration) => void,
 ): AnyModel<T> {
   return {
     get(key) {
@@ -55,7 +43,6 @@ export function modelProxy<T extends ModelState>(
       signal.addEventListener("abort", () => model.off(name, callback), {
         once: true,
       });
-      onRegister?.({ event: name, callback });
     },
     off(name?: string | null, callback?: ModelEventCallback | null): void {
       model.off(name ?? null, callback ?? null);

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

@@ -12,7 +12,7 @@ import { isTrustedVirtualFileUrl } from "@/plugins/core/trusted-url";
 import { Logger } from "@/utils/Logger";
 import type { Host } from "./host";
 import type { Model } from "./model";
-import { modelProxy, type ProxyRegistration } from "./model-proxy";
+import { modelProxy } from "./model-proxy";
 import type { ModelState } from "./types";
 
 export const experimental: Experimental = {
@@ -266,9 +266,8 @@ export class WidgetBinding<T extends ModelState = ModelState> {
    * when the caller's `signal` fires or the binding is destroyed, and
    * listeners registered inside `render` auto-clear on abort.
    *
-   * Hydration guarantee: listeners attached during `render` observe
-   * current model state exactly once, after `render` settles. Scoped
-   * to this view's listeners; re-firing at other views double-paints.
+   * `render` reads current state via `model.get`; change listeners
+   * observe only subsequent changes, matching Jupyter semantics.
    */
   async createView(
     target: { el: HTMLElement },
@@ -305,11 +304,8 @@ export class WidgetBinding<T extends ModelState = ModelState> {
     // Each view gets a host scoped to its own signal so child views tear
     // down with this view.
     const host = this.#createHost(renderSignal);
-    const registrations: ProxyRegistration[] = [];
     const renderCleanup = await widget.render({
-      model: modelProxy(this.#model, renderSignal, (registration) =>
-        registrations.push(registration),
-      ),
+      model: modelProxy(this.#model, renderSignal),
       el: target.el,
       experimental,
       signal: renderSignal,
@@ -333,7 +329,6 @@ export class WidgetBinding<T extends ModelState = ModelState> {
         once: true,
       });
     }
-    this.#replayState(registrations, renderSignal);
   }
 
   #trackCleanup(cleanup: Cleanup, reason: string): Promise<void> {
@@ -343,31 +338,6 @@ export class WidgetBinding<T extends ModelState = ModelState> {
     return task;
   }
 
-  /**
-   * The hydration guarantee documented on `createView`.
-   */
-  #replayState(
-    registrations: readonly ProxyRegistration[],
-    renderSignal: AbortSignal,
-  ): void {
-    const changePrefix = "change:";
-    for (const { event, callback } of registrations) {
-      if (renderSignal.aborted) {
-        return;
-      }
-      try {
-        if (event.startsWith(changePrefix)) {
-          const key = event.slice(changePrefix.length);
-          callback(this.#model.get(key));
-        } else if (event === "change") {
-          callback();
-        }
-      } catch (error) {
-        Logger.error("[WidgetBinding] Error replaying state", error);
-      }
-    }
-  }
-
   /**
    * Destroy this generation, running initialize/render cleanups and
    * clearing listeners registered through its model proxies.