@agent-native/core 0.80.9 → 0.80.10

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -15,6 +15,249 @@ import { isTrustedCanvasBridgeMessage } from "./bridge-security";
 import { DeviceFrame } from "./DeviceFrame";
 import type { ElementInfo, DeviceFrameType } from "./types";
 
+/**
+ * Allowlist check for Fusion (Builder-hosted) frame origins.
+ *
+ * Fusion frames are served cross-origin from the Builder-hosted app, so the
+ * strict `origin === parentOrigin` bridge check can never match. Before relaxing
+ * trust to window-identity only, we must confirm the message origin is actually
+ * a Builder host — the exact origin of the `fusionUrl` we were asked to render,
+ * or any `*.builder.io` host (plus the bare `builder.io`), over https. This
+ * prevents the relaxed-trust path from accepting messages from an arbitrary
+ * cross-origin frame that merely shares our iframe's window reference.
+ */
+function isAllowedFusionOrigin(
+  origin: string,
+  fusionUrl: string | undefined,
+): boolean {
+  if (!origin || origin === "null") return false;
+  let host: string;
+  let protocol: string;
+  try {
+    const parsed = new URL(origin);
+    host = parsed.hostname.toLowerCase();
+    protocol = parsed.protocol;
+  } catch {
+    return false;
+  }
+  // Only allow secure (https) Builder origins.
+  if (protocol !== "https:") return false;
+  // Exact match against the configured fusion URL's origin.
+  if (fusionUrl) {
+    try {
+      if (new URL(fusionUrl).origin === origin) return true;
+    } catch {
+      // Malformed fusionUrl — fall through to the host-family allowlist.
+    }
+  }
+  // Builder host family: builder.io and any subdomain of it.
+  return host === "builder.io" || host.endsWith(".builder.io");
+}
+
+/**
+ * Wire shape for a single motion track sent via the `motion-load-tracks`
+ * postMessage. Matches the serialisable subset of `MotionTrack` from
+ * `shared/motion-timeline.ts` without requiring an import at the UI layer.
+ */
+export interface MotionTrackWire {
+  targetNodeId: string;
+  property: string;
+  keyframes: Array<{ t: number; value: string; ease?: string }>;
+}
+
+/**
+ * Motion-preview bridge. Injected alongside the other bridge scripts so the
+ * MotionDock's scrubbing preview works in ALL editor modes without writing
+ * anything to the DB, Yjs state, or source files.
+ *
+ * Protocol (parent → iframe):
+ *
+ *   { type: 'motion-load-tracks', tracks: MotionTrackWire[] }
+ *     Load (or replace) the track list for this document. Each entry:
+ *     { targetNodeId, property, keyframes: [{ t, value, ease? }] }
+ *     where t ∈ [0, 1].  Sent whenever the active timeline changes.
+ *
+ *   { type: 'motion-preview', t, durationMs }
+ *     Seek all loaded tracks to normalised position t ∈ [0, 1] and apply
+ *     the interpolated CSS property values as inline styles on the matching
+ *     [data-agent-native-node-id="…"] elements.  Never writes to storage.
+ *
+ *   { type: 'motion-preview-clear' }
+ *     Remove all motion-preview inline-style overrides and the in-memory
+ *     track list.  Called when the dock is closed or the timeline is
+ *     discarded.
+ *
+ * Easing is deliberately simple: linear interpolation between keyframe
+ * values (CSS handles easing when the compiled CSS is actually applied;
+ * preview is a live visualisation, not a perfect recreation of the final
+ * animation).
+ */
+const MOTION_PREVIEW_BRIDGE_SCRIPT = `
+<script data-agent-native-motion-preview-bridge>
+(function() {
+  // Track list loaded by 'motion-load-tracks'.
+  var loadedTracks = [];
+  // Map of nodeId -> [property, ...] we have touched, for cleanup.
+  var touchedProps = {};
+
+  function lerp(a, b, ratio) {
+    var numA = parseFloat(a);
+    var numB = parseFloat(b);
+    if (Number.isFinite(numA) && Number.isFinite(numB)) {
+      var suffix = a.replace(/^-?[\\d.]+/, '') || b.replace(/^-?[\\d.]+/, '');
+      return (numA + (numB - numA) * ratio).toFixed(4).replace(/\\.?0+$/, '') + suffix;
+    }
+    // Non-numeric: snap to b after the midpoint.
+    return ratio < 0.5 ? a : b;
+  }
+
+  function interpolate(keyframes, t) {
+    if (!keyframes || keyframes.length === 0) return '';
+    if (keyframes.length === 1) return keyframes[0].value;
+    // Find surrounding keyframes.
+    var prev = keyframes[0];
+    var next = keyframes[keyframes.length - 1];
+    for (var i = 0; i < keyframes.length - 1; i++) {
+      if (t >= keyframes[i].t && t <= keyframes[i + 1].t) {
+        prev = keyframes[i];
+        next = keyframes[i + 1];
+        break;
+      }
+    }
+    var span = next.t - prev.t;
+    if (span <= 0) return prev.value;
+    var ratio = Math.max(0, Math.min(1, (t - prev.t) / span));
+    return lerp(prev.value, next.value, ratio);
+  }
+
+  function applyPreview(t) {
+    for (var i = 0; i < loadedTracks.length; i++) {
+      var track = loadedTracks[i];
+      var el = document.querySelector('[data-agent-native-node-id="' + track.targetNodeId + '"]');
+      if (!el) continue;
+      var value = interpolate(track.keyframes, t);
+      if (value === '') continue;
+      el.style[track.property] = value;
+      if (!touchedProps[track.targetNodeId]) touchedProps[track.targetNodeId] = [];
+      if (touchedProps[track.targetNodeId].indexOf(track.property) === -1) {
+        touchedProps[track.targetNodeId].push(track.property);
+      }
+    }
+  }
+
+  function clearPreview() {
+    var nodeIds = Object.keys(touchedProps);
+    for (var i = 0; i < nodeIds.length; i++) {
+      var el = document.querySelector('[data-agent-native-node-id="' + nodeIds[i] + '"]');
+      if (!el) continue;
+      var props = touchedProps[nodeIds[i]];
+      for (var j = 0; j < props.length; j++) {
+        el.style[props[j]] = '';
+      }
+    }
+    touchedProps = {};
+    loadedTracks = [];
+  }
+
+  window.addEventListener('message', function(e) {
+    if (e.source !== window.parent) return;
+    if (!e.data || typeof e.data.type !== 'string') return;
+    if (e.data.type === 'motion-load-tracks') {
+      loadedTracks = Array.isArray(e.data.tracks) ? e.data.tracks : [];
+      touchedProps = {};
+      return;
+    }
+    if (e.data.type === 'motion-preview') {
+      var t = Number(e.data.t);
+      if (!Number.isFinite(t)) return;
+      t = Math.max(0, Math.min(1, t));
+      applyPreview(t);
+      return;
+    }
+    if (e.data.type === 'motion-preview-clear') {
+      clearPreview();
+      return;
+    }
+  });
+})();
+</script>
+`;
+
+/**
+ * Shader-fill preview bridge.  ALWAYS injected alongside the other bridge
+ * scripts so the parent can apply a CSS gradient approximation of a shader
+ * fill to the currently-selected element **without** persisting anything.
+ *
+ * Protocol (parent → iframe):
+ *
+ *   { type: 'shader-fill-preview', selector, nodeId, css }
+ *     Apply `css` as the `background` inline style on the first element that
+ *     matches `selector` (preferred) or `[data-agent-native-node-id="nodeId"]`.
+ *     When both are absent, targets `document.body`.  Stores the previous
+ *     background value so it can be restored on clear.
+ *     Preview-only — never writes to DB, Yjs, or source files.
+ *
+ *   { type: 'shader-fill-preview-clear' }
+ *     Remove the applied background override and restore the previous value.
+ *     Called when the user discards the preview or switches selections.
+ */
+const SHADER_FILL_PREVIEW_BRIDGE_SCRIPT = `
+<script data-agent-native-shader-fill-preview-bridge>
+(function() {
+  // Track the element we patched and its original background so we can undo.
+  var patchedEl = null;
+  var originalBackground = '';
+
+  function resolveTarget(selector, nodeId) {
+    if (selector) {
+      try {
+        var hit = document.querySelector(selector);
+        if (hit) return hit;
+      } catch (_err) {}
+    }
+    if (nodeId) {
+      var byId = document.querySelector('[data-agent-native-node-id="' + nodeId.replace(/"/g, '\\\\"') + '"]');
+      if (byId) return byId;
+    }
+    return document.body;
+  }
+
+  function applyPreview(selector, nodeId, css) {
+    // Clear any prior patch first so we don't stack patches.
+    clearPreview();
+    var el = resolveTarget(selector, nodeId);
+    if (!el) return;
+    originalBackground = el.style.background || '';
+    el.style.background = css || '';
+    patchedEl = el;
+  }
+
+  function clearPreview() {
+    if (!patchedEl) return;
+    patchedEl.style.background = originalBackground;
+    patchedEl = null;
+    originalBackground = '';
+  }
+
+  window.addEventListener('message', function(e) {
+    if (e.source !== window.parent) return;
+    if (!e.data || typeof e.data.type !== 'string') return;
+    if (e.data.type === 'shader-fill-preview') {
+      var selector = typeof e.data.selector === 'string' ? e.data.selector : '';
+      var nodeId = typeof e.data.nodeId === 'string' ? e.data.nodeId : '';
+      var css = typeof e.data.css === 'string' ? e.data.css : '';
+      applyPreview(selector, nodeId, css);
+      return;
+    }
+    if (e.data.type === 'shader-fill-preview-clear') {
+      clearPreview();
+      return;
+    }
+  });
+})();
+</script>
+`;
+
 /**
  * Tweak-bridge script. ALWAYS injected so the parent's postMessage
  * (`tweak-values`) can update CSS custom properties on the iframe's :root
@@ -260,7 +503,11 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     var chromeTransitionStyle = document.createElement('style');
     chromeTransitionStyle.textContent =
       '[data-agent-native-edit-overlay="selection"]{transition:border-width 150ms ease-out}' +
-      '[data-agent-native-edge-handle],[data-agent-native-edit-handle],[data-agent-native-rotate-handle]{transition:width 150ms ease-out,height 150ms ease-out,border-width 150ms ease-out,top 150ms ease-out,bottom 150ms ease-out,left 150ms ease-out,right 150ms ease-out}';
+      '[data-agent-native-edge-handle],[data-agent-native-edit-handle],[data-agent-native-rotate-handle]{transition:width 150ms ease-out,height 150ms ease-out,border-width 150ms ease-out,top 150ms ease-out,bottom 150ms ease-out,left 150ms ease-out,right 150ms ease-out}' +
+      '[data-agent-native-spacing-line]{position:absolute;display:none;pointer-events:none;border-radius:999px}' +
+      '[data-agent-native-spacing-region]{position:absolute;display:none;box-sizing:border-box;pointer-events:auto;background-size:6px 6px}' +
+      '[data-agent-native-spacing-region][data-orientation="vertical"]{cursor:ew-resize}' +
+      '[data-agent-native-spacing-region][data-orientation="horizontal"]{cursor:ns-resize}';
     (document.head || document.documentElement).appendChild(chromeTransitionStyle);
   })();
 
@@ -484,6 +731,38 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
         reason: 'Parent layout context decides whether movement means gap, order, alignment, or wrapper structure.',
       });
     }
+    // --- provenance: read source-location attributes when present ---
+    // These are emitted by connected apps via @vitejs/plugin-react jsxDEV or a
+    // Babel source plugin.  Cross-origin localhost iframes cannot be read (CSP /
+    // same-origin policy), so this will be undefined in that case — expected.
+    var provenance = undefined;
+    var dataSourceFile = el.getAttribute('data-source-file');
+    var dataSourceLine = el.getAttribute('data-source-line');
+    var dataSourceColumn = el.getAttribute('data-source-column');
+    var dataComponentName = el.getAttribute('data-component-name');
+    var dataLoc = el.getAttribute('data-loc');
+    // data-loc may encode "file:line:col" (Babel source plugin convention).
+    // Only parse it when data-source-file is absent, to avoid double-reads.
+    if (!dataSourceFile && dataLoc) {
+      var lastColonIndex = dataLoc.lastIndexOf(':');
+      var lastPart = lastColonIndex >= 0 ? dataLoc.slice(lastColonIndex + 1) : '';
+      if (lastColonIndex >= 0 && /^\\d+$/.test(lastPart)) {
+        var beforeLastPart = dataLoc.slice(0, lastColonIndex);
+        var previousColonIndex = beforeLastPart.lastIndexOf(':');
+        var previousPart = previousColonIndex >= 0 ? beforeLastPart.slice(previousColonIndex + 1) : '';
+        var hasColumn = /^\\d+$/.test(previousPart);
+        dataSourceFile = hasColumn ? beforeLastPart.slice(0, previousColonIndex) : beforeLastPart;
+        dataSourceLine = hasColumn ? previousPart : lastPart;
+        if (hasColumn) dataSourceColumn = lastPart;
+      }
+    }
+    if (dataSourceFile || dataSourceLine || dataSourceColumn || dataComponentName) {
+      provenance = {};
+      if (dataSourceFile) provenance.sourceFile = dataSourceFile;
+      if (dataSourceLine) { var ln = parseInt(dataSourceLine, 10); if (!isNaN(ln)) provenance.line = ln; }
+      if (dataSourceColumn) { var col = parseInt(dataSourceColumn, 10); if (!isNaN(col)) provenance.column = col; }
+      if (dataComponentName) provenance.component = dataComponentName;
+    }
     return {
       tagName: el.tagName.toLowerCase(),
       id: el.id || undefined,
@@ -559,6 +838,7 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
       confidence: capabilities.reduce(function(best, item) {
         return Math.max(best, item.confidence || 0);
       }, 0),
+      provenance: provenance,
     };
   }
 
@@ -635,10 +915,10 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     if (pos.indexOf('e') !== -1) rotate.style.right = '-26px';
     selectionOverlay.appendChild(rotate);
   });
-  var paddingOverlay = document.createElement('div');
-  paddingOverlay.setAttribute('data-agent-native-padding-overlay', '');
-  paddingOverlay.style.cssText = 'position:absolute;border:1px dashed var(--design-editor-accent-strong-color);border-radius:2px;pointer-events:none;';
-  selectionOverlay.appendChild(paddingOverlay);
+  var spacingOverlay = document.createElement('div');
+  spacingOverlay.setAttribute('data-agent-native-spacing-overlay', '');
+  spacingOverlay.style.cssText = 'position:absolute;inset:0;display:none;pointer-events:none;';
+  selectionOverlay.appendChild(spacingOverlay);
   document.body.appendChild(selectionOverlay);
 
   var transformBadge = document.createElement('div');
@@ -646,6 +926,11 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
   transformBadge.style.cssText = 'position:fixed;z-index:100000;display:none;pointer-events:none;border:1px solid hsl(var(--border));border-radius:4px;background:hsl(var(--background) / 0.96);color:hsl(var(--foreground));font:11px/1.4 ui-monospace,SFMono-Regular,Menlo,monospace;padding:3px 5px;box-shadow:0 8px 20px color-mix(in srgb, hsl(var(--foreground)) 16%, transparent);';
   document.body.appendChild(transformBadge);
 
+  var spacingBadge = document.createElement('div');
+  spacingBadge.setAttribute('data-agent-native-spacing-badge', '');
+  spacingBadge.style.cssText = 'position:fixed;z-index:100000;display:none;pointer-events:none;border-radius:3px;color:white;font:10px/1.2 ui-monospace,SFMono-Regular,Menlo,monospace;font-weight:700;padding:2px 4px;box-shadow:0 4px 14px rgba(0,0,0,0.18);';
+  document.body.appendChild(spacingBadge);
+
   var insertionGuide = document.createElement('div');
   insertionGuide.setAttribute('data-agent-native-insertion-guide', '');
   insertionGuide.style.cssText = 'position:fixed;z-index:100000;display:none;pointer-events:none;background:var(--design-editor-accent-color);border-radius:999px;box-shadow:0 0 0 1px var(--design-editor-accent-color);';
@@ -656,20 +941,116 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
   measurementOverlay.style.cssText = 'position:fixed;inset:0;z-index:100001;display:none;pointer-events:none;color:var(--design-editor-measure-color);font:11px/1.2 ui-monospace,SFMono-Regular,Menlo,monospace;';
   document.body.appendChild(measurementOverlay);
 
+  // Component-instance tag: a small pill that floats above the selection
+  // outline whenever the selected element carries a data-agent-native-component
+  // attribute.  Clicking it sends a 'component-source-jump' message to the
+  // parent so the editor can invoke open-component-source.
+  var componentTagOverlay = document.createElement('div');
+  componentTagOverlay.setAttribute('data-agent-native-edit-overlay', 'component-tag');
+  componentTagOverlay.style.cssText = [
+    'position:fixed',
+    'z-index:100002',
+    'display:none',
+    'pointer-events:auto',
+    'cursor:pointer',
+    'padding:2px 6px',
+    'border-radius:4px',
+    'font:11px/1.6 ui-sans-serif,system-ui,sans-serif',
+    'white-space:nowrap',
+    'user-select:none',
+    '-webkit-user-select:none',
+    'background:var(--design-editor-accent-color)',
+    'color:var(--design-editor-accent-contrast-color)',
+    'box-shadow:0 1px 4px color-mix(in srgb,var(--design-editor-accent-color) 40%,transparent)',
+    'border:1px solid color-mix(in srgb,var(--design-editor-accent-strong-color) 60%,transparent)',
+    'outline:2px solid transparent',
+    'transition:opacity 0.1s',
+  ].join(';') + ';';
+  document.body.appendChild(componentTagOverlay);
+
+  componentTagOverlay.addEventListener('click', function(e) {
+    e.stopPropagation();
+    e.preventDefault();
+    var nodeId = componentTagOverlay.getAttribute('data-component-node-id') || '';
+    var componentName = componentTagOverlay.getAttribute('data-component-name') || '';
+    if (!nodeId || !componentName) return;
+    try {
+      window.parent.postMessage({
+        type: 'component-source-jump',
+        nodeId: nodeId,
+        componentName: componentName,
+      }, '*');
+    } catch (_err) {}
+  });
+
+  function updateComponentTag(el) {
+    if (!el) {
+      clearComponentTag();
+      return;
+    }
+    var compName = el.getAttribute && el.getAttribute('data-agent-native-component');
+    if (!compName) {
+      clearComponentTag();
+      return;
+    }
+    var nodeId = (
+      el.getAttribute('data-agent-native-node-id') ||
+      el.getAttribute('data-code-layer-id') ||
+      el.getAttribute('data-layer-id') ||
+      el.id ||
+      ''
+    );
+    componentTagOverlay.textContent = compName + ' →';
+    componentTagOverlay.setAttribute('data-component-node-id', nodeId);
+    componentTagOverlay.setAttribute('data-component-name', compName);
+
+    var rect = el.getBoundingClientRect();
+    var tagHeight = 22;
+    var tagTop = rect.top - tagHeight - 4;
+    if (tagTop < 4) tagTop = rect.top + 4;
+    componentTagOverlay.style.display = 'block';
+    componentTagOverlay.style.left = rect.left + 'px';
+    componentTagOverlay.style.top = tagTop + 'px';
+    // Accent outline on the selection overlay to distinguish component roots.
+    selectionOverlay.style.outline = '2px solid var(--design-editor-accent-strong-color)';
+    selectionOverlay.style.outlineOffset = '2px';
+  }
+
+  function clearComponentTag() {
+    componentTagOverlay.style.display = 'none';
+    componentTagOverlay.removeAttribute('data-component-node-id');
+    componentTagOverlay.removeAttribute('data-component-name');
+    selectionOverlay.style.outline = '';
+    selectionOverlay.style.outlineOffset = '';
+  }
+
 	  var selectedEl = null;
 	  var hoveredEl = null;
 	  var activeTextEditEl = null;
 	  var textEditPointerState = null;
 	  var pendingStructureMove = null;
+  var pendingShieldDrag = null;
+  var suppressNextShieldClick = false;
+  var suppressNextShieldClickTimer = null;
+  var selectedSpacingHovered = false;
+  var hoveredSpacingHandleKey = '';
+  var spacingHandleStateByKey = {};
+  var spacingHandleNodesByKey = {};
+  var spacingDrag = null;
 	  var lockedSelectors = [];
 	  var hiddenSelectors = [];
 
   function clearRuntimeSelection() {
     selectedEl = null;
     hoveredEl = null;
+    selectedSpacingHovered = false;
+    hoveredSpacingHandleKey = '';
+    spacingDrag = null;
     selectionOverlay.style.display = 'none';
     highlightOverlay.style.display = 'none';
+    hideSpacingOverlay();
     hideMeasurements();
+    clearComponentTag();
   }
 
   function matchesSelectorList(el, selectors) {
@@ -849,22 +1230,365 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     refreshOverlays();
   }
 
-  function updatePaddingOverlay(el) {
-    if (!el) {
-      paddingOverlay.style.display = 'none';
-      return;
+  function hideSpacingOverlay() {
+    spacingOverlay.style.display = 'none';
+    spacingOverlay.innerHTML = '';
+    spacingHandleStateByKey = {};
+    spacingHandleNodesByKey = {};
+    if (!spacingDrag) spacingBadge.style.display = 'none';
+  }
+
+  function visibleLayoutChildren(el) {
+    if (!el || !el.children) return [];
+    return Array.prototype.slice.call(el.children).filter(function(child) {
+      if (!child || child.nodeType !== 1 || isOverlayElement(child) || isLayerInteractionBlocked(child)) return false;
+      var cs = window.getComputedStyle(child);
+      if (cs.display === 'none' || cs.visibility === 'hidden' || cs.position === 'fixed') return false;
+      var rect = child.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    });
+  }
+
+  function spacingColor(kind) {
+    return kind === 'gap' ? '#ff4fd8' : 'var(--design-editor-accent-color)';
+  }
+
+  function spacingFill(kind, orientation) {
+    var tint = kind === 'gap' ? 'rgba(255, 79, 216, 0.28)' : 'rgba(46, 168, 255, 0.24)';
+    var stripe = kind === 'gap' ? 'rgba(255, 79, 216, 0.58)' : 'rgba(46, 168, 255, 0.52)';
+    var angle = orientation === 'vertical' ? '135deg' : '45deg';
+    return 'repeating-linear-gradient(' + angle + ', ' + stripe + ' 0 1px, ' + tint + ' 1px 4px, transparent 4px 7px)';
+  }
+
+  function clampSpacingValue(value) {
+    var rounded = Math.round(value);
+    if (!Number.isFinite(rounded)) return 0;
+    return Math.max(0, Math.min(999, rounded));
+  }
+
+  function makeSpacingHandle(config) {
+    var region = config.region;
+    if (!region || region.width <= 0 || region.height <= 0) return null;
+    return {
+      key: config.key,
+      groupKey: config.groupKey || config.key,
+      kind: config.kind,
+      property: config.property,
+      oppositeProperty: config.oppositeProperty || '',
+      side: config.side || '',
+      orientation: config.orientation,
+      value: clampSpacingValue(config.value),
+      region: {
+        x: Math.round(region.x),
+        y: Math.round(region.y),
+        width: Math.max(1, Math.round(region.width)),
+        height: Math.max(1, Math.round(region.height)),
+      },
+      line: config.line,
+    };
+  }
+
+  function childLocalRect(child, containerRect) {
+    var rect = child.getBoundingClientRect();
+    return {
+      left: rect.left - containerRect.left,
+      top: rect.top - containerRect.top,
+      right: rect.right - containerRect.left,
+      bottom: rect.bottom - containerRect.top,
+      width: rect.width,
+      height: rect.height,
+    };
+  }
+
+  function childRectsOverlap(a, b, axis) {
+    if (axis === 'x') {
+      return Math.max(a.top, b.top) < Math.min(a.bottom, b.bottom);
     }
+    return Math.max(a.left, b.left) < Math.min(a.right, b.right);
+  }
+
+  function buildPaddingSpacingHandles(el, rect, cs) {
+    var handles = [];
+    var borderTop = readPx(cs.borderTopWidth);
+    var borderRight = readPx(cs.borderRightWidth);
+    var borderBottom = readPx(cs.borderBottomWidth);
+    var borderLeft = readPx(cs.borderLeftWidth);
+    var paddingTop = readPx(cs.paddingTop);
+    var paddingRight = readPx(cs.paddingRight);
+    var paddingBottom = readPx(cs.paddingBottom);
+    var paddingLeft = readPx(cs.paddingLeft);
+    var sx = chromeScaleX();
+    var sy = chromeScaleY();
+    var line = Math.max(1, chromeLineScale());
+    var hLineWidth = Math.max(8, Math.min(24, rect.width * 0.18)) * sx;
+    var vLineHeight = Math.max(8, Math.min(24, rect.height * 0.18)) * sy;
+    var innerLeft = borderLeft;
+    var innerTop = borderTop;
+    var innerWidth = Math.max(1, rect.width - borderLeft - borderRight);
+    var innerHeight = Math.max(1, rect.height - borderTop - borderBottom);
+    if (paddingTop > 0) {
+      handles.push(makeSpacingHandle({
+        key: 'padding:top',
+        kind: 'padding',
+        property: 'paddingTop',
+        oppositeProperty: 'paddingBottom',
+        side: 'top',
+        orientation: 'horizontal',
+        value: paddingTop,
+        region: { x: innerLeft, y: innerTop, width: innerWidth, height: paddingTop },
+        line: {
+          x: rect.width / 2 - hLineWidth / 2,
+          y: innerTop + paddingTop / 2 - line / 2,
+          width: hLineWidth,
+          height: line,
+        },
+      }));
+    }
+    if (paddingBottom > 0) {
+      handles.push(makeSpacingHandle({
+        key: 'padding:bottom',
+        kind: 'padding',
+        property: 'paddingBottom',
+        oppositeProperty: 'paddingTop',
+        side: 'bottom',
+        orientation: 'horizontal',
+        value: paddingBottom,
+        region: { x: innerLeft, y: rect.height - borderBottom - paddingBottom, width: innerWidth, height: paddingBottom },
+        line: {
+          x: rect.width / 2 - hLineWidth / 2,
+          y: rect.height - borderBottom - paddingBottom / 2 - line / 2,
+          width: hLineWidth,
+          height: line,
+        },
+      }));
+    }
+    if (paddingLeft > 0) {
+      handles.push(makeSpacingHandle({
+        key: 'padding:left',
+        kind: 'padding',
+        property: 'paddingLeft',
+        oppositeProperty: 'paddingRight',
+        side: 'left',
+        orientation: 'vertical',
+        value: paddingLeft,
+        region: { x: innerLeft, y: innerTop, width: paddingLeft, height: innerHeight },
+        line: {
+          x: innerLeft + paddingLeft / 2 - line / 2,
+          y: rect.height / 2 - vLineHeight / 2,
+          width: line,
+          height: vLineHeight,
+        },
+      }));
+    }
+    if (paddingRight > 0) {
+      handles.push(makeSpacingHandle({
+        key: 'padding:right',
+        kind: 'padding',
+        property: 'paddingRight',
+        oppositeProperty: 'paddingLeft',
+        side: 'right',
+        orientation: 'vertical',
+        value: paddingRight,
+        region: { x: rect.width - borderRight - paddingRight, y: innerTop, width: paddingRight, height: innerHeight },
+        line: {
+          x: rect.width - borderRight - paddingRight / 2 - line / 2,
+          y: rect.height / 2 - vLineHeight / 2,
+          width: line,
+          height: vLineHeight,
+        },
+      }));
+    }
+    return handles.filter(Boolean);
+  }
+
+  function buildGapSpacingHandles(el, rect, cs) {
+    var children = visibleLayoutChildren(el);
+    if (children.length < 2) return [];
+    var handles = [];
+    var sx = chromeScaleX();
+    var sy = chromeScaleY();
+    var line = Math.max(1, chromeLineScale());
+    var hLineWidth = 10 * sx;
+    var vLineHeight = 10 * sy;
+    var isFlex = cs.display === 'flex' || cs.display === 'inline-flex';
+    var isGrid = cs.display === 'grid' || cs.display === 'inline-grid';
+    if (!isFlex && !isGrid) return handles;
+    var primaryAxis = isFlex && cs.flexDirection && cs.flexDirection.indexOf('column') === 0 ? 'y' : 'x';
+    var childRects = children.map(function(child) {
+      return childLocalRect(child, rect);
+    });
+
+    function addAxisGaps(axis, property, groupKey) {
+      var cssGap = readPx(cs[property]);
+      if (cssGap <= 0) return;
+      var sorted = childRects.slice().sort(function(a, b) {
+        return axis === 'x' ? a.left - b.left : a.top - b.top;
+      });
+      var count = 0;
+      for (var i = 0; i < sorted.length - 1; i += 1) {
+        var a = sorted[i];
+        var b = sorted[i + 1];
+        if (!childRectsOverlap(a, b, axis)) continue;
+        var gap = axis === 'x' ? b.left - a.right : b.top - a.bottom;
+        if (gap <= 1) continue;
+        if (axis === 'x') {
+          var top = Math.max(a.top, b.top);
+          var bottom = Math.min(a.bottom, b.bottom);
+          var height = Math.max(1, bottom - top);
+          handles.push(makeSpacingHandle({
+            key: groupKey + ':' + count,
+            groupKey: groupKey,
+            kind: 'gap',
+            property: property,
+            orientation: 'vertical',
+            value: cssGap,
+            region: { x: a.right, y: top, width: gap, height: height },
+            line: {
+              x: a.right + gap / 2 - line / 2,
+              y: top + height / 2 - vLineHeight / 2,
+              width: line,
+              height: vLineHeight,
+            },
+          }));
+        } else {
+          var left = Math.max(a.left, b.left);
+          var right = Math.min(a.right, b.right);
+          var width = Math.max(1, right - left);
+          handles.push(makeSpacingHandle({
+            key: groupKey + ':' + count,
+            groupKey: groupKey,
+            kind: 'gap',
+            property: property,
+            orientation: 'horizontal',
+            value: cssGap,
+            region: { x: left, y: a.bottom, width: width, height: gap },
+            line: {
+              x: left + width / 2 - hLineWidth / 2,
+              y: a.bottom + gap / 2 - line / 2,
+              width: hLineWidth,
+              height: line,
+            },
+          }));
+        }
+        count += 1;
+      }
+    }
+
+    if (primaryAxis === 'x') {
+      addAxisGaps('x', 'columnGap', 'gap:column');
+      if (isGrid) addAxisGaps('y', 'rowGap', 'gap:row');
+    } else {
+      addAxisGaps('y', 'rowGap', 'gap:row');
+      if (isGrid) addAxisGaps('x', 'columnGap', 'gap:column');
+    }
+    return handles.filter(Boolean);
+  }
+
+  function buildSpacingHandles(el) {
+    if (!el || !document.documentElement.contains(el)) return [];
+    if (Math.abs(currentRotation(el)) > 0.01) return [];
+    var children = visibleLayoutChildren(el);
+    if (children.length === 0) return [];
+    var rect = el.getBoundingClientRect();
+    if (rect.width <= 0 || rect.height <= 0) return [];
     var cs = window.getComputedStyle(el);
-    var top = readPx(cs.paddingTop) + readPx(cs.borderTopWidth);
-    var right = readPx(cs.paddingRight) + readPx(cs.borderRightWidth);
-    var bottom = readPx(cs.paddingBottom) + readPx(cs.borderBottomWidth);
-    var left = readPx(cs.paddingLeft) + readPx(cs.borderLeftWidth);
-    var hasPadding = top > 0 || right > 0 || bottom > 0 || left > 0;
-    paddingOverlay.style.display = hasPadding ? 'block' : 'none';
-    paddingOverlay.style.top = top + 'px';
-    paddingOverlay.style.right = right + 'px';
-    paddingOverlay.style.bottom = bottom + 'px';
-    paddingOverlay.style.left = left + 'px';
+    return buildPaddingSpacingHandles(el, rect, cs).concat(buildGapSpacingHandles(el, rect, cs));
+  }
+
+  function showSpacingBadgeForHandle(handle, value) {
+    if (!selectedEl || !handle) {
+      spacingBadge.style.display = 'none';
+      return;
+    }
+    var rect = selectedEl.getBoundingClientRect();
+    var x = rect.left + handle.region.x + handle.region.width / 2;
+    var y = rect.top + handle.region.y + handle.region.height / 2;
+    spacingBadge.textContent = String(clampSpacingValue(value));
+    spacingBadge.style.display = 'block';
+    spacingBadge.style.background = spacingColor(handle.kind);
+    spacingBadge.style.left = x + 'px';
+    spacingBadge.style.top = y + 'px';
+    spacingBadge.style.transform = 'translate(-50%, -50%)';
+  }
+
+  function renderSpacingHandle(handle, activeGroupKey) {
+    if (!handle) return;
+    spacingHandleStateByKey[handle.key] = handle;
+    var highlighted = Boolean(activeGroupKey && handle.groupKey === activeGroupKey);
+    var lineNode = document.createElement('span');
+    lineNode.setAttribute('data-agent-native-spacing-line', handle.kind);
+    lineNode.style.display = 'block';
+    lineNode.style.left = handle.line.x + 'px';
+    lineNode.style.top = handle.line.y + 'px';
+    lineNode.style.width = Math.max(1, handle.line.width) + 'px';
+    lineNode.style.height = Math.max(1, handle.line.height) + 'px';
+    lineNode.style.background = spacingColor(handle.kind);
+    spacingOverlay.appendChild(lineNode);
+
+    var regionNode = document.createElement('span');
+    regionNode.setAttribute('data-agent-native-spacing-region', handle.kind);
+    regionNode.setAttribute('data-orientation', handle.orientation);
+    regionNode.setAttribute('data-spacing-key', handle.key);
+    regionNode.style.display = 'block';
+    regionNode.style.left = handle.region.x + 'px';
+    regionNode.style.top = handle.region.y + 'px';
+    regionNode.style.width = handle.region.width + 'px';
+    regionNode.style.height = handle.region.height + 'px';
+    regionNode.style.background = highlighted ? spacingFill(handle.kind, handle.orientation) : 'transparent';
+    regionNode.style.outline = highlighted ? '1px solid ' + spacingColor(handle.kind) : '0';
+    regionNode.style.outlineOffset = '-1px';
+    regionNode.addEventListener('mouseenter', function() {
+      hoveredSpacingHandleKey = handle.key;
+      selectedSpacingHovered = true;
+      updateSpacingOverlay(selectedEl);
+    });
+    regionNode.addEventListener('mouseleave', function() {
+      if (spacingDrag) return;
+      hoveredSpacingHandleKey = '';
+      updateSpacingOverlay(selectedEl);
+    });
+    regionNode.addEventListener('mousedown', function(event) {
+      startSpacingDrag(handle.key, event);
+    }, true);
+    spacingHandleNodesByKey[handle.key] = regionNode;
+    spacingOverlay.appendChild(regionNode);
+  }
+
+  function updateSpacingOverlay(el) {
+    if (el && el !== selectedEl) {
+      hideSpacingOverlay();
+      return;
+    }
+    if (!selectedEl || !document.documentElement.contains(selectedEl)) {
+      hideSpacingOverlay();
+      return;
+    }
+    if (!selectedSpacingHovered && !hoveredSpacingHandleKey && !spacingDrag) {
+      hideSpacingOverlay();
+      return;
+    }
+    var handles = buildSpacingHandles(selectedEl);
+    if (handles.length === 0) {
+      hideSpacingOverlay();
+      return;
+    }
+    spacingOverlay.style.display = 'block';
+    spacingOverlay.innerHTML = '';
+    spacingHandleStateByKey = {};
+    spacingHandleNodesByKey = {};
+    var activeHandle =
+      (spacingDrag && spacingDrag.handle) ||
+      handles.find(function(handle) { return handle.key === hoveredSpacingHandleKey; }) ||
+      null;
+    var activeGroupKey = activeHandle ? activeHandle.groupKey : '';
+    handles.forEach(function(handle) {
+      renderSpacingHandle(handle, activeGroupKey);
+    });
+    if (activeHandle) {
+      showSpacingBadgeForHandle(activeHandle, spacingDrag ? spacingDrag.currentValue : activeHandle.value);
+    } else {
+      spacingBadge.style.display = 'none';
+    }
   }
 
   function applyEditorChromeScale() {
@@ -874,7 +1598,7 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     var line = chromeLineScale();
     highlightOverlay.style.borderWidth = (1.5 * line) + 'px';
     selectionOverlay.style.borderWidth = (1.5 * line) + 'px';
-    paddingOverlay.style.borderWidth = Math.max(1, 1 * line) + 'px';
+    if (selectedEl) updateSpacingOverlay(selectedEl);
 
     selectionOverlay.querySelectorAll('[data-agent-native-edge-handle]').forEach(function(edge) {
       var pos = edge.getAttribute('data-agent-native-edge-handle');
@@ -913,6 +1637,7 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
   function positionOverlay(overlay, el) {
     if (!el || !document.documentElement.contains(el)) {
       overlay.style.display = 'none';
+      if (overlay === selectionOverlay) clearComponentTag();
       return;
     }
     // For the selection overlay, prefer the CSS box + rotation transform so
@@ -936,7 +1661,8 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
         overlay.style.height = elH + 'px';
         overlay.style.transform = 'rotate(' + elRot + 'deg)';
         overlay.style.transformOrigin = '0 0';
-        updatePaddingOverlay(el);
+        updateSpacingOverlay(el);
+        updateComponentTag(el);
         return;
       }
     }
@@ -947,7 +1673,10 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     overlay.style.width = rect.width + 'px';
     overlay.style.height = rect.height + 'px';
     overlay.style.transform = '';
-    if (overlay === selectionOverlay) updatePaddingOverlay(el);
+    if (overlay === selectionOverlay) {
+      updateSpacingOverlay(el);
+      updateComponentTag(el);
+    }
   }
 
   function refreshOverlays() {
@@ -1026,6 +1755,13 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     );
   }
 
+  function dragEventNames(e) {
+    var pointerGesture = e && e.type && e.type.indexOf('pointer') === 0;
+    return pointerGesture
+      ? { move: 'pointermove', up: 'pointerup' }
+      : { move: 'mousemove', up: 'mouseup' };
+  }
+
   function elementFromEditorPoint(clientX, clientY) {
     var shieldPointerEvents = shieldOverlay.style.pointerEvents;
     var selectionPointerEvents = selectionOverlay.style.pointerEvents;
@@ -1190,6 +1926,14 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
   function selectElementAtEvent(e) {
     stopNativeInteraction(e);
     blurActiveTextEditor();
+    if (suppressNextShieldClick) {
+      suppressNextShieldClick = false;
+      if (suppressNextShieldClickTimer !== null) {
+        clearTimeout(suppressNextShieldClickTimer);
+        suppressNextShieldClickTimer = null;
+      }
+      return;
+    }
     // Suppress the first click in a double-click sequence — the dblclick
     // handler (beginTextEditingFromEvent) will fire immediately after and a
     // spurious element-select would cause inspector flicker.
@@ -1197,23 +1941,37 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     var target = elementFromEditorPoint(e.clientX, e.clientY);
     if (!target || target === document.body || target === document.documentElement) {
       // Click on empty canvas: clear the current selection (matches Figma).
-      selectedEl = null;
-      selectionOverlay.style.display = 'none';
+      clearRuntimeSelection();
       window.parent.postMessage({ type: 'clear-selection' }, '*');
       return;
     }
+    selectedSpacingHovered = false;
+    hoveredSpacingHandleKey = '';
     selectedEl = selectionTargetForHit(target);
     var info = getElementInfo(selectedEl);
     positionOverlay(selectionOverlay, selectedEl);
     window.parent.postMessage({ type: 'element-select', payload: info }, '*');
   }
 
+  function suppressNextShieldClickBriefly() {
+    suppressNextShieldClick = true;
+    if (suppressNextShieldClickTimer !== null) {
+      clearTimeout(suppressNextShieldClickTimer);
+    }
+    suppressNextShieldClickTimer = setTimeout(function() {
+      suppressNextShieldClick = false;
+      suppressNextShieldClickTimer = null;
+    }, 250);
+  }
+
   function openContextMenuAtEvent(e) {
     stopNativeInteraction(e);
     blurActiveTextEditor();
     var target = elementFromEditorPoint(e.clientX, e.clientY);
     var info = null;
     if (target) {
+      selectedSpacingHovered = false;
+      hoveredSpacingHandleKey = '';
       selectedEl = selectionTargetForHit(target);
       info = getElementInfo(selectedEl);
       positionOverlay(selectionOverlay, selectedEl);
@@ -1319,6 +2077,81 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     }, '*');
   }
 
+  function spacingValueFromPointer(handle, originValue, startX, startY, clientX, clientY) {
+    var delta =
+      handle.orientation === 'vertical' ? clientX - startX : clientY - startY;
+    if (handle.kind === 'padding' && (handle.side === 'right' || handle.side === 'bottom')) {
+      delta = -delta;
+    }
+    return clampSpacingValue(originValue + delta);
+  }
+
+  function applySpacingDragValue(target, handle, value, mirrorOpposite) {
+    if (!target || !handle) return;
+    target.style[handle.property] = value + 'px';
+    if (handle.kind === 'padding' && mirrorOpposite && handle.oppositeProperty) {
+      target.style[handle.oppositeProperty] = value + 'px';
+    }
+  }
+
+  function startSpacingDrag(key, e) {
+    var handle = spacingHandleStateByKey[key];
+    if (!selectedEl || !handle || isLayerInteractionBlocked(selectedEl)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.stopImmediatePropagation) e.stopImmediatePropagation();
+    var events = dragEventNames(e);
+    var dragEl = selectedEl;
+    var originValue = handle.value;
+    var startX = e.clientX;
+    var startY = e.clientY;
+    hoveredSpacingHandleKey = key;
+    selectedSpacingHovered = true;
+    spacingDrag = {
+      handle: handle,
+      currentValue: originValue,
+      mirrorOpposite: !!e.altKey,
+    };
+    showSpacingBadgeForHandle(handle, originValue);
+
+    function onMove(ev) {
+      if (!dragEl || !document.documentElement.contains(dragEl)) return;
+      var nextValue = spacingValueFromPointer(handle, originValue, startX, startY, ev.clientX, ev.clientY);
+      spacingDrag = {
+        handle: handle,
+        currentValue: nextValue,
+        mirrorOpposite: !!ev.altKey,
+      };
+      applySpacingDragValue(dragEl, handle, nextValue, !!ev.altKey);
+      positionOverlay(selectionOverlay, dragEl);
+      showSpacingBadgeForHandle(handle, nextValue);
+    }
+
+    function onUp(ev) {
+      document.removeEventListener(events.move, onMove, true);
+      document.removeEventListener(events.up, onUp, true);
+      if (!dragEl || !document.documentElement.contains(dragEl)) {
+        spacingDrag = null;
+        return;
+      }
+      var finalValue = spacingDrag ? spacingDrag.currentValue : originValue;
+      var mirrorOpposite = spacingDrag ? spacingDrag.mirrorOpposite : !!ev.altKey;
+      applySpacingDragValue(dragEl, handle, finalValue, mirrorOpposite);
+      selectedEl = dragEl;
+      spacingDrag = null;
+      var styles = {};
+      styles[handle.property] = finalValue + 'px';
+      if (handle.kind === 'padding' && mirrorOpposite && handle.oppositeProperty) {
+        styles[handle.oppositeProperty] = finalValue + 'px';
+      }
+      postVisualStyleChange(styles);
+      positionOverlay(selectionOverlay, dragEl);
+    }
+
+    document.addEventListener(events.move, onMove, true);
+    document.addEventListener(events.up, onUp, true);
+  }
+
 	  function postTextContentChange(el, value, html) {
 	    window.parent.postMessage({
 	      type: 'text-content-change',
@@ -1404,7 +2237,14 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
   }
 
   function isOverlayElement(el) {
-    return Boolean(el && el.getAttribute && el.getAttribute('data-agent-native-edit-overlay'));
+    // Use closest() so that children of overlay elements (e.g. spacing-region
+    // spans inside selectionOverlay that have pointer-events:auto via a CSS rule
+    // and can therefore still be returned by elementFromPoint even when the
+    // parent overlay has pointer-events:none set inline) are also treated as
+    // overlay elements and never used as drag-drop anchor targets.
+    return Boolean(
+      el && el.closest && el.closest('[data-agent-native-edit-overlay]')
+    );
   }
 
   function draggableElementChildren(parent) {
@@ -1418,9 +2258,40 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     if (el === document.body || el === document.documentElement) return false;
     var cs = window.getComputedStyle(el);
     if (cs.position === 'absolute' || cs.position === 'fixed') return false;
-    var parent = el.parentElement;
-    if (parent === document.body && draggableElementChildren(parent).length <= 2) return false;
-    return draggableElementChildren(parent).filter(function(child) { return child !== el; }).length > 0;
+    return true;
+  }
+
+  // keep in sync with EditPanel.tsx CONTAINER_TAGS/LEAF_TAGS (~line 1679)
+  var BRIDGE_CONTAINER_TAGS = ['div', 'section', 'main', 'header', 'footer', 'nav', 'article', 'aside', 'form', 'ul', 'ol', 'figure', 'fieldset', 'details', 'dialog', 'blockquote', 'table', 'tbody', 'thead', 'tr'];
+  var BRIDGE_LEAF_TAGS = ['img', 'video', 'picture', 'audio', 'canvas', 'svg', 'path', 'input', 'textarea', 'select', 'br', 'hr', 'iframe'];
+  var BRIDGE_TEXT_TAGS = ['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'span', 'a', 'strong', 'em', 'label', 'li'];
+
+  function isContainerDropTarget(el) {
+    if (!el || el === document.documentElement) return false;
+    if (isOverlayElement(el) || isLayerInteractionBlocked(el)) return false;
+    if (el === document.body) return true;
+    var tag = (el.tagName || '').toLowerCase();
+    // Reject leaf/text tags — they cannot accept children
+    if (BRIDGE_LEAF_TAGS.indexOf(tag) !== -1 || BRIDGE_TEXT_TAGS.indexOf(tag) !== -1) return false;
+    var cs = window.getComputedStyle(el);
+    if (
+      cs.display === 'flex' ||
+      cs.display === 'inline-flex' ||
+      cs.display === 'grid' ||
+      cs.display === 'inline-grid'
+    ) {
+      return true;
+    }
+    return BRIDGE_CONTAINER_TAGS.indexOf(tag) !== -1;
+  }
+
+  function edgePlacementForRect(rect, axis, clientX, clientY) {
+    var size = axis === 'x' ? rect.width : rect.height;
+    if (!size) return null;
+    var offset = axis === 'x' ? clientX - rect.left : clientY - rect.top;
+    if (offset < size * 0.22) return 'before';
+    if (offset > size * 0.78) return 'after';
+    return null;
   }
 
   function parentFlowAxis(parent) {
@@ -1445,18 +2316,19 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     var hit = elementFromEditorPoint(clientX, clientY);
     if (
       hit &&
-      hit !== document.body &&
       hit !== document.documentElement &&
       hit !== el &&
       !el.contains(hit) &&
-      !hit.contains(el) &&
       !isOverlayElement(hit)
     ) {
-      var hitChildren = draggableElementChildren(hit).filter(function(child) {
-        return child !== el;
-      });
-      if (hitChildren.length === 0) {
-        return { anchor: hit, placement: 'inside', axis: parentFlowAxis(hit) };
+      if (isContainerDropTarget(hit)) {
+        var containerRect = hit.getBoundingClientRect();
+        var edgeAxis = hit.parentElement ? parentFlowAxis(hit.parentElement) : parentFlowAxis(hit);
+        var edgePlacement = edgePlacementForRect(containerRect, edgeAxis, clientX, clientY);
+        if (!edgePlacement) {
+          return { anchor: hit, placement: 'inside', axis: parentFlowAxis(hit) };
+        }
+        return { anchor: hit, placement: edgePlacement, axis: edgeAxis };
       }
       var hitParent = hit.parentElement;
       if (hitParent) {
@@ -1503,6 +2375,7 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     insertionGuide.style.display = 'block';
     insertionGuide.style.background = 'var(--design-editor-accent-color)';
     insertionGuide.style.border = '0';
+    insertionGuide.style.borderRadius = '999px';
     insertionGuide.style.boxShadow = '0 0 0 1px var(--design-editor-accent-color)';
     if (target.placement === 'inside') {
       insertionGuide.style.left = rect.left + 'px';
@@ -1511,6 +2384,7 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
       insertionGuide.style.height = rect.height + 'px';
       insertionGuide.style.background = 'color-mix(in srgb, var(--design-editor-accent-color) 14%, transparent)';
       insertionGuide.style.border = '2px solid var(--design-editor-accent-color)';
+      insertionGuide.style.borderRadius = '4px';
       insertionGuide.style.boxShadow = 'none';
       return;
     }
@@ -1578,6 +2452,8 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     if (isLayerInteractionBlocked(selectedEl)) return;
     e.preventDefault();
     e.stopPropagation();
+    if (e.stopImmediatePropagation) e.stopImmediatePropagation();
+    var events = dragEventNames(e);
     var originalSelectedEl = selectedEl;
     var duplicatedForDrag = false;
     if (e.altKey && selectedEl !== document.body && selectedEl !== document.documentElement) {
@@ -1595,16 +2471,96 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
       var reorderEl = selectedEl;
       var currentTarget = reorderTargetForPoint(reorderEl, e.clientX, e.clientY);
       showInsertionGuideFor(currentTarget);
+      // Cross-screen drag state: true when the pointer is outside this iframe's
+      // viewport bounds.  The host frame renders the ghost + highlight and owns
+      // the drop when this is true; the bridge suppresses its in-iframe reorder.
+      var pointerOutsideIframe = false;
+      var reorderSelector = getSelector(reorderEl);
+      var reorderSourceId = getSourceId(reorderEl);
       function onReorderMove(ev) {
-        currentTarget = reorderTargetForPoint(reorderEl, ev.clientX, ev.clientY);
-        showInsertionGuideFor(currentTarget);
-        showTransformBadge(currentTarget ? 'Move layer' : 'Move', ev.clientX, ev.clientY);
+        var vw = window.innerWidth;
+        var vh = window.innerHeight;
+        var cx = ev.clientX;
+        var cy = ev.clientY;
+        var outside = cx < 0 || cy < 0 || cx > vw || cy > vh;
+        pointerOutsideIframe = outside;
+        // Always notify the host frame so it can track the cursor position,
+        // render the ghost, and highlight the target screen.
+        window.parent.postMessage({
+          type: 'agent-native:cross-screen-drag',
+          phase: 'move',
+          selector: reorderSelector,
+          sourceId: reorderSourceId,
+          iframeX: cx,
+          iframeY: cy,
+          viewportW: vw,
+          viewportH: vh,
+        }, '*');
+        if (outside) {
+          // Cursor left this iframe — hide the in-iframe insertion guide so
+          // it does not render while the host shows a cross-screen drop target.
+          hideInsertionGuide();
+          showTransformBadge('Move layer', cx, cy);
+        } else {
+          // Cursor is inside this iframe — use existing in-iframe behavior.
+          currentTarget = reorderTargetForPoint(reorderEl, cx, cy);
+          showInsertionGuideFor(currentTarget);
+          showTransformBadge(currentTarget ? 'Move layer' : 'Move', cx, cy);
+        }
+      }
+      function onReorderEscape() {
+        document.removeEventListener(events.move, onReorderMove, true);
+        document.removeEventListener(events.up, onReorderUp, true);
+        document.removeEventListener('keydown', onReorderKeyDown, true);
+        hideTransformBadge();
+        hideInsertionGuide();
+        window.parent.postMessage({ type: 'agent-native:cross-screen-drag', phase: 'cancel' }, '*');
+        // Revert any clone that was inserted for alt-drag.
+        if (duplicatedForDrag && reorderEl && reorderEl !== originalSelectedEl) {
+          if (reorderEl.parentElement) reorderEl.parentElement.removeChild(reorderEl);
+          selectedEl = originalSelectedEl;
+          positionOverlay(selectionOverlay, selectedEl);
+          window.parent.postMessage({ type: 'element-select', payload: getElementInfo(selectedEl) }, '*');
+        }
+      }
+      function onReorderKeyDown(ev) {
+        if (ev.key === 'Escape') {
+          ev.preventDefault();
+          ev.stopPropagation();
+          if (ev.stopImmediatePropagation) ev.stopImmediatePropagation();
+          onReorderEscape();
+        }
       }
-      function onReorderUp() {
-        document.removeEventListener('mousemove', onReorderMove, true);
-        document.removeEventListener('mouseup', onReorderUp, true);
+      function onReorderUp(ev) {
+        document.removeEventListener(events.move, onReorderMove, true);
+        document.removeEventListener(events.up, onReorderUp, true);
+        document.removeEventListener('keydown', onReorderKeyDown, true);
 	        hideTransformBadge();
 	        hideInsertionGuide();
+        var vw = window.innerWidth;
+        var vh = window.innerHeight;
+        var cx = ev ? ev.clientX : 0;
+        var cy = ev ? ev.clientY : 0;
+        var outsideOnDrop = cx < 0 || cy < 0 || cx > vw || cy > vh;
+        // Post the end message so the host can finalize a cross-screen drop.
+        window.parent.postMessage({
+          type: 'agent-native:cross-screen-drag',
+          phase: 'end',
+          selector: reorderSelector,
+          sourceId: reorderSourceId,
+          iframeX: cx,
+          iframeY: cy,
+          viewportW: vw,
+          viewportH: vh,
+        }, '*');
+        // When the pointer is outside this iframe at release, the host owns the
+        // move (cross-screen drop).  Do NOT apply the in-iframe reorder so we
+        // avoid a ghost element left in screen A's DOM.
+        // Use outsideOnDrop only — pointerOutsideIframe is stale when the user
+        // briefly exits the iframe and re-enters before releasing.  The host
+        // already clears cross-screen state on re-entry so checking the
+        // momentary excursion flag here would wrongly drop the element nowhere.
+        if (outsideOnDrop) return;
 	        if (!currentTarget) {
 	          // No valid drop target — clean up the clone if one was inserted so
 	          // no ghost element is left in the DOM.
@@ -1630,9 +2586,10 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
 	          applyRuntimeReorder(reorderEl, currentTarget);
 	          postVisualStructureChange(reorderEl, currentTarget, { prevParent: prevParent, prevNextSibling: prevNextSibling });
 	        }
-	      }
-      document.addEventListener('mousemove', onReorderMove, true);
-      document.addEventListener('mouseup', onReorderUp, true);
+      }
+      document.addEventListener(events.move, onReorderMove, true);
+      document.addEventListener(events.up, onReorderUp, true);
+      document.addEventListener('keydown', onReorderKeyDown, true);
       return;
     }
     ensurePositionable(selectedEl);
@@ -1659,8 +2616,8 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
       refreshOverlays();
     }
     function onUp() {
-      document.removeEventListener('mousemove', onMove, true);
-      document.removeEventListener('mouseup', onUp, true);
+      document.removeEventListener(events.move, onMove, true);
+      document.removeEventListener(events.up, onUp, true);
       hideTransformBadge();
       if (!dragEl) return;
       if (duplicatedForDrag && !moved) {
@@ -1686,8 +2643,8 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
         }, '*');
       }
     }
-    document.addEventListener('mousemove', onMove, true);
-    document.addEventListener('mouseup', onUp, true);
+    document.addEventListener(events.move, onMove, true);
+    document.addEventListener(events.up, onUp, true);
   }
 
   function startResize(handle, e) {
@@ -1864,7 +2821,68 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     document.addEventListener('mouseup', onUp, true);
   }
 
+  function clearPendingShieldDrag() {
+    if (!pendingShieldDrag) return;
+    document.removeEventListener(pendingShieldDrag.move, pendingShieldDrag.onMove, true);
+    document.removeEventListener(pendingShieldDrag.up, pendingShieldDrag.onUp, true);
+    pendingShieldDrag = null;
+  }
+
+  function beginPotentialShieldDrag(e) {
+    stopNativeInteraction(e);
+    if (e.button !== 0 || activeTextEditEl) return;
+    var events = dragEventNames(e);
+    var hit = elementFromEditorPoint(e.clientX, e.clientY);
+    if (!hit || hit === document.body || hit === document.documentElement) return;
+    var dragTarget =
+      selectedEl &&
+      document.documentElement.contains(selectedEl) &&
+      selectedEl.contains(hit)
+        ? selectedEl
+        : selectionTargetForHit(hit);
+    if (
+      !dragTarget ||
+      dragTarget === document.body ||
+      dragTarget === document.documentElement ||
+      isLayerInteractionBlocked(dragTarget)
+    ) {
+      return;
+    }
+    var startX = e.clientX;
+    var startY = e.clientY;
+    var didStartDrag = false;
+    function selectDragTarget() {
+      selectedEl = dragTarget;
+      positionOverlay(selectionOverlay, selectedEl);
+      window.parent.postMessage({ type: 'element-select', payload: getElementInfo(selectedEl) }, '*');
+    }
+    function onMove(ev) {
+      if (Math.hypot(ev.clientX - startX, ev.clientY - startY) <= 3) return;
+      clearPendingShieldDrag();
+      didStartDrag = true;
+      selectDragTarget();
+      suppressNextShieldClickBriefly();
+      startMove(ev);
+    }
+    function onUp(ev) {
+      clearPendingShieldDrag();
+      if (didStartDrag) return;
+      if (ev) stopNativeInteraction(ev);
+      selectDragTarget();
+      suppressNextShieldClickBriefly();
+    }
+    clearPendingShieldDrag();
+    pendingShieldDrag = { move: events.move, up: events.up, onMove: onMove, onUp: onUp };
+    document.addEventListener(events.move, onMove, true);
+    document.addEventListener(events.up, onUp, true);
+  }
+
   selectionOverlay.addEventListener('mousedown', function(e) {
+    var spacingKey = e.target && e.target.getAttribute && e.target.getAttribute('data-spacing-key');
+    if (spacingKey) {
+      startSpacingDrag(spacingKey, e);
+      return;
+    }
     var resizeHandle = e.target && e.target.getAttribute && e.target.getAttribute('data-agent-native-edit-handle');
     if (!resizeHandle && e.target && e.target.getAttribute) {
       resizeHandle = e.target.getAttribute('data-agent-native-edge-handle');
@@ -1881,6 +2899,8 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     startMove(e);
   }, true);
 
+  shieldOverlay.addEventListener('pointerdown', beginPotentialShieldDrag, true);
+
   ['pointerdown','pointerup','mousedown','mouseup','auxclick'].forEach(function(type) {
     shieldOverlay.addEventListener(type, stopNativeInteraction, true);
   });
@@ -2050,10 +3070,25 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
     hoveredEl = elementFromEditorPoint(e.clientX, e.clientY);
     if (!hoveredEl) {
       highlightOverlay.style.display = 'none';
+      if (!spacingDrag) {
+        selectedSpacingHovered = false;
+        hoveredSpacingHandleKey = '';
+        updateSpacingOverlay(selectedEl);
+      }
       hideMeasurements();
       return;
     }
     if (hoveredEl && hoveredEl.closest('[data-agent-native-text-editing]')) return;
+    if (!spacingDrag) {
+      selectedSpacingHovered = Boolean(
+        selectedEl &&
+          hoveredEl &&
+          (hoveredEl === selectedEl ||
+            (selectedEl.contains && selectedEl.contains(hoveredEl))),
+      );
+      if (!selectedSpacingHovered) hoveredSpacingHandleKey = '';
+      updateSpacingOverlay(selectedEl);
+    }
     if (hoveredEl === selectedEl) {
       highlightOverlay.style.display = 'none';
     } else {
@@ -2071,6 +3106,11 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
   shieldOverlay.addEventListener('pointerleave', function(e) {
     stopNativeInteraction(e);
     hoveredEl = null;
+    if (!spacingDrag) {
+      selectedSpacingHovered = false;
+      hoveredSpacingHandleKey = '';
+      updateSpacingOverlay(selectedEl);
+    }
     highlightOverlay.style.display = 'none';
     hideMeasurements();
     window.parent.postMessage({ type: 'element-hover', payload: null }, '*');
@@ -2130,6 +3170,8 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
         } catch (_err) {}
       }
       if (!target) return;
+      selectedSpacingHovered = false;
+      hoveredSpacingHandleKey = '';
       selectedEl = target;
       positionOverlay(selectionOverlay, target);
       if (hoveredEl === selectedEl) highlightOverlay.style.display = 'none';
@@ -2230,6 +3272,41 @@ const EDITOR_CHROME_BRIDGE_SCRIPT = `
 interface DesignCanvasProps {
   content: string;
   contentKey?: string;
+  /**
+   * The runtime source tier for this canvas.
+   *
+   * - `"inline"` (default) — HTML/Alpine `srcdoc` iframe; same-origin null
+   *   origin; all bridge scripts injected by DesignCanvas.
+   * - `"localhost"` — `src=devServerUrl`; dev server is same-origin in most
+   *   setups; bridge trust: origin must match parent or be "null".
+   * - `"fusion"` — `src=builderHostedUrl`; cross-origin Builder-hosted app;
+   *   bridge trust is relaxed to window-identity only (no origin check) so
+   *   the Builder-hosted iframe can communicate with the editor.  The sandbox
+   *   grants `allow-same-origin` so the Builder app can reach its own resources.
+   *
+   * When omitted, DesignCanvas infers the tier from the content value:
+   * a value that passes `getExternalPreviewUrl` is treated as `"localhost"`;
+   * otherwise `"inline"`.  Pass `sourceType="fusion"` explicitly when the
+   * content URL is a Builder-hosted (cross-origin) app so the bridge security
+   * model uses window-identity trust instead of same-origin trust.
+   */
+  sourceType?: "inline" | "localhost" | "fusion";
+  /**
+   * Explicit Builder-hosted app URL for fusion source rendering.
+   *
+   * When `sourceType === "fusion"` and this prop is provided, the iframe uses
+   * this URL as `src` regardless of what `content` contains.  This lets the
+   * caller hold the original inline HTML in `content` (for collab/history
+   * purposes) while pointing the canvas at the migrated Builder-hosted app.
+   *
+   * When absent and `sourceType === "fusion"`, the component falls back to
+   * the existing external-URL detection on `content` (i.e. if `content` is
+   * itself a URL it is used as-is, which is the pattern when the branch URL
+   * has been written into the design file content).
+   *
+   * For `"inline"` and `"localhost"` sources this prop is ignored.
+   */
+  fusionUrl?: string;
   zoom: number;
   onZoomChange?: (zoom: number) => void;
   deviceFrame: DeviceFrameType;
