nudge-ui 0.2.0 → 0.2.2

package/dist/inspector/canvas/rendererElementSelector.js

@@ -1,16 +1,18 @@
-import { PROTOCOL_VERSION, getRendererIdentity, sendToParent, } from "./frameProtocol.js";
-import { findClosestAnchor, isEligibleNavigation, hasDifferentRoute, shouldPreserveNativeLinkActivation, } from "./linkEligibility.js";
+import { PROTOCOL_VERSION, getRendererIdentity, sendToParent, isKeyboardShortcutCode, } from "./frameProtocol.js";
 import { readBorderWidths, readMargins } from "../overlay/overlayGeometry.js";
 import { installInteractionStyles } from "../overlay/interactionStyles.js";
 import { createFrameThrottle } from "../overlay/frameThrottle.js";
 import { createCidIndex } from "./rendererCidIndex.js";
 import { isNudgeUiDev } from "../runtime/devFlag.js";
-import { isEditableEvent } from "../shell/shortcuts.js";
+import { isEditableEvent, isInspectorToggleShortcut, isSendPromptShortcut } from "../shell/shortcuts.js";
 import { resolveSelectionTarget, selectionTargetMode } from "../selection/selectionTarget.js";
 import { escapeCssString } from "../projection/cssEscapes.js";
-import { blockApplicationClick, isApplicationActivationClick } from "../overlay/clickPolicy.js";
+import { APPLICATION_GESTURE_EVENTS, blockApplicationClick, blockApplicationGesture, isInlineEditorTarget, isUserClick, } from "../overlay/clickPolicy.js";
+import { EMPTY_TEXT_PROJECTION_ATTR } from "../projection/textProjection.js";
+import { getSpacingAffordanceAtPoint, toSpacingDescriptor, } from "../overlay/spacingGestures.js";
 const REACT_FIBER_KEY = /^__reactFiber\$/;
 const REACT_INTERNAL_KEY = /^__reactInternalInstance\$/;
