@pascal-app/editor 0.9.1 → 1.0.0-beta.1

package/src/components/editor/node-arrow-handles.tsx

@@ -6,15 +6,15 @@ import {
   type ArcResizeHandle,
   type Cursor,
   createSceneApi,
+  DEFAULT_ANGLE_STEP,
   type HandleDescriptor,
   type HandlePortal,
+  type LatchHandle,
   type LinearResizeHandle,
   nodeRegistry,
   type RadialResizeHandle,
   sceneRegistry,
-  snapScalar,
   type TapActionHandle,
-  type TranslateHandle,
   useLiveNodeOverrides,
   useScene,
 } from '@pascal-app/core'
@@ -34,15 +34,25 @@ import {
   OrthographicCamera,
   Plane,
   Quaternion,
+  Ray,
   RingGeometry,
   Vector3,
 } from 'three'
 import { mergeGeometries } from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+
 import { MeshBasicNodeMaterial } from 'three/webgpu'
 import { EDITOR_LAYER } from '../../lib/constants'
+import { RESIZE_HANDLE_DRAG_LABEL, ROTATE_HANDLE_DRAG_LABEL } from '../../lib/contextual-help'
 import { createEditorApi } from '../../lib/editor-api'
 import { sfxEmitter } from '../../lib/sfx-bus'