@@ -2322,6 +3399,55 @@ interface DesignCanvasProps {
    * opened in a new tab by the iframe itself and never reach this callback.
    */
   onPrototypeNavigate?: (screen: string, href: string) => void;
+  /**
+   * Motion tracks to load into the iframe's motion-preview bridge.  Sent via
+   * `motion-load-tracks` whenever this prop changes.  When cleared
+   * (`undefined` or `[]`) a `motion-preview-clear` message is sent to remove
+   * any applied preview overrides.
+   *
+   * The MotionDock sends scrub ticks as `{ type: 'motion-preview', t,
+   * durationMs }` directly from its `canvasIframeRef`.  DesignCanvas only
+   * needs the tracks so the bridge can interpolate values at each tick.
+   */
+  motionTracks?: MotionTrackWire[];
+  /**
+   * Explicit iframe width in pixels.  When provided it overrides the width
+   * derived from `deviceFrame`, enabling per-breakpoint preview (e.g. Mobile
+   * 390 / Tablet 768 / Desktop 1280 side-by-side frames in the overview).
+   * The height still comes from `deviceFrame`; `deviceFrame="none"` keeps
+   * 100% height.
+   */
+  previewWidthPx?: number;
+  /**
+   * Shader-fill CSS preview to apply to a selected element inside the iframe.
+   *
+   * When set, the canvas sends a `shader-fill-preview` bridge message that
+   * applies the CSS `background` value on the target element **without
+   * persisting anything**.  When cleared (`null` / `undefined`) a
+   * `shader-fill-preview-clear` message is sent to restore the original
+   * background.
+   *
+   * Preview-only — never writes to DB, Yjs, or source.  Part of the §6.7
+   * shader-fill PREVIEW path; the apply path remains gated until runtime
+   * rendering + source-write + diff proof are all in place.
+   */
+  shaderFillPreview?: {
+    /** CSS selector for the target element (preferred over nodeId). */
+    selector?: string;
+    /** data-agent-native-node-id value for the target element. */
+    nodeId?: string;
+    /** The CSS `background` value returned by preview-shader-fill. */
+    css: string;
+  } | null;
+  /**
+   * Called when the user clicks the component-instance source tag (the
+   * "ComponentName →" pill that floats above a selected component root).
+   * The parent should invoke `open-component-source` with these params.
+   */
+  onComponentSourceJump?: (params: {
+    nodeId: string;
+    componentName: string;
+  }) => void;
 }
 
 function getExternalPreviewUrl(content: string): string | null {
@@ -2357,6 +3483,8 @@ export interface IframeContextMenuPayload {
 export function DesignCanvas({
   content,
   contentKey,
+  sourceType,
+  fusionUrl,
   zoom,
   onZoomChange,
   deviceFrame,
@@ -2396,6 +3524,10 @@ export function DesignCanvas({
   commentContextId,
   commentContextLabel,
   onPrototypeNavigate,
+  motionTracks,
+  previewWidthPx,
+  onComponentSourceJump,
+  shaderFillPreview,
 }: DesignCanvasProps) {
   const t = useT();
   const iframeRef = useRef<HTMLIFrameElement>(null);
@@ -2406,10 +3538,25 @@ export function DesignCanvas({
   const [annotationPins, setAnnotationPins] = useState<CanvasPin[]>([]);
   const [pinSubmitSignal, setPinSubmitSignal] = useState(0);
   const isEmbeddedFrame = Boolean(embeddedFrame);
-  const externalPreviewUrl = useMemo(
-    () => getExternalPreviewUrl(renderedContent),
-    [renderedContent],
-  );
+  // Resolve the URL to render in the iframe:
+  // 1. When sourceType === "fusion" and fusionUrl is set, prefer the explicit
+  //    Builder-hosted URL over whatever is in `content` (which may still be the
+  //    original inline HTML).
+  // 2. Otherwise fall back to the content-based URL detection (handles the case
+  //    where the branch URL has been written into the design file content, or
+  //    where the localhost URL is the file content).
+  const externalPreviewUrl = useMemo(() => {
+    if (sourceType === "fusion" && fusionUrl) {
+      try {
+        const url = new URL(fusionUrl);
+        url.hash = "";
+        return url.toString();
+      } catch {
+        // fall through to content detection below
+      }
+    }
+    return getExternalPreviewUrl(renderedContent);
+  }, [fusionUrl, renderedContent, sourceType]);
   zoomRef.current = zoom;
 
   const queuedAnnotationPins = useMemo(
@@ -2462,6 +3609,8 @@ export function DesignCanvas({
       isEmbeddedFrame ? "true" : "false",
     );
     const bridgeToInject =
+      MOTION_PREVIEW_BRIDGE_SCRIPT +
+      SHADER_FILL_PREVIEW_BRIDGE_SCRIPT +
       TWEAK_BRIDGE_SCRIPT +
       ZOOM_BRIDGE_SCRIPT +
       NAV_BRIDGE_SCRIPT +
@@ -2492,14 +3641,27 @@ export function DesignCanvas({
   // Listen for messages from the iframe
   useEffect(() => {
     function handleMessage(e: MessageEvent) {
-      if (
-        !isTrustedCanvasBridgeMessage({
-          source: e.source,
-          origin: e.origin,
-          iframeWindow: iframeRef.current?.contentWindow,
-          parentOrigin: window.location.origin,
-        })
-      ) {
+      const iframeWindow = iframeRef.current?.contentWindow;
+      // For fusion sources the Builder-hosted app is cross-origin, so the strict
+      // `origin === parentOrigin` check can never match. We still require window
+      // identity (the message must come from our own iframe window, not any
+      // arbitrary cross-origin frame), AND we validate the message origin
+      // against a Builder-host allowlist (the configured fusionUrl origin or the
+      // *.builder.io family) before relaxing the origin check. If the origin is
+      // not on the allowlist we keep the strict check so a hostile frame that
+      // somehow shares our window reference still can't be trusted.
+      const trusted =
+        sourceType === "fusion"
+          ? iframeWindow != null &&
+            e.source === iframeWindow &&
+            isAllowedFusionOrigin(e.origin, fusionUrl)
+          : isTrustedCanvasBridgeMessage({
+              source: e.source,
+              origin: e.origin,
+              iframeWindow,
+              parentOrigin: window.location.origin,
+            });
+      if (!trusted) {
         return;
       }
       if (!e.data || !e.data.type) return;
@@ -2540,9 +3702,15 @@ export function DesignCanvas({
         const placement = String(e.data.placement || "after");
         const requestId =
           typeof e.data.requestId === "string" ? e.data.requestId : undefined;
+        const sourceId =
+          typeof e.data.sourceId === "string" ? e.data.sourceId : undefined;
+        const anchorSourceId =
+          typeof e.data.anchorSourceId === "string"
+            ? e.data.anchorSourceId
+            : undefined;
         if (
-          selector &&
-          anchorSelector &&
+          (selector || sourceId) &&
+          (anchorSelector || anchorSourceId) &&
           (placement === "before" ||
             placement === "after" ||
             placement === "inside")
@@ -2554,14 +3722,8 @@ export function DesignCanvas({
             e.data.payload,
             {
               requestId,
-              sourceId:
-                typeof e.data.sourceId === "string"
-                  ? e.data.sourceId
-                  : undefined,
-              anchorSourceId:
-                typeof e.data.anchorSourceId === "string"
-                  ? e.data.anchorSourceId
-                  : undefined,
+              sourceId,
+              anchorSourceId,
             },
           );
           if (requestId) {
@@ -2663,6 +3825,16 @@ export function DesignCanvas({
         );
         return;
       }
+      if (e.data.type === "component-source-jump") {
+        // The user clicked the component-instance tag ("ComponentName →").
+        // Relay to the parent so it can invoke open-component-source.
+        const nodeId = String(e.data.nodeId || "");
+        const componentName = String(e.data.componentName || "");
+        if (nodeId && componentName) {
+          onComponentSourceJump?.({ nodeId, componentName });
+        }
+        return;
+      }
       if (e.data.type === "embedded-canvas-wheel") {
         if (!isEmbeddedFrame) return;
         const iframe = iframeRef.current;
@@ -2748,7 +3920,10 @@ export function DesignCanvas({
     onZoomChange,
     deviceFrame,
     onPrototypeNavigate,
+    onComponentSourceJump,
     isEmbeddedFrame,
+    sourceType,
+    fusionUrl,
   ]);
 
   const replayIframeEditorState = useCallback(() => {
@@ -2786,14 +3961,43 @@ export function DesignCanvas({
         : { type: "hover-element", selector: "", selectorCandidates: [] },
       "*",
     );
+    // Re-send motion tracks so the preview bridge is ready after a reload.
+    if (motionTracks && motionTracks.length > 0) {
+      iframe.contentWindow?.postMessage(
+        { type: "motion-load-tracks", tracks: motionTracks },
+        "*",
+      );
+    } else {
+      iframe.contentWindow?.postMessage({ type: "motion-preview-clear" }, "*");
+    }
+    // Re-apply the shader-fill preview after a reload so the preview survives
+    // screen switches.  Preview-only — never writes to DB, Yjs, or source.
+    if (shaderFillPreview) {
+      iframe.contentWindow?.postMessage(
+        {
+          type: "shader-fill-preview",
+          selector: shaderFillPreview.selector ?? "",
+          nodeId: shaderFillPreview.nodeId ?? "",
+          css: shaderFillPreview.css,
+        },
+        "*",
+      );
+    } else {
+      iframe.contentWindow?.postMessage(
+        { type: "shader-fill-preview-clear" },
+        "*",
+      );
+    }
   }, [
     hoveredSelector,
     hoveredSelectorCandidates,
     hiddenSelectors,
     lockedSelectors,
+    motionTracks,
     scaleMode,
     selectedSelector,
     selectedSelectorCandidates,
+    shaderFillPreview,
     tweakValues,
   ]);
 
@@ -2816,6 +4020,44 @@ export function DesignCanvas({
     );
   }, [clearSelectionRequest]);
 
+  // Sync motion tracks to the iframe bridge whenever they change.
+  // When motionTracks is empty/undefined, clear any preview overrides so the
+  // design returns to its authored state (no stale inline styles).
+  useEffect(() => {
+    const win = iframeRef.current?.contentWindow;
+    if (!win) return;
+    if (!motionTracks || motionTracks.length === 0) {
+      win.postMessage({ type: "motion-preview-clear" }, "*");
+    } else {
+      win.postMessage(
+        { type: "motion-load-tracks", tracks: motionTracks },
+        "*",
+      );
+    }
+  }, [motionTracks]);
+
+  // Sync shader-fill preview to the iframe whenever the prop changes.
+  // When cleared (null / undefined) send a clear message so the bridge
+  // restores the original background on the previously-patched element.
+  // Preview-only — never writes to DB, Yjs, or source.
+  useEffect(() => {
+    const win = iframeRef.current?.contentWindow;
+    if (!win) return;
+    if (!shaderFillPreview) {
+      win.postMessage({ type: "shader-fill-preview-clear" }, "*");
+    } else {
+      win.postMessage(
+        {
+          type: "shader-fill-preview",
+          selector: shaderFillPreview.selector ?? "",
+          nodeId: shaderFillPreview.nodeId ?? "",
+          css: shaderFillPreview.css,
+        },
+        "*",
+      );
+    }
+  }, [shaderFillPreview]);
+
   // Push the constant-size chrome scale into the iframe LIVE (CSS vars only) when
   // overview zoom settles. This is intentionally separate from the srcdoc build so
   // a scale change never rebuilds srcdoc / reloads the iframe (which flashes the
@@ -2843,6 +4085,61 @@ export function DesignCanvas({
     [],
   );
 
+  /**
+   * Send a motion-preview scrub tick to the iframe.  `t` is the normalised
+   * playhead position in [0, 1].  Tracks must have been loaded first via the
+   * `motionTracks` prop (or an explicit `motion-load-tracks` message).
+   * Preview-only — never writes to DB/Yjs/source.
+   */
+  const sendMotionPreview = useCallback((t: number, durationMs?: number) => {
+    const iframe = iframeRef.current;
+    if (!iframe?.contentWindow) return;
+    iframe.contentWindow.postMessage(
+      { type: "motion-preview", t: Math.max(0, Math.min(1, t)), durationMs },
+      "*",
+    );
+  }, []);
+
+  /**
+   * Clear all motion-preview inline-style overrides in the iframe and remove
+   * the in-memory track list.  Call when the Motion dock is closed.
+   */
+  const clearMotionPreview = useCallback(() => {
+    iframeRef.current?.contentWindow?.postMessage(
+      { type: "motion-preview-clear" },
+      "*",
+    );
+  }, []);
+
+  /**
+   * Send a shader-fill CSS preview to the iframe.  Targets the element
+   * identified by `selector` (preferred) or `nodeId`.  Preview-only — the
+   * bridge script restores the original background on clear.
+   */
+  const sendShaderFillPreview = useCallback(
+    (selector: string, nodeId: string, css: string) => {
+      const win = iframeRef.current?.contentWindow;
+      if (!win) return;
+      win.postMessage(
+        { type: "shader-fill-preview", selector, nodeId, css },
+        "*",
+      );
+    },
+    [],
+  );
+
+  /**
+   * Clear the shader-fill preview in the iframe, restoring the original
+   * background on the patched element.  Call when the preview is dismissed
+   * or when the selection changes to a different element.
+   */
+  const clearShaderFillPreview = useCallback(() => {
+    iframeRef.current?.contentWindow?.postMessage(
+      { type: "shader-fill-preview-clear" },
+      "*",
+    );
+  }, []);
+
   const replacePreviewContent = useCallback(
     (nextContent: string, selector?: string | null, candidates?: string[]) => {
       const iframe = iframeRef.current;
@@ -2884,7 +4181,15 @@ export function DesignCanvas({
     (window as any).__designCanvasSendStyle = sendStyleChange;
     (window as any).__designCanvasReplaceContent = replacePreviewContent;
     (window as any).__designCanvasDeleteElement = deleteRuntimeElement;
+    (window as any).__designCanvasSendMotionPreview = sendMotionPreview;
+    (window as any).__designCanvasClearMotionPreview = clearMotionPreview;
+    // Shader-fill preview helpers (preview-only, §6.7 gating applies to apply).
+    (window as any).__designCanvasSendShaderFillPreview = sendShaderFillPreview;
+    (window as any).__designCanvasClearShaderFillPreview =
+      clearShaderFillPreview;
     return () => {
+      // Identity-guard each delete so a stale unmounting instance never clobbers
+      // a freshly mounted instance's bridge during a remount race.
       if ((window as any).__designCanvasSendStyle === sendStyleChange) {
         delete (window as any).__designCanvasSendStyle;
       }
@@ -2898,12 +4203,38 @@ export function DesignCanvas({
       ) {
         delete (window as any).__designCanvasDeleteElement;
       }
+      if (
+        (window as any).__designCanvasSendMotionPreview === sendMotionPreview
+      ) {
+        delete (window as any).__designCanvasSendMotionPreview;
+      }
+      if (
+        (window as any).__designCanvasClearMotionPreview === clearMotionPreview
+      ) {
+        delete (window as any).__designCanvasClearMotionPreview;
+      }
+      if (
+        (window as any).__designCanvasSendShaderFillPreview ===
+        sendShaderFillPreview
+      ) {
+        delete (window as any).__designCanvasSendShaderFillPreview;
+      }
+      if (
+        (window as any).__designCanvasClearShaderFillPreview ===
+        clearShaderFillPreview
+      ) {
+        delete (window as any).__designCanvasClearShaderFillPreview;
+      }
     };
   }, [
     deleteRuntimeElement,
     registerRuntimeBridge,
     replacePreviewContent,
     sendStyleChange,
+    sendMotionPreview,
+    clearMotionPreview,
+    sendShaderFillPreview,
+    clearShaderFillPreview,
   ]);
 
   // Device dimensions match real-world devices. iframes are replaced elements
@@ -2923,6 +4254,12 @@ export function DesignCanvas({
     deviceDimensions[deviceFrame];
   const embeddedFrameFluid = embeddedFrame?.fluid === true;
 
+  // Per-breakpoint override: when previewWidthPx is set it takes priority over
+  // the deviceFrame width so the caller can render the same source at an
+  // explicit viewport width (e.g. 390 / 768 / 1280 side-by-side breakpoints).
+  const resolvedWidth =
+    previewWidthPx != null ? `${previewWidthPx}px` : iframeWidth;
+
   // Wrap the iframe in a positioned container so DrawOverlay /
   // CanvasCommentPins can absolutely-position themselves on top of the
   // iframe. The pin component anchors to `.design-canvas-iframe-wrapper`
@@ -2938,7 +4275,7 @@ export function DesignCanvas({
           ? embeddedFrameFluid
             ? "100%"
             : embeddedFrame.viewportWidth
-          : iframeWidth,
+          : resolvedWidth,
         height: embeddedFrame
           ? embeddedFrameFluid
             ? "100%"
@@ -2958,6 +4295,12 @@ export function DesignCanvas({
             : "allow-scripts allow-popups allow-popups-to-escape-sandbox allow-same-origin"
         }
         data-design-preview-iframe
+        data-design-source-type={
+          sourceType ??
+          (externalPreviewUrl
+            ? "localhost" // inferred — content is a URL
+            : "inline")
+        }
         className="block h-full w-full border-0 bg-transparent"
         title={t("designEditor.designPreview")}
       />