@marimo-team/islands 0.23.14-dev6 → 0.23.14-dev61

package/src/plugins/impl/anywidget/__tests__/host.test.ts

@@ -0,0 +1,313 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type MockInstance,
+  vi,
+} from "vitest";
+import { createHost } from "../host";
+import { Model } from "../model";
+import { WIDGET_REGISTRY } from "../registry";
+import type { ModelState, WidgetModelId } from "../types";
+import { visibleForTesting, WIDGET_DEF_REGISTRY } from "../widget-binding";
+import { WIDGET_REF_PREFIX } from "../widget-ref";
+
+const { WidgetBinding } = visibleForTesting;
+
+const asModelId = (id: string): WidgetModelId => id as WidgetModelId;
+const ref = (id: string): string => `${WIDGET_REF_PREFIX}${id}`;
+
+function createMockComm() {
+  return {
+    sendUpdate: vi.fn().mockResolvedValue(undefined),
+    sendCustomMessage: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe("createHost", () => {
+  // Each test uses a unique model id so global WIDGET_REGISTRY state
+  // from earlier tests doesn't leak in.
+  let nextId = 0;
+  let modelId: WidgetModelId;
+  let parentController: AbortController;
+  let getModuleSpy: MockInstance<typeof WIDGET_DEF_REGISTRY.getModule>;
+
+  beforeEach(() => {
+    nextId += 1;
+    modelId = asModelId(`host-test-${nextId}`);
+    parentController = new AbortController();
+    getModuleSpy = vi.spyOn(WIDGET_DEF_REGISTRY, "getModule");
+  });
+
+  afterEach(() => {
+    WIDGET_REGISTRY.delete(modelId);
+    getModuleSpy.mockRestore();
+  });
+
+  /** Register a child in the global registry the way an open message
+   * would: model + ESM spec, with the module load answered by the spy. */
+  function registerChild(
+    widgetDef: object,
+    state?: ModelState,
+  ): Model<ModelState> {
+    const childModel = new Model<ModelState>(
+      state ?? { count: 0 },
+      createMockComm(),
+    );
+    WIDGET_REGISTRY.setModel(modelId, childModel);
+    WIDGET_REGISTRY.setSpec(modelId, {
+      url: `./@file/10-${modelId}.js`,
+      // Unique per test: the def registry caches modules by hash.
+      hash: `hash-${modelId}`,
+    });
+    getModuleSpy.mockResolvedValue({ default: widgetDef });
+    return childModel;
+  }
+
+  describe("getModel", () => {
+    it("resolves the child model by ref", async () => {
+      const childModel = new Model<ModelState>({ value: 42 }, createMockComm());
+      WIDGET_REGISTRY.setModel(modelId, childModel);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const resolved = await host.getModel(ref(modelId));
+      expect(resolved.get("value")).toBe(42);
+    });
+
+    it("rejects an invalid ref", async () => {
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      await expect(host.getModel("IPY_MODEL_xyz")).rejects.toThrow(/Invalid/);
+    });
+
+    it("scopes listeners on the resolved model to the parent's signal", async () => {
+      const childModel = new Model<ModelState>({ count: 0 }, createMockComm());
+      WIDGET_REGISTRY.setModel(modelId, childModel);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const resolved = await host.getModel(ref(modelId));
+
+      const cb = vi.fn();
+      resolved.on("change:count", cb);
+      childModel.set("count", 1);
+      expect(cb).toHaveBeenCalledTimes(1);
+
+      // Aborting the parent signal should clear the listener even though
+      // the caller never wired it up themselves.
+      parentController.abort();
+      childModel.set("count", 2);
+      expect(cb).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("getWidget", () => {
+    it("resolves an undisplayed child with exports and a render method", async () => {
+      const exports = { setValue: vi.fn() };
+      const widgetDef = {
+        initialize: vi.fn().mockResolvedValue(exports),
+        render: vi.fn(),
+      };
+      registerChild(widgetDef);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const resolved = await host.getWidget(ref(modelId));
+      expect(resolved.exports).toBe(exports);
+
+      const el = document.createElement("div");
+      await resolved.render({ el });
+      expect(widgetDef.render).toHaveBeenCalledTimes(1);
+      expect(widgetDef.render.mock.calls[0][0].el).toBe(el);
+    });
+
+    it("waits for an in-flight `initialize` to settle", async () => {
+      let resolveInit!: (v: object) => void;
+      const widgetDef = {
+        initialize: vi.fn().mockReturnValue(
+          new Promise<object>((r) => {
+            resolveInit = r;
+          }),
+        ),
+        render: vi.fn(),
+      };
+      registerChild(widgetDef);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const widgetPromise = host.getWidget(ref(modelId));
+
+      // Until initialize resolves, getWidget should be pending.
+      let resolvedExports: unknown;
+      widgetPromise.then((w) => {
+        resolvedExports = w.exports;
+      });
+      await new Promise((r) => setTimeout(r, 5));
+      expect(resolvedExports).toBeUndefined();
+
+      const exports = { ready: true };
+      resolveInit(exports);
+      const resolved = await widgetPromise;
+      expect(resolved.exports).toBe(exports);
+    });
+
+    it("rejects if the child is deleted mid-initialize", async () => {
+      const widgetDef = {
+        initialize: vi.fn().mockReturnValue(new Promise(() => undefined)),
+        render: vi.fn(),
+      };
+      registerChild(widgetDef);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const widgetPromise = host.getWidget(ref(modelId));
+      widgetPromise.catch(() => undefined);
+      // Let the import resolve and initialize start.
+      await new Promise((r) => setTimeout(r, 0));
+
+      WIDGET_REGISTRY.delete(modelId);
+
+      await expect(widgetPromise).rejects.toThrow(/binding destroyed/);
+    });
+
+    it("rejects for a child that has no ESM spec", async () => {
+      // e.g. a ref to a traditional jupyter widget's model.
+      const childModel = new Model<ModelState>({ count: 0 }, createMockComm());
+      WIDGET_REGISTRY.setModel(modelId, childModel);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      await expect(host.getWidget(ref(modelId))).rejects.toThrow(/No ESM spec/);
+    });
+
+    it("uses the parent's signal as a default for child render", async () => {
+      const widgetDef = {
+        initialize: vi.fn(),
+        render: vi.fn(),
+      };
+      registerChild(widgetDef);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const resolved = await host.getWidget(ref(modelId));
+
+      await resolved.render({ el: document.createElement("div") });
+      const childRenderSignal = widgetDef.render.mock.calls[0][0].signal;
+      expect(childRenderSignal.aborted).toBe(false);
+
+      // Aborting the parent signal cascades to the child's view.
+      parentController.abort();
+      expect(childRenderSignal.aborted).toBe(true);
+    });
+
+    it("uses the caller-supplied signal when given, ignoring the parent default", async () => {
+      const widgetDef = {
+        initialize: vi.fn(),
+        render: vi.fn(),
+      };
+      registerChild(widgetDef);
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const resolved = await host.getWidget(ref(modelId));
+
+      const childController = new AbortController();
+      await resolved.render({
+        el: document.createElement("div"),
+        signal: childController.signal,
+      });
+      const childRenderSignal = widgetDef.render.mock.calls[0][0].signal;
+      expect(childRenderSignal.aborted).toBe(false);
+
+      childController.abort();
+      expect(childRenderSignal.aborted).toBe(true);
+    });
+  });
+});
+
+describe("WidgetBinding receives a host in render props", () => {
+  it("passes a host into render whose getWidget resolves siblings", async () => {
+    const parentId = asModelId("host-render-parent");
+    const childId = asModelId("host-render-child");
+    const parentController = new AbortController();
+    const getModuleSpy = vi.spyOn(WIDGET_DEF_REGISTRY, "getModule");
+    try {
+      const childExports = { id: "child" };
+      const childWidget = {
+        initialize: vi.fn().mockResolvedValue(childExports),
+        render: vi.fn(),
+      };
+      const childModel = new Model<ModelState>({ count: 0 }, createMockComm());
+      WIDGET_REGISTRY.setModel(childId, childModel);
+      WIDGET_REGISTRY.setSpec(childId, {
+        url: "./@file/10-host-render-child.js",
+        hash: "hash-host-render-child",
+      });
+      getModuleSpy.mockResolvedValue({ default: childWidget });
+
+      const parentModel = new Model<ModelState>(
+        { child: `${WIDGET_REF_PREFIX}${childId}` },
+        createMockComm(),
+      );
+      WIDGET_REGISTRY.setModel(parentId, parentModel);
+
+      const parentWidget = {
+        initialize: vi.fn(),
+        render: vi.fn(),
+      };
+      const parentBinding = await WidgetBinding.create({
+        widgetDef: parentWidget,
+        model: parentModel,
+        createHost: (signal) => createHost(WIDGET_REGISTRY, signal),
+      });
+
+      await parentBinding.createView(
+        { el: document.createElement("div") },
+        { signal: parentController.signal },
+      );
+
+      const renderProps = parentWidget.render.mock.calls[0][0];
+      expect(renderProps.host).toBeDefined();
+      expect(typeof renderProps.host.getWidget).toBe("function");
+
+      const resolved = await renderProps.host.getWidget(
+        parentModel.get("child"),
+      );
+      expect(resolved.exports).toBe(childExports);
+    } finally {
+      WIDGET_REGISTRY.delete(parentId);
+      WIDGET_REGISTRY.delete(childId);
+      getModuleSpy.mockRestore();
+    }
+  });
+});
+
+describe("host-mounted views hydrate like display-mounted ones", () => {
+  it("replays current state to a child's render listeners", async () => {
+    const childId = asModelId("host-hydration-child");
+    const parentController = new AbortController();
+    const getModuleSpy = vi.spyOn(WIDGET_DEF_REGISTRY, "getModule");
+    try {
+      const childWidget = {
+        render: vi.fn(({ model, el }) => {
+          el.textContent = "count is 5";
+          model.on("change:count", () => {
+            el.textContent = `count is ${model.get("count")}`;
+          });
+        }),
+      };
+      const childModel = new Model<ModelState>({ count: 8 }, createMockComm());
+      WIDGET_REGISTRY.setModel(childId, childModel);
+      WIDGET_REGISTRY.setSpec(childId, {
+        url: "./@file/10-host-hydration-child.js",
+        hash: "hash-host-hydration-child",
+      });
+      getModuleSpy.mockResolvedValue({ default: childWidget });
+
+      const host = createHost(WIDGET_REGISTRY, parentController.signal);
+      const resolved = await host.getWidget(ref(childId));
+
+      const el = document.createElement("div");
+      await resolved.render({ el });
+      expect(el.textContent).toBe("count is 8");
+    } finally {
+      WIDGET_REGISTRY.delete(childId);
+      getModuleSpy.mockRestore();
+    }
+  });
+});

package/src/plugins/impl/anywidget/__tests__/model-proxy.test.ts

@@ -0,0 +1,158 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it, vi } from "vitest";
+import { Model } from "../model";
+import { modelProxy } from "../model-proxy";
+import type { ModelState } from "../types";
+
+function createMockComm() {
+  return {
+    sendUpdate: vi.fn().mockResolvedValue(undefined),
+    sendCustomMessage: vi.fn().mockResolvedValue(undefined),
+  };
+}
+
+describe("Model.on signal option", () => {
+  it("removes the listener when the signal aborts", () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const controller = new AbortController();
+    const cb = vi.fn();
+
+    model.on("change:count", cb, { signal: controller.signal });
+    model.set("count", 1);
+    expect(cb).toHaveBeenCalledTimes(1);
+
+    controller.abort();
+    model.set("count", 2);
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not register if the signal is already aborted", () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const controller = new AbortController();
+    controller.abort();
+    const cb = vi.fn();
+
+    model.on("change:count", cb, { signal: controller.signal });
+    model.set("count", 1);
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  it("scopes listeners independently per signal", () => {
+    const model = new Model<ModelState>({ value: 0 }, createMockComm());
+    const view1 = new AbortController();
+    const view2 = new AbortController();
+    const cb1 = vi.fn();
+    const cb2 = vi.fn();
+
+    model.on("change:value", cb1, { signal: view1.signal });
+    model.on("change:value", cb2, { signal: view2.signal });
+
+    model.set("value", 1);
+    expect(cb1).toHaveBeenCalledTimes(1);
+    expect(cb2).toHaveBeenCalledTimes(1);
+
+    view1.abort();
+    model.set("value", 2);
+    expect(cb1).toHaveBeenCalledTimes(1);
+    expect(cb2).toHaveBeenCalledTimes(2);
+  });
+
+  it("allows a listener to call off() during emit without skipping siblings", () => {
+    // Snapshot-before-iterate guard: a listener that removes itself
+    // (typical signal-abort cleanup path) shouldn't drop a sibling.
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const sibling = vi.fn();
+    const selfRemoving = vi.fn(() => model.off("change:count", selfRemoving));
+
+    model.on("change:count", selfRemoving);
+    model.on("change:count", sibling);
+
+    model.set("count", 1);
+    expect(selfRemoving).toHaveBeenCalledTimes(1);
+    expect(sibling).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("modelProxy", () => {
+  it("auto-ties on() to the supplied signal", () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const controller = new AbortController();
+    const proxy = modelProxy(model, controller.signal);
+    const cb = vi.fn();
+
+    proxy.on("change:count", cb);
+    model.set("count", 1);
+    expect(cb).toHaveBeenCalledTimes(1);
+
+    // Aborting the signal should clear the listener even though the
+    // widget author never wired it up themselves.
+    controller.abort();
+    model.set("count", 2);
+    expect(cb).toHaveBeenCalledTimes(1);
+  });
+
+  it("scopes child listeners to per-view signals", () => {
+    const model = new Model<ModelState>({ value: 0 }, createMockComm());
+    const view1 = new AbortController();
+    const view2 = new AbortController();
+    const cb1 = vi.fn();
+    const cb2 = vi.fn();
+
+    modelProxy(model, view1.signal).on("change:value", cb1);
+    modelProxy(model, view2.signal).on("change:value", cb2);
+
+    model.set("value", 1);
+    expect(cb1).toHaveBeenCalledTimes(1);
+    expect(cb2).toHaveBeenCalledTimes(1);
+
+    // Dispose view1 — view2's listener stays.
+    view1.abort();
+    model.set("value", 2);
+    expect(cb1).toHaveBeenCalledTimes(1);
+    expect(cb2).toHaveBeenCalledTimes(2);
+  });
+
+  it("scopes legacy widget_manager child listeners to the parent signal", async () => {
+    const parent = new Model<ModelState>({}, createMockComm());
+    const child = new Model<ModelState>({ count: 0 }, createMockComm());
+    vi.spyOn(parent.widget_manager, "get_model").mockResolvedValue(child);
+    const controller = new AbortController();
+    const parentProxy = modelProxy(parent, controller.signal);
+
+    const childProxy =
+      await parentProxy.widget_manager.get_model<ModelState>("child-id");
+    const callback = vi.fn();
+    childProxy.on("change:count", callback);
+
+    child.set("count", 1);
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    controller.abort();
+    child.set("count", 2);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards get / set / save_changes", () => {
+    const comm = createMockComm();
+    const model = new Model<ModelState>({ count: 0 }, comm);
+    const controller = new AbortController();
+    const proxy = modelProxy(model, controller.signal);
+
+    proxy.set("count", 5);
+    expect(proxy.get("count")).toBe(5);
+    proxy.save_changes();
+    expect(comm.sendUpdate).toHaveBeenCalledWith({ count: 5 });
+  });
+
+  it("forwards off() through to the underlying model", () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const controller = new AbortController();
+    const proxy = modelProxy(model, controller.signal);
+    const cb = vi.fn();
+
+    proxy.on("change:count", cb);
+    proxy.off("change:count", cb);
+    model.set("count", 1);
+    expect(cb).not.toHaveBeenCalled();
+  });
+});

package/src/plugins/impl/anywidget/__tests__/model.test.ts

@@ -9,16 +9,9 @@ import {
   vi,
 } from "vitest";
 import { TestUtils } from "@/__tests__/test-helpers";
-import {
-  getMarimoInternal,
-  handleWidgetMessage,
-  Model,
-  visibleForTesting,
-} from "../model";
-import type { WidgetModelId } from "../types";
-import { BINDING_MANAGER } from "../widget-binding";
-
-const { ModelManager } = visibleForTesting;
+import { getMarimoInternal, Model } from "../model";
+import { WidgetRegistry } from "../registry";
+import type { ModelState, WidgetModelId } from "../types";
 
 // Helper to create typed model IDs for tests
 const asModelId = (id: string): WidgetModelId => id as WidgetModelId;
@@ -38,7 +31,7 @@ vi.mock("@/core/static/static-state", () => ({
 }));
 
 // Helper to create a mock MarimoComm
-function createMockComm<T>() {
+function createMockComm() {
   return {
     sendUpdate: vi.fn().mockResolvedValue(undefined),
     sendCustomMessage: vi.fn().mockResolvedValue(undefined),
@@ -47,7 +40,7 @@ function createMockComm<T>() {
 
 describe("Model", () => {
   let model: Model<{ foo: string; bar: number }>;
-  let mockComm: ReturnType<typeof createMockComm<{ foo: string; bar: number }>>;
+  let mockComm: ReturnType<typeof createMockComm>;
 
   beforeEach(() => {
     mockComm = createMockComm();
@@ -211,13 +204,13 @@ describe("Model", () => {
 
   describe("widget_manager", () => {
     const childModelId = asModelId("test-id");
-    const childModel = new Model({ foo: "test" }, createMockComm());
-    const manager = new ModelManager(10);
+    const childModel = new Model<ModelState>({ foo: "test" }, createMockComm());
+    const manager = new WidgetRegistry(10);
     let previousModelManager = Model._modelManager;
 
     beforeAll(() => {
       previousModelManager = Model._modelManager;
-      manager.set(childModelId, childModel);
+      manager.setModel(childModelId, childModel);
       Model._modelManager = manager;
     });
 
@@ -272,25 +265,6 @@ describe("Model", () => {
     });
   });
 
-  describe("reemitState", () => {
-    it("should emit change events for current values without state changes", async () => {
-      const onFoo = vi.fn();
-      const onBar = vi.fn();
-      const onAny = vi.fn();
-
-      model.on("change:foo", onFoo);
-      model.on("change:bar", onBar);
-      model.on("change", onAny);
-
-      getMarimoInternal(model).reemitState();
-      await TestUtils.nextTick();
-
-      expect(onFoo).toHaveBeenCalledWith("test");
-      expect(onBar).toHaveBeenCalledWith(123);
-      expect(onAny).toHaveBeenCalledTimes(1);
-    });
-  });
-
   describe("emitCustomMessage", () => {
     it("should handle custom messages", () => {
       const callback = vi.fn();
@@ -323,146 +297,3 @@ describe("Model", () => {
     });
   });
 });
-
-describe("ModelManager", () => {
-  let modelManager = new ModelManager(50);
-  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 }, 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(asModelId("non-existent"))).rejects.toThrow(
-      "Model not found for key: non-existent",
-    );
-  });
-
-  it("should delete models", async () => {
-    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 () => {
-    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);
-
-    await handleWidgetMessage(modelManager, {
-      model_id: testId,
-      message: {
-        method: "update",
-        state: { count: 1 },
-        buffer_paths: [],
-        buffers: [],
-      },
-    });
-    expect(model.get("count")).toBe(1);
-  });
-
-  it("should handle custom messages", async () => {
-    const model = new Model({ count: 0 }, createMockComm());
-    const callback = vi.fn();
-    model.on("msg:custom", callback);
-    modelManager.set(testId, model);
-
-    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 }, createMockComm());
-    modelManager.set(testId, model);
-
-    await handleWidgetMessage(modelManager, {
-      model_id: testId,
-      message: { method: "close" },
-    });
-    await expect(modelManager.get(testId)).rejects.toThrow();
-  });
-
-  it("should destroy binding on close message", async () => {
-    const model = new Model({ count: 0 }, createMockComm());
-    modelManager.set(testId, model);
-
-    // Create a binding for this model
-    BINDING_MANAGER.getOrCreate(testId);
-    expect(BINDING_MANAGER.has(testId)).toBe(true);
-
-    await handleWidgetMessage(modelManager, {
-      model_id: testId,
-      message: { method: "close" },
-    });
-
-    expect(BINDING_MANAGER.has(testId)).toBe(false);
-  });
-
-  describe("static mode", () => {
-    beforeEach(() => {
-      mockIsStatic.mockReturnValue(true);
-    });
-
-    afterAll(() => {
-      mockIsStatic.mockReturnValue(false);
-    });
-
-    it("should create model with no-op comm in static mode", async () => {
-      await handleWidgetMessage(modelManager, {
-        model_id: testId,
-        message: {
-          method: "open",
-          state: { count: 42 },
-          buffer_paths: [],
-          buffers: [],
-        },
-      });
-
-      const model = await modelManager.get(testId);
-      expect(model.get("count")).toBe(42);
-
-      // save_changes should not call the real request client
-      model.set("count", 100);
-      model.save_changes();
-      expect(mockSendModelValue).not.toHaveBeenCalled();
-    });
-
-    it("should not throw on send in static mode", async () => {
-      await handleWidgetMessage(modelManager, {
-        model_id: testId,
-        message: {
-          method: "open",
-          state: { count: 0 },
-          buffer_paths: [],
-          buffers: [],
-        },
-      });
-
-      const model = await modelManager.get(testId);
-      // send() should silently no-op
-      await expect(model.send({ test: true })).resolves.toBeUndefined();
-      expect(mockSendModelValue).not.toHaveBeenCalled();
-    });
-  });
-});