made-refine 0.2.6 → 0.2.7

package/dist/utils.js

@@ -26,6 +26,9 @@ __export(utils_exports, {
   buildCommentExport: () => buildCommentExport,
   buildEditExport: () => buildEditExport,
   buildElementContext: () => buildElementContext,
+  buildExportInstruction: () => buildExportInstruction,
+  buildMovePlan: () => buildMovePlan,
+  buildMovePlanContext: () => buildMovePlanContext,
   buildSessionExport: () => buildSessionExport,
   calculateDropPosition: () => calculateDropPosition,
   calculateElementMeasurements: () => calculateElementMeasurements,
@@ -37,17 +40,20 @@ __export(utils_exports, {
   colorPropertyToCSSMap: () => colorPropertyToCSSMap,
   colorToTailwind: () => colorToTailwind,
   computeHoverHighlight: () => computeHoverHighlight,
+  computeIntendedIndex: () => computeIntendedIndex,
   detectChildrenDirection: () => detectChildrenDirection,
   detectSizingMode: () => detectSizingMode,
   elementFromPointWithoutOverlays: () => elementFromPointWithoutOverlays,
   ensureDirectTextSpanAtPoint: () => ensureDirectTextSpanAtPoint,
   findChildAtPoint: () => findChildAtPoint,
   findContainerAtPoint: () => findContainerAtPoint,
+  findLayoutContainerAtPoint: () => findLayoutContainerAtPoint,
   findTextOwnerAtPoint: () => findTextOwnerAtPoint,
   findTextOwnerByRangeScan: () => findTextOwnerByRangeScan,
   flexPropertyToCSSMap: () => flexPropertyToCSSMap,
   formatPropertyValue: () => formatPropertyValue,
   getAllComputedStyles: () => getAllComputedStyles,
+  getChildBriefInfo: () => getChildBriefInfo,
   getComputedBorderStyles: () => getComputedBorderStyles,
   getComputedBoxShadow: () => getComputedBoxShadow,
   getComputedColorStyles: () => getComputedColorStyles,
@@ -58,11 +64,16 @@ __export(utils_exports, {
   getElementDisplayName: () => getElementDisplayName,
   getElementInfo: () => getElementInfo,
   getElementLocator: () => getElementLocator,
+  getElementSource: () => getElementSource,
+  getExportContentProfile: () => getExportContentProfile,
   getFlexDirection: () => getFlexDirection,
+  getMoveIntentForEdit: () => getMoveIntentForEdit,
   getOriginalInlineStyles: () => getOriginalInlineStyles,
   getSizingValue: () => getSizingValue,
   isFlexContainer: () => isFlexContainer,
+  isInFlowChild: () => isInFlowChild,
   isInputFocused: () => isInputFocused,
+  isLayoutContainer: () => isLayoutContainer,
   isTextElement: () => isTextElement,
   parseColorValue: () => parseColorValue,
   parsePropertyValue: () => parsePropertyValue,
@@ -1182,6 +1193,10 @@ function getFlexDirection(element) {
   const computed = window.getComputedStyle(element);
   return computed.flexDirection;
 }
+function isInFlowChild(el) {
+  const cs = window.getComputedStyle(el);
+  return cs.display !== "none" && cs.position !== "absolute" && cs.position !== "fixed";
+}
 function detectChildrenDirection(container, exclude) {
   const computed = window.getComputedStyle(container);
   if (computed.display === "flex" || computed.display === "inline-flex") {
@@ -1194,8 +1209,7 @@ function detectChildrenDirection(container, exclude) {
   const visible = [];
   for (const c of container.children) {
     if (!(c instanceof HTMLElement) || c === exclude) continue;
-    const cs = window.getComputedStyle(c);
-    if (cs.display === "none" || cs.position === "absolute" || cs.position === "fixed") continue;
+    if (!isInFlowChild(c)) continue;
     visible.push(c);
     if (visible.length === 2) break;
   }
@@ -1208,6 +1222,29 @@ function detectChildrenDirection(container, exclude) {
   }
   return { axis: "vertical", reversed: second.bottom < first.top };
 }
+function computeIntendedIndex(parent, draggedElement) {
+  const { axis } = detectChildrenDirection(parent, draggedElement);
+  const isHorizontal = axis === "horizontal";
+  const draggedRect = draggedElement.getBoundingClientRect();
+  const intendedCenter = isHorizontal ? draggedRect.left + draggedRect.width / 2 : draggedRect.top + draggedRect.height / 2;
+  const siblings = [];
+  for (const c of parent.children) {
+    if (!(c instanceof HTMLElement) || c === draggedElement) continue;
+    if (!isInFlowChild(c)) continue;
+    siblings.push(c);
+  }
+  if (siblings.length === 0) {
+    return { index: 0, siblingBefore: null, siblingAfter: null };
+  }
+  for (let i = 0; i < siblings.length; i++) {
+    const rect = siblings[i].getBoundingClientRect();
+    const midpoint = isHorizontal ? rect.left + rect.width / 2 : rect.top + rect.height / 2;
+    if (intendedCenter < midpoint) {
+      return { index: i, siblingBefore: i > 0 ? siblings[i - 1] : null, siblingAfter: siblings[i] };
+    }
+  }
+  return { index: siblings.length, siblingBefore: siblings[siblings.length - 1], siblingAfter: null };
+}
 function htmlChildren(el) {
   return Array.from(el.children).filter(
     (child) => child instanceof HTMLElement
@@ -1366,6 +1403,22 @@ function findContainerAtPoint(x, y, exclude, preferredParent) {
   }
   return findContainerViaTraversal(x, y, exclude);
 }
+function findLayoutContainerAtPoint(x, y, exclude, preferredParent) {
+  const host = document.querySelector("[data-direct-edit-host]");
+  if (host) host.style.display = "none";
+  const elements = document.elementsFromPoint(x, y);
+  if (host) host.style.display = "";
+  for (const el of elements) {
+    if (skipElement(el, exclude)) continue;
+    if (isLayoutContainer(el)) return el;
+  }
+  if (preferredParent && isLayoutContainer(preferredParent)) {
+    for (const el of elements) {
+      if (el === preferredParent) return preferredParent;
+    }
+  }
+  return null;
+}
 function calculateDropPosition(container, pointerX, pointerY, draggedElement) {
   const { axis, reversed: isReversed } = detectChildrenDirection(container, draggedElement);
   const isHorizontal = axis === "horizontal";
@@ -1760,7 +1813,18 @@ function getReactComponentStack(element) {
   return getRenderStack(fiber);
 }
 function getElementDisplayName(element) {
-  return element.tagName.toLowerCase();
+  const tag = element.tagName.toLowerCase();
+  if (element.id) return `${tag}#${element.id}`;
+  const firstClass = Array.from(element.classList).find((c) => c && !c.startsWith("direct-edit"));
+  if (firstClass) return `${tag}.${firstClass}`;
+  return tag;
+}
+function getChildBriefInfo(element) {
+  const name = getElementDisplayName(element);
+  const raw = ((element.innerText || element.textContent) ?? "").replace(/\s+/g, " ").trim();
+  const textPreview = raw.length > 40 ? `${raw.slice(0, 37)}...` : raw;
+  const source = getElementSource(element);
+  return { name, textPreview, source };
 }
 var STABLE_ATTRIBUTES = ["data-testid", "data-qa", "data-cy", "aria-label", "role"];
 var MAX_SELECTOR_DEPTH = 24;
@@ -2048,26 +2112,28 @@ function parseDomSource(element) {
   }
   return { file, line, column };
 }
-function getElementLocator(element) {
-  const elementInfo = getElementInfo(element);
-  let domSource = parseDomSource(element);
-  if (!domSource) {
-    const seenFibers = /* @__PURE__ */ new Set();
-    let fiber = getFiberForElement(element);
-    while (fiber && !seenFibers.has(fiber)) {
-      seenFibers.add(fiber);
-      const fiberSource = getSourceFromFiber(fiber);
-      if (fiberSource?.fileName) {
-        domSource = {
-          file: fiberSource.fileName,
-          line: fiberSource.lineNumber,
-          column: fiberSource.columnNumber
-        };
-        break;
-      }
-      fiber = fiber._debugOwner ?? fiber.return ?? null;
+function getElementSource(element) {
+  const domSource = parseDomSource(element);
+  if (domSource) return domSource;
+  const seenFibers = /* @__PURE__ */ new Set();
+  let fiber = getFiberForElement(element);
+  while (fiber && !seenFibers.has(fiber)) {
+    seenFibers.add(fiber);
+    const fiberSource = getSourceFromFiber(fiber);
+    if (fiberSource?.fileName) {
+      return {
+        file: fiberSource.fileName,
+        line: fiberSource.lineNumber,
+        column: fiberSource.columnNumber
+      };
     }
+    fiber = fiber._debugOwner ?? fiber.return ?? null;
   }
+  return null;
+}
+function getElementLocator(element) {
+  const elementInfo = getElementInfo(element);
+  const domSource = getElementSource(element);
   return {
     reactStack: getReactComponentStack(element),
     domSelector: buildDomSelector(element),
@@ -2086,7 +2152,7 @@ function getLocatorHeader(locator) {
   const formattedSource = locator.domSource?.file ? formatSourceLocation(locator.domSource.file, locator.domSource.line, locator.domSource.column) : primaryFrame?.file ? formatSourceLocation(primaryFrame.file, primaryFrame.line, primaryFrame.column) : null;
   return { componentLabel, formattedSource };
 }
-function buildLocatorContextLines(locator) {
+function buildLocatorContextLines(locator, options) {
   const lines = [];
   const { componentLabel, formattedSource } = getLocatorHeader(locator);
   const target = (locator.targetHtml || locator.domContextHtml || "").trim();
@@ -2099,7 +2165,7 @@ function buildLocatorContextLines(locator) {
     lines.push("target:");
     lines.push(target);
   }
-  if (context && context !== target) {
+  if (!options?.skipContext && context && context !== target) {
     lines.push("context:");
     lines.push(context);
   }
@@ -2253,6 +2319,29 @@ function buildEditExport(arg1, arg2, arg3, arg4, arg5, arg6, arg7) {
   }
   return lines.join("\n");
 }
+function buildEditExportWithOptions(locator, pendingStyles, textEdit, options) {
+  const changes = [];
+  const collapsedStyles = collapseExportShorthands(pendingStyles);
+  for (const [property, value] of Object.entries(collapsedStyles)) {
+    const tailwindClass = stylesToTailwind({ [property]: value });
+    changes.push({ property, value, tailwind: tailwindClass });
+  }
+  const lines = buildLocatorContextLines(locator, options);
+  lines.push("");
+  if (changes.length > 0) {
+    lines.push("edits:");
+    for (const change of changes) {
+      const tailwind = change.tailwind ? ` (${change.tailwind})` : "";
+      lines.push(`${change.property}: ${change.value}${tailwind}`);
+    }
+  }
+  if (textEdit) {
+    lines.push("text content changed:");
+    lines.push(`from: "${textEdit.originalText}"`);
+    lines.push(`to: "${textEdit.newText}"`);
+  }
+  return lines.join("\n");
+}
 function buildCommentExport(locator, commentText, replies) {
   const lines = buildLocatorContextLines(locator);
   lines.push("");
@@ -2264,55 +2353,554 @@ function buildCommentExport(locator, commentText, replies) {
   }
   return lines.join("\n");
 }
-function formatPosition(siblingBefore, siblingAfter) {
-  if (siblingBefore && siblingAfter) return `after <${siblingBefore}>`;
-  if (siblingBefore && !siblingAfter) return `after <${siblingBefore}> (last)`;
-  if (!siblingBefore && siblingAfter) return `before <${siblingAfter}> (first)`;
-  return "(only child)";
+function normalizeSelector(selector) {
+  const value = selector?.trim();
+  return value && value.length > 0 ? value : null;
+}
+function normalizeName(name) {
+  return name?.trim().toLowerCase() || "element";
+}
+function buildAnchorRef(name, selector, source) {
+  return {
+    name: name?.trim() || "element",
+    selector: normalizeSelector(selector),
+    source: source?.file ? source : null
+  };
 }
-function formatMoveSummary(move) {
-  const fromPosition = formatPosition(move.fromSiblingBefore, move.fromSiblingAfter);
-  const toPosition = formatPosition(move.toSiblingBefore, move.toSiblingAfter);
-  if (move.fromParentName === move.toParentName) {
-    return `in <${move.toParentName}>, from ${fromPosition} to ${toPosition}`;
+function anchorKey(anchor) {
+  if (!anchor) return "none";
+  const selector = normalizeSelector(anchor.selector);
+  if (selector) return `selector:${selector}`;
+  if (anchor.source?.file) {
+    return `source:${anchor.source.file}:${anchor.source.line ?? 0}:${anchor.source.column ?? 0}`;
+  }
+  return `name:${normalizeName(anchor.name)}`;
+}
+function anchorsEqual(a, b) {
+  if (!a && !b) return true;
+  if (!a || !b) return false;
+  const aSelector = normalizeSelector(a.selector);
+  const bSelector = normalizeSelector(b.selector);
+  if (aSelector && bSelector) return aSelector === bSelector;
+  if (a.source?.file && b.source?.file) {
+    return a.source.file === b.source.file && (a.source.line ?? null) === (b.source.line ?? null) && (a.source.column ?? null) === (b.source.column ?? null);
+  }
+  return normalizeName(a.name) === normalizeName(b.name);
+}
+function formatAnchorRef(anchor, fallback = "(none)") {
+  if (!anchor) return fallback;
+  const selector = normalizeSelector(anchor.selector);
+  if (selector) return selector;
+  if (anchor.source?.file) return `<${anchor.name}> @ ${formatSourceLocation(anchor.source.file, anchor.source.line, anchor.source.column)}`;
+  return `<${anchor.name}>`;
+}
+function buildPlacementRef(before, after) {
+  if (before && after) {
+    return {
+      before,
+      after,
+      description: `between after ${formatAnchorRef(before)} and before ${formatAnchorRef(after)}`
+    };
+  }
+  if (before) {
+    return {
+      before,
+      after: null,
+      description: `after ${formatAnchorRef(before)}`
+    };
   }
-  return `from <${move.fromParentName}> ${fromPosition} to <${move.toParentName}> ${toPosition}`;
+  if (after) {
+    return {
+      before: null,
+      after,
+      description: `before ${formatAnchorRef(after)}`
+    };
+  }
+  return {
+    before: null,
+    after: null,
+    description: "as the only child"
+  };
 }
-function formatMoveSelector(selector, fallback) {
-  const normalized = selector?.trim();
-  return normalized ? normalized : fallback;
+function buildPlacementFromMove(beforeName, beforeSelector, beforeSource, afterName, afterSelector, afterSource) {
+  const before = beforeName || beforeSelector || beforeSource?.file ? buildAnchorRef(beforeName, beforeSelector, beforeSource) : null;
+  const after = afterName || afterSelector || afterSource?.file ? buildAnchorRef(afterName, afterSelector, afterSource) : null;
+  return buildPlacementRef(before, after);
+}
+function toRoundedVisualDelta(move) {
+  const delta = move.visualDelta ?? move.positionDelta;
+  if (!delta) return void 0;
+  const rounded = { x: Math.round(delta.x), y: Math.round(delta.y) };
+  return rounded.x === 0 && rounded.y === 0 ? void 0 : rounded;
+}
+function hasVisualIntent(move) {
+  return Boolean(toRoundedVisualDelta(move));
+}
+function hasStructuralChange(move) {
+  const fromParent = buildAnchorRef(move.fromParentName, move.fromParentSelector, move.fromParentSource);
+  const toParent = buildAnchorRef(move.toParentName, move.toParentSelector, move.toParentSource);
+  const fromPlacement = buildPlacementFromMove(
+    move.fromSiblingBefore,
+    move.fromSiblingBeforeSelector,
+    move.fromSiblingBeforeSource,
+    move.fromSiblingAfter,
+    move.fromSiblingAfterSelector,
+    move.fromSiblingAfterSource
+  );
+  const toPlacement = buildPlacementFromMove(
+    move.toSiblingBefore,
+    move.toSiblingBeforeSelector,
+    move.toSiblingBeforeSource,
+    move.toSiblingAfter,
+    move.toSiblingAfterSelector,
+    move.toSiblingAfterSource
+  );
+  if (!anchorsEqual(fromParent, toParent)) return true;
+  if (!anchorsEqual(fromPlacement.before, toPlacement.before)) return true;
+  if (!anchorsEqual(fromPlacement.after, toPlacement.after)) return true;
+  if (typeof move.fromIndex === "number" && typeof move.toIndex === "number" && move.fromIndex !== move.toIndex) return true;
+  return false;
 }
-function formatMoveSource(source, fallback) {
-  if (!source?.file) return fallback;
-  return formatSourceLocation(source.file, source.line, source.column);
+function isStructuredLayoutContainer(layout) {
+  return layout === "flex" || layout === "grid";
+}
+function isExistingFlexWorkflow(move) {
+  const structuralChange = hasStructuralChange(move);
+  if (!structuralChange) return false;
+  const fromParent = buildAnchorRef(move.fromParentName, move.fromParentSelector, move.fromParentSource);
+  const toParent = buildAnchorRef(move.toParentName, move.toParentSelector, move.toParentSource);
+  const sameParent = anchorsEqual(fromParent, toParent);
+  const fromLayout = move.fromParentLayout;
+  const toLayout = move.toParentLayout;
+  if (sameParent) {
+    return Boolean(move.mode === "reorder" && (isStructuredLayoutContainer(toLayout) || isStructuredLayoutContainer(fromLayout)));
+  }
+  return Boolean(isStructuredLayoutContainer(fromLayout) && isStructuredLayoutContainer(toLayout));
+}
+function classifyMove(move) {
+  const structuralChange = hasStructuralChange(move);
+  const visualIntent = hasVisualIntent(move);
+  if (!structuralChange && !visualIntent) return "noop";
+  if (isExistingFlexWorkflow(move)) return "existing_layout_move";
+  if (move.mode === "free" || move.mode === "position") return "layout_refactor";
+  if (!structuralChange && visualIntent) return "layout_refactor";
+  return "layout_refactor";
+}
+function buildNumericClusters(values, tolerance) {
+  if (values.length === 0) return [];
+  const sorted = [...values].sort((a, b) => a - b);
+  const clusters = [{ center: sorted[0], values: [sorted[0]] }];
+  for (let i = 1; i < sorted.length; i++) {
+    const value = sorted[i];
+    const current = clusters[clusters.length - 1];
+    if (Math.abs(value - current.center) <= tolerance) {
+      current.values.push(value);
+      current.center = current.values.reduce((sum, n) => sum + n, 0) / current.values.length;
+    } else {
+      clusters.push({ center: value, values: [value] });
+    }
+  }
+  return clusters;
 }
-function buildMoveExportLines(move) {
-  return [
+function inferFlexDirection(sameRowCount, sameColumnCount, visualDelta) {
+  if (sameRowCount > sameColumnCount) {
+    return { direction: "row", reason: "Subject aligns with neighboring anchors on the same row." };
+  }
+  if (sameColumnCount > sameRowCount) {
+    return { direction: "column", reason: "Subject aligns with neighboring anchors on the same column." };
+  }
+  if (sameRowCount > 0) {
+    return { direction: "row", reason: "Detected row alignment in final geometry." };
+  }
+  if (sameColumnCount > 0) {
+    return { direction: "column", reason: "Detected column alignment in final geometry." };
+  }
+  const horizontalDominant = Math.abs(visualDelta?.x ?? 0) >= Math.abs(visualDelta?.y ?? 0);
+  return {
+    direction: horizontalDominant ? "row" : "column",
+    reason: "Fell back to movement axis because anchor alignment was ambiguous."
+  };
+}
+function inferLayoutPrescription(edit, operation, reasons) {
+  const parent = edit.element.parentElement;
+  if (!parent || !edit.element.isConnected) {
+    return {
+      recommendedSystem: "flex",
+      intentPatterns: ["no_geometry_context"],
+      refactorSteps: [
+        `Reparent ${formatAnchorRef(operation.subject)} under ${formatAnchorRef(operation.to.parent)} at ${operation.to.placement.description}.`
+      ],
+      styleSteps: [
+        `Convert ${formatAnchorRef(operation.to.parent)} to flex and set a clear primary axis for this relationship.`,
+        "Use `gap` for spacing and keep positioning static."
+      ],
+      itemSteps: [
+        "Remove any inline `left/top/transform` move artifacts from moved elements."
+      ]
+    };
+  }
+  const children = Array.from(parent.children).filter(
+    (node) => node instanceof HTMLElement && isInFlowChild(node) && !node.hasAttribute("data-direct-edit")
+  );
+  const childSnapshots = children.map((child) => {
+    const rect = child.getBoundingClientRect();
+    const locator = getElementLocator(child);
+    const anchor = buildAnchorRef(getElementDisplayName(child), locator.domSelector, locator.domSource);
+    return {
+      child,
+      rect,
+      centerX: rect.left + rect.width / 2,
+      centerY: rect.top + rect.height / 2,
+      anchor,
+      anchorLabel: formatAnchorRef(anchor)
+    };
+  });
+  const subjectSnapshot = childSnapshots.find((snapshot) => snapshot.child === edit.element);
+  const subjectRect = edit.element.getBoundingClientRect();
+  const subjectCenterX = subjectRect.left + subjectRect.width / 2;
+  const subjectCenterY = subjectRect.top + subjectRect.height / 2;
+  const rowTolerance = Math.max(8, subjectRect.height * 0.35);
+  const colTolerance = Math.max(8, subjectRect.width * 0.35);
+  const sameRowWith = [];
+  const sameColumnWith = [];
+  const sameRowNodes = [];
+  let aboveAnchor = null;
+  let belowAnchor = null;
+  let bestAboveDistance = Number.POSITIVE_INFINITY;
+  let bestBelowDistance = Number.POSITIVE_INFINITY;
+  for (const node of childSnapshots) {
+    if (node.child === edit.element) continue;
+    if (Math.abs(node.centerY - subjectCenterY) <= rowTolerance) {
+      sameRowWith.push(node.anchorLabel);
+      sameRowNodes.push(node);
+    }
+    if (Math.abs(node.centerX - subjectCenterX) <= colTolerance) {
+      sameColumnWith.push(node.anchorLabel);
+    }
+    const yDelta = node.centerY - subjectCenterY;
+    if (yDelta < 0 && Math.abs(yDelta) < bestAboveDistance) {
+      bestAboveDistance = Math.abs(yDelta);
+      aboveAnchor = node.anchorLabel;
+    }
+    if (yDelta > 0 && yDelta < bestBelowDistance) {
+      bestBelowDistance = yDelta;
+      belowAnchor = node.anchorLabel;
+    }
+  }
+  const rowCenters = childSnapshots.map(({ centerY }) => centerY);
+  const colCenters = childSnapshots.map(({ centerX }) => centerX);
+  const rowClusters = buildNumericClusters(rowCenters, rowTolerance);
+  const colClusters = buildNumericClusters(colCenters, colTolerance);
+  const denseRowClusters = rowClusters.filter((cluster) => cluster.values.length >= 2).length;
+  const denseColClusters = colClusters.filter((cluster) => cluster.values.length >= 2).length;
+  const isTwoDimensional = childSnapshots.length >= 4 && denseRowClusters >= 2 && denseColClusters >= 2;
+  const recommendedSystem = isTwoDimensional ? "grid" : "flex";
+  const intentPatterns = [];
+  if (sameRowWith.length > 0) intentPatterns.push(`same_row_with:${sameRowWith.slice(0, 3).join(", ")}`);
+  if (sameColumnWith.length > 0) intentPatterns.push(`same_column_with:${sameColumnWith.slice(0, 3).join(", ")}`);
+  if (aboveAnchor) intentPatterns.push(`below:${aboveAnchor}`);
+  if (belowAnchor) intentPatterns.push(`above:${belowAnchor}`);
+  if (sameRowWith.length === 0 && sameColumnWith.length === 0) intentPatterns.push("separate_cluster");
+  const visualDelta = operation.visualDelta;
+  const flexDirectionInfo = inferFlexDirection(sameRowWith.length, sameColumnWith.length, visualDelta);
+  const flexDirection = flexDirectionInfo.direction;
+  if (recommendedSystem === "grid") {
+    reasons.push("Detected multiple dense row and column clusters; a 2D layout system is likely intentional.");
+    return {
+      recommendedSystem: "grid",
+      intentPatterns,
+      refactorSteps: [
+        `Create/ensure a shared container around ${formatAnchorRef(operation.subject)} and related anchors under ${formatAnchorRef(operation.to.parent)}.`,
+        `Reorder/reparent elements to satisfy placement ${operation.to.placement.description}.`
+      ],
+      styleSteps: [
+        `Set ${formatAnchorRef(operation.to.parent)} to grid with explicit template rows/columns for the final layout.`,
+        "Use `gap` for consistent spacing and keep placement structural."
+      ],
+      itemSteps: [
+        `Set item alignment on ${formatAnchorRef(operation.subject)} with grid self-alignment (\`justify-self\`/\`align-self\`).`
+      ]
+    };
+  }
+  reasons.push(`${flexDirectionInfo.reason} Use a 1D flex layout instead of literal drag replay.`);
+  let hasStackedCluster = false;
+  const stackedAnchorLabels = /* @__PURE__ */ new Set();
+  if (flexDirection === "row" && subjectSnapshot) {
+    for (const rowPeer of sameRowNodes) {
+      for (const node of childSnapshots) {
+        if (node.child === edit.element || node.child === rowPeer.child) continue;
+        const sameColumnAsPeer = Math.abs(node.centerX - rowPeer.centerX) <= colTolerance;
+        const verticallySeparated = Math.abs(node.centerY - rowPeer.centerY) > rowTolerance;
+        if (sameColumnAsPeer && verticallySeparated) {
+          hasStackedCluster = true;
+          stackedAnchorLabels.add(rowPeer.anchorLabel);
+          stackedAnchorLabels.add(node.anchorLabel);
+        }
+      }
+    }
+  }
+  const hasBelowCluster = childSnapshots.some((node) => node.child !== edit.element && node.centerY - subjectCenterY > rowTolerance * 1.5 && Math.abs(node.centerY - subjectCenterY) > Math.abs(node.centerX - subjectCenterX));
+  const refactorSteps = [
+    `Ensure ${formatAnchorRef(operation.subject)} and referenced neighbors share a common container under ${formatAnchorRef(operation.to.parent)}.`,
+    `Reparent/reorder nodes so ${formatAnchorRef(operation.subject)} lands ${operation.to.placement.description}.`
+  ];
+  if (flexDirection === "row" && hasStackedCluster) {
+    const clusterSample = Array.from(stackedAnchorLabels).slice(0, 3).join(", ");
+    refactorSteps.push(`Create a left-side content wrapper for vertically stacked items (${clusterSample}), and keep ${formatAnchorRef(operation.subject)} as the opposite-side sibling.`);
+  }
+  if (hasBelowCluster) {
+    refactorSteps.push("Keep lower content sections in a separate block below the horizontal header row; do not force them into the same row.");
+  }
+  const styleSteps = [
+    `Set ${formatAnchorRef(operation.to.parent)} to flex with direction ${flexDirection}.`,
+    flexDirection === "row" ? "Use `justify-content: space-between` and `align-items: flex-start` when the moved element should sit on the opposite edge." : "Use `justify-content` / `align-items` to establish top-bottom alignment.",
+    "Use `gap` for spacing between siblings."
+  ];
+  if (flexDirection === "row" && hasStackedCluster) {
+    styleSteps.push("Set the content wrapper to `display: flex` with `flex-direction: column` and an appropriate vertical gap.");
+  }
+  return {
+    recommendedSystem: "flex",
+    intentPatterns,
+    refactorSteps,
+    styleSteps,
+    itemSteps: [
+      `Apply item-level alignment (\`align-self\` / flex-basis) only when needed for ${formatAnchorRef(operation.subject)}.`,
+      "Do not use absolute positioning, top/left offsets, transforms, or margin hacks to simulate movement."
+    ]
+  };
+}
+function buildMoveEntries(edits) {
+  const entries = [];
+  let noopMoveCount = 0;
+  for (const edit of edits) {
+    const move = edit.move;
+    if (!move) continue;
+    const subject = buildAnchorRef(
+      getElementDisplayName(edit.element) || edit.locator.tagName,
+      edit.locator.domSelector,
+      edit.locator.domSource
+    );
+    const fromParent = buildAnchorRef(move.fromParentName, move.fromParentSelector, move.fromParentSource);
+    const toParent = buildAnchorRef(move.toParentName, move.toParentSelector, move.toParentSource);
+    const fromPlacement = buildPlacementFromMove(
+      move.fromSiblingBefore,
+      move.fromSiblingBeforeSelector,
+      move.fromSiblingBeforeSource,
+      move.fromSiblingAfter,
+      move.fromSiblingAfterSelector,
+      move.fromSiblingAfterSource
+    );
+    const toPlacement = buildPlacementFromMove(
+      move.toSiblingBefore,
+      move.toSiblingBeforeSelector,
+      move.toSiblingBeforeSource,
+      move.toSiblingAfter,
+      move.toSiblingAfterSelector,
+      move.toSiblingAfterSource
+    );
+    const reasons = [];
+    const classification = classifyMove(move);
+    if (classification === "noop") {
+      noopMoveCount++;
+      continue;
+    }
+    const interactionMode = move.mode ?? "free";
+    const visualDelta = toRoundedVisualDelta(move);
+    if (visualDelta) {
+      reasons.push(`Non-zero visual delta detected (${visualDelta.x}px, ${visualDelta.y}px).`);
+    }
+    const structuralChange = hasStructuralChange(move);
+    if (structuralChange) reasons.push("Anchor placement changed between source and target.");
+    else reasons.push("No anchor placement change; treating movement as layout intent translation.");
+    const operationBase = {
+      classification,
+      interactionMode,
+      subject,
+      from: { parent: fromParent, placement: fromPlacement },
+      to: { parent: toParent, placement: toPlacement },
+      ...visualDelta ? { visualDelta } : {},
+      confidence: classification === "existing_layout_move" ? "high" : structuralChange ? "medium" : "high",
+      reasons
+    };
+    if (classification === "layout_refactor") {
+      operationBase.layoutPrescription = inferLayoutPrescription(edit, operationBase, reasons);
+    }
+    const sortSource = subject.source?.file ? `${subject.source.file}:${subject.source.line ?? 0}:${subject.source.column ?? 0}` : "";
+    const sortKey = [
+      sortSource,
+      anchorKey(subject),
+      anchorKey(toParent),
+      toPlacement.description
+    ].join("|");
+    entries.push({ edit, operation: operationBase, sortKey });
+  }
+  entries.sort((a, b) => a.sortKey.localeCompare(b.sortKey));
+  return { entries, noopMoveCount };
+}
+function buildMovePlanContext(edits, _domContext) {
+  const { entries, noopMoveCount } = buildMoveEntries(edits);
+  if (entries.length === 0) {
+    return {
+      movePlan: null,
+      intentsByEdit: /* @__PURE__ */ new Map(),
+      noopMoveCount
+    };
+  }
+  const operations = [];
+  const intentsByEdit = /* @__PURE__ */ new Map();
+  for (let i = 0; i < entries.length; i++) {
+    const operationId = `op-${i + 1}`;
+    const operation = { operationId, ...entries[i].operation };
+    operations.push(operation);
+    intentsByEdit.set(entries[i].edit, operation);
+  }
+  const affectedContainerMap = /* @__PURE__ */ new Map();
+  for (const operation of operations) {
+    affectedContainerMap.set(anchorKey(operation.from.parent), operation.from.parent);
+    affectedContainerMap.set(anchorKey(operation.to.parent), operation.to.parent);
+  }
+  const orderingConstraints = operations.filter((op) => op.classification === "existing_layout_move").map((op) => `${op.operationId}: place ${formatAnchorRef(op.subject)} ${op.to.placement.description} in ${formatAnchorRef(op.to.parent)}.`);
+  const notes = [];
+  if (noopMoveCount > 0) notes.push(`Excluded ${noopMoveCount} no-op move(s).`);
+  if (operations.some((op) => op.classification === "layout_refactor")) {
+    notes.push("Layout refactor operations include best-practice flex/grid prescriptions.");
+  }
+  return {
+    movePlan: {
+      operations,
+      affectedContainers: Array.from(affectedContainerMap.values()),
+      orderingConstraints,
+      notes
+    },
+    intentsByEdit,
+    noopMoveCount
+  };
+}
+function buildMovePlan(edits, domContext) {
+  const context = buildMovePlanContext(edits, domContext);
+  return context.movePlan ?? {
+    operations: [],
+    affectedContainers: [],
+    orderingConstraints: [],
+    notes: context.noopMoveCount > 0 ? [`Excluded ${context.noopMoveCount} no-op move(s).`] : []
+  };
+}
+function getMoveIntentForEdit(edit, context) {
+  if (!edit.move) return null;
+  if (context?.intentsByEdit.has(edit)) return context.intentsByEdit.get(edit) ?? null;
+  const singleContext = buildMovePlanContext([edit]);
+  return singleContext.intentsByEdit.get(edit) ?? null;
+}
+function buildMoveInstructionFromIntent(intent) {
+  if (intent.classification === "existing_layout_move") {
+    return `Apply as a structural move in code: place ${formatAnchorRef(intent.subject)} ${intent.to.placement.description} in ${formatAnchorRef(intent.to.parent)}.`;
+  }
+  const system = intent.layoutPrescription?.recommendedSystem ?? "flex";
+  return `Treat this as a ${system} layout refactor. Implement the listed structure/style steps in source code instead of drag replay.`;
+}
+function formatMoveType(classification) {
+  return classification === "existing_layout_move" ? "structural_move" : "layout_refactor";
+}
+function buildMoveExportLines(intent) {
+  const moveType = formatMoveType(intent.classification);
+  const implementationSteps = [];
+  if (intent.classification === "existing_layout_move") {
+    implementationSteps.push(`Reorder/reparent ${formatAnchorRef(intent.subject)} to ${intent.to.placement.description} in ${formatAnchorRef(intent.to.parent)}.`);
+  } else {
+    const prescription = intent.layoutPrescription;
+    if (prescription) {
+      implementationSteps.push(...prescription.refactorSteps);
+      implementationSteps.push(...prescription.styleSteps);
+      implementationSteps.push(...prescription.itemSteps);
+    }
+  }
+  const lines = [
     "moved:",
-    `summary: ${formatMoveSummary(move)}`,
-    `from_parent_selector: ${formatMoveSelector(move.fromParentSelector, "(unknown)")}`,
-    `from_before_selector: ${formatMoveSelector(move.fromSiblingBeforeSelector, "(none)")}`,
-    `from_after_selector: ${formatMoveSelector(move.fromSiblingAfterSelector, "(none)")}`,
-    `from_parent_source: ${formatMoveSource(move.fromParentSource, "(unknown)")}`,
-    `from_before_source: ${formatMoveSource(move.fromSiblingBeforeSource, "(none)")}`,
-    `from_after_source: ${formatMoveSource(move.fromSiblingAfterSource, "(none)")}`,
-    `to_parent_selector: ${formatMoveSelector(move.toParentSelector, "(unknown)")}`,
-    `to_before_selector: ${formatMoveSelector(move.toSiblingBeforeSelector, "(none)")}`,
-    `to_after_selector: ${formatMoveSelector(move.toSiblingAfterSelector, "(none)")}`,
-    `to_parent_source: ${formatMoveSource(move.toParentSource, "(unknown)")}`,
-    `to_before_source: ${formatMoveSource(move.toSiblingBeforeSource, "(none)")}`,
-    `to_after_source: ${formatMoveSource(move.toSiblingAfterSource, "(none)")}`
+    `id: ${intent.operationId}`,
+    `type: ${moveType}`,
+    `subject: ${formatAnchorRef(intent.subject, "(unknown)")}`,
+    `parent: ${formatAnchorRef(intent.to.parent, "(unknown)")}`,
+    `current_anchor: ${intent.from.placement.description}`,
+    `target_anchor: ${intent.to.placement.description}`,
+    ...intent.visualDelta ? [`visual_hint: ${intent.visualDelta.x}px horizontal, ${intent.visualDelta.y}px vertical`] : []
   ];
+  if (intent.layoutPrescription) {
+    lines.push(`recommended_layout: ${intent.layoutPrescription.recommendedSystem}`);
+  }
+  lines.push("implementation_steps:");
+  for (const step of implementationSteps) {
+    lines.push(`  - ${step}`);
+  }
+  lines.push("guardrails:");
+  lines.push("  - Do not simulate movement with absolute positioning, left/top offsets, transform, or margin hacks.");
+  lines.push(`instruction: ${buildMoveInstructionFromIntent(intent)}`);
+  return lines;
+}
+function getExportContentProfile(edits, comments, movePlanOrContext) {
+  const moveOpCount = movePlanOrContext ? "operations" in movePlanOrContext ? movePlanOrContext.operations.length : movePlanOrContext.movePlan?.operations.length ?? 0 : buildMovePlanContext(edits).movePlan?.operations.length ?? 0;
+  return {
+    hasCssEdits: edits.some((e) => Object.keys(e.pendingStyles).length > 0),
+    hasTextEdits: edits.some((e) => e.textEdit != null),
+    hasMoves: moveOpCount > 0,
+    hasComments: comments.length > 0
+  };
+}
+function buildExportInstruction(profile) {
+  const { hasCssEdits, hasTextEdits, hasMoves, hasComments } = profile;
+  if (!hasCssEdits && !hasTextEdits && !hasMoves && !hasComments) return "";
+  if (!hasCssEdits && !hasTextEdits && !hasMoves) {
+    return hasComments ? "Address this feedback on the UI. Use the provided source location and selector to find each element in the codebase." : "";
+  }
+  const parts = [];
+  if (hasCssEdits) parts.push("Apply the CSS changes to the targeted elements using the project's existing styling approach (Tailwind, CSS modules, etc.).");
+  if (hasTextEdits) parts.push("Update the text content as specified.");
+  if (hasMoves) parts.push("Implement the move plan below directly in source code. For `structural_move`, reorder/reparent elements using the target anchors. For `layout_refactor`, apply the listed flex/grid refactor steps. Do NOT simulate movement with absolute positioning, left/top offsets, transform, or margin hacks.");
+  if (hasComments) parts.push("Address the comments on the relevant elements.");
+  return `${parts.join(" ")} Use the provided source locations, selectors, and context HTML to locate each element in the codebase.`;
 }
-function buildSessionExport(edits, comments = []) {
+function buildSessionExport(edits, comments = [], options) {
   const blocks = [];
-  for (const edit of edits) {
-    let block = buildEditExport(edit.locator, edit.pendingStyles, edit.textEdit);
-    if (edit.move) {
-      block += `
-${buildMoveExportLines(edit.move).join("\n")}`;
+  const planContext = options?.movePlanContext ?? buildMovePlanContext(edits);
+  const movePlan = planContext.movePlan;
+  const includeMovePlanHeader = options?.includeMovePlanHeader !== false;
+  if (includeMovePlanHeader && movePlan && movePlan.operations.length > 0) {
+    const planLines = [
+      "=== LAYOUT MOVE PLAN ===",
+      `operations: ${movePlan.operations.length}`
+    ];
+    if (movePlan.affectedContainers.length > 0) {
+      planLines.push("containers:");
+      for (const container of movePlan.affectedContainers) {
+        planLines.push(`  - ${formatAnchorRef(container, "(unknown)")}`);
+      }
+    }
+    if (movePlan.orderingConstraints.length > 0) {
+      planLines.push("structural_constraints:");
+      for (const constraint of movePlan.orderingConstraints) {
+        planLines.push(`  - ${constraint}`);
+      }
     }
-    blocks.push(block);
+    if (movePlan.notes.length > 0) {
+      planLines.push("plan_notes:");
+      for (const note of movePlan.notes) {
+        planLines.push(`  - ${note}`);
+      }
+    }
+    blocks.push(planLines.join("\n"));
+  }
+  for (const edit of edits) {
+    const moveIntent = getMoveIntentForEdit(edit, planContext);
+    const hasMove = Boolean(moveIntent);
+    const hasStyleOrText = Object.keys(edit.pendingStyles).length > 0 || edit.textEdit != null;
+    if (!hasMove && !hasStyleOrText) continue;
+    const block = hasMove ? buildEditExportWithOptions(edit.locator, edit.pendingStyles, edit.textEdit, { skipContext: true }) : buildEditExport(edit.locator, edit.pendingStyles, edit.textEdit);
+    let moveBlock = "";
+    if (moveIntent) {
+      moveBlock = `
+${buildMoveExportLines(moveIntent).join("\n")}`;
+    }
+    blocks.push(block + moveBlock);
   }
   for (const comment of comments) {
     blocks.push(buildCommentExport(comment.locator, comment.text, comment.replies));
@@ -2327,6 +2915,9 @@ ${buildMoveExportLines(edit.move).join("\n")}`;
   buildCommentExport,
   buildEditExport,
   buildElementContext,
+  buildExportInstruction,
+  buildMovePlan,
+  buildMovePlanContext,
   buildSessionExport,
   calculateDropPosition,
   calculateElementMeasurements,
@@ -2338,17 +2929,20 @@ ${buildMoveExportLines(edit.move).join("\n")}`;
   colorPropertyToCSSMap,
   colorToTailwind,
   computeHoverHighlight,
+  computeIntendedIndex,
   detectChildrenDirection,
   detectSizingMode,
   elementFromPointWithoutOverlays,
   ensureDirectTextSpanAtPoint,
   findChildAtPoint,
   findContainerAtPoint,
+  findLayoutContainerAtPoint,
   findTextOwnerAtPoint,
   findTextOwnerByRangeScan,
   flexPropertyToCSSMap,
   formatPropertyValue,
   getAllComputedStyles,
+  getChildBriefInfo,
   getComputedBorderStyles,
   getComputedBoxShadow,
   getComputedColorStyles,
@@ -2359,11 +2953,16 @@ ${buildMoveExportLines(edit.move).join("\n")}`;
   getElementDisplayName,
   getElementInfo,
   getElementLocator,
+  getElementSource,
+  getExportContentProfile,
   getFlexDirection,
+  getMoveIntentForEdit,
   getOriginalInlineStyles,
   getSizingValue,
   isFlexContainer,
+  isInFlowChild,
   isInputFocused,
+  isLayoutContainer,
   isTextElement,
   parseColorValue,
   parsePropertyValue,