Skip to content

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

fix: decouple anywidget model and view (#8124)

Myles Scolnick973eefcb4679
diff --git a/frontend/benchmarks/base64-conversion.bench.ts b/frontend/benchmarks/base64-conversion.bench.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 field
diff --git a/frontend/src/core/islands/bridge.ts b/frontend/src/core/islands/bridge.ts
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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 CSS
useEffect(() => {
- 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-rendering
el.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.tsx
index 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 implementation
const 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 render
await 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 render
await 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 widget
await 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.ts
index 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 change
expect(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(); // flush
expect(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 test
modelManager = 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.ts
similarity index 79%
rename from frontend/src/utils/__tests__/data-views.test.ts
rename to frontend/src/plugins/impl/anywidget/__tests__/serialization.test.ts
index 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 property
expect("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.ts
index 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 hanging
setTimeout(() => {
@@ -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.ts
new file mode 100644
index 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.ts
similarity index 75%
rename from frontend/src/utils/data-views.ts
rename to frontend/src/plugins/impl/anywidget/serialization.ts
index 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.ts
new file mode 100644
index 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.tsx
index 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 process
const 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.ts
index 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.ts
index 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.py
index 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.py
index 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.py
index 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 lifecycle
ReloadNotification,
diff --git a/marimo/_plugins/ui/_impl/anywidget/init.py b/marimo/_plugins/ui/_impl/anywidget/init.py
index 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 messages
diff --git a/marimo/_plugins/ui/_impl/anywidget/types.py b/marimo/_plugins/ui/_impl/anywidget/types.py
index 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 id
WidgetModelId = NewType("WidgetModelId", str)
@@ -14,47 +14,3 @@ WidgetModelState = dict[str, Any]
# Widget model state without buffers
WidgetModelStateWithoutBuffers = 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.py
index 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 DependencyManager
from 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: ignore
return 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 True
diff --git a/marimo/_plugins/ui/_impl/comm.py b/marimo/_plugins/ui/_impl/comm.py
index 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, Optional
from 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 # unused
self._msg_callback: Optional[MsgCallback] = None
self._close_callback: Optional[MsgCallback] = None
self._closed: bool = False
@@ -100,46 +135,44 @@ class MarimoComm:
self.comm_manager = comm_manager
self.target_name = target_name
self.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 = False
except 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:
return
self._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 unregistered
self.comm_manager.unregister_comm(self)
- # trigger close on gc
def __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 = callback
def 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.py
index 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 hashlib
import weakref
from copy import deepcopy
-from dataclasses import dataclass
from typing import (
TYPE_CHECKING,
Any,
Generic,
- Optional,
+ TypeAlias,
TypedDict,
TypeVar,
cast,
@@ -20,58 +17,25 @@ import marimo._output.data.data as mo_data
from marimo import _loggers
from marimo._output.rich_help import mddoc
from 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: AnyWidgetState
bufferPaths: 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: WidgetModelId
if 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' message
super().__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 value
raise RuntimeError("Setting the value of a UIElement is not allowed.")
diff --git a/marimo/_runtime/commands.py b/marimo/_runtime/commands.py
index 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: WidgetModelId
message: 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 operations
UpdateUIElementCommand,
- UpdateWidgetModelCommand,
+ ModelCommand,
InvokeFunctionCommand,
# User/configuration operations
UpdateUserConfigCommand,
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index 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)
# Datasets
diff --git a/marimo/_server/api/endpoints/execution.py b/marimo/_server/api/endpoints/execution.py
index 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 APIRouter
from 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.py
index 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.py
index 084e79284f..e0e7d0f909 100644
--- a/marimo/_session/state/session_view.py
+++ b/marimo/_session/state/session_view.py
@@ -303,7 +303,9 @@ class SessionView:
return
messages = 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] = messages
elif 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.py
index 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.py
index 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_bound
diff --git a/marimo/_smoke_tests/anywidget_examples/scatter.py b/marimo/_smoke_tests/anywidget_examples/scatter.py
index 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 jscatter
import 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.py
index 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.value
return
@@ -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.cell
def _():
+ thing = {"a": 0}
+ return (thing,)
+
+
+def _(q, thing):
+ # Check gets update only once
+ thing["a"] += 1
+ print(thing["a"])
+
+ q.data()
return
diff --git a/marimo/_smoke_tests/anywidget_smoke_tests/multiple_models.py b/marimo/_smoke_tests/anywidget_smoke_tests/multiple_models.py
index 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.py
index 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 anywidget
import 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 widget
diff --git a/marimo/_smoke_tests/issues/2366-anywidget-binary.py b/marimo/_smoke_tests/issues/2366-anywidget-binary.py
index 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.yaml
index 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: type
data_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:
- isolated
title: MissingPackageAlertNotification
type: 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: integer
type: array
type: array
+ method:
+ enum:
+ - update
state:
type: object
required:
+ - method
- state
- bufferPaths
- title: ModelMessage
+ title: ModelUpdateMessage
type: object
MultipleDefinitionError:
properties:
@@ -4379,51 +4567,6 @@ components:
- config
title: UpdateUserConfigRequest
type: 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: object
ValidateSQLCommand:
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.ts
index 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.txt
index 0aa2931baf..13fdd6a742 100644
--- a/tests/_internal/snapshots/internal_api.txt
+++ b/tests/_internal/snapshots/internal_api.txt
@@ -19,6 +19,7 @@ commands
ListOrValue
ListSQLTablesCommand
ListSecretKeysCommand
+ ModelCommand
ModelMessage
PreviewDatasetColumnCommand
PreviewSQLTableCommand
@@ -32,7 +33,6 @@ commands
UpdateCellConfigCommand
UpdateUIElementCommand
UpdateUserConfigCommand
- UpdateWidgetModelCommand
ValidateSQLCommand
kebab_case
config
diff --git a/tests/_plugins/ui/_impl/anywidget/test_anywidget_utils.py b/tests/_plugins/ui/_impl/anywidget/test_anywidget_utils.py
index 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 annotations
import pytest
from 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_paths
HAS_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 False
diff --git a/tests/_plugins/ui/_impl/test_anywidget.py b/tests/_plugins/ui/_impl/test_anywidget.py
index 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 UIElement
from 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 UpdateUIElementCommand
from marimo._runtime.runtime import Kernel
@@ -189,11 +188,10 @@ x = as_marimo_element.count
@staticmethod
async 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
@staticmethod
async 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.count
non_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)
@staticmethod
async def test_skips_non_sync_traits() -> None:
@@ -263,13 +252,11 @@ x = as_marimo_element.count
sync = 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
@staticmethod
async def test_frontend_changes(
k: Kernel, exec_req: ExecReqProvider
@@ -307,8 +294,6 @@ x = as_marimo_element.count
@staticmethod
async 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.count
data = 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 directly
new_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
@staticmethod
async def test_error_handling() -> None:
@@ -348,11 +329,11 @@ x = as_marimo_element.count
wrapped = anywidget(ErrorWidget())
- # Test invalid update
+ # Test valid update - now the widget is updated directly
wrapped.value = 5
- assert wrapped.value == {"value": 0}
+ assert wrapped.value == {"value": 5}
- # Test invalid update
+ # Test invalid update - should raise ValueError
with pytest.raises(ValueError):
wrapped.value = -1
@@ -492,6 +473,31 @@ x = as_marimo_element.count
assert 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
+
@staticmethod
async def test_partial_state_updates() -> None:
class MultiTraitWidget(_anywidget.AnyWidget):
@@ -515,10 +521,6 @@ x = as_marimo_element.count
wrapped._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}
-
@staticmethod
async 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 propagation
with 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 result
diff --git a/tests/_plugins/ui/_impl/test_comm.py b/tests/_plugins/ui/_impl/test_comm.py
index 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, patch
import pytest
from 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.fixture
def 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_id
assert comm_id in comm_manager.comms
assert 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._closed
def 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._closed
def 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.py
index 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.py
index 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