Move canvas routing from CanvasWidget to CanvasManagerWidget (#134)

rgbkrk · claude · web-flow · commit e21a2708d4a7 · 2026-02-06T15:39:37.000-08:00
Co-authored-by: Claude Haiku 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/content/docs/widgets/ipycanvas.mdx b/content/docs/widgets/ipycanvas.mdx
@@ -163,15 +163,43 @@ canvas.on_mouse_down(on_mouse_down)
 
 ipycanvas uses two widget models:
 
-- **`CanvasManagerModel`** - Headless widget that receives drawing commands as binary custom messages. Routes commands to the active canvas via `switchCanvas`.
-- **`CanvasModel`** - Visual widget that renders the HTML `<canvas>` element. Subscribes to its manager's custom messages and executes drawing commands on the 2D context.
+- **`CanvasManagerModel`** — Headless singleton (`_view_name: null`) that receives ALL drawing commands from Python as binary custom messages. Uses `switchCanvas` to indicate which canvas each command targets.
+- **`CanvasModel`** — Visual widget that renders an HTML `<canvas>` element. Subscribes to its own comm_id and executes drawing commands on the 2D context.
 
 Commands are serialized as binary buffers for performance. The first buffer contains JSON-encoded command metadata, and subsequent buffers carry binary data (e.g., NumPy arrays for batch operations).
 
 <Callout type="info">
-  The `hold_canvas()` context manager in Python batches many drawing commands into a single message for better performance.
+  The `hold_canvas()` context manager in Python batches many drawing commands into a single message for better performance. Without it, each drawing call is a separate message.
 </Callout>
 
+## Implementation Notes
+
+Our implementation differs from ipycanvas's original frontend in how command routing works. The binary protocol and command set are identical.
+
+### Store-level routing
+
+In ipycanvas's original Backbone.js frontend, each `CanvasView` subscribes to the `CanvasManagerModel`'s comm channel and tracks `switchCanvas` state locally. This means every canvas sees every command for every other canvas — they just filter locally.
+
+We route at the store level instead. `createCanvasManagerRouter` (in `canvas-manager-subscriptions.ts`) watches for `CanvasManagerModel` instances, subscribes to their messages, parses `switchCanvas` targets, and re-emits each message to only the targeted canvas's comm_id. Each `CanvasWidget` subscribes to its own comm_id and processes everything it receives — no filtering, no shared state.
+
+```
+Original ipycanvas:
+  Manager → broadcast to all canvases → each canvas filters locally
+
+nteract-elements:
+  Manager → store router parses switchCanvas → emits to target canvas only
+```
+
+This matters for correctness: with the broadcast approach, rapid animations on one canvas can interfere with other canvases' `switchCanvas` tracking. Store-level routing eliminates this by isolating each canvas completely.
+
+### Headless manager routing
+
+`CanvasManagerModel` has `_view_name: null` — it's never in the widget render tree and has no visual representation. The original frontend handles this inside `CanvasView` by reaching into the manager's model. We handle it at the store level via `createCanvasManagerRouter`, which follows the same pattern as `createLinkManager` for `jslink`/`jsdlink`. This runs in `WidgetStoreProvider` and requires no component to be mounted.
+
+### No Backbone.js
+
+ipycanvas's original frontend uses Backbone.js models and views. We use a pure React widget store with `useSyncExternalStore` for state and store-level subscriptions for custom messages.
+
 ## Not Yet Supported
 
 These features require cross-widget model resolution and are planned for a future release:
diff --git a/content/docs/widgets/meta.json b/content/docs/widgets/meta.json
@@ -6,6 +6,7 @@
     "anywidget-view",
     "controls",
     "output-widget",
+    "---Third Party Widgets---",
     "ipycanvas"
   ]
 }