-import useEditor from '../../store/use-editor'
+import useDirectManipulationFeedback from '../../store/use-direct-manipulation-feedback'
+import useEditor, { isGridSnapActive, isMagneticSnapActive } from '../../store/use-editor'
+import useInteractionScope, {
+  useEndpointReshape,
+  useIsCurveReshape,
+  useMovingNode,
+} from '../../store/use-interaction-scope'
+import useOpeningGuides from '../../store/use-opening-guides'
 import { formatAngleRadians } from '../tools/shared/segment-angle'
 import {
   ARROW_COLOR,
@@ -52,17 +62,70 @@ import {
   HandleArrow,
   NO_RAYCAST,
 } from './handles/handle-arrow'
+import { replacePreviewOverrideIds } from './handles/preview-overrides'
+import { resolveResizeSnapValue } from './handles/resize-snap'
 import { type HandleDragControls, useHandleDrag } from './handles/use-handle-drag'
 
+// Pooled scratch for the handle rig's world-relative pose mapping.
+const _rigRelative = new Matrix4()
+const _rigScratchScale = new Vector3()
+const _resizeAxisW = new Vector3()
+const _resizeScale = new Vector3()
+const _resizeQuaternion = new Quaternion()
+const _resizeOriginW = new Vector3()
+const _resizePositionW = new Vector3()
+const _resizeRay = new Ray()
+const _resizeRayW = new Vector3()
+const MEASUREMENT_SURFACE_EXCLUDE_USER_DATA = { measurementSurface: false }
+
+// Tilt that stands a flat XZ-plane move cross up into a node's facing plane
+// (its local XY = a wall face) for `plane: 'node-normal'` handles.
+const NODE_NORMAL_TILT: [number, number, number] = [Math.PI / 2, 0, 0]
+
+function axisVector(axis: 'x' | 'y' | 'z', target: Vector3) {
+  target.set(0, 0, 0)
+  if (axis === 'x') target.x = 1
+  else if (axis === 'y') target.y = 1
+  else target.z = 1
+  return target
+}
+
+function axisScale(axis: 'x' | 'y' | 'z', scale: Vector3) {
+  return axis === 'x' ? scale.x : axis === 'y' ? scale.y : scale.z
+}
+
+function closestAxisParameterToRay(axisOrigin: Vector3, axisDirection: Vector3, ray: Ray) {
+  _resizeRayW.subVectors(axisOrigin, ray.origin)
+  const b = axisDirection.dot(ray.direction)
+  const d = axisDirection.dot(_resizeRayW)
+  const e = ray.direction.dot(_resizeRayW)
+  const denominator = 1 - b * b
+  if (Math.abs(denominator) < 1e-6) {
+    return -d
+  }
+
+  const axisParameter = (b * e - d) / denominator
+  const rayParameter = e + b * axisParameter
+  if (rayParameter < 0) {
+    return -d
+  }
+  return axisParameter
+}
+
 export {
   ARROW_COLOR,
   ARROW_HOVER_COLOR,
   ARROW_SCALE,
+  createArrowHandleGeometry,
   createArrowHitAreaGeometry,
   createEndpointHitAreaGeometry,
   createMoveCrossHandleGeometry,
   createRotateArrowHandleGeometry,
   createRotateArrowHitAreaGeometry,
+  HandleArrow,
+  type HandleArrowInputShape,
+  type HandleArrowPlacement,
+  type HandleArrowProps,
   HIT_AREA_MARGIN,
   InvisibleHandleHitArea,
   NO_RAYCAST,
@@ -76,6 +139,20 @@ export { swallowNextClick } from './handles/use-handle-drag'
 // its end). Upward trackers — wall / chimney height — stop at the cube.
 const TRACKER_THROUGH = 0.12
 
+type SceneApiForHandles = ReturnType<typeof createSceneApi>
+type CenteredGuideDecoration = {
+  center?: (node: AnyNode, sceneApi: SceneApiForHandles) => readonly [number, number, number]
+  radius: (node: AnyNode, sceneApi: SceneApiForHandles) => number
+}
+
+function guideDecorationCenter(decoration: unknown, node: AnyNode, sceneApi: SceneApiForHandles) {
+  return (decoration as CenteredGuideDecoration | undefined)?.center?.(node, sceneApi)
+}
+
+function guideDecorationRadius(decoration: unknown, node: AnyNode, sceneApi: SceneApiForHandles) {
+  return (decoration as CenteredGuideDecoration).radius(node, sceneApi)
+}
+
 // Mirrors the formatter used by wall / fence measurement labels so all
 // in-world dimension chips read consistently.
 function formatDimension(value: number, unit: 'metric' | 'imperial'): string {
@@ -122,23 +199,22 @@ function DimensionLabel({
 
 export function NodeArrowHandles() {
   const selectedIds = useViewer((state) => state.selection.selectedIds)
+  const activeRotateNodeId = useDirectManipulationFeedback((state) => state.activeRotateNodeId)
   const mode = useEditor((state) => state.mode)
   const isFloorplanHovered = useEditor((state) => state.isFloorplanHovered)
-  const movingNode = useEditor((state) => state.movingNode)
-  const placementDragMode = useEditor((state) => state.placementDragMode)
+  const movingNode = useMovingNode()
   // Endpoint / curve drags reshape the selected wall or fence; hide its
   // resize arrows for the duration so they don't clutter (or get blocked
   // by) the drag's own cursor + dimension overlays. Mirrors the same guard
   // on the legacy wall handles (`WallMoveSideHandles`).
-  const movingWallEndpoint = useEditor((state) => state.movingWallEndpoint)
-  const movingFenceEndpoint = useEditor((state) => state.movingFenceEndpoint)
-  const curvingWall = useEditor((state) => state.curvingWall)
-  const curvingFence = useEditor((state) => state.curvingFence)
-
-  const selectedId = selectedIds.length === 1 ? selectedIds[0] : null
-  const rawNode = useScene((state) =>
-    selectedId ? (state.nodes[selectedId as AnyNodeId] ?? null) : null,
-  )
+  const endpointReshape = useEndpointReshape()
+  const isCurveReshape = useIsCurveReshape()
+
+  const selectedId = selectedIds.length === 1 ? selectedIds[0] : activeRotateNodeId
+  const rawNode = useScene((state) => {
+    if (!selectedId) return null
+    return state.nodes[selectedId as AnyNodeId] ?? null
+  })
 
   // Merge any live drag override so the arrows themselves (positions,
   // ring decorations) track the in-flight drag instead of freezing at
@@ -151,26 +227,37 @@ export function NodeArrowHandles() {
     () => (rawNode && liveOverride ? ({ ...rawNode, ...liveOverride } as AnyNode) : rawNode),
     [rawNode, liveOverride],
   )
-  const isOwnPressDragMove =
-    placementDragMode && movingNode !== null && selectedId !== null && movingNode.id === selectedId
-
   const def = node ? nodeRegistry.get(node.type) : null
+  const descriptorSceneApi = useMemo(() => createSceneApi(useScene), [])
   const descriptors = useMemo(() => {
     if (!(node && def?.handles)) return null
-    return typeof def.handles === 'function'
-      ? def.handles(node as never)
-      : (def.handles as HandleDescriptor[])
-  }, [node, def])
+    const all =
+      typeof def.handles === 'function'
+        ? def.handles(node as never, descriptorSceneApi)
+        : (def.handles as HandleDescriptor[])
+    // The whole-node move-cross gizmo is gone: moving is now click-to-move on
+    // the selected node body (see selection-manager). Drop both flavours — the
+    // `translate` ground cross (column/roof/shelf/spawn) and the `tap-action`
+    // `move-cross` (item/door/window/elevator/stair) — keep rotate/resize.
+    return all.filter(
+      (d) =>
+        d.kind !== 'translate' &&
+        !('shape' in d && d.shape === 'move-cross') &&
+        (d.kind !== 'linear-resize' || d.visible?.(node as never, descriptorSceneApi) !== false),
+    )
+  }, [node, def, descriptorSceneApi])
 
   const shouldRender =
     Boolean(node && descriptors?.length) &&
     !isFloorplanHovered &&
     mode !== 'delete' &&
-    (!movingNode || isOwnPressDragMove) &&
-    !movingWallEndpoint &&
-    !movingFenceEndpoint &&
-    !curvingWall &&
-    !curvingFence
+    // Any whole-node move (placement or press-drag) hides the rig: the item is
+    // following the cursor, so its rotate/resize handles would only clutter and
+    // draw stray selection rays. The active handle-drag scope (resize/rotate)
+    // sets `activeHandleDrag`, not `movingNode`, so those are unaffected.
+    !movingNode &&
+    !endpointReshape &&
+    !isCurveReshape
 
   if (!shouldRender || !node || !descriptors) return null
   // Key by the selected node id so switching selection REMOUNTS the rig.
@@ -275,14 +362,32 @@ function NodeArrowHandlesForNode({
   // exclusion the wall arrow also goes without.
 
   useFrame(() => {
+    if (innerRef.current && innerRide && portalObject) {
+      // Grandparent mode: pose the rig by mapping the node's WORLD pose
+      // into the portal target's frame. Copying the parent + node
+      // registry poses (the previous approach) assumed the node mesh is
+      // a DIRECT child of the parent's registered object — roof-hosted
+      // openings break that with an intermediate face-frame group, which
+      // the world-relative mapping absorbs for free. For wall children
+      // the result is identical (portal⁻¹ ∘ node = wall.local ∘ node.local).
+      if (outerRef.current) {
+        outerRef.current.position.set(0, 0, 0)
+        outerRef.current.quaternion.identity()
+      }
+      portalObject.updateWorldMatrix(true, false)
+      innerRide.updateWorldMatrix(true, false)
+      _rigRelative.copy(portalObject.matrixWorld).invert().multiply(innerRide.matrixWorld)
+      _rigRelative.decompose(
+        innerRef.current.position,
+        innerRef.current.quaternion,
+        _rigScratchScale,
+      )
+      return
+    }
     if (outerRef.current && outerRide) {
       outerRef.current.position.copy(outerRide.position)
       outerRef.current.quaternion.copy(outerRide.quaternion)
     }
-    if (innerRef.current && innerRide) {
-      innerRef.current.position.copy(innerRide.position)
-      innerRef.current.quaternion.copy(innerRide.quaternion)
-    }
   })
 
   // Active-drag tracking. When a handle starts dragging, it claims its
@@ -299,6 +404,21 @@ function NodeArrowHandlesForNode({
   // hook count between renders and trip React's rules-of-hooks check.
   const [activeIndex, setActiveIndex] = useState<number | null>(null)
   const [preDragNode, setPreDragNode] = useState<AnyNode | null>(null)
+  // Latch groups currently toggled open. A `latch` cube descriptor flips its
+  // group here on click; arrows tagged with a `latchGroup` only render while
+  // their group is in this set. Local to this mount, so it resets on deselect
+  // (the rig remounts per selection — see the `key` on NodeArrowHandlesForNode).
+  const [openLatchGroups, setOpenLatchGroups] = useState<ReadonlySet<string>>(() => new Set())
+  const toggleLatchGroup = useMemo(
+    () => (group: string) =>
+      setOpenLatchGroups((prev) => {
+        const next = new Set(prev)
+        if (next.has(group)) next.delete(group)
+        else next.add(group)
+        return next
+      }),
+    [],
+  )
   const dragControls = useMemo<HandleDragControls>(
     () => ({
       onStart: (index: number, snapshot: AnyNode) => {
@@ -328,25 +448,48 @@ function NodeArrowHandlesForNode({
   // resize that re-centres the mesh) must NOT fire for the non-active arrows
   // here, or they'd lag behind the moving item.
   const activeIsTranslate = activeIndex !== null && descriptors[activeIndex]?.kind === 'translate'
-
-  const arrows = descriptors.map((descriptor, index) => (
-    <ArrowHandle
-      activeIndex={activeIndex}
-      descriptor={descriptor}
-      dragControls={dragControls}
-      handleIndex={index}
-      // Descriptors come from a per-node-kind static list, so index is a
-      // stable identity within this node's selection cycle.
-      key={index}
-      liveNode={node}
-      preDragNode={preDragNode}
-      rideObject={arrowFrame}
-      suppressFreeze={activeIsTranslate}
-    />
-  ))
+  // While a rotate gizmo is mid-drag, drop the opposite-side move cross: you
+  // can't move and rotate at once, so it only clutters the rotation.
+  const activeDescriptor = activeIndex !== null ? descriptors[activeIndex] : undefined
+  const activeIsRotate =
+    !!activeDescriptor && 'shape' in activeDescriptor && activeDescriptor.shape === 'rotate'
+
+  const arrows = descriptors.map((descriptor, index) => {
+    if (activeIsRotate && 'shape' in descriptor && descriptor.shape === 'move-cross') return null
+    // A `latch` cube toggles its group's visibility; render it always.
+    if (descriptor.kind === 'latch') {
+      return (
+        <LatchCube
+          descriptor={descriptor}
+          key={index}
+          node={node}
+          onToggle={toggleLatchGroup}
+          open={openLatchGroups.has(descriptor.group)}
+        />
+      )
+    }
+    // Arrows tagged with a latch group stay hidden until that group is open.
+    const latchGroup = descriptor.kind === 'linear-resize' ? descriptor.latchGroup : undefined
+    if (latchGroup && !openLatchGroups.has(latchGroup)) return null
+    return (
+      <ArrowHandle
+        activeIndex={activeIndex}
+        descriptor={descriptor}
+        dragControls={dragControls}
+        handleIndex={index}
+        // Descriptors come from a per-node-kind static list, so index is a
+        // stable identity within this node's selection cycle.
+        key={index}
+        liveNode={node}
+        preDragNode={preDragNode}
+        rideObject={arrowFrame}
+        suppressFreeze={activeIsTranslate}
+      />
+    )
+  })
 
   return createPortal(
-    <group ref={outerRef}>
+    <group ref={outerRef} userData={MEASUREMENT_SURFACE_EXCLUDE_USER_DATA}>
       {innerRideId !== null ? <group ref={innerRef}>{arrows}</group> : arrows}
     </group>,
     portalObject,
@@ -443,17 +586,6 @@ function ArrowHandle({
       />
     )
   }
-  if (descriptor.kind === 'translate') {
-    return (
-      <TranslateArrow
-        descriptor={descriptor}
-        dragControls={dragControls}
-        handleIndex={handleIndex}
-        node={placementNode}
-        rideObject={rideObject}
-      />
-    )
-  }
   if (descriptor.kind === 'tap-action') {
     // Tap-action handles (fence side-move arrows, corner pickers) aren't
     // resize handles, so the freeze-at-pre-drag mechanism — which only
@@ -524,6 +656,9 @@ function LinearArrow({
   // floating dimension pill (via `activeHandleDrag`) and its own in-world
   // chip is suppressed — matches the wall height handle.
   const measureLabel = descriptor.kind === 'linear-resize' ? descriptor.measureLabel : undefined
+  // Optional per-tick feedback hook (doors/windows publish proximity/sill guides
+  // for the edge being resized); cleared when the drag ends.
+  const onDrag = descriptor.kind === 'linear-resize' ? descriptor.onDrag : undefined
   const placementSceneApi = useMemo(() => createSceneApi(useScene), [])
   const basePosition = descriptor.placement.position(node, placementSceneApi)
   // `freezeOffset` (in node-local frame) cancels the mesh's `position`
@@ -555,40 +690,33 @@ function LinearArrow({
     rideObject,
     setIsDragging,
     onStart: ({
-      camera: dragCamera,
       event,
+      getPointerRay,
       initialNode,
-      intersectPlane,
       nodeId,
       rideObject: dragRideObject,
       sceneApi,
     }) => {
-      const initialFrameInverse = new Matrix4().copy(dragRideObject.matrixWorld).invert()
-      const worldOrigin = new Vector3(...position).applyMatrix4(dragRideObject.matrixWorld)
-      const planeNormal = new Vector3().subVectors(dragCamera.position, worldOrigin).setY(0)
-      if (planeNormal.lengthSq() === 0) return null
-      planeNormal.normalize()
-      const plane = new Plane().setFromNormalAndCoplanarPoint(planeNormal, worldOrigin)
+      dragRideObject.matrixWorld.decompose(_resizePositionW, _resizeQuaternion, _resizeScale)
+      _resizeOriginW.set(...position).applyMatrix4(dragRideObject.matrixWorld)
+      axisVector(descriptor.axis, _resizeAxisW).applyQuaternion(_resizeQuaternion).normalize()
+      const localToWorldScale = axisScale(descriptor.axis, _resizeScale)
+      if (Math.abs(localToWorldScale) < 1e-6 || _resizeAxisW.lengthSq() === 0) return null
 
-      const hitWorld = new Vector3()
-      if (!intersectPlane(event.nativeEvent.clientX, event.nativeEvent.clientY, plane, hitWorld)) {
-        return null
-      }
-      const hitLocal = hitWorld.clone().applyMatrix4(initialFrameInverse)
+      const initialPointer =
+        closestAxisParameterToRay(
+          _resizeOriginW,
+          _resizeAxisW,
+          getPointerRay(event.nativeEvent.clientX, event.nativeEvent.clientY, _resizeRay),
+        ) / localToWorldScale
 
       const overrideId =
         (descriptor.kind === 'linear-resize'
           ? descriptor.overrideTarget?.(initialNode as never, sceneApi)
           : undefined) ?? nodeId
       const initialValue = descriptor.currentValue(initialNode)
-      const initialPointer =
-        descriptor.axis === 'x' ? hitLocal.x : descriptor.axis === 'y' ? hitLocal.y : hitLocal.z
       const minBound = resolveBound(descriptor.min, Number.NEGATIVE_INFINITY, initialNode, sceneApi)
       const maxBound = resolveBound(descriptor.max, Number.POSITIVE_INFINITY, initialNode, sceneApi)
-      const gridSnapStep =
-        descriptor.kind === 'linear-resize' && descriptor.gridSnap
-          ? useEditor.getState().gridSnapStep
-          : null
       const factor =
         descriptor.kind === 'radial-resize'
           ? 1
@@ -598,36 +726,92 @@ function LinearArrow({
               ? 1
               : -1
 
+      // Last value an emitted resize tick fired at — a new tick fires only
+      // when the (snapped + clamped) value actually changes, so the cue
+      // tracks real size steps instead of every sub-pixel pointer jitter.
+      let lastTickValue = initialValue
+      let previewOverrideIds = new Set<AnyNodeId>()
+
       return {
         overrideId,
+        commit:
+          descriptor.kind === 'linear-resize' && descriptor.commit
+            ? (patch) => descriptor.commit?.(initialNode, patch, sceneApi)
+            : undefined,
         onBegin: () => {
-          if (measureLabel) {
-            useEditor.getState().setActiveHandleDrag({ nodeId, label: measureLabel })
-          }
+          // Always claim the handle-drag scope so the HUD knows a resize is the
+          // active interaction (keeps the idle select hints off-screen). The
+          // dimension-pill handles carry their `measureLabel`; plain resize
+          // arrows use the generic label.
+          useInteractionScope.getState().begin({
+            kind: 'handle-drag',
+            nodeId,
+            handle: measureLabel ?? RESIZE_HANDLE_DRAG_LABEL,
+          })
         },
         onEnd: () => {
-          if (measureLabel) {
-            useEditor.getState().setActiveHandleDrag(null)
+          useInteractionScope.getState().endIf((sc) => sc.kind === 'handle-drag')
+          if (descriptor.kind === 'linear-resize') {
+            descriptor.onDragEnd?.(initialNode as never, sceneApi)
           }
-        },
-        move: ({ event: moveEvent, intersectPlane: intersectMovePlane }) => {
-          const intersection = new Vector3()
-          if (!intersectMovePlane(moveEvent.clientX, moveEvent.clientY, plane, intersection)) {
-            return null
+          if (onDrag) useOpeningGuides.getState().clear()
+          for (const previewId of previewOverrideIds) {
+            useLiveNodeOverrides.getState().clear(previewId)
+            useScene.getState().markDirty(previewId)
           }
-          const intersectionLocal = intersection.clone().applyMatrix4(initialFrameInverse)
+        },
+        move: ({ event: moveEvent, getPointerRay: getMovePointerRay }) => {
           const currentPointer =
-            descriptor.axis === 'x'
-              ? intersectionLocal.x
-              : descriptor.axis === 'y'
-                ? intersectionLocal.y
-                : intersectionLocal.z
+            closestAxisParameterToRay(
+              _resizeOriginW,
+              _resizeAxisW,
+              getMovePointerRay(moveEvent.clientX, moveEvent.clientY, _resizeRay),
+            ) / localToWorldScale
           const delta = currentPointer - initialPointer
           const rawNext = initialValue + delta * factor
-          const snappedNext =
-            gridSnapStep && gridSnapStep > 0 ? snapScalar(rawNext, gridSnapStep) : rawNext
+          const linearDescriptor = descriptor.kind === 'linear-resize' ? descriptor : null
+          const snappedNext = resolveResizeSnapValue({
+            rawValue: rawNext,
+            gridSnapEnabled: linearDescriptor?.gridSnap === true,
+            gridSnapActive: isGridSnapActive(),
+            gridSnapStep: useEditor.getState().gridSnapStep,
+            magneticSnapActive: isMagneticSnapActive(),
+            magneticSnap: linearDescriptor?.magneticSnap
+              ? (value) => linearDescriptor.magneticSnap?.(initialNode, value, sceneApi) ?? value
+              : undefined,
+          })
           const next = Math.min(maxBound, Math.max(minBound, snappedNext))
-          return descriptor.apply(initialNode as never, next, sceneApi) as Partial<AnyNode>
+          if (next !== lastTickValue) {
+            lastTickValue = next
+            sfxEmitter.emit('sfx:resize')
+          }
+          const patch = descriptor.apply(initialNode as never, next, sceneApi) as Partial<AnyNode>
+          if (descriptor.kind === 'linear-resize' && descriptor.previewOverrides) {
+            const previewEntries = descriptor.previewOverrides(initialNode as never, next, sceneApi)
+            const nextPreviewOverrideIds = replacePreviewOverrideIds(
+              previewOverrideIds,
+              previewEntries,
+              (previewId) => {
+                useLiveNodeOverrides.getState().clear(previewId)
+                useScene.getState().markDirty(previewId)
+              },
+            )
+            useLiveNodeOverrides
+              .getState()
+              .setMany(
+                previewEntries.map(([id, previewPatch]) => [
+                  id,
+                  previewPatch as Record<string, unknown>,
+                ]),
+              )
+            for (const [previewId] of previewEntries) {
+              useScene.getState().markDirty(previewId)
+            }
+            previewOverrideIds = nextPreviewOverrideIds
+          }
+          // Let the kind publish live guides for the edge being resized.
+          onDrag?.({ ...(initialNode as object), ...patch } as AnyNode, sceneApi)
+          return patch
         },
       }
     },
@@ -637,10 +821,19 @@ function LinearArrow({
   // X+Z rotation chain matching DoorHeightArrowHandle. When the handle
   // sits below the node (placement Y < 0, e.g. window bottom arrow),
   // flip the Z rotation so the chevron points outward (downward).
+  //
+  // For axis === 'x' with `faceNormal` (wall-mounted opening width arrows),
+  // roll the blade 90° about its own pointing (X) axis so it stands up from
+  // the horizontal XZ plane into the node's facing plane (XY = the wall
+  // face) — otherwise the blade is seen edge-on from the front.
+  const faceNormalX =
+    descriptor.kind === 'linear-resize' && descriptor.axis === 'x' && descriptor.faceNormal === true
   const innerRotation: [number, number, number] =
     descriptor.axis === 'y'
       ? [0, Math.PI / 2, position[1] < 0 ? -Math.PI / 2 : Math.PI / 2]
-      : [0, 0, 0]
+      : faceNormalX
+        ? [Math.PI / 2, 0, 0]
+        : [0, 0, 0]
 
   // Optional guide decoration — linear handles use it for curved-stair
   // width / inner-radius rings; radial handles use it for the column's
@@ -686,7 +879,8 @@ function LinearArrow({
       <>
         {showDecoration && decoration ? (
           <GuideRing
-            radius={decoration.radius(node as never)}
+            center={guideDecorationCenter(decoration, node, placementSceneApi)}
+            radius={guideDecorationRadius(decoration, node, placementSceneApi)}
             y={decoration.y?.(node as never) ?? 0}
           />
         ) : null}
@@ -714,7 +908,8 @@ function LinearArrow({
     <>
       {showDecoration && decoration ? (
         <GuideRing
-          radius={decoration.radius(node as never)}
+          center={guideDecorationCenter(decoration, node, placementSceneApi)}
+          radius={guideDecorationRadius(decoration, node, placementSceneApi)}
           y={decoration.y?.(node as never) ?? 0}
         />
       ) : null}
@@ -726,6 +921,7 @@ function LinearArrow({
         onPointerDown={activate}
         placement={{ position, rotation: [0, rotationY, 0], baseScale }}
         shape="chevron"
+        thin
       >
         {showLabel ? <DimensionLabel position={[0, 0.22, 0]} text={labelText} /> : null}
       </HandleArrow>
@@ -737,7 +933,15 @@ function LinearArrow({
 // e.g. the curved-stair width arrow traces the outer rim, the inner-radius
 // arrow traces the central pillar. Floats at node-local `y`, lies in the
 // XZ plane.
-export function GuideRing({ radius, y }: { radius: number; y: number }) {
+export function GuideRing({
+  center,
+  radius,
+  y,
+}: {
+  center?: readonly [number, number, number]
+  radius: number
+  y: number
+}) {
   const safeRadius = Math.max(radius, 0.01)
   const ringGeometry = useMemo(() => {
     const inner = Math.max(safeRadius - 0.015, 0.001)
@@ -764,7 +968,7 @@ export function GuideRing({ radius, y }: { radius: number; y: number }) {
       frustumCulled={false}
       geometry={ringGeometry}
       material={ringMaterial}
-      position={[0, y, 0]}
+      position={center ? [center[0], y, center[2]] : [0, y, 0]}
       renderOrder={1009}
       rotation={[-Math.PI / 2, 0, 0]}
     />
@@ -873,11 +1077,13 @@ function RotationGuideOutline({ geometry }: { geometry: BufferGeometry }) {
 // from the pivot; the fill is pulled inside it so it reads as the handle
 // swinging around rather than overlapping the icon.
 function RotationWedge({
+  center,
   delta,
   handleAngle,
   orbitRadius,
   y,
 }: {
+  center?: readonly [number, number, number]
   delta: number
   handleAngle: number
   orbitRadius: number
@@ -917,7 +1123,7 @@ function RotationWedge({
   ]
 
   return (
-    <group position={[0, y, 0]}>
+    <group position={center ? [center[0], y, center[2]] : [0, y, 0]}>
       <mesh
         frustumCulled={false}
         geometry={fill}
@@ -971,6 +1177,8 @@ function ArcArrow({
   // corner) render a two-headed curved arrow; everything else (stair
   // sweep, etc.) keeps the chevron.
   const isRotateShape = descriptor.shape === 'rotate'
+  const activeRotateNodeId = useDirectManipulationFeedback((state) => state.activeRotateNodeId)
+  const isDirectRotating = isRotateShape && activeRotateNodeId === liveNode.id
   // 'node-normal' spins the node about its local +Z (a wall item flat against
   // its wall) instead of yaw about world-Y. The drag plane and the icon both
   // tilt into that plane, and the horizontal-only wedge/ring readout is
@@ -1010,7 +1218,8 @@ function ArcArrow({
   // arrow is hovered or dragging. Same recipe as the linear / radial
   // decoration path.
   const decoration = descriptor.decoration
-  const showDecoration = Boolean(decoration) && (isHovered || isDragging)
+  const decorationCenter = guideDecorationCenter(decoration, node, placementSceneApi)
+  const showDecoration = Boolean(decoration) && (isHovered || isDragging || isDirectRotating)
 
   const activate = useHandleDrag({
     kind: 'drag',
@@ -1062,8 +1271,23 @@ function ArcArrow({
       }
       const initialAngle = angleOf(hitWorld)
 
+      // Advertise the rotate interaction so the contextual HUD can surface the
+      // Shift = free-rotation toggle (the angle-step bypass below). Resize
+      // handles route a measurement label here; rotate gets a sentinel label so
+      // the HUD shows the rotate hint, not a dimension pill.
+      if (isRotateShape) {
+        useInteractionScope
+          .getState()
+          .begin({ kind: 'handle-drag', nodeId: node.id, handle: ROTATE_HANDLE_DRAG_LABEL })
+      }
+
       return {
-        onEnd: () => setRotationDelta(null),
+        onEnd: () => {
+          setRotationDelta(null)
+          if (isRotateShape) {
+            useInteractionScope.getState().endIf((sc) => sc.kind === 'handle-drag')
+          }
+        },
         move: ({ event: moveEvent, intersectPlane: intersectMovePlane }) => {
           const hit = new Vector3()
           if (!intersectMovePlane(moveEvent.clientX, moveEvent.clientY, plane, hit)) return null
@@ -1072,9 +1296,8 @@ function ArcArrow({
           while (delta > Math.PI) delta -= 2 * Math.PI
           while (delta < -Math.PI) delta += 2 * Math.PI
 
-          if (moveEvent.shiftKey && descriptor.shape === 'rotate') {
-            const step = Math.PI / 12
-            delta = Math.round(delta / step) * step
+          if (!moveEvent.shiftKey && descriptor.shape === 'rotate') {
+            delta = Math.round(delta / DEFAULT_ANGLE_STEP) * DEFAULT_ANGLE_STEP
           }
 
           if (isRotateShape && !isNodeNormalRot) {
@@ -1086,18 +1309,12 @@ function ArcArrow({
     },
   })
 
-  // Suppress "declared but unused" for `liveNode` — ArcArrow's apply
-  // operates entirely on `initialNode` (snapshot taken inside activate)
-  // and `delta` (live cursor angle), so the live store node doesn't
-  // appear in the rotation pipeline. The prop is still required because
-  // ArrowHandle passes it uniformly to every variant.
-  void liveNode
-
   return (
     <>
       {showDecoration && decoration ? (
         <GuideRing
-          radius={decoration.radius(node as never)}
+          center={guideDecorationCenter(decoration, node, placementSceneApi)}
+          radius={guideDecorationRadius(decoration, node, placementSceneApi)}
           y={decoration.y?.(node as never) ?? 0}
         />
       ) : null}
@@ -1107,16 +1324,23 @@ function ArcArrow({
           ring on any surface — flat ground or a pitched roof. */}
       {rotationDelta !== null ? (
         <RotationWedge
+          center={decorationCenter}
           delta={rotationDelta}
-          handleAngle={Math.atan2(position[2], position[0])}
-          orbitRadius={Math.hypot(position[0], position[2])}
+          handleAngle={Math.atan2(
+            position[2] - (decorationCenter?.[2] ?? 0),
+            position[0] - (decorationCenter?.[0] ?? 0),
+          )}
+          orbitRadius={Math.hypot(
+            position[0] - (decorationCenter?.[0] ?? 0),
+            position[2] - (decorationCenter?.[2] ?? 0),
+          )}
           y={decoration?.y?.(node as never) ?? 0}
         />
       ) : null}
       <HandleArrow
         activeCursor={dragCursor}
         cursor={hoverCursor}
-        hover={isHovered}
+        hover={isHovered || isDirectRotating}
         onHoverChange={setIsHovered}
         onPointerDown={activate}
         placement={{
@@ -1127,69 +1351,12 @@ function ArcArrow({
           baseScale,
         }}
         shape={isRotateShape ? 'curved-arrow' : 'chevron'}
+        thin
       />
     </>
   )
 }
 
-// Free ground-plane move gizmo (the 4-way cross). Press-drag-release: raycast
-// the horizontal plane at the node's base, convert the hit into the node's
-// parent-local frame, add the delta to the node's drag-start position, grid-
-// snap via the descriptor's `snapExtents`, and publish to `useLiveNodeOverrides`
-// each move — committing one write to the store on release. The override stays
-// at base Y; `<FloorElevationSystem>` reads that effective node and owns the
-// presentation-only slab lift so the handle path shares the menu-move stacking
-// contract without storing lifted positions.
-function TranslateArrow({
-  descriptor,
-  node,
-}: {
-  descriptor: TranslateHandle<AnyNode>
-  node: AnyNode
-  handleIndex: number
-  dragControls: HandleDragControls
-  rideObject: Object3D
-}) {
-  const [isHovered, setIsHovered] = useState(false)
-  const { camera } = useThree()
-  const zoom = camera instanceof OrthographicCamera ? 1 / camera.zoom : 1
-  const baseScale = zoom * ARROW_SCALE
-
-  const placementSceneApi = useMemo(() => createSceneApi(useScene), [])
-  const position = descriptor.placement.position(node, placementSceneApi)
-  const cursor: Cursor = 'move'
-  // 'node-normal' constrains the drag to the wall face (plane ⟂ the node's
-  // local +Z). Its cross icon stands up into that plane (tilt about X).
-  const isWallPlane = descriptor.plane === 'node-normal'
-
-  // Same function as the floating action menu's Move button
-  // (`floating-action-menu.tsx` → `handleMove`): arm the registry move tool,
-  // which owns the cursor follow, grid + alignment snap, green guide overlay,
-  // and click-to-commit. Routes both entry points through one path so the
-  // 3D translate gizmo and the floating Move button behave identically.
-  const activate = (event: ThreeEvent<PointerEvent>) => {
-    event.stopPropagation()
-    sfxEmitter.emit('sfx:item-pick')
-    useEditor.getState().setMovingNode(node as never)
-    useViewer.getState().setSelection({ selectedIds: [] })
-  }
-
-  // The cross is built flat in the XZ plane. On a wall, tilt it up about X so
-  // it lies in the item-local XY plane (= the wall face).
-  const iconRotation: [number, number, number] = isWallPlane ? [Math.PI / 2, 0, 0] : [0, 0, 0]
-
-  return (
-    <HandleArrow
-      cursor={cursor}
-      hover={isHovered}
-      onHoverChange={setIsHovered}
-      onPointerDown={activate}
-      placement={{ position, rotation: iconRotation, baseScale }}
-      shape="cross"
-    />
-  )
-}
-
 // Click-to-engage affordance — no drag plumbing, just a click target. The
 // descriptor's `onActivate` receives sceneApi + editorApi so it can engage
 // move tools, endpoint drags, or any other editor-state transition without
@@ -1210,6 +1377,7 @@ function TapActionArrow({
   const rotationY = descriptor.placement.rotationY?.(node, placementSceneApi) ?? 0
   const shape = descriptor.shape ?? 'arrow'
   const cursor: Cursor = descriptor.cursor ?? (shape === 'corner-picker' ? 'move' : 'ew-resize')
+  const round = descriptor.round ?? false
 
   const onActivate = useHandleDrag({
     kind: 'tap',
@@ -1230,20 +1398,75 @@ function TapActionArrow({
         onHoverChange={setIsHovered}
         onPointerDown={onActivate}
         position={position}
+        round={round}
       />
     )
   }
 
-  // Default 'arrow' shape — the standard chevron.
   const baseScale = zoom * ARROW_SCALE
+  // A `move-cross` with `plane: 'node-normal'` stands up into the node's facing
+  // plane (a wall face) like the door / window / wall-item move grips; other
+  // tap-actions keep their in-plane `rotationY`.
+  const rotation: [number, number, number] =
+    descriptor.plane === 'node-normal' ? NODE_NORMAL_TILT : [0, rotationY, 0]
   return (
     <HandleArrow
       cursor={cursor}
       hover={isHovered}
       onHoverChange={setIsHovered}
       onPointerDown={onActivate}
+      placement={{ position, rotation, baseScale }}
+      shape={shape === 'move-cross' ? 'move-cross' : 'chevron'}
+      thin
+    />
+  )
+}
+
+// Click-to-latch cube. A persistent grip (the `tracker` cube) that toggles
+// the visibility of every arrow tagged with its `latchGroup` on click. Sized
+// to match the duct selection cube (`baseScale = zoom`, full TRACKER_CUBE_SIZE)
+// so every latch grip reads the same across the app. Stays highlighted while
+// its group is open so the user can tell it's engaged.
+function LatchCube({
+  descriptor,
+  node,
+  open,
+  onToggle,
+}: {
+  descriptor: LatchHandle<AnyNode>
+  node: AnyNode
+  open: boolean
+  onToggle: (group: string) => void
+}) {
+  const [isHovered, setIsHovered] = useState(false)
+  const { camera } = useThree()
+  const zoom = camera instanceof OrthographicCamera ? 1 / camera.zoom : 1
+  const baseScale = zoom
+
+  const placementSceneApi = useMemo(() => createSceneApi(useScene), [])
+  const position = descriptor.placement.position(node, placementSceneApi)
+  const rotationY = descriptor.placement.rotationY?.(node, placementSceneApi) ?? 0
+
+  // Route through the shared tap path so the cube click is swallowed before it
+  // reaches the select tool — stops R3F propagation, suppresses box-select, and
+  // eats the trailing DOM click that would otherwise select the host node.
+  const onPointerDown = useHandleDrag({
+    kind: 'tap',
+    onTap: () => {
+      setIsHovered(false)
+      onToggle(descriptor.group)
+    },
+  })
+
+  return (
+    <HandleArrow
+      cursor="grab"
+      hover={isHovered || open}
+      hoverScale={1.15}
+      onHoverChange={setIsHovered}
+      onPointerDown={onPointerDown}
       placement={{ position, rotation: [0, rotationY, 0], baseScale }}
-      shape="chevron"
+      shape="tracker"
     />
   )
 }
@@ -1281,6 +1504,7 @@ function CornerPickerShape({
   hover,
   onHoverChange,
   onPointerDown,
+  round = false,
 }: {
   position: readonly [number, number, number]
   height: number
@@ -1289,6 +1513,7 @@ function CornerPickerShape({
   hover: boolean
   onHoverChange: (hovered: boolean) => void
   onPointerDown: (event: ThreeEvent<PointerEvent>) => void
+  round?: boolean
 }) {
   const dashedGeometry = useMemo(() => buildDashedVerticalGeometry(height), [height])
   useEffect(() => () => dashedGeometry.dispose(), [dashedGeometry])
@@ -1358,7 +1583,10 @@ function CornerPickerShape({
         position={position}
         renderOrder={1001}
       />
-      <group position={[position[0], CORNER_FLOOR_OFFSET, position[2]]} ref={billboardRef}>
+      <group
+        position={[position[0], position[1] + CORNER_FLOOR_OFFSET, position[2]]}
+        ref={billboardRef}
+      >
         <HandleArrow
           cursor={cursor}
           hover={hover}
@@ -1366,10 +1594,11 @@ function CornerPickerShape({
           onHoverChange={onHoverChange}
           onPointerDown={onPointerDown}
           placement={{ position: [0, 0, 0], baseScale }}
+          round={round}
           shape="corner-picker"
         />
         <mesh material={ringMaterial} renderOrder={1002} scale={scale}>
-          <ringGeometry args={[CORNER_HEX_RADIUS, CORNER_HEX_RADIUS * 1.18, 6]} />
+          <ringGeometry args={[CORNER_HEX_RADIUS, CORNER_HEX_RADIUS * 1.18, round ? 32 : 6]} />
         </mesh>
       </group>
     </>