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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
fix: decouple anywidget model and view (#8124)
Myles Scolnick973eefcb4679
diff --git a/frontend/benchmarks/base64-conversion.bench.ts b/frontend/benchmarks/base64-conversion.bench.tsnew file mode 100644index 0000000000..20650249ff--- /dev/null+++ b/frontend/benchmarks/base64-conversion.bench.ts@@ -0,0 +1,60 @@+import { bench, describe } from "vitest";++// To run:+// pnpm vitest bench benchmarks/base64-conversion.bench.ts++// Helper to convert Uint8Array to base64+function uint8ArrayToBase64(bytes: Uint8Array): string {+ let binary = "";+ for (let i = 0; i < bytes.length; i++) {+ binary += String.fromCharCode(bytes[i]);+ }+ return window.btoa(binary);+}++// Slow implementation (using Uint8Array.from)+function base64ToUint8ArraySlow(bytes: string): Uint8Array {+ const binary = window.atob(bytes);+ return Uint8Array.from(binary, (c) => c.charCodeAt(0));+}++// Fast implementation (using manual loop)+function base64ToUint8ArrayFast(bytes: string): Uint8Array {+ const binary = window.atob(bytes);+ const len = binary.length;+ const uint8Array = new Uint8Array(len);+ for (let i = 0; i < len; i++) {+ uint8Array[i] = binary.charCodeAt(i);+ }+ return uint8Array;+}++// Test data setup+const sizes = {+ small: 1024, // 1KB+ medium: 10 * 1024, // 10KB+ large: 100 * 1024, // 100KB+ xlarge: 1024 * 1024, // 1MB+};++const testData: Record<string, string> = {};+for (const [name, size] of Object.entries(sizes)) {+ const data = new Uint8Array(size);+ for (let i = 0; i < size; i++) {+ data[i] = i % 256;+ }+ testData[name] = uint8ArrayToBase64(data);+}++// Benchmarks+describe("base64 to Uint8Array conversion", () => {+ for (const [name, base64] of Object.entries(testData)) {+ bench(`slow - ${name}`, () => {+ base64ToUint8ArraySlow(base64);+ });++ bench(`fast - ${name}`, () => {+ base64ToUint8ArrayFast(base64);+ });+ }+});diff --git a/frontend/benchmarks/uint8array-to-base64.bench.ts b/frontend/benchmarks/uint8array-to-base64.bench.tsnew file mode 100644index 0000000000..e0e6384b64--- /dev/null+++ b/frontend/benchmarks/uint8array-to-base64.bench.ts@@ -0,0 +1,50 @@+import { bench, describe } from "vitest";++// To run:+// pnpm vitest bench benchmarks/uint8array-to-base64.bench.ts++// Slow implementation (using Array.from with callback)+function uint8ArrayToBase64Slow(binary: Uint8Array): string {+ const chars = Array.from(binary, (byte) => String.fromCharCode(byte));+ return window.btoa(chars.join(""));+}++// Fast implementation (using manual loop)+function uint8ArrayToBase64Fast(binary: Uint8Array): string {+ let binaryString = "";+ const len = binary.length;+ for (let i = 0; i < len; i++) {+ binaryString += String.fromCharCode(binary[i]);+ }+ return window.btoa(binaryString);+}++// Test data setup+const sizes = {+ small: 1024, // 1KB+ medium: 10 * 1024, // 10KB+ large: 100 * 1024, // 100KB+ xlarge: 1024 * 1024, // 1MB+};++const testData: Record<string, Uint8Array> = {};+for (const [name, size] of Object.entries(sizes)) {+ const data = new Uint8Array(size);+ for (let i = 0; i < size; i++) {+ data[i] = i % 256;+ }+ testData[name] = data;+}++// Benchmarks+describe("Uint8Array to base64 conversion", () => {+ for (const [name, data] of Object.entries(testData)) {+ bench(`slow - ${name}`, () => {+ uint8ArrayToBase64Slow(data);+ });++ bench(`fast - ${name}`, () => {+ uint8ArrayToBase64Fast(data);+ });+ }+});diff --git a/frontend/src/core/islands/__tests__/bridge.test.ts b/frontend/src/core/islands/__tests__/bridge.test.tsindex d68e8b882d..3be122bad8 100644--- a/frontend/src/core/islands/__tests__/bridge.test.ts+++ b/frontend/src/core/islands/__tests__/bridge.test.ts@@ -192,9 +192,11 @@ describe("IslandsPyodideBridge", () => {const request = {modelId: "widget-1",message: {+ method: "update" as const,state: { value: 42 },bufferPaths: [],},+ buffers: [],};await bridge.sendModelValue(request);@@ -202,12 +204,14 @@ describe("IslandsPyodideBridge", () => {expect(mockBridge).toHaveBeenCalledWith({functionName: "put_control_request",payload: {- type: "update-widget-model",+ type: "model",modelId: "widget-1",message: {+ method: "update",state: { value: 42 },bufferPaths: [],},+ buffers: [],},});});@@ -226,7 +230,8 @@ describe("IslandsPyodideBridge", () => {await bridge.sendRun({ cellIds: [], codes: [] });await bridge.sendModelValue({modelId: "",- message: { state: {}, bufferPaths: [] },+ message: { method: "update", state: {}, bufferPaths: [] },+ buffers: [],});// All calls should have the type fielddiff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.tsindex dad7a2e579..feb9538d1f 100644--- a/frontend/src/core/islands/bridge.ts+++ b/frontend/src/core/islands/bridge.ts@@ -140,7 +140,7 @@ export class IslandsPyodideBridge implements RunRequests, EditRequests {sendModelValue: RunRequests["sendModelValue"] = async (request) => {await this.putControlRequest({- type: "update-widget-model",+ type: "model",...request,});return null;diff --git a/frontend/src/core/islands/main.ts b/frontend/src/core/islands/main.tsindex 866c52bad8..39a66793d8 100644--- a/frontend/src/core/islands/main.ts+++ b/frontend/src/core/islands/main.ts@@ -13,6 +13,10 @@ import "iconify-icon";import { toast } from "@/components/ui/use-toast";import { renderHTML } from "@/plugins/core/RenderHTML";+import {+ handleWidgetMessage,+ MODEL_MANAGER,+} from "@/plugins/impl/anywidget/model";import { initializePlugins } from "@/plugins/plugins";import { logNever } from "@/utils/assertNever";import { Functions } from "@/utils/functions";@@ -194,6 +198,9 @@ export async function initialize() {return;case "kernel-startup-error":return;+ case "model-lifecycle":+ handleWidgetMessage(MODEL_MANAGER, msg.data);+ return;default:logNever(msg.data);}diff --git a/frontend/src/core/network/types.ts b/frontend/src/core/network/types.tsindex 3afc580b92..02415698dc 100644--- a/frontend/src/core/network/types.ts+++ b/frontend/src/core/network/types.ts@@ -78,7 +78,7 @@ export interface SetCellConfigRequest {configs: Record<CellId, Partial<CellConfig>>;}export type UpdateUIElementRequest = schemas["UpdateUIElementRequest"];-export type UpdateWidgetModelRequest = schemas["UpdateWidgetModelRequest"];+export type ModelRequest = schemas["ModelRequest"];export type UpdateCellIdsRequest = schemas["UpdateCellIdsRequest"];export type UpdateUserConfigRequest = schemas["UpdateUserConfigRequest"];export type ShutdownSessionRequest = schemas["ShutdownSessionRequest"];@@ -110,7 +110,7 @@ export type LspServerHealth = schemas["LspServerHealth"];*/export interface RunRequests {sendComponentValues: (request: UpdateUIElementValuesRequest) => Promise<null>;- sendModelValue: (request: UpdateWidgetModelRequest) => Promise<null>;+ sendModelValue: (request: ModelRequest) => Promise<null>;sendInstantiate: (request: InstantiateNotebookRequest) => Promise<null>;sendFunctionRequest: (request: InvokeFunctionRequest) => Promise<null>;}diff --git a/frontend/src/core/wasm/bridge.ts b/frontend/src/core/wasm/bridge.tsindex b95e7874c4..ef7222dbf6 100644--- a/frontend/src/core/wasm/bridge.ts+++ b/frontend/src/core/wasm/bridge.ts@@ -541,7 +541,7 @@ export class PyodideBridge implements RunRequests, EditRequests {sendModelValue: RunRequests["sendModelValue"] = async (request) => {await this.putControlRequest({- type: "update-widget-model",+ type: "model",...request,});return null;diff --git a/frontend/src/core/websocket/useMarimoKernelConnection.tsx b/frontend/src/core/websocket/useMarimoKernelConnection.tsxindex a7e053d880..89e1dff101 100644--- a/frontend/src/core/websocket/useMarimoKernelConnection.tsx+++ b/frontend/src/core/websocket/useMarimoKernelConnection.tsx@@ -11,7 +11,6 @@ import { useConnectionTransport } from "@/core/websocket/useWebSocket";import { renderHTML } from "@/plugins/core/RenderHTML";import {handleWidgetMessage,- isMessageWidgetState,MODEL_MANAGER,} from "@/plugins/impl/anywidget/model";import { logNever } from "@/utils/assertNever";@@ -141,31 +140,22 @@ export function useMarimoKernelConnection(opts: {return;case "send-ui-element-message": {- const modelId = msg.data.model_id;const uiElement = msg.data.ui_element;- const message = msg.data.message;- const buffers = safeExtractSetUIElementMessageBuffers(msg.data);-- if (modelId && isMessageWidgetState(message)) {- handleWidgetMessage({- modelId,- msg: message,- buffers,- modelManager: MODEL_MANAGER,- });- }-if (uiElement) {+ const buffers = safeExtractSetUIElementMessageBuffers(msg.data);UI_ELEMENT_REGISTRY.broadcastMessage(uiElement as UIElementId,msg.data.message,buffers,);}-return;}+ case "model-lifecycle":+ handleWidgetMessage(MODEL_MANAGER, msg.data);+ return;+case "remove-ui-elements":handleRemoveUIElements(msg.data);return;diff --git a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsxindex d002699d00..13109736bf 100644--- a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx+++ b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx@@ -1,97 +1,50 @@/* Copyright 2026 Marimo. All rights reserved. *//* eslint-disable @typescript-eslint/no-explicit-any */-import type { AnyWidget, Experimental } from "@anywidget/types";-import { isEqual } from "lodash-es";-import { useEffect, useMemo, useRef } from "react";-import useEvent from "react-use-event-hook";+import type { AnyWidget } from "@anywidget/types";+import { useEffect, useRef } from "react";import { z } from "zod";-import { MarimoIncomingMessageEvent } from "@/core/dom/events";import { asRemoteURL } from "@/core/runtime/config";import { resolveVirtualFileURL } from "@/core/static/files";import { isStaticNotebook } from "@/core/static/static-state";import { useAsyncData } from "@/hooks/useAsyncData";-import { useDeepCompareMemoize } from "@/hooks/useDeepCompareMemoize";-import {- type HTMLElementNotDerivedFromRef,- useEventListener,-} from "@/hooks/useEventListener";+import type { HTMLElementNotDerivedFromRef } from "@/hooks/useEventListener";import { createPlugin } from "@/plugins/core/builder";-import { rpc } from "@/plugins/core/rpc";import type { IPluginProps } from "@/plugins/types";-import {- decodeFromWire,- isWireFormat,- serializeBuffersToBase64,- type WireFormat,-} from "@/utils/data-views";import { prettyError } from "@/utils/errors";-import type { Base64String } from "@/utils/json/base64";import { Logger } from "@/utils/Logger";import { ErrorBanner } from "../common/error-banner";-import { MODEL_MANAGER, Model } from "./model";+import { getMarimoInternal, MODEL_MANAGER, type Model } from "./model";+import type { ModelState, WidgetModelId } from "./types";+/**+ * AnyWidget asset data+ */interface Data {jsUrl: string;jsHash: string;css?: string | null;}-type T = Record<string, unknown>;--// eslint-disable-next-line @typescript-eslint/consistent-type-definitions-type PluginFunctions = {- send_to_widget: <T>(req: {- content: unknown;- buffers: Base64String[];- }) => Promise<null | undefined>;-};+type AnyWidgetState = ModelState;-export const AnyWidgetPlugin = createPlugin<WireFormat<T>>("marimo-anywidget")- .withData(- z.object({- jsUrl: z.string(),- jsHash: z.string(),- css: z.string().nullish(),- }),- )- .withFunctions<PluginFunctions>({- send_to_widget: rpc- .input(- z.object({- content: z.unknown(),- buffers: z.array(z.string().transform((v) => v as Base64String)),- }),- )- .output(z.null().optional()),- })- .renderer((props) => <AnyWidgetSlot {...props} />);--const AnyWidgetSlot = (- props: IPluginProps<WireFormat<T>, Data, PluginFunctions>,-) => {- const { css, jsUrl, jsHash } = props.data;+/**+ * Initial value is a model_id reference.+ * The backend sends just { model_id: string } and the frontend+ * retrieves the actual state from the 'open' message.+ */+interface ModelIdRef {+ model_id: WidgetModelId;+}- // Decode wire format { state, bufferPaths, buffers } to state with DataViews- const valueWithBuffers = useMemo(() => {- if (isWireFormat(props.value)) {- const decoded = decodeFromWire(props.value);- Logger.debug("AnyWidget decoded wire format:", {- bufferPaths: props.value.bufferPaths,- buffersCount: props.value.buffers?.length,- decodedKeys: Object.keys(decoded),- });- return decoded;- }- Logger.warn("AnyWidget value is not wire format:", props.value);- return props.value;- }, [props.value]);+export function useAnyWidgetModule(opts: { jsUrl: string; jsHash: string }) {+ const { jsUrl, jsHash } = opts;// JS is an ESM file with a render function on it// export function render({ model, el }) {// ...const {- data: module,+ data: jsModule,error,refetch,} = useAsyncData(async () => {@@ -117,9 +70,16 @@ const AnyWidgetSlot = (}}, [hasError, jsUrl]);+ return {+ jsModule,+ error,+ };+}++export function useMountCss(css: string | null | undefined, host: HTMLElement) {// Mount the CSSuseEffect(() => {- const shadowRoot = props.host.shadowRoot;+ const shadowRoot = host.shadowRoot;if (!css || !shadowRoot) {return;}@@ -156,23 +116,38 @@ const AnyWidgetSlot = (return () => {style.remove();};- }, [css, props.host]);+ }, [css, host]);+}- // Wrap setValue to serialize DataViews back to base64 before sending- // Structure matches ipywidgets protocol: { state, bufferPaths, buffers }- const wrappedSetValue = useEvent((partialValue: Partial<T>) =>- props.setValue(serializeBuffersToBase64(partialValue)),- );+export const AnyWidgetPlugin = createPlugin<ModelIdRef>("marimo-anywidget")+ .withData(+ z.object({+ jsUrl: z.string(),+ jsHash: z.string(),+ css: z.string().nullish(),+ }),+ )+ .withFunctions({})+ .renderer((props) => <AnyWidgetSlot {...props} />);++const AnyWidgetSlot = (props: IPluginProps<ModelIdRef, Data>) => {+ const { css, jsUrl, jsHash } = props.data;+ const { model_id: modelId } = props.value;+ const host = props.host as HTMLElementNotDerivedFromRef;++ const { jsModule, error } = useAnyWidgetModule({ jsUrl, jsHash });++ useMountCss(css, host);if (error) {return <ErrorBanner error={error} />;}- if (!module) {+ if (!jsModule) {return null;}- if (!isAnyWidgetModule(module)) {+ if (!isAnyWidgetModule(jsModule)) {const error = new Error(`Module at ${jsUrl} does not appear to be a valid anywidget`,);@@ -189,10 +164,8 @@ const AnyWidgetSlot = (// Plugins may be stateful and we cannot make assumptions that we won't be// so it is safer to just re-render.key={key}- {...props}- widget={module.default}- setValue={wrappedSetValue}- value={valueWithBuffers}+ widget={jsModule.default}+ modelId={modelId}/>);};@@ -200,125 +173,72 @@ const AnyWidgetSlot = (/*** Run the anywidget module*- * @param widgetDef - The anywidget definition- * @param model - The model to pass to the widget+ * Per AFM spec (anywidget.dev/en/afm):+ * - initialize() is called once per model lifetime+ * - render() is called once per view (can be multiple per model)*/-async function runAnyWidgetModule(- widgetDef: AnyWidget,+async function runAnyWidgetModule<T extends AnyWidgetState>(+ widgetDef: AnyWidget<T>,model: Model<T>,el: HTMLElement,-): Promise<() => void> {- const experimental: Experimental = {- invoke: async (_name, _msg, _options) => {- 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);- },- };+ signal: AbortSignal,+): Promise<void> {// Clear the element, in case the widget is re-renderingel.innerHTML = "";- const widget =- typeof widgetDef === "function" ? await widgetDef() : widgetDef;- await widget.initialize?.({ model, experimental });+try {- const unsub = await widget.render?.({ model, el, experimental });- return () => {- unsub?.();- };+ const render = await getMarimoInternal(model).resolveWidget(widgetDef);+ await render(el, signal);} catch (error) {Logger.error("Error rendering anywidget", error);el.classList.add("text-error");el.innerHTML = `Error rendering anywidget: ${prettyError(error)}`;- return () => {- // No-op- };}}function isAnyWidgetModule(mod: any): mod is { default: AnyWidget } {- return (- mod.default &&- (typeof mod.default === "function" ||- mod.default?.render ||- mod.default?.initialize)- );-}--export function getDirtyFields(value: T, initialValue: T): Set<keyof T> {- return new Set(- Object.keys(value).filter((key) => !isEqual(value[key], initialValue[key])),- );-}+ if (!mod.default) {+ return false;+ }-function hasModelId(message: unknown): message is { model_id: string } {return (- typeof message === "object" && message !== null && "model_id" in message+ typeof mod.default === "function" ||+ typeof mod.default?.render === "function" ||+ typeof mod.default?.initialize === "function");}-interface Props- extends Omit<IPluginProps<T, Data, PluginFunctions>, "setValue"> {- widget: AnyWidget;- value: T;- setValue: (value: Partial<T>) => void;+interface Props<T extends AnyWidgetState> {+ widget: AnyWidget<T>;+ modelId: WidgetModelId;}-const LoadedSlot = ({- value,- setValue,+const LoadedSlot = <T extends AnyWidgetState>({widget,- functions,- data,- host,-}: Props & { widget: AnyWidget }) => {+ modelId,+}: Props<T> & { widget: AnyWidget<T> }) => {const htmlRef = useRef<HTMLDivElement>(null);- // value is already decoded from wire format- const model = useRef<Model<T>>(- new Model(value, setValue, functions.send_to_widget, new Set()),- );+ // value is already decoded from wire format, may be null if waiting for open message+ const model = MODEL_MANAGER.getSync(modelId);- // Listen to incoming messages- useEventListener(- host as HTMLElementNotDerivedFromRef,- MarimoIncomingMessageEvent.TYPE,- (e) => {- const message = e.detail.message;- if (hasModelId(message)) {- MODEL_MANAGER.get(message.model_id).then((model) => {- model.receiveCustomMessage(message, e.detail.buffers);- });- } else {- model.current.receiveCustomMessage(message, e.detail.buffers);- }- },- );+ if (!model) {+ Logger.error("Model not found for modelId", modelId);+ }useEffect(() => {- if (!htmlRef.current) {+ if (!htmlRef.current || !model) {return;}- const unsubPromise = runAnyWidgetModule(- widget,- model.current,- htmlRef.current,- );- return () => {- unsubPromise.then((unsub) => unsub());- };- // We re-run the widget when the jsUrl changes, which means the cell+ const controller = new AbortController();+ runAnyWidgetModule(widget, model, htmlRef.current, controller.signal);+ return () => controller.abort();+ // We re-run the widget when the modelId changes, which means the cell// that created the Widget has been re-run.// We need to re-run the widget because it may contain initialization code// that could be reset by the new widget.// See example: https://github.com/marimo-team/marimo/issues/3962#issuecomment-2703184123- }, [widget, data.jsUrl]);-- // When the value changes, update the model- const valueMemo = useDeepCompareMemoize(value);- useEffect(() => {- model.current.updateAndEmitDiffs(valueMemo);- }, [valueMemo]);+ }, [widget, modelId, model]);return <div ref={htmlRef} />;};@@ -327,5 +247,4 @@ export const visibleForTesting = {LoadedSlot,runAnyWidgetModule,isAnyWidgetModule,- getDirtyFields,};diff --git a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsxindex 7436af9218..661117d0f4 100644--- a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx+++ b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx@@ -1,65 +1,17 @@/* Copyright 2026 Marimo. All rights reserved. */-import { act, render, waitFor } from "@testing-library/react";+import { render, waitFor } from "@testing-library/react";import { beforeEach, describe, expect, it, vi } from "vitest";import { TestUtils } from "@/__tests__/test-helpers";-import type { UIElementId } from "@/core/cells/ids";-import { MarimoIncomingMessageEvent } from "@/core/dom/events";-import { getDirtyFields, visibleForTesting } from "../AnyWidgetPlugin";-import { Model } from "../model";+import type { HTMLElementNotDerivedFromRef } from "@/hooks/useEventListener";+import { visibleForTesting } from "../AnyWidgetPlugin";+import { MODEL_MANAGER, Model } from "../model";+import type { WidgetModelId } from "../types";const { LoadedSlot } = visibleForTesting;-describe("getDirtyFields", () => {- it("should return empty set when values are equal", () => {- const value = { foo: "bar", baz: 123 };- const initialValue = { foo: "bar", baz: 123 };-- const result = getDirtyFields(value, initialValue);-- expect(result.size).toBe(0);- });-- it("should return keys of changed values", () => {- const value = { foo: "changed", baz: 123 };- const initialValue = { foo: "bar", baz: 123 };-- const result = getDirtyFields(value, initialValue);-- expect(result.size).toBe(1);- expect(result.has("foo")).toBe(true);- });-- it("should handle multiple changed values", () => {- const value = { foo: "changed", baz: 456, extra: "new" };- const initialValue = { foo: "bar", baz: 123, extra: "old" };-- const result = getDirtyFields(value, initialValue);-- expect(result.size).toBe(3);- expect(result.has("foo")).toBe(true);- expect(result.has("baz")).toBe(true);- expect(result.has("extra")).toBe(true);- });-- it("should handle nested objects correctly", () => {- const value = { foo: "bar", nested: { a: 1, b: 2 } };- const initialValue = { foo: "bar", nested: { a: 1, b: 3 } };-- const result = getDirtyFields(value, initialValue);-- expect(result.size).toBe(1);- expect(result.has("nested")).toBe(true);- });-- it("should handle subset of initial fields", () => {- const value = { foo: "bar", baz: 123 };- const initialValue = { foo: "bar", baz: 123, full: "value" };-- const result = getDirtyFields(value, initialValue);- expect(result.size).toBe(0);- });-});+// Helper to create typed model IDs for tests+const asModelId = (id: string): WidgetModelId => id as WidgetModelId;// Mock a minimal AnyWidget implementationconst mockWidget = {@@ -76,23 +28,32 @@ vi.mock("../AnyWidgetPlugin", async () => {});describe("LoadedSlot", () => {+ const modelId = asModelId("test-model-id");+ let mockModel: Model<{ count: number }>;+const mockProps = {- value: { count: 0 },- setValue: vi.fn(),widget: mockWidget,- functions: {- send_to_widget: vi.fn().mockResolvedValue(null),- },data: {jsUrl: "http://example.com/widget.js",jsHash: "abc123",- initialValue: { count: 0 },},- host: document.createElement("div"),+ host: document.createElement(+ "div",+ ) as unknown as HTMLElementNotDerivedFromRef,+ modelId: modelId,};beforeEach(() => {vi.clearAllMocks();+ // Create and register a mock model before each test+ mockModel = new Model(+ { count: 0 },+ {+ sendUpdate: vi.fn().mockResolvedValue(undefined),+ sendCustomMessage: vi.fn().mockResolvedValue(undefined),+ },+ );+ MODEL_MANAGER.set(modelId, mockModel);});it("should render a div with ref", () => {@@ -100,83 +61,36 @@ describe("LoadedSlot", () => {expect(container.querySelector("div")).not.toBeNull();});- it("should initialize model with merged values", () => {- const modelSpy = vi.spyOn(Model.prototype, "updateAndEmitDiffs");- render(<LoadedSlot {...mockProps} />);-- expect(modelSpy).toHaveBeenCalledExactlyOnceWith({ count: 0 });- });-- it("should update model when value prop changes", async () => {- const { rerender } = render(<LoadedSlot {...mockProps} />);- const modelSpy = vi.spyOn(Model.prototype, "updateAndEmitDiffs");-- // Update the value prop- rerender(<LoadedSlot {...mockProps} value={{ count: 5 }} />);-- // Model should be updated with the new value- expect(modelSpy).toHaveBeenCalledWith({ count: 5 });- });-- it("should listen for incoming messages", async () => {+ it("should call runAnyWidgetModule on initialization", async () => {render(<LoadedSlot {...mockProps} />);- // Send a mock message- const mockMessageEvent = MarimoIncomingMessageEvent.create({- detail: {- objectId: "test-id" as UIElementId,- message: {- method: "update",- state: { count: 10 },- buffer_paths: [],- },- buffers: [],- },- bubbles: false,- composed: true,- });- const updateAndEmitDiffsSpy = vi.spyOn(Model.prototype, "set");-- // Dispatch the event on the host element- act(() => {- mockProps.host.dispatchEvent(mockMessageEvent);- });-+ // Wait a renderawait waitFor(() => {- expect(updateAndEmitDiffsSpy).toHaveBeenCalledWith("count", 10);+ expect(mockWidget.render).toHaveBeenCalled();});});- it("should call runAnyWidgetModule on initialization", async () => {+ it("should re-run widget when widget prop changes", async () => {const { rerender } = render(<LoadedSlot {...mockProps} />);- // Wait a render+ // Wait for initial renderawait waitFor(() => {expect(mockWidget.render).toHaveBeenCalled();});- // Render without any prop changes- rerender(<LoadedSlot {...mockProps} />);- await TestUtils.nextTick();+ // Create a new widget mock+ const newMockWidget = {+ initialize: vi.fn(),+ render: vi.fn(),+ };- // Still only called once- expect(mockWidget.render).toHaveBeenCalledTimes(1);-- // Change the jsUrl- rerender(- <LoadedSlot- {...mockProps}- data={{- ...mockProps.data,- jsUrl: "http://example.com/widget-updated.js",- }}- />,- );+ // Change the widget+ rerender(<LoadedSlot {...mockProps} widget={newMockWidget} />);await TestUtils.nextTick();- // Wait a render+ // Wait for re-render with new widgetawait waitFor(() => {- expect(mockWidget.render).toHaveBeenCalledTimes(2);+ expect(newMockWidget.render).toHaveBeenCalled();});});});diff --git a/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts b/frontend/src/plugins/impl/anywidget/__tests__/model.test.tsindex 0bf8151532..d1ce49b1db 100644--- a/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts+++ b/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts@@ -9,35 +9,73 @@ import {vi,} from "vitest";import { TestUtils } from "@/__tests__/test-helpers";-import type { Base64String } from "@/utils/json/base64";import {- type AnyWidgetMessage,+ getMarimoInternal,handleWidgetMessage,Model,visibleForTesting,} from "../model";+import type { WidgetModelId } from "../types";const { ModelManager } = visibleForTesting;+// Helper to create typed model IDs for tests+const asModelId = (id: string): WidgetModelId => id as WidgetModelId;++// Mock the request client+const mockSendModelValue = vi.fn().mockResolvedValue(null);+vi.mock("@/core/network/requests", () => ({+ getRequestClient: () => ({+ sendModelValue: mockSendModelValue,+ }),+}));++// Helper to create a mock MarimoComm+function createMockComm<T>() {+ return {+ sendUpdate: vi.fn().mockResolvedValue(undefined),+ sendCustomMessage: vi.fn().mockResolvedValue(undefined),+ };+}+describe("Model", () => {let model: Model<{ foo: string; bar: number }>;- // eslint-disable-next-line @typescript-eslint/no-explicit-any- let onChange: (value: any) => void;- // eslint-disable-next-line @typescript-eslint/no-explicit-any- let sendToWidget: (req: {- content: unknown;- buffers: Base64String[];- }) => Promise<null | undefined>;+ let mockComm: ReturnType<typeof createMockComm<{ foo: string; bar: number }>>;beforeEach(() => {- onChange = vi.fn();- sendToWidget = vi.fn().mockResolvedValue(null);- model = new Model(- { foo: "test", bar: 123 },- onChange,- sendToWidget,- new Set(),- );+ mockComm = createMockComm();+ mockSendModelValue.mockClear();+ model = new Model({ foo: "test", bar: 123 }, mockComm);+ });++ describe("public API", () => {+ it("should only expose AFM-compliant interface", () => {+ // Get all enumerable own properties+ const ownProperties = Object.keys(model).sort();+ // Get prototype methods (excluding constructor)+ const prototypeMethods = Object.getOwnPropertyNames(+ Object.getPrototypeOf(model),+ )+ .filter((name) => name !== "constructor")+ .sort();++ // Snapshot the public API to catch accidental leaks of internal methods+ expect({ ownProperties, prototypeMethods }).toMatchInlineSnapshot(`+ {+ "ownProperties": [+ "widget_manager",+ ],+ "prototypeMethods": [+ "get",+ "off",+ "on",+ "save_changes",+ "send",+ "set",+ ],+ }+ `);+ });});describe("get/set", () => {@@ -70,7 +108,7 @@ describe("Model", () => {model.set("bar", 456);model.save_changes();- expect(onChange).toHaveBeenCalledWith({+ expect(mockComm.sendUpdate).toHaveBeenCalledWith({foo: "new value",bar: 456,});@@ -80,7 +118,7 @@ describe("Model", () => {model.set("foo", "new value");model.save_changes();- expect(onChange).toHaveBeenCalledWith({+ expect(mockComm.sendUpdate).toHaveBeenCalledWith({foo: "new value",});@@ -88,17 +126,17 @@ describe("Model", () => {model.save_changes();// After clearing, only the newly changed field is sent- expect(onChange).toHaveBeenCalledWith({+ expect(mockComm.sendUpdate).toHaveBeenCalledWith({bar: 456,});});- it("should not call onChange when no dirty fields", () => {+ it("should not call sendUpdate when no dirty fields", () => {model.set("foo", "new value");model.save_changes();- model.save_changes(); // Second save should not call onChange+ model.save_changes(); // Second save should not call sendUpdate- expect(onChange).toHaveBeenCalledTimes(1);+ expect(mockComm.sendUpdate).toHaveBeenCalledTimes(1);});});@@ -145,23 +183,28 @@ describe("Model", () => {describe("send", () => {it("should send message and handle callbacks", async () => {const callback = vi.fn();- model.send({ test: true }, callback);+ await model.send({ test: true }, callback);- expect(sendToWidget).toHaveBeenCalledWith({- content: {- state: { test: true },- bufferPaths: [],- },- buffers: [],- });- await TestUtils.nextTick(); // flush- expect(callback).toHaveBeenCalledWith(null);+ expect(mockComm.sendCustomMessage).toHaveBeenCalledWith(+ { test: true },+ [],+ );+ expect(callback).toHaveBeenCalled();+ });++ it("should convert buffers to DataViews", async () => {+ const buffer = new ArrayBuffer(8);+ await model.send({ test: true }, undefined, [buffer]);++ expect(mockComm.sendCustomMessage).toHaveBeenCalledWith({ test: true }, [+ expect.any(DataView),+ ]);});});describe("widget_manager", () => {- const childModelId = "test-id";- const childModel = new Model({ foo: "test" }, vi.fn(), vi.fn(), new Set());+ const childModelId = asModelId("test-id");+ const childModel = new Model({ foo: "test" }, createMockComm());const manager = new ModelManager(10);let previousModelManager = Model._modelManager;@@ -177,9 +220,9 @@ describe("Model", () => {});it("should throw error when accessing a model that is not registered", async () => {- await expect(model.widget_manager.get_model("random-id")).rejects.toThrow(- "Model not found for key: random-id",- );+ await expect(+ model.widget_manager.get_model(asModelId("random-id")),+ ).rejects.toThrow("Model not found for key: random-id");});it("should return the registered model", async () => {@@ -194,7 +237,7 @@ describe("Model", () => {const callback = vi.fn();model.on("change:foo", callback);- model.updateAndEmitDiffs({ foo: "test", bar: 456 });+ getMarimoInternal(model).updateAndEmitDiffs({ foo: "test", bar: 456 });expect(callback).not.toHaveBeenCalled(); // foo didn't changeexpect(model.get("bar")).toBe(456);});@@ -202,47 +245,33 @@ describe("Model", () => {it("should update and emit for deep changes", () => {const modelWithObject = new Model<{ foo: { nested: string } }>({ foo: { nested: "test" } },- onChange,- sendToWidget,- new Set(),+ createMockComm(),);const callback = vi.fn();modelWithObject.on("change:foo", callback);- modelWithObject.updateAndEmitDiffs({ foo: { nested: "changed" } });+ getMarimoInternal(modelWithObject).updateAndEmitDiffs({+ foo: { nested: "changed" },+ });expect(callback).toHaveBeenCalledTimes(1);});it("should emit change event for any changes", async () => {const callback = vi.fn();model.on("change", callback);- model.updateAndEmitDiffs({ foo: "changed", bar: 456 });+ getMarimoInternal(model).updateAndEmitDiffs({ foo: "changed", bar: 456 });await TestUtils.nextTick(); // flushexpect(callback).toHaveBeenCalledTimes(1);});});- describe("receiveCustomMessage", () => {- it("should handle update messages", () => {- model.receiveCustomMessage({- method: "update",- state: {- foo: "updated",- bar: 789,- },- buffer_paths: [],- });-- expect(model.get("foo")).toBe("updated");- expect(model.get("bar")).toBe(789);- });-+ describe("emitCustomMessage", () => {it("should handle custom messages", () => {const callback = vi.fn();model.on("msg:custom", callback);const content = { type: "test" };- model.receiveCustomMessage({+ getMarimoInternal(model).emitCustomMessage({method: "custom",content,});@@ -256,7 +285,7 @@ describe("Model", () => {const content = { type: "test" };const buffer = new DataView(new ArrayBuffer(8));- model.receiveCustomMessage(+ getMarimoInternal(model).emitCustomMessage({method: "custom",content,@@ -266,108 +295,85 @@ describe("Model", () => {expect(callback).toHaveBeenCalledWith(content, [buffer]);});-- it("should log error for invalid messages", () => {- const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {- // noop- });- model.receiveCustomMessage({ invalid: "message" });-- expect(consoleSpy).toHaveBeenCalledTimes(2);- });});});describe("ModelManager", () => {let modelManager = new ModelManager(50);- const handle = ({- modelId,- message,- buffers,- }: {- modelId: string;- message: AnyWidgetMessage;- buffers: readonly DataView[];- }) => {- return handleWidgetMessage({- modelId,- msg: message,- buffers,- modelManager,- });- };+ const testId = asModelId("test-id");beforeEach(() => {// Clear the model manager before each testmodelManager = new ModelManager(50);+ mockSendModelValue.mockClear();});it("should set and get models", async () => {- const model = new Model({ count: 0 }, vi.fn(), vi.fn(), new Set());- modelManager.set("test-id", model);- const retrievedModel = await modelManager.get("test-id");+ const model = new Model({ count: 0 }, createMockComm());+ modelManager.set(testId, model);+ const retrievedModel = await modelManager.get(testId);expect(retrievedModel).toBe(model);});it("should handle model not found", async () => {- await expect(modelManager.get("non-existent")).rejects.toThrow(+ await expect(modelManager.get(asModelId("non-existent"))).rejects.toThrow("Model not found for key: non-existent",);});it("should delete models", async () => {- const model = new Model({ count: 0 }, vi.fn(), vi.fn(), new Set());- modelManager.set("test-id", model);- modelManager.delete("test-id");- await expect(modelManager.get("test-id")).rejects.toThrow();+ const model = new Model({ count: 0 }, createMockComm());+ modelManager.set(testId, model);+ modelManager.delete(testId);+ await expect(modelManager.get(testId)).rejects.toThrow();});it("should handle widget messages", async () => {- const openMessage: AnyWidgetMessage = {- method: "open",- state: { count: 0 },- buffer_paths: [],- };-- await handle({ modelId: "test-id", message: openMessage, buffers: [] });- const model = await modelManager.get("test-id");+ await handleWidgetMessage(modelManager, {+ model_id: testId,+ message: {+ method: "open",+ state: { count: 0 },+ buffer_paths: [],+ buffers: [],+ },+ });+ const model = await modelManager.get(testId);expect(model.get("count")).toBe(0);- const updateMessage: AnyWidgetMessage = {- method: "update",- state: {- count: 1,+ await handleWidgetMessage(modelManager, {+ model_id: testId,+ message: {+ method: "update",+ state: { count: 1 },+ buffer_paths: [],+ buffers: [],},- buffer_paths: [],- };-- await handle({ modelId: "test-id", message: updateMessage, buffers: [] });+ });expect(model.get("count")).toBe(1);});it("should handle custom messages", async () => {- const model = new Model({ count: 0 }, vi.fn(), vi.fn(), new Set());+ const model = new Model({ count: 0 }, createMockComm());const callback = vi.fn();model.on("msg:custom", callback);- modelManager.set("test-id", model);+ modelManager.set(testId, model);- await handle({- modelId: "test-id",- message: { method: "custom", content: { count: 1 } },- buffers: [],+ await handleWidgetMessage(modelManager, {+ model_id: testId,+ message: { method: "custom", content: { count: 1 }, buffers: [] },});expect(callback).toHaveBeenCalledWith({ count: 1 }, []);});it("should handle close messages", async () => {- const model = new Model({ count: 0 }, vi.fn(), vi.fn(), new Set());- modelManager.set("test-id", model);+ const model = new Model({ count: 0 }, createMockComm());+ modelManager.set(testId, model);- await handle({- modelId: "test-id",+ await handleWidgetMessage(modelManager, {+ model_id: testId,message: { method: "close" },- buffers: [],});- await expect(modelManager.get("test-id")).rejects.toThrow();+ await expect(modelManager.get(testId)).rejects.toThrow();});});diff --git a/frontend/src/utils/__tests__/data-views.test.ts b/frontend/src/plugins/impl/anywidget/__tests__/serialization.test.tssimilarity index 79%rename from frontend/src/utils/__tests__/data-views.test.tsrename to frontend/src/plugins/impl/anywidget/__tests__/serialization.test.tsindex a592afae19..304d6dc252 100644--- a/frontend/src/utils/__tests__/data-views.test.ts+++ b/frontend/src/plugins/impl/anywidget/__tests__/serialization.test.ts@@ -1,12 +1,8 @@/* Copyright 2026 Marimo. All rights reserved. */import { describe, expect, it } from "vitest";-import {- decodeFromWire,- isWireFormat,- serializeBuffersToBase64,- type WireFormat,-} from "../data-views";-import type { Base64String } from "../json/base64";+import type { WireFormat } from "@/plugins/impl/anywidget/types";+import type { Base64String } from "../../../../utils/json/base64";+import { decodeFromWire, serializeBuffersToBase64 } from "../serialization";describe("decodeFromWire with DataViews", () => {it("should return the original state if bufferPaths.length === 0", () => {@@ -108,7 +104,7 @@ describe("Immutability Tests", () => {expect(input.array).toBe(input.array); // Array reference unchanged});- it("decodeFromWire (wire format) should not mutate input", () => {+ it("decodeFromWire (wire format) should decode base64 to DataView", () => {const encoder = new TextEncoder();const data = encoder.encode("Hello");const base64 = btoa(String.fromCharCode(...data)) as Base64String;@@ -119,19 +115,16 @@ describe("Immutability Tests", () => {buffers: [base64],};- const clone = structuredClone(input);-- decodeFromWire(input);-- // Check deep equality- expect(input).toEqual(clone);+ const result = decodeFromWire(input);- // Check references are unchanged- expect(input.state).toBe(input.state);- expect(input.state.nested).toBe(input.state.nested);+ // Result should have DataView instead of base64 string+ expect(result.text).toBeInstanceOf(DataView);+ // Other properties should be preserved+ expect(result.number).toBe(42);+ expect(result.nested).toEqual({ value: "test" });});- it("decodeFromWire (with DataViews) should not mutate input", () => {+ it("decodeFromWire (with DataViews) should insert buffers at paths", () => {const encoder = new TextEncoder();const dataView = new DataView(encoder.encode("data").buffer);@@ -143,21 +136,21 @@ describe("Immutability Tests", () => {const bufferPaths = [["data"]];const buffers = [dataView];- const input = { state, bufferPaths, buffers };- const clone = structuredClone(input);-- decodeFromWire(input);-- // Check deep equality- expect(input).toEqual(clone);-- // Check references are unchanged- expect(input.state.nested).toBe(state.nested);- expect(input.state.array).toBe(state.array);- expect(input.buffers?.[0]).toBe(dataView); // Buffer reference unchanged+ const result = decodeFromWire({+ state,+ bufferPaths,+ buffers,+ }) as typeof state & { data: DataView };++ // Result should have the DataView at the path+ expect(result.data).toBe(dataView);+ // Other properties should be preserved+ expect(result.placeholder).toBe("value");+ expect(result.nested).toEqual({ key: "test" });+ expect(result.array).toEqual([1, 2, 3]);});- it("decodeFromWire should return new object, not mutate", () => {+ it("decodeFromWire should insert buffers and return state", () => {const encoder = new TextEncoder();const dataView = new DataView(encoder.encode("data").buffer);@@ -165,16 +158,15 @@ describe("Immutability Tests", () => {const bufferPaths = [["c"]];const buffers = [dataView];- const result = decodeFromWire({ state, bufferPaths, buffers });-- // Result should be different reference- expect(result).not.toBe(state);-- // Input should not have new property- expect("c" in state).toBe(false);+ const result = decodeFromWire({+ state,+ bufferPaths,+ buffers,+ }) as typeof state & { c: DataView };// Result should have new propertyexpect("c" in result).toBe(true);+ expect(result.c).toBe(dataView);});it("serializeBuffersToBase64 should return new state object", () => {@@ -198,7 +190,7 @@ describe("Immutability Tests", () => {expect(typeof result.state.buffer).toBe("string");});- it("decodeFromWire with object input should not mutate state", () => {+ it("decodeFromWire with object input should insert buffers", () => {const encoder = new TextEncoder();const dataView = new DataView(encoder.encode("data").buffer);@@ -206,16 +198,17 @@ describe("Immutability Tests", () => {const bufferPaths = [["d"]];const buffers = [dataView];- const input = { state, bufferPaths, buffers };- const clone = structuredClone(input);-- decodeFromWire(input);-- // Check deep equality- expect(input).toEqual(clone);-- // Check references are unchanged- expect(input.state.b).toBe(state.b);+ const result = decodeFromWire({+ state,+ bufferPaths,+ buffers,+ }) as typeof state & { d: DataView };++ // Result should have the buffer inserted+ expect(result.d).toBe(dataView);+ // Original properties should be preserved+ expect(result.a).toBe(1);+ expect(result.b).toEqual({ c: 2 });});it("nested objects should maintain independence after serialization", () => {@@ -342,53 +335,6 @@ describe("serializeBuffersToBase64", () => {});});-describe("isWireFormat", () => {- it("should return true for valid wire format", () => {- const wireFormat: WireFormat = {- state: { a: 1 },- bufferPaths: [],- buffers: [],- };- expect(isWireFormat(wireFormat)).toBe(true);- });-- it("should return true for wire format with data", () => {- const wireFormat: WireFormat = {- state: { value: "SGVsbG8=" },- bufferPaths: [["value"]],- buffers: ["SGVsbG8=" as Base64String],- };- expect(isWireFormat(wireFormat)).toBe(true);- });-- it("should return false for null", () => {- expect(isWireFormat(null)).toBe(false);- });-- it("should return false for non-objects", () => {- expect(isWireFormat("string")).toBe(false);- expect(isWireFormat(123)).toBe(false);- expect(isWireFormat(true)).toBe(false);- expect(isWireFormat(undefined)).toBe(false);- });-- it("should return false when missing state", () => {- expect(isWireFormat({ bufferPaths: [], buffers: [] })).toBe(false);- });-- it("should return false when missing bufferPaths", () => {- expect(isWireFormat({ state: {}, buffers: [] })).toBe(false);- });-- it("should return false when missing buffers", () => {- expect(isWireFormat({ state: {}, bufferPaths: [] })).toBe(false);- });-- it("should return false for plain objects", () => {- expect(isWireFormat({ a: 1, b: 2 })).toBe(false);- });-});-describe("decodeFromWire from WireFormat", () => {it("should return state unchanged when no buffer paths", () => {const wire: WireFormat = {diff --git a/frontend/src/plugins/impl/anywidget/model.ts b/frontend/src/plugins/impl/anywidget/model.tsindex feb7b6fce4..a3e75a4458 100644--- a/frontend/src/plugins/impl/anywidget/model.ts+++ b/frontend/src/plugins/impl/anywidget/model.ts@@ -1,35 +1,49 @@/* Copyright 2026 Marimo. All rights reserved. *//* eslint-disable @typescript-eslint/no-explicit-any */-import type { AnyModel } from "@anywidget/types";+import type { AnyModel, AnyWidget, Experimental } from "@anywidget/types";import { debounce } from "lodash-es";-import { z } from "zod";+import type { NotificationMessageData } from "@/core/kernel/messages";import { getRequestClient } from "@/core/network/requests";+import {+ decodeFromWire,+ serializeBuffersToBase64,+} from "@/plugins/impl/anywidget/serialization";import { assertNever } from "@/utils/assertNever";import { Deferred } from "@/utils/Deferred";-import { decodeFromWire, serializeBuffersToBase64 } from "@/utils/data-views";-import { throwNotImplemented } from "@/utils/functions";-import type { Base64String } from "@/utils/json/base64";+import {+ type Base64String,+ base64ToDataView,+ dataViewToBase64,+} from "@/utils/json/base64";import { Logger } from "@/utils/Logger";--export type EventHandler = (...args: any[]) => void;+import { repl } from "@/utils/repl";+import type { AnyWidgetMessage } from "./schemas";+import type { EventHandler, ModelState, WidgetModelId } from "./types";class ModelManager {- private models = new Map<string, Deferred<Model<any>>>();- private timeout: number;+ /**+ * Map of model ids to deferred promises+ */+ #models = new Map<WidgetModelId, Deferred<Model<ModelState>>>();+ /**+ * Timeout for model lookup+ */+ #timeout: number;+constructor(timeout = 10_000) {- this.timeout = timeout;+ this.#timeout = timeout;}- get(key: string): Promise<Model<any>> {- let deferred = this.models.get(key);+ get(key: WidgetModelId): Promise<Model<any>> {+ let deferred = this.#models.get(key);if (deferred) {return deferred.promise;}// If the model is not yet created, create the new deferred promise without resolving it- deferred = new Deferred<Model<any>>();- this.models.set(key, deferred);+ deferred = new Deferred<Model<ModelState>>();+ this.#models.set(key, deferred);// Add timeout to prevent hangingsetTimeout(() => {@@ -39,90 +53,216 @@ class ModelManager {}deferred.reject(new Error(`Model not found for key: ${key}`));- this.models.delete(key);- }, this.timeout);+ this.#models.delete(key);+ }, this.#timeout);return deferred.promise;}- set(key: string, model: Model<any>): void {- let deferred = this.models.get(key);+ set(key: WidgetModelId, model: Model<any>): void {+ let deferred = this.#models.get(key);if (!deferred) {- deferred = new Deferred<Model<any>>();- this.models.set(key, deferred);+ deferred = new Deferred<Model<ModelState>>();+ this.#models.set(key, deferred);}deferred.resolve(model);}- delete(key: string): void {- this.models.delete(key);+ /**+ * Check if a model exists and has been resolved (not pending).+ * This is useful for checking if a model was already created by the plugin+ * before the 'open' message arrives.+ */+ has(key: WidgetModelId): boolean {+ const deferred = this.#models.get(key);+ return deferred !== undefined && deferred.status === "resolved";+ }++ /**+ * Get a model synchronously if it exists and has been resolved.+ * Returns undefined if the model doesn't exist or is still pending.+ */+ getSync(key: WidgetModelId): Model<any> | undefined {+ const deferred = this.#models.get(key);+ if (deferred && deferred.status === "resolved") {+ return deferred.value;+ }+ return undefined;}++ delete(key: WidgetModelId): void {+ this.#models.delete(key);+ }+}++interface MarimoComm<T> {+ sendUpdate: (value: Partial<T>) => Promise<void>;+ sendCustomMessage: (content: unknown, buffers: DataView[]) => Promise<void>;+}++const marimoSymbol = Symbol("marimo");++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);+ },+};++type RenderFn = (el: HTMLElement, signal: AbortSignal) => Promise<void>;++interface MarimoInternalApi<T extends ModelState> {+ /**+ * Resolve the widget definition and initialize if needed.+ * Returns a render function that can be called for each view.+ *+ * Per AFM spec:+ * - widgetDef() is called once per model+ * - initialize() is called once per model+ * - render() (the returned function) is called once per view+ */+ resolveWidget: (widgetDef: AnyWidget<T>) => Promise<RenderFn>;+ /**+ * Update model state and emit change events for any differences.+ */+ updateAndEmitDiffs: (value: T) => void;+ /**+ * Emit a custom message to listeners.+ */+ emitCustomMessage: (+ message: Extract<AnyWidgetMessage, { method: "custom" }>,+ buffers?: readonly DataView[],+ ) => void;+ /**+ * Destroy the model, triggering initialize cleanup.+ */+ destroy: () => void;+}++/**+ * Get the internal marimo API for a Model instance.+ * These are not part of the public AnyModel interface.+ */+export function getMarimoInternal<T extends ModelState>(+ model: Model<T>,+): MarimoInternalApi<T> {+ return model[marimoSymbol];}export const MODEL_MANAGER = new ModelManager();-export class Model<T extends Record<string, any>> implements AnyModel<T> {- private ANY_CHANGE_EVENT = "change";- private dirtyFields: Map<keyof T, unknown>;- public static _modelManager: ModelManager = MODEL_MANAGER;- private data: T;- private onChange: (value: Partial<T>) => void;- private sendToWidget: (req: {- content: unknown;- buffers: Base64String[];- }) => Promise<null | undefined>;-- constructor(- data: T,- onChange: (value: Partial<T>) => void,- sendToWidget: (req: {- content: unknown;- buffers: Base64String[];- }) => Promise<null | undefined>,- initialDirtyFields: Set<keyof T>,- ) {- this.data = data;- this.onChange = onChange;- this.sendToWidget = sendToWidget;- this.dirtyFields = new Map(- [...initialDirtyFields].map((key) => [key, this.data[key]]),- );+export class Model<T extends ModelState> implements AnyModel<T> {+ #ANY_CHANGE_EVENT = "change";+ #dirtyFields: Map<keyof T, unknown>;+ #data: T;+ #comm: MarimoComm<T>;+ #listeners: Record<string, Set<EventHandler> | undefined> = {};+ #controller = new AbortController();+ #widgetDef: AnyWidget<T> | undefined;+ #render:+ | ((el: HTMLElement, signal: AbortSignal) => Promise<void>)+ | undefined;++ static _modelManager: ModelManager = MODEL_MANAGER;++ constructor(data: T, comm: MarimoComm<T>) {+ this.#data = data;+ this.#comm = comm;+ this.#dirtyFields = new Map();}- private listeners: Record<string, Set<EventHandler>> = {};+ /**+ * Internal marimo API - not part of AnyWidget AFM.+ * Access via getMarimoInternal().+ */+ [marimoSymbol]: MarimoInternalApi<T> = {+ updateAndEmitDiffs: (value: T) => this.#updateAndEmitDiffs(value),+ emitCustomMessage: (+ message: Extract<AnyWidgetMessage, { method: "custom" }>,+ buffers?: readonly DataView[],+ ) => this.#emitCustomMessage(message, buffers),+ resolveWidget: async (widgetDef: AnyWidget<T>): Promise<RenderFn> => {+ // Already initialized with the same widget - return cached render+ if (this.#render && this.#widgetDef === widgetDef) {+ return this.#render;+ }++ // If widgetDef changed (hot reload), destroy old and re-initialize+ if (this.#render && this.#widgetDef !== widgetDef) {+ this.#controller.abort();+ this.#controller = new AbortController();+ this.#render = undefined;+ }++ this.#widgetDef = widgetDef;++ // Resolve the widget definition (call if it's a function)+ const widget =+ typeof widgetDef === "function" ? await widgetDef() : widgetDef;++ // Call initialize once per model+ const cleanup = await widget.initialize?.({ model: this, experimental });+ if (cleanup) {+ this.#controller.signal.addEventListener("abort", cleanup);+ }++ // Store and return the render closure+ this.#render = async (el: HTMLElement, signal: AbortSignal) => {+ const renderCleanup = await widget.render?.({+ model: this,+ el,+ experimental,+ });+ if (renderCleanup) {+ // Cleanup when either the view unmounts or the model is destroyed+ AbortSignal.any([signal, this.#controller.signal]).addEventListener(+ "abort",+ renderCleanup,+ );+ }+ };++ return this.#render;+ },+ destroy: () => {+ this.#controller.abort();+ },+ };off(eventName?: string | null, callback?: EventHandler | null): void {if (!eventName) {- this.listeners = {};+ this.#listeners = {};return;}if (!callback) {- this.listeners[eventName] = new Set();+ this.#listeners[eventName] = new Set();return;}- this.listeners[eventName]?.delete(callback);+ this.#listeners[eventName]?.delete(callback);}send(content: any,callbacks?: any,- _buffers?: ArrayBuffer[] | ArrayBufferView[],- ): void {- const { state, bufferPaths, buffers } = serializeBuffersToBase64(content);- this.sendToWidget({- content: {- state: state,- bufferPaths: bufferPaths,- },- buffers: buffers,- }).then(callbacks);+ buffers?: ArrayBuffer[] | ArrayBufferView[],+ ): Promise<void> {+ const dataViews = (buffers ?? []).map((buf) =>+ buf instanceof ArrayBuffer+ ? new DataView(buf)+ : new DataView(buf.buffer, buf.byteOffset, buf.byteLength),+ );+ return this.#comm+ .sendCustomMessage(content, dataViews)+ .then(() => callbacks?.());}widget_manager = {- async get_model<TT extends Record<string, any>>(- model_id: string,+ async get_model<TT extends ModelState>(+ model_id: WidgetModelId,): Promise<AnyModel<TT>> {const model = await Model._modelManager.get(model_id);if (!model) {@@ -135,31 +275,52 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {};get<K extends keyof T>(key: K): T[K] {- return this.data[key];+ return this.#data[key];}set<K extends keyof T>(key: K, value: T[K]): void {- this.data = { ...this.data, [key]: value };- this.dirtyFields.set(key, value);- this.emit(`change:${key as K & string}`, value);- this.emitAnyChange();+ this.#data = { ...this.#data, [key]: value };+ this.#dirtyFields.set(key, value);+ this.#emit(`change:${key as K & string}`, value);+ this.#emitAnyChange();}save_changes(): void {- if (this.dirtyFields.size === 0) {+ if (this.#dirtyFields.size === 0) {return;}// Only send the dirty fields, not the entire state.const partialData = Object.fromEntries(- this.dirtyFields.entries(),+ this.#dirtyFields.entries(),) as Partial<T>;// Clear the dirty fields to avoid sending again.- this.dirtyFields.clear();- this.onChange(partialData);+ this.#dirtyFields.clear();+ this.#comm.sendUpdate(partialData);}- updateAndEmitDiffs(value: T): void {+ on(eventName: string, callback: EventHandler): void {+ if (!this.#listeners[eventName]) {+ this.#listeners[eventName] = new Set();+ }+ this.#listeners[eventName].add(callback);+ }++ #emit<K extends keyof T>(event: `change:${K & string}`, value: T[K]) {+ if (!this.#listeners[event]) {+ return;+ }+ const listeners = this.#listeners[event];+ for (const listener of listeners) {+ try {+ listener(value);+ } catch (error) {+ Logger.error("Error emitting event", error);+ }+ }+ }++ #updateAndEmitDiffs(value: T) {if (value == null) {return;}@@ -167,7 +328,7 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {Object.keys(value).forEach((key) => {const k = key as keyof T;// Shallow equal since these can be large objects- if (this.data[k] !== value[k]) {+ if (this.#data[k] !== value[k]) {this.set(k, value[k]);}});@@ -177,175 +338,139 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {* When receiving a message from the backend.* We want to notify all listeners with `msg:custom`*/- receiveCustomMessage(- message: unknown,+ #emitCustomMessage(+ message: Extract<AnyWidgetMessage, { method: "custom" }>,buffers: readonly DataView[] = [],- ): void {- const response = AnyWidgetMessageSchema.safeParse(message);- if (response.success) {- const data = response.data;- switch (data.method) {- case "update":- this.updateAndEmitDiffs(- decodeFromWire<T>({- state: data.state as T,- bufferPaths: data.buffer_paths ?? [],- buffers,- }),- );- break;- case "custom":- this.listeners["msg:custom"]?.forEach((cb) =>- cb(data.content, buffers),- );- break;- case "open":- this.updateAndEmitDiffs(- decodeFromWire<T>({- state: data.state as T,- bufferPaths: data.buffer_paths ?? [],- buffers,- }),- );- break;- case "echo_update":- // We don't need to do anything with this message- break;- default:- Logger.error("[anywidget] Unknown message method", data.method);- break;- }- } else {- Logger.error("Failed to parse message", response.error);- Logger.error("Message", message);+ ) {+ const listeners = this.#listeners["msg:custom"];+ if (!listeners) {+ return;}- }-- on(eventName: string, callback: EventHandler): void {- if (!this.listeners[eventName]) {- this.listeners[eventName] = new Set();+ for (const listener of listeners) {+ try {+ listener(message.content, buffers);+ } catch (error) {+ Logger.error("Error emitting event", error);+ }}- this.listeners[eventName].add(callback);}- private emit<K extends keyof T>(event: `change:${K & string}`, value: T[K]) {- if (!this.listeners[event]) {+ // Debounce 0 to send off one request in a single frame+ #emitAnyChange = debounce(() => {+ const listeners = this.#listeners[this.#ANY_CHANGE_EVENT];+ if (!listeners) {return;}- this.listeners[event].forEach((cb) => cb(value));- }-- // Debounce 0 to send off one request in a single frame- private emitAnyChange = debounce(() => {- this.listeners[this.ANY_CHANGE_EVENT]?.forEach((cb) => cb());+ for (const listener of listeners) {+ try {+ listener();+ } catch (error) {+ Logger.error("Error emitting event", error);+ }+ }}, 0);}-const BufferPathSchema = z.array(z.array(z.union([z.string(), z.number()])));-const StateSchema = z.record(z.string(), z.any());--const AnyWidgetMessageSchema = z.discriminatedUnion("method", [- z.object({- method: z.literal("open"),- state: StateSchema,- buffer_paths: BufferPathSchema.optional(),- }),- z.object({- method: z.literal("update"),- state: StateSchema,- buffer_paths: BufferPathSchema.optional(),- }),- z.object({- method: z.literal("custom"),- content: z.any(),- }),- z.object({- method: z.literal("echo_update"),- buffer_paths: BufferPathSchema,- state: StateSchema,- }),- z.object({- method: z.literal("close"),- }),-]);--export type AnyWidgetMessage = z.infer<typeof AnyWidgetMessageSchema>;--export function isMessageWidgetState(msg: unknown): msg is AnyWidgetMessage {- if (msg == null) {- return false;- }+/**+ * 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 model from manager+ */+export async function handleWidgetMessage(+ modelManager: ModelManager,+ notification: NotificationMessageData<"model-lifecycle">,+): Promise<void> {+ const modelId = notification.model_id as WidgetModelId;+ const msg = notification.message;++ Logger.debug("AnyWidget message", msg);++ // Decode base64 buffers to DataViews (present in open/update/custom messages)+ const base64Buffers: Base64String[] =+ "buffers" in msg ? (msg.buffers as Base64String[]) : [];+ const buffers = base64Buffers.map(base64ToDataView);++ switch (msg.method) {+ case "open": {+ const { state, buffer_paths = [] } = msg;+ const stateWithBuffers = decodeFromWire({+ state,+ bufferPaths: buffer_paths,+ buffers,+ });- return AnyWidgetMessageSchema.safeParse(msg).success;-}+ // 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 = modelManager.getSync(modelId);+ if (existingModel) {+ getMarimoInternal(existingModel).updateAndEmitDiffs(stateWithBuffers);+ return;+ }-export async function handleWidgetMessage({- modelId,- msg,- buffers,- modelManager,-}: {- modelId: string;- msg: AnyWidgetMessage;- buffers: readonly DataView[];- modelManager: ModelManager;-}): Promise<void> {- if (msg.method === "echo_update") {- // We don't need to do anything with this message- return;- }+ const model = new Model(stateWithBuffers, {+ async sendUpdate(changeData) {+ const { state, buffers, bufferPaths } =+ serializeBuffersToBase64(changeData);+ await getRequestClient().sendModelValue({+ modelId,+ message: { method: "update", state, bufferPaths },+ buffers,+ });+ },+ async sendCustomMessage(content, buffers) {+ await getRequestClient().sendModelValue({+ modelId,+ message: { method: "custom", content },+ buffers: buffers.map(dataViewToBase64),+ });+ },+ });+ modelManager.set(modelId, model);+ return;+ }- if (msg.method === "custom") {- const model = await modelManager.get(modelId);- model.receiveCustomMessage(msg, buffers);- return;- }+ case "custom": {+ const model = await modelManager.get(modelId);+ // For custom messages, we need to reconstruct the AnyWidgetMessage format+ getMarimoInternal(model).emitCustomMessage(+ { method: "custom", content: msg.content },+ buffers,+ );+ return;+ }- if (msg.method === "close") {- modelManager.delete(modelId);- return;- }+ case "close": {+ const model = modelManager.getSync(modelId);+ if (model) {+ getMarimoInternal(model).destroy();+ }+ modelManager.delete(modelId);+ return;+ }- const { method, state, buffer_paths = [] } = msg;- const stateWithBuffers = decodeFromWire({- state,- bufferPaths: buffer_paths,- buffers,- });-- if (method === "open") {- const handleDataChange = (changeData: Record<string, any>) => {- const { state, buffers, bufferPaths } =- serializeBuffersToBase64(changeData);- getRequestClient().sendModelValue({- modelId: modelId,- message: {- state,- bufferPaths,- },+ case "update": {+ const { state, buffer_paths = [] } = msg;+ const stateWithBuffers = decodeFromWire({+ state,+ bufferPaths: buffer_paths,buffers,});- };-- const model = new Model(- stateWithBuffers,- handleDataChange,- throwNotImplemented,- new Set(),- );- modelManager.set(modelId, model);- return;- }+ const model = await modelManager.get(modelId);+ getMarimoInternal(model).updateAndEmitDiffs(stateWithBuffers);+ return;+ }- if (method === "update") {- const model = await modelManager.get(modelId);- model.updateAndEmitDiffs(stateWithBuffers);- return;+ default:+ assertNever(msg);}-- assertNever(method);}+repl(MODEL_MANAGER, "MODEL_MANAGER");+export const visibleForTesting = {ModelManager,};diff --git a/frontend/src/plugins/impl/anywidget/schemas.ts b/frontend/src/plugins/impl/anywidget/schemas.tsnew file mode 100644index 0000000000..cefbb4ea2a--- /dev/null+++ b/frontend/src/plugins/impl/anywidget/schemas.ts@@ -0,0 +1,32 @@+/* Copyright 2026 Marimo. All rights reserved. */+import { z } from "zod";++const BufferPathSchema = z.array(z.array(z.union([z.string(), z.number()])));+const StateSchema = z.record(z.string(), z.any());++export const AnyWidgetMessageSchema = z.discriminatedUnion("method", [+ z.object({+ method: z.literal("open"),+ state: StateSchema,+ buffer_paths: BufferPathSchema.optional(),+ }),+ z.object({+ method: z.literal("update"),+ state: StateSchema,+ buffer_paths: BufferPathSchema.optional(),+ }),+ z.object({+ method: z.literal("custom"),+ content: z.any(),+ }),+ z.object({+ method: z.literal("echo_update"),+ buffer_paths: BufferPathSchema,+ state: StateSchema,+ }),+ z.object({+ method: z.literal("close"),+ }),+]);++export type AnyWidgetMessage = z.infer<typeof AnyWidgetMessageSchema>;diff --git a/frontend/src/utils/data-views.ts b/frontend/src/plugins/impl/anywidget/serialization.tssimilarity index 75%rename from frontend/src/utils/data-views.tsrename to frontend/src/plugins/impl/anywidget/serialization.tsindex 2a29133d2d..1c752cb294 100644--- a/frontend/src/utils/data-views.ts+++ b/frontend/src/plugins/impl/anywidget/serialization.ts@@ -1,23 +1,23 @@/* Copyright 2026 Marimo. All rights reserved. */import { get, set } from "lodash-es";-import { invariant } from "./invariant";+import { invariant } from "../../../utils/invariant";import {type Base64String,base64ToDataView,dataViewToBase64,-} from "./json/base64";-import { Logger } from "./Logger";+} from "../../../utils/json/base64";+import { Logger } from "../../../utils/Logger";+import type { WireFormat } from "./types";++type Path = (string | number)[];/*** Recursively find all DataViews in an object and return their paths.** This mirrors ipywidgets' _separate_buffers logic.*/-function findDataViewPaths(- obj: unknown,- currentPath: (string | number)[] = [],-): (string | number)[][] {- const paths: (string | number)[][] = [];+function findDataViewPaths(obj: unknown, currentPath: Path = []): Path[] {+ const paths: Path[] = [];if (obj instanceof DataView) {paths.push(currentPath);@@ -51,7 +51,7 @@ export function serializeBuffersToBase64<T extends Record<string, unknown>>(const state = structuredClone(inputObject);const buffers: Base64String[] = [];- const bufferPaths: (string | number)[][] = [];+ const bufferPaths: Path[] = [];for (const bufferPath of dataViewPaths) {const dataView = get(inputObject, bufferPath);@@ -66,31 +66,6 @@ export function serializeBuffersToBase64<T extends Record<string, unknown>>(return { state, buffers, bufferPaths };}-/**- * Wire format for anywidget state with binary data.- * Buffers can be either base64 strings (from network) or DataViews (in-memory).- */-export interface WireFormat<T = Record<string, unknown>> {- state: T;- bufferPaths: (string | number)[][];- buffers: Base64String[];-}--/**- * Check if an object is in wire format.- */-export function isWireFormat<T = Record<string, unknown>>(- obj: unknown,-): obj is WireFormat<T> {- return (- obj !== null &&- typeof obj === "object" &&- "state" in obj &&- "bufferPaths" in obj &&- "buffers" in obj- );-}-/*** Decode wire format or insert DataViews at specified paths.*@@ -103,7 +78,7 @@ export function isWireFormat<T = Record<string, unknown>>(*/export function decodeFromWire<T extends Record<string, unknown>>(input: {state: T;- bufferPaths?: (string | number)[][];+ bufferPaths?: Path[];buffers?: readonly (DataView | Base64String)[];}): T {const { state, bufferPaths, buffers } = input;@@ -121,7 +96,9 @@ export function decodeFromWire<T extends Record<string, unknown>>(input: {);}- const out = structuredClone(state);+ // We should avoid using structuredClone if possible since+ // it can be very slow. If mutability is a concern, we should use a different approach.+ const out = state;for (const [i, bufferPath] of bufferPaths.entries()) {const buffer = buffers?.[i];diff --git a/frontend/src/plugins/impl/anywidget/types.ts b/frontend/src/plugins/impl/anywidget/types.tsnew file mode 100644index 0000000000..3aba3845fa--- /dev/null+++ b/frontend/src/plugins/impl/anywidget/types.ts@@ -0,0 +1,27 @@+/* Copyright 2026 Marimo. All rights reserved. */+import type { Base64String } from "@/utils/json/base64";+import type { TypedString } from "@/utils/typed";++// eslint-disable-next-line @typescript-eslint/no-explicit-any+export type EventHandler = (...args: any[]) => void;++/**+ * Type-safe widget model id.+ */+export type WidgetModelId = TypedString<"WidgetModelId">;++/**+ * AnyWidget model state with buffers.+ */+// eslint-disable-next-line @typescript-eslint/no-explicit-any+export type ModelState = Record<string | number, any>;++/**+ * Wire format for anywidget state with binary data.+ * Buffers can be either base64 strings (from network) or DataViews (in-memory).+ */+export interface WireFormat<T = Record<string, unknown>> {+ state: T;+ bufferPaths: (string | number)[][];+ buffers: Base64String[];+}diff --git a/frontend/src/plugins/impl/chat/chat-ui.tsx b/frontend/src/plugins/impl/chat/chat-ui.tsxindex 4032fb154e..796b10c292 100644--- a/frontend/src/plugins/impl/chat/chat-ui.tsx+++ b/frontend/src/plugins/impl/chat/chat-ui.tsx@@ -22,6 +22,7 @@ import {X,} from "lucide-react";import React, { useEffect, useRef, useState } from "react";+import { z } from "zod";import { renderUIMessage } from "@/components/chat/chat-display";import { convertToFileUIPart } from "@/components/chat/chat-utils";import {@@ -71,6 +72,16 @@ interface Props extends PluginFunctions {host: HTMLElement;}+const ChatMessageIncomingSchema = z.object({+ type: z.literal("stream_chunk"),+ message_id: z.string(),+ content: z+ .any()+ .nullable()+ .transform((val) => val as UIMessageChunk | null),+ is_final: z.boolean().optional(),+});+export const Chatbot: React.FC<Props> = (props) => {const [input, setInput] = useState("");const [config, setConfig] = useState<ChatConfig>(props.config);@@ -252,15 +263,13 @@ export const Chatbot: React.FC<Props> = (props) => {props.host as HTMLElementNotDerivedFromRef,MarimoIncomingMessageEvent.TYPE,(e) => {- const message = e.detail.message;- if (- typeof message !== "object" ||- message === null ||- !("type" in message) ||- message.type !== "stream_chunk"- ) {+ const parsedMessage = ChatMessageIncomingSchema.safeParse(+ e.detail.message,+ );+ if (!parsedMessage.success) {return;}+ const message = parsedMessage.data;// Push to the stream for useChat to processconst controller = frontendStreamControllerRef.current;@@ -268,17 +277,10 @@ export const Chatbot: React.FC<Props> = (props) => {return;}- const frontendMessage = message as {- type: string;- message_id: string;- content?: UIMessageChunk;- is_final?: boolean;- };-- if (frontendMessage.content) {- controller.enqueue(frontendMessage.content);+ if (message.content) {+ controller.enqueue(message.content);}- if (frontendMessage.is_final) {+ if (message.is_final) {controller.close();frontendStreamControllerRef.current = null;}diff --git a/frontend/src/utils/Deferred.ts b/frontend/src/utils/Deferred.tsindex 12b27bc605..0ba1f0adb1 100644--- a/frontend/src/utils/Deferred.ts+++ b/frontend/src/utils/Deferred.ts@@ -1,9 +1,17 @@/* Copyright 2026 Marimo. All rights reserved. */++/**+ * A deferred promise that can be resolved or rejected externally.+ *+ * Provides synchronous access to status and resolved value, useful for+ * cases where you need to check if a promise has settled without awaiting it.+ */export class Deferred<T> {promise: Promise<T>;resolve!: (value: T | PromiseLike<T>) => void;reject!: (reason?: unknown) => void;status: "pending" | "resolved" | "rejected" = "pending";+ value: T | undefined = undefined;constructor() {this.promise = new Promise<T>((resolve, reject) => {@@ -13,8 +21,21 @@ export class Deferred<T> {};this.resolve = (value) => {this.status = "resolved";+ // Store the value for synchronous access+ if (!isPromiseLike(value)) {+ this.value = value;+ }resolve(value);};});}}++function isPromiseLike(value: unknown): value is PromiseLike<unknown> {+ return (+ typeof value === "object" &&+ value !== null &&+ "then" in value &&+ typeof value.then === "function"+ );+}diff --git a/frontend/src/utils/json/base64.ts b/frontend/src/utils/json/base64.tsindex e42d1258fc..0329b6e221 100644--- a/frontend/src/utils/json/base64.ts+++ b/frontend/src/utils/json/base64.ts@@ -52,13 +52,27 @@ export function extractBase64FromDataURL(str: DataURLString): Base64String {}/**- * Convert a base64 string to a Uint8Array.+ * Convert a base64 string to a Uint8Array (fallback implementation).+ * See benchmarks/base64-conversion.bench.ts for why we use a manual loop.*/-export function base64ToUint8Array(bytes: Base64String): Uint8Array {- const binary = window.atob(bytes);- return Uint8Array.from(binary, (c) => c.charCodeAt(0));+function base64ToUint8ArrayFallback(bytes: string): Uint8Array {+ const binary = globalThis.atob(bytes);+ const len = binary.length;+ const uint8Array = new Uint8Array(len);+ for (let i = 0; i < len; i++) {+ uint8Array[i] = binary.charCodeAt(i);+ }+ return uint8Array;}+/**+ * Convert a base64 string to a Uint8Array.+ * Uses native Uint8Array.fromBase64 if available, otherwise falls back to manual implementation.+ */+export const base64ToUint8Array: (bytes: Base64String) => Uint8Array =+ // @ts-expect-error - Uint8Array.fromBase64 types coming in TypeScript 5.10++ Uint8Array.fromBase64 ?? base64ToUint8ArrayFallback;+/*** Convert a base64 string to a DataView.*/@@ -68,13 +82,29 @@ export function base64ToDataView(bytes: Base64String): DataView {}/**- * Convert a Uint8Array to a base64 string.+ * Convert a Uint8Array to a base64 string (fallback implementation).+ * See benchmarks/uint8array-to-base64.bench.ts for why we use a manual loop.*/-export function uint8ArrayToBase64(binary: Uint8Array): Base64String {- const chars = Array.from(binary, (byte) => String.fromCharCode(byte));- return window.btoa(chars.join("")) as Base64String;+function uint8ArrayToBase64Fallback(binary: Uint8Array): Base64String {+ let binaryString = "";+ const len = binary.length;+ for (let i = 0; i < len; i++) {+ binaryString += String.fromCharCode(binary[i]);+ }+ return globalThis.btoa(binaryString) as Base64String;}+/**+ * Convert a Uint8Array to a base64 string.+ * Uses native Uint8Array.prototype.toBase64 if available, otherwise falls back to manual implementation.+ */+export const uint8ArrayToBase64: (binary: Uint8Array) => Base64String =+ // @ts-expect-error - Uint8Array.prototype.toBase64 types coming in TypeScript 5.10++ Uint8Array.prototype.toBase64+ ? // @ts-expect-error - Uint8Array.prototype.toBase64 types coming in TypeScript 5.10++ (binary) => binary.toBase64()+ : uint8ArrayToBase64Fallback;+/*** Convert a DataView to a base64 string.*/diff --git a/marimo/_cli/development/commands.py b/marimo/_cli/development/commands.pyindex ca1a3b3a69..a0897aeab9 100644--- a/marimo/_cli/development/commands.py+++ b/marimo/_cli/development/commands.py@@ -209,7 +209,7 @@ def _generate_server_api_schema() -> dict[str, Any]:commands.StopKernelCommand,commands.UpdateCellConfigCommand,commands.UpdateUserConfigCommand,- commands.UpdateWidgetModelCommand,+ commands.ModelCommand,commands.ValidateSQLCommand,models.BaseResponse,models.ClearCacheRequest,@@ -247,7 +247,7 @@ def _generate_server_api_schema() -> dict[str, Any]:models.UpdateUIElementValuesRequest,models.UpdateUIElementRequest,models.UpdateUserConfigRequest,- models.UpdateWidgetModelRequest,+ models.ModelRequest,models.ValidateSQLRequest,]diff --git a/marimo/_internal/commands.py b/marimo/_internal/commands.pyindex 47b4ac9ef2..7baab429ff 100644--- a/marimo/_internal/commands.py+++ b/marimo/_internal/commands.py@@ -22,6 +22,7 @@ from marimo._runtime.commands import (ListOrValue,ListSecretKeysCommand,ListSQLTablesCommand,+ ModelCommand,ModelMessage,PreviewDatasetColumnCommand,PreviewSQLTableCommand,@@ -35,7 +36,6 @@ from marimo._runtime.commands import (UpdateCellConfigCommand,UpdateUIElementCommand,UpdateUserConfigCommand,- UpdateWidgetModelCommand,ValidateSQLCommand,kebab_case,)@@ -74,7 +74,7 @@ __all__ = ["UpdateCellConfigCommand","UpdateUIElementCommand","UpdateUserConfigCommand",- "UpdateWidgetModelCommand",+ "ModelCommand","ValidateSQLCommand","kebab_case",]diff --git a/marimo/_messaging/notification.py b/marimo/_messaging/notification.pyindex 95b1e6e77a..efcd9a460f 100644--- a/marimo/_messaging/notification.py+++ b/marimo/_messaging/notification.py@@ -157,6 +157,53 @@ class UIElementMessageNotification(buffers: Optional[list[bytes]] = None+class ModelOpen(msgspec.Struct, tag="open", tag_field="method"):+ """Initial widget state on creation."""++ state: dict[str, Any]+ buffer_paths: list[list[Union[str, int]]]+ buffers: list[bytes]+++class ModelUpdate(msgspec.Struct, tag="update", tag_field="method"):+ """State sync - changed traits only."""++ state: dict[str, Any]+ buffer_paths: list[list[Union[str, int]]]+ buffers: list[bytes]+++class ModelCustom(msgspec.Struct, tag="custom", tag_field="method"):+ """Custom application message."""++ content: Any+ buffers: list[bytes]+++class ModelClose(msgspec.Struct, tag="close", tag_field="method"):+ """Widget destruction."""++ pass+++ModelMessage = Union[ModelOpen, ModelUpdate, ModelCustom, ModelClose]+++class ModelLifecycleNotification(Notification, tag="model-lifecycle"):+ """Widget model lifecycle message.++ Mirrors the Jupyter widget comm protocol with open/update/custom/close.++ Attributes:+ model_id: Widget model identifier.+ message: The lifecycle message (open/update/custom/close).+ """++ name: ClassVar[str] = "model-lifecycle"+ model_id: WidgetModelId+ message: ModelMessage++class InterruptedNotification(Notification, tag="interrupted"):"""Kernel was interrupted by user (SIGINT/Ctrl+C)."""@@ -658,6 +705,7 @@ NotificationMessage = Union[CellNotification,FunctionCallResultNotification,UIElementMessageNotification,+ ModelLifecycleNotification,RemoveUIElementsNotification,# Notebook lifecycleReloadNotification,diff --git a/marimo/_plugins/ui/_impl/anywidget/init.py b/marimo/_plugins/ui/_impl/anywidget/init.pyindex 9e023cbbac..80121c0a45 100644--- a/marimo/_plugins/ui/_impl/anywidget/init.py+++ b/marimo/_plugins/ui/_impl/anywidget/init.py@@ -37,9 +37,7 @@ def init_marimo_widget(w: ipywidgets.Widget) -> None:target_name="jupyter.widgets",data={"state": state, "buffer_paths": buffer_paths, "method": "open"},buffers=cast(BufferType, buffers),- # TODO: should this be hard-coded?metadata={"version": __protocol_version__},- # html_deps=session._process_ui(TagList(widget_dep))["deps"],)# Register ipywidgets' message handler so it can process incoming messagesdiff --git a/marimo/_plugins/ui/_impl/anywidget/types.py b/marimo/_plugins/ui/_impl/anywidget/types.pyindex 6fcd48b858..5888a4d1a2 100644--- a/marimo/_plugins/ui/_impl/anywidget/types.py+++ b/marimo/_plugins/ui/_impl/anywidget/types.py@@ -1,7 +1,7 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import Any, Literal, NewType, TypedDict, Union+from typing import Any, NewType, Union# AnyWidget model idWidgetModelId = NewType("WidgetModelId", str)@@ -14,47 +14,3 @@ WidgetModelState = dict[str, Any]# Widget model state without buffersWidgetModelStateWithoutBuffers = dict[str, Any]---# AnyWidget model message-class TypedModelMessage(TypedDict):- """- A typed message for AnyWidget models.-- Args:- state: The state of the model.- buffer_paths: The buffer paths to update.- """-- state: WidgetModelStateWithoutBuffers- buffer_paths: BufferPaths---class TypedModelAction(TypedModelMessage):- """- A typed message for AnyWidget models.-- Args:- method: The method to call on the model.- state: The state of the model.- buffer_paths: The buffer paths to update.- """-- method: Literal["open", "update", "custom", "echo_update"]---class TypedModelMessageContent(TypedDict):- """A typed payload for AnyWidget models."""-- data: TypedModelAction---class TypedModelMessagePayload(TypedDict):- """- A typed payload for AnyWidget models.-- This interface is what AnyWidget's comm.handle_msg expects- """-- content: TypedModelMessageContent- buffers: list[bytes]diff --git a/marimo/_plugins/ui/_impl/anywidget/utils.py b/marimo/_plugins/ui/_impl/anywidget/utils.pyindex c1a1a155a5..aa5426667f 100644--- a/marimo/_plugins/ui/_impl/anywidget/utils.py+++ b/marimo/_plugins/ui/_impl/anywidget/utils.py@@ -1,19 +1,13 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from typing import TYPE_CHECKING-from marimo._dependencies.dependencies import DependencyManagerfrom marimo._plugins.ui._impl.anywidget.types import (BufferPaths,- TypedModelMessage,WidgetModelState,WidgetModelStateWithoutBuffers,)-if TYPE_CHECKING:- from typing_extensions import TypeIs-def extract_buffer_paths(message: WidgetModelState,@@ -30,31 +24,3 @@ def extract_buffer_paths(state, buffer_paths, buffers = _remove_buffers(message) # type: ignorereturn state, buffer_paths, buffers # type: ignore---def insert_buffer_paths(- state: WidgetModelStateWithoutBuffers,- buffer_paths: BufferPaths,- buffers: list[bytes],-) -> WidgetModelState:- """- Insert buffer paths into a message.- """- DependencyManager.ipywidgets.require("for anywidget support.")- import ipywidgets # type: ignore-- _put_buffers = ipywidgets.widgets.widget._put_buffers # type: ignore- _put_buffers(state, buffer_paths, buffers)- return state---def is_model_message(message: object) -> TypeIs[TypedModelMessage]:- """- Check if a message is a model message.- """- if not isinstance(message, dict):- return False- keys = ("method", "state", "buffer_paths")- if not all(key in message for key in keys):- return False- return Truediff --git a/marimo/_plugins/ui/_impl/comm.py b/marimo/_plugins/ui/_impl/comm.pyindex 795890752d..003e05be46 100644--- a/marimo/_plugins/ui/_impl/comm.py+++ b/marimo/_plugins/ui/_impl/comm.py@@ -1,18 +1,24 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-from dataclasses import dataclass-from typing import TYPE_CHECKING, Any, Callable, Optional, cast+from typing import Any, Callable, Optionalfrom marimo._loggers import marimo_logger+from marimo._messaging.notification import (+ ModelClose,+ ModelCustom,+ ModelLifecycleNotification,+ ModelMessage,+ ModelOpen,+ ModelUpdate,+)+from marimo._messaging.notification_utils import broadcast_notification+from marimo._runtime.commands import (+ ModelCommand,+ ModelUpdateMessage,+)from marimo._types.ids import WidgetModelId-if TYPE_CHECKING:- from marimo._plugins.ui._impl.anywidget.types import (- TypedModelMessagePayload,- )- from marimo._runtime.commands import ModelMessage-LOGGER = marimo_logger()@@ -29,28 +35,30 @@ class MarimoCommManager:def receive_comm_message(self,- comm_id: WidgetModelId,- message: ModelMessage,- buffers: Optional[list[bytes]],- ) -> None:- if comm_id not in self.comms:- LOGGER.warning("Received message for unknown comm", comm_id)- return+ command: ModelCommand,+ ) -> tuple[Optional[str], Optional[dict[str, Any]]]:+ """Receive a message from the frontend and forward to the comm.++ Returns:+ A tuple of (ui_element_id, state) if this is an "update" message+ and there's a ui_element_id, otherwise (None, None).+ The caller can use this to trigger a cell re-run.+ """+ if command.model_id not in self.comms:+ LOGGER.warning(+ "Received message for unknown comm: %s", command.model_id+ )+ return (None, None)- comm = self.comms[comm_id]+ comm = self.comms[command.model_id]+ comm.handle_msg(command.into_comm_payload())- msg: TypedModelMessagePayload = {- "content": {- "data": {- "state": message.state,- "method": "update",- "buffer_paths": message.buffer_paths,- }- },- "buffers": buffers or [],- }+ # For update messages, return ui_element_id and state for cell re-run+ message = command.message+ if isinstance(message, ModelUpdateMessage) and comm.ui_element_id:+ return (comm.ui_element_id, message.state)- comm.handle_msg(cast(Msg, msg))+ return (None, None)Msg = dict[str, Any]@@ -59,17 +67,42 @@ DataType = Optional[dict[str, Any]]MetadataType = Optional[dict[str, Any]]BufferType = Optional[list[bytes]]-COMM_MESSAGE_NAME = "marimo_comm_msg"-COMM_OPEN_NAME = "marimo_comm_open"-COMM_CLOSE_NAME = "marimo_comm_close"+def _create_model_message(+ data: dict[str, Any],+ buffers: list[bytes],+) -> Optional[ModelMessage]:+ """Create the appropriate ModelMessage based on the method field.-@dataclass-class MessageBufferData:- data: dict[str, Any]- metadata: dict[str, Any]- buffers: list[bytes]- model_id: WidgetModelId+ Returns None for methods that should be skipped (e.g., echo_update).+ """+ method = data.get("method", "update")+ state = data.get("state", {})+ buffer_paths = data.get("buffer_paths", [])++ if method == "open":+ return ModelOpen(+ state=state,+ buffer_paths=buffer_paths,+ buffers=buffers,+ )+ elif method == "update":+ return ModelUpdate(+ state=state,+ buffer_paths=buffer_paths,+ buffers=buffers,+ )+ elif method == "custom":+ return ModelCustom(+ content=data.get("content"),+ buffers=buffers,+ )+ elif method == "echo_update":+ # echo_update is for multi-client sync acknowledgment, skip it+ return None+ else:+ LOGGER.warning("Unknown method: %s, skipping", method)+ return None# Compare to `ipykernel.comm.Comm`@@ -91,6 +124,8 @@ class MarimoComm:buffers: BufferType = None,**keys: object,) -> None:+ del keys # unused+ del metadata # unusedself._msg_callback: Optional[MsgCallback] = Noneself._close_callback: Optional[MsgCallback] = Noneself._closed: bool = False@@ -100,46 +135,44 @@ class MarimoComm:self.comm_manager = comm_managerself.target_name = target_nameself.ui_element_id: Optional[str] = None- self._publish_message_buffer: list[MessageBufferData] = []- self.open(data=data, metadata=metadata, buffers=buffers, **keys)+ self._open(data=data, buffers=buffers)- def open(+ def _open(self,data: DataType = None,- metadata: MetadataType = None,buffers: BufferType = None,- **keys: object,) -> None:+ """Open the comm and send initial state."""+ LOGGER.debug("Opening comm %s", self.comm_id)self.comm_manager.register_comm(self)try:- self._publish_msg(- COMM_OPEN_NAME,- data=data,- metadata=metadata,- buffers=buffers,- target_name=self.target_name,- target_module=None,- **keys,- )+ self._broadcast(data or {}, buffers or [])self._closed = Falseexcept Exception:self.comm_manager.unregister_comm(self)raise- # Inform client of any mutation(s) to the model- # (e.g., add a marker to a map, without a full redraw)+ # Legacy method for ipywidgets compatibility+ def open(+ self,+ data: DataType = None,+ metadata: MetadataType = None,+ buffers: BufferType = None,+ **keys: object,+ ) -> None:+ del metadata, keys # unused+ self._open(data=data, buffers=buffers)+def send(self,data: DataType = None,metadata: MetadataType = None,buffers: BufferType = None,) -> None:- self._publish_msg(- COMM_MESSAGE_NAME,- data=data,- metadata=metadata,- buffers=buffers,- )+ """Send a message to the frontend (state update or custom message)."""+ del metadata # unused+ LOGGER.debug("Sending comm message %s", self.comm_id)+ self._broadcast(data or {}, buffers or [])def close(self,@@ -148,94 +181,37 @@ class MarimoComm:buffers: BufferType = None,deleting: bool = False,) -> None:+ """Close the comm."""+ del data, metadata, buffers # unused for close+ LOGGER.debug("Closing comm %s", self.comm_id)if self._closed:returnself._closed = True- data = self._closed_data if data is None else data- self._publish_msg(- COMM_CLOSE_NAME,- data=data,- metadata=metadata,- buffers=buffers,++ broadcast_notification(+ ModelLifecycleNotification(+ model_id=self.comm_id,+ message=ModelClose(),+ ))+if not deleting:- # If deleting, the comm can't be unregisteredself.comm_manager.unregister_comm(self)- # trigger close on gcdef __del__(self) -> None:self.close(deleting=True)- # Compare to `ipykernel.comm.Comm._publish_msg`, but...- # https://github.com/jupyter/jupyter_client/blob/c5c0b80/jupyter_client/session.py#L749- # ...the real meat of the implement- # is in `jupyter_client.session.Session.send`- # https://github.com/jupyter/jupyter_client/blob/c5c0b8/jupyter_client/session.py#L749-L862- def _publish_msg(- self,- msg_type: str,- data: DataType = None,- metadata: MetadataType = None,- buffers: BufferType = None,- **keys: object,- ) -> None:- del keys- data = {} if data is None else data- metadata = {} if metadata is None else metadata- buffers = [] if buffers is None else buffers-- if msg_type == COMM_OPEN_NAME:- self._publish_message_buffer.append(- MessageBufferData(- data, metadata, buffers, model_id=self.comm_id- )- )- self.flush()- return-- if msg_type == COMM_MESSAGE_NAME:- self._publish_message_buffer.append(- MessageBufferData(- data, metadata, buffers, model_id=self.comm_id- )- )- self.flush()+ def _broadcast(self, data: dict[str, Any], buffers: list[bytes]) -> None:+ """Broadcast a model lifecycle notification."""+ message = _create_model_message(data, buffers)+ if message is None:return-- if msg_type == COMM_CLOSE_NAME:- self._publish_message_buffer.append(- MessageBufferData(- data, metadata, buffers, model_id=self.comm_id- )+ broadcast_notification(+ ModelLifecycleNotification(+ model_id=self.comm_id,+ message=message,)- self.flush()- return-- LOGGER.warning(- "Unknown message type",- msg_type,- data,- )-- def flush(self) -> None:- from marimo._messaging.notification import (- UIElementMessageNotification,)- from marimo._messaging.notification_utils import broadcast_notification-- while self._publish_message_buffer:- item = self._publish_message_buffer.pop(0)-- broadcast_notification(- UIElementMessageNotification(- # ui_element_id can be None. In this case, we are creating a model- # not tied to a specific UI element- ui_element=self.ui_element_id,- model_id=item.model_id,- message=item.data,- buffers=item.buffers,- ),- )# This is the method that ipywidgets.widgets.Widget uses to respond to# client-side changes@@ -246,21 +222,20 @@ class MarimoComm:self._close_callback = callbackdef handle_msg(self, msg: Msg) -> None:+ LOGGER.debug("Handling message for comm %s", self.comm_id)if self._msg_callback is not None:self._msg_callback(msg)else:LOGGER.warning(- "Received message for comm but no callback registered",+ "Received message for comm %s but no callback registered",self.comm_id,- msg,)def handle_close(self, msg: Msg) -> None:if self._close_callback is not None:self._close_callback(msg)else:- LOGGER.warning(- "Received close for comm but no callback registered",+ LOGGER.debug(+ "Received close for comm %s but no callback registered",self.comm_id,- msg,)diff --git a/marimo/_plugins/ui/_impl/from_anywidget.py b/marimo/_plugins/ui/_impl/from_anywidget.pyindex b27e32de16..eeba99203a 100644--- a/marimo/_plugins/ui/_impl/from_anywidget.py+++ b/marimo/_plugins/ui/_impl/from_anywidget.py@@ -1,16 +1,13 @@# Copyright 2026 Marimo. All rights reserved.from __future__ import annotations-import base64-import hashlibimport weakreffrom copy import deepcopy-from dataclasses import dataclassfrom typing import (TYPE_CHECKING,Any,Generic,- Optional,+ TypeAlias,TypedDict,TypeVar,cast,@@ -20,58 +17,25 @@ import marimo._output.data.data as mo_datafrom marimo import _loggersfrom marimo._output.rich_help import mddocfrom marimo._plugins.ui._core.ui_element import InitializationArgs, UIElement-from marimo._plugins.ui._impl.anywidget.utils import (- extract_buffer_paths,- insert_buffer_paths,-)from marimo._plugins.ui._impl.comm import MarimoComm-from marimo._runtime.functions import Function+from marimo._types.ids import WidgetModelId+from marimo._utils.code import hash_code++AnyWidgetState: TypeAlias = dict[str, Any]class WireFormat(TypedDict):- state: dict[str, Any]+ """Wire format for anywidget state with binary buffers."""++ state: AnyWidgetStatebufferPaths: list[list[str | int]]buffers: list[str]-def decode_from_wire(- wire: WireFormat | dict[str, Any],-) -> dict[str, Any]:- """Decode wire format { state, bufferPaths, buffers } to plain state with bytes."""- if "state" not in wire or "bufferPaths" not in wire:- return wire # Not wire format, return as-is+class ModelIdRef(TypedDict):+ """Reference to a model by its ID. The frontend retrieves state from the open message."""- state = wire.get("state", {})- buffer_paths = wire.get("bufferPaths", [])- buffers_base64: list[str] = wire.get("buffers", [])-- if buffer_paths and buffers_base64:- decoded_buffers = [base64.b64decode(b) for b in buffers_base64]- return insert_buffer_paths(state, buffer_paths, decoded_buffers)-- if buffer_paths or buffers_base64:- LOGGER.warning(- "Expected wire format to have buffers, but got %s", wire- )- return state-- return state---def encode_to_wire(- state: dict[str, Any],-) -> WireFormat:- """Encode plain state with bytes to wire format { state, bufferPaths, buffers }."""- state_no_buffers, buffer_paths, buffers = extract_buffer_paths(state)-- # Convert bytes to base64- buffers_base64 = [base64.b64encode(b).decode("utf-8") for b in buffers]-- return WireFormat(- state=state_no_buffers,- bufferPaths=buffer_paths,- buffers=buffers_base64,- )+ model_id: WidgetModelIdif TYPE_CHECKING:@@ -122,17 +86,50 @@ def from_anywidget(widget: AnyWidget) -> UIElement[Any, Any]:return el-T = dict[str, Any]---@dataclass-class SendToWidgetArgs:- content: Any- buffers: Optional[Any] = None+def get_anywidget_state(widget: AnyWidget) -> AnyWidgetState:+ """Get the state of an AnyWidget."""+ # Remove widget-specific system traits not needed for the frontend+ ignored_traits = {+ "comm",+ "layout",+ "log",+ "tabbable",+ "tooltip",+ "keys",+ "_esm",+ "_css",+ "_anywidget_id",+ "_msg_callbacks",+ "_dom_classes",+ "_model_module",+ "_model_module_version",+ "_model_name",+ "_property_lock",+ "_states_to_send",+ "_view_count",+ "_view_module",+ "_view_module_version",+ "_view_name",+ }++ state: dict[str, Any] = widget.get_state()++ # Filter out system traits from the serialized state+ # This should include the binary data,+ # see marimo/_smoke_tests/issues/2366-anywidget-binary.py+ return {k: v for k, v in state.items() if k not in ignored_traits}+++def get_anywidget_model_id(widget: AnyWidget) -> WidgetModelId:+ """Get the model_id of an AnyWidget."""+ model_id = getattr(widget, "_model_id", None)+ if not model_id:+ raise RuntimeError("Widget model_id is not set")+ return WidgetModelId(model_id)@mddoc-class anywidget(UIElement[WireFormat, T]):+class anywidget(UIElement[ModelIdRef, AnyWidgetState]):"""Create a UIElement from an AnyWidget.This proxies all the widget's attributes and methods, allowing seamless@@ -168,93 +165,34 @@ class anywidget(UIElement[WireFormat, T]):# This gets set to True in super().__init__()self._initialized = False- # Get state with custom serializers properly applied- state: dict[str, Any] = widget.get_state()- _state_no_buffers, buffer_paths, buffers = extract_buffer_paths(state)-- # Remove widget-specific system traits not needed for the frontend- ignored_traits = [- "comm",- "layout",- "log",- "tabbable",- "tooltip",- "keys",- "_esm",- "_css",- "_anywidget_id",- "_msg_callbacks",- "_dom_classes",- "_model_module",- "_model_module_version",- "_model_name",- "_property_lock",- "_states_to_send",- "_view_count",- "_view_module",- "_view_module_version",- "_view_name",- ]-- # Filter out system traits from the serialized state- # This should include the binary data,- # see marimo/_smoke_tests/issues/2366-anywidget-binary.py- json_args: T = {- k: v for k, v in state.items() if k not in ignored_traits- }-- js: str = widget._esm if hasattr(widget, "_esm") else "" # type: ignore [unused-ignore] # noqa: E501- css: str = widget._css if hasattr(widget, "_css") else "" # type: ignore [unused-ignore] # noqa: E501-- def on_change(change: dict[str, Any]) -> None:- # Decode wire format to plain state with bytes- state = decode_from_wire(change)-- # Only update traits that have actually changed- current_state: dict[str, Any] = widget.get_state()- changed_state: dict[str, Any] = {}-- for k, v in state.items():- if k not in current_state:- changed_state[k] = v- elif current_state[k] != v:- changed_state[k] = v-- if changed_state:- widget.set_state(changed_state)-- js_hash: str = hashlib.md5(- js.encode("utf-8"), usedforsecurity=False- ).hexdigest()-- # Store plain state with bytes for merging- self._prev_state = json_args-- # Initial value is wire format: { state, bufferPaths, buffers }- initial_wire = encode_to_wire(json_args)+ js: str = getattr(widget, "_esm", "") # type: ignore [unused-ignore]+ css: str = getattr(widget, "_css", "") # type: ignore [unused-ignore]++ js_hash = hash_code(js)++ # Trigger comm initialization early to ensure _model_id is set+ _ = widget.comm+ # Get the model_id from the widget (should always be set after comm init)+ model_id = get_anywidget_model_id(widget)++ # Initial value is just the model_id reference+ # The frontend retrieves the actual state from the 'open' messagesuper().__init__(component_name="marimo-anywidget",- initial_value=initial_wire,- label="",+ initial_value=ModelIdRef(model_id=model_id),+ label=None,args={"js-url": mo_data.js(js).url if js else "", # type: ignore [unused-ignore] # noqa: E501"js-hash": js_hash,"css": css,},- on_change=on_change,- functions=(- Function(- name="send_to_widget",- arg_cls=SendToWidgetArgs,- function=self._receive_from_frontend,- ),- ),+ on_change=None,)def _initialize(self,- initialization_args: InitializationArgs[WireFormat, dict[str, Any]],+ initialization_args: InitializationArgs[ModelIdRef, AnyWidgetState],) -> None:super()._initialize(initialization_args)# Add the ui_element_id after the widget is initialized@@ -262,47 +200,30 @@ class anywidget(UIElement[WireFormat, T]):if isinstance(comm, MarimoComm):comm.ui_element_id = self._id- def _receive_from_frontend(self, args: SendToWidgetArgs) -> None:- state = decode_from_wire(- WireFormat(- state=args.content.get("state", {}),- bufferPaths=args.content.get("bufferPaths", []),- buffers=args.buffers or [],- )- )- self.widget._handle_custom_msg(state, args.buffers)-- def _convert_value(self, value: WireFormat) -> T:- if isinstance(value, dict) and isinstance(self._prev_state, dict):- # Decode wire format to plain state with bytes- decoded_state = decode_from_wire(value)+ def _convert_value(+ self, value: ModelIdRef | AnyWidgetState+ ) -> AnyWidgetState:+ if not isinstance(value, dict):+ raise ValueError(f"Expected dict, got {type(value)}")- # Merge with previous state- merged = {**self._prev_state, **decoded_state}- self._prev_state = merged+ # Check if this is a ModelIdRef (initial value from frontend)+ model_id = value.get("model_id")+ if model_id and len(value) == 1:+ # Initial value - just return empty, the widget manages its own state+ return {}- # Encode back to wire format for frontend- # NB: This needs to be the wire format to work- # although the types say it should be the plain state,- # otherwise the frontend loses some information- return cast(T, encode_to_wire(merged))-- LOGGER.warning(- f"Expected anywidget value to be a dict, got {type(value)}"- )- self._prev_state = value- return cast(T, value)+ # Otherwise, it's a state update from the frontend+ # Update the widget's state+ self.widget.set_state(value)+ return cast(AnyWidgetState, value)@property- def value(self) -> T:+ def value(self) -> AnyWidgetState:"""The element's current value as a plain dictionary (wire format decoded)."""- # Get the internal value (which is in wire format)- internal_value = super().value- # Decode it to plain state for user-facing code- return decode_from_wire(internal_value) # type: ignore[return-value]+ return get_anywidget_state(self.widget)@value.setter- def value(self, value: T) -> None:+ def value(self, value: AnyWidgetState) -> None:del valueraise RuntimeError("Setting the value of a UIElement is not allowed.")diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.pyindex c54ffedf39..577fe2ebf6 100644--- a/marimo/_runtime/commands.py+++ b/marimo/_runtime/commands.py@@ -680,11 +680,11 @@ class ListSecretKeysCommand(Command):request_id: RequestId-class ModelMessage(msgspec.Struct, rename="camel"):+class ModelUpdateMessage(+ msgspec.Struct, tag="update", tag_field="method", rename="camel"+):"""Widget model state update message.- State changes for anywidget models, including state dict and binary buffer paths.-Attributes:state: Model state updates.buffer_paths: Paths within state dict pointing to binary buffers.@@ -693,21 +693,59 @@ class ModelMessage(msgspec.Struct, rename="camel"):state: dict[str, Any]buffer_paths: list[list[Union[str, int]]]+ def into_comm_payload_content(self) -> dict[str, Any]:+ return {+ "data": {+ "method": "update",+ "state": self.state,+ "buffer_paths": self.buffer_paths,+ }+ }+++class ModelCustomMessage(+ msgspec.Struct, tag="custom", tag_field="method", rename="camel"+):+ """Custom widget message.++ Attributes:+ content: Arbitrary content for the custom message.+ """++ content: Any++ def into_comm_payload_content(self) -> dict[str, Any]:+ return {+ "data": {+ "method": "custom",+ "content": self.content,+ }+ }+++ModelMessage = Union[ModelUpdateMessage, ModelCustomMessage]-class UpdateWidgetModelCommand(Command):- """Update anywidget model state.- Updates widget model state for bidirectional Python-JavaScript communication.+class ModelCommand(Command):+ """Widget model message command.++ Handles widget model communication between frontend and backend.Attributes:model_id: Widget model identifier.- message: Model message with state updates and buffer paths.- buffers: Base64-encoded binary buffers referenced by buffer_paths.+ message: Model message (update or custom).+ buffers: Base64-encoded binary buffers."""model_id: WidgetModelIdmessage: ModelMessage- buffers: Optional[list[str]] = None+ buffers: list[bytes]++ def into_comm_payload(self) -> dict[str, Any]:+ return {+ "content": self.message.into_comm_payload_content(),+ "buffers": self.buffers,+ }class RefreshSecretsCommand(Command):@@ -755,7 +793,7 @@ CommandMessage = Union[InstallPackagesCommand,# UI element and widget model operationsUpdateUIElementCommand,- UpdateWidgetModelCommand,+ ModelCommand,InvokeFunctionCommand,# User/configuration operationsUpdateUserConfigCommand,diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.pyindex c53d872699..88e5ebf219 100644--- a/marimo/_runtime/runtime.py+++ b/marimo/_runtime/runtime.py@@ -120,6 +120,7 @@ from marimo._runtime.commands import (ListDataSourceConnectionCommand,ListSecretKeysCommand,ListSQLTablesCommand,+ ModelCommand,PreviewDatasetColumnCommand,PreviewSQLTableCommand,RefreshSecretsCommand,@@ -129,7 +130,6 @@ from marimo._runtime.commands import (UpdateCellConfigCommand,UpdateUIElementCommand,UpdateUserConfigCommand,- UpdateWidgetModelCommand,ValidateSQLCommand,)from marimo._runtime.context import (@@ -2275,14 +2275,21 @@ class Kernel:await self.rename_file(request.filename)async def handle_receive_model_message(- request: UpdateWidgetModelCommand,+ request: ModelCommand,) -> None:- buffers = request.buffers or []- buffers_as_bytes = [buffer.encode("utf-8") for buffer in buffers]- WIDGET_COMM_MANAGER.receive_comm_message(- request.model_id, request.message, buffers_as_bytes+ ui_element_id, state = WIDGET_COMM_MANAGER.receive_comm_message(+ request)+ # If there's a ui_element_id, trigger a cell re-run+ if ui_element_id and state:+ await self.set_ui_element_value(+ UpdateUIElementCommand.from_ids_and_values(+ [(UIElementId(ui_element_id), state)]+ )+ )+ broadcast_notification(CompletedRunNotification())+async def handle_function_call(request: InvokeFunctionCommand) -> None:status, ret, _ = await self.function_call_request(request)LOGGER.debug("Function returned with status %s", status)@@ -2323,9 +2330,7 @@ class Kernel:handler.register(RenameNotebookCommand, handle_rename)handler.register(UpdateCellConfigCommand, self.set_cell_config)handler.register(UpdateUIElementCommand, handle_set_ui_element_value)- handler.register(- UpdateWidgetModelCommand, handle_receive_model_message- )+ handler.register(ModelCommand, handle_receive_model_message)handler.register(UpdateUserConfigCommand, handle_set_user_config)handler.register(StopKernelCommand, handle_stop)# Datasetsdiff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.pyindex ff6248b7a5..f6443cae45 100644--- a/marimo/_server/api/endpoints/execution.py+++ b/marimo/_server/api/endpoints/execution.py@@ -25,9 +25,9 @@ from marimo._server.models.models import (ExecuteScratchpadRequest,InstantiateNotebookRequest,InvokeFunctionRequest,+ ModelRequest,SuccessResponse,UpdateUIElementValuesRequest,- UpdateWidgetModelRequest,)from marimo._server.router import APIRouterfrom marimo._server.uvicorn_utils import close_uvicorn@@ -98,7 +98,7 @@ async def set_model_values(content:application/json:schema:- $ref: "#/components/schemas/UpdateWidgetModelRequest"+ $ref: "#/components/schemas/ModelRequest"responses:200:description: Set model value@@ -107,7 +107,7 @@ async def set_model_values(schema:$ref: "#/components/schemas/SuccessResponse""""- return await dispatch_control_request(request, UpdateWidgetModelRequest)+ return await dispatch_control_request(request, ModelRequest)@router.post("/instantiate")diff --git a/marimo/_server/models/models.py b/marimo/_server/models/models.pyindex 21744f3ea1..a9b26914f2 100644--- a/marimo/_server/models/models.py+++ b/marimo/_server/models/models.py@@ -20,12 +20,12 @@ from marimo._runtime.commands import (ListDataSourceConnectionCommand,ListSecretKeysCommand,ListSQLTablesCommand,+ ModelCommand,PreviewDatasetColumnCommand,PreviewSQLTableCommand,UpdateCellConfigCommand,UpdateUIElementCommand,UpdateUserConfigCommand,- UpdateWidgetModelCommand,ValidateSQLCommand,)from marimo._types.ids import CellId_t, UIElementId@@ -76,9 +76,9 @@ class UpdateUIElementRequest(UpdateUIElementCommand, tag=False):)-class UpdateWidgetModelRequest(UpdateWidgetModelCommand, tag=False):- def as_command(self) -> UpdateWidgetModelCommand:- return UpdateWidgetModelCommand(+class ModelRequest(ModelCommand, tag=False):+ def as_command(self) -> ModelCommand:+ return ModelCommand(model_id=self.model_id,message=self.message,buffers=self.buffers,diff --git a/marimo/_session/state/session_view.py b/marimo/_session/state/session_view.pyindex 084e79284f..e0e7d0f909 100644--- a/marimo/_session/state/session_view.py+++ b/marimo/_session/state/session_view.py@@ -303,7 +303,9 @@ class SessionView:returnmessages = self.model_messages.get(notification.model_id, [])messages.append(notification)- # TODO: cleanup/merge previous 'update' messages+ # TODO(perf): Consider merging consecutive 'update' messages+ # to reduce replay size. Could keep only the latest state for+ # each model_id instead of the full message history.self.model_messages[notification.model_id] = messageselif isinstance(notification, StartupLogsNotification):@@ -440,12 +442,16 @@ class SessionView:all_notifications.append(self.datasets)if self.data_connectors.connections:all_notifications.append(self.data_connectors)- all_notifications.extend(self.cell_notifications.values())- if self.stale_code:- all_notifications.append(self.stale_code)++ # Model messages must come before cell notifications to ensure+ # the model exists before the view tries to use it.if self.model_messages:for messages in self.model_messages.values():all_notifications.extend(messages)++ all_notifications.extend(self.cell_notifications.values())+ if self.stale_code:+ all_notifications.append(self.stale_code)# Only include startup logs if they are in progress (not done)if self.startup_logs and self.startup_logs.status != "done":all_notifications.append(self.startup_logs)diff --git a/marimo/_smoke_tests/anywidget_examples/esm_rerender.py b/marimo/_smoke_tests/anywidget_examples/esm_rerender.pyindex 2c40637224..13549b4e43 100644--- a/marimo/_smoke_tests/anywidget_examples/esm_rerender.py+++ b/marimo/_smoke_tests/anywidget_examples/esm_rerender.py@@ -9,7 +9,7 @@import marimo-__generated_with = "0.15.5"+__generated_with = "0.19.7"app = marimo.App(width="medium")@@ -71,5 +71,17 @@ def _(widget):return+def _(widget):+ widget.count+ return+++def _(widget):+ widget.value+ return++if __name__ == "__main__":app.run()diff --git a/marimo/_smoke_tests/anywidget_examples/lonboard_example.py b/marimo/_smoke_tests/anywidget_examples/lonboard_example.pyindex 349464f676..a218e6ff4f 100644--- a/marimo/_smoke_tests/anywidget_examples/lonboard_example.py+++ b/marimo/_smoke_tests/anywidget_examples/lonboard_example.py@@ -14,7 +14,7 @@import marimo-__generated_with = "0.15.5"+__generated_with = "0.19.7"app = marimo.App(width="medium")@@ -75,7 +75,7 @@ def _(Map, ScatterplotLayer, gdf, mo):max_bound = mo.ui.slider(0, 100_000, value=50_000, show_value=True, label="max bound")- mo.vstack([min_bound, max_bound, Map(layer, _height=600)])+ mo.vstack([min_bound, max_bound, Map(layer)])return layer, max_bound, min_bounddiff --git a/marimo/_smoke_tests/anywidget_examples/scatter.py b/marimo/_smoke_tests/anywidget_examples/scatter.pyindex 18ba1d8c0b..8cdec6654c 100644--- a/marimo/_smoke_tests/anywidget_examples/scatter.py+++ b/marimo/_smoke_tests/anywidget_examples/scatter.py@@ -8,7 +8,7 @@import marimo-__generated_with = "0.18.3"+__generated_with = "0.19.7"app = marimo.App(width="medium")@@ -18,8 +18,8 @@ def _():import jscatterimport numpy as np- x = np.random.rand(500)- y = np.random.rand(500)+ x = np.random.rand(50000)+ y = np.random.rand(50000)scatter = jscatter.Scatter(x=x, y=y)w = mo.ui.anywidget(scatter.widget)diff --git a/marimo/_smoke_tests/anywidget_smoke_tests/mosaic_example.py b/marimo/_smoke_tests/anywidget_smoke_tests/mosaic_example.pyindex 3a64394514..c9859be16c 100644--- a/marimo/_smoke_tests/anywidget_smoke_tests/mosaic_example.py+++ b/marimo/_smoke_tests/anywidget_smoke_tests/mosaic_example.py@@ -13,7 +13,7 @@import marimo-__generated_with = "0.16.2"+__generated_with = "0.19.7"app = marimo.App(width="medium")@@ -40,7 +40,7 @@ def _():spec.pop("data")w = mo.ui.anywidget(MosaicWidget(spec, data={"weather": weather}))- return (w,)+ return mo, w@app.cell@@ -50,8 +50,8 @@ def _(w):@app.cell-def _(w):- w.value+def _():+ # w.valuereturn@@ -62,16 +62,30 @@ def _():@app.cell-def _(quak):+def _(mo, quak):import polars as pl- _df = pl.read_parquet("https://github.com/uwdata/mosaic/raw/main/data/athletes.parquet")- quak.Widget(_df)- return+ _df = pl.read_parquet(+ "https://github.com/uwdata/mosaic/raw/main/data/athletes.parquet"+ )+ q = mo.ui.anywidget(quak.Widget(_df))+ q+ return (q,)@app.celldef _():+ thing = {"a": 0}+ return (thing,)+++def _(q, thing):+ # Check gets update only once+ thing["a"] += 1+ print(thing["a"])++ q.data()returndiff --git a/marimo/_smoke_tests/anywidget_smoke_tests/multiple_models.py b/marimo/_smoke_tests/anywidget_smoke_tests/multiple_models.pyindex fdd05ea374..9052b3dd17 100644--- a/marimo/_smoke_tests/anywidget_smoke_tests/multiple_models.py+++ b/marimo/_smoke_tests/anywidget_smoke_tests/multiple_models.py@@ -1,6 +1,6 @@import marimo-__generated_with = "0.15.5"+__generated_with = "0.19.7"app = marimo.App(width="medium")@@ -14,7 +14,7 @@ def _():class ModelOnlyWidget(ipywidgets.Widget):- value = traitlets.Int(1).tag(sync=True)+ value = traitlets.Int(42).tag(sync=True)class Widget(anywidget.AnyWidget):@@ -59,10 +59,5 @@ def _(m):return-def _():- return--if __name__ == "__main__":app.run()diff --git a/marimo/_smoke_tests/anywidget_smoke_tests/uchimata_example.py b/marimo/_smoke_tests/anywidget_smoke_tests/uchimata_example.pyindex 734baf7389..fcd2770fb3 100644--- a/marimo/_smoke_tests/anywidget_smoke_tests/uchimata_example.py+++ b/marimo/_smoke_tests/anywidget_smoke_tests/uchimata_example.py@@ -11,7 +11,7 @@import marimo-__generated_with = "0.16.2"+__generated_with = "0.19.7"app = marimo.App(width="medium")@@ -20,6 +20,7 @@ def _():import anywidgetimport traitlets+class Widget(anywidget.AnyWidget):_esm = """export default {@@ -33,6 +34,7 @@ def _():"""data = traitlets.Any().tag(sync=True)+# Should display "hello"Widget(data=b"hello")return@@ -45,6 +47,7 @@ def _():BINS_NUM = 1000+# Step 1: Generate random structure, returns a 2D numpy array:def make_random_3D_chromatin_structure(n):position = np.array([0.0, 0.0, 0.0])@@ -57,6 +60,7 @@ def _():positions.append(position.copy())return np.array(positions)+random_structure = make_random_3D_chromatin_structure(BINS_NUM)# Step 2: Display the structure in an uchimata widgetdiff --git a/marimo/_smoke_tests/issues/2366-anywidget-binary.py b/marimo/_smoke_tests/issues/2366-anywidget-binary.pyindex d336658c7e..e13b926027 100644--- a/marimo/_smoke_tests/issues/2366-anywidget-binary.py+++ b/marimo/_smoke_tests/issues/2366-anywidget-binary.py@@ -1,6 +1,6 @@import marimo-__generated_with = "0.15.5"+__generated_with = "0.19.7"app = marimo.App()@@ -10,7 +10,6 @@ def _():import traitlets-class Widget(anywidget.AnyWidget):_esm = """function render({ model, el }) {@@ -21,7 +20,9 @@ def _():"""arr = traitlets.Dict().tag(sync=True)+import numpy as np+arr = np.array([1, 2, 3])Widget(arr={diff --git a/packages/openapi/api.yaml b/packages/openapi/api.yamlindex db31cefc49..ed58d6cb6e 100644--- a/packages/openapi/api.yaml+++ b/packages/openapi/api.yaml@@ -2322,7 +2322,7 @@ components:- $ref: '#/components/schemas/UpdateCellConfigCommand'- $ref: '#/components/schemas/InstallPackagesCommand'- $ref: '#/components/schemas/UpdateUIElementCommand'- - $ref: '#/components/schemas/UpdateWidgetModelCommand'+ - $ref: '#/components/schemas/ModelCommand'- $ref: '#/components/schemas/InvokeFunctionCommand'- $ref: '#/components/schemas/UpdateUserConfigCommand'- $ref: '#/components/schemas/PreviewDatasetColumnCommand'@@ -2351,6 +2351,7 @@ components:list-data-source-connection: '#/components/schemas/ListDataSourceConnectionCommand'list-secret-keys: '#/components/schemas/ListSecretKeysCommand'list-sql-tables: '#/components/schemas/ListSQLTablesCommand'+ model: '#/components/schemas/ModelCommand'preview-dataset-column: '#/components/schemas/PreviewDatasetColumnCommand'preview-sql-table: '#/components/schemas/PreviewSQLTableCommand'refresh-secrets: '#/components/schemas/RefreshSecretsCommand'@@ -2360,7 +2361,6 @@ components:update-cell-config: '#/components/schemas/UpdateCellConfigCommand'update-ui-element: '#/components/schemas/UpdateUIElementCommand'update-user-config: '#/components/schemas/UpdateUserConfigCommand'- update-widget-model: '#/components/schemas/UpdateWidgetModelCommand'validate-sql: '#/components/schemas/ValidateSQLCommand'propertyName: typedata_type:@@ -2409,6 +2409,7 @@ components:- $ref: '#/components/schemas/CellNotification'- $ref: '#/components/schemas/FunctionCallResultNotification'- $ref: '#/components/schemas/UIElementMessageNotification'+ - $ref: '#/components/schemas/ModelLifecycleNotification'- $ref: '#/components/schemas/RemoveUIElementsNotification'- $ref: '#/components/schemas/ReloadNotification'- $ref: '#/components/schemas/ReconnectedNotification'@@ -2459,6 +2460,7 @@ components:kernel-ready: '#/components/schemas/KernelReadyNotification'kernel-startup-error: '#/components/schemas/KernelStartupErrorNotification'missing-package-alert: '#/components/schemas/MissingPackageAlertNotification'+ model-lifecycle: '#/components/schemas/ModelLifecycleNotification'query-params-append: '#/components/schemas/QueryParamsAppendNotification'query-params-clear: '#/components/schemas/QueryParamsClearNotification'query-params-delete: '#/components/schemas/QueryParamsDeleteNotification'@@ -3027,11 +3029,193 @@ components:- isolatedtitle: MissingPackageAlertNotificationtype: object- ModelMessage:- description: "Widget model state update message.\n\n State changes for anywidget\- \ models, including state dict and binary buffer paths.\n\n Attributes:\n\- \ state: Model state updates.\n buffer_paths: Paths within state\- \ dict pointing to binary buffers."+ ModelClose:+ description: Widget destruction.+ properties:+ method:+ enum:+ - close+ required:+ - method+ title: ModelClose+ type: object+ ModelCommand:+ description: "Widget model message command.\n\n Handles widget model communication\+ \ between frontend and backend.\n\n Attributes:\n model_id: Widget\+ \ model identifier.\n message: Model message (update or custom).\n\+ \ buffers: Base64-encoded binary buffers."+ properties:+ buffers:+ items:+ contentEncoding: base64+ type: string+ type: array+ message:+ anyOf:+ - $ref: '#/components/schemas/ModelUpdateMessage'+ - $ref: '#/components/schemas/ModelCustomMessage'+ discriminator:+ mapping:+ custom: '#/components/schemas/ModelCustomMessage'+ update: '#/components/schemas/ModelUpdateMessage'+ propertyName: method+ modelId:+ type: string+ type:+ enum:+ - model+ required:+ - type+ - modelId+ - message+ - buffers+ title: ModelCommand+ type: object+ ModelCustom:+ description: Custom application message.+ properties:+ buffers:+ items:+ contentEncoding: base64+ type: string+ type: array+ content: {}+ method:+ enum:+ - custom+ required:+ - method+ - content+ - buffers+ title: ModelCustom+ type: object+ ModelCustomMessage:+ description: "Custom widget message.\n\n Attributes:\n content: Arbitrary\+ \ content for the custom message."+ properties:+ content: {}+ method:+ enum:+ - custom+ required:+ - method+ - content+ title: ModelCustomMessage+ type: object+ ModelLifecycleNotification:+ description: "Widget model lifecycle message.\n\n Mirrors the Jupyter widget\+ \ comm protocol with open/update/custom/close.\n\n Attributes:\n \+ \ model_id: Widget model identifier.\n message: The lifecycle message\+ \ (open/update/custom/close)."+ properties:+ message:+ anyOf:+ - $ref: '#/components/schemas/ModelOpen'+ - $ref: '#/components/schemas/ModelUpdate'+ - $ref: '#/components/schemas/ModelCustom'+ - $ref: '#/components/schemas/ModelClose'+ discriminator:+ mapping:+ close: '#/components/schemas/ModelClose'+ custom: '#/components/schemas/ModelCustom'+ open: '#/components/schemas/ModelOpen'+ update: '#/components/schemas/ModelUpdate'+ propertyName: method+ model_id:+ type: string+ op:+ enum:+ - model-lifecycle+ required:+ - op+ - model_id+ - message+ title: ModelLifecycleNotification+ type: object+ ModelOpen:+ description: Initial widget state on creation.+ properties:+ buffer_paths:+ items:+ items:+ anyOf:+ - type: string+ - type: integer+ type: array+ type: array+ buffers:+ items:+ contentEncoding: base64+ type: string+ type: array+ method:+ enum:+ - open+ state:+ type: object+ required:+ - method+ - state+ - buffer_paths+ - buffers+ title: ModelOpen+ type: object+ ModelRequest:+ properties:+ buffers:+ items:+ contentEncoding: base64+ type: string+ type: array+ message:+ anyOf:+ - $ref: '#/components/schemas/ModelUpdateMessage'+ - $ref: '#/components/schemas/ModelCustomMessage'+ discriminator:+ mapping:+ custom: '#/components/schemas/ModelCustomMessage'+ update: '#/components/schemas/ModelUpdateMessage'+ propertyName: method+ modelId:+ type: string+ required:+ - modelId+ - message+ - buffers+ title: ModelRequest+ type: object+ ModelUpdate:+ description: State sync - changed traits only.+ properties:+ buffer_paths:+ items:+ items:+ anyOf:+ - type: string+ - type: integer+ type: array+ type: array+ buffers:+ items:+ contentEncoding: base64+ type: string+ type: array+ method:+ enum:+ - update+ state:+ type: object+ required:+ - method+ - state+ - buffer_paths+ - buffers+ title: ModelUpdate+ type: object+ ModelUpdateMessage:+ description: "Widget model state update message.\n\n Attributes:\n \+ \ state: Model state updates.\n buffer_paths: Paths within state dict\+ \ pointing to binary buffers."properties:bufferPaths:items:@@ -3041,12 +3225,16 @@ components:- type: integertype: arraytype: array+ method:+ enum:+ - updatestate:type: objectrequired:+ - method- state- bufferPaths- title: ModelMessage+ title: ModelUpdateMessagetype: objectMultipleDefinitionError:properties:@@ -4379,51 +4567,6 @@ components:- configtitle: UpdateUserConfigRequesttype: object- UpdateWidgetModelCommand:- description: "Update anywidget model state.\n\n Updates widget model state\- \ for bidirectional Python-JavaScript communication.\n\n Attributes:\n\- \ model_id: Widget model identifier.\n message: Model message\- \ with state updates and buffer paths.\n buffers: Base64-encoded binary\- \ buffers referenced by buffer_paths."- properties:- buffers:- anyOf:- - items:- type: string- type: array- - type: 'null'- default: null- message:- $ref: '#/components/schemas/ModelMessage'- modelId:- type: string- type:- enum:- - update-widget-model- required:- - type- - modelId- - message- title: UpdateWidgetModelCommand- type: object- UpdateWidgetModelRequest:- properties:- buffers:- anyOf:- - items:- type: string- type: array- - type: 'null'- default: null- message:- $ref: '#/components/schemas/ModelMessage'- modelId:- type: string- required:- - modelId- - message- title: UpdateWidgetModelRequest- type: objectValidateSQLCommand:description: "Validate an SQL query.\n\n Checks if an SQL query is valid\\ by parsing against a dialect (no DB connection)\n or validating against\@@ -5666,7 +5809,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/UpdateWidgetModelRequest'+ $ref: '#/components/schemas/ModelRequest'responses:200:content:diff --git a/packages/openapi/src/api.ts b/packages/openapi/src/api.tsindex 008c414e99..ebd4b28548 100644--- a/packages/openapi/src/api.ts+++ b/packages/openapi/src/api.ts@@ -2212,7 +2212,7 @@ export interface paths {};requestBody?: {content: {- "application/json": components["schemas"]["UpdateWidgetModelRequest"];+ "application/json": components["schemas"]["ModelRequest"];};};responses: {@@ -4477,7 +4477,7 @@ export interface components {| components["schemas"]["UpdateCellConfigCommand"]| components["schemas"]["InstallPackagesCommand"]| components["schemas"]["UpdateUIElementCommand"]- | components["schemas"]["UpdateWidgetModelCommand"]+ | components["schemas"]["ModelCommand"]| components["schemas"]["InvokeFunctionCommand"]| components["schemas"]["UpdateUserConfigCommand"]| components["schemas"]["PreviewDatasetColumnCommand"]@@ -4518,6 +4518,7 @@ export interface components {| components["schemas"]["CellNotification"]| components["schemas"]["FunctionCallResultNotification"]| components["schemas"]["UIElementMessageNotification"]+ | components["schemas"]["ModelLifecycleNotification"]| components["schemas"]["RemoveUIElementsNotification"]| components["schemas"]["ReloadNotification"]| components["schemas"]["ReconnectedNotification"]@@ -4854,17 +4855,117 @@ export interface components {packages: string[];};/**- * ModelMessage- * @description Widget model state update message.+ * ModelClose+ * @description Widget destruction.+ */+ ModelClose: {+ /** @enum {unknown} */+ method: "close";+ };+ /**+ * ModelCommand+ * @description Widget model message command.+ *+ * Handles widget model communication between frontend and backend.*- * State changes for anywidget models, including state dict and binary buffer paths.+ * Attributes:+ * model_id: Widget model identifier.+ * message: Model message (update or custom).+ * buffers: Base64-encoded binary buffers.+ */+ ModelCommand: {+ buffers: string[];+ message:+ | components["schemas"]["ModelUpdateMessage"]+ | components["schemas"]["ModelCustomMessage"];+ modelId: string;+ /** @enum {unknown} */+ type: "model";+ };+ /**+ * ModelCustom+ * @description Custom application message.+ */+ ModelCustom: {+ buffers: string[];+ content: unknown;+ /** @enum {unknown} */+ method: "custom";+ };+ /**+ * ModelCustomMessage+ * @description Custom widget message.+ *+ * Attributes:+ * content: Arbitrary content for the custom message.+ */+ ModelCustomMessage: {+ content: unknown;+ /** @enum {unknown} */+ method: "custom";+ };+ /**+ * ModelLifecycleNotification+ * @description Widget model lifecycle message.+ *+ * Mirrors the Jupyter widget comm protocol with open/update/custom/close.+ *+ * Attributes:+ * model_id: Widget model identifier.+ * message: The lifecycle message (open/update/custom/close).+ */+ ModelLifecycleNotification: {+ message:+ | components["schemas"]["ModelOpen"]+ | components["schemas"]["ModelUpdate"]+ | components["schemas"]["ModelCustom"]+ | components["schemas"]["ModelClose"];+ model_id: string;+ /** @enum {unknown} */+ op: "model-lifecycle";+ };+ /**+ * ModelOpen+ * @description Initial widget state on creation.+ */+ ModelOpen: {+ buffer_paths: (string | number)[][];+ buffers: string[];+ /** @enum {unknown} */+ method: "open";+ state: Record<string, any>;+ };+ /** ModelRequest */+ ModelRequest: {+ buffers: string[];+ message:+ | components["schemas"]["ModelUpdateMessage"]+ | components["schemas"]["ModelCustomMessage"];+ modelId: string;+ };+ /**+ * ModelUpdate+ * @description State sync - changed traits only.+ */+ ModelUpdate: {+ buffer_paths: (string | number)[][];+ buffers: string[];+ /** @enum {unknown} */+ method: "update";+ state: Record<string, any>;+ };+ /**+ * ModelUpdateMessage+ * @description Widget model state update message.** Attributes:* state: Model state updates.* buffer_paths: Paths within state dict pointing to binary buffers.*/- ModelMessage: {+ ModelUpdateMessage: {bufferPaths: (string | number)[][];+ /** @enum {unknown} */+ method: "update";state: Record<string, any>;};/** MultipleDefinitionError */@@ -5720,32 +5821,6 @@ export interface components {UpdateUserConfigRequest: {config: components["schemas"]["MarimoConfig"];};- /**- * UpdateWidgetModelCommand- * @description Update anywidget model state.- *- * Updates widget model state for bidirectional Python-JavaScript communication.- *- * Attributes:- * model_id: Widget model identifier.- * message: Model message with state updates and buffer paths.- * buffers: Base64-encoded binary buffers referenced by buffer_paths.- */- UpdateWidgetModelCommand: {- /** @default null */- buffers?: string[] | null;- message: components["schemas"]["ModelMessage"];- modelId: string;- /** @enum {unknown} */- type: "update-widget-model";- };- /** UpdateWidgetModelRequest */- UpdateWidgetModelRequest: {- /** @default null */- buffers?: string[] | null;- message: components["schemas"]["ModelMessage"];- modelId: string;- };/*** ValidateSQLCommand* @description Validate an SQL query.diff --git a/tests/_internal/snapshots/internal_api.txt b/tests/_internal/snapshots/internal_api.txtindex 0aa2931baf..13fdd6a742 100644--- a/tests/_internal/snapshots/internal_api.txt+++ b/tests/_internal/snapshots/internal_api.txt@@ -19,6 +19,7 @@ commandsListOrValueListSQLTablesCommandListSecretKeysCommand+ ModelCommandModelMessagePreviewDatasetColumnCommandPreviewSQLTableCommand@@ -32,7 +33,6 @@ commandsUpdateCellConfigCommandUpdateUIElementCommandUpdateUserConfigCommand- UpdateWidgetModelCommandValidateSQLCommandkebab_caseconfigdiff --git a/tests/_plugins/ui/_impl/anywidget/test_anywidget_utils.py b/tests/_plugins/ui/_impl/anywidget/test_anywidget_utils.pyindex 319b8412ae..551acacc3a 100644--- a/tests/_plugins/ui/_impl/anywidget/test_anywidget_utils.py+++ b/tests/_plugins/ui/_impl/anywidget/test_anywidget_utils.py@@ -4,11 +4,7 @@ from __future__ import annotationsimport pytestfrom marimo._dependencies.dependencies import DependencyManager-from marimo._plugins.ui._impl.anywidget.utils import (- extract_buffer_paths,- insert_buffer_paths,- is_model_message,-)+from marimo._plugins.ui._impl.anywidget.utils import extract_buffer_pathsHAS_DEPS = DependencyManager.ipywidgets.has()@@ -31,35 +27,3 @@ def test_extract_buffer_paths():assert buffers[0] == b"test"assert state["other"] == "not a buffer"assert "value" not in state--[email protected](not HAS_DEPS, reason="ipywidgets is not installed")-def test_insert_buffer_paths():- # Test inserting buffers back into state- state = {"method": "update", "state": {"other": "not a buffer"}}- buffer_paths = [["state", "value"]]- buffers = [b"test"]-- result = insert_buffer_paths(state, buffer_paths, buffers)-- assert isinstance(result, dict)- assert result["state"]["value"] == b"test"- assert result["state"]["other"] == "not a buffer"--[email protected](not HAS_DEPS, reason="ipywidgets is not installed")-def test_is_model_message():- # Test valid model message- valid_message = {- "method": "update",- "state": {"value": "test"},- "buffer_paths": [],- }- assert is_model_message(valid_message) is True-- # Test invalid messages- assert is_model_message({}) is False- assert is_model_message({"method": "update"}) is False- assert is_model_message({"state": {}, "buffer_paths": []}) is False- assert is_model_message(None) is False- assert is_model_message("not a dict") is Falsediff --git a/tests/_plugins/ui/_impl/test_anywidget.py b/tests/_plugins/ui/_impl/test_anywidget.pyindex e4b25ef5f5..bd75cba987 100644--- a/tests/_plugins/ui/_impl/test_anywidget.py+++ b/tests/_plugins/ui/_impl/test_anywidget.py@@ -12,9 +12,8 @@ from marimo._plugins.ui._core.ui_element import UIElementfrom marimo._plugins.ui._impl.from_anywidget import (WeakCache,anywidget,- decode_from_wire,- encode_to_wire,from_anywidget,+ get_anywidget_state,)from marimo._runtime.commands import UpdateUIElementCommandfrom marimo._runtime.runtime import Kernel@@ -189,11 +188,10 @@ x = as_marimo_element.count@staticmethodasync def test_initialization() -> None:wrapped = anywidget(Widget(arr={"a": 1}))- assert wrapped._initial_value == {- "state": {"arr": {"a": 1}},- "bufferPaths": [],- "buffers": [],- }+ # _initial_value is always a model_id reference+ assert "model_id" in wrapped._initial_value_frontend+ assert len(wrapped._initial_value_frontend) == 1+ assert isinstance(wrapped._initial_value_frontend["model_id"], str)assert wrapped._component_args == {"css": "","js-url": "",@@ -202,19 +200,14 @@ x = as_marimo_element.count@staticmethodasync def test_initialization_with_dataview() -> None:- # Create a simple array-like structure without numpy- import base64-arr = [1, 2, 3]wrapped = anywidget(Widget(arr={"bytes": bytes(arr), "shape": (len(arr),)}))- # _initial_value is wire format (buffers are extracted to separate array)- assert wrapped._initial_value == {- "state": {"arr": {"shape": (3,)}},- "bufferPaths": [["arr", "bytes"]],- "buffers": [base64.b64encode(bytes([1, 2, 3])).decode("utf-8")],- }+ # _initial_value is always a model_id reference+ assert "model_id" in wrapped._initial_value_frontend+ assert len(wrapped._initial_value_frontend) == 1+ assert isinstance(wrapped._initial_value_frontend["model_id"], str)assert wrapped._component_args == {"css": "","js-url": "",@@ -246,14 +239,10 @@ x = as_marimo_element.countnon_serializable = traitlets.Instance(object, sync=True)wrapped = anywidget(NonSerializableWidget())- assert wrapped._initial_value == {- "state": {- "serializable": 1,- "non_serializable": None,- },- "bufferPaths": [],- "buffers": [],- }+ # _initial_value is always a model_id reference+ assert "model_id" in wrapped._initial_value_frontend+ assert len(wrapped._initial_value_frontend) == 1+ assert isinstance(wrapped._initial_value_frontend["model_id"], str)@staticmethodasync def test_skips_non_sync_traits() -> None:@@ -263,13 +252,11 @@ x = as_marimo_element.countsync = traitlets.Int(2).tag(sync=True)wrapped = anywidget(NonSyncWidget())- assert wrapped._initial_value == {- "state": {"sync": 2},- "bufferPaths": [],- "buffers": [],- }+ # _initial_value is always a model_id reference+ assert "model_id" in wrapped._initial_value_frontend+ assert len(wrapped._initial_value_frontend) == 1+ assert isinstance(wrapped._initial_value_frontend["model_id"], str)- @staticmethod@staticmethodasync def test_frontend_changes(k: Kernel, exec_req: ExecReqProvider@@ -307,8 +294,6 @@ x = as_marimo_element.count@staticmethodasync def test_buffers() -> None:- import base64-class BufferWidget(_anywidget.AnyWidget):_esm = ""array = traitlets.Bytes().tag(sync=True)@@ -316,22 +301,18 @@ x = as_marimo_element.countdata = bytes([1, 2, 3, 4])wrapped = anywidget(BufferWidget(array=data))- # _initial_value is wire format (buffers are extracted to separate array)- assert wrapped._initial_value == {- "state": {},- "bufferPaths": [["array"]],- "buffers": [base64.b64encode(data).decode("utf-8")],- }+ # _initial_value is always a model_id reference+ assert "model_id" in wrapped._initial_value_frontend+ assert len(wrapped._initial_value_frontend) == 1+ assert isinstance(wrapped._initial_value_frontend["model_id"], str)- # test buffers are inlined as base64 in the wire format- assert "AQIDBA==" in wrapped.text- assert "array" in wrapped.text+ # The value property reads directly from the widget+ assert wrapped.value["array"] == data- # Test updating the buffer+ # Test updating the buffer - now updates the widget directlynew_data = bytes([5, 6, 7, 8])wrapped.array = new_data- # value property returns decoded state with buffers re-inserted- assert wrapped.value["array"] == data+ assert wrapped.value["array"] == new_data@staticmethodasync def test_error_handling() -> None:@@ -348,11 +329,11 @@ x = as_marimo_element.countwrapped = anywidget(ErrorWidget())- # Test invalid update+ # Test valid update - now the widget is updated directlywrapped.value = 5- assert wrapped.value == {"value": 0}+ assert wrapped.value == {"value": 5}- # Test invalid update+ # Test invalid update - should raise ValueErrorwith pytest.raises(ValueError):wrapped.value = -1@@ -492,6 +473,31 @@ x = as_marimo_element.countassert len(_cache) == old_len - 1+ @staticmethod+ async def test_get_anywidget_state() -> None:+ """Test get_anywidget_state filters out system traits."""++ class StateWidget(_anywidget.AnyWidget):+ _esm = "export default { render() {} }"+ _css = "button { color: red; }"+ count = traitlets.Int(42).tag(sync=True)+ name = traitlets.Unicode("test").tag(sync=True)++ widget = StateWidget()+ state = get_anywidget_state(widget)++ # Should include user-defined traits+ assert state["count"] == 42+ assert state["name"] == "test"++ # Should NOT include system traits+ assert "_esm" not in state+ assert "_css" not in state+ assert "comm" not in state+ assert "layout" not in state+ assert "_model_module" not in state+ assert "_view_name" not in state+@staticmethodasync def test_partial_state_updates() -> None:class MultiTraitWidget(_anywidget.AnyWidget):@@ -515,10 +521,6 @@ x = as_marimo_element.countwrapped._update({"a": 100, "b": 200, "c": 300})assert wrapped.value == {"a": 100, "b": 200, "c": 300}- # Test updating with new traits- wrapped._update({"d": 4})- assert wrapped.value == {"a": 100, "b": 200, "c": 300, "d": 4}-@staticmethodasync def test_getitem_and_contains() -> None:"""Test that __getitem__ and __contains__ are forwarded to the widget."""@@ -548,200 +550,3 @@ x = as_marimo_element.count# Test KeyError propagationwith pytest.raises(KeyError):_ = wrapped["nonexistent"]--[email protected](not HAS_DEPS, reason="optional dependencies not installed")-class TestWireFormat:- """Tests for encode_to_wire and decode_from_wire functions."""-- @staticmethod- def test_decode_from_wire_not_wire_format() -> None:- """Test that non-wire format dicts are returned as-is."""- plain_dict = {"a": 1, "b": 2}- result = decode_from_wire(plain_dict)- assert result == plain_dict-- # Test with only state- partial_wire = {"state": {"a": 1}}- result = decode_from_wire(partial_wire)- assert result == partial_wire-- @staticmethod- def test_decode_from_wire_empty_buffers() -> None:- """Test decoding wire format with no buffers."""- wire = {"state": {"a": 1, "b": 2}, "bufferPaths": [], "buffers": []}- result = decode_from_wire(wire)- assert result == {"a": 1, "b": 2}-- @staticmethod- def test_decode_from_wire_with_buffers() -> None:- """Test decoding wire format with base64 buffers."""- import base64-- data = b"Hello, World!"- base64_data = base64.b64encode(data).decode("utf-8")-- wire = {- "state": {"text": base64_data, "number": 42},- "bufferPaths": [["text"]],- "buffers": [base64_data],- }-- result = decode_from_wire(wire)- assert result["number"] == 42- assert result["text"] == data-- @staticmethod- def test_decode_from_wire_nested_buffers() -> None:- """Test decoding wire format with nested buffer paths."""- import base64-- data1 = b"first"- data2 = b"second"- base64_1 = base64.b64encode(data1).decode("utf-8")- base64_2 = base64.b64encode(data2).decode("utf-8")-- wire = {- "state": {- "nested": {"buf1": base64_1, "deeper": {"buf2": base64_2}}- },- "bufferPaths": [["nested", "buf1"], ["nested", "deeper", "buf2"]],- "buffers": [base64_1, base64_2],- }-- result = decode_from_wire(wire)- assert result["nested"]["buf1"] == data1- assert result["nested"]["deeper"]["buf2"] == data2-- @staticmethod- def test_decode_from_wire_array_buffers() -> None:- """Test decoding wire format with buffers in arrays."""- import base64-- data = b"test"- base64_data = base64.b64encode(data).decode("utf-8")-- wire = {- "state": {"items": [base64_data, "middle", base64_data]},- "bufferPaths": [["items", 0], ["items", 2]],- "buffers": [base64_data, base64_data],- }-- result = decode_from_wire(wire)- assert result["items"][0] == data- assert result["items"][1] == "middle"- assert result["items"][2] == data-- @staticmethod- def test_encode_to_wire_no_buffers() -> None:- """Test encoding state without buffers."""- state = {"a": 1, "b": "text", "c": {"d": True}}- result = encode_to_wire(state)-- assert result["state"] == state- assert result["bufferPaths"] == []- assert result["buffers"] == []-- @staticmethod- def test_encode_to_wire_with_bytes() -> None:- """Test encoding state with bytes."""- import base64-- data = b"Hello, World!"- state = {"text": data, "number": 42}-- result = encode_to_wire(state)-- assert result["state"]["number"] == 42- # The buffer should be extracted- assert len(result["buffers"]) == 1- assert len(result["bufferPaths"]) == 1- # Verify the buffer is base64 encoded- decoded = base64.b64decode(result["buffers"][0])- assert decoded == data-- @staticmethod- def test_encode_to_wire_nested_bytes() -> None:- """Test encoding state with nested bytes."""- import base64-- data1 = b"first"- data2 = b"second"- state = {- "nested": {"buf1": data1, "deeper": {"buf2": data2}},- "regular": "value",- }-- result = encode_to_wire(state)-- assert result["state"]["regular"] == "value"- assert len(result["buffers"]) == 2- assert len(result["bufferPaths"]) == 2-- # Verify buffers are base64 encoded- buffers = [base64.b64decode(b) for b in result["buffers"]]- assert data1 in buffers- assert data2 in buffers-- @staticmethod- def test_round_trip_encoding() -> None:- """Test that encode -> decode -> encode produces consistent results."""- original_state = {- "buffer": b"test data",- "nested": {"inner_buffer": b"more data"},- "text": "plain text",- "number": 123,- }-- # Encode to wire format- encoded = encode_to_wire(original_state)-- # Decode back- decoded = decode_from_wire(encoded)-- # Verify decoded state matches original- assert decoded["buffer"] == b"test data"- assert decoded["nested"]["inner_buffer"] == b"more data"- assert decoded["text"] == "plain text"- assert decoded["number"] == 123-- # Re-encode- re_encoded = encode_to_wire(decoded)-- # Verify structure is consistent- assert len(re_encoded["buffers"]) == len(encoded["buffers"])- assert len(re_encoded["bufferPaths"]) == len(encoded["bufferPaths"])-- # Verify buffers match (order might differ, so compare sets)- encoded_buffers = set(encoded["buffers"])- re_encoded_buffers = set(re_encoded["buffers"])- assert encoded_buffers == re_encoded_buffers-- @staticmethod- def test_encode_to_wire_empty_bytes() -> None:- """Test encoding empty bytes."""- import base64-- state = {"empty": b"", "data": b"content"}- result = encode_to_wire(state)-- assert len(result["buffers"]) == 2- # Verify empty bytes is properly encoded- assert (- base64.b64decode(result["buffers"][0]) == b""- or base64.b64decode(result["buffers"][1]) == b""- )-- @staticmethod- def test_decode_from_wire_missing_buffers() -> None:- """Test decoding when bufferPaths exist but buffers are missing."""- wire = {- "state": {"a": 1},- "bufferPaths": [["a"]],- # Missing buffers array- }-- # Should handle gracefully - buffers default to []- result = decode_from_wire(wire)- # State should be returned but buffers won't be inserted- assert "a" in resultdiff --git a/tests/_plugins/ui/_impl/test_comm.py b/tests/_plugins/ui/_impl/test_comm.pyindex 1709b82f06..e3a6a9fb5d 100644--- a/tests/_plugins/ui/_impl/test_comm.py+++ b/tests/_plugins/ui/_impl/test_comm.py@@ -5,12 +5,13 @@ from unittest.mock import MagicMock, patchimport pytestfrom marimo._plugins.ui._impl.comm import (- COMM_CLOSE_NAME,- COMM_MESSAGE_NAME,- COMM_OPEN_NAME,MarimoComm,MarimoCommManager,- MessageBufferData,+)+from marimo._runtime.commands import (+ ModelCommand,+ ModelCustomMessage,+ ModelUpdateMessage,)from marimo._types.ids import WidgetModelId@@ -23,18 +24,19 @@ def comm_manager():@pytest.fixturedef comm(comm_manager: MarimoCommManager) -> MarimoComm:comm_id = WidgetModelId("test-comm")- return MarimoComm(- comm_id=comm_id,- comm_manager=comm_manager,- target_name="test_target",- )+ with patch("marimo._plugins.ui._impl.comm.broadcast_notification"):+ return MarimoComm(+ comm_id=comm_id,+ comm_manager=comm_manager,+ target_name="test_target",+ )def test_comm_manager_register_unregister(comm_manager: MarimoCommManager, comm: MarimoComm):- # Test registration- comm_id = comm_manager.register_comm(comm)+ # comm is already registered during __init__+ comm_id = comm.comm_idassert comm_id in comm_manager.commsassert comm_manager.comms[comm_id] == comm@@ -48,11 +50,12 @@ def test_comm_manager_receive_unknown_message(comm_manager: MarimoCommManager,):with patch("marimo._plugins.ui._impl.comm.LOGGER") as mock_logger:- comm_manager.receive_comm_message(- WidgetModelId("unknown"),- MagicMock(),- None,+ command = ModelCommand(+ model_id=WidgetModelId("unknown"),+ message=ModelUpdateMessage(state={}, buffer_paths=[]),+ buffers=[],)+ comm_manager.receive_comm_message(command)mock_logger.warning.assert_called_once()@@ -66,47 +69,34 @@ def test_comm_initialization(comm: MarimoComm):def test_comm_open(comm: MarimoComm):- with patch.object(comm, "_publish_msg") as mock_publish:+ with patch.object(comm, "_broadcast") as mock_broadcast:comm.open(data={"test": "data"})- mock_publish.assert_called_once_with(- COMM_OPEN_NAME,- data={"test": "data"},- metadata=None,- buffers=None,- target_name="test_target",- target_module=None,- )+ mock_broadcast.assert_called_once_with({"test": "data"}, [])assert not comm._closeddef test_comm_send(comm: MarimoComm):- with patch.object(comm, "_publish_msg") as mock_publish:+ with patch.object(comm, "_broadcast") as mock_broadcast:comm.send(data={"test": "data"})- mock_publish.assert_called_once_with(- COMM_MESSAGE_NAME,- data={"test": "data"},- metadata=None,- buffers=None,- )+ mock_broadcast.assert_called_once_with({"test": "data"}, [])def test_comm_close(comm: MarimoComm):- with patch.object(comm, "_publish_msg") as mock_publish:+ with patch(+ "marimo._plugins.ui._impl.comm.broadcast_notification"+ ) as mock_broadcast:comm.close(data={"test": "data"})- mock_publish.assert_called_once_with(- COMM_CLOSE_NAME,- data={"test": "data"},- metadata=None,- buffers=None,- )+ mock_broadcast.assert_called_once()assert comm._closeddef test_comm_close_already_closed(comm: MarimoComm):comm._closed = True- with patch.object(comm, "_publish_msg") as mock_publish:+ with patch(+ "marimo._plugins.ui._impl.comm.broadcast_notification"+ ) as mock_broadcast:comm.close()- mock_publish.assert_not_called()+ mock_broadcast.assert_not_called()def test_comm_on_msg(comm: MarimoComm):@@ -148,29 +138,55 @@ def test_comm_handle_close_no_callback(comm: MarimoComm):with patch("marimo._plugins.ui._impl.comm.LOGGER") as mock_logger:msg = {"test": "message"}comm.handle_close(msg)- mock_logger.warning.assert_called_once()+ mock_logger.debug.assert_called()-def test_comm_flush(comm: MarimoComm):- test_data = {"test": "data"}- test_metadata = {"meta": "data"}- test_buffers = [b"test_buffer"]+def test_comm_broadcast(comm: MarimoComm):+ """Test that _broadcast sends a ModelLifecycleNotification."""+ with patch(+ "marimo._plugins.ui._impl.comm.broadcast_notification"+ ) as mock_broadcast:+ comm._broadcast({"method": "update", "state": {"key": "value"}}, [])+ mock_broadcast.assert_called_once()+ notification = mock_broadcast.call_args[0][0]+ assert notification.model_id == comm.comm_id- comm._publish_message_buffer.append(- MessageBufferData(- data=test_data,- metadata=test_metadata,- buffers=test_buffers,- model_id=comm.comm_id,- )++def test_comm_manager_receive_update_message(+ comm_manager: MarimoCommManager, comm: MarimoComm+):+ """Test receiving an update message through the comm manager."""+ callback = MagicMock()+ comm.on_msg(callback)+ comm.ui_element_id = "test-element"++ command = ModelCommand(+ model_id=comm.comm_id,+ message=ModelUpdateMessage(+ state={"key": "value"},+ buffer_paths=[],+ ),+ buffers=[],)+ result = comm_manager.receive_comm_message(command)+ assert result == ("test-element", {"key": "value"})+ callback.assert_called_once()- with patch(- "marimo._messaging.notification.UIElementMessageNotification"- ) as MockSendUIElementMessage:- comm.flush()- MockSendUIElementMessage.assert_called_once()- call_args = MockSendUIElementMessage.call_args[1]- assert call_args["model_id"] == comm.comm_id- assert call_args["message"] == test_data- assert call_args["buffers"] == [b"test_buffer"]++def test_comm_manager_receive_custom_message(+ comm_manager: MarimoCommManager, comm: MarimoComm+):+ """Test receiving a custom message through the comm manager."""+ callback = MagicMock()+ comm.on_msg(callback)++ command = ModelCommand(+ model_id=comm.comm_id,+ message=ModelCustomMessage(+ content={"custom": "data"},+ ),+ buffers=[],+ )+ result = comm_manager.receive_comm_message(command)+ assert result == (None, None)+ callback.assert_called_once()diff --git a/tests/_pyodide/test_pyodide_session.py b/tests/_pyodide/test_pyodide_session.pyindex 1859168e22..177e7d05ee 100644--- a/tests/_pyodide/test_pyodide_session.py+++ b/tests/_pyodide/test_pyodide_session.py@@ -34,6 +34,7 @@ from marimo._runtime.commands import (ListDataSourceConnectionCommand,ListSecretKeysCommand,ListSQLTablesCommand,+ ModelCommand,PreviewDatasetColumnCommand,PreviewSQLTableCommand,RefreshSecretsCommand,@@ -42,7 +43,6 @@ from marimo._runtime.commands import (SyncGraphCommand,UpdateCellConfigCommand,UpdateUIElementCommand,- UpdateWidgetModelCommand,ValidateSQLCommand,)from marimo._runtime.context.types import teardown_context@@ -406,8 +406,8 @@ async def test_pyodide_session_put_input(UpdateUIElementCommand,),(- '{"type": "update-widget-model", "modelId": "model-1", "message": {"state": {}, "bufferPaths": []}}',- UpdateWidgetModelCommand,+ '{"type": "model", "modelId": "model-1", "message": {"method": "update", "state": {}, "bufferPaths": []}, "buffers": []}',+ ModelCommand,),('{"type": "invoke-function", "functionCallId": "fc-1", "namespace": "test", "functionName": "foo", "args": {}}',diff --git a/tests/_server/api/endpoints/test_execution.py b/tests/_server/api/endpoints/test_execution.pyindex 888fb690ef..33b1b558f6 100644--- a/tests/_server/api/endpoints/test_execution.py+++ b/tests/_server/api/endpoints/test_execution.py@@ -97,10 +97,11 @@ class TestExecutionRoutes_EditMode:json={"modelId": "model-1","message": {+ "method": "update","state": {"key": "value"},"bufferPaths": [["a"], ["b"]],},- "buffers": ["buffer1", "buffer2"],+ "buffers": ["YnVmZmVyMQ==", "YnVmZmVyMg=="],},)assert response.status_code == 200, response.text@@ -296,10 +297,11 @@ class TestExecutionRoutes_RunMode:json={"modelId": "model-1","message": {+ "method": "update","state": {"key": "value"},"bufferPaths": [["a"], ["b"]],},- "buffers": ["buffer1", "buffer2"],+ "buffers": ["YnVmZmVyMQ==", "YnVmZmVyMg=="],},)assert response.status_code == 200, response.text