@marimo-team/islands 0.23.14-dev6 → 0.23.14-dev61

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

@@ -1,14 +1,19 @@
 /* Copyright 2026 Marimo. All rights reserved. */
-/* oxlint-disable typescript/no-explicit-any */
-
-import type { AnyWidget, Experimental } from "@anywidget/types";
+import type {
+  AnyWidget,
+  Experimental,
+  Initialize,
+  Render,
+} from "@anywidget/types";
 import { asRemoteURL } from "@/core/runtime/config";
 import { resolveVirtualFileURL } from "@/core/static/files";
 import { isStaticNotebook } from "@/core/static/static-state";
 import { isTrustedVirtualFileUrl } from "@/plugins/core/trusted-url";
 import { Logger } from "@/utils/Logger";
+import type { Host } from "./host";
 import type { Model } from "./model";
-import type { ModelState, WidgetModelId } from "./types";
+import { modelProxy, type ProxyRegistration } from "./model-proxy";
+import type { ModelState } from "./types";
 
 export const experimental: Experimental = {
   invoke: async () => {
@@ -19,8 +24,6 @@ export const experimental: Experimental = {
   },
 };
 
-export type RenderFn = (el: HTMLElement, signal: AbortSignal) => Promise<void>;
-
 /**
  * Polyfill for AbortSignal.any. Returns a signal that aborts when any of the
  * input signals abort. This can be removed once the Node.js test environment
@@ -48,19 +51,26 @@ function abortSignalAny(signals: AbortSignal[]): AbortSignal {
  * A single import is shared across all widget instances using the same module.
  */
 class WidgetDefRegistry {
-  #cache = new Map<string, Promise<any>>();
+  #cache = new Map<string, Promise<unknown>>();
 
   /**
-   * Get (or start) the ESM import for a widget module.
-   * Cached by jsHash so multiple instances share one import.
+   * 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.
    */
-  getModule(jsUrl: string, jsHash: string): Promise<any> {
+  getModule(options: {
+    jsUrl: string;
+    jsHash: string;
+    kernelAuthored?: boolean;
+  }): Promise<unknown> {
+    const { jsUrl, jsHash, kernelAuthored = false } = options;
     const cached = this.#cache.get(jsHash);
     if (cached) {
       return cached;
     }
 
-    const promise = this.#doImport(jsUrl).catch((error) => {
+    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;
@@ -70,23 +80,19 @@ class WidgetDefRegistry {
     return promise;
   }
 
-  /**
-   * Invalidate a cached module (e.g. for hot-reload support).
-   */
-  invalidate(jsHash: string): void {
-    Logger.debug(
-      `[WidgetDefRegistry] Invalidating module cache for hash=${jsHash}`,
-    );
-    this.#cache.delete(jsHash);
-  }
-
-  async #doImport(jsUrl: string): Promise<any> {
-    // Only trust marimo virtual file paths. Accepting arbitrary URLs
-    // would let a raw `<marimo-anywidget data-js-url=...>` element
-    // embedded in a markdown cell dynamically import attacker-controlled
-    // JavaScript at same origin (the HTML sanitizer allows any marimo-*
-    // custom element with any attribute through to the plugin layer).
-    if (!isTrustedVirtualFileUrl(jsUrl)) {
+  async #doImport(
+    jsUrl: string,
+    opts: { kernelAuthored?: boolean } = {},
+  ): Promise<unknown> {
+    // 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 —
+    // a client cannot forge a notification to its peers. data: URLs
+    // cover runtimes where virtual files are unsupported.
+    const trusted =
+      isTrustedVirtualFileUrl(jsUrl) ||
+      (opts.kernelAuthored === true && /^(https?:|data:)/.test(jsUrl));
+    if (!trusted) {
       throw new Error(
         `Refusing to load anywidget module from untrusted URL: ${String(
           jsUrl,
@@ -102,128 +108,283 @@ class WidgetDefRegistry {
 }
 
 /**
- * Connects a Model to a resolved AnyWidget definition.
- * Owns the initialize lifecycle and produces a render function.
+ * Resolved widget def — what `initialize` and `render` are actually called
+ * on. `AnyWidget` is either this shape directly or a factory that returns it.
+ */
+interface ResolvedWidget<T extends ModelState> {
+  initialize?: Initialize<T>;
+  render?: Render<T>;
+}
+
+type HostFactory = (signal: AbortSignal) => Host;
+type Cleanup = () => void | PromiseLike<void>;
+
+function isCleanup(value: unknown): value is Cleanup {
+  return typeof value === "function";
+}
+
+interface CreateWidgetBindingOptions<T extends ModelState> {
+  widgetDef: AnyWidget<T>;
+  model: Model<T>;
+  createHost: HostFactory;
+  controller?: AbortController;
+}
+
+async function safelyRunCleanup(cleanup: Cleanup, reason: string) {
+  try {
+    await cleanup();
+  } catch (error) {
+    Logger.warn(`[WidgetBinding] ${reason} cleanup failed`, error);
+  }
+}
+
+/**
+ * One immutable generation of a widget: a resolved AnyWidget definition
+ * paired with a Model. Constructed by `WidgetBinding.create` and never
+ * rebinds; a code change replaces the whole generation.
  *
  * Per AFM spec:
- * - initialize() is called once per model (or once per hot-reload)
- * - render() (the returned function) is called once per view
+ * - initialize() ran exactly once, in `create`
+ * - render() runs once per view (zero or more per generation)
  */
-class WidgetBinding<T extends ModelState = ModelState> {
-  #controller: AbortController | undefined;
-  #widgetDef: AnyWidget<T> | undefined;
-  #render: RenderFn | undefined;
+export class WidgetBinding<T extends ModelState = ModelState> {
+  #controller: AbortController;
+  #widget: ResolvedWidget<T>;
+  #model: Model<T>;
+  #exports: unknown;
+  #createHost: HostFactory;
+  #cleanupTasks = new Set<Promise<void>>();
+  #viewTasks = new Set<Promise<void>>();
+
+  private constructor(options: {
+    widget: ResolvedWidget<T>;
+    model: Model<T>;
+    exports: unknown;
+    controller: AbortController;
+    createHost: HostFactory;
+  }) {
+    this.#widget = options.widget;
+    this.#model = options.model;
+    this.#exports = options.exports;
+    this.#controller = options.controller;
+    this.#createHost = options.createHost;
+  }
 
   /**
-   * Bind a widget definition to a model.
-   * If the same def is already bound, returns the cached render function.
-   * If a different def is provided (hot reload), tears down the old binding
-   * and re-initializes.
+   * Resolve the widget definition (calling it if it is a factory) and
+   * run `initialize` exactly once, with its listeners scoped to
+   * `controller`'s signal. Aborting the controller mid-initialize
+   * still runs any legacy cleanup callback, and `create` rejects.
    */
-  async bind(widgetDef: AnyWidget<T>, model: Model<T>): Promise<RenderFn> {
-    // Already initialized with the same widget - return cached render
-    if (this.#render && this.#widgetDef === widgetDef) {
-      return this.#render;
-    }
+  static async create<T extends ModelState>({
+    widgetDef,
+    model,
+    createHost,
+    controller = new AbortController(),
+  }: CreateWidgetBindingOptions<T>): Promise<WidgetBinding<T>> {
+    const signal = controller.signal;
+    const widget: ResolvedWidget<T> =
+      typeof widgetDef === "function" ? await widgetDef() : widgetDef;
 
-    // If widgetDef changed (hot reload), destroy old and re-initialize
-    if (this.#render && this.#widgetDef !== widgetDef) {
-      Logger.debug(
-        "[WidgetBinding] Hot-reload detected, aborting previous binding",
-      );
-      this.#controller?.abort();
-      this.#controller = undefined;
-      this.#render = undefined;
-    }
+    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);
 
-    this.#widgetDef = widgetDef;
-    this.#controller = new AbortController();
-    const bindingSignal = this.#controller.signal;
+    // 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 });
+      }),
+    ]);
 
-    // Resolve the widget definition (call if it's a function)
-    const widget =
-      typeof widgetDef === "function" ? await widgetDef() : widgetDef;
+    if (signal.aborted) {
+      throw new Error("[anywidget] binding destroyed");
+    }
 
-    // Call initialize once per model
-    const cleanup = await widget.initialize?.({ model, experimental });
-    if (cleanup) {
-      bindingSignal.addEventListener("abort", cleanup);
+    // 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;
     }
 
-    // Store and return the render closure
-    this.#render = async (el: HTMLElement, viewSignal: AbortSignal) => {
-      const renderCleanup = await widget.render?.({
-        model,
-        el,
-        experimental,
-      });
-      if (renderCleanup) {
-        // Cleanup when either the view unmounts or the binding is destroyed
-        const combined = abortSignalAny([viewSignal, bindingSignal]);
-        combined.addEventListener("abort", () => {
-          const reason = viewSignal.aborted
-            ? "view unmount"
-            : "binding destroyed";
-          Logger.debug(
-            `[WidgetBinding] Render cleanup triggered (reason: ${reason})`,
-          );
-          renderCleanup();
-        });
-      }
-    };
+    const binding = new WidgetBinding({
+      widget,
+      model,
+      exports,
+      controller,
+      createHost,
+    });
+    if (initializeCleanup) {
+      signal.addEventListener(
+        "abort",
+        () => void binding.#trackCleanup(initializeCleanup, "initialize"),
+        { once: true },
+      );
+    }
+    return binding;
+  }
 
-    return this.#render;
+  /**
+   * The object returned from `initialize`, or `undefined` if it
+   * returned a cleanup function or nothing.
+   */
+  get exports(): unknown {
+    return this.#exports;
   }
 
   /**
-   * Destroy this binding, aborting the initialize lifecycle.
+   * Mount a view of this widget into `el`. Each view's signal aborts
+   * 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.
    */
-  destroy(): void {
-    Logger.debug(
-      "[WidgetBinding] Destroying binding, aborting initialize lifecycle",
-    );
-    this.#controller?.abort();
-    this.#controller = undefined;
-    this.#widgetDef = undefined;
-    this.#render = undefined;
+  async createView(
+    target: { el: HTMLElement },
+    options: { signal: AbortSignal },
+  ): Promise<void> {
+    const task = this.#createView(target, options);
+    this.#viewTasks.add(task);
+    try {
+      await task;
+    } finally {
+      this.#viewTasks.delete(task);
+    }
   }
-}
 
-/**
- * Maps WidgetModelId to WidgetBinding instances.
- * Singleton that manages the lifecycle of all bindings.
- */
-class BindingManager {
-  #bindings = new Map<WidgetModelId, WidgetBinding<any>>();
-
-  getOrCreate(modelId: WidgetModelId): WidgetBinding<any> {
-    let binding = this.#bindings.get(modelId);
-    if (!binding) {
-      binding = new WidgetBinding();
-      this.#bindings.set(modelId, binding);
+  async #createView(
+    target: { el: HTMLElement },
+    options: { signal: AbortSignal },
+  ): Promise<void> {
+    const widget = this.#widget;
+    if (!widget.render) {
+      return;
     }
-    return binding;
+    // `renderSignal` aborts when either the caller's view unmounts or
+    // the binding itself is destroyed.
+    const renderSignal = abortSignalAny([
+      options.signal,
+      this.#controller.signal,
+    ]);
+    if (renderSignal.aborted) {
+      return;
+    }
+    // Clear whatever a previous generation or render left behind.
+    target.el.innerHTML = "";
+    // 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),
+      ),
+      el: target.el,
+      experimental,
+      signal: renderSignal,
+      host,
+    });
+    if (isCleanup(renderCleanup)) {
+      const runCleanup = () => {
+        const reason = options.signal.aborted
+          ? "view unmount"
+          : "binding destroyed";
+        Logger.debug(
+          `[WidgetBinding] Render cleanup triggered (reason: ${reason})`,
+        );
+        return this.#trackCleanup(renderCleanup, "render");
+      };
+      if (renderSignal.aborted) {
+        await runCleanup();
+        return;
+      }
+      renderSignal.addEventListener("abort", () => void runCleanup(), {
+        once: true,
+      });
+    }
+    this.#replayState(registrations, renderSignal);
+  }
+
+  #trackCleanup(cleanup: Cleanup, reason: string): Promise<void> {
+    const task = safelyRunCleanup(cleanup, reason);
+    this.#cleanupTasks.add(task);
+    void task.finally(() => this.#cleanupTasks.delete(task));
+    return task;
   }
 
-  destroy(modelId: WidgetModelId): void {
-    const binding = this.#bindings.get(modelId);
-    if (binding) {
-      Logger.debug(`[BindingManager] Destroying binding for model=${modelId}`);
-      binding.destroy();
-      this.#bindings.delete(modelId);
+  /**
+   * 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);
+      }
     }
   }
 
-  has(modelId: WidgetModelId): boolean {
-    return this.#bindings.has(modelId);
+  /**
+   * Destroy this generation, running initialize/render cleanups and
+   * clearing listeners registered through its model proxies.
+   */
+  async destroy(): Promise<void> {
+    Logger.debug("[WidgetBinding] Destroying binding generation");
+    this.#controller.abort();
+    await Promise.allSettled(this.#viewTasks);
+    while (this.#cleanupTasks.size > 0) {
+      await Promise.all(this.#cleanupTasks);
+    }
   }
 }
 
 export const WIDGET_DEF_REGISTRY = new WidgetDefRegistry();
-export const BINDING_MANAGER = new BindingManager();
 
 export const visibleForTesting = {
   WidgetDefRegistry,
   WidgetBinding,
-  BindingManager,
 };

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

@@ -0,0 +1,29 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { isWidgetModelId, type WidgetModelId } from "./types";
+
+export const WIDGET_REF_PREFIX = "anywidget:";
+
+/**
+ * Parse a widget reference string into its model id.
+ *
+ * Per anywidget>=0.11, widget refs are serialized as
+ * `anywidget:<model_id>` strings embedded directly in widget state.
+ * `host.getWidget(ref)` consumes these strings.
+ *
+ * The legacy `IPY_MODEL_<id>` prefix used by ipywidgets'
+ * `widget_serialization` is intentionally NOT accepted here — widgets
+ * using that path resolve children manually via
+ * `model.widget_manager.get_model(id)` after stripping the prefix.
+ */
+export function parseWidgetRef(ref: unknown): WidgetModelId {
+  if (typeof ref === "string" && ref.startsWith(WIDGET_REF_PREFIX)) {
+    const modelId = ref.slice(WIDGET_REF_PREFIX.length);
+    if (isWidgetModelId(modelId)) {
+      return modelId;
+    }
+  }
+  throw new Error(
+    `[anywidget] Invalid widget reference: ${JSON.stringify(ref)}`,
+  );
+}