diff --git a/registry/widgets/canvas-manager-subscriptions.ts b/registry/widgets/canvas-manager-subscriptions.ts
@@ -0,0 +1,132 @@
+/**
+ * Store-level routing for ipycanvas CanvasManagerModel.
+ *
+ * CanvasManagerModel is a headless widget (_view_name: null) that receives
+ * ALL drawing commands from Python. This module subscribes to each manager's
+ * custom messages, parses switchCanvas targets, and re-emits to each target
+ * canvas's comm_id — isolating canvases from each other.
+ *
+ * Same pattern as link-subscriptions.ts for LinkModel/DirectionalLinkModel.
+ *
+ * Usage:
+ *   const cleanup = createCanvasManagerRouter(store);
+ *   // ... later, to tear down all routing:
+ *   cleanup();
+ *
+ * WidgetStoreProvider calls this automatically. For non-React integrations
+ * (e.g. iframe isolation), call createCanvasManagerRouter directly.
+ */
+
+import { COMMANDS, getTypedArray } from "./ipycanvas/ipycanvas-commands";
+import type { WidgetStore } from "./widget-store";
+
+/**
+ * Walk a command structure and collect switchCanvas target IDs.
+ * Calls setTarget as a side effect so subsequent messages without
+ * switchCanvas route to the last known target.
+ */
+function collectSwitchCanvasTargets(
+  commands: unknown,
+  targets: Set<string>,
+  setTarget: (id: string) => void,
+): void {
+  if (!Array.isArray(commands) || commands.length === 0) return;
+
+  if (Array.isArray(commands[0])) {
+    for (const sub of commands) {
+      collectSwitchCanvasTargets(sub, targets, setTarget);
+    }
+  } else {
+    const cmdIndex = commands[0] as number;
+    if (COMMANDS[cmdIndex] === "switchCanvas") {
+      const args = commands[1] as string[] | undefined;
+      const ref = args?.[0] ?? "";
+      const targetId = ref.startsWith("IPY_MODEL_") ? ref.slice(10) : ref;
+      setTarget(targetId);
+      targets.add(targetId);
+    }
+  }
+}
+
+/**
+ * Set up message routing for a single CanvasManagerModel.
+ * Returns a cleanup function to tear down the subscription.
+ */
+function setupManagerRouting(
+  store: WidgetStore,
+  managerId: string,
+): () => void {
+  let currentTarget: string | null = null;
+
+  return store.subscribeToCustomMessage(managerId, (content, buffers) => {
+    if (!buffers || buffers.length === 0) return;
+
+    try {
+      const metadata = content as { dtype: string };
+      const typedArray = getTypedArray(buffers[0], metadata);
+      const jsonStr = new TextDecoder("utf-8").decode(typedArray);
+      const commands = JSON.parse(jsonStr);
+
+      const targets = new Set<string>();
+      collectSwitchCanvasTargets(commands, targets, (id) => {
+        currentTarget = id;
+      });
+
+      if (targets.size === 0 && currentTarget) {
+        targets.add(currentTarget);
+      }
+
+      const rawBuffers = buffers.map((dv) => dv.buffer as ArrayBuffer);
+      for (const targetId of targets) {
+        store.emitCustomMessage(targetId, content, rawBuffers);
+      }
+    } catch (err) {
+      console.warn("[ipycanvas] Manager routing error:", err);
+    }
+  });
+}
+
+/**
+ * Create a canvas manager router that monitors the store for
+ * CanvasManagerModel widgets and routes their messages to target canvases.
+ *
+ * Returns a cleanup function that tears down all active routing.
+ *
+ * Called automatically by WidgetStoreProvider. For non-React integrations
+ * (e.g. iframe isolation), call this directly after creating the store.
+ */
+export function createCanvasManagerRouter(store: WidgetStore): () => void {
+  const activeRoutes = new Map<string, () => void>();
+  let lastSize = -1;
+
+  function scan() {
+    const models = store.getSnapshot();
+
+    if (models.size === lastSize) return;
+    lastSize = models.size;
+
+    models.forEach((model, id) => {
+      if (activeRoutes.has(id)) return;
+
+      if (model.modelName === "CanvasManagerModel") {
+        activeRoutes.set(id, setupManagerRouting(store, id));
+      }
+    });
+
+    for (const [id, cleanup] of activeRoutes) {
+      if (!models.has(id)) {
+        cleanup();
+        activeRoutes.delete(id);
+      }
+    }
+  }
+
+  const unsubscribe = store.subscribe(scan);
+  scan();
+
+  return () => {
+    unsubscribe();
+    activeRoutes.forEach((cleanup) => cleanup());
+    activeRoutes.clear();
+  };
+}
diff --git a/registry/widgets/ipycanvas/canvas-widget.tsx b/registry/widgets/ipycanvas/canvas-widget.tsx
@@ -4,16 +4,15 @@
  * ipycanvas Canvas widget.
  *
  * Renders an HTML <canvas> element and processes drawing commands sent from
