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

package/src/plugins/impl/anywidget/__tests__/widget-binding.test.ts

@@ -1,19 +1,18 @@
 /* Copyright 2026 Marimo. All rights reserved. */
 import type { ExtractAtomValue } from "jotai";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { AnyWidget } from "@anywidget/types";
 import { hasRunAnyCellAtom } from "@/components/editor/cell/useRunCells";
 import { userConfigAtom } from "@/core/config/config";
 import { parseUserConfig } from "@/core/config/config-schema";
 import { initialModeAtom } from "@/core/mode";
 import { store } from "@/core/state/jotai";
 import { Model } from "../model";
-import type { ModelState, WidgetModelId } from "../types";
+import type { Host } from "../host";
+import type { ModelState } from "../types";
 import { visibleForTesting } from "../widget-binding";
 
-const { WidgetDefRegistry, WidgetBinding, BindingManager } = visibleForTesting;
-
-// Helper to create typed model IDs for tests
-const asModelId = (id: string): WidgetModelId => id as WidgetModelId;
+const { WidgetDefRegistry, WidgetBinding } = visibleForTesting;
 
 function createMockComm() {
   return {
@@ -22,6 +21,34 @@ function createMockComm() {
   };
 }
 
+const createTestHost = (): Host => ({
+  getModel: vi.fn(),
+  getWidget: vi.fn(),
+});
+
+// oxlint-disable-next-line marimo/prefer-object-params -- terse test helper
+function createBinding<T extends ModelState>(
+  widgetDef: AnyWidget<T>,
+  model: Model<T>,
+  options: { controller?: AbortController } = {},
+) {
+  return WidgetBinding.create({
+    widgetDef,
+    model,
+    createHost: createTestHost,
+    controller: options.controller,
+  });
+}
+
+// oxlint-disable-next-line marimo/prefer-object-params -- terse test helper
+function getModule(
+  registry: InstanceType<typeof WidgetDefRegistry>,
+  jsUrl: string,
+  jsHash: string,
+) {
+  return registry.getModule({ jsUrl, jsHash });
+}
+
 describe("WidgetDefRegistry", () => {
   let registry: InstanceType<typeof WidgetDefRegistry>;
   let previousConfig: ExtractAtomValue<typeof userConfigAtom>;
@@ -53,44 +80,35 @@ describe("WidgetDefRegistry", () => {
 
   it("should cache modules by jsHash and return same promise", () => {
     // Two calls with same hash should return the exact same promise object
-    const promise1 = registry.getModule("http://localhost/widget.js", "hash1");
-    const promise2 = registry.getModule("http://localhost/widget.js", "hash1");
+    const promise1 = getModule(registry, "http://localhost/widget.js", "hash1");
+    const promise2 = getModule(registry, "http://localhost/widget.js", "hash1");
     expect(promise1).toBe(promise2);
     // Catch the unhandled rejection from the import() attempt
     promise1.catch(() => undefined);
   });
 
   it("should deduplicate concurrent imports for the same hash", () => {
-    const promise1 = registry.getModule("http://localhost/a.js", "same-hash");
-    const promise2 = registry.getModule("http://localhost/b.js", "same-hash");
+    const promise1 = getModule(registry, "http://localhost/a.js", "same-hash");
+    const promise2 = getModule(registry, "http://localhost/b.js", "same-hash");
     // Same hash means same promise, even with different URLs
     expect(promise1).toBe(promise2);
     promise1.catch(() => undefined);
   });
 
   it("should create different promises for different hashes", () => {
-    const promise1 = registry.getModule("http://localhost/a.js", "hash-a");
-    const promise2 = registry.getModule("http://localhost/b.js", "hash-b");
+    const promise1 = getModule(registry, "http://localhost/a.js", "hash-a");
+    const promise2 = getModule(registry, "http://localhost/b.js", "hash-b");
     expect(promise1).not.toBe(promise2);
     promise1.catch(() => undefined);
     promise2.catch(() => undefined);
   });
 
-  it("should invalidate cached modules", () => {
-    const promise1 = registry.getModule("http://localhost/a.js", "hash1");
-    promise1.catch(() => undefined);
-    registry.invalidate("hash1");
-    const promise2 = registry.getModule("http://localhost/a.js", "hash1");
-    promise2.catch(() => undefined);
-    expect(promise1).not.toBe(promise2);
-  });
-
   it("should remove from cache on import failure so retry creates new promise", async () => {
-    const promise1 = registry.getModule("http://localhost/a.js", "fail-hash");
+    const promise1 = getModule(registry, "http://localhost/a.js", "fail-hash");
     // The URL is rejected by the trusted-URL validator.
     await expect(promise1).rejects.toThrow();
     // After failure, cache should be cleared, so next call creates a new promise
-    const promise2 = registry.getModule("http://localhost/a.js", "fail-hash");
+    const promise2 = getModule(registry, "http://localhost/a.js", "fail-hash");
     expect(promise1).not.toBe(promise2);
     promise2.catch(() => undefined);
   });
@@ -106,7 +124,7 @@ describe("WidgetDefRegistry", () => {
       "./@file/x.js?redirect=http://evil.com",
       "",
     ])("rejects untrusted URL: %s", async (url) => {
-      await expect(registry.getModule(url, `hash-${url}`)).rejects.toThrow(
+      await expect(getModule(registry, url, `hash-${url}`)).rejects.toThrow(
         /untrusted/i,
       );
     });
@@ -116,179 +134,333 @@ describe("WidgetDefRegistry", () => {
       // is a Node test environment with no server. We only assert that
       // the rejection reason is NOT the "untrusted URL" refusal.
       await expect(
-        registry.getModule("./@file/123-widget.js", "trusted-hash"),
+        getModule(registry, "./@file/123-widget.js", "trusted-hash"),
       ).rejects.not.toThrow(/untrusted/i);
     });
   });
 });
 
 describe("WidgetBinding", () => {
-  let binding: InstanceType<typeof WidgetBinding>;
-  let model: Model<ModelState>;
-
-  beforeEach(() => {
-    binding = new WidgetBinding();
-    model = new Model<ModelState>({ count: 0 }, createMockComm());
-  });
-
-  it("should initialize once and return a render function", async () => {
-    const initCleanup = vi.fn();
-    const renderCleanup = vi.fn();
+  it("should run initialize exactly once and expose exports", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const exports = { setValue: vi.fn() };
     const widgetDef = {
-      initialize: vi.fn().mockResolvedValue(initCleanup),
-      render: vi.fn().mockResolvedValue(renderCleanup),
+      initialize: vi.fn().mockResolvedValue(exports),
+      render: vi.fn(),
     };
 
-    const renderFn = await binding.bind(widgetDef, model);
+    const binding = await createBinding(widgetDef, model);
     expect(widgetDef.initialize).toHaveBeenCalledTimes(1);
-    expect(typeof renderFn).toBe("function");
+    expect(binding.exports).toBe(exports);
 
-    // Render into an element
-    const el = document.createElement("div");
     const controller = new AbortController();
-    await renderFn(el, controller.signal);
-    expect(widgetDef.render).toHaveBeenCalledTimes(1);
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    expect(widgetDef.initialize).toHaveBeenCalledTimes(1);
+    expect(widgetDef.render).toHaveBeenCalledTimes(2);
   });
 
-  it("should return cached render for same widget def", async () => {
-    const widgetDef = {
-      initialize: vi.fn(),
-      render: vi.fn(),
-    };
+  it("should handle widget def as a factory function", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const render = vi.fn();
+    const factory = vi.fn().mockResolvedValue({ render });
 
-    const render1 = await binding.bind(widgetDef, model);
-    const render2 = await binding.bind(widgetDef, model);
-    expect(render1).toBe(render2);
-    // Initialize should only be called once
-    expect(widgetDef.initialize).toHaveBeenCalledTimes(1);
+    const binding = await createBinding(factory, model);
+    const controller = new AbortController();
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(render).toHaveBeenCalledTimes(1);
   });
 
-  it("should re-initialize on hot reload (different widget def)", async () => {
-    const cleanup1 = vi.fn();
-    const widgetDef1 = {
-      initialize: vi.fn().mockResolvedValue(cleanup1),
-      render: vi.fn(),
-    };
+  it("should handle a widget with no initialize or render", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const binding = await createBinding({}, model);
+    expect(binding.exports).toBeUndefined();
+    const controller = new AbortController();
+    // No render — createView is a no-op, not an error.
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+  });
+
+  it("should expose undefined exports for void initialize", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const binding = await createBinding(
+      { initialize: vi.fn(), render: vi.fn() },
+      model,
+    );
+    expect(binding.exports).toBeUndefined();
+  });
+
+  it("should run a legacy initialize cleanup on destroy", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const initCleanup = vi.fn();
+    const binding = await createBinding(
+      { initialize: vi.fn().mockResolvedValue(initCleanup), render: vi.fn() },
+      model,
+    );
+    expect(binding.exports).toBeUndefined();
+    expect(initCleanup).not.toHaveBeenCalled();
+    binding.destroy();
+    expect(initCleanup).toHaveBeenCalledTimes(1);
+  });
 
-    const widgetDef2 = {
-      initialize: vi.fn(),
+  it("should reject and run cleanup when aborted mid-initialize", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const initCleanup = vi.fn();
+    let resolveInit!: (v: unknown) => void;
+    const widgetDef = {
+      initialize: vi.fn().mockReturnValue(
+        new Promise((r) => {
+          resolveInit = r;
+        }),
+      ),
       render: vi.fn(),
     };
 
-    const render1 = await binding.bind(widgetDef1, model);
-    const render2 = await binding.bind(widgetDef2, model);
+    const controller = new AbortController();
+    const pending = createBinding(widgetDef, model, { controller });
+    pending.catch(() => undefined);
+
+    controller.abort();
+    resolveInit(initCleanup);
+
+    await expect(pending).rejects.toThrow(/binding destroyed/);
+    expect(initCleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("should pass an AbortSignal to initialize that aborts on destroy", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const widgetDef = { initialize: vi.fn(), render: vi.fn() };
+    const binding = await createBinding(widgetDef, model);
 
-    expect(render1).not.toBe(render2);
-    expect(cleanup1).toHaveBeenCalledTimes(1); // Old binding cleaned up
-    expect(widgetDef2.initialize).toHaveBeenCalledTimes(1);
+    const initSignal = widgetDef.initialize.mock.calls[0][0]
+      .signal as AbortSignal;
+    expect(initSignal.aborted).toBe(false);
+    binding.destroy();
+    expect(initSignal.aborted).toBe(true);
   });
 
-  it("should cleanup render on view signal abort", async () => {
+  it("should abort a view when its own signal aborts", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
     const renderCleanup = vi.fn();
     const widgetDef = {
-      initialize: vi.fn(),
       render: vi.fn().mockResolvedValue(renderCleanup),
     };
+    const binding = await createBinding(widgetDef, model);
 
-    const renderFn = await binding.bind(widgetDef, model);
-    const el = document.createElement("div");
-    const viewController = new AbortController();
-    await renderFn(el, viewController.signal);
+    const controller = new AbortController();
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    const renderSignal = widgetDef.render.mock.calls[0][0]
+      .signal as AbortSignal;
+    expect(renderSignal.aborted).toBe(false);
+
+    controller.abort();
+    expect(renderSignal.aborted).toBe(true);
+    expect(renderCleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it("runs a late render cleanup after the view already aborted", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const renderCleanup = vi.fn();
+    let resolveRender!: (cleanup: () => void) => void;
+    const widgetDef = {
+      render: vi.fn(
+        () =>
+          new Promise<() => void>((resolve) => {
+            resolveRender = resolve;
+          }),
+      ),
+    };
+    const binding = await createBinding(widgetDef, model);
+    const controller = new AbortController();
+
+    const pending = binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    controller.abort();
+    resolveRender(renderCleanup);
 
-    // Aborting the view signal should trigger render cleanup
-    viewController.abort();
+    await pending;
     expect(renderCleanup).toHaveBeenCalledTimes(1);
   });
 
-  it("should cleanup everything on destroy", async () => {
-    const initCleanup = vi.fn();
+  it("should abort every view when the binding is destroyed", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
     const renderCleanup = vi.fn();
     const widgetDef = {
-      initialize: vi.fn().mockResolvedValue(initCleanup),
       render: vi.fn().mockResolvedValue(renderCleanup),
     };
+    const binding = await createBinding(widgetDef, model);
 
-    const renderFn = await binding.bind(widgetDef, model);
-    const el = document.createElement("div");
-    const viewController = new AbortController();
-    await renderFn(el, viewController.signal);
+    const controller = new AbortController();
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    const renderSignal = widgetDef.render.mock.calls[0][0]
+      .signal as AbortSignal;
 
     binding.destroy();
-    expect(initCleanup).toHaveBeenCalledTimes(1);
+    expect(renderSignal.aborted).toBe(true);
     expect(renderCleanup).toHaveBeenCalledTimes(1);
+    // The caller's own signal is untouched — only the combined one.
+    expect(controller.signal.aborted).toBe(false);
   });
 
-  it("should handle widget def as a function", async () => {
-    const widget = {
-      initialize: vi.fn(),
-      render: vi.fn(),
+  it("should auto-clear render listeners when the view aborts", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const onCount = vi.fn();
+    const widgetDef = {
+      render: vi.fn(({ model }) => {
+        model.on("change:count", onCount);
+      }),
     };
-    const widgetDefFn = vi.fn().mockResolvedValue(widget);
+    const binding = await createBinding(widgetDef, model);
 
-    await binding.bind(widgetDefFn, model);
-    expect(widgetDefFn).toHaveBeenCalledTimes(1);
-    expect(widget.initialize).toHaveBeenCalledTimes(1);
+    const controller = new AbortController();
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    // Called once by the hydration replay at mount, once by the set.
+    model.set("count", 1);
+    expect(onCount).toHaveBeenCalledTimes(2);
+
+    controller.abort();
+    model.set("count", 2);
+    expect(onCount).toHaveBeenCalledTimes(2);
   });
 
-  it("should handle widget with no initialize or render", async () => {
-    const widgetDef = {};
-    const renderFn = await binding.bind(widgetDef, model);
-    expect(typeof renderFn).toBe("function");
+  it("should auto-clear initialize listeners on destroy", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const onCount = vi.fn();
+    const widgetDef = {
+      initialize: vi.fn(({ model }) => {
+        model.on("change:count", onCount);
+      }),
+      render: vi.fn(),
+    };
+    const binding = await createBinding(widgetDef, model);
 
-    // Render should not throw
-    const el = document.createElement("div");
-    const controller = new AbortController();
-    await renderFn(el, controller.signal);
+    model.set("count", 1);
+    expect(onCount).toHaveBeenCalledTimes(1);
+
+    binding.destroy();
+    model.set("count", 2);
+    expect(onCount).toHaveBeenCalledTimes(1);
   });
 });
 
-describe("BindingManager", () => {
-  let manager: InstanceType<typeof BindingManager>;
+describe("WidgetBinding hydration replay", () => {
+  it("replays current state to render listeners exactly once", async () => {
+    const model = new Model<ModelState>({ count: 8 }, createMockComm());
+    const el = document.createElement("div");
+    const widgetDef = {
+      render: vi.fn(({ model, el }) => {
+        // A widget view that starts with a local default and relies on
+        // change events for hydration.
+        el.textContent = "count is 5";
+        model.on("change:count", () => {
+          el.textContent = `count is ${model.get("count")}`;
+        });
+      }),
+    };
+    const binding = await createBinding(widgetDef, model);
 
-  beforeEach(() => {
-    manager = new BindingManager();
+    const controller = new AbortController();
+    await binding.createView({ el }, { signal: controller.signal });
+    expect(el.textContent).toBe("count is 8");
   });
 
-  it("should create bindings on demand", () => {
-    const modelId = asModelId("model-1");
-    expect(manager.has(modelId)).toBe(false);
+  it("does not re-fire listeners of already-mounted views", async () => {
+    // Mounting view B must not double-paint view A: the replay is
+    // scoped to the listeners the new render attached.
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const listeners: Array<ReturnType<typeof vi.fn>> = [];
+    const widgetDef = {
+      render: vi.fn(({ model }) => {
+        const listener = vi.fn();
+        listeners.push(listener);
+        model.on("change:count", listener);
+      }),
+    };
+    const binding = await createBinding(widgetDef, model);
+    const controller = new AbortController();
 
-    const binding = manager.getOrCreate(modelId);
-    expect(binding).toBeDefined();
-    expect(manager.has(modelId)).toBe(true);
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    expect(listeners[0]).toHaveBeenCalledTimes(1);
+
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    // View B's listener hydrated once; view A's was left alone.
+    expect(listeners[1]).toHaveBeenCalledTimes(1);
+    expect(listeners[0]).toHaveBeenCalledTimes(1);
   });
 
-  it("should return the same binding for the same model id", () => {
-    const modelId = asModelId("model-1");
-    const binding1 = manager.getOrCreate(modelId);
-    const binding2 = manager.getOrCreate(modelId);
-    expect(binding1).toBe(binding2);
+  it("replays the any-change event to its listeners", async () => {
+    const model = new Model<ModelState>({ count: 1 }, createMockComm());
+    const onAnyChange = vi.fn();
+    const widgetDef = {
+      render: vi.fn(({ model }) => {
+        model.on("change", onAnyChange);
+      }),
+    };
+    const binding = await createBinding(widgetDef, model);
+    const controller = new AbortController();
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    expect(onAnyChange).toHaveBeenCalledTimes(1);
   });
 
-  it("should destroy and remove bindings", async () => {
-    const modelId = asModelId("model-1");
-    const binding = manager.getOrCreate(modelId);
-
-    const model = new Model<ModelState>({ count: 0 }, createMockComm());
-    const initCleanup = vi.fn();
+  it("does not replay initialize listeners", async () => {
+    // The guarantee is per-view: initialize listeners existed before
+    // any view, and replaying at them would fire once per mount.
+    const model = new Model<ModelState>({ count: 1 }, createMockComm());
+    const initListener = vi.fn();
     const widgetDef = {
-      initialize: vi.fn().mockResolvedValue(initCleanup),
+      initialize: vi.fn(({ model }) => {
+        model.on("change:count", initListener);
+      }),
       render: vi.fn(),
     };
-    await binding.bind(widgetDef, model);
-
-    manager.destroy(modelId);
-    expect(manager.has(modelId)).toBe(false);
-    expect(initCleanup).toHaveBeenCalledTimes(1);
+    const binding = await createBinding(widgetDef, model);
+    const controller = new AbortController();
+    await binding.createView(
+      { el: document.createElement("div") },
+      { signal: controller.signal },
+    );
+    expect(initListener).not.toHaveBeenCalled();
   });
 
-  it("should handle idempotent destroy", () => {
-    const modelId = asModelId("model-1");
-    manager.getOrCreate(modelId);
-
-    // Should not throw
-    manager.destroy(modelId);
-    manager.destroy(modelId);
-    expect(manager.has(modelId)).toBe(false);
+  it("clears the element before rendering into it", async () => {
+    const model = new Model<ModelState>({ count: 0 }, createMockComm());
+    const el = document.createElement("div");
+    el.innerHTML = "<span>stale content</span>";
+    const binding = await createBinding({ render: vi.fn() }, model);
+    const controller = new AbortController();
+    await binding.createView({ el }, { signal: controller.signal });
+    expect(el.innerHTML).toBe("");
   });
 });

package/src/plugins/impl/anywidget/__tests__/widget-ref.test.ts

@@ -0,0 +1,28 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+import { describe, expect, it } from "vitest";
+import { parseWidgetRef, WIDGET_REF_PREFIX } from "../widget-ref";
+
+describe("parseWidgetRef", () => {
+  it("parses an anywidget: ref", () => {
+    expect(parseWidgetRef(`${WIDGET_REF_PREFIX}abc-123`)).toBe("abc-123");
+  });
+
+  it("rejects the legacy IPY_MODEL_ prefix", () => {
+    expect(() => parseWidgetRef("IPY_MODEL_abc-123")).toThrow(/Invalid/);
+  });
+
+  it("rejects a bare model id", () => {
+    expect(() => parseWidgetRef("abc-123")).toThrow(/Invalid/);
+  });
+
+  it("rejects an empty model id", () => {
+    expect(() => parseWidgetRef(WIDGET_REF_PREFIX)).toThrow(/Invalid/);
+  });
+
+  it("rejects non-string inputs", () => {
+    expect(() => parseWidgetRef(undefined)).toThrow(/Invalid/);
+    expect(() => parseWidgetRef(null)).toThrow(/Invalid/);
+    expect(() => parseWidgetRef(42)).toThrow(/Invalid/);
+    expect(() => parseWidgetRef({ model_id: "abc" })).toThrow(/Invalid/);
+  });
+});

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

@@ -0,0 +1,54 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import type { AnyModel, Host, ResolvedWidget } from "@anywidget/types";
+import { modelProxy } from "./model-proxy";
+import type { Model } from "./model";
+import type { ModelState } from "./types";
+import type { WidgetModelId } from "./types";
+import { parseWidgetRef } from "./widget-ref";
+
+export type { Host, ResolvedWidget };
+
+export interface WidgetResolver {
+  getModel(key: WidgetModelId): Promise<Model<ModelState>>;
+  getWidget<T = unknown>(key: WidgetModelId): Promise<ResolvedWidget<T>>;
+}
+
+/**
+ * Build a `Host` scoped to a parent view's lifetime.
+ *
+ * The supplied `parentSignal` is used as the default for child renders
+ * that don't pass their own `signal` — so a child mounted via
+ * `host.getWidget(ref).render({ el })` is automatically torn down when
+ * the parent view tears down. Listeners that the child registers on its
+ * own model via `model.on(...)` are scoped to the same signal through
+ * `modelProxy`.
+ */
+export function createHost(
+  resolver: WidgetResolver,
+  parentSignal: AbortSignal,
+): Host {
+  return {
+    async getModel<T extends Record<string, unknown> = Record<string, unknown>>(
+      ref: string,
+    ): Promise<AnyModel<T>> {
+      const modelId = parseWidgetRef(ref);
+      const model = await resolver.getModel(modelId);
+      // Wrap in a proxy so listeners the parent registers on the child's
+      // model are auto-cleared when the parent's view tears down.
+      // The generic T is structural — modelProxy returns the underlying
+      // AnyModel shape regardless of T, which the caller narrows.
+      return modelProxy(model, parentSignal) as unknown as AnyModel<T>;
+    },
+    async getWidget<T = unknown>(ref: string): Promise<ResolvedWidget<T>> {
+      const modelId = parseWidgetRef(ref);
+      const widget = await resolver.getWidget<T>(modelId);
+      return {
+        exports: widget.exports,
+        async render({ el, signal }) {
+          await widget.render({ el, signal: signal ?? parentSignal });
+        },
+      };
+    },
+  };
+}