Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

13.2 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */
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 { modelProxy } from "./model-proxy";
import type { ModelState } from "./types";

export const experimental: Experimental = {
  invoke: async () => {
    const message =
      "anywidget.invoke not supported in marimo. Please file an issue at https://github.com/marimo-team/marimo/issues";
    Logger.warn(message);
    throw new Error(message);
  },
};

/**
 * 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
 * (jsdom) supports AbortSignal.any natively.
 */
function abortSignalAny(signals: AbortSignal[]): AbortSignal {
  if (typeof AbortSignal.any === "function") {
    return AbortSignal.any(signals);
  }
  const controller = new AbortController();
  for (const signal of signals) {
    if (signal.aborted) {
      controller.abort(signal.reason);
      return controller.signal;
    }
    signal.addEventListener("abort", () => controller.abort(signal.reason), {
      once: true,
    });
  }
  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, 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. 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, 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 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 {
    this.#cache.delete(jsHash);
  }

  async #doImport(
    jsUrl: string,
    opts: { kernelAuthored?: boolean } = {},
  ): 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 —
    // 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,
        )}`,
      );
    }
    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;
    }
  }
}

/**
 * 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;
  onDestroy?: () => void;
}

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() ran exactly once, in `create`
 * - render() runs once per view (zero or more per generation)
 */
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>>();
  #onDestroy?: () => void;

  private constructor(options: {
    widget: ResolvedWidget<T>;
    model: Model<T>;
    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;
  }

  /**
   * 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.
   */
  public static async create<T extends ModelState>({
    widgetDef,
    model,
    createHost,
    controller = new AbortController(),
    onDestroy,
  }: CreateWidgetBindingOptions<T>): Promise<WidgetBinding<T>> {
    const signal = controller.signal;
    let lateCleanup: Promise<void> | undefined;
    try {
      const widget: ResolvedWidget<T> =
        typeof widgetDef === "function" ? await widgetDef() : widgetDef;

      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 });
        }),
      ]);

      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;
      }

      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;
    }
  }

  /**
   * The object returned from `initialize`, or `undefined` if it
   * returned a cleanup function or nothing.
   */
  public get exports(): unknown {
    return this.#exports;
  }

  /**
   * 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.
   *
   * `render` reads current state via `model.get`; change listeners
   * observe only subsequent changes, matching Jupyter semantics.
   */
  public 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);
    }
  }

  async #createView(
    target: { el: HTMLElement },
    options: { signal: AbortSignal },
  ): Promise<void> {
    const widget = this.#widget;
    if (!widget.render) {
      return;
    }
    // `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 renderCleanup = await widget.render({
      model: modelProxy(this.#model, renderSignal),
      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,
      });
    }
  }

  #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 this generation, running initialize/render cleanups and
   * clearing listeners registered through its model proxies.
   */
  public 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);
    }
    this.#onDestroy?.();
    this.#onDestroy = undefined;
  }
}

export const WIDGET_DEF_REGISTRY = new WidgetDefRegistry();

export const visibleForTesting = {
  WidgetDefRegistry,
  WidgetBinding,
};