From 1f3501070268b68fa75de2ca554fe5a0ce913035 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 11:48:12 -0400
Subject: [PATCH 01/11] feat(studio): add grid overlay component and snap
 preferences

Add snapEnabled, gridVisible, gridSpacing, snapToGrid fields to
studioUiPreferences for persistence. Create GridOverlay component
using CSS repeating-linear-gradient for zero-JS-cost grid rendering.
---
 .../src/components/editor/GridOverlay.tsx     | 50 +++++++++++++++++++
 .../studio/src/utils/studioUiPreferences.ts   | 17 +++++++
 2 files changed, 67 insertions(+)
 create mode 100644 packages/studio/src/components/editor/GridOverlay.tsx

diff --git a/packages/studio/src/components/editor/GridOverlay.tsx b/packages/studio/src/components/editor/GridOverlay.tsx
new file mode 100644
index 0000000000..1ca973a806
--- /dev/null
+++ b/packages/studio/src/components/editor/GridOverlay.tsx
@@ -0,0 +1,50 @@
+// fallow-ignore-file unused-file
+import { memo } from "react";
+
+interface GridOverlayProps {
+  visible: boolean;
+  spacing: number;
+  scaleX: number;
+  scaleY: number;
+  compositionLeft: number;
+  compositionTop: number;
+  compositionWidth: number;
+  compositionHeight: number;
+}
+
+// fallow-ignore-next-line complexity
+export const GridOverlay = memo(function GridOverlay({
+  visible,
+  spacing,
+  scaleX,
+  scaleY,
+  compositionLeft,
+  compositionTop,
+  compositionWidth,
+  compositionHeight,
+}: GridOverlayProps) {
+  if (!visible || spacing <= 0) return null;
+
+  const overlaySpacingX = spacing * scaleX;
+  const overlaySpacingY = spacing * scaleY;
+
+  if (overlaySpacingX < 4 || overlaySpacingY < 4) return null;
+
+  return (
+    <div
+      aria-hidden="true"
+      className="pointer-events-none absolute"
+      style={{
+        left: compositionLeft,
+        top: compositionTop,
+        width: compositionWidth,
+        height: compositionHeight,
+        backgroundImage: [
+          `repeating-linear-gradient(90deg, rgba(255,255,255,0.12) 0px, rgba(255,255,255,0.12) 1px, transparent 1px, transparent ${overlaySpacingX}px)`,
+          `repeating-linear-gradient(0deg, rgba(255,255,255,0.12) 0px, rgba(255,255,255,0.12) 1px, transparent 1px, transparent ${overlaySpacingY}px)`,
+        ].join(", "),
+        backgroundSize: `${overlaySpacingX}px ${overlaySpacingY}px`,
+      }}
+    />
+  );
+});
diff --git a/packages/studio/src/utils/studioUiPreferences.ts b/packages/studio/src/utils/studioUiPreferences.ts
index 5c38a67a75..14428a4fd6 100644
--- a/packages/studio/src/utils/studioUiPreferences.ts
+++ b/packages/studio/src/utils/studioUiPreferences.ts
@@ -11,6 +11,10 @@ export interface StudioUiPreferences {
   audioMuted?: boolean;
   previewZoom?: StoredPreviewZoomState;
   recentBlocks?: string[];
+  snapEnabled?: boolean;
+  gridVisible?: boolean;
+  gridSpacing?: number;
+  snapToGrid?: boolean;
 }
 
 const STUDIO_UI_PREFERENCES_KEY = "hf-studio-ui-preferences";
@@ -28,6 +32,7 @@ function getBrowserStorage(): Storage | null {
   }
 }
 
