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.

8.8 KB
Raw Blame
/* Copyright 2026 Marimo. All rights reserved. */
import type { NotificationMessageData } from "@/core/kernel/messages";
import { getRequestClient } from "@/core/network/requests";
import type { ModelRequest } from "@/core/network/types";
import { isStaticNotebook } from "@/core/static/static-state";
import { assertNever } from "@/utils/assertNever";
import {
  type Base64String,
  base64ToDataView,
  dataViewToBase64,
} from "@/utils/json/base64";
import { Logger } from "@/utils/Logger";
import { repl } from "@/utils/repl";
import { Semaphore } from "@/utils/semaphore";
import { viewStateAtom } from "@/core/mode";
import { store } from "@/core/state/jotai";
import { createHost, type WidgetResolver } from "./host";
import { getMarimoInternal, type MarimoComm, Model } from "./model";
import { WidgetRuntime } from "./runtime";
import { decodeFromWire, serializeBuffersToBase64 } from "./serialization";
import {
  isWidgetModelId,
  type EsmSpec,
  type ModelState,
  type WidgetModelId,
} from "./types";

/**
 * Only edit sessions may swap widget code ("present" is an edit
 * session with different chrome); a viewer's widget code is immutable.
 */
function defaultIsEditMode(): boolean {
  const mode = store.get(viewStateAtom).mode;
  return mode === "edit" || mode === "present";
}

/**
 * Maps model ids to stable runtimes and routes callers through their
 * public behavior. Generation and view lifecycles stay inside each runtime.
 */
export class WidgetRegistry implements WidgetResolver {
  #runtimes = new Map<WidgetModelId, WidgetRuntime>();
  #timeout: number;
  #isEditMode: () => boolean;

  public constructor(
    timeout = 10_000,
    isEditMode: () => boolean = defaultIsEditMode,
  ) {
    this.#timeout = timeout;
    this.#isEditMode = isEditMode;
  }

  #getOrCreateRuntime(key: WidgetModelId): WidgetRuntime {
    let runtime = this.#runtimes.get(key);
    if (!runtime) {
      const nextRuntime = new WidgetRuntime(key, {
        timeout: this.#timeout,
        isEditMode: this.#isEditMode,
        createHost: (signal) => createHost(this, signal),
        onModelTimeout: () => {
          if (this.#runtimes.get(key) === nextRuntime) {
            nextRuntime.dispose();
            this.#runtimes.delete(key);
          }
        },
      });
      runtime = nextRuntime;
      this.#runtimes.set(key, runtime);
    }
    return runtime;
  }

  /**
   * Resolve the model for `key`, waiting for its `open` message if it
   * hasn't arrived yet. Rejects after the registry timeout so a ref to
   * a model that never opens fails loudly instead of hanging.
   */
  public getModel(key: WidgetModelId): Promise<Model<ModelState>> {
    return this.#getOrCreateRuntime(key).getModel();
  }

  /**
   * Get a model synchronously if it exists and has been resolved.
   * Returns undefined if the model doesn't exist or is still pending.
   */
  public getModelSync(key: WidgetModelId): Model<ModelState> | undefined {
    return this.#runtimes.get(key)?.getModelSync();
  }

  /**
   * Create a model with a managed lifecycle signal.
   * The signal is aborted when the entry is deleted.
   */
  public createModel(
    key: WidgetModelId,
    factory: (signal: AbortSignal) => Model<ModelState>,
  ): void {
    this.#getOrCreateRuntime(key).createModel(factory);
  }

  public setModel(key: WidgetModelId, model: Model<ModelState>): void {
    this.#getOrCreateRuntime(key).setModel(model);
  }

  /**
   * Record where this widget's code can be imported from and, in an
   * edit session, hot-swap a live generation whose code changed.
   *
   * Specs only come from kernel-authored notifications; model state
   * must never be treated as code (it is client-writable).
   */
  public setSpec(key: WidgetModelId, spec: EsmSpec): void {
    this.#getOrCreateRuntime(key).setSpec(spec);
  }

  public getWidget<T = unknown>(key: WidgetModelId) {
    return this.#getOrCreateRuntime(key).getWidget<T>();
  }

  public createView(options: {
    modelId: WidgetModelId;
    el: HTMLElement;
    signal: AbortSignal;
  }): Promise<void> {
    return this.#getOrCreateRuntime(options.modelId).createView(options);
  }

  /**
   * Tear down everything known about `key`: the model's lifecycle
   * signal and the current generation.
   */
  public delete(key: WidgetModelId): void {
    const runtime = this.#runtimes.get(key);
    if (!runtime) {
      return;
    }
    runtime.dispose();
    this.#runtimes.delete(key);
  }
}