- * Python via the ipycanvas binary protocol. Commands arrive as custom messages
- * on the CanvasManagerModel and are executed on the canvas 2D context.
+ * Python via the ipycanvas binary protocol. Drawing commands arrive at each
+ * canvas's comm_id, routed by createCanvasManagerRouter at the store level.
  *
  * @see https://ipycanvas.readthedocs.io/
  */
 
 import { useCallback, useEffect, useRef } from "react";
 import { cn } from "@/lib/utils";
 import type { WidgetComponentProps } from "../widget-registry";
-import { parseModelRef } from "../widget-store";
 import {
   useWidgetModelValue,
   useWidgetStoreRequired,
@@ -29,16 +28,9 @@ export function CanvasWidget({ modelId, className }: WidgetComponentProps) {
   const ctxRef = useRef<CanvasRenderingContext2D | null>(null);
   // Track an async command processing chain so commands execute in order
   const processingRef = useRef<Promise<void>>(Promise.resolve());
-  // Track which canvas the manager last targeted via switchCanvas.
-  // In non-caching mode (the default, without hold_canvas()), each drawing
-  // command is a separate custom message. We need to persist the switchCanvas
-  // target across messages so each canvas only processes its own commands.
-  const activeCanvasRef = useRef<string | null>(null);
 
   const width = useWidgetModelValue<number>(modelId, "width") ?? 200;
   const height = useWidgetModelValue<number>(modelId, "height") ?? 200;
-  const canvasManagerRef =
-    useWidgetModelValue<string>(modelId, "_canvas_manager") ?? null;
   const sendClientReady =
     useWidgetModelValue<boolean>(modelId, "_send_client_ready_event") ?? true;
   const imageData = useWidgetModelValue<Uint8ClampedArray | null>(
@@ -67,18 +59,12 @@ export function CanvasWidget({ modelId, className }: WidgetComponentProps) {
     img.src = url;
   }, [imageData]);
 
-  // Subscribe to custom messages on the CanvasManagerModel, then send client_ready.
-  // These must be in the same effect so the subscription is active before
-  // Python replays drawing commands in response to client_ready.
+  // Subscribe to messages routed to this canvas's comm_id, then send
+  // client_ready. Routing is handled by createCanvasManagerRouter at the
+  // store level — this widget just processes what it receives.
   useEffect(() => {
-    if (!canvasManagerRef) return;
-
-    const managerModelId = parseModelRef(canvasManagerRef);
-    if (!managerModelId) return;
-
-    // Subscribe FIRST
     const unsubscribe = store.subscribeToCustomMessage(
-      managerModelId,
+      modelId,
       (content, buffers) => {
         const canvas = canvasRef.current;
         const ctx = ctxRef.current;
@@ -96,39 +82,27 @@ export function CanvasWidget({ modelId, className }: WidgetComponentProps) {
             // Remaining buffers are binary data for batch operations
             const dataBuffers = buffers.slice(1);
 
-            // Determine if this canvas is the active target based on the
-            // last switchCanvas we saw. Start inactive — a canvas should not
-            // draw until switchCanvas explicitly targets it.
-            const isActive = activeCanvasRef.current === modelId;
-
-            const result = await processCommands(
+            await processCommands(
               ctx,
               commands,
               dataBuffers,
               canvas,
               modelId,
-              isActive,
+              true,
             );
-
-            // Persist switchCanvas target across messages
-            if (result.switchedTo !== null) {
-              activeCanvasRef.current = result.switchedTo;
-            }
           } catch (err) {
             console.warn("[ipycanvas] Error processing commands:", err);
           }
         });
       },
     );
 
-    // THEN send client_ready — subscription is now active so
-    // replayed commands from Python will be received
     if (sendClientReady) {
       sendCustom(modelId, { event: "client_ready" });
     }
 
     return unsubscribe;
-  }, [canvasManagerRef, store, modelId, sendClientReady, sendCustom]);
+  }, [store, modelId, sendClientReady, sendCustom]);
 
   // Mouse event helpers
   const getCoordinates = useCallback(
@@ -223,9 +197,9 @@ export function CanvasWidget({ modelId, className }: WidgetComponentProps) {
 // === CanvasManagerWidget ===
 
 /**
- * Headless widget for CanvasManagerModel.
- * The manager coordinates drawing commands but has no visual representation.
- * Command processing is handled via custom message subscriptions from CanvasWidget.
+ * Stub for CanvasManagerModel. Routing is handled at the store level
+ * by createCanvasManagerRouter. CanvasManagerModel has _view_name: null
+ * and is never rendered.
  */
 export function CanvasManagerWidget(_props: WidgetComponentProps) {
   return null;
diff --git a/registry/widgets/ipycanvas/ipycanvas-commands.ts b/registry/widgets/ipycanvas/ipycanvas-commands.ts
@@ -213,7 +213,6 @@ function getArg(metadata: unknown, buffers: DataView[]): Arg {
 // === Drawing Helpers ===
 
 function drawRects(
-  ctx: CanvasRenderingContext2D,
   args: unknown[],
   buffers: DataView[],
   callback: (x: number, y: number, w: number, h: number) => void,
@@ -230,7 +229,6 @@ function drawRects(
 }
 
 function drawCircles(
-  ctx: CanvasRenderingContext2D,
   args: unknown[],
   buffers: DataView[],
   callback: (x: number, y: number, r: number) => void,
@@ -246,7 +244,6 @@ function drawCircles(
 }
 
 function drawArcs(
-  ctx: CanvasRenderingContext2D,
   args: unknown[],
   buffers: DataView[],
   callback: (
@@ -701,24 +698,24 @@ export async function processCommands(
 
     // --- Batch drawing ---
     case "fillRects":
-      drawRects(ctx, args, buffers, (x, y, w, h) => ctx.fillRect(x, y, w, h));
+      drawRects(args, buffers, (x, y, w, h) => ctx.fillRect(x, y, w, h));
       break;
     case "strokeRects":
-      drawRects(ctx, args, buffers, (x, y, w, h) => ctx.strokeRect(x, y, w, h));
+      drawRects(args, buffers, (x, y, w, h) => ctx.strokeRect(x, y, w, h));
       break;
     case "fillCircles":
-      drawCircles(ctx, args, buffers, (x, y, r) => fillCircle(ctx, x, y, r));
+      drawCircles(args, buffers, (x, y, r) => fillCircle(ctx, x, y, r));
       break;
     case "strokeCircles":
-      drawCircles(ctx, args, buffers, (x, y, r) => strokeCircle(ctx, x, y, r));
+      drawCircles(args, buffers, (x, y, r) => strokeCircle(ctx, x, y, r));
       break;
     case "fillArcs":
-      drawArcs(ctx, args, buffers, (x, y, r, sa, ea, ac) =>
+      drawArcs(args, buffers, (x, y, r, sa, ea, ac) =>
         fillArc(ctx, x, y, r, sa, ea, ac),
       );
       break;
     case "strokeArcs":
-      drawArcs(ctx, args, buffers, (x, y, r, sa, ea, ac) =>
+      drawArcs(args, buffers, (x, y, r, sa, ea, ac) =>
         strokeArc(ctx, x, y, r, sa, ea, ac),
       );
       break;
diff --git a/registry/widgets/widget-store-context.tsx b/registry/widgets/widget-store-context.tsx
@@ -21,6 +21,7 @@ import {
   useRef,
   useSyncExternalStore,
 } from "react";
+import { createCanvasManagerRouter } from "./canvas-manager-subscriptions";
 import { createLinkManager } from "./link-subscriptions";
 import {
   type JupyterCommMessage,
@@ -91,6 +92,7 @@ export function WidgetStoreProvider({
   // Headless widgets like LinkModel have _view_name: null and won't be
   // in any container's children, so they need store-level subscriptions.
   useEffect(() => createLinkManager(store), [store]);
+  useEffect(() => createCanvasManagerRouter(store), [store]);
 
   // Use the comm router hook for message handling
   const { handleMessage, sendUpdate, sendCustom, closeComm } = useCommRouter({
@@ -235,7 +237,8 @@ export function useWasWidgetClosed(modelId: string): boolean {
   return store.wasModelClosed(modelId);
 }
 
-// Re-export link manager for non-React integrations (e.g. iframe isolation)
+// Re-export store-level managers for non-React integrations (e.g. iframe isolation)
+export { createCanvasManagerRouter } from "./canvas-manager-subscriptions";
 export { createLinkManager } from "./link-subscriptions";
 export type {
   JupyterCommMessage,

Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@`
`6`	`6`	`"anywidget-view",`
`7`	`7`	`"controls",`
`8`	`8`	`"output-widget",`
	`9`	`+ "---Third Party Widgets---",`
`9`	`10`	`"ipycanvas"`
`10`	`11`	`]`
`11`	`12`	`}`