nudge-ui 0.2.1 → 0.2.2

package/dist/inspector/agent/httpTransport.js

@@ -18,6 +18,7 @@ function endpointValue(value) {
         statusUrl: stringValue(value.statusUrl),
         canvasAckUrl: stringValue(value.canvasAckUrl),
         disconnectUrl: stringValue(value.disconnectUrl),
+        takeoverUrl: stringValue(value.takeoverUrl),
         ...(value.autoConnect === true ? { autoConnect: true } : {}),
     };
     return Object.values(config).some((entry) => entry !== undefined) ? config : undefined;
@@ -96,6 +97,16 @@ function headers() {
         Accept: "application/json",
     };
 }
+export class AgentBridgeHttpError extends Error {
+    status;
+    code;
+    constructor(status, message, code) {
+        super(message);
+        this.name = "AgentBridgeHttpError";
+        this.status = status;
+        this.code = code;
+    }
+}
 async function readJson(response) {
     let payload;
     try {
@@ -107,7 +118,8 @@ async function readJson(response) {
     if (!response.ok) {
         const error = isRecord(payload) && isRecord(payload.error) ? payload.error : payload;
         const message = isRecord(error) ? stringValue(error.message) : undefined;
-        throw new Error(message ?? `Agent bridge request failed (${response.status}).`);
+        const code = isRecord(error) ? stringValue(error.code) : undefined;
+        throw new AgentBridgeHttpError(response.status, message ?? `Agent bridge request failed (${response.status}).`, code);
     }
     return isRecord(payload) ? payload : {};
 }
@@ -253,6 +265,34 @@ export class HttpAgentBridgeTransport {
             status,
         };
     }
+    async takeOver(request, signal) {
+        const url = endpointUrl(this.config, request.projectId, "takeoverUrl", "/takeover", pageOrigin());
+        if (!url || typeof fetch !== "function")
+            throw new Error("Agent bridge is unavailable.");
+        const response = await fetch(url, {
+            method: "POST",
+            headers: { ...headers(), "Content-Type": "application/json" },
+            body: JSON.stringify(request),
+            signal,
+        });
+        const payload = await readJson(response);
+        if (payload.protocolVersion !== AGENT_PROTOCOL_VERSION
+            || payload.projectId !== request.projectId
+            || payload.origin !== request.origin
+            || typeof payload.sessionToken !== "string") {
+            throw new Error("Agent bridge returned an invalid takeover response.");
+        }
+        const status = statusPayload(payload.status);
+        if (!status)
+            throw new Error("Agent bridge returned an invalid status.");
+        return {
+            protocolVersion: AGENT_PROTOCOL_VERSION,
+            projectId: request.projectId,
+            origin: request.origin,
+            sessionToken: payload.sessionToken,
+            status,
+        };
+    }
     async restore(request, signal) {
         const url = endpointUrl(this.config, request.projectId, "statusUrl", "/status", pageOrigin());
         if (!url || typeof fetch !== "function")

package/dist/inspector/agent/protocol.d.ts

@@ -18,6 +18,7 @@ export interface AgentBridgeEndpointConfig {
     readonly statusUrl?: string;
     readonly canvasAckUrl?: string;
     readonly disconnectUrl?: string;
+    readonly takeoverUrl?: string;
     /** Pair automatically when this endpoint came from the trusted dev host. */
     readonly autoConnect?: boolean;
 }
@@ -87,6 +88,8 @@ export interface AgentBridgeTransport {
     readonly openEvents: (request: AgentEventsRequest, handlers: AgentEventHandlers) => AgentEventSubscription;
     readonly dispatch: (request: AgentPromptDispatch, signal?: AbortSignal) => Promise<PromptDispatchResponse | null>;
     readonly disconnect?: (request: AgentDisconnectRequest, signal?: AbortSignal) => Promise<void>;
+    /** Deliberately revokes another browser pairing before pairing this page. */
+    readonly takeOver?: (request: AgentPairRequest, signal?: AbortSignal) => Promise<PairingResponse>;
     readonly acknowledgeCanvasCommand?: (request: AgentCanvasAcknowledgementRequest, signal?: AbortSignal) => Promise<void>;
 }
 export interface AgentClientOptions {

package/dist/inspector/canvas/CanvasElementOverlay.js

@@ -3,7 +3,7 @@ import { useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } fro
 import { PROTOCOL_VERSION, isElementClickMessage, isInlineTextIntentMessage, } from "./frameProtocol.js";
 import { useBoardCamera, useCanvasCards, useCanvasPresentation, useCanvasPresentationTransitioning } from "./canvasStore.js";
 import { handleElementClick } from "./rendererSelectionProxy.js";
-import { getSelectedElements, useSelectedElement, useSelectedElements } from "../selection/selectionStore.js";
+import { getSelectedElements, useHierarchy, useSelectedElement, useSelectedElements } from "../selection/selectionStore.js";
 import { readBorderWidths, toRect, } from "../overlay/overlayGeometry.js";
 const overlayStyles = ".canvas-element-overlay {\n  position: fixed;\n  pointer-events: none;\n  z-index: 1;\n  background: transparent;\n  outline: 1px solid var(--accent);\n  outline-offset: -1px;\n}\n\n.canvas-spacing-guide {\n  position: fixed;\n  z-index: 1;\n  border-radius: 999px;\n  background: var(--accent);\n  outline: none;\n  box-shadow: none;\n  pointer-events: none;\n}\n\n.canvas-spacing-fill {\n  position: fixed;\n  z-index: 1;\n  pointer-events: none;\n  background: rgb(59 130 246 / 14%);\n}\n\n.canvas-spacing-fill[data-kind=\"gap\"] {\n  background: rgb(236 72 153 / 14%);\n}\n\n.canvas-spacing-guide[data-kind=\"gap\"] {\n  background: #ec4899;\n}\n\n.canvas-selected-outline {\n  position: fixed;\n  pointer-events: none;\n  z-index: 1;\n  outline: 1px solid var(--accent);\n  outline-offset: -1px;\n}\n\n.canvas-dom-drop-line {\n  z-index: 2147483647;\n  border-radius: 999px;\n  background: #3b82f6;\n  box-shadow: 0 0 0 1px rgb(255 255 255 / 95%), 0 1px 5px rgb(37 99 235 / 72%);\n}\n\n.canvas-dom-drop-line::before,\n.canvas-dom-drop-line::after {\n  position: absolute;\n  top: 50%;\n  width: 8px;\n  height: 8px;\n  border: 2px solid #ffffff;\n  border-radius: 50%;\n  background: #2563eb;\n  content: \"\";\n  transform: translateY(-50%);\n}\n\n.canvas-dom-drop-line::before { left: -3px; }\n.canvas-dom-drop-line::after { right: -3px; }\n\n.canvas-dom-drop-line[data-orientation=\"vertical\"]::before,\n.canvas-dom-drop-line[data-orientation=\"vertical\"]::after {\n  left: 50%;\n  right: auto;\n  transform: translateX(-50%);\n}\n\n.canvas-dom-drop-line[data-orientation=\"vertical\"]::before { top: -3px; }\n.canvas-dom-drop-line[data-orientation=\"vertical\"]::after { top: auto; bottom: -3px; }\n\n.canvas-dom-drop-target {\n  z-index: 2147483646;\n  box-sizing: border-box;\n  border: 1px solid rgb(59 130 246 / 72%);\n  border-radius: 4px;\n  background: rgb(59 130 246 / 5%);\n}\n";
 import { deleteElement, getDropLocationAtPoint, moveElement, nudgeElement } from "../overlay/structuralGestures.js";
@@ -25,6 +25,8 @@ import { subscribeCanvasRendererMessages } from "./rendererMessageRouter.js";
 import { setStyles } from "../tokens/editActions.js";
 import { getSpacingAffordanceAtPoint, getSpacingAffordanceForDescriptor, SPACING_GUIDE_HANDLE_LENGTH, spacingValueCss, spacingValueForDrag, } from "../overlay/spacingGestures.js";
 import { beginLayoutPreview, endLayoutPreview } from "../styleEditors/layoutPreviewState.js";
+import { useNudgeUiRuntimeConfig } from "../runtime/useRuntimeConfig.js";
+import { DomNavigator } from "../overlay/DomNavigator.js";
 function projectRect(iframe, rect, zoom) {
     const frameRect = iframe.getBoundingClientRect();
     return {
@@ -104,8 +106,8 @@ function clearSpacingDrag(ref) {
     if (drag)
         restoreSpacingPreview(drag);
 }
-function applySpacingPreview(drag, point) {
-    const value = spacingValueForDrag(drag.affordance, drag.start, point);
+function applySpacingPreview(drag, point, shiftKey = false) {
+    const value = spacingValueForDrag(drag.affordance, drag.start, point, shiftKey);
     drag.currentValue = value;
     beginLayoutPreview(drag.element, drag.affordance.property);
     drag.element.style.setProperty(drag.affordance.property, spacingValueCss(value));
@@ -148,6 +150,8 @@ export function CanvasElementOverlay() {
     const [, refreshSelectedGeometry] = useReducer((revision) => revision + 1, 0);
     const selected = useSelectedElement();
     const selectedElements = useSelectedElements();
+    const hierarchy = useHierarchy();
+    const domNavigationEnabled = useNudgeUiRuntimeConfig().capabilities.domNavigation === true;
     const inlineTextSession = useInlineTextSession();
     const camera = useBoardCamera();
     const presentation = useCanvasPresentation();
@@ -242,6 +246,35 @@ export function CanvasElementOverlay() {
         return elementId ? { elementId } : null;
     }, [selected?.domElement]);
     useEffect(() => {
+        const refreshSpacingPreviewOverlay = (drag) => {
+            const descriptor = {
+                kind: drag.affordance.kind,
+                property: drag.affordance.property,
+                side: drag.affordance.side,
+            };
+            const affordance = getSpacingAffordanceForDescriptor(drag.element, descriptor);
+            const rect = toRect(drag.element.getBoundingClientRect());
+            const borders = readBorderWidths(drag.element);
+            const elementId = drag.element.getAttribute(RENDERER_ELEMENT_ID_ATTR);
+            setHover((current) => {
+                if (!current
+                    || current.iframe !== drag.iframe
+                    || current.identity.elementId !== elementId
+                    || !current.spacing
+                    || current.spacing.kind !== descriptor.kind
+                    || current.spacing.property !== descriptor.property
+                    || current.spacing.side !== descriptor.side) {
+                    return current;
+                }
+                return {
+                    ...current,
+                    rect,
+                    borders,
+                    spacingGuides: affordance?.affectedGuides ?? [],
+                    spacingAreas: affordance?.affectedAreas ?? [],
+                };
+            });
+        };
         const unsubscribe = subscribeCanvasRendererMessages(({ cardId: sourceCardId, iframe: sourceIframe, identity: frameIdentity, message: data, }) => {
             if (data.type === "renderer-hello" || data.type === "frame-ready") {
                 sendMeasureModifier(sourceIframe, sourceCardId, measureAltKeyRef.current);
@@ -357,7 +390,8 @@ export function CanvasElementOverlay() {
                     const selectedElement = resolveSelectionFromElement(element);
                     if (selectedElement)
                         setSelectedElement(selectedElement);
-                    applySpacingPreview(spacingDragRef.current, msg.point);
+                    applySpacingPreview(spacingDragRef.current, msg.point, msg.shiftKey === true);
+                    refreshSpacingPreviewOverlay(spacingDragRef.current);
                     return;
                 }
                 dragRef.current = { iframe: sourceIframe, element };
@@ -369,7 +403,8 @@ export function CanvasElementOverlay() {
             else if (data.type === "element-drag-move") {
                 const spacing = spacingDragRef.current;
                 if (spacing && spacing.iframe === sourceIframe) {
-                    applySpacingPreview(spacing, data.point);
+                    applySpacingPreview(spacing, data.point, data.shiftKey === true);
+                    refreshSpacingPreviewOverlay(spacing);
                     return;
                 }
                 updateDropGuide(data.point, sourceIframe);
@@ -381,10 +416,12 @@ export function CanvasElementOverlay() {
                     spacingDragRef.current = null;
                     if (msg.cancelled) {
                         restoreSpacingPreview(spacing);
+                        refreshSpacingPreviewOverlay(spacing);
                     }
                     else {
-                        applySpacingPreview(spacing, msg.point);
+                        applySpacingPreview(spacing, msg.point, msg.shiftKey === true);
                         commitSpacingDrag(spacing);
+                        refreshSpacingPreviewOverlay(spacing);
                     }
                     clearDropGuide("canvas");
                     if (!msg.cancelled) {
@@ -479,6 +516,9 @@ export function CanvasElementOverlay() {
     const isSelfHover = Boolean(hoverInSelectedFrame
         && selectedIdentity
         && hoverInSelectedFrame.identity.elementId === selectedIdentity.elementId);
+    // Selected elements already have a live geometry outline. The hover outline
+    // is based on a cached renderer message and can lag during spacing previews.
+    const showHoverOutline = Boolean(projectedHoverRect && !isSelfHover);
     const showMeasurement = Boolean(showGuideOverlay
         && selectedLocalRect
         && hoverInSelectedFrame
@@ -491,5 +531,7 @@ export function CanvasElementOverlay() {
         : [];
     if (presentationTransitioning)
         return _jsx("style", { "data-test": "canvas-element-overlay-styles", children: overlayStyles });
-    return (_jsxs(_Fragment, { children: [_jsx("style", { "data-test": "canvas-element-overlay-styles", children: overlayStyles }), showGuideOverlay && selectedRect && selectedFrameRect ? (_jsx(MeasurementGuideOverlay, { testId: "canvas-measurement-overlay", selectedRect: selectedRect, guideViewport: selectedFrameRect, segments: measurementSegments })) : null, projectedHoverRect ? (_jsxs(_Fragment, { children: [hoverSpacing ? projectedSpacingAreas.map((area, index) => (_jsx("div", { className: "canvas-spacing-fill", "data-test": "canvas-spacing-fill", "data-kind": hoverSpacing.kind, "data-property": hoverSpacing.property, "data-side": hoverSpacing.side ?? undefined, "data-area-index": index, style: overlayStyle(area), "aria-hidden": "true" }, `${hoverSpacing.property}-area-${index}`))) : null, _jsx("div", { className: "canvas-element-overlay", "data-test": "canvas-hover-outline", style: overlayStyle(projectedHoverRect), "aria-hidden": "true" }), hoverSpacing ? projectedSpacingGuides.map((guide, index) => (_jsx("div", { className: "canvas-spacing-guide", "data-test": "canvas-spacing-guide", "data-kind": hoverSpacing.kind, "data-property": hoverSpacing.property, "data-side": hoverSpacing.side ?? undefined, "data-guide-index": index, style: spacingGuideStyle(guide), "aria-hidden": "true" }, `${hoverSpacing.property}-${index}`))) : null] })) : null, projectedSelectedGeometry.map(({ element, rect }, index) => (_jsx("div", { className: "canvas-selected-outline", "data-test": "canvas-selected-outline", "data-selected-cid": element.cid, "data-selected-index": index, "data-selected-src": element.src, style: overlayStyle(rect), "aria-hidden": "true" }, `${element.cid}-${index}`))), _jsx(DropGuideOverlay, { guide: projectedDropGuide, lineClassName: "canvas-dom-drop-line", lineTestId: "canvas-dom-drop-line", targetClassName: "canvas-dom-drop-target", targetTestId: "canvas-dom-drop-target" })] }));
+    return (_jsxs(_Fragment, { children: [_jsx("style", { "data-test": "canvas-element-overlay-styles", children: overlayStyles }), showGuideOverlay && selectedRect && selectedFrameRect ? (_jsx(MeasurementGuideOverlay, { testId: "canvas-measurement-overlay", selectedRect: selectedRect, guideViewport: selectedFrameRect, segments: measurementSegments })) : null, projectedHoverRect ? (_jsxs(_Fragment, { children: [hoverSpacing ? projectedSpacingAreas.map((area, index) => (_jsx("div", { className: "canvas-spacing-fill", "data-test": "canvas-spacing-fill", "data-kind": hoverSpacing.kind, "data-property": hoverSpacing.property, "data-side": hoverSpacing.side ?? undefined, "data-area-index": index, style: overlayStyle(area), "aria-hidden": "true" }, `${hoverSpacing.property}-area-${index}`))) : null, showHoverOutline ? (_jsx("div", { className: "canvas-element-overlay", "data-test": "canvas-hover-outline", style: overlayStyle(projectedHoverRect), "aria-hidden": "true" })) : null, hoverSpacing ? projectedSpacingGuides.map((guide, index) => (_jsx("div", { className: "canvas-spacing-guide", "data-test": "canvas-spacing-guide", "data-kind": hoverSpacing.kind, "data-property": hoverSpacing.property, "data-side": hoverSpacing.side ?? undefined, "data-guide-index": index, style: spacingGuideStyle(guide), "aria-hidden": "true" }, `${hoverSpacing.property}-${index}`))) : null] })) : null, projectedSelectedGeometry.map(({ element, rect }, index) => (_jsx("div", { className: "canvas-selected-outline", "data-test": "canvas-selected-outline", "data-selected-cid": element.cid, "data-selected-index": index, "data-selected-src": element.src, style: overlayStyle(rect), "aria-hidden": "true" }, `${element.cid}-${index}`))), domNavigationEnabled && !inlineTextSession && selectedElements.length === 1 && selected && selectedRect && selectedFrame instanceof HTMLIFrameElement ? (_jsx(DomNavigator, { selected: selected, hierarchy: hierarchy, anchor: selectedRect, project: (element) => element.ownerDocument === selected.domElement.ownerDocument
+                    ? projectRect(selectedFrame, toRect(element.getBoundingClientRect()), projectionZoom)
+                    : null })) : null, _jsx(DropGuideOverlay, { guide: projectedDropGuide, lineClassName: "canvas-dom-drop-line", lineTestId: "canvas-dom-drop-line", targetClassName: "canvas-dom-drop-target", targetTestId: "canvas-dom-drop-target" })] }));
 }

package/dist/inspector/canvas/CanvasToolbar.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { IconHandStop, IconPointer2, IconSketching, } from "@tabler/icons-react";
+import { IconHandStop, IconPlayerPlay, IconPointer2, IconSketching, } from "@tabler/icons-react";
 import { IconButton } from "../ui/IconButton.js";
 export const CANVAS_ZOOM_LEVELS = [0.25, 0.5, 0.9, 1];
 export function closestCanvasZoomLevel(zoom) {
@@ -16,9 +16,9 @@ export function adjacentCanvasZoomLevel(zoom, direction) {
     const next = CANVAS_ZOOM_LEVELS[index + direction];
     return next === undefined ? null : next;
 }
-function ToolButton({ active, disabled, label, icon, onClick, }) {
-    return (_jsx(IconButton, { variant: "quiet", size: "large", className: "canvas-toolbar__tool", label: label, title: label, "aria-pressed": active, "data-test": `canvas-tool-${label.toLowerCase()}`, "data-active": active ? "true" : "false", disabled: disabled, onClick: onClick, children: icon }));
+function ToolButton({ active, disabled, label, description, icon, onClick, }) {
+    return (_jsx(IconButton, { variant: "quiet", size: "large", className: "canvas-toolbar__tool", label: label, title: description ?? label, "aria-pressed": active, "data-test": `canvas-tool-${label.toLowerCase()}`, "data-active": active ? "true" : "false", disabled: disabled, onClick: onClick, children: icon }));
 }
 export function CanvasToolbar({ tool, sketchEnabled, onToolChange, }) {
-    return (_jsx("div", { className: "canvas-toolbar", "data-test": "canvas-toolbar", role: "toolbar", "aria-label": "Canvas tools", children: _jsxs("div", { className: "canvas-toolbar__tools", role: "group", "aria-label": "Interaction tools", children: [_jsx(ToolButton, { active: tool === "move", label: "Move", icon: _jsx(IconPointer2, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("move") }), _jsx(ToolButton, { active: tool === "pan", label: "Pan", icon: _jsx(IconHandStop, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("pan") }), _jsx(ToolButton, { active: tool === "sketch", label: "Sketch", disabled: !sketchEnabled, icon: _jsx(IconSketching, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("sketch") })] }) }));
+    return (_jsxs("div", { className: "canvas-toolbar", "data-test": "canvas-toolbar", role: "toolbar", "aria-label": "Canvas tools", children: [_jsxs("div", { className: "canvas-toolbar__tools", role: "group", "aria-label": "Interaction tools", children: [_jsx(ToolButton, { active: tool === "design", label: "Design", description: "Design (V): click elements to inspect and edit them", icon: _jsx(IconPointer2, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("design") }), _jsx(ToolButton, { active: tool === "pan", label: "Pan", icon: _jsx(IconHandStop, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("pan") }), _jsx(ToolButton, { active: tool === "sketch", label: "Sketch", disabled: !sketchEnabled, icon: _jsx(IconSketching, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("sketch") })] }), _jsx("div", { className: "canvas-toolbar__divider", "aria-hidden": "true" }), _jsx("div", { className: "canvas-toolbar__tools", role: "group", "aria-label": "Preview tools", children: _jsx(ToolButton, { active: tool === "select", label: "Select", description: "Select (I): use the app normally", icon: _jsx(IconPlayerPlay, { size: "var(--icon-size-large)", stroke: "var(--icon-stroke-width)", "aria-hidden": "true" }), onClick: () => onToolChange("select") }) })] }));
 }

package/dist/inspector/canvas/CanvasWorkspace.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { IconCornerLeftUp } from "@tabler/icons-react";
-import { useCanvasCards, activateIframeWorkspace, removeCanvasCard, getSelectedCardId, getFocusedCardId, getCanvasCards, setBoardCamera, getBoardCamera, fitAllCards, setCanvasPresentation, focusCard, hasFitAllRan, useBoardCamera, useCanvasPresentation, useCanvasPresentationTransitioning, useSelectedCardId, useFocusedCardId, resizeCard, setCardPosition, updateCardTitle, CARD_GAP, updateCardUrl, } from "./canvasStore.js";
+import { useCanvasCards, activateIframeWorkspace, removeCanvasCard, getSelectedCardId, getFocusedCardId, getCanvasCards, setBoardCamera, getBoardCamera, fitAllCards, setCanvasPresentation, focusCard, hasFitAllRan, useBoardCamera, useCanvasPresentation, useCanvasPresentationTransitioning, useSelectedCardId, useFocusedCardId, resizeCard, setCardPosition, updateCardTitle, addCanvasCard, findCardByNormalizedUrl, selectCard, CARD_GAP, updateCardUrl, } from "./canvasStore.js";
 import { CanvasCard } from "./CanvasCard.js";
 import { Button } from "../ui/Button.js";
 import { useCanvasMode } from "./canvasStore.js";
@@ -21,7 +21,7 @@ import { createNudgeUiEditorUrl } from "../../transport/editor.js";
 import { disposeInlineTextEdit } from "../inline-text/inlineTextEditor.js";
 import { PROTOCOL_VERSION, isProjectionAppliedMessage, isKeyboardShortcutMessage, isRenderedInstanceProjectionReportMessage, isTextProjectionReportMessage, isStructuralProjectionReportMessage, } from "./frameProtocol.js";
 import { iframePointToClientPoint, zoomCameraAtPointer } from "./canvasGestures.js";
-const canvasWorkspaceStyles = ".canvas-workspace {\n  position: fixed;\n  inset: 0;\n  display: flex;\n  flex-direction: column;\n  background: var(--surface-panel);\n  pointer-events: auto;\n}\n\n.canvas-workspace__board {\n  flex: 1;\n  overflow: hidden;\n  position: relative;\n  background: var(--surface-panel);\n}\n\n.canvas-workspace__focus-action {\n  position: absolute;\n  top: max(12px, env(safe-area-inset-top));\n  left: max(12px, env(safe-area-inset-left));\n  z-index: calc(var(--z-index) - 1);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: var(--space-4);\n  border-radius: var(--radius-12);\n  background: var(--surface-raised-2x);\n  box-shadow: var(--shadow-popup);\n  pointer-events: auto;\n}\n\n.canvas-workspace__board.is-grabbable {\n  cursor: grab;\n}\n\n.canvas-workspace__board.is-grabbing {\n  cursor: grabbing;\n}\n\n/* Canvas gestures take precedence over every card interaction while Space is\n   held. This also closes the short postMessage gap before an iframe receives\n   its mirrored modifier state. */\n.canvas-workspace__board.is-grabbable .canvas-card,\n.canvas-workspace__board.is-grabbing .canvas-card {\n  pointer-events: none;\n}\n\n.canvas-workspace__board-content {\n  position: absolute;\n  width: 100%;\n  height: 100%;\n  will-change: transform;\n}\n\n.canvas-workspace.is-presentation-transitioning .canvas-workspace__board-content {\n  transition: transform 200ms ease;\n}\n\n.canvas-workspace[data-presentation=\"focus\"] .canvas-workspace__board-content {\n  inset: 0;\n  transform: none !important;\n}\n\n.canvas-workspace.is-presentation-transitioning .canvas-card.is-presentation-card {\n  transition: left 200ms ease, top 200ms ease;\n}\n\n.canvas-workspace.is-presentation-transitioning .canvas-card:not(.is-presentation-card) {\n  visibility: hidden !important;\n  pointer-events: none !important;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .canvas-workspace.is-presentation-transitioning .canvas-workspace__board-content,\n  .canvas-workspace.is-presentation-transitioning .canvas-card.is-presentation-card {\n    transition: none;\n  }\n}\n\n.canvas-workspace__target-error {\n  position: absolute;\n  inset: 0;\n  display: grid;\n  place-items: center;\n  color: #6b7280;\n  font: 500 14px/1.4 system-ui, sans-serif;\n}\n";
+const canvasWorkspaceStyles = ".canvas-workspace {\n  position: fixed;\n  inset: 0;\n  display: flex;\n  flex-direction: column;\n  background: var(--surface-panel);\n  pointer-events: auto;\n}\n\n.canvas-workspace__board {\n  flex: 1;\n  overflow: hidden;\n  position: relative;\n  background: var(--surface-panel);\n}\n\n.canvas-workspace__focus-action {\n  position: absolute;\n  top: max(12px, env(safe-area-inset-top));\n  left: max(12px, env(safe-area-inset-left));\n  z-index: calc(var(--z-index) - 1);\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: var(--space-4);\n  border-radius: var(--radius-12);\n  background: var(--surface-raised-2x);\n  box-shadow: var(--shadow-popup);\n  pointer-events: auto;\n}\n\n.canvas-workspace__board.is-grabbable {\n  cursor: grab;\n}\n\n.canvas-workspace__board.is-grabbing {\n  cursor: grabbing;\n}\n\n/* Canvas gestures take precedence over every card interaction while Space is\n   held. This also closes the short postMessage gap before an iframe receives\n   its mirrored modifier state. */\n.canvas-workspace__board.is-grabbable .canvas-card,\n.canvas-workspace__board.is-grabbing .canvas-card {\n  pointer-events: none;\n}\n\n.canvas-workspace__board-content {\n  position: absolute;\n  width: 100%;\n  height: 100%;\n  /*\n   * Leave `will-change` unset so the browser can re-rasterize this subtree at\n   * the current camera scale. A permanent `will-change: transform` promotes\n   * it to a fixed bitmap, which makes iframe content look soft when zoomed.\n   */\n}\n\n.canvas-workspace__board.is-grabbing .canvas-workspace__board-content {\n  /* Panning benefits from a cached composited layer; zoom restores the crisp\n   * default path as soon as the gesture ends. */\n  will-change: transform;\n}\n\n.canvas-workspace.is-presentation-transitioning .canvas-workspace__board-content {\n  transition: transform 200ms ease;\n}\n\n.canvas-workspace[data-presentation=\"focus\"] .canvas-workspace__board-content {\n  inset: 0;\n  transform: none !important;\n}\n\n.canvas-workspace.is-presentation-transitioning .canvas-card.is-presentation-card {\n  transition: left 200ms ease, top 200ms ease;\n}\n\n.canvas-workspace.is-presentation-transitioning .canvas-card:not(.is-presentation-card) {\n  visibility: hidden !important;\n  pointer-events: none !important;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .canvas-workspace.is-presentation-transitioning .canvas-workspace__board-content,\n  .canvas-workspace.is-presentation-transitioning .canvas-card.is-presentation-card {\n    transition: none;\n  }\n}\n\n.canvas-workspace__target-error {\n  position: absolute;\n  inset: 0;\n  display: grid;\n  place-items: center;\n  color: #6b7280;\n  font: 500 14px/1.4 system-ui, sans-serif;\n}\n";
 const canvasCardStyles = ".canvas-card {\n  position: relative;\n}\n\n/* Extend the card's hover region to the toolbar above the iframe. */\n.canvas-card::before {\n  content: \"\";\n  position: absolute;\n  right: 0;\n  bottom: 100%;\n  left: 0;\n  height: calc(var(--control-height-large) + var(--space-8));\n  pointer-events: auto;\n}\n\n.canvas-card__frame {\n  position: relative;\n  width: 100%;\n  height: 100%;\n  background: var(--surface-panel);\n  border-radius: 0;\n  overflow: hidden;\n}\n\n.canvas-card.is-selected .canvas-card__frame {\n  outline: 2px solid var(--accent);\n  outline-offset: -2px;\n}\n\n.canvas-card.is-focus-presentation .canvas-card__frame {\n  outline: none;\n}\n\n.canvas-card.is-focused .canvas-card__frame {\n  animation: canvas-card-focus 900ms ease-out;\n}\n\n@keyframes canvas-card-focus {\n  0%, 35% { outline: 3px solid var(--accent); outline-offset: -3px; }\n  100% { outline: 0 solid transparent; outline-offset: -2px; }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .canvas-card.is-focused .canvas-card__frame {\n    animation: none;\n  }\n}\n\n.canvas-card__toolbar {\n  display: flex;\n  align-items: center;\n  position: absolute;\n  left: 0;\n  right: 0;\n  bottom: calc(100% + var(--space-8));\n  justify-content: flex-start;\n  z-index: 1;\n  cursor: grab;\n  opacity: 0;\n  visibility: hidden;\n  pointer-events: none;\n  transition: opacity 120ms ease;\n}\n\n.canvas-card:hover .canvas-card__toolbar,\n.canvas-card:focus-within .canvas-card__toolbar,\n.canvas-card.is-selected .canvas-card__toolbar,\n.canvas-card.is-focused .canvas-card__toolbar {\n  opacity: 1;\n  visibility: visible;\n  pointer-events: auto;\n}\n\n.canvas-card.is-dragging .canvas-card__toolbar {\n  cursor: grabbing;\n}\n\n.canvas-card__drag-surface {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: var(--space-8);\n  flex: 1 1 auto;\n  min-width: 0;\n  min-height: var(--control-height-large);\n  padding: 0;\n  cursor: grab;\n  user-select: none;\n  touch-action: none;\n}\n\n.canvas-card.is-dragging .canvas-card__drag-surface {\n  cursor: grabbing;\n}\n\n.canvas-card__dimensions {\n  position: absolute;\n  left: 50%;\n  bottom: 0;\n  color: var(--text-secondary);\n  font-size: var(--font-size-base);\n  font-variant-numeric: tabular-nums;\n  white-space: nowrap;\n}\n\n.canvas-card__iframe {\n  width: 100%;\n  height: 100%;\n  border: none;\n  display: block;\n}\n\n.canvas-card__sketch-overlay {\n  position: absolute;\n  inset: 0;\n  z-index: 2;\n  display: block;\n  pointer-events: none;\n}\n\n.canvas-card__loading {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  height: 100%;\n  color: var(--text-muted, #777777);\n  font-size: 12px;\n  font-weight: 500;\n}\n\n.canvas-card__error {\n  display: flex;\n  flex-direction: column;\n  align-items: center;\n  justify-content: center;\n  gap: 12px;\n  height: 100%;\n  padding: 20px;\n  text-align: center;\n}\n\n.canvas-card__error p {\n  margin: 0;\n  color: var(--text-muted, #777777);\n  font-size: 12px;\n  font-weight: 500;\n}\n\n.canvas-card__error-actions {\n  display: flex;\n  gap: 8px;\n}\n\n.canvas-card__resize-handle {\n  position: absolute;\n  z-index: 3;\n  display: flex;\n  align-items: flex-end;\n  justify-content: flex-end;\n  padding: 4px;\n  color: var(--text-muted, #777777);\n  opacity: 0;\n  transition: opacity 150ms ease;\n  touch-action: none;\n  user-select: none;\n}\n\n.canvas-card__resize-handle--top,\n.canvas-card__resize-handle--bottom {\n  right: 16px;\n  left: 16px;\n  height: 16px;\n  cursor: ns-resize;\n}\n\n.canvas-card__resize-handle--top {\n  top: 0;\n}\n\n.canvas-card__resize-handle--bottom {\n  bottom: 0;\n}\n\n.canvas-card__resize-handle--left,\n.canvas-card__resize-handle--right {\n  top: 16px;\n  bottom: 16px;\n  width: 16px;\n  cursor: ew-resize;\n}\n\n.canvas-card__resize-handle--left {\n  left: 0;\n}\n\n.canvas-card__resize-handle--right {\n  right: 0;\n}\n\n.canvas-card__resize-handle--top-left,\n.canvas-card__resize-handle--top-right,\n.canvas-card__resize-handle--bottom-right,\n.canvas-card__resize-handle--bottom-left {\n  z-index: 4;\n  width: 24px;\n  height: 24px;\n  cursor: nwse-resize;\n}\n\n.canvas-card__resize-handle--top-left {\n  top: 0;\n  left: 0;\n}\n\n.canvas-card__resize-handle--top-right {\n  top: 0;\n  right: 0;\n  cursor: nesw-resize;\n}\n\n.canvas-card__resize-handle--bottom-right {\n  right: 0;\n  bottom: 0;\n}\n\n.canvas-card__resize-handle--bottom-left {\n  bottom: 0;\n  left: 0;\n  cursor: nesw-resize;\n}\n\n.canvas-card:hover .canvas-card__resize-handle,\n.canvas-card:focus-within .canvas-card__resize-handle {\n  opacity: 1;\n}\n\n.canvas-card__resize-handle:hover {\n  color: var(--accent);\n}\n\n.canvas-card__resize-handle:focus-visible {\n  outline: 2px solid var(--accent);\n  outline-offset: 1px;\n  opacity: 1;\n}\n";
 const foundationStyles = ":host {\n  all: initial;\n  --surface-panel: #F5F5F4;\n  --surface-control: var(--surface-well);\n  --surface-control-hover: var(--surface-well-2x);\n  --surface-raised: #FAFAFA;\n  --surface-raised-2x: #fff ;\n  --surface-raised-hover: #F5F5F4;\n  --surface-well: hsla(0, 0%, 0%, 0.05);\n  --surface-well-2x: hsla(0, 0%, 0%, 0.10);\n\n  --border-subtle: hsla(0, 0%, 0%, 0.1);\n  --border-medium: hsla(0, 0%, 0%, 0.2);\n  --border-strong: #d8d8d8;\n\n  --text-primary: #242424;\n  --text-secondary: #6f6f6f;\n  --text-muted: #777777;\n  --text-muted-subtle: #a1a1a1;\n\n  --accent: #0096ff;\n  --accent-surface: rgba(0, 176, 255, 0.15);\n  --warning: #d97706;\n  --warning-text: #9a5b00;\n  --warning-surface: #fff6e5;\n  --danger: #df4b4b;\n  --danger-text: #bd3636;\n  --danger-surface: rgba(223, 75, 75, 0.2);\n\n  --space-0: 0;\n  --space-4: 4px;\n  --space-8: 8px;\n  --space-12: 12px;\n  --space-16: 16px;\n  --space-20: 20px;\n  --space-24: 24px;\n  --space-32: 32px;\n  --space-40: 40px;\n  --space-48: 48px;\n\n  /* Radius */\n  --radius-0: 0;\n  --radius-4: 4px;\n  --radius-8: 8px;\n  --radius-12: 12px;\n  --radius-16: 16px;\n  --radius-20: 20px;\n  --radius-24: 24px;\n  --radius-pill: 999px;\n\n  --radius-control: var(--radius-8);\n  --shadow-outline: 0 0 0 1px rgba(0, 0, 0, 0.05);\n  --shadow-popup: 0 0 0 1px rgba(0, 0, 0, 0.05), 0 4px 16px rgba(0, 0, 0, 0.10);\n  --shadow-control: inset 0 -2px 0 rgba(0, 0, 0, 0.03), 0 0 0 0.5px rgba(0, 0, 0, 0.25);\n  --z-index: 2147483647;\n\n  --font-family: \"Inter Variable\", Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, \"Segoe UI\", sans-serif;\n  --font-size-base: 12px;\n  --font-size-small: 10px;\n  --font-weight-base: 400;\n  --font-weight-label: 600;\n\n  /* Control semantic sizes */\n  --control-height-small: 24px;\n  --control-height-large: 32px;\n  --control-height-xlarge: 40px;\n  --label-column: 104px;\n\n  --icon-size-small: 16px;\n  --icon-size-large: 20px;\n  --icon-stroke-width: 1.5px;\n\n  position: fixed;\n  inset: 0;\n  z-index: var(--z-index);\n  pointer-events: none;\n  font-family: var(--font-family);\n  background: transparent;\n  box-sizing: border-box;\n}\n\n*,\n*::before,\n*::after {\n  box-sizing: border-box;\n}\n\nbutton,\ninput,\nselect {\n  font-family: inherit;\n}\n";
 import { useInspectorOpen } from "../shell/openStore.js";
@@ -32,7 +32,7 @@ import { useNudgeUiRuntimeConfig } from "../runtime/useRuntimeConfig.js";
 import { subscribeCanvasRendererMessages } from "./rendererMessageRouter.js";
 import { adjacentCanvasZoomLevel, CanvasToolbar, } from "./CanvasToolbar.js";
 import { canvasToolForEvent, canvasToolForCode } from "./keyboardShortcuts.js";
-const canvasToolbarStyles = ".canvas-toolbar {\n  position: absolute;\n  left: 50%;\n  bottom: var(--space-20);\n  /* Keep the persistent controls above the live sketch surface. The sketch\n     toolbar gets the next layer so both toolbars remain available together. */\n  z-index: calc(var(--z-index) - 2);\n  display: flex;\n  align-items: center;\n  gap: var(--space-4);\n  padding: var(--space-4);\n  border-radius: var(--radius-12);\n  background: var(--surface-raised-2x);\n  box-shadow: var(--shadow-popup);\n  transform: translateX(-50%);\n  pointer-events: auto;\n}\n\n/* The live sketch surface is a separate stacking context. Keep a copy of the\n   toolbar at the root layer while sketching so pointer events reach the\n   controls instead of the full-screen SVG drawing surface. */\n.canvas-toolbar__portal {\n  position: fixed;\n  inset: 0;\n  z-index: var(--z-index);\n  pointer-events: none;\n}\n\n.canvas-toolbar__portal > .canvas-toolbar {\n  pointer-events: auto;\n}\n\n.canvas-toolbar__tools {\n  display: flex;\n  align-items: center;\n  gap: var(--space-4);\n}\n\n.canvas-toolbar__tool[data-active=\"true\"] {\n  background: var(--accent-surface);\n  color: var(--accent);\n}\n";
+const canvasToolbarStyles = ".canvas-toolbar {\n  position: absolute;\n  left: 50%;\n  bottom: var(--space-20);\n  /* Keep the persistent controls above the live sketch surface. The sketch\n     toolbar gets the next layer so both toolbars remain available together. */\n  z-index: calc(var(--z-index) - 2);\n  display: flex;\n  align-items: center;\n  gap: var(--space-4);\n  padding: var(--space-4);\n  border-radius: var(--radius-12);\n  background: var(--surface-raised-2x);\n  box-shadow: var(--shadow-popup);\n  transform: translateX(-50%);\n  pointer-events: auto;\n}\n\n/* The live sketch surface is a separate stacking context. Keep a copy of the\n   toolbar at the root layer while sketching so pointer events reach the\n   controls instead of the full-screen SVG drawing surface. */\n.canvas-toolbar__portal {\n  position: fixed;\n  inset: 0;\n  z-index: var(--z-index);\n  pointer-events: none;\n}\n\n.canvas-toolbar__portal > .canvas-toolbar {\n  pointer-events: auto;\n}\n\n.canvas-toolbar__tools {\n  display: flex;\n  align-items: center;\n  gap: var(--space-4);\n}\n\n.canvas-toolbar__divider {\n  flex-shrink: 0;\n  width: 1px;\n  height: var(--control-height-small);\n  margin-inline: var(--space-4);\n  background: var(--border-subtle);\n}\n\n.canvas-toolbar__tool[data-active=\"true\"] {\n  background: var(--accent-surface);\n  color: var(--accent);\n}\n";
 import { getActiveCanvasFrame } from "./activeCanvasDocument.js";
 import { startSketchCapture } from "../sketch/SketchWorkspace.js";
 import { cancelSketchInteraction, useSketchInteractionActive } from "../sketch/interaction.js";
@@ -74,7 +74,9 @@ export function CanvasWorkspace({ primaryUrl }) {
     const focusCardRectRef = useRef(null);
     const canvasEntryAnimationRef = useRef(null);
     const [boardCursorClass, setBoardCursorClass] = useState("");
-    const [interactionTool, setInteractionTool] = useState("move");
+    const [interactionTool, setInteractionTool] = useState("design");
+    const rendererInteractionsEnabled = interactionTool !== "select";
+    const linksOpenInCards = interactionTool === "select" && presentation === "canvas";
     const presentationCardId = selectedCardId ?? focusedCardId ?? cards[0]?.id ?? null;
     useLayoutEffect(() => {
         const board = boardRef.current;
@@ -222,7 +224,7 @@ export function CanvasWorkspace({ primaryUrl }) {
             spaceHeld,
         }, window.location.origin);
     }, []);
-    const sendInspectorInteractionState = useCallback((iframe, cardId, open) => {
+    const sendInspectorInteractionState = useCallback((iframe, cardId, open, interactionsEnabled) => {
         iframe.contentWindow?.postMessage({
             type: "inspector-interaction-state",
             protocolVersion: PROTOCOL_VERSION,
@@ -230,7 +232,17 @@ export function CanvasWorkspace({ primaryUrl }) {
             workspaceId: WORKSPACE_ID,
             cardId,
             open,
-            interactionsEnabled: true,
+            interactionsEnabled,
+        }, window.location.origin);
+    }, []);
+    const sendLinkTargetState = useCallback((iframe, cardId, openInCard) => {
+        iframe.contentWindow?.postMessage({
+            type: "link-target-state",
+            protocolVersion: PROTOCOL_VERSION,
+            projectId: PROJECT_ID,
+            workspaceId: WORKSPACE_ID,
+            cardId,
+            openInCard,
         }, window.location.origin);
     }, []);
     const sendBoardGestureState = useCallback((iframe, cardId, enabled) => {
@@ -245,10 +257,11 @@ export function CanvasWorkspace({ primaryUrl }) {
     }, []);
     useEffect(() => {
         for (const [cardId, iframe] of getRegisteredFrames()) {
-            sendInspectorInteractionState(iframe, cardId, inspectorOpen);
+            sendInspectorInteractionState(iframe, cardId, inspectorOpen, rendererInteractionsEnabled);
             sendBoardGestureState(iframe, cardId, presentation === "canvas");
+            sendLinkTargetState(iframe, cardId, linksOpenInCards);
         }
-    }, [inspectorOpen, presentation, sendBoardGestureState, sendInspectorInteractionState]);
+    }, [inspectorOpen, linksOpenInCards, presentation, rendererInteractionsEnabled, sendBoardGestureState, sendInspectorInteractionState, sendLinkTargetState]);
     const broadcastPanModifier = useCallback((spaceHeld) => {
         for (const [cardId, iframe] of getRegisteredFrames()) {
             sendPanModifier(iframe, cardId, spaceHeld);
@@ -362,7 +375,7 @@ export function CanvasWorkspace({ primaryUrl }) {
     }, []);
     useEffect(() => {
         if (!sketchActive && interactionTool === "sketch") {
-            setInteractionTool("move");
+            setInteractionTool("design");
         }
     }, [interactionTool, sketchActive]);
     useLayoutEffect(() => {
@@ -454,8 +467,9 @@ export function CanvasWorkspace({ primaryUrl }) {
                 // A card can finish loading after Space was pressed on the controller.
                 // Seed it with the current modifier state before its first pointer event.
                 sendPanModifier(frame.iframe, frame.cardId, spaceHeldRef.current);
-                sendInspectorInteractionState(frame.iframe, frame.cardId, inspectorOpen);
+                sendInspectorInteractionState(frame.iframe, frame.cardId, inspectorOpen, rendererInteractionsEnabled);
                 sendBoardGestureState(frame.iframe, frame.cardId, presentation === "canvas");
+                sendLinkTargetState(frame.iframe, frame.cardId, linksOpenInCards);
             }
             if (msg.type === "pan-modifier") {
                 if (presentation !== "canvas")
@@ -520,11 +534,16 @@ export function CanvasWorkspace({ primaryUrl }) {
             const normalized = normalizeUrl(msg.url);
             if (!normalized || normalized.origin !== window.location.origin)
                 return;
+            if (msg.openInCard === true) {
+                const card = findCardByNormalizedUrl(normalized) ?? addCanvasCard(msg.url);
+                selectCard(card.id);
+                return;
+            }
             const frameDocument = frame.iframe.contentDocument;
             if (frameDocument)
                 disposeInlineTextEdit("route-disposed", frameDocument);
         });
-    }, [broadcastPanModifier, endPanning, handleToolChange, inspectorOpen, movePanning, presentation, sendBoardGestureState, sendInspectorInteractionState, sendPanModifier, sketchAvailable, startPanning, zoomAtPointer]);
+    }, [broadcastPanModifier, endPanning, handleToolChange, inspectorOpen, linksOpenInCards, movePanning, presentation, rendererInteractionsEnabled, sendBoardGestureState, sendInspectorInteractionState, sendLinkTargetState, sendPanModifier, sketchAvailable, startPanning, zoomAtPointer]);
     useEffect(() => {
         if (mode === "canvas" && !hasFitAllRan()) {
             if (!fitAllScheduledRef.current) {

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

@@ -2,7 +2,7 @@ import type { ComponentOverride } from "../componentSemantics/types.js";
 import type { RenderedInstanceOverride } from "../changes/editModel.js";
 import type { NudgeUiRuntimeConfig } from "../runtime/runtimeConfig.js";
 import type { SpacingDescriptor } from "../overlay/spacingGestures.js";
-export declare const PROTOCOL_VERSION = 19;
+export declare const PROTOCOL_VERSION = 20;
 export interface FrameMessage {
     type: string;
     protocolVersion: number;
@@ -93,6 +93,13 @@ export interface TextProjectionReportMessage extends RendererMessage {
 export interface NavigationIntentMessage extends RendererMessage {
     type: "navigation-intent";
     url: string;
+    /** The renderer kept its own route and asks the controller for a card instead. */
+    openInCard?: boolean;
+}
+/** Tells a renderer whether ordinary link clicks open a new canvas card. */
+export interface LinkTargetStateMessage extends RendererMessage {
+    type: "link-target-state";
+    openInCard: boolean;
 }
 export interface ElementHoverMessage extends RendererMessage {
     type: "element-hover";
@@ -179,6 +186,8 @@ export interface ElementDragStartMessage extends RendererMessage {
     };
     /** Spacing affordance captured at pointer-down, if this is a spacing drag. */
     spacing?: SpacingDescriptor | null;
+    /** True while Shift is held; spacing drags use this to snap by 8px steps. */
+    shiftKey?: boolean;
 }
 export interface ElementDragMoveMessage extends RendererMessage {
     type: "element-drag-move";
@@ -186,6 +195,8 @@ export interface ElementDragMoveMessage extends RendererMessage {
         x: number;
         y: number;
     };
+    /** True while Shift is held; spacing drags use this to snap by 8px steps. */
+    shiftKey?: boolean;
 }
 export interface ElementDragEndMessage extends RendererMessage {
     type: "element-drag-end";
@@ -193,6 +204,8 @@ export interface ElementDragEndMessage extends RendererMessage {
         x: number;
         y: number;
     };
+    /** True while Shift is held; spacing drags use this to snap by 8px steps. */
+    shiftKey?: boolean;
     /** True when the renderer lost the gesture before the pointer was released. */
     cancelled?: boolean;
 }
@@ -222,7 +235,7 @@ export interface InspectorToggleRequestMessage extends RendererMessage {
 export interface InspectorOpenRequestMessage extends RendererMessage {
     type: "inspector-open-request";
 }
-export type KeyboardShortcutCode = "Backslash" | "KeyV" | "KeyH" | "KeyP" | "KeyS";
+export type KeyboardShortcutCode = "Backslash" | "KeyI" | "KeyV" | "KeyH" | "KeyP" | "KeyS";
 export type KeyboardShortcutPhase = "keydown" | "keyup";
 /** Forwards controller-owned keyboard shortcuts from an iframe document. */
 export interface KeyboardShortcutMessage extends RendererMessage {
@@ -271,7 +284,7 @@ export interface ZoomMessage extends RendererMessage {
         y: number;
     };
 }
-export type FrameProtocolMessage = ParentReadyMessage | RendererHelloMessage | FrameReadyMessage | FrameRuntimeMessage | FrameMetadataMessage | FrameLoadError | ReplaceStylesMessage | ProjectionAppliedMessage | StructuralProjectionReportMessage | RenderedInstanceProjectionReportMessage | TextProjectionReportMessage | NavigationIntentMessage | ElementHoverMessage | ElementMeasureStateMessage | ElementClickMessage | InlineTextIntentMessage | ElementDeselectMessage | ElementDragStartMessage | ElementDragMoveMessage | ElementDragEndMessage | ElementDeleteMessage | ElementNudgeMessage | HistoryRequestMessage | InspectorToggleRequestMessage | InspectorOpenRequestMessage | KeyboardShortcutMessage | PanStartMessage | PanMoveMessage | PanEndMessage | PanModifierMessage | MeasureModifierMessage | BoardGestureStateMessage | ZoomMessage;
+export type FrameProtocolMessage = ParentReadyMessage | RendererHelloMessage | FrameReadyMessage | FrameRuntimeMessage | FrameMetadataMessage | FrameLoadError | ReplaceStylesMessage | ProjectionAppliedMessage | StructuralProjectionReportMessage | RenderedInstanceProjectionReportMessage | TextProjectionReportMessage | NavigationIntentMessage | LinkTargetStateMessage | ElementHoverMessage | ElementMeasureStateMessage | ElementClickMessage | InlineTextIntentMessage | ElementDeselectMessage | ElementDragStartMessage | ElementDragMoveMessage | ElementDragEndMessage | ElementDeleteMessage | ElementNudgeMessage | HistoryRequestMessage | InspectorToggleRequestMessage | InspectorOpenRequestMessage | KeyboardShortcutMessage | PanStartMessage | PanMoveMessage | PanEndMessage | PanModifierMessage | MeasureModifierMessage | BoardGestureStateMessage | ZoomMessage;
 export declare function setRendererIdentity(identity: FrameIdentity): void;
 export declare function clearRendererIdentity(expected?: FrameIdentity): void;
 export declare function getRendererIdentity(): FrameIdentity | null;

package/dist/inspector/canvas/frameProtocol.js

@@ -1,6 +1,8 @@
 import { isDocumentProjectionReport } from "../projection/renderedInstance.js";
 import { isTextProjectionReport } from "../projection/textProjection.js";
 import { isStructuralProjectionReport } from "../projection/structuralProjectionBoundary.js";
+// v20 adds Shift state to element drag messages so spacing handles can snap
+// changes to 8px increments.
 // v19 adds spacing drag gestures (hover point, spacing descriptor, start
 // point, and cancelled drag-end) plus renderer-to-controller keyboard shortcut
 // forwarding for Canvas frames.
@@ -15,7 +17,7 @@ import { isStructuralProjectionReport } from "../projection/structuralProjection
 // rereading a Canvas iframe until the renderer has applied its revision. v11
 // added the renderer-hello handshake solicitation for runtimes whose boot
 // completes after the controller's load-time parent-ready.
-export const PROTOCOL_VERSION = 19;
+export const PROTOCOL_VERSION = 20;
 let rendererIdentity = null;
 export function setRendererIdentity(identity) {
     rendererIdentity = identity;
@@ -37,7 +39,12 @@ export function isRendererMessageFor(value, identity) {
         && message.cardId === identity.cardId;
 }
 export function isKeyboardShortcutCode(value) {
-    return value === "Backslash" || value === "KeyV" || value === "KeyH" || value === "KeyP" || value === "KeyS";
+    return value === "Backslash"
+        || value === "KeyI"
+        || value === "KeyV"
+        || value === "KeyH"
+        || value === "KeyP"
+        || value === "KeyS";
 }
 /** Strict JSON-only schema for renderer-originated global keyboard shortcuts. */
 export function isKeyboardShortcutMessage(value, identity) {

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

@@ -1,3 +1,4 @@
-export type CanvasInteractionTool = "move" | "pan" | "sketch";
+/** `select` leaves the application interactive; `design` turns clicks into inspector selection. */
+export type CanvasInteractionTool = "select" | "design" | "pan" | "sketch";
 export declare function canvasToolForCode(code: string): CanvasInteractionTool | null;
 export declare function canvasToolForEvent(event: KeyboardEvent): CanvasInteractionTool | null;

package/dist/inspector/canvas/keyboardShortcuts.js

@@ -1,6 +1,8 @@
 export function canvasToolForCode(code) {
+    if (code === "KeyI")
+        return "select";
     if (code === "KeyV")
-        return "move";
+        return "design";
     if (code === "KeyH")
         return "pan";
     if (code === "KeyP")

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

@@ -1,8 +1,3 @@
 export declare function findClosestAnchor(target: EventTarget | null): HTMLAnchorElement | null;
 export declare function isEligibleNavigation(anchor: HTMLAnchorElement, event: MouseEvent): boolean;
 export declare function hasDifferentRoute(anchor: HTMLAnchorElement): boolean;
-/**
- * Returns whether the renderer should leave an anchor's browser behavior
- * intact instead of consuming it as an editing click.
- */
-export declare function shouldPreserveNativeLinkActivation(anchor: HTMLAnchorElement, event: MouseEvent): boolean;

package/dist/inspector/canvas/linkEligibility.js

@@ -37,32 +37,3 @@ export function hasDifferentRoute(anchor) {
         return false;
     }
 }
-/**
- * Returns whether the renderer should leave an anchor's browser behavior
- * intact instead of consuming it as an editing click.
- */
-export function shouldPreserveNativeLinkActivation(anchor, event) {
-    // Command/Ctrl-click is the deep-selection gesture. Shift makes it the
-    // explicit application-activation gesture instead.
-    if (event.metaKey || event.ctrlKey)
-        return event.shiftKey;
-    // Shift-click is the additive inspector-selection gesture. Do not let a
-    // link navigate or preserve its native activation in that mode.
-    if (event.shiftKey)
-        return false;
-    if (anchor.hasAttribute("download"))
-        return true;
-    if (anchor.target && anchor.target !== "" && anchor.target !== "_self")
-        return true;
-    if (anchor.protocol !== "http:" && anchor.protocol !== "https:")
-        return true;
-    try {
-        const url = new URL(anchor.href);
-        if (url.origin !== window.location.origin)
-            return true;
-    }
-    catch {
-        return true;
-    }
-    return !hasDifferentRoute(anchor);
-}

package/dist/inspector/canvas/rendererBootstrap.js

@@ -155,6 +155,7 @@ export function bootstrapRenderer() {
         if (disposeSelector)
             owner.resourceDisposers.push(disposeSelector);
         installRendererPanProxy(owner);
+        let openLinksInCards = false;
         const onClick = (event) => {
             if (!ownsRendererBootstrap(owner))
                 return;
@@ -168,10 +169,16 @@ export function bootstrapRenderer() {
             const identity = getRendererIdentity();
             if (!identity)
                 return;
+            if (openLinksInCards) {
+                // Capture on document runs before framework routers, so the card keeps its route.
+                event.preventDefault();
+                event.stopImmediatePropagation();
+            }
             const msg = {
                 type: "navigation-intent",
                 protocolVersion: PROTOCOL_VERSION,
                 url: anchor.href,
+                ...(openLinksInCards ? { openInCard: true } : {}),
                 ...identity,
             };
             sendToParent(msg);
@@ -198,6 +205,12 @@ export function bootstrapRenderer() {
                 sendFrameReady(owner);
                 return;
             }
+            const frameIdentity = getRendererIdentity();
+            if (frameIdentity && isRendererMessageFor(msg, frameIdentity) && msg.type === "link-target-state") {
+                // SAFETY: the identity check proves a protocol message; the discriminator selects this shape.
+                openLinksInCards = msg.openInCard === true;
+                return;
+            }
             if (msg &&
                 typeof msg === "object" &&
                 msg.type === "replace-styles" &&

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

@@ -1,2 +1,2 @@
 export declare function buildSelector(el: HTMLElement): string;
-export declare function installRendererElementSelector(): () => void;
+export declare function installRendererElementSelector(acceptsClick?: (event: Event) => boolean): () => void;