export const WIDGET_REGISTRY = new WidgetRegistry();

// The legacy ipywidgets escape hatch (`model.widget_manager.get_model`)
// resolves through the registry; assigned here to keep Model free of
// registry knowledge.
Model._modelManager = WIDGET_REGISTRY;

/**
 * Handle an incoming model lifecycle notification from the backend.
 *
 * Messages are dispatched by method type:
 * - "open": Initialize a new model or update existing one with initial state
 * - "update": Update model state with new values
 * - "custom": Forward custom message to model listeners
 * - "close": Remove the model and its binding from the registry
 */
export async function handleWidgetMessage(
  registry: WidgetRegistry,
  notification: NotificationMessageData<"model-lifecycle">,
): Promise<void> {
  const modelId = notification.model_id;
  if (!isWidgetModelId(modelId)) {
    throw new Error(`[anywidget] Invalid model id: ${String(modelId)}`);
  }
  const msg = notification.message;

  // Decode base64 buffers to DataViews (present in open/update/custom messages)
  const base64Buffers: Base64String[] = "buffers" in msg ? msg.buffers : [];
  const buffers = base64Buffers.map(base64ToDataView);

  switch (msg.method) {
    case "open": {
      const { state, buffer_paths = [] } = msg;
      // Record the spec before resolving the model so a waiting
      // getWidget sees it.
      if (msg.esm_spec) {
        registry.setSpec(modelId, msg.esm_spec);
      }
      const stateWithBuffers = decodeFromWire({
        state,
        bufferPaths: buffer_paths,
        buffers,
      });

      // Check if a model already exists (created by the plugin using model_id reference)
      // If so, just update its state instead of creating a duplicate
      const existingModel = registry.getModelSync(modelId);
      if (existingModel) {
        getMarimoInternal(existingModel).updateAndEmitDiffs(stateWithBuffers);
        return;
      }

      registry.createModel(modelId, (signal) => {
        // Wait for the server to acknowledge queueing each message before
        // sending the next one, preserving order within this model.
        const sends = new Semaphore(1);
        const sendMessage = (request: ModelRequest): Promise<void> =>
          sends.run(async () => {
            if (signal.aborted) {
              Logger.debug(
                `[Model] ${request.message.method} suppressed for model=${modelId} (signal aborted)`,
              );
              return;
            }
            await getRequestClient().sendModelValue(request);
          });

        // In static exports there is no kernel, so comm calls are no-ops.
        const comm: MarimoComm<ModelState> = isStaticNotebook()
          ? {
              sendUpdate: async () => undefined,
              sendCustomMessage: async () => undefined,
            }
          : {
              async sendUpdate(changeData) {
                const { state, buffers, bufferPaths } =
                  serializeBuffersToBase64(changeData);
                await sendMessage({
                  modelId,
                  message: { method: "update", state, bufferPaths },
                  buffers,
                });
              },
              async sendCustomMessage(content, buffers) {
                await sendMessage({
                  modelId,
                  message: { method: "custom", content },
                  buffers: buffers.map(dataViewToBase64),
                });
              },
            };

        return new Model(stateWithBuffers, comm, signal);
      });
      return;
    }

    case "custom": {
      const model = await registry.getModel(modelId);
      // For custom messages, we need to reconstruct the custom-message shape
      getMarimoInternal(model).emitCustomMessage(
        { method: "custom", content: msg.content },
        buffers,
      );
      return;
    }

    case "close":
      registry.delete(modelId); // aborts the model's signal, destroys the binding
      return;

    case "update": {
      const { state, buffer_paths = [] } = msg;
      // A spec on an update is a hot reload (handled by setSpec).
      if (msg.esm_spec) {
        registry.setSpec(modelId, msg.esm_spec);
      }
      const stateWithBuffers = decodeFromWire({
        state,
        bufferPaths: buffer_paths,
        buffers,
      });
      const model = await registry.getModel(modelId);
      getMarimoInternal(model).updateAndEmitDiffs(stateWithBuffers);
      return;
    }

    default:
      assertNever(msg);
  }
}

repl(WIDGET_REGISTRY, "WIDGET_REGISTRY");