@ashraf_mizo/htmlcanvas 1.0.0

package/editor/manipulation.js

@@ -0,0 +1,864 @@
+// editor/manipulation.js — Custom drag/resize/rotate engine
+//
+// Architecture:
+//   - Drag uses transform: translate(dx, dy) — no reflow
+//   - Resize uses transform: scale() DURING the gesture (no reflow at all),
+//     then applies final width/height on pointerup (single reflow)
+//   - Rotate uses transform: rotate(deg) — no reflow
+//   - All transforms are combined in a single transform property
+//   - Commands store full before/after snapshots for clean undo
+//
+// Why scale-during-resize?
+//   In flex/grid layouts, changing width/height on one child causes all siblings
+//   to reflow. By using transform: scale() during the drag, the element's layout
+//   size stays unchanged — siblings don't move. The actual width/height is only
+//   set once on release, producing a single clean reflow.
+//
+// Exports:
+//   initManipulation(iframe, iframeDoc, canvasArea)
+//   writeStyleDelta(element, props)
+
+import { push } from './history.js';
+import { recordChange } from './serializer.js';
+import { hasVarReference } from './cssVars.js';
+import { getZoom } from './zoom.js';
+import { getElementCanvasRect } from './coords.js';
+import { isMultiSelectActive, getSelectedElements, getSelectedHcIds } from './multiSelect.js';
+
+// ── Module state ──────────────────────────────────────────────────────────────
+
+let _iframe     = null;
+let _iframeDoc  = null;
+let _canvasArea = null;
+
+let _targetElement = null;
+let _targetHcId    = null;
+
+// ── DOM refs ────────────────────────────────────────────────────────────────
+
+const selectionOverlay = document.getElementById('selection-overlay');
+const dragSurface      = selectionOverlay.querySelector('.sel-drag-surface');
+const handles          = selectionOverlay.querySelectorAll('.sel-handle');
+const dimLabel         = selectionOverlay.querySelector('.sel-dim-label');
+
+// ── writeStyleDelta ───────────────────────────────────────────────────────────
+
+/**
+ * Writes only the specified CSS properties to the element's inline style.
+ * Skips any property whose current value contains a var() reference.
+ */
+export function writeStyleDelta(element, props) {
+  for (const [prop, value] of Object.entries(props)) {
+    const existing = element.style.getPropertyValue(prop);
+    if (hasVarReference(existing)) {
+      console.warn(`writeStyleDelta: skipping "${prop}" — contains var() reference: ${existing}`);
+      continue;
+    }
+    element.style.setProperty(prop, value);
+  }
+}
+
+// ── Transform helpers ───────────────────────────────────────────────────────
+
+/**
+ * Parses the current translate(x, y) from an element's inline transform.
+ * Returns {x: 0, y: 0} if no translate is present.
+ */
+function parseTranslate(element) {
+  const t = element.style.transform || '';
+  const m = t.match(/translate\(\s*(-?[\d.]+)px\s*,\s*(-?[\d.]+)px\s*\)/);
+  return m ? { x: parseFloat(m[1]), y: parseFloat(m[2]) } : { x: 0, y: 0 };
+}
+
+/**
+ * Parses the current rotate(deg) from an element's inline transform.
+ */
+function parseRotation(element) {
+  const t = element.style.transform || '';
+  const m = t.match(/rotate\(\s*(-?[\d.]+)deg\s*\)/);
+  return m ? parseFloat(m[1]) : 0;
+}
+
+/**
+ * Parses the current scale(sx, sy) from an element's inline transform.
+ */
+function parseScale(element) {
+  const t = element.style.transform || '';
+  // Match scale(sx, sy) or scale(s)
+  const m2 = t.match(/scale\(\s*(-?[\d.]+)\s*,\s*(-?[\d.]+)\s*\)/);
+  if (m2) return { x: parseFloat(m2[1]), y: parseFloat(m2[2]) };
+  const m1 = t.match(/scale\(\s*(-?[\d.]+)\s*\)/);
+  if (m1) return { x: parseFloat(m1[1]), y: parseFloat(m1[1]) };
+  return { x: 1, y: 1 };
+}
+
+/**
+ * Writes a combined transform string preserving any transforms we don't manage.
+ * Managed functions: translate, rotate, scale
+ */
+function setTransform(element, translate, rotateDeg, scale) {
+  let t = element.style.transform || '';
+
+  // Strip our managed functions
+  t = t.replace(/translate\([^)]*\)/g, '')
+       .replace(/rotate\([^)]*\)/g, '')
+       .replace(/scale\([^)]*\)/g, '')
+       .trim();
+
+  const parts = [];
+  if (translate && (translate.x !== 0 || translate.y !== 0)) {
+    parts.push(`translate(${translate.x}px, ${translate.y}px)`);
+  }
+  if (rotateDeg !== 0) {
+    parts.push(`rotate(${rotateDeg}deg)`);
+  }
+  if (scale && (scale.x !== 1 || scale.y !== 1)) {
+    parts.push(`scale(${scale.x}, ${scale.y})`);
+  }
+  if (t) parts.push(t);
+
+  const val = parts.join(' ');
+  if (val) {
+    element.style.transform = val;
+  } else {
+    element.style.removeProperty('transform');
+  }
+}
+
+// ── Layout dimension helpers ─────────────────────────────────────────────────
+// offsetWidth/offsetHeight don't exist on SVG elements. These helpers
+// fall back to the SVG's width/height attributes or getBBox().
+
+function getLayoutWidth(el) {
+  if (el.offsetWidth != null && el.offsetWidth > 0) return el.offsetWidth;
+  // SVG: try width attribute first, then getBBox
+  if (el.tagName && el.tagName.toLowerCase() === 'svg') {
+    const attr = parseFloat(el.getAttribute('width'));
+    if (attr > 0) return attr;
+    if (el.getBBox) { try { return el.getBBox().width; } catch { /* */ } }
+  }
+  // Final fallback: getBoundingClientRect (includes transforms, but better than 0)
+  return el.getBoundingClientRect().width || 1;
+}
+
+function getLayoutHeight(el) {
+  if (el.offsetHeight != null && el.offsetHeight > 0) return el.offsetHeight;
+  if (el.tagName && el.tagName.toLowerCase() === 'svg') {
+    const attr = parseFloat(el.getAttribute('height'));
+    if (attr > 0) return attr;
+    if (el.getBBox) { try { return el.getBBox().height; } catch { /* */ } }
+  }
+  return el.getBoundingClientRect().height || 1;
+}
+
+// ── Snapshot / restore ──────────────────────────────────────────────────────
+// Every command captures the exact inline style before and after.
+// Undo/redo simply restores the snapshot — no side effects, no sibling mutation.
+
+function snapshotStyle(element) {
+  return {
+    transform:       element.style.transform || '',
+    transformOrigin: element.style.transformOrigin || '',
+    width:           element.style.width || '',
+    height:          element.style.height || '',
+  };
+}
+
+function restoreStyle(element, snapshot) {
+  if (snapshot.transform) {
+    element.style.transform = snapshot.transform;
+  } else {
+    element.style.removeProperty('transform');
+  }
+  if (snapshot.transformOrigin) {
+    element.style.transformOrigin = snapshot.transformOrigin;
+  } else {
+    element.style.removeProperty('transform-origin');
+  }
+  if (snapshot.width) {
+    element.style.width = snapshot.width;
+  } else {
+    element.style.removeProperty('width');
+  }
+  if (snapshot.height) {
+    element.style.height = snapshot.height;
+  } else {
+    element.style.removeProperty('height');
+  }
+}
+
+/**
+ * Creates a command from before/after snapshots. Used by all three gesture types.
+ */
+function makeStyleCommand(description, element, hcId, before, after) {
+  return {
+    description,
+    execute() {
+      restoreStyle(element, after);
+      recordChange(hcId, element.outerHTML);
+    },
+    undo() {
+      restoreStyle(element, before);
+      recordChange(hcId, element.outerHTML);
+    }
+  };
+}
+
+
+// ── Overlay sync ────────────────────────────────────────────────────────────
+
+/**
+ * Refocuses after a manipulation so keyboard shortcuts (Ctrl+Z) work.
+ * Overlay handles are in the parent document, so after interacting with them
+ * the iframe loses focus. We need to return it so the keydown relay fires.
+ */
+function refocusAfterManipulation() {
+  // Focus the iframe so the iframe's keydown handler picks up shortcuts.
+  // Fall back to parent body if the iframe isn't available.
+  if (_iframe) {
+    try { _iframe.contentWindow.focus(); } catch { /* */ }
+  }
+}
+
+function syncOverlay() {
+  if (!_targetElement || !_iframe || !_canvasArea) return;
+
+  // getBoundingClientRect already accounts for transforms (including scale),
+  // so the rect includes the visual scaled size. getElementCanvasRect uses
+  // this, so the overlay naturally tracks the scaled bounds.
+  const rect = getElementCanvasRect(_targetElement, _iframe, _canvasArea);
+  selectionOverlay.style.left   = rect.x + 'px';
+  selectionOverlay.style.top    = rect.y + 'px';
+  selectionOverlay.style.width  = rect.width + 'px';
+  selectionOverlay.style.height = rect.height + 'px';
+  selectionOverlay.style.display = '';
+
+  const naturalRect = _targetElement.getBoundingClientRect();
+  dimLabel.textContent = `${Math.round(naturalRect.width)}x${Math.round(naturalRect.height)} px`;
+}
+
+// ── DRAG handler ────────────────────────────────────────────────────────────
+// Uses transform: translate(dx, dy) so the element stays in document flow.
+// Nothing else on the page is affected.
+
+function setupDragHandler() {
+  let dragging = false;
+  let startClientX, startClientY;
+  let startTranslate, startRotation, startScale;
+  let beforeSnapshot = null;
+
+  // Multi-drag state
+  let _multiDrag = false;
+  let _multiStartData = []; // { el, hcId, startTranslate, startRotation, startScale, before }
+
+  dragSurface.addEventListener('pointerdown', (e) => {
+    if (!_targetElement || !_iframeDoc) return;
+    e.preventDefault();
+    e.stopPropagation();
+
+    startClientX = e.clientX;
+    startClientY = e.clientY;
+
+    // Check if multi-selection is active
+    if (isMultiSelectActive()) {
+      _multiDrag = true;
+      const elements = getSelectedElements();
+      const hcIds = getSelectedHcIds();
+      _multiStartData = elements.map((el, i) => ({
+        el,
+        hcId: hcIds[i] || el.getAttribute('data-hc-id'),
+        startTranslate: parseTranslate(el),
+        startRotation: parseRotation(el),
+        startScale: parseScale(el),
+        before: snapshotStyle(el),
+      }));
+      // Also snapshot the primary target for overlay sync
+      startTranslate = parseTranslate(_targetElement);
+      startRotation  = parseRotation(_targetElement);
+      startScale     = parseScale(_targetElement);
+      beforeSnapshot = snapshotStyle(_targetElement);
+    } else {
+      _multiDrag = false;
+      _multiStartData = [];
+      startTranslate = parseTranslate(_targetElement);
+      startRotation  = parseRotation(_targetElement);
+      startScale     = parseScale(_targetElement);
+      beforeSnapshot = snapshotStyle(_targetElement);
+    }
+
+    dragging = true;
+    dragSurface.setPointerCapture(e.pointerId);
+    document.body.style.cursor = 'move';
+  });
+
+  dragSurface.addEventListener('pointermove', (e) => {
+    if (!dragging) return;
+    e.preventDefault();
+
+    const scale = getZoom();
+    const dx = (e.clientX - startClientX) / scale;
+    const dy = (e.clientY - startClientY) / scale;
+
+    if (Math.abs(dx) < 1 && Math.abs(dy) < 1) return;
+
+    if (_multiDrag) {
+      // Move ALL selected elements by the same delta
+      for (const data of _multiStartData) {
+        setTransform(data.el, {
+          x: data.startTranslate.x + dx,
+          y: data.startTranslate.y + dy,
+        }, data.startRotation, data.startScale);
+      }
+    } else {
+      setTransform(_targetElement, {
+        x: startTranslate.x + dx,
+        y: startTranslate.y + dy,
+      }, startRotation, startScale);
+    }
+
+    syncOverlay();
+
+    // Update multi-selection overlay too
+    if (_multiDrag) {
+      window.dispatchEvent(new CustomEvent('hc:multi-selection-changed', {
+        detail: { elements: getSelectedElements(), hcIds: getSelectedHcIds() }
+      }));
+    }
+  });
+
+  const endDrag = (e) => {
+    if (!dragging) return;
+    dragging = false;
+    document.body.style.cursor = '';
+    dragSurface.releasePointerCapture(e.pointerId);
+    refocusAfterManipulation();
+
+    if (_multiDrag && _multiStartData.length > 0) {
+      // Check if any element actually moved
+      const firstAfter = snapshotStyle(_multiStartData[0].el);
+      if (firstAfter.transform === _multiStartData[0].before.transform) {
+        _multiStartData = [];
+        _multiDrag = false;
+        beforeSnapshot = null;
+        window.dispatchEvent(new CustomEvent('hc:drag-surface-click', {
+          detail: { clientX: e.clientX, clientY: e.clientY }
+        }));
+        return;
+      }
+
+      // Create a compound undo command for all elements
+      const snapshots = _multiStartData.map(data => ({
+        el: data.el,
+        hcId: data.hcId,
+        before: data.before,
+        after: snapshotStyle(data.el),
+      }));
+
+      const cmd = {
+        description: `Move ${snapshots.length} elements`,
+        execute() {
+          for (const s of snapshots) {
+            restoreStyle(s.el, s.after);
+            recordChange(s.hcId, s.el.outerHTML);
+          }
+        },
+        undo() {
+          for (const s of snapshots) {
+            restoreStyle(s.el, s.before);
+            recordChange(s.hcId, s.el.outerHTML);
+          }
+        }
+      };
+      push(cmd);
+      syncOverlay();
+      _multiStartData = [];
+      _multiDrag = false;
+      beforeSnapshot = null;
+      return;
+    }
+
+    if (!beforeSnapshot || !_targetElement) return;
+
+    const afterSnapshot = snapshotStyle(_targetElement);
+
+    // No change — it was a click, not a drag. Dispatch event for text editing.
+    if (afterSnapshot.transform === beforeSnapshot.transform) {
+      beforeSnapshot = null;
+      window.dispatchEvent(new CustomEvent('hc:drag-surface-click', {
+        detail: { clientX: e.clientX, clientY: e.clientY }
+      }));
+      return;
+    }
+
+    const cmd = makeStyleCommand('Move element', _targetElement, _targetHcId, beforeSnapshot, afterSnapshot);
+    push(cmd);
+    syncOverlay();
+    beforeSnapshot = null;
+  };
+
+  dragSurface.addEventListener('pointerup', endDrag);
+  dragSurface.addEventListener('pointercancel', endDrag);
+}
+
+// ── RESIZE handler ──────────────────────────────────────────────────────────
+// During the gesture: uses transform: scale() to visually resize. This causes
+// ZERO reflow — siblings don't move at all.
+// On release: removes scale, applies final width/height (single reflow).
+// For left/top handles: adjusts translate to keep the opposite edge pinned.
+
+function setupResizeHandlers() {
+  for (const handle of handles) {
+    const pos = handle.getAttribute('data-pos');
+
+    const cursors = {
+      tl: 'nwse-resize', tr: 'nesw-resize', bl: 'nesw-resize', br: 'nwse-resize',
+      tm: 'ns-resize',   bm: 'ns-resize',   ml: 'ew-resize',   mr: 'ew-resize',
+    };
+    handle.style.cursor = cursors[pos] || 'default';
+
+    let resizing = false;
+    let startX, startY;
+    let startWidth, startHeight;  // visual (scaled) dimensions at gesture start
+    let layoutW, layoutH;         // layout (unscaled) dimensions — for computing absolute scale
+    let startTranslate, startRotation;
+    let initialAspect = 1;
+    let beforeSnapshot = null;
+    let currentScaleX = 1, currentScaleY = 1;
+    let originApplied = false;
+
+    handle.addEventListener('pointerdown', (e) => {
+      if (!_targetElement || !_iframeDoc) return;
+      e.preventDefault();
+      e.stopPropagation();
+
+      beforeSnapshot = snapshotStyle(_targetElement);
+      startTranslate = parseTranslate(_targetElement);
+      startRotation  = parseRotation(_targetElement);
+
+      // Account for any existing scale from a previous resize.
+      // offsetWidth/offsetHeight return the LAYOUT size (ignoring scale transform).
+      // SVG elements don't have offsetWidth/offsetHeight — use their attributes or BBox.
+      const existingScale = parseScale(_targetElement);
+      layoutW = getLayoutWidth(_targetElement);
+      layoutH = getLayoutHeight(_targetElement);
+      startWidth  = layoutW * existingScale.x;
+      startHeight = layoutH * existingScale.y;
+      initialAspect = startWidth / (startHeight || 1);
+
+      startX = e.clientX;
+      startY = e.clientY;
+      resizing = true;
+      originApplied = false;   // defer transform-origin until first move
+      currentScaleX = 1;
+      currentScaleY = 1;
+      handle.setPointerCapture(e.pointerId);
+      document.body.style.cursor = cursors[pos];
+    });
+
+    handle.addEventListener('pointermove', (e) => {
+      if (!resizing) return;
+      e.preventDefault();
+
+      // On the first move: set transform-origin and compensate translate so the
+      // element doesn't visually shift. Both happen in the same frame, so there's
+      // no visible jump — the origin change is cancelled by the translate adjustment
+      // before the browser paints.
+      if (!originApplied) {
+        const origins = {
+          tl: 'bottom right', tr: 'bottom left', bl: 'top right', br: 'top left',
+          tm: 'bottom center', bm: 'top center', ml: 'center right', mr: 'center left',
+        };
+        const rectBefore = _targetElement.getBoundingClientRect();
+        _targetElement.style.transformOrigin = origins[pos] || 'center center';
+        const rectAfter = _targetElement.getBoundingClientRect();
+
+        // Compensate translate to cancel the visual shift from the origin change
+        const shiftX = rectBefore.left - rectAfter.left;
+        const shiftY = rectBefore.top  - rectAfter.top;
+        if (shiftX !== 0 || shiftY !== 0) {
+          startTranslate = {
+            x: startTranslate.x + shiftX,
+            y: startTranslate.y + shiftY,
+          };
+        }
+        originApplied = true;
+      }
+
+      const zoom = getZoom();
+      let dx = (e.clientX - startX) / zoom;
+      let dy = (e.clientY - startY) / zoom;
+
+      // Compute target width/height
+      let targetW = startWidth;
+      let targetH = startHeight;
+
+      if (pos.includes('r')) { targetW += dx; }
+      if (pos.includes('l')) { targetW -= dx; }
+      if (pos.includes('b')) { targetH += dy; }
+      if (pos.includes('t')) { targetH -= dy; }
+
+      // Enforce minimum
+      targetW = Math.max(targetW, 10);
+      targetH = Math.max(targetH, 10);
+
+      // Shift = keep aspect ratio
+      if (e.shiftKey && initialAspect) {
+        if (pos === 'tm' || pos === 'bm') {
+          targetW = targetH * initialAspect;
+        } else if (pos === 'ml' || pos === 'mr') {
+          targetH = targetW / initialAspect;
+        } else {
+          targetH = targetW / initialAspect;
+        }
+      }
+
+      // Compute scale factors relative to LAYOUT size (since setTransform
+      // replaces the entire scale, not composes with existing scale)
+      currentScaleX = targetW / layoutW;
+      currentScaleY = targetH / layoutH;
+
+      // Apply scale transform (no reflow!)
+      setTransform(_targetElement, startTranslate, startRotation,
+        { x: currentScaleX, y: currentScaleY });
+
+      // getBoundingClientRect includes transform:scale, so syncOverlay works
+      syncOverlay();
+    });
+
+    const endResize = (e) => {
+      if (!resizing) return;
+      resizing = false;
+      document.body.style.cursor = '';
+      handle.releasePointerCapture(e.pointerId);
+      refocusAfterManipulation();
+
+      if (!beforeSnapshot || !_targetElement) return;
+
+      // Keep the scale transform permanently — do NOT convert to width/height.
+      // This prevents sibling reflow entirely. The scale is converted to actual
+      // dimensions only when serializing for save (see recordChange below).
+      //
+      // The transform already has the correct scale from the last pointermove.
+      // We just need to snapshot it and record the change.
+
+      const afterSnapshot = snapshotStyle(_targetElement);
+
+      if (afterSnapshot.transform === beforeSnapshot.transform) {
+        beforeSnapshot = null;
+        return;
+      }
+
+      // Capture references by value — the outer-scope variables get nulled/reused
+      // after endResize, so the command closure must have its own copies.
+      const el = _targetElement;
+      const hcId = _targetHcId;
+      const savedBefore = beforeSnapshot;
+      const savedStartTranslate = { ...startTranslate };
+
+      const finalWidth  = Math.round(layoutW * currentScaleX);
+      const finalHeight = Math.round(layoutH * currentScaleY);
+      const isSvg = el.tagName && el.tagName.toLowerCase() === 'svg';
+
+      if (isSvg) {
+        // SVG path: convert scale → attributes, restore scale for live display
+        setTransform(el, startTranslate, startRotation, { x: 1, y: 1 });
+        el.setAttribute('width', finalWidth);
+        el.setAttribute('height', finalHeight);
+        el.style.transformOrigin = '';
+      } else {
+        // Non-SVG path: convert scale → width/height so border/border-radius
+        // render at exact pixel size with no distortion.
+        //
+        // Problem: the translate was calibrated for scale+transformOrigin, not
+        // for a pixel-sized element. Capture the visual rect NOW (while scale is
+        // still active) so we can re-derive the correct translate after committing
+        // to explicit dimensions.
+        const visualRect = el.getBoundingClientRect();
+
+        setTransform(el, startTranslate, startRotation, { x: 1, y: 1 });
+        el.style.width  = finalWidth + 'px';
+        el.style.height = finalHeight + 'px';
+        el.style.transformOrigin = '';
+
+        // After setting final dimensions the element sits at startTranslate but
+        // may be in the wrong position (scale+origin was doing the placement work).
+        // Measure the drift and fold it into the translate.
+        const newRect = el.getBoundingClientRect();
+        const driftX = visualRect.left - newRect.left;
+        const driftY = visualRect.top  - newRect.top;
+        if (Math.abs(driftX) > 0.5 || Math.abs(driftY) > 0.5) {
+          setTransform(el, { x: startTranslate.x + driftX, y: startTranslate.y + driftY },
+            startRotation, { x: 1, y: 1 });
+        }
+      }
+
+      const cleanHTML = el.outerHTML;
+      const finalSnapshot = isSvg ? null : snapshotStyle(el);
+
+      // SVG only: restore original attributes and scale transform for live display
+      if (isSvg) {
+        el.setAttribute('width', layoutW);
+        el.setAttribute('height', layoutH);
+        restoreStyle(el, afterSnapshot);
+      }
+
+      // Capture original SVG attrs for undo
+      const origSvgW = isSvg ? layoutW : null;
+      const origSvgH = isSvg ? layoutH : null;
+
+      const cmd = {
+        description: 'Resize element',
+        execute() {
+          if (isSvg) {
+            restoreStyle(el, afterSnapshot);
+          } else {
+            restoreStyle(el, finalSnapshot);
+          }
+          recordChange(hcId, cleanHTML);
+        },
+        undo() {
+          restoreStyle(el, savedBefore);
+          // Capture clean HTML for undo serialization too
+          setTransform(el, savedStartTranslate, startRotation, { x: 1, y: 1 });
+          if (isSvg) {
+            el.setAttribute('width', origSvgW);
+            el.setAttribute('height', origSvgH);
+          } else {
+            el.style.width = savedBefore.width || '';
+            el.style.height = savedBefore.height || '';
+          }
+          el.style.transformOrigin = '';
+          const undoHTML = el.outerHTML;
+          restoreStyle(el, savedBefore);
+          if (isSvg) {
+            el.setAttribute('width', origSvgW);
+            el.setAttribute('height', origSvgH);
+          }
+          recordChange(hcId, undoHTML);
+        }
+      };
+      push(cmd);
+      syncOverlay();
+      beforeSnapshot = null;
+    };
+
+    handle.addEventListener('pointerup', endResize);
+    handle.addEventListener('pointercancel', endResize);
+  }
+}
+
+// ── ROTATE handler ──────────────────────────────────────────────────────────
+
+function setupRotateHandler() {
+  let rotateHandle = selectionOverlay.querySelector('.sel-rotate-handle');
+  if (!rotateHandle) {
+    rotateHandle = document.createElement('div');
+    rotateHandle.className = 'sel-rotate-handle';
+    rotateHandle.title = 'Drag to rotate';
+    selectionOverlay.appendChild(rotateHandle);
+  }
+
+  let rotating = false;
+  let centerX, centerY;
+  let startAngle, startRotation, startTranslate, startScale;
+  let beforeSnapshot = null;
+
+  rotateHandle.addEventListener('pointerdown', (e) => {
+    if (!_targetElement) return;
+    e.preventDefault();
+    e.stopPropagation();
+
+    beforeSnapshot = snapshotStyle(_targetElement);
+    startTranslate = parseTranslate(_targetElement);
+    startRotation  = parseRotation(_targetElement);
+    startScale     = parseScale(_targetElement);
+
+    const overlayRect = selectionOverlay.getBoundingClientRect();
+    centerX = overlayRect.left + overlayRect.width / 2;
+    centerY = overlayRect.top  + overlayRect.height / 2;
+
+    startAngle = Math.atan2(e.clientY - centerY, e.clientX - centerX) * (180 / Math.PI);
+
+    rotating = true;
+    rotateHandle.setPointerCapture(e.pointerId);
+    document.body.style.cursor = 'grabbing';
+  });
+
+  rotateHandle.addEventListener('pointermove', (e) => {
+    if (!rotating) return;
+    e.preventDefault();
+
+    const currentAngle = Math.atan2(e.clientY - centerY, e.clientX - centerX) * (180 / Math.PI);
+    let newDeg = startRotation + (currentAngle - startAngle);
+
+    if (e.shiftKey) {
+      newDeg = Math.round(newDeg / 15) * 15;
+    }
+
+    setTransform(_targetElement, startTranslate, newDeg, startScale);
+  });
+
+  const endRotate = (e) => {
+    if (!rotating) return;
+    rotating = false;
+    document.body.style.cursor = '';
+    rotateHandle.releasePointerCapture(e.pointerId);
+    refocusAfterManipulation();
+
+    if (!beforeSnapshot || !_targetElement) return;
+
+    const afterSnapshot = snapshotStyle(_targetElement);
+
+    if (afterSnapshot.transform === beforeSnapshot.transform) {
+      beforeSnapshot = null;
+      return;
+    }
+
+    const cmd = makeStyleCommand('Rotate element', _targetElement, _targetHcId, beforeSnapshot, afterSnapshot);
+    push(cmd);
+    beforeSnapshot = null;
+  };
+
+  rotateHandle.addEventListener('pointerup', endRotate);
+  rotateHandle.addEventListener('pointercancel', endRotate);
+}
+
+// ── initManipulation ────────────────────────────────────────────────────────
+
+let _listenersAttached = false;
+
+export function initManipulation(iframe, iframeDoc, canvasArea) {
+  _iframe     = iframe;
+  _iframeDoc  = iframeDoc;
+  _canvasArea = canvasArea;
+  _targetElement = null;
+  _targetHcId    = null;
+
+  if (!_listenersAttached) {
+    _listenersAttached = true;
+
+    window.addEventListener('hc:selection-changed', (e) => {
+      const { element, hcId } = e.detail || {};
+      _targetElement = element || null;
+      _targetHcId    = hcId || null;
+    });
+
+    window.addEventListener('hc:selection-cleared', () => {
+      _targetElement = null;
+      _targetHcId    = null;
+    });
+  }
+}
+
+// ── MULTI-DRAG handler (drag surface on multi-selection overlay) ─────────────
+
+function setupMultiDragHandler() {
+  const multiOverlay = document.getElementById('multi-selection-overlay');
+  const multiDragSurface = multiOverlay ? multiOverlay.querySelector('.multi-drag-surface') : null;
+  if (!multiDragSurface) return;
+
+  let dragging = false;
+  let startClientX, startClientY;
+  let _multiStartData = [];
+
+  multiDragSurface.addEventListener('pointerdown', (e) => {
+    if (!isMultiSelectActive()) return;
+    e.preventDefault();
+    e.stopPropagation();
+
+    startClientX = e.clientX;
+    startClientY = e.clientY;
+
+    const elements = getSelectedElements();
+    const hcIds = getSelectedHcIds();
+    _multiStartData = elements.map((el, i) => ({
+      el,
+      hcId: hcIds[i] || el.getAttribute('data-hc-id'),
+      startTranslate: parseTranslate(el),
+      startRotation: parseRotation(el),
+      startScale: parseScale(el),
+      before: snapshotStyle(el),
+    }));
+
+    dragging = true;
+    multiDragSurface.setPointerCapture(e.pointerId);
+    document.body.style.cursor = 'move';
+  });
+
+  multiDragSurface.addEventListener('pointermove', (e) => {
+    if (!dragging) return;
+    e.preventDefault();
+
+    const scale = getZoom();
+    const dx = (e.clientX - startClientX) / scale;
+    const dy = (e.clientY - startClientY) / scale;
+
+    if (Math.abs(dx) < 1 && Math.abs(dy) < 1) return;
+
+    for (const data of _multiStartData) {
+      setTransform(data.el, {
+        x: data.startTranslate.x + dx,
+        y: data.startTranslate.y + dy,
+      }, data.startRotation, data.startScale);
+    }
+
+    // Update multi overlay position
+    window.dispatchEvent(new CustomEvent('hc:multi-selection-changed', {
+      detail: { elements: getSelectedElements(), hcIds: getSelectedHcIds() }
+    }));
+
+    syncOverlay();
+  });
+
+  const endMultiDrag = (e) => {
+    if (!dragging) return;
+    dragging = false;
+    document.body.style.cursor = '';
+    multiDragSurface.releasePointerCapture(e.pointerId);
+    refocusAfterManipulation();
+
+    if (_multiStartData.length === 0) return;
+
+    // Check if any element actually moved
+    const firstAfter = snapshotStyle(_multiStartData[0].el);
+    if (firstAfter.transform === _multiStartData[0].before.transform) {
+      _multiStartData = [];
+      return;
+    }
+
+    const snapshots = _multiStartData.map(data => ({
+      el: data.el,
+      hcId: data.hcId,
+      before: data.before,
+      after: snapshotStyle(data.el),
+    }));
+
+    const cmd = {
+      description: `Move ${snapshots.length} elements`,
+      execute() {
+        for (const s of snapshots) {
+          restoreStyle(s.el, s.after);
+          recordChange(s.hcId, s.el.outerHTML);
+        }
+      },
+      undo() {
+        for (const s of snapshots) {
+          restoreStyle(s.el, s.before);
+          recordChange(s.hcId, s.el.outerHTML);
+        }
+      }
+    };
+    push(cmd);
+    _multiStartData = [];
+  };
+
+  multiDragSurface.addEventListener('pointerup', endMultiDrag);
+  multiDragSurface.addEventListener('pointercancel', endMultiDrag);
+}
+
+// ── One-time setup ──────────────────────────────────────────────────────────
+
+setupDragHandler();
+setupResizeHandlers();
+setupRotateHandler();
+setupMultiDragHandler();