+const HOVER_SCROLL_SETTLE_DELAY = 150;
 function findFiber(el) {
     const keys = Object.keys(el);
     for (const key of keys) {
@@ -75,24 +77,73 @@ export function buildSelector(el) {
 }
 let installed = false;
 const noopDisposal = () => undefined;
-export function installRendererElementSelector() {
+export function installRendererElementSelector(acceptsClick = isUserClick) {
     if (!isNudgeUiDev())
         return noopDisposal;
     if (installed)
         return noopDisposal;
     installed = true;
-    const removeInteractionStyles = installInteractionStyles();
+    let removeInteractionStyles = installInteractionStyles();
     const listenerCleanup = [];
     let disposed = false;
+    let interactionsSuspended = false;
+    let scrolling = false;
+    let scrollSettleTimer = null;
+    let activeHoverElement = null;
+    let suppressHoverDuringSpacingDrag = false;
+    let lastHoverPoint = null;
     function trackListener(target, type, listener, options) {
         const eventListener = (event) => listener(event);
         target.addEventListener(type, eventListener, options);
         listenerCleanup.push(() => target.removeEventListener(type, eventListener, options));
     }
     const cidIndex = createCidIndex(document);
-    const hoverUpdate = createFrameThrottle((pending) => {
-        if (disposed)
-            return;
+    const initialCursor = document.documentElement.style.getPropertyValue("cursor");
+    const initialCursorPriority = document.documentElement.style.getPropertyPriority("cursor");
+    let appliedRootCursor = null;
+    let spacingCursor = null;
+    function clearSpacingCursor() {
+        const active = spacingCursor;
+        spacingCursor = null;
+        if (active
+            && active.element.style.getPropertyValue("cursor") === active.appliedValue
+            && active.element.style.getPropertyPriority("cursor") === "important") {
+            if (active.previousValue) {
+                active.element.style.setProperty("cursor", active.previousValue, active.previousPriority);
+            }
+            else {
+                active.element.style.removeProperty("cursor");
+            }
+        }
+        if (appliedRootCursor !== null
+            && document.documentElement.style.getPropertyValue("cursor") === appliedRootCursor) {
+            if (initialCursor) {
+                document.documentElement.style.setProperty("cursor", initialCursor, initialCursorPriority);
+            }
+            else {
+                document.documentElement.style.removeProperty("cursor");
+            }
+        }
+        appliedRootCursor = null;
+    }
+    function setSpacingCursor(element, cursor) {
+        if (spacingCursor?.element !== element) {
+            clearSpacingCursor();
+            spacingCursor = {
+                element,
+                previousValue: element.style.getPropertyValue("cursor"),
+                previousPriority: element.style.getPropertyPriority("cursor"),
+                appliedValue: cursor,
+            };
+        }
+        else {
+            spacingCursor.appliedValue = cursor;
+        }
+        element.style.setProperty("cursor", cursor, "important");
+        document.documentElement.style.setProperty("cursor", cursor);
+        appliedRootCursor = cursor;
+    }
+    function reportHover(pending) {
         const { element, clear } = pending;
         const identity = getRendererIdentity();
         if (!identity)
@@ -101,6 +152,17 @@ export function installRendererElementSelector() {
         const selector = buildSelector(element);
         const src = element.getAttribute("data-src") ?? "";
         const rect = clear ? null : element.getBoundingClientRect();
+        const rawSpacing = !clear && pending.point
+            ? getSpacingAffordanceAtPoint(document, pending.point.x, pending.point.y)
+            : null;
+        const spacing = rawSpacing && rawSpacing.element === element ? rawSpacing : null;
+        if (spacing) {
+            setSpacingCursor(spacing.element, spacing.cursor);
+        }
+        else {
+            clearSpacingCursor();
+        }
+        activeHoverElement = clear ? null : element;
         const msg = {
             type: "element-hover",
             protocolVersion: PROTOCOL_VERSION,
@@ -118,10 +180,49 @@ export function installRendererElementSelector() {
                 : null,
             margins: rect ? readMargins(element) : null,
             borders: rect ? readBorderWidths(element) : null,
+            point: pending.point,
+            spacing: spacing ? toSpacingDescriptor(spacing) : null,
             ...identity,
         };
         sendToParent(msg);
+    }
+    const hoverUpdate = createFrameThrottle((pending) => {
+        if (disposed || scrolling || suppressHoverDuringSpacingDrag)
+            return;
+        reportHover(pending);
     });
+    function clearActiveHover() {
+        hoverUpdate.cancel();
+        clearSpacingCursor();
+        const element = activeHoverElement;
+        activeHoverElement = null;
+        if (element)
+            reportHover({ element, clear: true, point: null });
+    }
+    function resumeHoverAfterScroll() {
+        scrollSettleTimer = null;
+        scrolling = false;
+        if (disposed || interactionsSuspended || suppressHoverDuringSpacingDrag || !lastHoverPoint)
+            return;
+        const target = document.elementFromPoint?.(lastHoverPoint.x, lastHoverPoint.y);
+        const element = resolveSelectionTarget(target, lastHoverPoint.mode);
+        if (!element)
+            return;
+        hoverUpdate.schedule({
+            element,
+            clear: false,
+            point: { x: lastHoverPoint.x, y: lastHoverPoint.y },
+        });
+    }
+    function suppressHoverDuringScroll() {
+        if (disposed || interactionsSuspended)
+            return;
+        scrolling = true;
+        clearActiveHover();
+        if (scrollSettleTimer !== null)
+            window.clearTimeout(scrollSettleTimer);
+        scrollSettleTimer = window.setTimeout(resumeHoverAfterScroll, HOVER_SCROLL_SETTLE_DELAY);
+    }
     let measurePointerOverPage = false;
     let measureAltKey = false;
     function updateMeasureState(altKey, pointerOverPage) {
@@ -144,39 +245,189 @@ export function installRendererElementSelector() {
         sendToParent(msg);
     }
     trackListener(document, "mouseover", (event) => {
+        if (interactionsSuspended)
+            return;
         updateMeasureState(event.altKey, true);
+        if (suppressHoverDuringSpacingDrag)
+            return;
         const target = event.target;
         if (!(target instanceof Element))
             return;
         const el = resolveSelectionTarget(target, selectionTargetMode(event));
         if (!el)
             return;
-        hoverUpdate.schedule({ element: el, clear: false });
+        lastHoverPoint = { x: event.clientX, y: event.clientY, mode: selectionTargetMode(event) };
+        if (scrolling)
+            return;
+        hoverUpdate.schedule({ element: el, clear: false, point: { x: event.clientX, y: event.clientY } });
     }, true);
+    trackListener(window, "scroll", suppressHoverDuringScroll, true);
     let pendingDrag = null;
     let dragging = false;
+    let lastDragPoint = null;
     let lastSelected = null;
-    const dragMoveUpdate = createFrameThrottle((point) => {
+    trackListener(window, "nudge-ui:open", () => {
+        const identity = getRendererIdentity();
+        if (!identity)
+            return;
+        const message = {
+            type: "inspector-open-request",
+            protocolVersion: PROTOCOL_VERSION,
+            ...identity,
+        };
+        sendToParent(message);
+    });
+    trackListener(window, "message", (event) => {
+        if (event.origin !== window.location.origin || event.source !== window.parent)
+            return;
+        const identity = getRendererIdentity();
+        const message = event.data;
+        if (!identity || !message
+            || message.protocolVersion !== PROTOCOL_VERSION
+            || message.projectId !== identity.projectId
+            || message.workspaceId !== identity.workspaceId
+            || message.cardId !== identity.cardId)
+            return;
+        if (message.type === "measure-modifier" && typeof message.altKey === "boolean") {
+            updateMeasureState(message.altKey, measurePointerOverPage);
+            return;
+        }
+        if (message.type !== "inspector-interaction-state" || typeof message.open !== "boolean")
+            return;
+        const interactionsEnabled = message.interactionsEnabled === undefined
+            ? message.open
+            : message.interactionsEnabled === true;
+        interactionsSuspended = !interactionsEnabled;
+        if (message.open) {
+            document.documentElement.setAttribute("data-nudge-ui-panel", "open");
+        }
+        else {
+            document.documentElement.removeAttribute("data-nudge-ui-panel");
+        }
+        if (interactionsSuspended) {
+            cancelActiveDrag();
+            clearActiveHover();
+            if (scrollSettleTimer !== null)
+                window.clearTimeout(scrollSettleTimer);
+            scrollSettleTimer = null;
+            scrolling = false;
+            updateMeasureState(false, false);
+            removeInteractionStyles?.();
+            removeInteractionStyles = null;
+        }
+        else {
+            removeInteractionStyles ??= installInteractionStyles();
+        }
+    });
+    const dragMoveUpdate = createFrameThrottle((drag) => {
         if (disposed)
             return;
         const identity = getRendererIdentity();
-        if (!point || !identity)
+        if (!drag || !identity)
             return;
-        const msg = { type: "element-drag-move", protocolVersion: PROTOCOL_VERSION, point, ...identity };
+        const msg = {
+            type: "element-drag-move",
+            protocolVersion: PROTOCOL_VERSION,
+            point: drag.point,
+            shiftKey: drag.shiftKey,
+            ...identity,
+        };
         sendToParent(msg);
     });
+    function sendDragEnd(point, cancelled, shiftKey = false) {
+        if (!dragging || !point)
+            return;
+        const identity = getRendererIdentity();
+        if (!identity)
+            return;
+        const msg = {
+            type: "element-drag-end",
+            protocolVersion: PROTOCOL_VERSION,
+            point,
+            shiftKey,
+            ...(cancelled ? { cancelled: true } : {}),
+            ...identity,
+        };
+        sendToParent(msg);
+    }
+    function cancelActiveDrag() {
+        dragMoveUpdate.cancel();
+        sendDragEnd(lastDragPoint, true);
+        pendingDrag = null;
+        dragging = false;
+        suppressHoverDuringSpacingDrag = false;
+    }
     trackListener(document, "mousedown", (event) => {
+        if (interactionsSuspended)
+            return;
         if (event.button !== 0)
             return;
         const element = resolveSelectionTarget(event.target, selectionTargetMode(event));
         if (!element)
             return;
+        const spacingAffordance = getSpacingAffordanceAtPoint(document, event.clientX, event.clientY);
+        const spacing = spacingAffordance?.element === element
+            ? toSpacingDescriptor(spacingAffordance)
+            : null;
+        if (spacing) {
+            suppressHoverDuringSpacingDrag = true;
+            hoverUpdate.cancel();
+            lastHoverPoint = null;
+        }
+        const identity = getRendererIdentity();
+        // A spacing drag owns the pointer gesture. Do not start an inline-text
+        // attempt for the same down event; padding and gaps are intentionally not
+        // editable text targets.
+        if (identity && !spacing) {
+            const emptyProjectionId = event.target instanceof Element
+                ? event.target.closest(`[${EMPTY_TEXT_PROJECTION_ATTR}]`)?.getAttribute(EMPTY_TEXT_PROJECTION_ATTR) ?? undefined
+                : undefined;
+            const message = {
+                type: "inline-text-intent",
+                protocolVersion: PROTOCOL_VERSION,
+                intent: emptyProjectionId && event.detail >= 2 ? "double-click" : "pointer-down",
+                cid: element.getAttribute("data-cid"),
+                src: element.getAttribute("data-src") ?? "",
+                elementId: cidIndex.elementId(element),
+                point: { x: event.clientX, y: event.clientY },
+                clickCount: event.detail,
+                emptyProjectionId,
+                ...identity,
+            };
+            sendToParent(message);
+        }
         lastSelected = element;
-        pendingDrag = { element, point: { x: event.clientX, y: event.clientY } };
+        pendingDrag = {
+            element,
+            point: { x: event.clientX, y: event.clientY },
+            spacing,
+        };
+        lastDragPoint = { x: event.clientX, y: event.clientY };
     }, true);
+    for (const type of APPLICATION_GESTURE_EVENTS) {
+        trackListener(document, type, (event) => {
+            if (interactionsSuspended || !acceptsClick(event) || isInlineEditorTarget(event.target))
+                return;
+            blockApplicationGesture(event);
+        }, true);
+    }
     trackListener(document, "mousemove", (event) => {
-        if (!pendingDrag)
+        if (!pendingDrag) {
+            if (interactionsSuspended)
+                return;
+            const target = event.target;
+            if (target instanceof Element) {
+                const mode = selectionTargetMode(event);
+                const element = resolveSelectionTarget(target, mode);
+                if (element) {
+                    lastHoverPoint = { x: event.clientX, y: event.clientY, mode };
+                    if (scrolling)
+                        return;
+                    hoverUpdate.schedule({ element, clear: false, point: { x: event.clientX, y: event.clientY } });
+                }
+            }
             return;
+        }
         if (!dragging && Math.hypot(event.clientX - pendingDrag.point.x, event.clientY - pendingDrag.point.y) < 6)
             return;
         const identity = getRendererIdentity();
@@ -184,41 +435,93 @@ export function installRendererElementSelector() {
             return;
         event.preventDefault();
         const point = { x: event.clientX, y: event.clientY };
+        lastDragPoint = point;
         if (!dragging) {
             dragging = true;
             const msg = {
                 type: "element-drag-start", protocolVersion: PROTOCOL_VERSION,
                 cid: pendingDrag.element.getAttribute("data-cid"), src: pendingDrag.element.getAttribute("data-src") ?? "",
-                elementId: cidIndex.elementId(pendingDrag.element), point, ...identity,
+                elementId: cidIndex.elementId(pendingDrag.element), point,
+                startPoint: pendingDrag.point,
+                spacing: pendingDrag.spacing,
+                shiftKey: event.shiftKey,
+                ...identity,
             };
             sendToParent(msg);
         }
         else {
-            dragMoveUpdate.schedule(point);
+            dragMoveUpdate.schedule({ point, shiftKey: event.shiftKey });
         }
     }, true);
     function finishDrag(event) {
         dragMoveUpdate.cancel();
         if (dragging) {
-            const identity = getRendererIdentity();
-            if (identity) {
-                event.preventDefault();
-                const msg = {
-                    type: "element-drag-end", protocolVersion: PROTOCOL_VERSION,
-                    point: { x: event.clientX, y: event.clientY }, ...identity,
-                };
-                sendToParent(msg);
-            }
+            event.preventDefault();
+            const point = { x: event.clientX, y: event.clientY };
+            lastDragPoint = point;
+            sendDragEnd(point, false, event.shiftKey);
         }
         pendingDrag = null;
         dragging = false;
+        suppressHoverDuringSpacingDrag = false;
     }
     trackListener(document, "mouseup", finishDrag, true);
-    trackListener(document, "keydown", (event) => {
-        if (event.key === "Alt")
-            updateMeasureState(true, measurePointerOverPage);
+    function forwardKeyboardShortcut(event, phase) {
+        const code = isKeyboardShortcutCode(event.code) ? event.code : null;
+        if (!code)
+            return false;
+        if (code === "KeyS") {
+            if (phase !== "keydown" || !isSendPromptShortcut(event))
+                return false;
+        }
+        else if (code !== "Backslash" && interactionsSuspended) {
+            return false;
+        }
+        if (phase === "keydown") {
+            if (code !== "KeyS" && (event.repeat || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || isEditableEvent(event)))
+                return false;
+        }
+        else if (code !== "Backslash") {
+            return false;
+        }
+        const identity = getRendererIdentity();
+        if (!identity)
+            return false;
+        const message = {
+            type: "keyboard-shortcut",
+            protocolVersion: PROTOCOL_VERSION,
+            phase,
+            code,
+            ...identity,
+        };
+        sendToParent(message);
+        return phase === "keydown";
+    }
+    // Global tool shortcuts need to run before application capture handlers on
+    // the iframe document. A page-level window handler can otherwise stop the
+    // event before it reaches the document listener.
+    trackListener(window, "keydown", (event) => {
         if (isEditableEvent(event))
             return;
+        if (forwardKeyboardShortcut(event, "keydown"))
+            event.preventDefault();
+        if (isInspectorToggleShortcut(event)) {
+            const identity = getRendererIdentity();
+            if (!identity)
+                return;
+            event.preventDefault();
+            const msg = {
+                type: "inspector-toggle-request",
+                protocolVersion: PROTOCOL_VERSION,
+                ...identity,
+            };
+            sendToParent(msg);
+            return;
+        }
+        if (interactionsSuspended)
+            return;
+        if (event.key === "Alt")
+            updateMeasureState(true, measurePointerOverPage);
         const scrollKey = event.code === "Space"
             || event.key === "ArrowUp"
             || event.key === "ArrowDown"
@@ -242,6 +545,8 @@ export function installRendererElementSelector() {
         }
         if (event.key === "Escape" || event.key === "Esc") {
             event.preventDefault();
+            cancelActiveDrag();
+            clearSpacingCursor();
             lastSelected = null;
             const identity = getRendererIdentity();
             if (!identity)
@@ -279,21 +584,28 @@ export function installRendererElementSelector() {
         };
         sendToParent(msg);
     }, true);
-    trackListener(document, "keyup", (event) => {
+    trackListener(window, "keyup", (event) => {
+        forwardKeyboardShortcut(event, "keyup");
         if (event.key === "Alt")
             updateMeasureState(false, measurePointerOverPage);
     }, true);
     trackListener(window, "blur", () => {
+        cancelActiveDrag();
         updateMeasureState(false, false);
     });
     trackListener(document, "mouseout", (event) => {
+        if (interactionsSuspended)
+            return;
         const target = event.target;
         if (!(target instanceof HTMLElement))
             return;
         const related = event.relatedTarget;
         if (!(related instanceof Node) || !document.contains(related)) {
             updateMeasureState(event.altKey, false);
+            lastHoverPoint = null;
         }
+        if (scrolling)
+            return;
         if (related instanceof Node && (target.contains(related) || target === related))
             return;
         if (!(target instanceof Element))
@@ -303,40 +615,47 @@ export function installRendererElementSelector() {
             return;
         if (resolveSelectionTarget(related, selectionTargetMode(event)))
             return;
-        hoverUpdate.schedule({ element: el, clear: true });
+        clearSpacingCursor();
+        hoverUpdate.schedule({ element: el, clear: true, point: null });
+    }, true);
+    trackListener(document, "dblclick", (event) => {
+        if (interactionsSuspended)
+            return;
+        const element = resolveSelectionTarget(event.target, selectionTargetMode(event));
+        const identity = getRendererIdentity();
+        if (!element || !identity)
+            return;
+        blockApplicationClick(event);
+        const message = {
+            type: "inline-text-intent",
+            protocolVersion: PROTOCOL_VERSION,
+            intent: "double-click",
+            cid: element.getAttribute("data-cid"),
+            src: element.getAttribute("data-src") ?? "",
+            elementId: cidIndex.elementId(element),
+            point: { x: event.clientX, y: event.clientY },
+            emptyProjectionId: event.target instanceof Element
+                ? event.target.closest(`[${EMPTY_TEXT_PROJECTION_ATTR}]`)?.getAttribute(EMPTY_TEXT_PROJECTION_ATTR) ?? undefined
+                : undefined,
+            ...identity,
+        };
+        sendToParent(message);
     }, true);
     trackListener(document, "click", (event) => {
+        if (interactionsSuspended || !acceptsClick(event))
+            return;
         const target = event.target;
         if (!(target instanceof Element))
             return;
-        // Defer to navigation-intent when the user clicked a navigable same-origin
-        // anchor that points to a different route. In canvas mode, anchor clicks
-        // should create (or focus) a sibling card rather than selecting the anchor
-        // itself. The navigation-intent listener is registered AFTER this one, so
-        // we must NOT stop propagation here. Left to its own default the click would
-        // perform a full-frame navigation inside the iframe; the navigation-intent
-        // handler calls preventDefault once it has gathered the anchor href.
-        const anchor = findClosestAnchor(target);
-        if (anchor && isEligibleNavigation(anchor, event) && hasDifferentRoute(anchor)) {
-            return;
-        }
-        // Command/Ctrl+Shift-click is the deliberate escape hatch for running
-        // the application action. All other selected canvas clicks are editing
-        // gestures and must not reach the rendered application.
-        if (isApplicationActivationClick(event))
-            return;
-        const preserveNativeLink = anchor
-            ? shouldPreserveNativeLinkActivation(anchor, event)
-            : false;
+        // Design-tool clicks are editing gestures and must not reach the
+        // rendered application; the Select tool is how the app receives them.
         const el = resolveSelectionTarget(target, selectionTargetMode(event));
         if (!el) {
-            if (!preserveNativeLink)
-                blockApplicationClick(event);
+            blockApplicationClick(event);
             return;
         }
         lastSelected = el;
-        if (!preserveNativeLink)
-            blockApplicationClick(event);
+        blockApplicationClick(event);
         const cid = el.getAttribute("data-cid");
         const selector = buildSelector(el);
         const { file, line, component, src } = getFiberInfo(el);
@@ -361,18 +680,26 @@ export function installRendererElementSelector() {
     return () => {
         if (disposed)
             return;
+        cancelActiveDrag();
         disposed = true;
         installed = false;
         hoverUpdate.cancel();
-        dragMoveUpdate.cancel();
+        if (scrollSettleTimer !== null)
+            window.clearTimeout(scrollSettleTimer);
+        scrollSettleTimer = null;
         for (const cleanup of listenerCleanup)
             cleanup();
         listenerCleanup.length = 0;
-        removeInteractionStyles();
-        pendingDrag = null;
-        dragging = false;
+        removeInteractionStyles?.();
+        removeInteractionStyles = null;
         lastSelected = null;
+        activeHoverElement = null;
+        lastHoverPoint = null;
+        scrolling = false;
+        suppressHoverDuringSpacingDrag = false;
         measurePointerOverPage = false;
         measureAltKey = false;
+        document.documentElement.removeAttribute("data-nudge-ui-panel");
+        clearSpacingCursor();
     };
 }

package/dist/inspector/canvas/rendererMessageRouter.d.ts

@@ -0,0 +1,11 @@
+import { type FrameIdentity, type FrameProtocolMessage } from "./frameProtocol.js";
+export interface CanvasRendererMessage {
+    cardId: string;
+    iframe: HTMLIFrameElement;
+    identity: FrameIdentity;
+    message: FrameProtocolMessage;
+}
+type CanvasRendererMessageListener = (event: CanvasRendererMessage) => void;
+/** Subscribes to same-origin messages from registered Canvas renderer frames. */
+export declare function subscribeCanvasRendererMessages(listener: CanvasRendererMessageListener): () => void;
+export {};

package/dist/inspector/canvas/rendererMessageRouter.js

@@ -0,0 +1,43 @@
+import { isRendererMessageFor, PROTOCOL_VERSION, } from "./frameProtocol.js";
+import { findCanvasFrameBySource, PROJECT_ID, WORKSPACE_ID } from "./projection.js";
+const listeners = new Set();
+function routeRendererMessage(event) {
+    if (event.origin !== window.location.origin || !event.data || typeof event.data !== "object")
+        return;
+    const frame = findCanvasFrameBySource(event.source);
+    if (!frame)
+        return;
+    const identity = {
+        projectId: PROJECT_ID,
+        workspaceId: WORKSPACE_ID,
+        cardId: frame.cardId,
+    };
+    // SAFETY: The object guard above makes the optional discriminator fields safe to inspect.
+    const candidate = event.data;
+    if (candidate.type === "renderer-hello") {
+        if (candidate.protocolVersion !== PROTOCOL_VERSION)
+            return;
+    }
+    else if (!isRendererMessageFor(event.data, identity)) {
+        return;
+    }
+    const routed = {
+        ...frame,
+        identity,
+        // SAFETY: Subscribers narrow the discriminated protocol union before reading message-specific fields.
+        message: event.data,
+    };
+    for (const listener of listeners)
+        listener(routed);
+}
+/** Subscribes to same-origin messages from registered Canvas renderer frames. */
+export function subscribeCanvasRendererMessages(listener) {
+    if (listeners.size === 0)
+        window.addEventListener("message", routeRendererMessage);
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+            window.removeEventListener("message", routeRendererMessage);
+    };
+}