+// fallow-ignore-next-line complexity
 function readStorage(storage: Storage | null): StudioUiPreferences {
   if (!storage) return {};
   try {
@@ -67,6 +72,18 @@ function readStorage(storage: Storage | null): StudioUiPreferences {
         (v: unknown): v is string => typeof v === "string",
       );
     }
+    if (typeof parsed.snapEnabled === "boolean") {
+      preferences.snapEnabled = parsed.snapEnabled;
+    }
+    if (typeof parsed.gridVisible === "boolean") {
+      preferences.gridVisible = parsed.gridVisible;
+    }
+    if (typeof parsed.gridSpacing === "number" && Number.isFinite(parsed.gridSpacing)) {
+      preferences.gridSpacing = parsed.gridSpacing;
+    }
+    if (typeof parsed.snapToGrid === "boolean") {
+      preferences.snapToGrid = parsed.snapToGrid;
+    }
     return preferences;
   } catch {
     return {};

From 9f046190bab57e7af717091c52aedc10efb3d986 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 11:55:19 -0400
Subject: [PATCH 02/11] feat(studio): add snap engine, guide overlay, toolbar,
 and target collection

Core snap computation module (snapEngine.ts) with 38 passing tests.
SnapGuideOverlay renders magenta guide lines and equidistance spacing
indicators via ref-driven DOM updates (no React re-renders during drag).
SnapToolbar provides magnet/grid toggle buttons with S/G keyboard shortcuts.
snapTargetCollection collects sibling overlay rects into snap targets.
---
 .../components/editor/SnapGuideOverlay.tsx    | 160 +++++
 .../src/components/editor/SnapToolbar.tsx     | 160 +++++
 .../src/components/editor/snapEngine.test.ts  | 624 ++++++++++++++++++
 .../src/components/editor/snapEngine.ts       | 580 ++++++++++++++++
 .../components/editor/snapTargetCollection.ts | 122 ++++
 5 files changed, 1646 insertions(+)
 create mode 100644 packages/studio/src/components/editor/SnapGuideOverlay.tsx
 create mode 100644 packages/studio/src/components/editor/SnapToolbar.tsx
 create mode 100644 packages/studio/src/components/editor/snapEngine.test.ts
 create mode 100644 packages/studio/src/components/editor/snapEngine.ts
 create mode 100644 packages/studio/src/components/editor/snapTargetCollection.ts

diff --git a/packages/studio/src/components/editor/SnapGuideOverlay.tsx b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
new file mode 100644
index 0000000000..e599bef9b7
--- /dev/null
+++ b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
@@ -0,0 +1,160 @@
+// fallow-ignore-file unused-file
+import { memo, useRef, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
+import type { SnapGuide, SpacingGuide } from "./snapEngine";
+
+export interface SnapGuidesState {
+  guides: SnapGuide[];
+  spacingGuides: SpacingGuide[];
+}
+
+const MAX_GUIDES = 6;
+const MAX_SPACING_GUIDES = 4;
+
+const GUIDE_COLOR = "rgba(255, 68, 204, 0.85)";
+const SPACING_COLOR = "rgba(255, 68, 204, 0.6)";
+const SPACING_BG = "rgba(255, 68, 204, 0.15)";
+
+interface SnapGuideOverlayProps {
+  snapGuidesRef: RefObject<SnapGuidesState | null>;
+  overlayWidth: number;
+  overlayHeight: number;
+}
+
+export const SnapGuideOverlay = memo(function SnapGuideOverlay({
+  snapGuidesRef,
+  overlayWidth,
+  overlayHeight,
+}: SnapGuideOverlayProps) {
+  const guideElsRef = useRef<(HTMLDivElement | null)[]>([]);
+  const spacingElsRef = useRef<(HTMLDivElement | null)[]>([]);
+  const spacingLabelElsRef = useRef<(HTMLSpanElement | null)[]>([]);
+
+  useMountEffect(() => {
+    let frame = 0;
+
+    // fallow-ignore-next-line complexity
+    const update = () => {
+      frame = requestAnimationFrame(update);
+
+      const state = snapGuidesRef.current;
+      const guides = state?.guides ?? [];
+      const spacingGuides = state?.spacingGuides ?? [];
+
+      for (let i = 0; i < MAX_GUIDES; i++) {
+        const el = guideElsRef.current[i];
+        if (!el) continue;
+
+        const guide = guides[i];
+        if (!guide) {
+          el.style.display = "none";
+          continue;
+        }
+
+        el.style.display = "";
+        if (guide.axis === "x") {
+          el.style.left = `${guide.position}px`;
+          el.style.top = "0";
+          el.style.width = "1px";
+          el.style.height = `${overlayHeight}px`;
+        } else {
+          el.style.left = "0";
+          el.style.top = `${guide.position}px`;
+          el.style.width = `${overlayWidth}px`;
+          el.style.height = "1px";
+        }
+      }
+
+      for (let i = 0; i < MAX_SPACING_GUIDES; i++) {
+        const el = spacingElsRef.current[i];
+        const label = spacingLabelElsRef.current[i];
+        if (!el) continue;
+
+        const sg = spacingGuides[i];
+        if (!sg) {
+          el.style.display = "none";
+          continue;
+        }
+
+        el.style.display = "flex";
+        el.style.alignItems = "center";
+        el.style.justifyContent = "center";
+        if (sg.axis === "x") {
+          el.style.left = `${sg.position}px`;
+          el.style.top = `${sg.from}px`;
+          el.style.width = `${sg.size}px`;
+          el.style.height = `${sg.to - sg.from}px`;
+          el.style.borderLeft = `1px dashed ${SPACING_COLOR}`;
+          el.style.borderRight = `1px dashed ${SPACING_COLOR}`;
+          el.style.borderTop = "none";
+          el.style.borderBottom = "none";
+        } else {
+          el.style.left = `${sg.from}px`;
+          el.style.top = `${sg.position}px`;
+          el.style.width = `${sg.to - sg.from}px`;
+          el.style.height = `${sg.size}px`;
+          el.style.borderTop = `1px dashed ${SPACING_COLOR}`;
+          el.style.borderBottom = `1px dashed ${SPACING_COLOR}`;
+          el.style.borderLeft = "none";
+          el.style.borderRight = "none";
+        }
+
+        if (label) {
+          label.textContent = `${Math.round(sg.size)}`;
+        }
+      }
+    };
+
+    frame = requestAnimationFrame(update);
+    return () => cancelAnimationFrame(frame);
+  });
+
+  return (
+    <div aria-hidden="true" className="pointer-events-none absolute inset-0">
+      {Array.from({ length: MAX_GUIDES }, (_, i) => (
+        <div
+          key={`guide-${i}`}
+          ref={(el) => {
+            guideElsRef.current[i] = el;
+          }}
+          style={{
+            display: "none",
+            position: "absolute",
+            backgroundColor: GUIDE_COLOR,
+            zIndex: 50,
+          }}
+        />
+      ))}
+
+      {Array.from({ length: MAX_SPACING_GUIDES }, (_, i) => (
+        <div
+          key={`spacing-${i}`}
+          ref={(el) => {
+            spacingElsRef.current[i] = el;
+          }}
+          style={{
+            display: "none",
+            position: "absolute",
+            zIndex: 50,
+          }}
+        >
+          <span
+            ref={(el) => {
+              spacingLabelElsRef.current[i] = el;
+            }}
+            style={{
+              fontSize: "10px",
+              fontFamily: "monospace",
+              color: GUIDE_COLOR,
+              backgroundColor: SPACING_BG,
+              padding: "0 3px",
+              borderRadius: "2px",
+              lineHeight: "14px",
+              whiteSpace: "nowrap",
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+});
diff --git a/packages/studio/src/components/editor/SnapToolbar.tsx b/packages/studio/src/components/editor/SnapToolbar.tsx
new file mode 100644
index 0000000000..9f28c4202a
--- /dev/null
+++ b/packages/studio/src/components/editor/SnapToolbar.tsx
@@ -0,0 +1,160 @@
+// fallow-ignore-file unused-file
+import { memo, useCallback, useEffect, useRef, useState } from "react";
+import { MagnetStraight, GridFour } from "@phosphor-icons/react";
+import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
+
+const SNAP_DEFAULTS = {
+  snapEnabled: true,
+  gridVisible: false,
+  gridSpacing: 50,
+  snapToGrid: false,
+};
+
+// fallow-ignore-next-line complexity
+function readSnapPrefs() {
+  const prefs = readStudioUiPreferences();
+  return {
+    snapEnabled: prefs.snapEnabled ?? SNAP_DEFAULTS.snapEnabled,
+    gridVisible: prefs.gridVisible ?? SNAP_DEFAULTS.gridVisible,
+    gridSpacing: prefs.gridSpacing ?? SNAP_DEFAULTS.gridSpacing,
+    snapToGrid: prefs.snapToGrid ?? SNAP_DEFAULTS.snapToGrid,
+  };
+}
+
+interface SnapToolbarProps {
+  onSnapChange?: (prefs: {
+    snapEnabled: boolean;
+    gridVisible: boolean;
+    gridSpacing: number;
+    snapToGrid: boolean;
+  }) => void;
+}
+
+// fallow-ignore-next-line complexity
+export const SnapToolbar = memo(function SnapToolbar({ onSnapChange }: SnapToolbarProps) {
+  const [prefs, setPrefs] = useState(readSnapPrefs);
+  const [gridPopoverOpen, setGridPopoverOpen] = useState(false);
+  const popoverRef = useRef<HTMLDivElement>(null);
+  const gridButtonRef = useRef<HTMLButtonElement>(null);
+
+  const updatePrefs = useCallback(
+    (patch: Partial<typeof prefs>) => {
+      setPrefs((prev) => {
+        const next = { ...prev, ...patch };
+        writeStudioUiPreferences(patch);
+        onSnapChange?.(next);
+        return next;
+      });
+    },
+    [onSnapChange],
+  );
+
+  const toggleSnap = useCallback(() => {
+    updatePrefs({ snapEnabled: !prefs.snapEnabled });
+  }, [prefs.snapEnabled, updatePrefs]);
+
+  const toggleGrid = useCallback(() => {
+    updatePrefs({ gridVisible: !prefs.gridVisible });
+  }, [prefs.gridVisible, updatePrefs]);
+
+  useEffect(() => {
+    // fallow-ignore-next-line complexity
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement) return;
+      if (e.key === "s" && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        e.preventDefault();
+        updatePrefs({ snapEnabled: !readSnapPrefs().snapEnabled });
+      }
+      if (e.key === "g" && !e.metaKey && !e.ctrlKey && !e.altKey) {
+        e.preventDefault();
+        updatePrefs({ gridVisible: !readSnapPrefs().gridVisible });
+      }
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [updatePrefs]);
+
+  useEffect(() => {
+    if (!gridPopoverOpen) return;
+    const handleClickOutside = (e: MouseEvent) => {
+      const target = e.target as Node;
+      if (popoverRef.current?.contains(target) || gridButtonRef.current?.contains(target)) return;
+      setGridPopoverOpen(false);
+    };
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, [gridPopoverOpen]);
+
+  return (
+    <div className="absolute top-2 right-2 z-50 flex items-center gap-1">
+      <button
+        type="button"
+        className={`rounded-md p-1.5 transition-colors ${
+          prefs.snapEnabled
+            ? "bg-studio-accent/20 text-studio-accent"
+            : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
+        }`}
+        onClick={toggleSnap}
+        title={prefs.snapEnabled ? "Snap enabled (S)" : "Snap disabled (S)"}
+        aria-label="Toggle snap"
+      >
+        <MagnetStraight size={16} weight={prefs.snapEnabled ? "fill" : "regular"} />
+      </button>
+
+      <div className="relative">
+        <button
+          ref={gridButtonRef}
+          type="button"
+          className={`rounded-md p-1.5 transition-colors ${
+            prefs.gridVisible
+              ? "bg-studio-accent/20 text-studio-accent"
+              : "bg-black/40 text-white/60 hover:bg-black/60 hover:text-white/80"
+          }`}
+          onClick={toggleGrid}
+          onContextMenu={(e) => {
+            e.preventDefault();
+            setGridPopoverOpen((v) => !v);
+          }}
+          title={prefs.gridVisible ? "Grid visible (G)" : "Grid hidden (G)"}
+          aria-label="Toggle grid"
+        >
+          <GridFour size={16} weight={prefs.gridVisible ? "fill" : "regular"} />
+        </button>
+
+        {gridPopoverOpen && (
+          <div
+            ref={popoverRef}
+            className="absolute right-0 top-full mt-1 rounded-lg bg-neutral-800 border border-neutral-700 p-3 shadow-xl min-w-[180px]"
+          >
+            <label className="flex items-center justify-between text-xs text-white/80 mb-2">
+              <span>Grid spacing</span>
+              <input
+                type="number"
+                min={10}
+                max={500}
+                step={10}
+                value={prefs.gridSpacing}
+                onChange={(e) => {
+                  const val = Number.parseInt(e.target.value, 10);
+                  if (Number.isFinite(val) && val >= 10 && val <= 500) {
+                    updatePrefs({ gridSpacing: val });
+                  }
+                }}
+                className="w-16 rounded bg-neutral-900 border border-neutral-600 px-1.5 py-0.5 text-xs text-white text-right tabular-nums outline-none focus:border-studio-accent"
+              />
+            </label>
+            <label className="flex items-center gap-2 text-xs text-white/80 cursor-pointer">
+              <input
+                type="checkbox"
+                checked={prefs.snapToGrid}
+                onChange={() => updatePrefs({ snapToGrid: !prefs.snapToGrid })}
+                className="accent-studio-accent"
+              />
+              <span>Snap to grid</span>
+            </label>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+});
diff --git a/packages/studio/src/components/editor/snapEngine.test.ts b/packages/studio/src/components/editor/snapEngine.test.ts
new file mode 100644
index 0000000000..19b1dc4660
--- /dev/null
+++ b/packages/studio/src/components/editor/snapEngine.test.ts
@@ -0,0 +1,624 @@
+// fallow-ignore-file code-duplication
+import { describe, test, expect } from "bun:test";
+import {
+  extractSnapTargets,
+  buildCompositionSnapTarget,
+  buildGridSnapEdges,
+  resolveSnapAdjustment,
+  resolveResizeSnapAdjustment,
+  resolveEquidistanceGuides,
+  SNAP_THRESHOLD_PX,
+  type SnapTarget,
+} from "./snapEngine";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rect(left: number, top: number, width: number, height: number) {
+  return { left, top, width, height };
+}
+
+function target(id: string, left: number, top: number, width: number, height: number): SnapTarget {
+  return {
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+    centerX: left + width / 2,
+    centerY: top + height / 2,
+    id,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// extractSnapTargets
+// ---------------------------------------------------------------------------
+
+describe("extractSnapTargets", () => {
+  test("computes right, bottom, centerX, centerY", () => {
+    const rects = [rect(10, 20, 100, 50)];
+    const [t] = extractSnapTargets(rects, ["a"]);
+    expect(t.left).toBe(10);
+    expect(t.top).toBe(20);
+    expect(t.right).toBe(110);
+    expect(t.bottom).toBe(70);
+    expect(t.centerX).toBe(60);
+    expect(t.centerY).toBe(45);
+    expect(t.id).toBe("a");
+  });
+
+  test("handles multiple rects", () => {
+    const targets = extractSnapTargets([rect(0, 0, 10, 10), rect(50, 50, 20, 30)], ["x", "y"]);
+    expect(targets).toHaveLength(2);
+    expect(targets[1].right).toBe(70);
+    expect(targets[1].bottom).toBe(80);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildCompositionSnapTarget
+// ---------------------------------------------------------------------------
+
+describe("buildCompositionSnapTarget", () => {
+  test("has id 'composition' and correct edges", () => {
+    const t = buildCompositionSnapTarget(rect(0, 0, 1920, 1080));
+    expect(t.id).toBe("composition");
+    expect(t.left).toBe(0);
+    expect(t.right).toBe(1920);
+    expect(t.centerX).toBe(960);
+    expect(t.centerY).toBe(540);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildGridSnapEdges
+// ---------------------------------------------------------------------------
+
+describe("buildGridSnapEdges", () => {
+  test("generates correct grid lines", () => {
+    const { x, y } = buildGridSnapEdges(rect(0, 0, 300, 200), 100, 1);
+    // At scale=1, step=100: x lines at 100, 200 (not 0 or 300)
+    expect(x.map((e) => e.position)).toEqual([100, 200]);
+    expect(y.map((e) => e.position)).toEqual([100]);
+    expect(x[0].source).toBe("grid");
+  });
+
+  test("applies scale to grid spacing", () => {
+    const { x } = buildGridSnapEdges(rect(0, 0, 600, 100), 100, 2);
+    // step = 200, lines at 200, 400
+    expect(x.map((e) => e.position)).toEqual([200, 400]);
+  });
+
+  test("handles offset composition rect", () => {
+    const { x } = buildGridSnapEdges(rect(50, 0, 300, 100), 100, 1);
+    // Lines at 150, 250 (offset + step, offset + 2*step)
+    expect(x.map((e) => e.position)).toEqual([150, 250]);
+  });
+
+  test("returns empty for zero gridSpacing", () => {
+    const { x, y } = buildGridSnapEdges(rect(0, 0, 300, 200), 0, 1);
+    expect(x).toHaveLength(0);
+    expect(y).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveSnapAdjustment — edge alignment
+// ---------------------------------------------------------------------------
+
+describe("resolveSnapAdjustment", () => {
+  const compositionTarget = target("composition", 0, 0, 1000, 800);
+
+  test("left-to-right alignment: moving left snaps to target right", () => {
+    // Target at x=200, width=100 => right edge at 300
+    // Moving rect at x=0, width=50. Propose dx=297 => proposed left=297
+    // Should snap left=300 (delta +3)
+    const t = target("a", 200, 100, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 100, 50, 50),
+      proposedDx: 297,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(300);
+    expect(result.guides.length).toBeGreaterThanOrEqual(1);
+    expect(result.guides[0].axis).toBe("x");
+    expect(result.guides[0].position).toBe(300);
+  });
+
+  test("right-to-left alignment: moving right snaps to target left", () => {
+    // Target at x=200. Moving rect width=50, at x=0.
+    // Proposed dx=146 => proposed right = 196. Target left=200. diff=4 within threshold.
+    const t = target("a", 200, 100, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 100, 50, 50),
+      proposedDx: 146,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    // Proposed right = 196, target left = 200, adjustment = +4
+    expect(result.dx).toBe(150);
+  });
+
+  test("center-to-center alignment on X axis", () => {
+    // Target center at x=250. Moving rect width=100 at x=0 => center at 50.
+    // Propose dx=198 => proposed center=248, target center=250, diff=2
+    const t = target("a", 200, 100, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 100, 100, 50),
+      proposedDx: 198,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(200);
+  });
+
+  test("top-to-bottom alignment", () => {
+    // Target bottom at 200. Moving top proposed at 197. Should snap to 200.
+    const t = target("a", 100, 100, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(100, 0, 50, 50),
+      proposedDx: 0,
+      proposedDy: 197,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dy).toBe(200);
+  });
+
+  test("center-to-center alignment on Y axis", () => {
+    // Target centerY = 150. Moving height=100 at y=0 => center=50.
+    // Propose dy=98 => proposed center=148, target center=150, diff=2
+    const t = target("a", 100, 100, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(100, 0, 100, 100),
+      proposedDx: 0,
+      proposedDy: 98,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dy).toBe(100);
+  });
+
+  test("composition center snap", () => {
+    // Composition center at 500, 400. Moving rect 100x100 at 0,0 => center 50,50.
+    // Propose dx=447, dy=347 => proposed center 497,397. Should snap to 500,400.
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 100, 100),
+      proposedDx: 447,
+      proposedDy: 347,
+      targets: [compositionTarget],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(450);
+    expect(result.dy).toBe(350);
+  });
+
+  test("no snap when outside threshold", () => {
+    const t = target("a", 200, 200, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 10,
+      proposedDy: 10,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    // Moving rect edges: left=10, center=35, right=60
+    // Target edges: left=200, center=250, right=300
+    // All distances > 6
+    expect(result.dx).toBe(10);
+    expect(result.dy).toBe(10);
+    expect(result.guides).toHaveLength(0);
+  });
+
+  test("multiple matching guides at same distance", () => {
+    // Two targets with left edges at 100 — both should produce guides
+    const t1 = target("a", 100, 0, 50, 50);
+    const t2 = target("b", 100, 200, 50, 50);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 100, 50, 50),
+      proposedDx: 97,
+      proposedDy: 0,
+      targets: [t1, t2],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(100);
+    // Should have a guide at x=100
+    const xGuides = result.guides.filter((g) => g.axis === "x");
+    expect(xGuides.length).toBeGreaterThanOrEqual(1);
+    expect(xGuides[0].position).toBe(100);
+    // The guide extent should cover both targets and the moving rect
+    expect(xGuides[0].from).toBe(0); // t1 top
+    expect(xGuides[0].to).toBe(250); // t2 bottom
+  });
+
+  test("disabled=true returns passthrough", () => {
+    const t = target("a", 100, 100, 50, 50);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 98,
+      proposedDy: 98,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: true,
+    });
+    expect(result.dx).toBe(98);
+    expect(result.dy).toBe(98);
+    expect(result.guides).toHaveLength(0);
+  });
+
+  test("threshold=0 means no snap", () => {
+    const t = target("a", 100, 100, 50, 50);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 99,
+      proposedDy: 99,
+      targets: [t],
+      threshold: 0,
+      disabled: false,
+    });
+    expect(result.dx).toBe(99);
+    expect(result.dy).toBe(99);
+    expect(result.guides).toHaveLength(0);
+  });
+
+  test("element snap takes priority over grid snap", () => {
+    // Element left edge at 100. Grid line at 97.
+    // Moving rect proposed left at 98 => dist to element=2, dist to grid=1.
+    // Grid is closer but element should win (priority).
+    // Actually the spec says element takes priority when both match within threshold.
+    // Let's set up: element at 103, grid at 97. Moving proposed left=100.
+    // Dist to element=3, dist to grid=3. Element should win.
+    const t = target("a", 103, 100, 50, 50);
+    const gridEdges = {
+      x: [{ position: 97, source: "grid" as const, id: "grid-x-0" }],
+      y: [],
+    };
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 100, 50, 50),
+      proposedDx: 100,
+      proposedDy: 0,
+      targets: [t],
+      gridEdges,
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    // Element at 103 wins over grid at 97 (both within threshold, same distance)
+    expect(result.dx).toBe(103);
+  });
+
+  test("grid snap used when no element matches", () => {
+    const gridEdges = {
+      x: [{ position: 100, source: "grid" as const, id: "grid-x-0" }],
+      y: [],
+    };
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 97,
+      proposedDy: 10,
+      targets: [],
+      gridEdges,
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(100);
+  });
+
+  test("snaps X and Y independently", () => {
+    const t = target("a", 200, 300, 100, 100);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 100, 100),
+      proposedDx: 198,
+      proposedDy: 500,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    // X should snap (left-to-left, diff=2), Y should not snap (too far)
+    expect(result.dx).toBe(200);
+    expect(result.dy).toBe(500);
+  });
+
+  test("works correctly with many targets (80)", () => {
+    const targets: SnapTarget[] = [];
+    for (let i = 0; i < 80; i++) {
+      targets.push(target(`el-${i}`, i * 50, i * 30, 40, 20));
+    }
+    // Moving rect near target el-40: left=2000, top=1200
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 40, 20),
+      proposedDx: 1998,
+      proposedDy: 1198,
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(2000);
+    expect(result.dy).toBe(1200);
+    expect(result.guides.length).toBeGreaterThanOrEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveResizeSnapAdjustment
+// ---------------------------------------------------------------------------
+
+describe("resolveResizeSnapAdjustment", () => {
+  test("only right edge snaps on X", () => {
+    // Moving rect at (100, 100) size 50x50, right=150.
+    // Target left at 200. Propose dx=47 => proposed right=197. Dist to 200=3.
+    const t = target("a", 200, 100, 100, 100);
+    const result = resolveResizeSnapAdjustment({
+      movingRect: rect(100, 100, 50, 50),
+      proposedDx: 47,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(50); // right edge snaps to 200
+  });
+
+  test("only bottom edge snaps on Y", () => {
+    // Moving rect at (100, 100) size 50x50, bottom=150.
+    // Target top at 200. Propose dy=47 => proposed bottom=197. Dist to 200=3.
+    const t = target("a", 100, 200, 100, 100);
+    const result = resolveResizeSnapAdjustment({
+      movingRect: rect(100, 100, 50, 50),
+      proposedDx: 0,
+      proposedDy: 47,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dy).toBe(50); // bottom edge snaps to 200
+  });
+
+  test("left edge does NOT snap during resize", () => {
+    // Target right at 150. Moving rect left=100. If drag were active,
+    // left would snap. But during resize, only right edge snaps.
+    // Moving rect at (100, 100) size 200x200, right=300.
+    // Target right=150. Proposed dx=-153 => proposed right=147. Dist to 150=3.
+    // This SHOULD snap right to 150 (dx = -150). But left stays at 100.
+    const t = target("a", 50, 100, 100, 100); // right=150
+    const result = resolveResizeSnapAdjustment({
+      movingRect: rect(100, 100, 200, 200),
+      proposedDx: -153,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    // Right edge: 300 + (-153) = 147 => snaps to 150, adjustment = +3, dx = -150
+    expect(result.dx).toBe(-150);
+  });
+
+  test("disabled=true returns passthrough for resize", () => {
+    const t = target("a", 200, 200, 100, 100);
+    const result = resolveResizeSnapAdjustment({
+      movingRect: rect(100, 100, 50, 50),
+      proposedDx: 47,
+      proposedDy: 47,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: true,
+    });
+    expect(result.dx).toBe(47);
+    expect(result.dy).toBe(47);
+    expect(result.guides).toHaveLength(0);
+  });
+
+  test("resize produces guide lines", () => {
+    const t = target("a", 200, 100, 100, 100);
+    const result = resolveResizeSnapAdjustment({
+      movingRect: rect(100, 100, 50, 50),
+      proposedDx: 47,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.guides.length).toBeGreaterThanOrEqual(1);
+    const xGuide = result.guides.find((g) => g.axis === "x");
+    expect(xGuide).toBeDefined();
+    expect(xGuide!.position).toBe(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveEquidistanceGuides
+// ---------------------------------------------------------------------------
+
+describe("resolveEquidistanceGuides", () => {
+  test("detects equal horizontal spacing", () => {
+    // Three elements in a row: A(0..40), moving(70..110), B(140..180)
+    // Gap A-moving = 70 - 40 = 30, gap moving-B = 140 - 110 = 30 => equal
+    const targets = [target("a", 0, 0, 40, 40), target("b", 140, 0, 40, 40)];
+    const guides = resolveEquidistanceGuides({
+      movingRect: rect(70, 0, 40, 40),
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+    });
+    const xGuides = guides.filter((g) => g.axis === "x");
+    expect(xGuides.length).toBe(2);
+    expect(xGuides[0].size).toBe(30);
+    expect(xGuides[1].size).toBe(30);
+  });
+
+  test("detects equal vertical spacing", () => {
+    // A(y=0..40), moving(y=60..100), B(y=120..160)
+    // Gap = 20 each
+    const targets = [target("a", 0, 0, 40, 40), target("b", 0, 120, 40, 40)];
+    const guides = resolveEquidistanceGuides({
+      movingRect: rect(0, 60, 40, 40),
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+    });
+    const yGuides = guides.filter((g) => g.axis === "y");
+    expect(yGuides.length).toBe(2);
+    expect(yGuides[0].size).toBe(20);
+  });
+
+  test("no equidistance when gaps differ", () => {
+    // A(0..40), moving(80..120), B(200..240)
+    // Gap A-moving = 40, gap moving-B = 80 => not equal
+    const targets = [target("a", 0, 0, 40, 40), target("b", 200, 0, 40, 40)];
+    const guides = resolveEquidistanceGuides({
+      movingRect: rect(80, 0, 40, 40),
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+    });
+    const xGuides = guides.filter((g) => g.axis === "x");
+    expect(xGuides.length).toBe(0);
+  });
+
+  test("handles tolerance of 1px", () => {
+    // A(0..40), moving(70..110), B(139..179)
+    // Gap A-moving = 30, gap moving-B = 29 => difference = 1 => within tolerance
+    const targets = [target("a", 0, 0, 40, 40), target("b", 139, 0, 40, 40)];
+    const guides = resolveEquidistanceGuides({
+      movingRect: rect(70, 0, 40, 40),
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+    });
+    const xGuides = guides.filter((g) => g.axis === "x");
+    expect(xGuides.length).toBe(2);
+  });
+
+  test("ignores overlapping elements", () => {
+    // A(0..100), moving(50..150), B(200..300) — A and moving overlap
+    const targets = [target("a", 0, 0, 100, 40), target("b", 200, 0, 100, 40)];
+    const guides = resolveEquidistanceGuides({
+      movingRect: rect(50, 0, 100, 40),
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+    });
+    const xGuides = guides.filter((g) => g.axis === "x");
+    // Gap A-moving = 50 - 100 = -50 (overlap), should be skipped
+    expect(xGuides.length).toBe(0);
+  });
+
+  test("only reports triplets involving the moving rect", () => {
+    // A(0..40), B(60..100), C(120..160) — all gaps = 20 but none involves moving
+    // Moving rect is far away at (500..540)
+    const targets = [
+      target("a", 0, 0, 40, 40),
+      target("b", 60, 0, 40, 40),
+      target("c", 120, 0, 40, 40),
+    ];
+    const guides = resolveEquidistanceGuides({
+      movingRect: rect(500, 0, 40, 40),
+      targets,
+      threshold: SNAP_THRESHOLD_PX,
+    });
+    // The A-B-C triplet doesn't involve moving, so no guides from it
+    // Any triplet involving moving would have huge gaps that don't match
+    const xGuides = guides.filter((g) => g.axis === "x");
+    expect(xGuides.length).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases
+// ---------------------------------------------------------------------------
+
+describe("edge cases", () => {
+  test("empty targets returns passthrough", () => {
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 10,
+      proposedDy: 20,
+      targets: [],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(10);
+    expect(result.dy).toBe(20);
+    expect(result.guides).toHaveLength(0);
+  });
+
+  test("exact match (zero distance) produces snap", () => {
+    const t = target("a", 100, 100, 50, 50);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 100,
+      proposedDy: 100,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(100);
+    expect(result.dy).toBe(100);
+    expect(result.guides.length).toBeGreaterThanOrEqual(1);
+  });
+
+  test("negative proposed delta works", () => {
+    const t = target("a", 50, 50, 100, 100);
+    // Moving rect at (200, 200), propose dx=-148 => proposed left=52, target left=50, diff=2
+    const result = resolveSnapAdjustment({
+      movingRect: rect(200, 200, 50, 50),
+      proposedDx: -148,
+      proposedDy: -148,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(-150);
+    expect(result.dy).toBe(-150);
+  });
+
+  test("left-to-left alignment", () => {
+    const t = target("a", 100, 0, 200, 200);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 300, 80, 80),
+      proposedDx: 97,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(100);
+  });
+
+  test("right-to-right alignment", () => {
+    // Target right = 300. Moving rect width=80 at x=0, right=80.
+    // Propose dx=217 => proposed right=297, target right=300, diff=3.
+    const t = target("a", 100, 0, 200, 200);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 300, 80, 80),
+      proposedDx: 217,
+      proposedDy: 0,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dx).toBe(220); // proposed left=220, proposed right=300
+  });
+
+  test("bottom-to-bottom alignment", () => {
+    // Target bottom = 200. Moving rect height=50 at y=0, bottom=50.
+    // Propose dy=147 => proposed bottom=197, target bottom=200, diff=3.
+    const t = target("a", 0, 0, 200, 200);
+    const result = resolveSnapAdjustment({
+      movingRect: rect(0, 0, 50, 50),
+      proposedDx: 0,
+      proposedDy: 147,
+      targets: [t],
+      threshold: SNAP_THRESHOLD_PX,
+      disabled: false,
+    });
+    expect(result.dy).toBe(150);
+  });
+});
diff --git a/packages/studio/src/components/editor/snapEngine.ts b/packages/studio/src/components/editor/snapEngine.ts
new file mode 100644
index 0000000000..31295c688f
--- /dev/null
+++ b/packages/studio/src/components/editor/snapEngine.ts
@@ -0,0 +1,580 @@
+// fallow-ignore-file code-duplication
+// Snap computation engine — pure functions, zero React/DOM dependencies.
+// All position values are in overlay-space (screen) pixels.
+
+export const SNAP_THRESHOLD_PX = 6;
+const EQUIDISTANCE_TOLERANCE_PX = 1;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SnapEdge {
+  position: number;
+  source: "element" | "composition" | "grid";
+  id: string;
+}
+
+export interface SnapTarget {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  centerX: number;
+  centerY: number;
+  id: string;
+}
+
+export interface SnapGuide {
+  axis: "x" | "y";
+  position: number;
+  /** Extent of the guide line (min of involved elements). */
+  from: number;
+  /** Extent of the guide line (max of involved elements). */
+  to: number;
+}
+
+export interface SpacingGuide {
+  axis: "x" | "y";
+  /** Position of the gap (start of gap). */
+  position: number;
+  /** Size of the gap in pixels. */
+  size: number;
+  /** Extent for rendering the indicator. */
+  from: number;
+  /** Extent for rendering the indicator. */
+  to: number;
+}
+
+export interface SnapResult {
+  dx: number;
+  dy: number;
+  guides: SnapGuide[];
+  spacingGuides: SpacingGuide[];
+}
+
+// ---------------------------------------------------------------------------
+// Rect shorthand used across the public API
+// ---------------------------------------------------------------------------
+
+interface Rect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rectRight(r: Rect): number {
+  return r.left + r.width;
+}
+
+function rectBottom(r: Rect): number {
+  return r.top + r.height;
+}
+
+function rectCenterX(r: Rect): number {
+  return r.left + r.width / 2;
+}
+
+function rectCenterY(r: Rect): number {
+  return r.top + r.height / 2;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert overlay rects to snap targets with precomputed edges & centers.
+ */
+export function extractSnapTargets(rects: Rect[], ids: string[]): SnapTarget[] {
+  const targets: SnapTarget[] = [];
+  for (let i = 0; i < rects.length; i++) {
+    const r = rects[i];
+    targets.push({
+      left: r.left,
+      top: r.top,
+      right: rectRight(r),
+      bottom: rectBottom(r),
+      centerX: rectCenterX(r),
+      centerY: rectCenterY(r),
+      id: ids[i],
+    });
+  }
+  return targets;
+}
+
+/**
+ * Create a snap target from the composition/overlay boundary.
+ */
+export function buildCompositionSnapTarget(rect: Rect): SnapTarget {
+  return {
+    left: rect.left,
+    top: rect.top,
+    right: rectRight(rect),
+    bottom: rectBottom(rect),
+    centerX: rectCenterX(rect),
+    centerY: rectCenterY(rect),
+    id: "composition",
+  };
+}
+
+/**
+ * Generate grid-line snap edges.
+ * `gridSpacing` is in composition pixels; `scale` converts to overlay pixels.
+ * X edges are vertical grid lines; Y edges are horizontal grid lines.
+ */
+export function buildGridSnapEdges(
+  compositionRect: Rect,
+  gridSpacing: number,
+  scale: number,
+): { x: SnapEdge[]; y: SnapEdge[] } {
+  const xEdges: SnapEdge[] = [];
+  const yEdges: SnapEdge[] = [];
+
+  if (gridSpacing <= 0 || scale <= 0) return { x: xEdges, y: yEdges };
+
+  const step = gridSpacing * scale;
+
+  // Vertical grid lines (x-axis edges)
+  let x = compositionRect.left + step;
+  const xMax = compositionRect.left + compositionRect.width;
+  let idx = 0;
+  while (x < xMax) {
+    xEdges.push({ position: x, source: "grid", id: `grid-x-${idx}` });
+    x += step;
+    idx++;
+  }
+
+  // Horizontal grid lines (y-axis edges)
+  let y = compositionRect.top + step;
+  const yMax = compositionRect.top + compositionRect.height;
+  idx = 0;
+  while (y < yMax) {
+    yEdges.push({ position: y, source: "grid", id: `grid-y-${idx}` });
+    y += step;
+    idx++;
+  }
+
+  return { x: xEdges, y: yEdges };
+}
+
+// ---------------------------------------------------------------------------
+// Internal snap resolution helpers
+// ---------------------------------------------------------------------------
+
+interface EdgeCandidate {
+  /** Distance the moving rect must adjust to align with this edge. */
+  adjustment: number;
+  /** Absolute distance (for comparison). */
+  distance: number;
+  /** Position of the guide line. */
+  guidePosition: number;
+  /** Source of the match. */
+  source: "element" | "composition" | "grid";
+  /** Id of the target or grid line. */
+  targetId: string;
+}
+
+/**
+ * Collect edge candidates on a single axis for a moving rect.
+ * `movingEdges` are the edges of the moving rect (e.g. left, centerX, right).
+ * `targetEdges` are the corresponding edges on each target.
+ */
+// fallow-ignore-next-line complexity
+function collectCandidates(
+  movingEdges: number[],
+  targets: SnapTarget[],
+  targetEdgeExtractor: (t: SnapTarget) => number[],
+  gridEdges: SnapEdge[] | undefined,
+  threshold: number,
+): EdgeCandidate[] {
+  const candidates: EdgeCandidate[] = [];
+
+  for (const target of targets) {
+    const tEdges = targetEdgeExtractor(target);
+    for (const mEdge of movingEdges) {
+      for (const tEdge of tEdges) {
+        const adjustment = tEdge - mEdge;
+        const distance = Math.abs(adjustment);
+        if (distance <= threshold) {
+          candidates.push({
+            adjustment,
+            distance,
+            guidePosition: tEdge,
+            source: target.id === "composition" ? "composition" : "element",
+            targetId: target.id,
+          });
+        }
+      }
+    }
+  }
+
+  if (gridEdges) {
+    for (const edge of gridEdges) {
+      for (const mEdge of movingEdges) {
+        const adjustment = edge.position - mEdge;
+        const distance = Math.abs(adjustment);
+        if (distance <= threshold) {
+          candidates.push({
+            adjustment,
+            distance,
+            guidePosition: edge.position,
+            source: "grid",
+            targetId: edge.id,
+          });
+        }
+      }
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * From a list of candidates, pick the best adjustment:
+ * - Element/composition matches take priority over grid matches.
+ * - Among equal-priority matches, pick the smallest distance.
+ * - Return all guides that share the winning adjustment.
+ */
+function pickBest(candidates: EdgeCandidate[]): {
+  adjustment: number;
+  matches: EdgeCandidate[];
+} | null {
+  if (candidates.length === 0) return null;
+
+  // Partition into element/composition vs grid
+  const elementCandidates = candidates.filter(
+    (c) => c.source === "element" || c.source === "composition",
+  );
+  const gridCandidates = candidates.filter((c) => c.source === "grid");
+
+  // Pick the pool with the best (smallest distance) match, preferring element
+  let pool: EdgeCandidate[];
+  const bestElem = elementCandidates.length
+    ? Math.min(...elementCandidates.map((c) => c.distance))
+    : Infinity;
+  const bestGrid = gridCandidates.length
+    ? Math.min(...gridCandidates.map((c) => c.distance))
+    : Infinity;
+
+  if (bestElem <= bestGrid) {
+    pool = elementCandidates;
+  } else {
+    pool = gridCandidates;
+  }
+
+  const minDist = Math.min(...pool.map((c) => c.distance));
+  const winners = pool.filter((c) => c.distance === minDist);
+
+  // All winners share the same adjustment magnitude but could differ in sign
+  // if two edges snap at the same distance in opposite directions. Pick the
+  // adjustment from the first winner (they're all at minDist).
+  const adjustment = winners[0].adjustment;
+
+  // Return all matches at this exact adjustment (same direction)
+  const matches = pool.filter((c) => c.adjustment === adjustment);
+  return { adjustment, matches };
+}
+
+// ---------------------------------------------------------------------------
+// Guide extent computation
+// ---------------------------------------------------------------------------
+
+function computeGuideExtent(
+  axis: "x" | "y",
+  guidePosition: number,
+  movingRect: Rect,
+  matchedTargetIds: string[],
+  allTargets: SnapTarget[],
+): { from: number; to: number } {
+  // Collect cross-axis extents from the moving rect and matched targets
+  const extents: number[] = [];
+
+  if (axis === "x") {
+    // Guide is vertical — extent runs along Y
+    extents.push(movingRect.top, rectBottom(movingRect));
+    for (const tid of matchedTargetIds) {
+      const t = allTargets.find((tgt) => tgt.id === tid);
+      if (t) {
+        extents.push(t.top, t.bottom);
+      }
+    }
+  } else {
+    // Guide is horizontal — extent runs along X
+    extents.push(movingRect.left, rectRight(movingRect));
+    for (const tid of matchedTargetIds) {
+      const t = allTargets.find((tgt) => tgt.id === tid);
+      if (t) {
+        extents.push(t.left, t.right);
+      }
+    }
+  }
+
+  return { from: Math.min(...extents), to: Math.max(...extents) };
+}
+
+// ---------------------------------------------------------------------------
+// Shared guide-building logic
+// ---------------------------------------------------------------------------
+
+function buildGuidesFromMatches(
+  bestX: { adjustment: number; matches: EdgeCandidate[] } | null,
+  bestY: { adjustment: number; matches: EdgeCandidate[] } | null,
+  adjustedRect: Rect,
+  allTargets: SnapTarget[],
+): SnapGuide[] {
+  const guides: SnapGuide[] = [];
+
+  for (const [axis, best] of [
+    ["x", bestX],
+    ["y", bestY],
+  ] as const) {
+    if (!best) continue;
+    const seenPositions = new Set<number>();
+    for (const m of best.matches) {
+      if (seenPositions.has(m.guidePosition)) continue;
+      seenPositions.add(m.guidePosition);
+      const targetIds = best.matches
+        .filter((mm) => mm.guidePosition === m.guidePosition)
+        .map((mm) => mm.targetId);
+      const extent = computeGuideExtent(axis, m.guidePosition, adjustedRect, targetIds, allTargets);
+      guides.push({ axis, position: m.guidePosition, from: extent.from, to: extent.to });
+    }
+  }
+
+  return guides;
+}
+
+const DISABLED_RESULT = (dx: number, dy: number): SnapResult => ({
+  dx,
+  dy,
+  guides: [],
+  spacingGuides: [],
+});
+
+// ---------------------------------------------------------------------------
+// resolveSnapAdjustment — main drag snap entry point
+// ---------------------------------------------------------------------------
+
+// fallow-ignore-next-line complexity
+export function resolveSnapAdjustment(input: {
+  movingRect: Rect;
+  proposedDx: number;
+  proposedDy: number;
+  targets: SnapTarget[];
+  gridEdges?: { x: SnapEdge[]; y: SnapEdge[] };
+  threshold: number;
+  disabled: boolean;
+}): SnapResult {
+  if (input.disabled || input.threshold <= 0) {
+    return DISABLED_RESULT(input.proposedDx, input.proposedDy);
+  }
+
+  const mr = input.movingRect;
+  const proposed: Rect = {
+    left: mr.left + input.proposedDx,
+    top: mr.top + input.proposedDy,
+    width: mr.width,
+    height: mr.height,
+  };
+
+  const xCandidates = collectCandidates(
+    [proposed.left, rectCenterX(proposed), rectRight(proposed)],
+    input.targets,
+    (t) => [t.left, t.centerX, t.right],
+    input.gridEdges?.x,
+    input.threshold,
+  );
+  const yCandidates = collectCandidates(
+    [proposed.top, rectCenterY(proposed), rectBottom(proposed)],
+    input.targets,
+    (t) => [t.top, t.centerY, t.bottom],
+    input.gridEdges?.y,
+    input.threshold,
+  );
+
+  const bestX = pickBest(xCandidates);
+  const bestY = pickBest(yCandidates);
+  const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
+  const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);
+
+  const adjustedRect: Rect = {
+    left: mr.left + adjustedDx,
+    top: mr.top + adjustedDy,
+    width: mr.width,
+    height: mr.height,
+  };
+
+  return {
+    dx: adjustedDx,
+    dy: adjustedDy,
+    guides: buildGuidesFromMatches(bestX, bestY, adjustedRect, input.targets),
+    spacingGuides: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resolveResizeSnapAdjustment — resize variant (only right/bottom snap)
+// ---------------------------------------------------------------------------
+
+// fallow-ignore-next-line complexity
+export function resolveResizeSnapAdjustment(input: {
+  movingRect: Rect;
+  proposedDx: number;
+  proposedDy: number;
+  targets: SnapTarget[];
+  gridEdges?: { x: SnapEdge[]; y: SnapEdge[] };
+  threshold: number;
+  disabled: boolean;
+}): SnapResult {
+  if (input.disabled || input.threshold <= 0) {
+    return DISABLED_RESULT(input.proposedDx, input.proposedDy);
+  }
+
+  const mr = input.movingRect;
+  const proposedRight = rectRight(mr) + input.proposedDx;
+  const proposedBottom = rectBottom(mr) + input.proposedDy;
+
+  const xCandidates = collectCandidates(
+    [proposedRight],
+    input.targets,
+    (t) => [t.left, t.centerX, t.right],
+    input.gridEdges?.x,
+    input.threshold,
+  );
+  const yCandidates = collectCandidates(
+    [proposedBottom],
+    input.targets,
+    (t) => [t.top, t.centerY, t.bottom],
+    input.gridEdges?.y,
+    input.threshold,
+  );
+
+  const bestX = pickBest(xCandidates);
+  const bestY = pickBest(yCandidates);
+  const adjustedDx = input.proposedDx + (bestX?.adjustment ?? 0);
+  const adjustedDy = input.proposedDy + (bestY?.adjustment ?? 0);
+
+  const adjustedRect: Rect = {
+    left: mr.left,
+    top: mr.top,
+    width: mr.width + adjustedDx,
+    height: mr.height + adjustedDy,
+  };
+
+  return {
+    dx: adjustedDx,
+    dy: adjustedDy,
+    guides: buildGuidesFromMatches(bestX, bestY, adjustedRect, input.targets),
+    spacingGuides: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resolveEquidistanceGuides
+// ---------------------------------------------------------------------------
+
+// fallow-ignore-next-line complexity
+export function resolveEquidistanceGuides(input: {
+  movingRect: Rect;
+  targets: SnapTarget[];
+  threshold: number;
+}): SpacingGuide[] {
+  const guides: SpacingGuide[] = [];
+  const mr = input.movingRect;
+
+  const movingTarget: SnapTarget = {
+    left: mr.left,
+    top: mr.top,
+    right: rectRight(mr),
+    bottom: rectBottom(mr),
+    centerX: rectCenterX(mr),
+    centerY: rectCenterY(mr),
+    id: "__moving__",
+  };
+
+  const allTargets = [...input.targets, movingTarget];
+
+  // X axis: sort by centerX, scan for equal gaps between adjacent triplets
+  const sortedX = [...allTargets].sort((a, b) => a.centerX - b.centerX);
+  for (let i = 0; i < sortedX.length - 2; i++) {
+    const a = sortedX[i];
+    const b = sortedX[i + 1];
+    const c = sortedX[i + 2];
+
+    // Gap between A and B = B.left - A.right
+    const gapAB = b.left - a.right;
+    const gapBC = c.left - b.right;
+
+    if (gapAB < 0 || gapBC < 0) continue; // overlapping elements
+
+    // Check if the moving rect is one of A, B, or C
+    const involvesMoving = a.id === "__moving__" || b.id === "__moving__" || c.id === "__moving__";
+    if (!involvesMoving) continue;
+
+    if (Math.abs(gapAB - gapBC) <= EQUIDISTANCE_TOLERANCE_PX) {
+      const crossMin = Math.min(a.top, b.top, c.top);
+      const crossMax = Math.max(a.bottom, b.bottom, c.bottom);
+
+      // Gap A-B
+      guides.push({
+        axis: "x",
+        position: a.right,
+        size: gapAB,
+        from: crossMin,
+        to: crossMax,
+      });
+      // Gap B-C
+      guides.push({
+        axis: "x",
+        position: b.right,
+        size: gapBC,
+        from: crossMin,
+        to: crossMax,
+      });
+    }
+  }
+
+  // Y axis: sort by centerY, scan for equal gaps between adjacent triplets
+  const sortedY = [...allTargets].sort((a, b) => a.centerY - b.centerY);
+  for (let i = 0; i < sortedY.length - 2; i++) {
+    const a = sortedY[i];
+    const b = sortedY[i + 1];
+    const c = sortedY[i + 2];
+
+    const gapAB = b.top - a.bottom;
+    const gapBC = c.top - b.bottom;
+
+    if (gapAB < 0 || gapBC < 0) continue;
+
+    const involvesMoving = a.id === "__moving__" || b.id === "__moving__" || c.id === "__moving__";
+    if (!involvesMoving) continue;
+
+    if (Math.abs(gapAB - gapBC) <= EQUIDISTANCE_TOLERANCE_PX) {
+      const crossMin = Math.min(a.left, b.left, c.left);
+      const crossMax = Math.max(a.right, b.right, c.right);
+
+      guides.push({
+        axis: "y",
+        position: a.bottom,
+        size: gapAB,
+        from: crossMin,
+        to: crossMax,
+      });
+      guides.push({
+        axis: "y",
+        position: b.bottom,
+        size: gapBC,
+        from: crossMin,
+        to: crossMax,
+      });
+    }
+  }
+
+  return guides;
+}
diff --git a/packages/studio/src/components/editor/snapTargetCollection.ts b/packages/studio/src/components/editor/snapTargetCollection.ts
new file mode 100644
index 0000000000..89d4044d04
--- /dev/null
+++ b/packages/studio/src/components/editor/snapTargetCollection.ts
@@ -0,0 +1,122 @@
+// fallow-ignore-file unused-file code-duplication
+import type { DomEditSelection } from "./domEditing";
+import type { DomEditContextOptions } from "./domEditingTypes";
+import { collectDomEditLayerItems } from "./domEditingLayers";
+import {
+  isElementVisibleForOverlay,
+  selectionCacheKey,
+  toOverlayRect,
+  type OverlayRect,
+} from "./domEditOverlayGeometry";
+import {
+  extractSnapTargets,
+  buildCompositionSnapTarget,
+  buildGridSnapEdges,
+  type SnapTarget,
+  type SnapEdge,
+} from "./snapEngine";
+import { readStudioUiPreferences } from "../../utils/studioUiPreferences";
+
+export interface SnapContext {
+  targets: SnapTarget[];
+  compositionTarget: SnapTarget | null;
+  gridEdges: { x: SnapEdge[]; y: SnapEdge[] } | null;
+  snapEnabled: boolean;
+}
+
+function readPositiveDimension(value: string | null): number | null {
+  if (!value) return null;
+  const parsed = Number.parseFloat(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+// fallow-ignore-next-line complexity
+export function collectSnapContext(input: {
+  overlayEl: HTMLDivElement;
+  iframe: HTMLIFrameElement;
+  excludeKeys: Set<string>;
+  activeCompositionPath: string | null;
+}): SnapContext {
+  const prefs = readStudioUiPreferences();
+  const snapEnabled = prefs.snapEnabled ?? true;
+
+  const doc = input.iframe.contentDocument;
+  if (!doc) {
+    return { targets: [], compositionTarget: null, gridEdges: null, snapEnabled };
+  }
+
+  const root = doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement;
+  const rootRect = root?.getBoundingClientRect();
+  const declaredWidth = readPositiveDimension(root?.getAttribute("data-width") ?? null);
+  const declaredHeight = readPositiveDimension(root?.getAttribute("data-height") ?? null);
+  const rootWidth = declaredWidth ?? rootRect?.width;
+  const rootHeight = declaredHeight ?? rootRect?.height;
+
+  if (!rootWidth || !rootHeight || !rootRect) {
+    return { targets: [], compositionTarget: null, gridEdges: null, snapEnabled };
+  }
+
+  const iframeRect = input.iframe.getBoundingClientRect();
+  const overlayRect = input.overlayEl.getBoundingClientRect();
+  const rootScaleX = iframeRect.width / rootWidth;
+  const rootScaleY = iframeRect.height / rootHeight;
+
+  const compositionOverlayRect: OverlayRect = {
+    left: iframeRect.left - overlayRect.left,
+    top: iframeRect.top - overlayRect.top,
+    width: iframeRect.width,
+    height: iframeRect.height,
+    editScaleX: rootScaleX,
+    editScaleY: rootScaleY,
+  };
+  const compositionTarget = buildCompositionSnapTarget(compositionOverlayRect);
+
+  const options: DomEditContextOptions = {
+    activeCompositionPath: input.activeCompositionPath,
+    isMasterView: true,
+  };
+  const layerItems = collectDomEditLayerItems(root, options);
+
+  const rects: Array<{ left: number; top: number; width: number; height: number }> = [];
+  const ids: string[] = [];
+
+  for (const item of layerItems) {
+    const key = item.key;
+    if (input.excludeKeys.has(key)) continue;
+
+    if (!isElementVisibleForOverlay(item.element)) continue;
+
+    const rect = toOverlayRect(input.overlayEl, input.iframe, item.element);
+    if (!rect) continue;
+
+    rects.push(rect);
+    ids.push(key);
+  }
+
+  const targets = extractSnapTargets(rects, ids);
+
+  let gridEdges: { x: SnapEdge[]; y: SnapEdge[] } | null = null;
+  const gridSpacing = prefs.gridSpacing ?? 50;
+  const snapToGrid = prefs.snapToGrid ?? false;
+  if (snapToGrid && gridSpacing > 0) {
+    gridEdges = buildGridSnapEdges(compositionOverlayRect, gridSpacing, rootScaleX);
+  }
+
+  return { targets, compositionTarget, gridEdges, snapEnabled };
+}
+
+export function buildExcludeKeys(input: {
+  selection?: DomEditSelection | null;
+  groupSelections?: DomEditSelection[];
+}): Set<string> {
+  const keys = new Set<string>();
+  if (input.selection) {
+    keys.add(selectionCacheKey(input.selection));
+  }
+  if (input.groupSelections) {
+    for (const sel of input.groupSelections) {
+      keys.add(selectionCacheKey(sel));
+    }
+  }
+  return keys;
+}

From 9207ba5f932f4ea2043ddc6764dbc7cf51353c3c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 12:03:41 -0400
Subject: [PATCH 03/11] feat(studio): wire snap engine into gesture handlers
 and preview overlay

Inject resolveSnapAdjustment into drag gestures and resolveResizeSnapAdjustment
into resize gestures. Snap targets collected at gesture start via
collectSnapContext. Alt/Option key temporarily disables snapping.
SnapGuideOverlay and GridOverlay rendered inside DomEditOverlay.
SnapToolbar added to StudioPreviewArea with S/G keyboard shortcuts.
---
 .../src/components/StudioPreviewArea.tsx      |  70 ++++++----
 .../src/components/editor/DomEditOverlay.tsx  |  36 +++++
 .../src/components/editor/GridOverlay.tsx     |   1 -
 .../components/editor/SnapGuideOverlay.tsx    |   1 -
 .../src/components/editor/SnapToolbar.tsx     |   1 -
 .../editor/domEditOverlayGestures.ts          |   3 +
 .../editor/domEditOverlayStartGesture.ts      |  28 ++++
 .../components/editor/snapTargetCollection.ts |   2 +-
 .../editor/useDomEditOverlayGestures.ts       | 131 +++++++++++++++++-
 9 files changed, 238 insertions(+), 35 deletions(-)

diff --git a/packages/studio/src/components/StudioPreviewArea.tsx b/packages/studio/src/components/StudioPreviewArea.tsx
index 63c161257b..ccb309495b 100644
--- a/packages/studio/src/components/StudioPreviewArea.tsx
+++ b/packages/studio/src/components/StudioPreviewArea.tsx
@@ -1,8 +1,9 @@
-import type { ReactNode } from "react";
+import { useState, type ReactNode } from "react";
 import { NLELayout } from "./nle/NLELayout";
 import { CaptionOverlay } from "../captions/components/CaptionOverlay";
 import { CaptionTimeline } from "../captions/components/CaptionTimeline";
 import { DomEditOverlay } from "./editor/DomEditOverlay";
+import { SnapToolbar } from "./editor/SnapToolbar";
 import { StudioFeedbackBar } from "./StudioFeedbackBar";
 import type { TimelineElement } from "../player";
 import type { BlockedTimelineEditIntent } from "../player/components/timelineEditing";
@@ -14,6 +15,7 @@ import {
 import { useStudioContext } from "../contexts/StudioContext";
 import { useDomEditContext } from "../contexts/DomEditContext";
 import type { BlockPreviewInfo } from "./sidebar/BlocksTab";
+import { readStudioUiPreferences } from "../utils/studioUiPreferences";
 
 export interface StudioPreviewAreaProps {
   timelineToolbar: ReactNode;
@@ -103,6 +105,17 @@ export function StudioPreviewArea({
     handleDomRotationCommit,
   } = useDomEditContext();
 
+  // fallow-ignore-next-line complexity
+  const [snapPrefs, setSnapPrefs] = useState(() => {
+    const p = readStudioUiPreferences();
+    return {
+      snapEnabled: p.snapEnabled ?? true,
+      gridVisible: p.gridVisible ?? false,
+      gridSpacing: p.gridSpacing ?? 50,
+      snapToGrid: p.snapToGrid ?? false,
+    };
+  });
+
   return (
     <div className="flex-1 flex flex-col relative min-w-0">
       <div className="flex-1 min-h-0 relative">
@@ -157,31 +170,36 @@ export function StudioPreviewArea({
             ) : captionEditMode ? (
               <CaptionOverlay iframeRef={previewIframeRef} />
             ) : STUDIO_INSPECTOR_PANELS_ENABLED ? (
-              <DomEditOverlay
-                iframeRef={previewIframeRef}
-                activeCompositionPath={activeCompPath}
-                hoverSelection={
-                  STUDIO_PREVIEW_SELECTION_ENABLED &&
-                  !captionEditMode &&
-                  !compositionLoading &&
-                  !isPlaying
-                    ? domEditHoverSelection
-                    : null
-                }
-                selection={shouldShowSelectedDomBounds ? domEditSelection : null}
-                groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
-                allowCanvasMovement={STUDIO_PREVIEW_MANUAL_EDITING_ENABLED}
-                onCanvasMouseDown={handlePreviewCanvasMouseDown}
-                onCanvasPointerMove={handlePreviewCanvasPointerMove}
-                onCanvasPointerLeave={handlePreviewCanvasPointerLeave}
-                onSelectionChange={applyDomSelection}
-                onBlockedMove={handleBlockedDomMove}
-                onManualDragStart={handleDomManualDragStart}
-                onPathOffsetCommit={handleDomPathOffsetCommit}
-                onGroupPathOffsetCommit={handleDomGroupPathOffsetCommit}
-                onBoxSizeCommit={handleDomBoxSizeCommit}
-                onRotationCommit={handleDomRotationCommit}
-              />
+              <>
+                <DomEditOverlay
+                  iframeRef={previewIframeRef}
+                  activeCompositionPath={activeCompPath}
+                  hoverSelection={
+                    STUDIO_PREVIEW_SELECTION_ENABLED &&
+                    !captionEditMode &&
+                    !compositionLoading &&
+                    !isPlaying
+                      ? domEditHoverSelection
+                      : null
+                  }
+                  selection={shouldShowSelectedDomBounds ? domEditSelection : null}
+                  groupSelections={shouldShowSelectedDomBounds ? domEditGroupSelections : []}
+                  allowCanvasMovement={STUDIO_PREVIEW_MANUAL_EDITING_ENABLED}
+                  onCanvasMouseDown={handlePreviewCanvasMouseDown}
+                  onCanvasPointerMove={handlePreviewCanvasPointerMove}
+                  onCanvasPointerLeave={handlePreviewCanvasPointerLeave}
+                  onSelectionChange={applyDomSelection}
+                  onBlockedMove={handleBlockedDomMove}
+                  onManualDragStart={handleDomManualDragStart}
+                  onPathOffsetCommit={handleDomPathOffsetCommit}
+                  onGroupPathOffsetCommit={handleDomGroupPathOffsetCommit}
+                  onBoxSizeCommit={handleDomBoxSizeCommit}
+                  onRotationCommit={handleDomRotationCommit}
+                  gridVisible={snapPrefs.gridVisible}
+                  gridSpacing={snapPrefs.gridSpacing}
+                />
+                <SnapToolbar onSnapChange={setSnapPrefs} />
+              </>
             ) : null
           }
           timelineFooter={
diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index 56d446c830..0896c1a04b 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -10,6 +10,8 @@ import {
 } from "./domEditOverlayGestures";
 import { useDomEditOverlayRects } from "./useDomEditOverlayRects";
 import { createDomEditOverlayGestureHandlers } from "./useDomEditOverlayGestures";
+import { SnapGuideOverlay, type SnapGuidesState } from "./SnapGuideOverlay";
+import { GridOverlay } from "./GridOverlay";
 
 // Re-exports for external consumers — preserving existing import paths.
 export {
@@ -61,6 +63,14 @@ interface DomEditOverlayProps {
     next: { width: number; height: number },
   ) => Promise<void> | void;
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
+  gridVisible?: boolean;
+  gridSpacing?: number;
+  compositionScaleX?: number;
+  compositionScaleY?: number;
+  compositionLeft?: number;
+  compositionTop?: number;
+  compositionWidth?: number;
+  compositionHeight?: number;
 }
 
 export const DomEditOverlay = memo(function DomEditOverlay({
@@ -75,6 +85,14 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onCanvasPointerLeave,
   onSelectionChange,
   onBlockedMove,
+  gridVisible = false,
+  gridSpacing = 50,
+  compositionScaleX = 1,
+  compositionScaleY = 1,
+  compositionLeft = 0,
+  compositionTop = 0,
+  compositionWidth = 0,
+  compositionHeight = 0,
   onManualDragStart,
   onPathOffsetCommit,
   onGroupPathOffsetCommit,
@@ -89,6 +107,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   const suppressNextBoxClickRef = useRef(false);
   const suppressNextBoxMouseDownRef = useRef(false);
   const suppressNextOverlayMouseDownRef = useRef(false);
+  const snapGuidesRef = useRef<SnapGuidesState | null>(null);
   const rafPausedRef = useRef(false);
 
   const selectionRef = useRef(selection);
@@ -158,6 +177,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     onRotationCommitRef,
     onCanvasPointerMoveRef,
     onCanvasMouseDown,
+    snapGuidesRef,
   });
 
   const selectionKey = useMemo(() => {
@@ -192,6 +212,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     }
   };
 
+  // fallow-ignore-next-line complexity
   const handleOverlayPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
     if (!allowCanvasMovement || event.button !== 0) return;
     if (event.shiftKey) {
@@ -387,6 +408,21 @@ export const DomEditOverlay = memo(function DomEditOverlay({
           </div>
         </>
       )}
+      <GridOverlay
+        visible={gridVisible}
+        spacing={gridSpacing}
+        scaleX={compositionScaleX}
+        scaleY={compositionScaleY}
+        compositionLeft={compositionLeft}
+        compositionTop={compositionTop}
+        compositionWidth={compositionWidth}
+        compositionHeight={compositionHeight}
+      />
+      <SnapGuideOverlay
+        snapGuidesRef={snapGuidesRef}
+        overlayWidth={compositionWidth}
+        overlayHeight={compositionHeight}
+      />
     </div>
   );
 });
diff --git a/packages/studio/src/components/editor/GridOverlay.tsx b/packages/studio/src/components/editor/GridOverlay.tsx
index 1ca973a806..2a65db6f1e 100644
--- a/packages/studio/src/components/editor/GridOverlay.tsx
+++ b/packages/studio/src/components/editor/GridOverlay.tsx
@@ -1,4 +1,3 @@
-// fallow-ignore-file unused-file
 import { memo } from "react";
 
 interface GridOverlayProps {
diff --git a/packages/studio/src/components/editor/SnapGuideOverlay.tsx b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
index e599bef9b7..cd4ba20ba1 100644
--- a/packages/studio/src/components/editor/SnapGuideOverlay.tsx
+++ b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
@@ -1,4 +1,3 @@
-// fallow-ignore-file unused-file
 import { memo, useRef, type RefObject } from "react";
 import { useMountEffect } from "../../hooks/useMountEffect";
 import type { SnapGuide, SpacingGuide } from "./snapEngine";
diff --git a/packages/studio/src/components/editor/SnapToolbar.tsx b/packages/studio/src/components/editor/SnapToolbar.tsx
index 9f28c4202a..d829a0ea56 100644
--- a/packages/studio/src/components/editor/SnapToolbar.tsx
+++ b/packages/studio/src/components/editor/SnapToolbar.tsx
@@ -1,4 +1,3 @@
-// fallow-ignore-file unused-file
 import { memo, useCallback, useEffect, useRef, useState } from "react";
 import { MagnetStraight, GridFour } from "@phosphor-icons/react";
 import { readStudioUiPreferences, writeStudioUiPreferences } from "../../utils/studioUiPreferences";
diff --git a/packages/studio/src/components/editor/domEditOverlayGestures.ts b/packages/studio/src/components/editor/domEditOverlayGestures.ts
index 40d678d2fa..f27520749b 100644
--- a/packages/studio/src/components/editor/domEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/domEditOverlayGestures.ts
@@ -6,6 +6,7 @@ import type {
 } from "./manualEdits";
 import type { ManualOffsetDragMember } from "./manualOffsetDrag";
 import type { GroupOverlayItem } from "./domEditOverlayGeometry";
+import type { SnapContext } from "./snapTargetCollection";
 
 export type GestureKind = "drag" | "resize" | "rotate";
 
@@ -36,6 +37,7 @@ export interface GestureState {
   editScaleX: number;
   editScaleY: number;
   manualEditDragToken?: string;
+  snapContext?: SnapContext;
 }
 
 export interface GroupGestureState {
@@ -43,6 +45,7 @@ export interface GroupGestureState {
   startY: number;
   originItems: GroupOverlayItem[];
   members: ManualOffsetDragMember[];
+  snapContext?: SnapContext;
 }
 
 export interface BlockedMoveState {
diff --git a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
index 5920b4b15d..6db88fd1f8 100644
--- a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
+++ b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
@@ -23,6 +23,7 @@ import {
 } from "./domEditOverlayGeometry";
 import { type GestureKind, type GestureState } from "./domEditOverlayGestures";
 import type { UseDomEditOverlayGesturesOptions } from "./useDomEditOverlayGestures";
+import { collectSnapContext, buildExcludeKeys } from "./snapTargetCollection";
 
 export function startGroupDrag(
   e: React.PointerEvent<HTMLElement>,
@@ -61,6 +62,18 @@ export function startGroupDrag(
     members.push(result.member);
   }
 
+  const overlayEl = opts.overlayRef.current;
+  const iframe = opts.iframeRef.current;
+  const snapContext =
+    overlayEl && iframe
+      ? collectSnapContext({
+          overlayEl,
+          iframe,
+          excludeKeys: buildExcludeKeys({ groupSelections: items.map((i) => i.selection) }),
+          activeCompositionPath: null,
+        })
+      : undefined;
+
   e.preventDefault();
   e.stopPropagation();
   e.currentTarget.setPointerCapture(e.pointerId);
@@ -70,10 +83,12 @@ export function startGroupDrag(
     startY: e.clientY,
     originItems: items,
     members,
+    snapContext,
   };
   return true;
 }
 
+// fallow-ignore-next-line complexity
 export function startGesture(
   kind: GestureKind,
   e: React.PointerEvent<HTMLElement>,
@@ -124,6 +139,18 @@ export function startGesture(
   const overlayBounds = overlayEl?.getBoundingClientRect();
   const centerX = (overlayBounds?.left ?? 0) + rect.left + rect.width / 2;
   const centerY = (overlayBounds?.top ?? 0) + rect.top + rect.height / 2;
+
+  const iframe = opts.iframeRef.current;
+  const snapContext =
+    (kind === "drag" || kind === "resize") && overlayEl && iframe
+      ? collectSnapContext({
+          overlayEl,
+          iframe,
+          excludeKeys: buildExcludeKeys({ selection: sel }),
+          activeCompositionPath: null,
+        })
+      : undefined;
+
   e.preventDefault();
   e.stopPropagation();
   e.currentTarget.setPointerCapture(e.pointerId);
@@ -150,6 +177,7 @@ export function startGesture(
     editScaleX: rect.editScaleX,
     editScaleY: rect.editScaleY,
     manualEditDragToken,
+    snapContext,
   };
   return true;
 }
diff --git a/packages/studio/src/components/editor/snapTargetCollection.ts b/packages/studio/src/components/editor/snapTargetCollection.ts
index 89d4044d04..6c17c8ed98 100644
--- a/packages/studio/src/components/editor/snapTargetCollection.ts
+++ b/packages/studio/src/components/editor/snapTargetCollection.ts
@@ -1,4 +1,4 @@
-// fallow-ignore-file unused-file code-duplication
+// fallow-ignore-file code-duplication
 import type { DomEditSelection } from "./domEditing";
 import type { DomEditContextOptions } from "./domEditingTypes";
 import { collectDomEditLayerItems } from "./domEditingLayers";
diff --git a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
index 19a7ecf00c..cbfdeea116 100644
--- a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 /**
  * Gesture handling for DomEditOverlay.
  * Owns: onPointerMove, onPointerUp, clearPointerState.
@@ -23,7 +24,12 @@ import {
   restoreStudioPathOffset,
   restoreStudioRotation,
 } from "./manualEdits";
-import { type GroupOverlayItem, type OverlayRect, toOverlayRect } from "./domEditOverlayGeometry";
+import {
+  type GroupOverlayItem,
+  type OverlayRect,
+  resolveDomEditGroupOverlayRect,
+  toOverlayRect,
+} from "./domEditOverlayGeometry";
 import {
   BLOCKED_MOVE_THRESHOLD_PX,
   type BlockedMoveState,
@@ -39,6 +45,13 @@ import {
   startGesture as _startGesture,
   startGroupDrag as _startGroupDrag,
 } from "./domEditOverlayStartGesture";
+import {
+  resolveSnapAdjustment,
+  resolveResizeSnapAdjustment,
+  resolveEquidistanceGuides,
+  SNAP_THRESHOLD_PX,
+} from "./snapEngine";
+import type { SnapGuidesState } from "./SnapGuideOverlay";
 
 // Refs are stable across renders; values are read via .current.
 export type UseDomEditOverlayGesturesOptions = {
@@ -79,6 +92,7 @@ export type UseDomEditOverlayGesturesOptions = {
     e: React.MouseEvent<HTMLDivElement>,
     o?: { preferClipAncestor?: boolean },
   ) => void;
+  snapGuidesRef: RefObject<SnapGuidesState | null>;
 };
 
 export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGesturesOptions) {
@@ -111,6 +125,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     options?: { selection?: DomEditSelection; rect?: OverlayRect | null },
   ) => _startGesture(kind, e, opts, options);
 
+  // fallow-ignore-next-line complexity
   const onPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
     const g = opts.gestureRef.current;
     const groupG = opts.groupGestureRef.current;
@@ -133,8 +148,46 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (groupG) {
-      const dx = e.clientX - groupG.startX;
-      const dy = e.clientY - groupG.startY;
+      let dx = e.clientX - groupG.startX;
+      let dy = e.clientY - groupG.startY;
+
+      const sc = groupG.snapContext;
+      if (sc?.snapEnabled && sc.targets.length > 0) {
+        const groupBounds = resolveDomEditGroupOverlayRect(
+          groupG.originItems.map((item) => item.rect),
+        );
+        if (groupBounds) {
+          const allTargets = sc.compositionTarget
+            ? [...sc.targets, sc.compositionTarget]
+            : sc.targets;
+          const snap = resolveSnapAdjustment({
+            movingRect: groupBounds,
+            proposedDx: dx,
+            proposedDy: dy,
+            targets: allTargets,
+            gridEdges: sc.gridEdges ?? undefined,
+            threshold: SNAP_THRESHOLD_PX,
+            disabled: e.altKey,
+          });
+          dx = snap.dx;
+          dy = snap.dy;
+          const movedRect = {
+            left: groupBounds.left + dx,
+            top: groupBounds.top + dy,
+            width: groupBounds.width,
+            height: groupBounds.height,
+          };
+          const spacingGuides = e.altKey
+            ? []
+            : resolveEquidistanceGuides({
+                movingRect: movedRect,
+                targets: allTargets,
+                threshold: SNAP_THRESHOLD_PX,
+              });
+          opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides };
+        }
+      }
+
       setDraftGroupOverlayItems(
         groupG.originItems.map((item) => ({
           ...item,
@@ -146,8 +199,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (!g || !sel) return;
-    const dx = e.clientX - g.startX;
-    const dy = e.clientY - g.startY;
+    let dx = e.clientX - g.startX;
+    let dy = e.clientY - g.startY;
 
     if (g.kind === "rotate") {
       applyStudioRotationDraft(
@@ -167,6 +220,44 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
 
     if (g.kind === "drag") {
+      const sc = g.snapContext;
+      if (sc?.snapEnabled) {
+        const movingRect = {
+          left: g.originLeft,
+          top: g.originTop,
+          width: g.originWidth,
+          height: g.originHeight,
+        };
+        const allTargets = sc.compositionTarget
+          ? [...sc.targets, sc.compositionTarget]
+          : sc.targets;
+        const snap = resolveSnapAdjustment({
+          movingRect,
+          proposedDx: dx,
+          proposedDy: dy,
+          targets: allTargets,
+          gridEdges: sc.gridEdges ?? undefined,
+          threshold: SNAP_THRESHOLD_PX,
+          disabled: e.altKey,
+        });
+        dx = snap.dx;
+        dy = snap.dy;
+        const movedRect = {
+          left: movingRect.left + dx,
+          top: movingRect.top + dy,
+          width: movingRect.width,
+          height: movingRect.height,
+        };
+        const spacingGuides = e.altKey
+          ? []
+          : resolveEquidistanceGuides({
+              movingRect: movedRect,
+              targets: allTargets,
+              threshold: SNAP_THRESHOLD_PX,
+            });
+        opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides };
+      }
+
       const nextBoxLeft = g.originLeft + dx;
       const nextBoxTop = g.originTop + dy;
       setDraftOverlayRect({
@@ -184,6 +275,32 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
       if (g.pathOffsetMember) applyManualOffsetDragDraft(g.pathOffsetMember, dx, dy);
     } else {
       if (!box) return;
+
+      const sc = g.snapContext;
+      if (sc?.snapEnabled) {
+        const movingRect = {
+          left: g.originLeft,
+          top: g.originTop,
+          width: g.originWidth,
+          height: g.originHeight,
+        };
+        const allTargets = sc.compositionTarget
+          ? [...sc.targets, sc.compositionTarget]
+          : sc.targets;
+        const snap = resolveResizeSnapAdjustment({
+          movingRect,
+          proposedDx: dx,
+          proposedDy: dy,
+          targets: allTargets,
+          gridEdges: sc.gridEdges ?? undefined,
+          threshold: SNAP_THRESHOLD_PX,
+          disabled: e.altKey,
+        });
+        dx = snap.dx;
+        dy = snap.dy;
+        opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides: [] };
+      }
+
       const nextSize = resolveDomEditResizeGesture({
         originWidth: g.originWidth,
         originHeight: g.originHeight,
@@ -223,7 +340,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
   };
 
+  // fallow-ignore-next-line complexity
   const onPointerUp = (e: React.PointerEvent<HTMLDivElement>) => {
+    opts.snapGuidesRef.current = null;
     const g = opts.gestureRef.current;
     const groupG = opts.groupGestureRef.current;
     const sel = g?.selection ?? opts.selectionRef.current;
@@ -372,7 +491,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     }
   };
 
+  // fallow-ignore-next-line complexity
   const clearPointerState = (selectionRef: RefObject<DomEditSelection | null>) => {
+    opts.snapGuidesRef.current = null;
     const groupG = opts.groupGestureRef.current;
     if (groupG) restoreGroupPathOffsets(groupG);
     const g = opts.gestureRef.current;

From 00af150e5503c56c1f33e545215a29206d88e509 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 12:17:45 -0400
Subject: [PATCH 04/11] fix(studio): compute composition rect inside
 DomEditOverlay for grid rendering

Track iframe-to-overlay rect via RAF loop instead of relying on external
props. Grid overlay now renders correctly at the composition's position
and scale.
---
 .../src/components/editor/DomEditOverlay.tsx  | 75 +++++++++++++------
 1 file changed, 54 insertions(+), 21 deletions(-)

diff --git a/packages/studio/src/components/editor/DomEditOverlay.tsx b/packages/studio/src/components/editor/DomEditOverlay.tsx
index 0896c1a04b..ec289fc78c 100644
--- a/packages/studio/src/components/editor/DomEditOverlay.tsx
+++ b/packages/studio/src/components/editor/DomEditOverlay.tsx
@@ -1,4 +1,5 @@
-import { memo, useMemo, useRef, type RefObject } from "react";
+import { memo, useMemo, useRef, useState, type RefObject } from "react";
+import { useMountEffect } from "../../hooks/useMountEffect";
 import { type DomEditSelection } from "./domEditing";
 import { resolveDomEditGroupOverlayRect, toOverlayRect } from "./domEditOverlayGeometry";
 import {
@@ -65,12 +66,6 @@ interface DomEditOverlayProps {
   onRotationCommit: (selection: DomEditSelection, next: { angle: number }) => Promise<void> | void;
   gridVisible?: boolean;
   gridSpacing?: number;
-  compositionScaleX?: number;
-  compositionScaleY?: number;
-  compositionLeft?: number;
-  compositionTop?: number;
-  compositionWidth?: number;
-  compositionHeight?: number;
 }
 
 export const DomEditOverlay = memo(function DomEditOverlay({
@@ -87,12 +82,6 @@ export const DomEditOverlay = memo(function DomEditOverlay({
   onBlockedMove,
   gridVisible = false,
   gridSpacing = 50,
-  compositionScaleX = 1,
-  compositionScaleY = 1,
-  compositionLeft = 0,
-  compositionTop = 0,
-  compositionWidth = 0,
-  compositionHeight = 0,
   onManualDragStart,
   onPathOffsetCommit,
   onGroupPathOffsetCommit,
@@ -155,6 +144,50 @@ export const DomEditOverlay = memo(function DomEditOverlay({
     rafPausedRef,
   });
 
+  const [compRect, setCompRect] = useState({
+    left: 0,
+    top: 0,
+    width: 0,
+    height: 0,
+    scaleX: 1,
+    scaleY: 1,
+  });
+  useMountEffect(() => {
+    let frame = 0;
+    // fallow-ignore-next-line complexity
+    const update = () => {
+      frame = requestAnimationFrame(update);
+      const iframe = iframeRef.current;
+      const overlayEl = overlayRef.current;
+      if (!iframe || !overlayEl) return;
+      const iRect = iframe.getBoundingClientRect();
+      const oRect = overlayEl.getBoundingClientRect();
+      const left = iRect.left - oRect.left;
+      const top = iRect.top - oRect.top;
+      if (iRect.width <= 0 || iRect.height <= 0) return;
+      const doc = iframe.contentDocument;
+      const root = doc?.querySelector<HTMLElement>("[data-composition-id]") ?? doc?.documentElement;
+      const dw = Number.parseFloat(root?.getAttribute("data-width") ?? "");
+      const dh = Number.parseFloat(root?.getAttribute("data-height") ?? "");
+      const scaleX = dw > 0 ? iRect.width / dw : 1;
+      const scaleY = dh > 0 ? iRect.height / dh : 1;
+      setCompRect((prev) => {
+        if (
+          Math.abs(prev.left - left) < 0.5 &&
+          Math.abs(prev.top - top) < 0.5 &&
+          Math.abs(prev.width - iRect.width) < 0.5 &&
+          Math.abs(prev.height - iRect.height) < 0.5 &&
+          Math.abs(prev.scaleX - scaleX) < 0.001 &&
+          Math.abs(prev.scaleY - scaleY) < 0.001
+        )
+          return prev;
+        return { left, top, width: iRect.width, height: iRect.height, scaleX, scaleY };
+      });
+    };
+    frame = requestAnimationFrame(update);
+    return () => cancelAnimationFrame(frame);
+  });
+
   const gestures = createDomEditOverlayGestureHandlers({
     overlayRef,
     iframeRef,
@@ -411,17 +444,17 @@ export const DomEditOverlay = memo(function DomEditOverlay({
       <GridOverlay
         visible={gridVisible}
         spacing={gridSpacing}
-        scaleX={compositionScaleX}
-        scaleY={compositionScaleY}
-        compositionLeft={compositionLeft}
-        compositionTop={compositionTop}
-        compositionWidth={compositionWidth}
-        compositionHeight={compositionHeight}
+        scaleX={compRect.scaleX}
+        scaleY={compRect.scaleY}
+        compositionLeft={compRect.left}
+        compositionTop={compRect.top}
+        compositionWidth={compRect.width}
+        compositionHeight={compRect.height}
       />
       <SnapGuideOverlay
         snapGuidesRef={snapGuidesRef}
-        overlayWidth={compositionWidth}
-        overlayHeight={compositionHeight}
+        overlayWidth={compRect.width}
+        overlayHeight={compRect.height}
       />
     </div>
   );

From 4587a7c2b6f517c5ee83694b3b1ceace2538a6f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 13:00:48 -0400
Subject: [PATCH 05/11] fix(studio): rewrite snap target collection to
 enumerate visible DOM elements directly

The previous approach used collectDomEditLayerItems which relies on
data-source-file attributes not present in the player iframe. Now
directly walks the iframe DOM tree, collects visible non-meta elements,
and computes their overlay rects via toOverlayRect.
---
 .../editor/domEditOverlayStartGesture.ts      | 11 +--
 .../components/editor/snapTargetCollection.ts | 70 +++++++++++--------
 2 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
index 6db88fd1f8..f252cfdda8 100644
--- a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
+++ b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
@@ -23,7 +23,7 @@ import {
 } from "./domEditOverlayGeometry";
 import { type GestureKind, type GestureState } from "./domEditOverlayGestures";
 import type { UseDomEditOverlayGesturesOptions } from "./useDomEditOverlayGestures";
-import { collectSnapContext, buildExcludeKeys } from "./snapTargetCollection";
+import { collectSnapContext, buildExcludeElements } from "./snapTargetCollection";
 
 export function startGroupDrag(
   e: React.PointerEvent<HTMLElement>,
@@ -69,8 +69,10 @@ export function startGroupDrag(
       ? collectSnapContext({
           overlayEl,
           iframe,
-          excludeKeys: buildExcludeKeys({ groupSelections: items.map((i) => i.selection) }),
-          activeCompositionPath: null,
+          excludeElements: buildExcludeElements({
+            iframe,
+            groupSelections: items.map((i) => i.selection),
+          }),
         })
       : undefined;
 
@@ -146,8 +148,7 @@ export function startGesture(
       ? collectSnapContext({
           overlayEl,
           iframe,
-          excludeKeys: buildExcludeKeys({ selection: sel }),
-          activeCompositionPath: null,
+          excludeElements: buildExcludeElements({ iframe, selection: sel }),
         })
       : undefined;
 
diff --git a/packages/studio/src/components/editor/snapTargetCollection.ts b/packages/studio/src/components/editor/snapTargetCollection.ts
index 6c17c8ed98..1fa2d3d2a3 100644
--- a/packages/studio/src/components/editor/snapTargetCollection.ts
+++ b/packages/studio/src/components/editor/snapTargetCollection.ts
@@ -1,10 +1,7 @@
 // fallow-ignore-file code-duplication
 import type { DomEditSelection } from "./domEditing";
-import type { DomEditContextOptions } from "./domEditingTypes";
-import { collectDomEditLayerItems } from "./domEditingLayers";
 import {
   isElementVisibleForOverlay,
-  selectionCacheKey,
   toOverlayRect,
   type OverlayRect,
 } from "./domEditOverlayGeometry";
@@ -30,12 +27,35 @@ function readPositiveDimension(value: string | null): number | null {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
 }
 
+const IGNORED_TAGS = new Set(["script", "style", "link", "meta", "base", "template", "br", "wbr"]);
+
+function collectVisibleElements(
+  root: HTMLElement,
+  excludeElements: Set<HTMLElement>,
+  maxItems: number,
+): HTMLElement[] {
+  const result: HTMLElement[] = [];
+  const visit = (el: HTMLElement) => {
+    if (result.length >= maxItems) return;
+    for (const child of Array.from(el.children)) {
+      if (!(child instanceof HTMLElement)) continue;
+      if (IGNORED_TAGS.has(child.tagName.toLowerCase())) continue;
+      if (child.hasAttribute("data-composition-id")) continue;
+      if (excludeElements.has(child)) continue;
+      if (!isElementVisibleForOverlay(child)) continue;
+      result.push(child);
+      visit(child);
+    }
+  };
+  visit(root);
+  return result;
+}
+
 // fallow-ignore-next-line complexity
 export function collectSnapContext(input: {
   overlayEl: HTMLDivElement;
   iframe: HTMLIFrameElement;
-  excludeKeys: Set<string>;
-  activeCompositionPath: string | null;
+  excludeElements: Set<HTMLElement>;
 }): SnapContext {
   const prefs = readStudioUiPreferences();
   const snapEnabled = prefs.snapEnabled ?? true;
@@ -45,7 +65,8 @@ export function collectSnapContext(input: {
     return { targets: [], compositionTarget: null, gridEdges: null, snapEnabled };
   }
 
-  const root = doc.querySelector<HTMLElement>("[data-composition-id]") ?? doc.documentElement;
+  const root =
+    doc.querySelector<HTMLElement>("[data-composition-id]") ?? (doc.documentElement as HTMLElement);
   const rootRect = root?.getBoundingClientRect();
   const declaredWidth = readPositiveDimension(root?.getAttribute("data-width") ?? null);
   const declaredHeight = readPositiveDimension(root?.getAttribute("data-height") ?? null);
@@ -71,26 +92,17 @@ export function collectSnapContext(input: {
   };
   const compositionTarget = buildCompositionSnapTarget(compositionOverlayRect);
 
-  const options: DomEditContextOptions = {
-    activeCompositionPath: input.activeCompositionPath,
-    isMasterView: true,
-  };
-  const layerItems = collectDomEditLayerItems(root, options);
+  const elements = collectVisibleElements(root, input.excludeElements, 80);
 
   const rects: Array<{ left: number; top: number; width: number; height: number }> = [];
   const ids: string[] = [];
 
-  for (const item of layerItems) {
-    const key = item.key;
-    if (input.excludeKeys.has(key)) continue;
-
-    if (!isElementVisibleForOverlay(item.element)) continue;
-
-    const rect = toOverlayRect(input.overlayEl, input.iframe, item.element);
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    const rect = toOverlayRect(input.overlayEl, input.iframe, el);
     if (!rect) continue;
-
     rects.push(rect);
-    ids.push(key);
+    ids.push(`snap-target-${i}`);
   }
 
   const targets = extractSnapTargets(rects, ids);
@@ -105,18 +117,20 @@ export function collectSnapContext(input: {
   return { targets, compositionTarget, gridEdges, snapEnabled };
 }
 
-export function buildExcludeKeys(input: {
+export function buildExcludeElements(input: {
+  iframe: HTMLIFrameElement;
   selection?: DomEditSelection | null;
   groupSelections?: DomEditSelection[];
-}): Set<string> {
-  const keys = new Set<string>();
-  if (input.selection) {
-    keys.add(selectionCacheKey(input.selection));
+}): Set<HTMLElement> {
+  const elements = new Set<HTMLElement>();
+  const sel = input.selection;
+  if (sel?.element) {
+    elements.add(sel.element);
   }
   if (input.groupSelections) {
-    for (const sel of input.groupSelections) {
-      keys.add(selectionCacheKey(sel));
+    for (const gs of input.groupSelections) {
+      if (gs.element) elements.add(gs.element);
     }
   }
-  return keys;
+  return elements;
 }

From 90778343d8db0c98c462e0d4303b2f4657691d9e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 13:02:34 -0400
Subject: [PATCH 06/11] fix(studio): use nodeType check instead of instanceof
 for cross-iframe elements

instanceof HTMLElement fails across iframe boundaries because each
window has its own HTMLElement constructor. Use nodeType === 1 instead.
---
 .../studio/src/components/editor/snapTargetCollection.ts    | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/studio/src/components/editor/snapTargetCollection.ts b/packages/studio/src/components/editor/snapTargetCollection.ts
index 1fa2d3d2a3..893bede2cc 100644
--- a/packages/studio/src/components/editor/snapTargetCollection.ts
+++ b/packages/studio/src/components/editor/snapTargetCollection.ts
@@ -29,6 +29,10 @@ function readPositiveDimension(value: string | null): number | null {
 
 const IGNORED_TAGS = new Set(["script", "style", "link", "meta", "base", "template", "br", "wbr"]);
 
+function isHtmlElement(node: Node): node is HTMLElement {
+  return node.nodeType === 1;
+}
+
 function collectVisibleElements(
   root: HTMLElement,
   excludeElements: Set<HTMLElement>,
@@ -38,7 +42,7 @@ function collectVisibleElements(
   const visit = (el: HTMLElement) => {
     if (result.length >= maxItems) return;
     for (const child of Array.from(el.children)) {
-      if (!(child instanceof HTMLElement)) continue;
+      if (!isHtmlElement(child)) continue;
       if (IGNORED_TAGS.has(child.tagName.toLowerCase())) continue;
       if (child.hasAttribute("data-composition-id")) continue;
       if (excludeElements.has(child)) continue;

From cd613f33bf6df915cfe5904948c4298482a38406 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 13:57:24 -0400
Subject: [PATCH 07/11] fix(studio): use refs for overlay dimensions in
 SnapGuideOverlay RAF loop

useMountEffect captures closure variables at mount time. overlayWidth
and overlayHeight were 0 at mount, so guide lines had zero dimensions.
Store them in refs updated on every render so the RAF loop always reads
current values. Remove debug console.logs.
---
 .../studio/src/components/editor/SnapGuideOverlay.tsx  | 10 ++++++++--
 .../components/editor/domEditOverlayStartGesture.ts    |  1 -
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/studio/src/components/editor/SnapGuideOverlay.tsx b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
index cd4ba20ba1..9d519bf756 100644
--- a/packages/studio/src/components/editor/SnapGuideOverlay.tsx
+++ b/packages/studio/src/components/editor/SnapGuideOverlay.tsx
@@ -28,6 +28,10 @@ export const SnapGuideOverlay = memo(function SnapGuideOverlay({
   const guideElsRef = useRef<(HTMLDivElement | null)[]>([]);
   const spacingElsRef = useRef<(HTMLDivElement | null)[]>([]);
   const spacingLabelElsRef = useRef<(HTMLSpanElement | null)[]>([]);
+  const overlayWidthRef = useRef(overlayWidth);
+  overlayWidthRef.current = overlayWidth;
+  const overlayHeightRef = useRef(overlayHeight);
+  overlayHeightRef.current = overlayHeight;
 
   useMountEffect(() => {
     let frame = 0;
@@ -39,6 +43,8 @@ export const SnapGuideOverlay = memo(function SnapGuideOverlay({
       const state = snapGuidesRef.current;
       const guides = state?.guides ?? [];
       const spacingGuides = state?.spacingGuides ?? [];
+      const w = overlayWidthRef.current;
+      const h = overlayHeightRef.current;
 
       for (let i = 0; i < MAX_GUIDES; i++) {
         const el = guideElsRef.current[i];
@@ -55,11 +61,11 @@ export const SnapGuideOverlay = memo(function SnapGuideOverlay({
           el.style.left = `${guide.position}px`;
           el.style.top = "0";
           el.style.width = "1px";
-          el.style.height = `${overlayHeight}px`;
+          el.style.height = `${h}px`;
         } else {
           el.style.left = "0";
           el.style.top = `${guide.position}px`;
-          el.style.width = `${overlayWidth}px`;
+          el.style.width = `${w}px`;
           el.style.height = "1px";
         }
       }
diff --git a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
index f252cfdda8..8b3dc4775c 100644
--- a/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
+++ b/packages/studio/src/components/editor/domEditOverlayStartGesture.ts
@@ -151,7 +151,6 @@ export function startGesture(
           excludeElements: buildExcludeElements({ iframe, selection: sel }),
         })
       : undefined;
-
   e.preventDefault();
   e.stopPropagation();
   e.currentTarget.setPointerCapture(e.pointerId);

From 80d1e58c00c9fafe2a0b048e97361295633dca7e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 19:41:54 -0400
Subject: [PATCH 08/11] feat(studio): add fit-content toggle for element sizing
 in property panel

Adds a "Fit Content" button in the Layout section of the inspector panel.
When activated, writes width:fit-content and height:fit-content to the
element's inline styles, causing it to shrink-wrap to its visible children.
W/H fields show "fit" and become read-only when fit-content is active.
Toggling off captures the current BCR and sets that as fixed pixel size.
---
 .../src/components/editor/PropertyPanel.tsx   | 42 ++++++++++++++++---
 1 file changed, 36 insertions(+), 6 deletions(-)

diff --git a/packages/studio/src/components/editor/PropertyPanel.tsx b/packages/studio/src/components/editor/PropertyPanel.tsx
index e93d2c1cd7..2cc9a21174 100644
--- a/packages/studio/src/components/editor/PropertyPanel.tsx
+++ b/packages/studio/src/components/editor/PropertyPanel.tsx
@@ -208,6 +208,9 @@ export const PropertyPanel = memo(function PropertyPanel({
   const manualOffsetEditingDisabled = !element.capabilities.canApplyManualOffset;
   const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize;
   const sourceLabel = element.id ? `#${element.id}` : element.selector;
+  const isFitWidth = styles.width === "fit-content";
+  const isFitHeight = styles.height === "fit-content";
+  const isFitContent = isFitWidth && isFitHeight;
   const showEditableSections = element.capabilities.canEditStyles;
   const manualOffset = readStudioPathOffset(element.element);
   const manualSize = readStudioBoxSize(element.element);
@@ -333,16 +336,16 @@ export const PropertyPanel = memo(function PropertyPanel({
             />
             <MetricField
               label="W"
-              value={formatPxMetricValue(resolvedWidth)}
-              disabled={manualSizeEditingDisabled}
-              scrub
+              value={isFitWidth ? "fit" : formatPxMetricValue(resolvedWidth)}
+              disabled={manualSizeEditingDisabled || isFitWidth}
+              scrub={!isFitWidth}
               onCommit={(next) => commitManualSize("width", next)}
             />
             <MetricField
               label="H"
-              value={formatPxMetricValue(resolvedHeight)}
-              disabled={manualSizeEditingDisabled}
-              scrub
+              value={isFitHeight ? "fit" : formatPxMetricValue(resolvedHeight)}
+              disabled={manualSizeEditingDisabled || isFitHeight}
+              scrub={!isFitHeight}
               onCommit={(next) => commitManualSize("height", next)}
             />
             <MetricField
@@ -359,6 +362,33 @@ export const PropertyPanel = memo(function PropertyPanel({
               onCommit={(next) => onSetStyle("z-index", next)}
             />
           </div>
+          {element.capabilities.canApplyManualSize && (
+            <div className="mt-3">
+              <button
+                type="button"
+                className={`w-full rounded-md px-2.5 py-1.5 text-[11px] font-medium transition-colors ${
+                  isFitContent
+                    ? "bg-studio-accent/20 text-studio-accent border border-studio-accent/30"
+                    : "bg-neutral-800 text-neutral-400 border border-neutral-700 hover:bg-neutral-750 hover:text-neutral-300"
+                }`}
+                onClick={() => {
+                  if (isFitContent) {
+                    const bcr = element.element.getBoundingClientRect();
+                    const w = Math.round(bcr.width) || 100;
+                    const h = Math.round(bcr.height) || 100;
+                    onSetStyle("width", `${w}px`);
+                    onSetStyle("height", `${h}px`);
+                  } else {
+                    onSetStyle("width", "fit-content");
+                    onSetStyle("height", "fit-content");
+                  }
+                }}
+                title={isFitContent ? "Switch to fixed size" : "Size to fit content"}
+              >
+                {isFitContent ? "Fit Content ✓" : "Fit Content"}
+              </button>
+            </div>
+          )}
         </Section>
 
         {STUDIO_GSAP_PANEL_ENABLED &&

From feff5b1d35a47ca950c0ee8bb5bd38cfad8a4fbe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 19:50:41 -0400
Subject: [PATCH 09/11] fix(studio): replace fit-content button with inline
 Fixed/Fit toggle

Segmented control between W/H fields and Z-index instead of
standalone button. Matches the visual language of the rest of the
property panel.
---
 .../src/components/editor/PropertyPanel.tsx   | 67 +++++++++++--------
 1 file changed, 40 insertions(+), 27 deletions(-)

diff --git a/packages/studio/src/components/editor/PropertyPanel.tsx b/packages/studio/src/components/editor/PropertyPanel.tsx
index 2cc9a21174..0fec0dc737 100644
--- a/packages/studio/src/components/editor/PropertyPanel.tsx
+++ b/packages/studio/src/components/editor/PropertyPanel.tsx
@@ -354,6 +354,46 @@ export const PropertyPanel = memo(function PropertyPanel({
               onCommit={(next) => commitManualRotation(next.replace("°", ""))}
             />
           </div>
+          {element.capabilities.canApplyManualSize && (
+            <div className="mt-2 flex items-center gap-2">
+              <span className="text-[10px] text-neutral-500 uppercase tracking-wider">Size</span>
+              <div className="flex rounded-md overflow-hidden border border-neutral-700">
+                <button
+                  type="button"
+                  className={`px-2.5 py-0.5 text-[10px] font-medium transition-colors ${
+                    !isFitContent
+                      ? "bg-neutral-700 text-neutral-200"
+                      : "bg-transparent text-neutral-500 hover:text-neutral-300"
+                  }`}
+                  onClick={() => {
+                    if (isFitContent) {
+                      const bcr = element.element.getBoundingClientRect();
+                      onSetStyle("width", `${Math.round(bcr.width) || 100}px`);
+                      onSetStyle("height", `${Math.round(bcr.height) || 100}px`);
+                    }
+                  }}
+                >
+                  Fixed
+                </button>
+                <button
+                  type="button"
+                  className={`px-2.5 py-0.5 text-[10px] font-medium transition-colors ${
+                    isFitContent
+                      ? "bg-neutral-700 text-neutral-200"
+                      : "bg-transparent text-neutral-500 hover:text-neutral-300"
+                  }`}
+                  onClick={() => {
+                    if (!isFitContent) {
+                      onSetStyle("width", "fit-content");
+                      onSetStyle("height", "fit-content");
+                    }
+                  }}
+                >
+                  Fit
+                </button>
+              </div>
+            </div>
+          )}
           <div className="mt-3">
             <MetricField
               label="Z-index"
@@ -362,33 +402,6 @@ export const PropertyPanel = memo(function PropertyPanel({
               onCommit={(next) => onSetStyle("z-index", next)}
             />
           </div>
-          {element.capabilities.canApplyManualSize && (
-            <div className="mt-3">
-              <button
-                type="button"
-                className={`w-full rounded-md px-2.5 py-1.5 text-[11px] font-medium transition-colors ${
-                  isFitContent
-                    ? "bg-studio-accent/20 text-studio-accent border border-studio-accent/30"
-                    : "bg-neutral-800 text-neutral-400 border border-neutral-700 hover:bg-neutral-750 hover:text-neutral-300"
-                }`}
-                onClick={() => {
-                  if (isFitContent) {
-                    const bcr = element.element.getBoundingClientRect();
-                    const w = Math.round(bcr.width) || 100;
-                    const h = Math.round(bcr.height) || 100;
-                    onSetStyle("width", `${w}px`);
-                    onSetStyle("height", `${h}px`);
-                  } else {
-                    onSetStyle("width", "fit-content");
-                    onSetStyle("height", "fit-content");
-                  }
-                }}
-                title={isFitContent ? "Switch to fixed size" : "Size to fit content"}
-              >
-                {isFitContent ? "Fit Content ✓" : "Fit Content"}
-              </button>
-            </div>
-          )}
         </Section>
 
         {STUDIO_GSAP_PANEL_ENABLED &&

From ceb6c204e244f14a13691f8ea26ff274054d8c71 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 19:55:52 -0400
Subject: [PATCH 10/11] fix(studio): replace fit-content toggle with icon
 button and fix sizing

---
 .../src/components/editor/PropertyPanel.tsx   | 135 ++++++++++--------
 1 file changed, 78 insertions(+), 57 deletions(-)

diff --git a/packages/studio/src/components/editor/PropertyPanel.tsx b/packages/studio/src/components/editor/PropertyPanel.tsx
index 0fec0dc737..c2c751ab47 100644
--- a/packages/studio/src/components/editor/PropertyPanel.tsx
+++ b/packages/studio/src/components/editor/PropertyPanel.tsx
@@ -1,7 +1,12 @@
 import { memo } from "react";
 import { Clock, Eye, Layers, MessageSquare, Move, X } from "../../icons/SystemIcons";
 import { type DomEditSelection } from "./domEditing";
-import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
+import {
+  readStudioBoxSize,
+  readStudioPathOffset,
+  readStudioRotation,
+  clearStudioBoxSize,
+} from "./manualEdits";
 import type { ImportedFontAsset } from "./fontAssets";
 import {
   EMPTY_STYLES,
@@ -334,67 +339,83 @@ export const PropertyPanel = memo(function PropertyPanel({
               scrub
               onCommit={(next) => commitManualOffset("y", next)}
             />
-            <MetricField
-              label="W"
-              value={isFitWidth ? "fit" : formatPxMetricValue(resolvedWidth)}
-              disabled={manualSizeEditingDisabled || isFitWidth}
-              scrub={!isFitWidth}
-              onCommit={(next) => commitManualSize("width", next)}
-            />
-            <MetricField
-              label="H"
-              value={isFitHeight ? "fit" : formatPxMetricValue(resolvedHeight)}
-              disabled={manualSizeEditingDisabled || isFitHeight}
-              scrub={!isFitHeight}
-              onCommit={(next) => commitManualSize("height", next)}
-            />
+          </div>
+          <div className="mt-2 flex items-center gap-1.5">
+            <div className="flex-1">
+              <MetricField
+                label="W"
+                value={isFitWidth ? "fit" : formatPxMetricValue(resolvedWidth)}
+                disabled={manualSizeEditingDisabled || isFitWidth}
+                scrub={!isFitWidth}
+                onCommit={(next) => commitManualSize("width", next)}
+              />
+            </div>
+            <div className="flex-1">
+              <MetricField
+                label="H"
+                value={isFitHeight ? "fit" : formatPxMetricValue(resolvedHeight)}
+                disabled={manualSizeEditingDisabled || isFitHeight}
+                scrub={!isFitHeight}
+                onCommit={(next) => commitManualSize("height", next)}
+              />
+            </div>
+            {element.capabilities.canApplyManualSize && (
+              <button
+                type="button"
+                className={`flex-shrink-0 rounded p-1 transition-colors ${
+                  isFitContent
+                    ? "text-studio-accent bg-studio-accent/10"
+                    : "text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800"
+                }`}
+                onClick={() => {
+                  if (isFitContent) {
+                    const bcr = element.element.getBoundingClientRect();
+                    onSetStyle("width", `${Math.round(bcr.width) || 100}px`);
+                    onSetStyle("height", `${Math.round(bcr.height) || 100}px`);
+                  } else {
+                    clearStudioBoxSize(element.element);
+                    onSetStyle("width", "fit-content");
+                    onSetStyle("height", "fit-content");
+                    element.element.style.setProperty("width", "fit-content");
+                    element.element.style.setProperty("height", "fit-content");
+                  }
+                }}
+                title={isFitContent ? "Fixed size" : "Fit to content"}
+              >
+                <svg
+                  width="14"
+                  height="14"
+                  viewBox="0 0 14 14"
+                  fill="none"
+                  xmlns="http://www.w3.org/2000/svg"
+                >
+                  <path
+                    d="M2 4V2h2M10 2h2v2M12 10v2h-2M4 12H2v-2"
+                    stroke="currentColor"
+                    strokeWidth="1.2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                  <rect
+                    x="4.5"
+                    y="4.5"
+                    width="5"
+                    height="5"
+                    rx="0.5"
+                    stroke="currentColor"
+                    strokeWidth="1"
+                    strokeDasharray="1.5 1.5"
+                  />
+                </svg>
+              </button>
+            )}
+          </div>
+          <div className={`mt-2 ${RESPONSIVE_GRID}`}>
             <MetricField
               label="R"
               value={`${manualRotation.angle}°`}
               onCommit={(next) => commitManualRotation(next.replace("°", ""))}
             />
-          </div>
-          {element.capabilities.canApplyManualSize && (
-            <div className="mt-2 flex items-center gap-2">
-              <span className="text-[10px] text-neutral-500 uppercase tracking-wider">Size</span>
-              <div className="flex rounded-md overflow-hidden border border-neutral-700">
-                <button
-                  type="button"
-                  className={`px-2.5 py-0.5 text-[10px] font-medium transition-colors ${
-                    !isFitContent
-                      ? "bg-neutral-700 text-neutral-200"
-                      : "bg-transparent text-neutral-500 hover:text-neutral-300"
-                  }`}
-                  onClick={() => {
-                    if (isFitContent) {
-                      const bcr = element.element.getBoundingClientRect();
-                      onSetStyle("width", `${Math.round(bcr.width) || 100}px`);
-                      onSetStyle("height", `${Math.round(bcr.height) || 100}px`);
-                    }
-                  }}
-                >
-                  Fixed
-                </button>
-                <button
-                  type="button"
-                  className={`px-2.5 py-0.5 text-[10px] font-medium transition-colors ${
-                    isFitContent
-                      ? "bg-neutral-700 text-neutral-200"
-                      : "bg-transparent text-neutral-500 hover:text-neutral-300"
-                  }`}
-                  onClick={() => {
-                    if (!isFitContent) {
-                      onSetStyle("width", "fit-content");
-                      onSetStyle("height", "fit-content");
-                    }
-                  }}
-                >
-                  Fit
-                </button>
-              </div>
-            </div>
-          )}
-          <div className="mt-3">
             <MetricField
               label="Z-index"
               value={String(parseInt(styles["z-index"] || "auto", 10) || 0)}

From e62f8b2203d5d20b199f1ddc48912f4fff850ff2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Miguel=20=C3=81ngel?= <miguel.sierra@heygen.com>
Date: Thu, 4 Jun 2026 20:06:58 -0400
Subject: [PATCH 11/11] fix(studio): fit-to-children uses BCR union and snap
 commit uses snapped deltas

---
 .../src/components/editor/PropertyPanel.tsx   | 58 +++++++++----------
 .../editor/domEditOverlayGestures.ts          |  4 ++
 .../editor/useDomEditOverlayGestures.ts       | 16 +++--
 3 files changed, 42 insertions(+), 36 deletions(-)

diff --git a/packages/studio/src/components/editor/PropertyPanel.tsx b/packages/studio/src/components/editor/PropertyPanel.tsx
index c2c751ab47..0dc4e873d6 100644
--- a/packages/studio/src/components/editor/PropertyPanel.tsx
+++ b/packages/studio/src/components/editor/PropertyPanel.tsx
@@ -1,12 +1,7 @@
 import { memo } from "react";
 import { Clock, Eye, Layers, MessageSquare, Move, X } from "../../icons/SystemIcons";
 import { type DomEditSelection } from "./domEditing";
-import {
-  readStudioBoxSize,
-  readStudioPathOffset,
-  readStudioRotation,
-  clearStudioBoxSize,
-} from "./manualEdits";
+import { readStudioBoxSize, readStudioPathOffset, readStudioRotation } from "./manualEdits";
 import type { ImportedFontAsset } from "./fontAssets";
 import {
   EMPTY_STYLES,
@@ -213,9 +208,6 @@ export const PropertyPanel = memo(function PropertyPanel({
   const manualOffsetEditingDisabled = !element.capabilities.canApplyManualOffset;
   const manualSizeEditingDisabled = !element.capabilities.canApplyManualSize;
   const sourceLabel = element.id ? `#${element.id}` : element.selector;
-  const isFitWidth = styles.width === "fit-content";
-  const isFitHeight = styles.height === "fit-content";
-  const isFitContent = isFitWidth && isFitHeight;
   const showEditableSections = element.capabilities.canEditStyles;
   const manualOffset = readStudioPathOffset(element.element);
   const manualSize = readStudioBoxSize(element.element);
@@ -344,43 +336,47 @@ export const PropertyPanel = memo(function PropertyPanel({
             <div className="flex-1">
               <MetricField
                 label="W"
-                value={isFitWidth ? "fit" : formatPxMetricValue(resolvedWidth)}
-                disabled={manualSizeEditingDisabled || isFitWidth}
-                scrub={!isFitWidth}
+                value={formatPxMetricValue(resolvedWidth)}
+                disabled={manualSizeEditingDisabled}
+                scrub
                 onCommit={(next) => commitManualSize("width", next)}
               />
             </div>
             <div className="flex-1">
               <MetricField
                 label="H"
-                value={isFitHeight ? "fit" : formatPxMetricValue(resolvedHeight)}
-                disabled={manualSizeEditingDisabled || isFitHeight}
-                scrub={!isFitHeight}
+                value={formatPxMetricValue(resolvedHeight)}
+                disabled={manualSizeEditingDisabled}
+                scrub
                 onCommit={(next) => commitManualSize("height", next)}
               />
             </div>
             {element.capabilities.canApplyManualSize && (
               <button
                 type="button"
-                className={`flex-shrink-0 rounded p-1 transition-colors ${
-                  isFitContent
-                    ? "text-studio-accent bg-studio-accent/10"
-                    : "text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800"
-                }`}
+                className="flex-shrink-0 rounded p-1 transition-colors text-neutral-500 hover:text-neutral-300 hover:bg-neutral-800"
                 onClick={() => {
-                  if (isFitContent) {
-                    const bcr = element.element.getBoundingClientRect();
-                    onSetStyle("width", `${Math.round(bcr.width) || 100}px`);
-                    onSetStyle("height", `${Math.round(bcr.height) || 100}px`);
-                  } else {
-                    clearStudioBoxSize(element.element);
-                    onSetStyle("width", "fit-content");
-                    onSetStyle("height", "fit-content");
-                    element.element.style.setProperty("width", "fit-content");
-                    element.element.style.setProperty("height", "fit-content");
+                  const el = element.element;
+                  const children = Array.from(el.children).filter(
+                    (c): c is HTMLElement => c.nodeType === 1,
+                  );
+                  if (children.length === 0) return;
+                  const parentRect = el.getBoundingClientRect();
+                  let maxRight = 0;
+                  let maxBottom = 0;
+                  for (const child of children) {
+                    const cr = child.getBoundingClientRect();
+                    if (cr.width <= 0 && cr.height <= 0) continue;
+                    const right = cr.right - parentRect.left;
+                    const bottom = cr.bottom - parentRect.top;
+                    if (right > maxRight) maxRight = right;
+                    if (bottom > maxBottom) maxBottom = bottom;
                   }
+                  const w = Math.max(1, Math.round(maxRight));
+                  const h = Math.max(1, Math.round(maxBottom));
+                  onSetManualSize(element, { width: w, height: h });
                 }}
-                title={isFitContent ? "Fixed size" : "Fit to content"}
+                title="Fit to visible children"
               >
                 <svg
                   width="14"
diff --git a/packages/studio/src/components/editor/domEditOverlayGestures.ts b/packages/studio/src/components/editor/domEditOverlayGestures.ts
index f27520749b..be342a9871 100644
--- a/packages/studio/src/components/editor/domEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/domEditOverlayGestures.ts
@@ -38,6 +38,8 @@ export interface GestureState {
   editScaleY: number;
   manualEditDragToken?: string;
   snapContext?: SnapContext;
+  lastSnappedDx?: number;
+  lastSnappedDy?: number;
 }
 
 export interface GroupGestureState {
@@ -46,6 +48,8 @@ export interface GroupGestureState {
   originItems: GroupOverlayItem[];
   members: ManualOffsetDragMember[];
   snapContext?: SnapContext;
+  lastSnappedDx?: number;
+  lastSnappedDy?: number;
 }
 
 export interface BlockedMoveState {
diff --git a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
index cbfdeea116..72db032580 100644
--- a/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
+++ b/packages/studio/src/components/editor/useDomEditOverlayGestures.ts
@@ -187,6 +187,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
           opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides };
         }
       }
+      groupG.lastSnappedDx = dx;
+      groupG.lastSnappedDy = dy;
 
       setDraftGroupOverlayItems(
         groupG.originItems.map((item) => ({
@@ -257,6 +259,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
             });
         opts.snapGuidesRef.current = { guides: snap.guides, spacingGuides };
       }
+      g.lastSnappedDx = dx;
+      g.lastSnappedDy = dy;
 
       const nextBoxLeft = g.originLeft + dx;
       const nextBoxTop = g.originTop + dy;
@@ -352,13 +356,15 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
     if (groupG) {
       opts.groupGestureRef.current = null;
       opts.rafPausedRef.current = false;
-      const dx = e.clientX - groupG.startX;
-      const dy = e.clientY - groupG.startY;
-      if (Math.hypot(dx, dy) < BLOCKED_MOVE_THRESHOLD_PX) {
+      const rawDx = e.clientX - groupG.startX;
+      const rawDy = e.clientY - groupG.startY;
+      if (Math.hypot(rawDx, rawDy) < BLOCKED_MOVE_THRESHOLD_PX) {
         restoreGroupPathOffsets(groupG);
         opts.suppressNextBoxClickRef.current = true;
         return;
       }
+      const dx = groupG.lastSnappedDx ?? rawDx;
+      const dy = groupG.lastSnappedDy ?? rawDy;
       setDraftGroupOverlayItems(
         groupG.originItems.map((item) => ({
           ...item,
@@ -446,8 +452,8 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
         })
         .finally(() => endStudioManualEditGesture(sel.element, g.manualEditDragToken));
     } else if (g.kind === "drag") {
-      const dx = e.clientX - g.startX;
-      const dy = e.clientY - g.startY;
+      const dx = g.lastSnappedDx ?? e.clientX - g.startX;
+      const dy = g.lastSnappedDy ?? e.clientY - g.startY;
       if (!g.pathOffsetMember) return;
       const finalOffset = applyManualOffsetDragCommit(g.pathOffsetMember, dx, dy);
       const nextBoxLeft = g.originLeft + dx;