@hyperframes/studio 0.7.15 → 0.7.16

package/src/components/editor/Transform3DCube.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { projectAxes, projectCubeFaces, wrapDeg } from "./transform3dProjection";
 
 export interface CubePose {
@@ -22,80 +22,19 @@ const SENSITIVITY = 0.6; // degrees per pixel of drag
  * Presentational only: emits a live draft pose while dragging and a final pose
  * on release — the parent owns live-previewing and committing to GSAP props.
  */
-// transformPerspective (px) is inversely related to effect strength, with 0 = off.
-// Map a 0..1 slider strength to px and to the cube's weak-perspective projection.
-const STRONG_PX = 200;
-const WEAK_PX = 1600;
-const PX_RANGE = WEAK_PX - STRONG_PX;
-const strengthToPx = (s: number) => (s <= 0.01 ? 0 : Math.round(WEAK_PX - s * PX_RANGE));
-const pxToStrength = (px: number) =>
-  px <= 0
-    ? 0
-    : Math.max(0, Math.min(1, (WEAK_PX - Math.max(STRONG_PX, Math.min(WEAK_PX, px))) / PX_RANGE));
+// transformPerspective (px) drives the cube's weak-perspective projection;
+// 0 = off → flattest (largest projection distance).
 const pxToProjPersp = (px: number) => (px > 0 ? Math.max(2.2, Math.min(14, px / 130)) : 14);
 
-/** Horizontal "perspective strength" slider — left = none, right = dramatic. */
-function PerspectiveSlider({
-  value,
-  onDraft,
-  onCommit,
-}: {
-  value: number;
-  onDraft?: (px: number) => void;
-  onCommit: (px: number) => void;
-}) {
-  const trackRef = useRef<HTMLDivElement | null>(null);
-  const draggingRef = useRef(false);
-  const strength = pxToStrength(value);
-  const fromEvent = (clientX: number) => {
-    const r = trackRef.current?.getBoundingClientRect();
-    if (!r || r.width === 0) return 0;
-    return strengthToPx(Math.max(0, Math.min(1, (clientX - r.left) / r.width)));
-  };
-  return (
-    <div className="flex items-center gap-1.5 px-2 pb-1.5 pt-1">
-      <span className="text-[8px] font-medium uppercase tracking-wide text-neutral-600">Persp</span>
-      <div
-        ref={trackRef}
-        onPointerDown={(e) => {
-          e.currentTarget.setPointerCapture(e.pointerId);
-          draggingRef.current = true;
-          onDraft?.(fromEvent(e.clientX));
-        }}
-        onPointerMove={(e) => {
-          if (draggingRef.current) onDraft?.(fromEvent(e.clientX));
-        }}
-        onPointerUp={(e) => {
-          if (!draggingRef.current) return;
-          draggingRef.current = false;
-          onCommit(fromEvent(e.clientX));
-        }}
-        onPointerCancel={() => {
-          draggingRef.current = false;
-        }}
-        className="relative h-3 flex-1 cursor-ew-resize touch-none"
-      >
-        <div className="absolute top-1/2 h-0.5 w-full -translate-y-1/2 rounded-full bg-neutral-700" />
-        <div
-          className="absolute top-1/2 h-0.5 -translate-y-1/2 rounded-full bg-[#5ff0bf]"
-          style={{ width: `${strength * 100}%` }}
-        />
-        <div
-          className="absolute top-1/2 size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full border border-neutral-900 bg-[#5ff0bf]"
-          style={{ left: `${strength * 100}%` }}
-        />
-      </div>
-    </div>
-  );
-}
-
 export function Transform3DCube({
   pose,
   perspective = 0,
+  defaultPerspective = 0,
+  z = 0,
   onPoseDraft,
   onPoseCommit,
-  onPerspectiveDraft,
-  onPerspectiveCommit,
+  onDepthDraft,
+  onDepthCommit,
   onRecenter,
   onKeyframe,
   keyframed,
@@ -103,13 +42,18 @@ export function Transform3DCube({
   pose: CubePose;
   /** Element's transformPerspective (px); drives the cube's foreshortening. */
   perspective?: number;
+  /** Comp-derived lens used for depth feedback before a perspective is committed. */
+  defaultPerspective?: number;
+  /** Element's translateZ (px) — "depth", adjusted by scrolling over the cube. */
+  z?: number;
   /** Fires on every drag move with the in-progress pose (parent live-previews). */
   onPoseDraft?: (pose: CubePose) => void;
   /** Fires once on pointer release with the final pose (commit). */
   onPoseCommit: (pose: CubePose) => void;
-  /** Live + committed perspective (px) from the in-cube slider. */
-  onPerspectiveDraft?: (px: number) => void;
-  onPerspectiveCommit?: (px: number) => void;
+  /** Live depth (translateZ px) during a scroll; parent live-previews it. */
+  onDepthDraft?: (z: number) => void;
+  /** Committed depth (translateZ px) once a scroll burst settles. */
+  onDepthCommit?: (z: number) => void;
   /** Reset to identity orientation. */
   onRecenter?: () => void;
   /** Toggle keyframing the 3D transform (convert the static set → keyframes). */
@@ -118,16 +62,74 @@ export function Transform3DCube({
   keyframed?: boolean;
 }) {
   const [draft, setDraft] = useState<CubePose | null>(null);
+  const [depthDraft, setDepthDraft] = useState<number | null>(null);
   const dragRef = useRef<{ x: number; y: number; pose: CubePose } | null>(null);
   const shown = draft ?? pose;
+  const shownZ = depthDraft ?? z;
+
+  // Scroll over the cube to push the element along Z (depth) — matches the
+  // studio's "scroll = z depth" gesture-recording convention. A non-passive
+  // listener is required so preventDefault can stop the panel from scrolling.
+  const svgRef = useRef<SVGSVGElement | null>(null);
+  // Perspective lens (committed, else the comp-derived default the panel will
+  // apply). Drives the cube's depth-scale feedback AND clamps the scroll so depth
+  // can't cross the lens. Defined here so the wheel handler can read it via the ref.
+  const lens = perspective > 0 ? perspective : defaultPerspective;
+  const depthRef = useRef({ z, onDepthDraft, onDepthCommit, lens });
+  depthRef.current = { z, onDepthDraft, onDepthCommit, lens };
+  useEffect(() => {
+    const el = svgRef.current;
+    if (!el) return;
+    let pending: number | null = null;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const onWheel = (e: WheelEvent) => {
+      const { onDepthCommit: commit, onDepthDraft: draft } = depthRef.current;
+      if (!commit) return;
+      e.preventDefault();
+      // ponytail: 0.25 px of Z per wheel-delta unit (~25px per notch); tune if
+      // it feels too fast/slow. Scroll up (deltaY < 0) pushes toward the viewer.
+      let next = Math.round((pending ?? depthRef.current.z) - e.deltaY * 0.25);
+      // Clamp depth in front of the perspective lens. At z ≥ lens the element sits
+      // at/behind the virtual camera and the projection lens/(lens−z) blows up or
+      // inverts — that's the runaway "Z = 3195px past a 1080 lens". Cap just short
+      // of the lens; allow pushing well back (smaller) but not absurdly far.
+      const L = depthRef.current.lens;
+      if (L > 0) next = Math.max(Math.min(next, Math.round(L * 0.85)), Math.round(-L * 4));
+      pending = next;
+      draft?.(pending);
+      setDepthDraft(pending); // live-scale the cube while scrolling
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        if (pending != null) commit(pending);
+        pending = null;
+        setDepthDraft(null); // fall back to the committed z prop
+      }, 160);
+    };
+    el.addEventListener("wheel", onWheel, { passive: false });
+    return () => {
+      el.removeEventListener("wheel", onWheel);
+      if (timer) clearTimeout(timer);
+    };
+  }, []);
+
+  // Depth feedback: the cube scales like the element would — translateZ(z) under
+  // a perspective lens P appears scaled by P/(P-z). Closer (z>0) reads bigger,
+  // farther (z<0) smaller. Use the committed perspective, else the comp-derived
+  // lens the panel is about to apply — same value in both, so the cube doesn't
+  // jump when the commit lands. If neither is known, skip the scale (no lens).
+  const depthScale = lens > 0 ? Math.max(0.4, Math.min(2.2, lens / (lens - shownZ))) : 1;
   const projOpts = {
     cx: CX,
     cy: CY,
-    r: RADIUS,
-    persp: pxToProjPersp(perspective),
+    r: RADIUS * depthScale,
+    persp: pxToProjPersp(lens),
   };
-  const faces = projectCubeFaces(shown.rotationX, shown.rotationY, shown.rotationZ, projOpts);
-  const axes = projectAxes(shown.rotationX, shown.rotationY, shown.rotationZ, projOpts);
+  // The element lives in CSS's screen-Y-down space; the cube projects Y-up. RotateX
+  // and RotateZ act in planes that contain Y, so they read inverted in the gizmo
+  // unless their sign is flipped — RotateY (X-Z plane) matches as-is. This keeps the
+  // cube's orientation a true mirror of the element.
+  const faces = projectCubeFaces(-shown.rotationX, shown.rotationY, -shown.rotationZ, projOpts);
+  const axes = projectAxes(-shown.rotationX, shown.rotationY, -shown.rotationZ, projOpts);
 
   const onPointerDown = (e: React.PointerEvent<SVGSVGElement>) => {
     e.currentTarget.setPointerCapture(e.pointerId);
@@ -140,10 +142,13 @@ export function Transform3DCube({
     if (!d) return;
     const dx = e.clientX - d.x;
     const dy = e.clientY - d.y;
+    // dy→rotationX and shift dx→rotationZ are negated to match the projection's
+    // sign flip (above), so the cube's response to a drag is unchanged while the
+    // element now rotates in lock-step with it.
     const next: CubePose = e.shiftKey
-      ? { ...d.pose, rotationZ: wrapDeg(d.pose.rotationZ + dx * SENSITIVITY) }
+      ? { ...d.pose, rotationZ: wrapDeg(d.pose.rotationZ - dx * SENSITIVITY) }
       : {
-          rotationX: wrapDeg(d.pose.rotationX - dy * SENSITIVITY),
+          rotationX: wrapDeg(d.pose.rotationX + dy * SENSITIVITY),
           rotationY: wrapDeg(d.pose.rotationY + dx * SENSITIVITY),
           rotationZ: d.pose.rotationZ,
         };
@@ -161,6 +166,7 @@ export function Transform3DCube({
   return (
     <div className="relative overflow-hidden rounded-lg border border-neutral-800 bg-gradient-to-b from-neutral-900 to-neutral-950">
       <svg
+        ref={svgRef}
         viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
         className="block w-full cursor-grab touch-none select-none active:cursor-grabbing"
         style={{ aspectRatio: `${VIEW_W} / ${VIEW_H}` }}
@@ -169,7 +175,7 @@ export function Transform3DCube({
         onPointerUp={onPointerUp}
         onPointerCancel={onPointerUp}
         role="slider"
-        aria-label="Drag to rotate in 3D; hold Shift to roll"
+        aria-label="Drag to rotate in 3D; hold Shift to roll; scroll to change depth"
         aria-valuetext={`X ${Math.round(shown.rotationX)}°, Y ${Math.round(
           shown.rotationY,
         )}°, Z ${Math.round(shown.rotationZ)}°`}
@@ -301,13 +307,6 @@ export function Transform3DCube({
           </svg>
         </button>
       )}
-      {onPerspectiveCommit && (
-        <PerspectiveSlider
-          value={perspective}
-          onDraft={onPerspectiveDraft}
-          onCommit={onPerspectiveCommit}
-        />
-      )}
     </div>
   );
 }

package/src/components/editor/domEditOverlayGeometry.ts

@@ -186,6 +186,34 @@ export function resolveDomEditGroupOverlayRect(rects: OverlayRect[]): OverlayRec
   };
 }
 
+// A group's overlay box encompasses its members' actual rendered bounds, not just
+// the wrapper's own box — so members moved or transformed out of the wrapper still
+// sit inside the box. Used by the selection, hover, and off-canvas overlays so they
+// all agree on where a group is.
+export function groupAwareOverlayRect(
+  overlayEl: HTMLDivElement,
+  iframe: HTMLIFrameElement,
+  el: HTMLElement,
+): OverlayRect | null {
+  const rect = toOverlayRect(overlayEl, iframe, el);
+  if (!rect || !el.hasAttribute("data-hf-group")) return rect;
+  // Union the MEMBERS' rendered rects — where the content actually is — not the
+  // wrapper's own box. The wrapper is invisible and its box can sit apart from the
+  // members once they've been moved/transformed, which would otherwise drag the
+  // group's bounds (and its off-canvas marker) off to a stale position.
+  const rects: OverlayRect[] = [];
+  for (const child of Array.from(el.children)) {
+    const childRect = toOverlayRect(overlayEl, iframe, child as HTMLElement);
+    if (childRect) rects.push(childRect);
+  }
+  const union = rects.length > 0 ? resolveDomEditGroupOverlayRect(rects) : null;
+  if (!union) return rect; // empty group → fall back to the wrapper box
+  // resolveDomEditGroupOverlayRect hardcodes editScaleX/Y to 1; keep the wrapper's
+  // real edit (display) scale, which the drag uses to convert pointer→offset — a
+  // reset-to-1 makes the group move at ~display-scale speed and lag the cursor.
+  return { ...union, editScaleX: rect.editScaleX, editScaleY: rect.editScaleY };
+}
+
 export function filterNestedDomEditGroupItems<T extends { element: HTMLElement }>(items: T[]): T[] {
   return items.filter(
     (item) => !items.some((other) => other !== item && other.element.contains(item.element)),

package/src/components/editor/domEditingDom.ts

@@ -250,7 +250,7 @@ export function querySelectorAllSafely(doc: Document, selector: string): Element
   }
 }
 
-export function humanizeIdentifier(value: string): string {
+function humanizeIdentifier(value: string): string {
   return (
     value
       .replace(/\.html$/i, "")
@@ -270,10 +270,16 @@ export function buildStableSelector(el: HTMLElement): string | undefined {
   const compositionId = el.getAttribute("data-composition-id");
   if (compositionId) return `[data-composition-id="${escapeCssString(compositionId)}"]`;
 
+  // Group wrappers carry no id/class; their data-hf-group value is the unique,
+  // stable handle the source mutations write — use it so the wrapper is
+  // selectable, patchable (move/scale), and addressable for ungroup.
+  const group = el.getAttribute("data-hf-group");
+  if (group) return `[data-hf-group="${escapeCssString(group)}"]`;
+
   return getPreferredClassSelector(el);
 }
 
-export function getPreferredClassSelector(el: HTMLElement): string | undefined {
+function getPreferredClassSelector(el: HTMLElement): string | undefined {
   const classes = Array.from(el.classList)
     .map((value) => value.trim())
     .filter(Boolean);
@@ -283,6 +289,34 @@ export function getPreferredClassSelector(el: HTMLElement): string | undefined {
   return preferred ? `.${escapeCssIdentifier(preferred)}` : undefined;
 }
 
+// fallow-ignore-next-line complexity
+export function buildElementLabel(el: HTMLElement): string {
+  const compositionId = el.getAttribute("data-composition-id");
+  if (compositionId && compositionId !== "main") {
+    return humanizeIdentifier(compositionId);
+  }
+
+  const compositionSrc =
+    el.getAttribute("data-composition-src") ?? el.getAttribute("data-composition-file");
+  if (compositionSrc) {
+    return humanizeIdentifier(compositionSrc);
+  }
+
+  const group = el.getAttribute("data-hf-group");
+  if (group) return group;
+
+  if (el.id) return humanizeIdentifier(el.id);
+
+  const preferredClass = getPreferredClassSelector(el);
+  if (preferredClass) {
+    return humanizeIdentifier(preferredClass.replace(/^\./, ""));
+  }
+
+  const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
+  if (text) return text.length > 40 ? `${text.slice(0, 39)}…` : text;
+  return el.tagName.toLowerCase();
+}
+
 export function getSelectorIndex(
   doc: Document,
   el: HTMLElement,

package/src/components/editor/domEditingGroups.ts

@@ -0,0 +1,41 @@
+import { isHtmlElement } from "./domEditingDom";
+
+// `data-hf-group` selection semantics: a group wrapper is selected as one unit
+// until the user drills into it; once drilled in, clicks resolve to its children
+// (or to the next nested group inside it). One level of drill-in at a time keeps
+// nested groups navigable.
+
+export type GroupCapture =
+  | { kind: "unit"; element: HTMLElement } // select this group wrapper as one unit
+  | { kind: "child" } // resolve the clicked element normally
+  | { kind: "out-of-scope" }; // clicked outside the drilled-into group → select nothing
+
+// Layer-tree roots: the drilled-into group's element children, else the doc root.
+export function groupScopedLayerRoots(
+  root: HTMLElement,
+  activeGroupElement: HTMLElement | null,
+): HTMLElement[] {
+  const els = activeGroupElement?.isConnected ? Array.from(activeGroupElement.children) : [root];
+  return els.filter(isHtmlElement);
+}
+
+export function resolveGroupCapture(
+  startEl: HTMLElement,
+  activeGroupElement: HTMLElement | null,
+): GroupCapture {
+  const groups: HTMLElement[] = [];
+  for (let n: HTMLElement | null = startEl; n; n = n.parentElement) {
+    if (n.hasAttribute("data-hf-group")) groups.push(n);
+  }
+  const result = ((): GroupCapture => {
+    if (!activeGroupElement) {
+      const outermost = groups[groups.length - 1];
+      return outermost ? { kind: "unit", element: outermost } : { kind: "child" };
+    }
+    const idx = groups.indexOf(activeGroupElement);
+    if (idx === -1) return { kind: "out-of-scope" };
+    const nestedInside = groups[idx - 1];
+    return nestedInside ? { kind: "unit", element: nestedInside } : { kind: "child" };
+  })();
+  return result;
+}

package/src/components/editor/domEditingLayers.test.ts

@@ -1,6 +1,11 @@
 // @vitest-environment jsdom
 import { describe, expect, it } from "vitest";
-import { resolveDomEditSelection, buildDomEditPatchTarget, readHfId } from "./domEditingLayers";
+import {
+  collectDomEditLayerItems,
+  resolveDomEditSelection,
+  buildDomEditPatchTarget,
+  readHfId,
+} from "./domEditingLayers";
 
 const opts = { activeCompositionPath: "index.html", isMasterView: true, skipSourceProbe: true };
 
@@ -76,3 +81,94 @@ describe("resolveDomEditSelection — hfId from data-hf-id", () => {
     expect(selection?.hfId).toBeUndefined();
   });
 });
+
+describe("resolveDomEditSelection — data-hf-group capture", () => {
+  // <div id="parent"><div data-hf-group="Group 1"><div data-hf-group="Group 2">
+  //   <span id="child"/></div></div></div>
+  function buildNestedGroups() {
+    const parent = document.createElement("div");
+    parent.id = "parent";
+    const outer = document.createElement("div");
+    outer.setAttribute("data-hf-group", "Group 1");
+    const inner = document.createElement("div");
+    inner.setAttribute("data-hf-group", "Group 2");
+    const child = document.createElement("span");
+    child.id = "child";
+    inner.appendChild(child);
+    outer.appendChild(inner);
+    parent.appendChild(outer);
+    document.body.appendChild(parent);
+    return { parent, outer, inner, child };
+  }
+
+  it("selects the outermost group as a unit when clicking a child (not drilled in)", async () => {
+    const { parent, outer, child } = buildNestedGroups();
+    const selection = await resolveDomEditSelection(child, opts);
+    document.body.removeChild(parent);
+
+    expect(selection?.element).toBe(outer);
+    expect(selection?.selector).toBe('[data-hf-group="Group 1"]');
+  });
+
+  it("selects the next nested group when drilled into the outer group", async () => {
+    const { parent, outer, inner, child } = buildNestedGroups();
+    const selection = await resolveDomEditSelection(child, { ...opts, activeGroupElement: outer });
+    document.body.removeChild(parent);
+
+    expect(selection?.element).toBe(inner);
+    expect(selection?.selector).toBe('[data-hf-group="Group 2"]');
+  });
+
+  it("selects the child when drilled all the way into the innermost group", async () => {
+    const { parent, inner, child } = buildNestedGroups();
+    const selection = await resolveDomEditSelection(child, { ...opts, activeGroupElement: inner });
+    document.body.removeChild(parent);
+
+    expect(selection?.element).toBe(child);
+    expect(selection?.id).toBe("child");
+  });
+
+  it("layer tree is scoped to the group's members when drilled in", () => {
+    const root = document.createElement("div");
+    root.setAttribute("data-composition-id", "main");
+    const group = document.createElement("div");
+    group.setAttribute("data-hf-group", "Group 1");
+    const inside = document.createElement("div");
+    inside.id = "inside";
+    const outside = document.createElement("div");
+    outside.id = "outside";
+    group.appendChild(inside);
+    root.appendChild(group);
+    root.appendChild(outside);
+    document.body.appendChild(root);
+
+    const opts2 = { activeCompositionPath: "index.html", isMasterView: true };
+    const full = collectDomEditLayerItems(root, opts2).map((i) => i.id);
+    const scoped = collectDomEditLayerItems(root, { ...opts2, activeGroupElement: group }).map(
+      (i) => i.id,
+    );
+    document.body.removeChild(root);
+
+    expect(full).toContain("outside");
+    expect(scoped).toContain("inside");
+    expect(scoped).not.toContain("outside");
+  });
+
+  it("exits the drilled-into group and selects the outside element (non-sticky drill)", async () => {
+    const { parent, inner } = buildNestedGroups();
+    const outside = document.createElement("div");
+    outside.id = "outside";
+    document.body.appendChild(outside);
+
+    const selection = await resolveDomEditSelection(outside, {
+      ...opts,
+      activeGroupElement: inner,
+    });
+    document.body.removeChild(parent);
+    document.body.removeChild(outside);
+
+    // Drill-in is non-sticky: clicking outside the active group exits it and
+    // resolves the clicked element normally (rather than selecting nothing).
+    expect(selection?.id).toBe("outside");
+  });
+});

package/src/components/editor/domEditingLayers.ts

@@ -3,6 +3,7 @@
  * for dom editing.
  */
 import type { PatchOperation } from "../../utils/sourcePatcher";
+import { groupScopedLayerRoots, resolveGroupCapture } from "./domEditingGroups";
 import type {
   DomEditCapabilities,
   DomEditContextOptions,
@@ -11,15 +12,14 @@ import type {
   DomEditTextField,
 } from "./domEditingTypes";
 import {
+  buildElementLabel,
   buildStableSelector,
   findClosestByAttribute,
   getCuratedComputedStyles,
   getDataAttributes,
   getInlineStyles,
-  getPreferredClassSelector,
   getSelectorIndex,
   getSourceFileForElement,
-  humanizeIdentifier,
   isHtmlElement,
   isIdentityTransform,
   isTextBearingTag,
@@ -275,31 +275,6 @@ export function resolveDomEditCapabilities(args: {
 
 // ─── Element label ────────────────────────────────────────────────────────────
 
-// fallow-ignore-next-line complexity
-export function buildElementLabel(el: HTMLElement): string {
-  const compositionId = el.getAttribute("data-composition-id");
-  if (compositionId && compositionId !== "main") {
-    return humanizeIdentifier(compositionId);
-  }
-
-  const compositionSrc =
-    el.getAttribute("data-composition-src") ?? el.getAttribute("data-composition-file");
-  if (compositionSrc) {
-    return humanizeIdentifier(compositionSrc);
-  }
-
-  if (el.id) return humanizeIdentifier(el.id);
-
-  const preferredClass = getPreferredClassSelector(el);
-  if (preferredClass) {
-    return humanizeIdentifier(preferredClass.replace(/^\./, ""));
-  }
-
-  const text = (el.textContent ?? "").trim().replace(/\s+/g, " ");
-  if (text) return text.length > 40 ? `${text.slice(0, 39)}…` : text;
-  return el.tagName.toLowerCase();
-}
-
 // ─── Source probe ────────────────────────────────────────────────────────────
 
 async function probeSourceElement(
@@ -334,7 +309,15 @@ export async function resolveDomEditSelection(
   if (!startEl) return null;
   const doc = startEl.ownerDocument;
 
-  let current: HTMLElement | null = getSelectionCandidate(startEl, options);
+  let capture = resolveGroupCapture(startEl, options.activeGroupElement ?? null);
+  if (capture.kind === "out-of-scope") {
+    // Drill-in is non-sticky: clicking/hovering OUTSIDE the drilled-into group
+    // exits it and resolves the target normally, rather than selecting nothing
+    // (which felt like "can't select anything" once you'd drilled in).
+    capture = resolveGroupCapture(startEl, null);
+  }
+  let current: HTMLElement | null =
+    capture.kind === "unit" ? capture.element : getSelectionCandidate(startEl, options);
   while (current && current !== doc.body && current !== doc.documentElement) {
     const selector = buildStableSelector(current);
     const hfId = readHfId(current);
@@ -501,7 +484,8 @@ export function collectDomEditLayerItems(
     }
   };
 
-  visit(root, 0);
+  // Drilled into a group → show only its members; otherwise the whole tree.
+  for (const el of groupScopedLayerRoots(root, options.activeGroupElement ?? null)) visit(el, 0);
   return items;
 }
 

package/src/components/editor/domEditingTypes.ts

@@ -108,6 +108,9 @@ export interface DomEditContextOptions {
   activeCompositionPath: string | null;
   isMasterView: boolean;
   preferClipAncestor?: boolean;
+  /** The group wrapper the user has drilled into (null = top level). Selection
+   * resolution treats groups as a unit unless drilled into one. */
+  activeGroupElement?: HTMLElement | null;
 }
 
 export interface DomEditViewport {

package/src/components/editor/manualOffsetDrag.ts

@@ -209,6 +209,22 @@ export function applyManualOffsetDragMatrix(matrix: ManualOffsetDragMatrix, poin
   };
 }
 
+/**
+ * The perspective w-divisor (matrix3d m44) of the element's current transform.
+ * For a plain `translateZ(z)` under `perspective(p)`, m44 = (p - z) / p, so the
+ * element renders 1/m44× larger and a translate of `d` composition px moves
+ * `d / m44` px on screen. Returns 1 for 2D transforms (no foreshortening). Used
+ * to keep the drag offset → screen-movement mapping correct for depth elements,
+ * which the flat-scale fast path below would otherwise get wrong by 1/m44.
+ */
+function readTransformWDivisor(element: HTMLElement): number {
+  const t = element.ownerDocument.defaultView?.getComputedStyle(element).transform;
+  if (!t || !t.startsWith("matrix3d(")) return 1;
+  const parts = t.slice("matrix3d(".length, -1).split(",");
+  const w = Number.parseFloat(parts[15] ?? "");
+  return Number.isFinite(w) && w > 0 ? w : 1;
+}
+
 export function measureManualOffsetDragScreenToOffsetMatrix(
   element: HTMLElement,
   initialOffset: { x: number; y: number },
@@ -221,7 +237,11 @@ export function measureManualOffsetDragScreenToOffsetMatrix(
   ) {
     const sx = options.scaleX || 1;
     const sy = options.scaleY || 1;
-    return { ok: true, matrix: { a: 1 / sx, b: 0, c: 0, d: 1 / sy } };
+    // Fold in the perspective foreshortening: a depth element (z≠0) moves
+    // 1/m44× faster on screen than its flat scale implies, so the screen→offset
+    // matrix must scale by m44 or the element outruns the pointer/overlay.
+    const w = readTransformWDivisor(element);
+    return { ok: true, matrix: { a: w / sx, b: 0, c: 0, d: w / sy } };
   }
 
   const probeSize = options.probeSize ?? DEFAULT_OFFSET_PROBE_PX;
@@ -360,6 +380,7 @@ export function createManualOffsetDragMember(input: {
     // drag is acceptable — the final committed position is always exact.
     const scaleX = input.rect.editScaleX || 1;
     const scaleY = input.rect.editScaleY || 1;
+    const w = readTransformWDivisor(input.element);
     return {
       ok: true,
       member: {
@@ -370,7 +391,7 @@ export function createManualOffsetDragMember(input: {
         baseGsap,
         initialPathOffset,
         gestureToken,
-        screenToOffset: { a: 1 / scaleX, b: 0, c: 0, d: 1 / scaleY },
+        screenToOffset: { a: w / scaleX, b: 0, c: 0, d: w / scaleY },
         originRect: input.rect,
       },
     };