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.

Unify handling of widget state/buffers/bufferPaths (#7441)

Myles Scolnicke9741235a194
diff --git a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
index be7104fcef..9f8a970270 100644
--- a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
+++ b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
@@ -2,8 +2,9 @@
/* eslint-disable @typescript-eslint/no-explicit-any */
import type { AnyWidget, Experimental } from "@anywidget/types";
-import { get, isEqual, set } from "lodash-es";
+import { isEqual } from "lodash-es";
import { useEffect, useMemo, useRef } from "react";
+import useEvent from "react-use-event-hook";
import { z } from "zod";
import { MarimoIncomingMessageEvent } from "@/core/dom/events";
import { asRemoteURL } from "@/core/runtime/config";
@@ -17,10 +18,13 @@ import { createPlugin } from "@/plugins/core/builder";
import { rpc } from "@/plugins/core/rpc";
import type { IPluginProps } from "@/plugins/types";
import {
- type Base64String,
- byteStringToBinary,
- typedAtob,
-} from "@/utils/json/base64";
+ 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";
@@ -29,44 +33,56 @@ interface Data {
jsUrl: string;
jsHash: string;
css?: string | null;
- bufferPaths?: (string | number)[][] | null;
- initialValue: T;
}
-type T = Record<string, any>;
+type T = Record<string, unknown>;
-// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
type PluginFunctions = {
- send_to_widget: <T>(req: { content?: any }) => Promise<null | undefined>;
+ send_to_widget: <T>(req: {
+ content: unknown;
+ buffers: Base64String[];
+ }) => Promise<null | undefined>;
};
-export const AnyWidgetPlugin = createPlugin<T>("marimo-anywidget")
+export const AnyWidgetPlugin = createPlugin<WireFormat<T>>("marimo-anywidget")
.withData(
z.object({
jsUrl: z.string(),
jsHash: z.string(),
css: z.string().nullish(),
- bufferPaths: z
- .array(z.array(z.union([z.string(), z.number()])))
- .nullish(),
- initialValue: z.object({}).passthrough(),
}),
)
.withFunctions<PluginFunctions>({
send_to_widget: rpc
- .input(z.object({ content: z.any() }))
+ .input(
+ z.object({
+ content: z.unknown(),
+ buffers: z.array(z.string().transform((v) => v as Base64String)),
+ }),
+ )
.output(z.null().optional()),
})
.renderer((props) => <AnyWidgetSlot {...props} />);
-type Props = IPluginProps<T, Data, PluginFunctions>;
-
-const AnyWidgetSlot = (props: Props) => {
- const { css, jsUrl, jsHash, bufferPaths } = props.data;
+const AnyWidgetSlot = (
+ props: IPluginProps<WireFormat<T>, Data, PluginFunctions>,
+) => {
+ const { css, jsUrl, jsHash } = props.data;
+ // Decode wire format { state, bufferPaths, buffers } to state with DataViews
const valueWithBuffers = useMemo(() => {
- return resolveInitialValue(props.value, bufferPaths ?? []);
- }, [props.value, bufferPaths]);
+ 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]);
// JS is an ESM file with a render function on it
// export function render({ model, el }) {
@@ -135,6 +151,12 @@ const AnyWidgetSlot = (props: Props) => {
};
}, [css, props.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)),
+ );
+
if (error) {
return <ErrorBanner error={error} />;
}
@@ -162,6 +184,7 @@ const AnyWidgetSlot = (props: Props) => {
key={key}
{...props}
widget={module.default}
+ setValue={wrappedSetValue}
value={valueWithBuffers}
/>
);
@@ -191,10 +214,19 @@ async function runAnyWidgetModule(
const widget =
typeof widgetDef === "function" ? await widgetDef() : widgetDef;
await widget.initialize?.({ model, experimental });
- const unsub = await widget.render?.({ model, el, experimental });
- return () => {
- unsub?.();
- };
+ try {
+ const unsub = await widget.render?.({ model, el, experimental });
+ return () => {
+ unsub?.();
+ };
+ } 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 } {
@@ -218,6 +250,13 @@ function hasModelId(message: unknown): message is { model_id: string } {
);
}
+interface Props
+ extends Omit<IPluginProps<T, Data, PluginFunctions>, "setValue"> {
+ widget: AnyWidget;
+ value: T;
+ setValue: (value: Partial<T>) => void;
+}
+
const LoadedSlot = ({
value,
setValue,
@@ -228,15 +267,9 @@ const LoadedSlot = ({
}: Props & { widget: AnyWidget }) => {
const htmlRef = useRef<HTMLDivElement>(null);
+ // value is already decoded from wire format
const model = useRef<Model<T>>(
- new Model(
- // Merge the initial value with the current value
- // since we only send partial updates to the backend
- { ...data.initialValue, ...value },
- setValue,
- functions.send_to_widget,
- getDirtyFields(value, data.initialValue),
- ),
+ new Model(value, setValue, functions.send_to_widget, new Set()),
);
// Listen to incoming messages
@@ -289,16 +322,3 @@ export const visibleForTesting = {
isAnyWidgetModule,
getDirtyFields,
};
-
-export function resolveInitialValue(
- raw: Record<string, any>,
- bufferPaths: readonly (readonly (string | number)[])[],
-) {
- const out = structuredClone(raw);
- for (const bufferPath of bufferPaths) {
- const base64String: Base64String = get(raw, bufferPath);
- const bytes = byteStringToBinary(typedAtob(base64String));
- set(out, bufferPath, new DataView(bytes.buffer));
- }
- return out;
-}
diff --git a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx
index 738c70046b..b042e4f156 100644
--- a/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx
+++ b/frontend/src/plugins/impl/anywidget/__tests__/AnyWidgetPlugin.test.tsx
@@ -5,11 +5,7 @@ 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,
- resolveInitialValue,
- visibleForTesting,
-} from "../AnyWidgetPlugin";
+import { getDirtyFields, visibleForTesting } from "../AnyWidgetPlugin";
import { Model } from "../model";
const { LoadedSlot } = visibleForTesting;
@@ -132,6 +128,7 @@ describe("LoadedSlot", () => {
message: {
method: "update",
state: { count: 10 },
+ buffer_paths: [],
},
buffers: [],
},
@@ -183,55 +180,3 @@ describe("LoadedSlot", () => {
});
});
});
-
-describe("resolveInitialValue", () => {
- it("should convert base64 strings to DataView at specified paths", () => {
- const result = resolveInitialValue(
- {
- a: 10,
- b: "aGVsbG8=", // "hello" in base64
- c: [1, "d29ybGQ="], // "world" in base64
- d: {
- foo: "bWFyaW1vCg==", // "marimo" in base64
- baz: 20,
- },
- },
- [["b"], ["c", 1], ["d", "foo"]],
- );
-
- expect(result).toMatchInlineSnapshot(`
- {
- "a": 10,
- "b": DataView [
- 104,
- 101,
- 108,
- 108,
- 111,
- ],
- "c": [
- 1,
- DataView [
- 119,
- 111,
- 114,
- 108,
- 100,
- ],
- ],
- "d": {
- "baz": 20,
- "foo": DataView [
- 109,
- 97,
- 114,
- 105,
- 109,
- 111,
- 10,
- ],
- },
- }
- `);
- });
-});
diff --git a/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts b/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts
index cc3265068f..9e9573b6a6 100644
--- a/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts
+++ b/frontend/src/plugins/impl/anywidget/__tests__/model.test.ts
@@ -9,6 +9,7 @@ import {
vi,
} from "vitest";
import { TestUtils } from "@/__tests__/test-helpers";
+import type { Base64String } from "@/utils/json/base64";
import {
type AnyWidgetMessage,
handleWidgetMessage,
@@ -23,7 +24,10 @@ describe("Model", () => {
// 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?: any }) => Promise<null | undefined>;
+ let sendToWidget: (req: {
+ content: unknown;
+ buffers: Base64String[];
+ }) => Promise<null | undefined>;
beforeEach(() => {
onChange = vi.fn();
@@ -72,7 +76,7 @@ describe("Model", () => {
});
});
- it("should send all dirty fields", () => {
+ it("should clear dirty fields after save", () => {
model.set("foo", "new value");
model.save_changes();
@@ -83,14 +87,13 @@ describe("Model", () => {
model.set("bar", 456);
model.save_changes();
+ // After clearing, only the newly changed field is sent
expect(onChange).toHaveBeenCalledWith({
- foo: "new value",
bar: 456,
});
});
- // Skip because we don't clear the dirty fields after save
- it.skip("should clear dirty fields after save", () => {
+ it("should not call onChange when no dirty fields", () => {
model.set("foo", "new value");
model.save_changes();
model.save_changes(); // Second save should not call onChange
@@ -144,21 +147,16 @@ describe("Model", () => {
const callback = vi.fn();
model.send({ test: true }, callback);
- expect(sendToWidget).toHaveBeenCalledWith({ content: { test: true } });
+ expect(sendToWidget).toHaveBeenCalledWith({
+ content: {
+ state: { test: true },
+ bufferPaths: [],
+ },
+ buffers: [],
+ });
await TestUtils.nextTick(); // flush
expect(callback).toHaveBeenCalledWith(null);
});
-
- it("should warn when buffers are provided", () => {
- const consoleSpy = vi.spyOn(console, "warn").mockImplementation(() => {
- // noop
- });
- model.send({ test: true }, null, [new ArrayBuffer(8)]);
-
- expect(consoleSpy).toHaveBeenCalledWith(
- "buffers not supported in marimo anywidget.send",
- );
- });
});
describe("widget_manager", () => {
@@ -228,7 +226,11 @@ describe("Model", () => {
it("should handle update messages", () => {
model.receiveCustomMessage({
method: "update",
- state: { foo: "updated", bar: 789 },
+ state: {
+ foo: "updated",
+ bar: 789,
+ },
+ buffer_paths: [],
});
expect(model.get("foo")).toBe("updated");
@@ -333,7 +335,9 @@ describe("ModelManager", () => {
const updateMessage: AnyWidgetMessage = {
method: "update",
- state: { count: 1 },
+ state: {
+ count: 1,
+ },
buffer_paths: [],
};
diff --git a/frontend/src/plugins/impl/anywidget/model.ts b/frontend/src/plugins/impl/anywidget/model.ts
index ba0903b6f3..b8023f3a19 100644
--- a/frontend/src/plugins/impl/anywidget/model.ts
+++ b/frontend/src/plugins/impl/anywidget/model.ts
@@ -2,14 +2,14 @@
/* eslint-disable @typescript-eslint/no-explicit-any */
import type { AnyModel } from "@anywidget/types";
-import { dequal } from "dequal";
import { debounce } from "lodash-es";
import { z } from "zod";
import { getRequestClient } from "@/core/network/requests";
import { assertNever } from "@/utils/assertNever";
import { Deferred } from "@/utils/Deferred";
-import { updateBufferPaths } from "@/utils/data-views";
+import { decodeFromWire, serializeBuffersToBase64 } from "@/utils/data-views";
import { throwNotImplemented } from "@/utils/functions";
+import type { Base64String } from "@/utils/json/base64";
import { Logger } from "@/utils/Logger";
export type EventHandler = (...args: any[]) => void;
@@ -63,28 +63,30 @@ export const MODEL_MANAGER = new ModelManager();
export class Model<T extends Record<string, any>> implements AnyModel<T> {
private ANY_CHANGE_EVENT = "change";
- private dirtyFields;
+ 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?: any;
- buffers?: ArrayBuffer[] | ArrayBufferView[];
+ content: unknown;
+ buffers: Base64String[];
}) => Promise<null | undefined>;
constructor(
data: T,
onChange: (value: Partial<T>) => void,
sendToWidget: (req: {
- content?: any;
- buffers?: ArrayBuffer[] | ArrayBufferView[];
+ content: unknown;
+ buffers: Base64String[];
}) => Promise<null | undefined>,
initialDirtyFields: Set<keyof T>,
) {
this.data = data;
this.onChange = onChange;
this.sendToWidget = sendToWidget;
- this.dirtyFields = new Set(initialDirtyFields);
+ this.dirtyFields = new Map(
+ [...initialDirtyFields].map((key) => [key, this.data[key]]),
+ );
}
private listeners: Record<string, Set<EventHandler>> = {};
@@ -106,12 +108,16 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {
send(
content: any,
callbacks?: any,
- buffers?: ArrayBuffer[] | ArrayBufferView[],
+ _buffers?: ArrayBuffer[] | ArrayBufferView[],
): void {
- if (buffers) {
- Logger.warn("buffers not supported in marimo anywidget.send");
- }
- this.sendToWidget({ content, buffers }).then(callbacks);
+ const { state, bufferPaths, buffers } = serializeBuffersToBase64(content);
+ this.sendToWidget({
+ content: {
+ state: state,
+ bufferPaths: bufferPaths,
+ },
+ buffers: buffers,
+ }).then(callbacks);
}
widget_manager = {
@@ -134,7 +140,7 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {
set<K extends keyof T>(key: K, value: T[K]): void {
this.data = { ...this.data, [key]: value };
- this.dirtyFields.add(key);
+ this.dirtyFields.set(key, value);
this.emit(`change:${key as K & string}`, value);
this.emitAnyChange();
}
@@ -143,24 +149,25 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {
if (this.dirtyFields.size === 0) {
return;
}
- const partialData: Partial<T> = {};
- this.dirtyFields.forEach((key) => {
- partialData[key] = this.data[key];
- });
- // We don't clear the dirty fields here, because we want
- // to send all fields that different from the initial value (have ever been changed).
- // This is less performant, but more correct, because the backend
- // stores the last value sent, and not a merge of the values.
- // When the backend knows to merge the partial updates, then we can clear
- // the dirty fields.
- // this.dirtyFields.clear();
+ // Only send the dirty fields, not the entire state.
+ const partialData = Object.fromEntries(
+ this.dirtyFields.entries(),
+ ) as Partial<T>;
+
+ // Clear the dirty fields to avoid sending again.
+ this.dirtyFields.clear();
this.onChange(partialData);
}
updateAndEmitDiffs(value: T): void {
+ if (value == null) {
+ return;
+ }
+
Object.keys(value).forEach((key) => {
const k = key as keyof T;
- if (!dequal(this.data[k], value[k])) {
+ // Shallow equal since these can be large objects
+ if (this.data[k] !== value[k]) {
this.set(k, value[k]);
}
});
@@ -170,13 +177,22 @@ 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: any, buffers: readonly DataView[] = []): void {
+ receiveCustomMessage(
+ message: unknown,
+ buffers: readonly DataView[] = [],
+ ): void {
const response = AnyWidgetMessageSchema.safeParse(message);
if (response.success) {
const data = response.data;
switch (data.method) {
case "update":
- this.updateAndEmitDiffs(data.state as T);
+ this.updateAndEmitDiffs(
+ decodeFromWire<T>({
+ state: data.state as T,
+ bufferPaths: data.buffer_paths ?? [],
+ buffers,
+ }),
+ );
break;
case "custom":
this.listeners["msg:custom"]?.forEach((cb) =>
@@ -184,7 +200,19 @@ export class Model<T extends Record<string, any>> implements AnyModel<T> {
);
break;
case "open":
- this.updateAndEmitDiffs(data.state as T);
+ 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 {
@@ -269,7 +297,7 @@ export async function handleWidgetMessage({
if (msg.method === "custom") {
const model = await modelManager.get(modelId);
- model.receiveCustomMessage(msg);
+ model.receiveCustomMessage(msg, buffers);
return;
}
@@ -279,24 +307,23 @@ export async function handleWidgetMessage({
}
const { method, state, buffer_paths = [] } = msg;
- const stateWithBuffers = updateBufferPaths(state, buffer_paths, buffers);
+ const stateWithBuffers = decodeFromWire({
+ state,
+ bufferPaths: buffer_paths,
+ buffers,
+ });
if (method === "open") {
const handleDataChange = (changeData: Record<string, any>) => {
- if (buffer_paths) {
- Logger.warn(
- "Changed data with buffer paths may not be supported",
- changeData,
- );
- // TODO: we may want to extract/undo DataView, to get back buffers and buffer_paths
- }
+ const { state, buffers, bufferPaths } =
+ serializeBuffersToBase64(changeData);
getRequestClient().sendModelValue({
modelId: modelId,
message: {
- state: changeData,
- bufferPaths: [],
+ state,
+ bufferPaths,
},
- buffers: [],
+ buffers,
});
};
diff --git a/frontend/src/utils/__tests__/data-views.test.ts b/frontend/src/utils/__tests__/data-views.test.ts
index cfae0f8c68..7d1ed24a39 100644
--- a/frontend/src/utils/__tests__/data-views.test.ts
+++ b/frontend/src/utils/__tests__/data-views.test.ts
@@ -1,16 +1,23 @@
/* Copyright 2024 Marimo. All rights reserved. */
import { describe, expect, it } from "vitest";
-import { updateBufferPaths } from "../data-views";
+import {
+ dataViewToBase64,
+ decodeFromWire,
+ isWireFormat,
+ serializeBuffersToBase64,
+ type WireFormat,
+} from "../data-views";
+import type { Base64String } from "../json/base64";
-describe("updateBufferPaths", () => {
- it("should return the original object if bufferPaths.length === 0", () => {
- const input = { a: 1, b: 2 };
- const result = updateBufferPaths(input, [], []);
- expect(result).toEqual(input);
+describe("decodeFromWire with DataViews", () => {
+ it("should return the original state if bufferPaths.length === 0", () => {
+ const state = { a: 1, b: 2 };
+ const result = decodeFromWire({ state, bufferPaths: [] });
+ expect(result).toEqual(state);
});
- it("should update buffer paths with provided buffers", () => {
- const input = {
+ it("should insert DataViews at specified buffer paths", () => {
+ const state = {
a: 1,
b: {
c: "Hello",
@@ -25,7 +32,7 @@ describe("updateBufferPaths", () => {
new TextEncoder().encode("Hello"),
new TextEncoder().encode("World"),
].map((b) => new DataView(b.buffer));
- const result = updateBufferPaths(input, bufferPaths, buffers);
+ const result = decodeFromWire({ state, bufferPaths, buffers });
expect(result).toMatchInlineSnapshot(`
{
"a": 1,
@@ -50,25 +57,500 @@ describe("updateBufferPaths", () => {
});
it("should throw error when buffers and paths length mismatch", () => {
- const input = { a: 1 };
+ const state = { a: 1 };
const bufferPaths = [
["b", "c"],
["b", "d"],
];
const buffers = [new DataView(new ArrayBuffer())]; // Only one buffer for two paths
- expect(() => updateBufferPaths(input, bufferPaths, buffers)).toThrow(
+ expect(() => decodeFromWire({ state, bufferPaths, buffers })).toThrow(
"Buffers and buffer paths not the same length",
);
});
it("should handle empty buffers array", () => {
- const input = { a: 1 };
+ const state = { a: 1 };
const bufferPaths = [["b", "c"]];
const buffers: DataView[] = [];
- expect(() => updateBufferPaths(input, bufferPaths, buffers)).toThrow(
+ expect(() => decodeFromWire({ state, bufferPaths, buffers })).toThrow(
"Buffers and buffer paths not the same length",
);
});
});
+
+describe("Immutability Tests", () => {
+ it("serializeBuffersToBase64 should not mutate input", () => {
+ const encoder = new TextEncoder();
+ const dataView1 = new DataView(encoder.encode("data1").buffer);
+ const dataView2 = new DataView(encoder.encode("data2").buffer);
+
+ const input = {
+ buffer1: dataView1,
+ nested: {
+ buffer2: dataView2,
+ value: "test",
+ },
+ array: [1, 2, 3],
+ };
+
+ const clone = structuredClone(input);
+
+ serializeBuffersToBase64(input);
+
+ // Check deep equality
+ expect(input).toEqual(clone);
+
+ // Check references are unchanged
+ expect(input.buffer1).toBe(dataView1);
+ expect(input.nested.buffer2).toBe(dataView2);
+ expect(input.nested).toBe(input.nested); // Nested object reference unchanged
+ expect(input.array).toBe(input.array); // Array reference unchanged
+ });
+
+ it("decodeFromWire (wire format) should not mutate input", () => {
+ const encoder = new TextEncoder();
+ const data = encoder.encode("Hello");
+ const base64 = btoa(String.fromCharCode(...data)) as Base64String;
+
+ const input = {
+ state: { text: base64, number: 42, nested: { value: "test" } },
+ bufferPaths: [["text"]],
+ buffers: [base64],
+ };
+
+ const clone = structuredClone(input);
+
+ decodeFromWire(input);
+
+ // Check deep equality
+ expect(input).toEqual(clone);
+
+ // Check references are unchanged
+ expect(input.state).toBe(input.state);
+ expect(input.state.nested).toBe(input.state.nested);
+ });
+
+ it("decodeFromWire (with DataViews) should not mutate input", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+
+ const state = {
+ placeholder: "value",
+ nested: { key: "test" },
+ array: [1, 2, 3],
+ };
+ 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
+ });
+
+ it("decodeFromWire should return new object, not mutate", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+
+ const state = { a: 1, b: 2 };
+ 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);
+
+ // Result should have new property
+ expect("c" in result).toBe(true);
+ });
+
+ it("serializeBuffersToBase64 should return new state object", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+
+ const input = {
+ buffer: dataView,
+ value: "test",
+ };
+
+ const result = serializeBuffersToBase64(input);
+
+ // State should be different reference
+ expect(result.state).not.toBe(input);
+
+ // Input should still have DataView
+ expect(input.buffer).toBeInstanceOf(DataView);
+
+ // Result state should have base64 string
+ expect(typeof result.state.buffer).toBe("string");
+ });
+
+ it("decodeFromWire with object input should not mutate state", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+
+ const state = { a: 1, b: { c: 2 } };
+ 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);
+ });
+
+ it("nested objects should maintain independence after serialization", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+
+ const nested = { buffer: dataView, value: "nested" };
+ const input = {
+ nested,
+ other: "value",
+ };
+
+ const result = serializeBuffersToBase64(input);
+
+ // Mutate result state
+ (result.state.nested as Record<string, unknown>).value = "changed";
+
+ // Original nested object should be unchanged
+ expect(nested.value).toBe("nested");
+ expect(input.nested.value).toBe("nested");
+ });
+
+ it("arrays should not be mutated during operations", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+
+ const input = {
+ items: [dataView, "middle", { value: 1 }],
+ };
+
+ const originalItems = input.items;
+ const originalMiddle = input.items[1];
+ const originalObject = input.items[2];
+
+ serializeBuffersToBase64(input);
+
+ // Array reference should be unchanged
+ expect(input.items).toBe(originalItems);
+ expect(input.items[1]).toBe(originalMiddle);
+ expect(input.items[2]).toBe(originalObject);
+ });
+});
+
+describe("dataViewToBase64", () => {
+ it("should convert a DataView to a base64 string", () => {
+ const encoder = new TextEncoder();
+ const bytes = encoder.encode("Hello, World!");
+ const dataView = new DataView(bytes.buffer);
+ const base64 = dataViewToBase64(dataView);
+
+ // Decode and verify
+ const decoded = atob(base64);
+ expect(decoded).toBe("Hello, World!");
+ });
+
+ it("should handle empty DataView", () => {
+ const dataView = new DataView(new ArrayBuffer(0));
+ const base64 = dataViewToBase64(dataView);
+ expect(base64).toBe("");
+ });
+
+ it("should handle DataView with offset and length", () => {
+ const encoder = new TextEncoder();
+ const bytes = encoder.encode("Hello, World!");
+ // Create a DataView that only looks at "World!"
+ const dataView = new DataView(bytes.buffer, 7, 6);
+ const base64 = dataViewToBase64(dataView);
+
+ const decoded = atob(base64);
+ expect(decoded).toBe("World!");
+ });
+
+ it("should handle binary data", () => {
+ const bytes = new Uint8Array([0, 1, 2, 255, 254, 253]);
+ const dataView = new DataView(bytes.buffer);
+ const base64 = dataViewToBase64(dataView);
+
+ // Verify round-trip
+ const decoded = atob(base64);
+ const decodedBytes = new Uint8Array(decoded.length);
+ for (let i = 0; i < decoded.length; i++) {
+ decodedBytes[i] = decoded.charCodeAt(i);
+ }
+ expect(Array.from(decodedBytes)).toEqual([0, 1, 2, 255, 254, 253]);
+ });
+});
+
+describe("serializeBuffersToBase64", () => {
+ it("should return empty arrays when no DataViews present", () => {
+ const input = { a: 1, b: "text", c: { d: true } };
+ const result = serializeBuffersToBase64(input);
+
+ expect(result).toEqual({
+ state: input,
+ buffers: [],
+ bufferPaths: [],
+ });
+ });
+
+ it("should serialize DataViews at top level", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("test").buffer);
+ const input = { data: dataView, other: 123 };
+
+ const result = serializeBuffersToBase64(input);
+
+ expect(result.buffers).toHaveLength(1);
+ expect(result.bufferPaths).toEqual([["data"]]);
+ expect(typeof result.state.data).toBe("string");
+ expect(result.state.other).toBe(123);
+ });
+
+ it("should serialize nested DataViews", () => {
+ const encoder = new TextEncoder();
+ const dataView1 = new DataView(encoder.encode("first").buffer);
+ const dataView2 = new DataView(encoder.encode("second").buffer);
+ const input = {
+ nested: {
+ buffer1: dataView1,
+ deeper: {
+ buffer2: dataView2,
+ },
+ },
+ regular: "value",
+ };
+
+ const result = serializeBuffersToBase64(input);
+
+ expect(result.buffers).toHaveLength(2);
+ expect(result.bufferPaths).toEqual([
+ ["nested", "buffer1"],
+ ["nested", "deeper", "buffer2"],
+ ]);
+ expect(typeof result.state.nested.buffer1).toBe("string");
+ expect(typeof result.state.nested.deeper.buffer2).toBe("string");
+ });
+
+ it("should serialize DataViews in arrays", () => {
+ const encoder = new TextEncoder();
+ const dataView1 = new DataView(encoder.encode("one").buffer);
+ const dataView2 = new DataView(encoder.encode("two").buffer);
+ const input = {
+ items: [dataView1, "middle", dataView2],
+ };
+
+ const result = serializeBuffersToBase64(input);
+
+ expect(result.buffers).toHaveLength(2);
+ expect(result.bufferPaths).toEqual([
+ ["items", 0],
+ ["items", 2],
+ ]);
+ expect(result.state.items[1]).toBe("middle");
+ });
+
+ it("should handle mixed nested structures", () => {
+ const encoder = new TextEncoder();
+ const dataView = new DataView(encoder.encode("data").buffer);
+ const input = {
+ array: [{ nested: dataView }, [dataView]],
+ };
+
+ const result = serializeBuffersToBase64(input);
+
+ expect(result.buffers).toHaveLength(2);
+ expect(result.bufferPaths).toContainEqual(["array", 0, "nested"]);
+ expect(result.bufferPaths).toContainEqual(["array", 1, 0]);
+ });
+});
+
+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 = {
+ state: { a: 1, b: "text" },
+ bufferPaths: [],
+ buffers: [],
+ };
+ const result = decodeFromWire(wire);
+ expect(result).toEqual({ a: 1, b: "text" });
+ });
+
+ it("should decode single buffer at top level", () => {
+ const encoder = new TextEncoder();
+ const originalData = encoder.encode("Hello");
+ const base64 = btoa(String.fromCharCode(...originalData)) as Base64String;
+
+ const wire: WireFormat = {
+ state: { data: base64, other: 123 },
+ bufferPaths: [["data"]],
+ buffers: [base64],
+ };
+
+ const result = decodeFromWire(wire);
+
+ expect(result.data).toBeInstanceOf(DataView);
+ expect(result.other).toBe(123);
+
+ // Verify the DataView contains correct data
+ const bytes = new Uint8Array((result.data as DataView).buffer);
+ const decoded = new TextDecoder().decode(bytes);
+ expect(decoded).toBe("Hello");
+ });
+
+ it("should decode nested buffers", () => {
+ const encoder = new TextEncoder();
+ const data1 = encoder.encode("first");
+ const data2 = encoder.encode("second");
+ const base641 = btoa(String.fromCharCode(...data1)) as Base64String;
+ const base642 = btoa(String.fromCharCode(...data2)) as Base64String;
+
+ const wire: WireFormat = {
+ state: {
+ nested: {
+ buf1: base641,
+ deeper: {
+ buf2: base642,
+ },
+ },
+ },
+ bufferPaths: [
+ ["nested", "buf1"],
+ ["nested", "deeper", "buf2"],
+ ],
+ buffers: [base641, base642],
+ };
+
+ const result = decodeFromWire(wire) as {
+ nested: { buf1: unknown; deeper: { buf2: unknown } };
+ };
+
+ expect(result.nested.buf1).toBeInstanceOf(DataView);
+ expect(result.nested.deeper.buf2).toBeInstanceOf(DataView);
+ });
+
+ it("should decode buffers in arrays", () => {
+ const encoder = new TextEncoder();
+ const data = encoder.encode("test");
+ const base64 = btoa(String.fromCharCode(...data)) as Base64String;
+
+ const wire: WireFormat = {
+ state: {
+ items: [base64, "middle", base64],
+ },
+ bufferPaths: [
+ ["items", 0],
+ ["items", 2],
+ ],
+ buffers: [base64, base64],
+ };
+
+ const result = decodeFromWire(wire) as { items: unknown[] };
+
+ expect(result.items[0]).toBeInstanceOf(DataView);
+ expect(result.items[1]).toBe("middle");
+ expect(result.items[2]).toBeInstanceOf(DataView);
+ });
+
+ it("should handle round-trip serialization", () => {
+ const encoder = new TextEncoder();
+ const dataView1 = new DataView(encoder.encode("data1").buffer);
+ const dataView2 = new DataView(encoder.encode("data2").buffer);
+
+ const original = {
+ buffer1: dataView1,
+ nested: {
+ buffer2: dataView2,
+ },
+ regular: "value",
+ };
+
+ // Serialize
+ const serialized = serializeBuffersToBase64(original);
+
+ // Deserialize
+ const deserialized = decodeFromWire(serialized);
+
+ // Verify structure is preserved
+ expect(deserialized.buffer1).toBeInstanceOf(DataView);
+ expect(deserialized.nested.buffer2).toBeInstanceOf(DataView);
+ expect(deserialized.regular).toBe("value");
+
+ // Verify data integrity
+ const bytes1 = new Uint8Array((deserialized.buffer1 as DataView).buffer);
+ const bytes2 = new Uint8Array(
+ (deserialized.nested.buffer2 as DataView).buffer,
+ );
+ expect(new TextDecoder().decode(bytes1)).toBe("data1");
+ expect(new TextDecoder().decode(bytes2)).toBe("data2");
+ });
+});
diff --git a/frontend/src/utils/data-views.ts b/frontend/src/utils/data-views.ts
index 27a10e526f..6eaec3051c 100644
--- a/frontend/src/utils/data-views.ts
+++ b/frontend/src/utils/data-views.ts
@@ -1,19 +1,131 @@
/* Copyright 2024 Marimo. All rights reserved. */
-import { set } from "lodash-es";
+import { get, set } from "lodash-es";
import { invariant } from "./invariant";
+import {
+ type Base64String,
+ binaryToByteString,
+ byteStringToBinary,
+ typedAtob,
+ typedBtoa,
+} from "./json/base64";
import { Logger } from "./Logger";
/**
- * Update the object with DataView buffers at the specified paths.
+ * Convert a DataView to a base64 string.
*/
-export function updateBufferPaths<T extends Record<string, unknown>>(
+export function dataViewToBase64(dataView: DataView): Base64String {
+ const bytes = new Uint8Array(
+ dataView.buffer,
+ dataView.byteOffset,
+ dataView.byteLength,
+ );
+ const byteString = binaryToByteString(bytes);
+ return typedBtoa(byteString);
+}
+
+/**
+ * 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)[][] = [];
+
+ if (obj instanceof DataView) {
+ paths.push(currentPath);
+ } else if (Array.isArray(obj)) {
+ for (let i = 0; i < obj.length; i++) {
+ paths.push(...findDataViewPaths(obj[i], [...currentPath, i]));
+ }
+ } else if (obj !== null && typeof obj === "object") {
+ for (const [key, value] of Object.entries(obj)) {
+ paths.push(...findDataViewPaths(value, [...currentPath, key]));
+ }
+ }
+
+ return paths;
+}
+
+/**
+ * Serialize DataView buffers to base64 strings.
+ *
+ * Finds all DataViews in the object.
+ */
+export function serializeBuffersToBase64<T extends Record<string, unknown>>(
inputObject: T,
- bufferPaths: readonly (readonly (string | number)[])[],
- buffers: readonly DataView[],
-): T {
- // If no buffer paths, return the original object
+): WireFormat<T> {
+ // Dynamically find all DataView paths instead of using fixed bufferPaths
+ const dataViewPaths = findDataViewPaths(inputObject);
+
+ if (dataViewPaths.length === 0) {
+ return { state: inputObject, buffers: [], bufferPaths: [] };
+ }
+
+ const state = structuredClone(inputObject);
+ const buffers: Base64String[] = [];
+ const bufferPaths: (string | number)[][] = [];
+
+ for (const bufferPath of dataViewPaths) {
+ const dataView = get(inputObject, bufferPath);
+ if (dataView instanceof DataView) {
+ const base64 = dataViewToBase64(dataView);
+ buffers.push(base64);
+ bufferPaths.push(bufferPath);
+ set(state, bufferPath, base64);
+ }
+ }
+
+ 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.
+ *
+ * Accepts either:
+ * 1. Wire format: { state, bufferPaths, buffers } where buffers are base64 strings
+ * 2. Direct format: { state, bufferPaths, buffers } where buffers are DataViews
+ *
+ * For ndarray-like structures {view: null, dtype, shape}, we insert the DataView
+ * at the 'view' key, preserving the structure for round-tripping.
+ */
+export function decodeFromWire<T extends Record<string, unknown>>(input: {
+ state: T;
+ bufferPaths?: (string | number)[][];
+ buffers?: readonly (DataView | Base64String)[];
+}): T {
+ const { state, bufferPaths, buffers } = input;
+
+ // If no buffer paths, return the original state
if (!bufferPaths || bufferPaths.length === 0) {
- return inputObject;
+ return state;
}
// If has buffers, assert they are the same size
@@ -24,18 +136,24 @@ export function updateBufferPaths<T extends Record<string, unknown>>(
);
}
- let object = structuredClone(inputObject);
+ const out = structuredClone(state);
for (const [i, bufferPath] of bufferPaths.entries()) {
- // If buffers exists, we use that value
- // Otherwise we grab it from inside the inputObject
- const dataView = buffers[i];
- if (!dataView) {
- Logger.warn("Could not find buffer at path", bufferPath);
+ const buffer = buffers?.[i];
+
+ if (buffer == null) {
+ Logger.warn("[anywidget] Could not find buffer at path", bufferPath);
continue;
}
- object = set(object, bufferPath, dataView);
+
+ // Handle both base64 strings (from wire format) and DataViews (direct usage)
+ if (typeof buffer === "string") {
+ const bytes = byteStringToBinary(typedAtob(buffer));
+ set(out, bufferPath, new DataView(bytes.buffer));
+ } else {
+ set(out, bufferPath, buffer);
+ }
}
- return object;
+ return out;
}
diff --git a/frontend/src/utils/json/base64.ts b/frontend/src/utils/json/base64.ts
index 5d419abcd8..65c29c809e 100644
--- a/frontend/src/utils/json/base64.ts
+++ b/frontend/src/utils/json/base64.ts
@@ -55,6 +55,14 @@ export function byteStringToBinary(bytes: ByteString): Uint8Array {
return Uint8Array.from(bytes, (c) => c.charCodeAt(0));
}
+export function binaryToByteString(binary: Uint8Array): ByteString {
+ let result = "";
+ for (const byte of binary) {
+ result += String.fromCharCode(byte);
+ }
+ return result as ByteString;
+}
+
export function safeExtractSetUIElementMessageBuffers(
op: OperationMessageData<"send-ui-element-message">,
): readonly DataView[] {
diff --git a/marimo/_plugins/ui/_impl/anywidget/init.py b/marimo/_plugins/ui/_impl/anywidget/init.py
index f6ef6e909f..1607d23f2c 100644
--- a/marimo/_plugins/ui/_impl/anywidget/init.py
+++ b/marimo/_plugins/ui/_impl/anywidget/init.py
@@ -42,5 +42,9 @@ def init_marimo_widget(w: ipywidgets.Widget) -> None:
# html_deps=session._process_ui(TagList(widget_dep))["deps"],
)
+ # Register ipywidgets' message handler so it can process incoming messages
+ # with proper buffer handling via _put_buffers and serializer support
+ w.comm.on_msg(w._handle_msg)
+
WIDGET_COMM_MANAGER = MarimoCommManager()
diff --git a/marimo/_plugins/ui/_impl/from_anywidget.py b/marimo/_plugins/ui/_impl/from_anywidget.py
index 221b2498cb..c47ab3f8c9 100644
--- a/marimo/_plugins/ui/_impl/from_anywidget.py
+++ b/marimo/_plugins/ui/_impl/from_anywidget.py
@@ -1,11 +1,20 @@
# Copyright 2024 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, TypeVar
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Generic,
+ Optional,
+ TypedDict,
+ TypeVar,
+ cast,
+)
import marimo._output.data.data as mo_data
from marimo import _loggers
@@ -18,6 +27,53 @@ from marimo._plugins.ui._impl.anywidget.utils import (
from marimo._plugins.ui._impl.comm import MarimoComm
from marimo._runtime.functions import Function
+
+class WireFormat(TypedDict):
+ state: dict[str, Any]
+ 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
+
+ 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,
+ )
+
+
if TYPE_CHECKING:
from anywidget import ( # type: ignore [import-not-found,unused-ignore] # noqa: E501
AnyWidget,
@@ -76,7 +132,7 @@ class SendToWidgetArgs:
@mddoc
-class anywidget(UIElement[T, T]):
+class anywidget(UIElement[WireFormat, T]):
"""Create a UIElement from an AnyWidget.
This proxies all the widget's attributes and methods, allowing seamless
@@ -150,32 +206,41 @@ class anywidget(UIElement[T, T]):
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: T) -> None:
- insert_buffer_paths(change, buffer_paths, buffers)
+ 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 change.items():
+
+ 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
- widget.set_state(changed_state)
+
+ 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)
+
super().__init__(
component_name="marimo-anywidget",
- initial_value=self._prev_state,
+ initial_value=initial_wire,
label="",
args={
"js-url": mo_data.js(js).url if js else "", # type: ignore [unused-ignore] # noqa: E501
"js-hash": js_hash,
"css": css,
- "buffer-paths": buffer_paths,
},
on_change=on_change,
functions=(
@@ -189,9 +254,7 @@ class anywidget(UIElement[T, T]):
def _initialize(
self,
- initialization_args: InitializationArgs[
- dict[str, Any], dict[str, Any]
- ],
+ initialization_args: InitializationArgs[WireFormat, dict[str, Any]],
) -> None:
super()._initialize(initialization_args)
# Add the ui_element_id after the widget is initialized
@@ -200,19 +263,48 @@ class anywidget(UIElement[T, T]):
comm.ui_element_id = self._id
def _receive_from_frontend(self, args: SendToWidgetArgs) -> None:
- self.widget._handle_custom_msg(args.content, args.buffers)
+ 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: T) -> T:
+ def _convert_value(self, value: WireFormat) -> T:
if isinstance(value, dict) and isinstance(self._prev_state, dict):
- merged = {**self._prev_state, **value}
+ # Decode wire format to plain state with bytes
+ decoded_state = decode_from_wire(value)
+
+ # Merge with previous state
+ merged = {**self._prev_state, **decoded_state}
self._prev_state = merged
- return merged
+
+ # 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 value
+ return cast(T, value)
+
+ @property
+ def value(self) -> T:
+ """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]
+
+ @value.setter
+ def value(self, value: T) -> None:
+ del value
+ raise RuntimeError("Setting the value of a UIElement is not allowed.")
def __deepcopy__(self, memo: Any) -> Any:
# Overriding UIElement deepcopy implementation
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index 5dae0d2673..640f9de3f2 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -2054,6 +2054,7 @@ class Kernel:
except Exception as e:
error_title = "Exception"
error_message = f"Function call (name: {request.function_name}, args: {request.args}) failed with exception {str(e)}"
+ LOGGER.info(error_message, exc_info=True)
debug(error_title, error_message)
# Couldn't call function, or function call failed
diff --git a/marimo/_smoke_tests/anywidget_examples/scatter.py b/marimo/_smoke_tests/anywidget_examples/scatter.py
new file mode 100644
index 0000000000..18ba1d8c0b
--- /dev/null
+++ b/marimo/_smoke_tests/anywidget_examples/scatter.py
@@ -0,0 +1,43 @@
+# /// script
+# requires-python = ">=3.13"
+# dependencies = [
+# "jupyter-scatter==0.22.2",
+# "numpy==2.3.5",
+# ]
+# ///
+
+import marimo
+
+__generated_with = "0.18.3"
+app = marimo.App(width="medium")
+
+
+def _():
+ import marimo as mo
+ import jscatter
+ import numpy as np
+
+ x = np.random.rand(500)
+ y = np.random.rand(500)
+
+ scatter = jscatter.Scatter(x=x, y=y)
+ w = mo.ui.anywidget(scatter.widget)
+ w
+ return (w,)
+
+
+def _(w):
+ w.selection
+ return
+
+
+def _(w):
+ w.hovering
+ return
+
+
+if __name__ == "__main__":
+ app.run()
diff --git a/tests/_plugins/ui/_impl/test_anywidget.py b/tests/_plugins/ui/_impl/test_anywidget.py
index 847a3bd3cc..c26de6c2cf 100644
--- a/tests/_plugins/ui/_impl/test_anywidget.py
+++ b/tests/_plugins/ui/_impl/test_anywidget.py
@@ -12,6 +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,
)
from marimo._runtime.requests import SetUIElementValueRequest
@@ -187,9 +189,12 @@ x = as_marimo_element.count
@staticmethod
async def test_initialization() -> None:
wrapped = anywidget(Widget(arr={"a": 1}))
- assert wrapped._initial_value == {"arr": {"a": 1}}
+ assert wrapped._initial_value == {
+ "state": {"arr": {"a": 1}},
+ "bufferPaths": [],
+ "buffers": [],
+ }
assert wrapped._component_args == {
- "buffer-paths": [],
"css": "",
"js-url": "",
"js-hash": md5(b"").hexdigest(),
@@ -198,15 +203,19 @@ 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 == {
- "arr": {"bytes": bytes([1, 2, 3]), "shape": (3,)}
+ "state": {"arr": {"shape": (3,)}},
+ "bufferPaths": [["arr", "bytes"]],
+ "buffers": [base64.b64encode(bytes([1, 2, 3])).decode("utf-8")],
}
assert wrapped._component_args == {
- "buffer-paths": [["arr", "bytes"]],
"css": "",
"js-url": "",
"js-hash": md5(b"").hexdigest(),
@@ -238,8 +247,12 @@ x = as_marimo_element.count
wrapped = anywidget(NonSerializableWidget())
assert wrapped._initial_value == {
- "serializable": 1,
- "non_serializable": None,
+ "state": {
+ "serializable": 1,
+ "non_serializable": None,
+ },
+ "bufferPaths": [],
+ "buffers": [],
}
@staticmethod
@@ -250,7 +263,11 @@ x = as_marimo_element.count
sync = traitlets.Int(2).tag(sync=True)
wrapped = anywidget(NonSyncWidget())
- assert wrapped._initial_value == {"sync": 2}
+ assert wrapped._initial_value == {
+ "state": {"sync": 2},
+ "bufferPaths": [],
+ "buffers": [],
+ }
@staticmethod
@staticmethod
@@ -290,6 +307,8 @@ x = as_marimo_element.count
@staticmethod
async def test_buffers() -> None:
+ import base64
+
class BufferWidget(_anywidget.AnyWidget):
_esm = ""
array = traitlets.Bytes().tag(sync=True)
@@ -297,20 +316,22 @@ x = as_marimo_element.count
data = bytes([1, 2, 3, 4])
wrapped = anywidget(BufferWidget(array=data))
- assert wrapped._initial_value == {"array": data}
- assert wrapped._component_args["buffer-paths"] == [["array"]]
+ # _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")],
+ }
- # test buffers are inlined as base64 inplace
- assert (
- "data-initial-value='{&quot;array&quot;:&quot;AQIDBA==&quot;}'"
- in wrapped.text
- )
- assert "data-buffer-paths='[[&quot;array&quot;]]'" in wrapped.text
+ # test buffers are inlined as base64 in the wire format
+ assert "AQIDBA==" in wrapped.text
+ assert "array" in wrapped.text
# Test updating the buffer
new_data = bytes([5, 6, 7, 8])
wrapped.array = new_data
- assert wrapped.value["array"] == b"\x01\x02\x03\x04"
+ # value property returns decoded state with buffers re-inserted
+ assert wrapped.value["array"] == data
@staticmethod
async def test_error_handling() -> None:
@@ -497,3 +518,200 @@ x = as_marimo_element.count
# Test updating with new traits
wrapped._update({"d": 4})
assert wrapped.value == {"a": 100, "b": 200, "c": 300, "d": 4}
+
+
[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