npm - @pascal-app/editor - Versions diffs - 0.7.0 → 0.9.1 - Mend

@pascal-app/editor 0.7.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (244) hide show

package/package.json +12 -13
package/src/components/editor/alignment-3d-guide-layer.tsx +160 -0
package/src/components/editor/custom-camera-controls.tsx +755 -25
package/src/components/editor/editor-layout-mobile.tsx +3 -3
package/src/components/editor/editor-layout-v2.tsx +62 -54
package/src/components/editor/export-manager.tsx +32 -3
package/src/components/editor/first-person/build-collider-world.test.ts +149 -0
package/src/components/editor/first-person/build-collider-world.ts +203 -87
package/src/components/editor/first-person/bvh-ecctrl.tsx +127 -62
package/src/components/editor/first-person-controls.tsx +836 -31
package/src/components/editor/floating-action-menu.tsx +287 -196
package/src/components/editor/floating-building-action-menu.tsx +1 -1
package/src/components/editor/floorplan-panel.tsx +5837 -12006
package/src/components/editor/grid.tsx +51 -17
package/src/components/editor/group-move-handle.tsx +316 -0
package/src/components/editor/group-rotate-handle.tsx +382 -0
package/src/components/editor/group-transform-shared.test.ts +205 -0
package/src/components/editor/group-transform-shared.ts +256 -0
package/src/components/editor/handles/handle-arrow.tsx +523 -0
package/src/components/editor/handles/use-handle-drag.ts +213 -0
package/src/components/editor/index.tsx +234 -190
package/src/components/editor/measurement-pill.tsx +75 -0
package/src/components/editor/node-arrow-handles.tsx +1453 -0
package/src/components/editor/selection-manager.tsx +435 -158
package/src/components/editor/site-edge-labels.tsx +44 -20
package/src/components/editor/slab-hole-highlights.tsx +466 -0
package/src/components/editor/snapshot-capture-overlay.tsx +539 -0
package/src/components/editor/thumbnail-generator.tsx +27 -64
package/src/components/editor/use-floorplan-background-placement.ts +122 -35
package/src/components/editor/use-floorplan-hit-testing.ts +24 -0
package/src/components/editor/use-floorplan-scene-data.ts +14 -2
package/src/components/editor/wall-measurement-label.tsx +11 -6
package/src/components/editor/wall-move-side-handles.tsx +855 -0
package/src/components/editor/wall-opening-highlights.tsx +181 -0
package/src/components/editor/wall-snap-beacon-layer.tsx +150 -0
package/src/components/editor-2d/floorplan-action-menu-layer.tsx +6 -1
package/src/components/editor-2d/floorplan-alignment-guide-layer.tsx +142 -0
package/src/components/editor-2d/floorplan-cursor-indicator-overlay.tsx +5 -3
package/src/components/editor-2d/floorplan-registry-action-menu.tsx +227 -0
package/src/components/editor-2d/floorplan-registry-move-overlay.tsx +616 -0
package/src/components/editor-2d/floorplan-render-context.tsx +62 -0
package/src/components/editor-2d/floorplan-snap-beacon-layer.tsx +75 -0
package/src/components/editor-2d/floorplan-wall-move-ghost-layer.tsx +47 -0
package/src/components/editor-2d/renderers/floorplan-draft-layer.tsx +6 -1
package/src/components/editor-2d/renderers/floorplan-geometry-renderer.tsx +266 -0
package/src/components/editor-2d/renderers/floorplan-measurements-layer.tsx +108 -61
package/src/components/editor-2d/renderers/floorplan-placement-preview-layer.tsx +59 -0
package/src/components/editor-2d/renderers/floorplan-registry-layer.tsx +1963 -0
package/src/components/editor-2d/renderers/floorplan-stair-layer.tsx +29 -14
package/src/components/editor-2d/svg-paths.ts +10 -2
package/src/components/systems/ceiling/ceiling-selection-affordance-system.tsx +30 -9
package/src/components/systems/ceiling/ceiling-system.tsx +12 -8
package/src/components/systems/roof/roof-edit-system.tsx +86 -12
package/src/components/systems/stair/stair-edit-system.tsx +2 -2
package/src/components/systems/zone/zone-label-editor-system.tsx +0 -0
package/src/components/systems/zone/zone-system.tsx +0 -0
package/src/components/tools/elevator/elevator-defaults.ts +8 -0
package/src/components/tools/elevator/elevator-tool.tsx +349 -0
package/src/components/tools/elevator/move-elevator-tool.tsx +252 -0
package/src/components/tools/fence/fence-drafting.ts +64 -22
package/src/components/tools/item/move-tool.tsx +40 -107
package/src/components/tools/item/placement-math.test.ts +10 -0
package/src/components/tools/item/placement-math.ts +33 -9
package/src/components/tools/item/placement-strategies.ts +201 -25
package/src/components/tools/item/placement-types.ts +10 -1
package/src/components/tools/item/use-draft-node.ts +20 -2
package/src/components/tools/item/use-placement-coordinator.tsx +700 -299
package/src/components/tools/registry/move-registry-node-tool.tsx +602 -0
package/src/components/tools/roof/roof-tool.tsx +108 -12
package/src/components/tools/select/box-select-state.ts +77 -0
package/src/components/tools/select/box-select-tool.tsx +324 -543
package/src/components/tools/select/plane-box-select-tool.tsx +577 -0
package/src/components/tools/select/screen-rectangle-selection.ts +84 -0
package/src/components/tools/select/select-candidates.test.ts +109 -0
package/src/components/tools/select/select-candidates.ts +85 -0
package/src/components/tools/shared/affordance-dispatch.ts +30 -0
package/src/components/tools/shared/drag-bounding-box.tsx +171 -0
package/src/components/tools/shared/floor-stack-preview.ts +25 -0
package/src/components/tools/shared/fresh-placement-visibility.ts +61 -0
package/src/components/tools/shared/placement-box-geometry.ts +123 -0
package/src/components/tools/shared/placement-box.tsx +123 -0
package/src/components/tools/shared/polygon-editor.tsx +617 -167
package/src/components/tools/shared/segment-angle.ts +57 -1
package/src/components/tools/site/site-boundary-editor.tsx +464 -12
package/src/components/tools/site/site-flag-model.ts +18 -0
package/src/components/tools/stair/stair-defaults.ts +1 -1
package/src/components/tools/stair/stair-tool.tsx +269 -35
package/src/components/tools/tool-manager.tsx +172 -56
package/src/components/tools/wall/wall-drafting.ts +98 -98
package/src/components/tools/wall/wall-snap-geometry.test.ts +79 -0
package/src/components/tools/wall/wall-snap-geometry.ts +270 -0
package/src/components/tools/zone/zone-tool.tsx +36 -11
package/src/components/ui/action-menu/action-button.tsx +21 -1
package/src/components/ui/action-menu/camera-actions.tsx +0 -0
package/src/components/ui/action-menu/control-modes.tsx +5 -76
package/src/components/ui/action-menu/furnish-tools.tsx +6 -92
package/src/components/ui/action-menu/index.tsx +33 -196
package/src/components/ui/action-menu/structure-tools.tsx +13 -88
package/src/components/ui/action-menu/view-toggles.tsx +262 -37
package/src/components/ui/command-palette/editor-commands.tsx +24 -17
package/src/components/ui/command-palette/index.tsx +6 -256
package/src/components/ui/controls/material-paint-panel.tsx +83 -0
package/src/components/ui/controls/material-picker.tsx +17 -35
package/src/components/ui/controls/metric-control.tsx +33 -11
package/src/components/ui/floating-level-selector.tsx +48 -11
package/src/components/ui/helpers/helper-manager.tsx +21 -17
package/src/components/ui/helpers/registered-tool-helper.tsx +25 -0
package/src/components/ui/item-catalog/catalog-items.tsx +1743 -315
package/src/components/ui/item-catalog/item-catalog.tsx +91 -46
package/src/components/ui/level-duplicate-dialog.tsx +5 -6
package/src/components/ui/panels/node-display.ts +1 -0
package/src/components/ui/panels/paint-panel.tsx +66 -41
package/src/components/ui/panels/panel-manager.tsx +33 -74
package/src/components/ui/panels/panel-wrapper.tsx +217 -12
package/src/components/ui/panels/parametric-inspector.tsx +469 -0
package/src/components/ui/panels/reference-panel.tsx +28 -13
package/src/components/ui/primitives/dropdown-menu.tsx +12 -8
package/src/components/ui/primitives/number-input.tsx +1 -1
package/src/components/ui/primitives/sidebar.tsx +0 -0
package/src/components/ui/scene-loader.tsx +1 -3
package/src/components/ui/sidebar/app-sidebar.tsx +0 -0
package/src/components/ui/sidebar/icon-rail.tsx +0 -0
package/src/components/ui/sidebar/panels/items-panel/function-tree-panel.tsx +263 -0
package/src/components/ui/sidebar/panels/items-panel/index.tsx +404 -0
package/src/components/ui/sidebar/panels/settings-panel/index.tsx +59 -9
package/src/components/ui/sidebar/panels/settings-panel/keyboard-shortcuts-dialog.tsx +6 -1
package/src/components/ui/sidebar/panels/settings-panel/load-build-dialog.tsx +259 -0
package/src/components/ui/sidebar/panels/site-panel/building-tree-node.tsx +3 -1
package/src/components/ui/sidebar/panels/site-panel/ceiling-tree-node.tsx +5 -2
package/src/components/ui/sidebar/panels/site-panel/chimney-tree-node.tsx +83 -0
package/src/components/ui/sidebar/panels/site-panel/dormer-tree-node.tsx +89 -0
package/src/components/ui/sidebar/panels/site-panel/elevator-tree-node.tsx +75 -0
package/src/components/ui/sidebar/panels/site-panel/fence-tree-node.tsx +2 -2
package/src/components/ui/sidebar/panels/site-panel/gutter-tree-node.tsx +83 -0
package/src/components/ui/sidebar/panels/site-panel/index.tsx +8 -12
package/src/components/ui/sidebar/panels/site-panel/level-tree-node.tsx +2 -1
package/src/components/ui/sidebar/panels/site-panel/registry-tree-node.tsx +93 -0
package/src/components/ui/sidebar/panels/site-panel/roof-tree-node.tsx +41 -5
package/src/components/ui/sidebar/panels/site-panel/shelf-tree-node.tsx +128 -0
package/src/components/ui/sidebar/panels/site-panel/slab-tree-node.tsx +5 -2
package/src/components/ui/sidebar/panels/site-panel/solar-panel-tree-node.tsx +83 -0
package/src/components/ui/sidebar/panels/site-panel/spawn-tree-node.tsx +1 -1
package/src/components/ui/sidebar/panels/site-panel/tree-node.tsx +68 -34
package/src/components/ui/sidebar/panels/site-panel/zone-tree-node.tsx +3 -1
package/src/components/ui/sidebar/panels/zone-panel/index.tsx +52 -3
package/src/components/ui/sidebar/tab-bar.tsx +61 -1
package/src/components/ui/slider.tsx +1 -1
package/src/components/viewer-overlay.tsx +169 -52
package/src/components/viewer-zone-system.tsx +1 -1
package/src/hooks/use-auto-save.ts +24 -3
package/src/hooks/use-ceiling-events.ts +175 -0
package/src/hooks/use-drag-action.ts +124 -0
package/src/hooks/use-keyboard.ts +125 -62
package/src/hooks/use-selection.ts +64 -0
package/src/index.tsx +243 -4
package/src/lib/constants.ts +6 -2
package/src/lib/editor-api.ts +62 -0
package/src/lib/elevator-support.ts +96 -0
package/src/lib/floorplan/apply-alignment.ts +111 -0
package/src/lib/floorplan/index.ts +7 -0
package/src/lib/floorplan/selection-tool.ts +40 -0
package/src/lib/floorplan/stairs.ts +12 -1
package/src/lib/fresh-planar-placement.test.ts +102 -0
package/src/lib/fresh-planar-placement.ts +63 -0
package/src/lib/history.ts +2 -1
package/src/lib/level-duplication.test.ts +0 -2
package/src/lib/level-duplication.ts +55 -43
package/src/lib/level-name.ts +11 -0
package/src/lib/material-paint.ts +212 -20
package/src/lib/placement-metadata.ts +29 -0
package/src/lib/planar-cursor-placement.test.ts +43 -0
package/src/lib/planar-cursor-placement.ts +42 -0
package/src/lib/roof-duplication.ts +2 -2
package/src/lib/scene-bounds.ts +1 -1
package/src/lib/scene-clipboard.ts +267 -0
package/src/lib/scene.ts +13 -4
package/src/lib/sfx-bus.ts +25 -1
package/src/lib/sfx-player.ts +75 -27
package/src/lib/site-boundary.ts +1 -0
package/src/lib/stair-duplication.ts +2 -2
package/src/lib/stair-levels.test.ts +146 -0
package/src/lib/stair-levels.ts +177 -0
package/src/lib/world-grid-snap.ts +199 -0
package/src/lib/zone-content.ts +130 -0
package/src/store/use-alignment-guides.ts +21 -0
package/src/store/use-editor.tsx +342 -91
package/src/store/use-placement-preview.ts +31 -0
package/src/store/use-wall-move-ghosts.ts +36 -0
package/src/store/use-wall-snap-indicator.ts +32 -0
package/tsconfig.json +2 -1
package/src/components/editor/preset-thumbnail-generator.tsx +0 -125
package/src/components/editor-2d/renderers/floorplan-roof-layer.tsx +0 -113
package/src/components/feedback-dialog.tsx +0 -265
package/src/components/pascal-radio.tsx +0 -280
package/src/components/preview-button.tsx +0 -16
package/src/components/tools/building/move-building-tool.tsx +0 -157
package/src/components/tools/ceiling/ceiling-boundary-editor.tsx +0 -43
package/src/components/tools/ceiling/ceiling-hole-editor.tsx +0 -49
package/src/components/tools/ceiling/ceiling-tool.tsx +0 -465
package/src/components/tools/ceiling/move-ceiling-tool.tsx +0 -257
package/src/components/tools/column/column-tool.tsx +0 -97
package/src/components/tools/column/move-column-tool.tsx +0 -105
package/src/components/tools/door/door-math.ts +0 -110
package/src/components/tools/door/door-tool.tsx +0 -324
package/src/components/tools/door/move-door-tool.tsx +0 -412
package/src/components/tools/fence/curve-fence-tool.tsx +0 -179
package/src/components/tools/fence/fence-tool.tsx +0 -346
package/src/components/tools/fence/move-fence-endpoint-tool.tsx +0 -438
package/src/components/tools/fence/move-fence-tool.tsx +0 -298
package/src/components/tools/item/item-tool.tsx +0 -26
package/src/components/tools/roof/move-roof-tool.tsx +0 -359
package/src/components/tools/slab/move-slab-tool.tsx +0 -182
package/src/components/tools/slab/slab-boundary-editor.tsx +0 -43
package/src/components/tools/slab/slab-hole-editor.tsx +0 -49
package/src/components/tools/slab/slab-tool.tsx +0 -322
package/src/components/tools/spawn/move-spawn-tool.tsx +0 -101
package/src/components/tools/spawn/spawn-tool.tsx +0 -130
package/src/components/tools/wall/curve-wall-tool.tsx +0 -176
package/src/components/tools/wall/move-wall-endpoint-tool.tsx +0 -423
package/src/components/tools/wall/move-wall-tool.tsx +0 -356
package/src/components/tools/wall/wall-tool.tsx +0 -332
package/src/components/tools/window/move-window-tool.tsx +0 -447
package/src/components/tools/window/window-math.ts +0 -117
package/src/components/tools/window/window-tool.tsx +0 -332
package/src/components/ui/helpers/ceiling-helper.tsx +0 -20
package/src/components/ui/helpers/slab-helper.tsx +0 -20
package/src/components/ui/helpers/wall-helper.tsx +0 -20
package/src/components/ui/panels/ceiling-panel.tsx +0 -250
package/src/components/ui/panels/column-panel.tsx +0 -715
package/src/components/ui/panels/door-panel.tsx +0 -1292
package/src/components/ui/panels/fence-panel.tsx +0 -227
package/src/components/ui/panels/item-panel.tsx +0 -306
package/src/components/ui/panels/presets/presets-popover.tsx +0 -511
package/src/components/ui/panels/roof-panel.tsx +0 -230
package/src/components/ui/panels/roof-segment-panel.tsx +0 -311
package/src/components/ui/panels/slab-panel.tsx +0 -250
package/src/components/ui/panels/spawn-panel.tsx +0 -155
package/src/components/ui/panels/stair-panel.tsx +0 -525
package/src/components/ui/panels/stair-segment-panel.tsx +0 -325
package/src/components/ui/panels/wall-panel.tsx +0 -177
package/src/components/ui/panels/window-panel.tsx +0 -960
package/src/components/ui/viewer-toolbar.tsx +0 -436
package/src/contexts/presets-context.tsx +0 -121
package/src/hooks/use-contextual-tools.ts +0 -61

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

@@ -0,0 +1,1453 @@
+'use client'
+import {
+  type AnyNode,
+  type AnyNodeId,
+  type ArcResizeHandle,
+  type Cursor,
+  createSceneApi,
+  type HandleDescriptor,
+  type HandlePortal,
+  type LinearResizeHandle,
+  nodeRegistry,
+  type RadialResizeHandle,
+  sceneRegistry,
+  snapScalar,
+  type TapActionHandle,
+  type TranslateHandle,
+  useLiveNodeOverrides,
+  useScene,
+} from '@pascal-app/core'
+import { useViewer } from '@pascal-app/viewer'
+import { Html } from '@react-three/drei'
+import { createPortal, type ThreeEvent, useFrame, useThree } from '@react-three/fiber'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import {
+  BufferGeometry,
+  Color,
+  CylinderGeometry,
+  DoubleSide,
+  Float32BufferAttribute,
+  type Group,
+  Matrix4,
+  type Object3D,
+  OrthographicCamera,
+  Plane,
+  Quaternion,
+  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 { createEditorApi } from '../../lib/editor-api'
+import { sfxEmitter } from '../../lib/sfx-bus'
+import useEditor from '../../store/use-editor'
+import { formatAngleRadians } from '../tools/shared/segment-angle'
+import {
+  ARROW_COLOR,
+  ARROW_HOVER_COLOR,
+  ARROW_SCALE,
+  CORNER_HEX_RADIUS,
+  HandleArrow,
+  NO_RAYCAST,
+} from './handles/handle-arrow'
+import { type HandleDragControls, useHandleDrag } from './handles/use-handle-drag'
+export {
+  ARROW_COLOR,
+  ARROW_HOVER_COLOR,
+  ARROW_SCALE,
+  createArrowHitAreaGeometry,
+  createEndpointHitAreaGeometry,
+  createMoveCrossHandleGeometry,
+  createRotateArrowHandleGeometry,
+  createRotateArrowHitAreaGeometry,
+  HIT_AREA_MARGIN,
+  InvisibleHandleHitArea,
+  NO_RAYCAST,
+  useArrowMaterial,
+  useInvisibleHitAreaMaterial,
+} from './handles/handle-arrow'
+export { swallowNextClick } from './handles/use-handle-drag'
+// How far a DOWNWARD tracker's dashed leader pokes past its cube so the
+// dashes visibly thread through it (the cube sits ON the line, not at
+// its end). Upward trackers — wall / chimney height — stop at the cube.
+const TRACKER_THROUGH = 0.12
+// 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 {
+  if (unit === 'imperial') {
+    const feet = value * 3.280_84
+    const wholeFeet = Math.floor(feet)
+    const inches = Math.round((feet - wholeFeet) * 12)
+    if (inches === 12) return `${wholeFeet + 1}'0"`
+    return `${wholeFeet}'${inches}"`
+  }
+  return `${Number.parseFloat(value.toFixed(2))}m`
+}
+// In-world dimension chip rendered next to a resize arrow during hover
+// or drag. Uses the same screen-space `<Html>` recipe + text-shadow
+// halo as the wall measurement label so it reads at every camera angle.
+function DimensionLabel({
+  position,
+  text,
+}: {
+  position: readonly [number, number, number]
+  text: string
+}) {
+  return (
+    <Html
+      center
+      position={position as unknown as [number, number, number]}
+      style={{ pointerEvents: 'none', userSelect: 'none' }}
+      zIndexRange={[25, 0]}
+    >
+      <div
+        className="whitespace-nowrap font-bold font-mono text-[13px]"
+        style={{
+          color: '#fafafa',
+          textShadow:
+            '-1.5px -1.5px 0 #0b0b0b, 1.5px -1.5px 0 #0b0b0b, -1.5px 1.5px 0 #0b0b0b, 1.5px 1.5px 0 #0b0b0b, 0 0 4px #0b0b0b',
+        }}
+      >
+        {text}
+      </div>
+    </Html>
+  )
+}
+export function NodeArrowHandles() {
+  const selectedIds = useViewer((state) => state.selection.selectedIds)
+  const mode = useEditor((state) => state.mode)
+  const isFloorplanHovered = useEditor((state) => state.isFloorplanHovered)
+  const movingNode = useEditor((state) => state.movingNode)
+  const placementDragMode = useEditor((state) => state.placementDragMode)
+  // 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,
+  )
+  // Merge any live drag override so the arrows themselves (positions,
+  // ring decorations) track the in-flight drag instead of freezing at
+  // pre-drag values. Subscribe to just this node's entry so unrelated
+  // override writes don't re-render the handle stack.
+  const liveOverride = useLiveNodeOverrides((s) =>
+    rawNode ? s.overrides.get(rawNode.id) : undefined,
+  )
+  const node = useMemo<AnyNode | null>(
+    () => (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 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 shouldRender =
+    Boolean(node && descriptors?.length) &&
+    !isFloorplanHovered &&
+    mode !== 'delete' &&
+    (!movingNode || isOwnPressDragMove) &&
+    !movingWallEndpoint &&
+    !movingFenceEndpoint &&
+    !curvingWall &&
+    !curvingFence
+  if (!shouldRender || !node || !descriptors) return null
+  // Key by the selected node id so switching selection REMOUNTS the rig.
+  // The portal target + ride-mesh refs are seeded from the scene registry
+  // in `useState` initializers; without a remount they'd persist from the
+  // previous selection and the arrows would ride the old node's world pose
+  // (right local placements, wrong frame) until the resolve effect happened
+  // to catch up. Remounting re-resolves both refs synchronously for the new
+  // node, so the arrows land in the right place the instant it's selected.
+  return <NodeArrowHandlesForNode descriptors={descriptors} key={node.id} node={node} />
+}
+// Resolves the portal target + ride mesh chain. Descriptor-level `portal`
+// toggles between two layout patterns; descriptor placement is *always* in
+// the selected node's local frame regardless of mode.
+//
+//  - 'parent' (default): mount inside the selected node's parent mesh.
+//    The wrapper mirrors the node's own local pose, so handles live in
+//    node-local coords directly. No inner group. Used by columns / walls
+//    / anything where the node IS the thing the user selected and whose
+//    rotation should drive the handle frame.
+//  - 'grandparent': mount inside the grandparent mesh (to escape the
+//    parent's selection-outline traversal). The wrapper mirrors the
+//    parent mesh's local pose; a nested inner group mirrors the node's
+//    own local pose. Handles end up in node-local coords. Used by doors /
+//    windows — handles need to ride the wall's rotation but not be
+//    children of the wall mesh.
+function NodeArrowHandlesForNode({
+  node,
+  descriptors,
+}: {
+  node: AnyNode
+  descriptors: HandleDescriptor[]
+}) {
+  const parentId = node.parentId ?? null
+  const grandparentId = useScene((state) => {
+    if (!parentId) return null
+    const parent = state.nodes[parentId as AnyNodeId]
+    return parent?.parentId ?? null
+  })
+  const portalMode: HandlePortal = descriptors.some((d) => d.portal === 'grandparent')
+    ? 'grandparent'
+    : 'parent'
+  // Portal target: the mesh we createPortal into.
+  const portalTargetId = portalMode === 'grandparent' ? grandparentId : parentId
+  // Outer wrapper mirrors this mesh's local pose. For 'parent' mode the
+  // outer IS the node (so handles + drag math both live in node-local).
+  // For 'grandparent' the outer rides the parent and an inner group adds
+  // the node's own pose.
+  const outerRideId = portalMode === 'grandparent' ? parentId : (node.id as AnyNodeId)
+  const innerRideId = portalMode === 'grandparent' ? (node.id as AnyNodeId) : null
+  const [portalObject, setPortalObject] = useState<Object3D | null>(() =>
+    portalTargetId ? (sceneRegistry.nodes.get(portalTargetId as AnyNodeId) ?? null) : null,
+  )
+  const [outerRide, setOuterRide] = useState<Object3D | null>(() =>
+    outerRideId ? (sceneRegistry.nodes.get(outerRideId as AnyNodeId) ?? null) : null,
+  )
+  const [innerRide, setInnerRide] = useState<Object3D | null>(() =>
+    innerRideId ? (sceneRegistry.nodes.get(innerRideId as AnyNodeId) ?? null) : null,
+  )
+  useEffect(() => {
+    let frameId = 0
+    const resolve = () => {
+      const nextPortal = portalTargetId
+        ? (sceneRegistry.nodes.get(portalTargetId as AnyNodeId) ?? null)
+        : null
+      const nextOuter = outerRideId
+        ? (sceneRegistry.nodes.get(outerRideId as AnyNodeId) ?? null)
+        : null
+      const nextInner = innerRideId
+        ? (sceneRegistry.nodes.get(innerRideId as AnyNodeId) ?? null)
+        : null
+      setPortalObject((cur) => (cur === nextPortal ? cur : nextPortal))
+      setOuterRide((cur) => (cur === nextOuter ? cur : nextOuter))
+      setInnerRide((cur) => (cur === nextInner ? cur : nextInner))
+      // Inner ride is optional ('parent' mode skips it).
+      const needInner = innerRideId !== null
+      if (!nextPortal || !nextOuter || (needInner && !nextInner)) {
+        frameId = window.requestAnimationFrame(resolve)
+      }
+    }
+    resolve()
+    return () => {
+      if (frameId) window.cancelAnimationFrame(frameId)
+    }
+  }, [portalTargetId, outerRideId, innerRideId])
+  const outerRef = useRef<Group>(null)
+  const innerRef = useRef<Group>(null)
+  // Keep arrow objects on SCENE_LAYER so the post-processing scenePass
+  // captures them in the depth/normal MRT — that's what feeds the ink-edge
+  // shader, and it's the reason the wall height arrow (which also stays on
+  // SCENE_LAYER) reads as a proper 3D plate with outlined edges. Putting
+  // them on EDITOR_LAYER hides them from scenePass and the chevron renders
+  // flat. Arrows are only mounted while a node is selected, so thumbnail
+  // captures (which never have selection) don't need the layer-based
+  // exclusion the wall arrow also goes without.
+  useFrame(() => {
+    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
+  // descriptor index here and snapshots the store node at drag-start.
+  // Non-active arrows re-render against the snapshot + a freeze offset
+  // that undoes the mesh's `position` drift in node-local frame — so
+  // asymmetric resize (width L/R, length L/R) doesn't visually slide the
+  // depth / height / rotate chevrons. They stay anchored at their
+  // pre-drag world positions for the duration of the drag.
+  //
+  // Hooks must sit ABOVE the early-return guard below — the registry-
+  // resolve `useEffect` flips `portalObject` from null → object after
+  // the first frame, so a guard between two hooks would change the
+  // 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)
+  const dragControls = useMemo<HandleDragControls>(
+    () => ({
+      onStart: (index: number, snapshot: AnyNode) => {
+        setActiveIndex(index)
+        setPreDragNode(snapshot)
+      },
+      onEnd: () => {
+        setActiveIndex(null)
+        setPreDragNode(null)
+      },
+    }),
+    [],
+  )
+  if (!portalObject || !outerRide || (innerRideId !== null && !innerRide)) return null
+  // `arrowFrame` is the Object3D used as the spatial reference for the
+  // per-arrow drag math — its world matrix maps node-local coords to
+  // world. In 'parent' mode that's the outer ride (= the node mesh
+  // itself). In 'grandparent' mode it's the inner ride (= the node mesh)
+  // because the inner group mirrors the node's local pose under the
+  // wall-riding outer wrapper.
+  const arrowFrame = innerRide ?? outerRide
+  // A translate drag moves `position`, so the whole handle rig should travel
+  // with the mesh — the freeze-at-pre-drag mechanism (built for asymmetric
+  // 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}
+    />
+  ))
+  return createPortal(
+    <group ref={outerRef}>
+      {innerRideId !== null ? <group ref={innerRef}>{arrows}</group> : arrows}
+    </group>,
+    portalObject,
+  )
+}
+// Offset, in node-local frame, that compensates for `position` drift on
+// the mesh during an asymmetric resize. Width/length L+R recompute
+// `position` so the anchored edge stays world-fixed — the renderer
+// follows that override, the ride object moves, and every arrow under
+// it would drift along with the mesh center. Subtracting this offset
+// from a non-active arrow's local placement undoes that drift so it
+// stays at its pre-drag world position.
+//
+// Rotation drags don't change `position`, so the offset collapses to
+// zero and non-active arrows naturally rotate with the mesh — which is
+// the desired behaviour (the whole rig rotates as a unit).
+function computeFreezeOffset(liveNode: AnyNode, preDragNode: AnyNode): [number, number, number] {
+  // Not every node in the union carries a `position` field (sites are the
+  // notable holdout — they don't have handles anyway, but TypeScript still
+  // requires us to discriminate). Guarded access keeps the freeze logic
+  // safe for the few node kinds that lack the field.
+  const liveP = (liveNode as { position?: readonly [number, number, number] }).position ?? [0, 0, 0]
+  const preP = (preDragNode as { position?: readonly [number, number, number] }).position ?? [
+    0, 0, 0,
+  ]
+  const deltaWorldX = liveP[0] - preP[0]
+  const deltaWorldY = liveP[1] - preP[1]
+  const deltaWorldZ = liveP[2] - preP[2]
+  const rotY = (preDragNode as { rotation?: number }).rotation ?? 0
+  // World → node-local for Y-axis rotation by rotY (THREE.Object3D
+  // rotation-y convention): inverse is rotation by -rotY around +Y.
+  const cosR = Math.cos(rotY)
+  const sinR = Math.sin(rotY)
+  const deltaLocalX = cosR * deltaWorldX - sinR * deltaWorldZ
+  const deltaLocalZ = sinR * deltaWorldX + cosR * deltaWorldZ
+  return [deltaLocalX, deltaWorldY, deltaLocalZ]
+}
+function ArrowHandle({
+  descriptor,
+  liveNode,
+  preDragNode,
+  activeIndex,
+  handleIndex,
+  dragControls,
+  rideObject,
+  suppressFreeze,
+}: {
+  descriptor: HandleDescriptor
+  liveNode: AnyNode
+  preDragNode: AnyNode | null
+  activeIndex: number | null
+  handleIndex: number
+  dragControls: HandleDragControls
+  rideObject: Object3D
+  /** When the active drag is a translate, non-active arrows ride the moving
+   *  mesh instead of freezing at their pre-drag world position. */
+  suppressFreeze?: boolean
+}) {
+  // During a drag, non-active arrows render against the pre-drag store
+  // snapshot. The active arrow always uses the live (override-merged)
+  // node so it tracks the cursor.
+  const isOtherActive = activeIndex !== null && activeIndex !== handleIndex && preDragNode !== null
+  const placementNode = isOtherActive ? (preDragNode as AnyNode) : liveNode
+  const freezeOffset =
+    isOtherActive && preDragNode && !suppressFreeze
+      ? computeFreezeOffset(liveNode, preDragNode)
+      : null
+  if (descriptor.kind === 'linear-resize' || descriptor.kind === 'radial-resize') {
+    return (
+      <LinearArrow
+        descriptor={descriptor}
+        dragControls={dragControls}
+        freezeOffset={freezeOffset}
+        handleIndex={handleIndex}
+        liveNode={liveNode}
+        node={placementNode}
+        rideObject={rideObject}
+      />
+    )
+  }
+  if (descriptor.kind === 'arc-resize') {
+    return (
+      <ArcArrow
+        descriptor={descriptor}
+        dragControls={dragControls}
+        freezeOffset={freezeOffset}
+        handleIndex={handleIndex}
+        liveNode={liveNode}
+        node={placementNode}
+        rideObject={rideObject}
+      />
+    )
+  }
+  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
+    // exists to stop arrows sliding when an asymmetric width/length resize
+    // re-centers the mesh — doesn't apply to them. Track the live node so
+    // their height-dependent placement (side arrows ride the top, corner
+    // leaders span the full height) follows a height drag in real time.
+    return <TapActionArrow descriptor={descriptor} node={liveNode} />
+  }
+  // endpoint-move not yet implemented.
+  return null
+}
+function pickCursor(descriptor: LinearResizeHandle<AnyNode> | RadialResizeHandle<AnyNode>): Cursor {
+  if (descriptor.kind === 'linear-resize' && descriptor.cursor) return descriptor.cursor
+  return descriptor.axis === 'y' ? 'ns-resize' : 'ew-resize'
+}
+function resolveBound(
+  bound:
+    | number
+    | ((node: AnyNode, sceneApi: ReturnType<typeof createSceneApi>) => number)
+    | undefined,
+  fallback: number,
+  node: AnyNode,
+  sceneApi: ReturnType<typeof createSceneApi>,
+): number {
+  if (bound === undefined) return fallback
+  return typeof bound === 'function' ? bound(node, sceneApi) : bound
+}
+function LinearArrow({
+  descriptor,
+  node,
+  liveNode,
+  freezeOffset,
+  handleIndex,
+  dragControls,
+  rideObject,
+}: {
+  descriptor: LinearResizeHandle<AnyNode> | RadialResizeHandle<AnyNode>
+  /** Effective node for placement (preDrag snapshot when another arrow is active). */
+  node: AnyNode
+  /** Always the live (override-merged) node — used inside drag handlers. */
+  liveNode: AnyNode
+  /** Node-local offset that undoes the mesh's `position` drift; null when not frozen. */
+  freezeOffset: [number, number, number] | null
+  handleIndex: number
+  dragControls: HandleDragControls
+  rideObject: Object3D
+}) {
+  const [isHovered, setIsHovered] = useState(false)
+  const [isDragging, setIsDragging] = useState(false)
+  const { camera } = useThree()
+  const zoom = camera instanceof OrthographicCamera ? 1 / camera.zoom : 1
+  const baseScale = zoom * ARROW_SCALE
+  const unit = useViewer((s) => s.unit)
+  // Suppress "declared but unused" for `liveNode` — LinearArrow's apply
+  // operates on `initialNode` (snapshot inside activate) and reads value
+  // updates back via `useLiveNodeOverrides`. The prop is required for
+  // uniformity with ArrowHandle's variant dispatch but isn't consumed in
+  // this variant's render path.
+  void liveNode
+  const cursor = pickCursor(descriptor)
+  // When a handle declares `measureLabel`, its readout is routed to the
+  // 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
+  const placementSceneApi = useMemo(() => createSceneApi(useScene), [])
+  const basePosition = descriptor.placement.position(node, placementSceneApi)
+  // `freezeOffset` (in node-local frame) cancels the mesh's `position`
+  // drift while another arrow is being dragged — `basePosition` is
+  // computed against the pre-drag snapshot, then we subtract the offset
+  // so the arrow's WORLD location matches its pre-drag world location.
+  // Active arrows + idle state have `freezeOffset === null`, so the
+  // position passes through unchanged.
+  const position: [number, number, number] = freezeOffset
+    ? [
+        basePosition[0] - freezeOffset[0],
+        basePosition[1] - freezeOffset[1],
+        basePosition[2] - freezeOffset[2],
+      ]
+    : [basePosition[0], basePosition[1], basePosition[2]]
+  const baseRotationY = descriptor.placement.rotationY?.(node, placementSceneApi) ?? 0
+  // Default chevron points +X. Rotate around Y to face the chosen axis.
+  const axisRotationY = descriptor.axis === 'z' ? -Math.PI / 2 : 0
+  // For axis === 'y' we orient the chevron up. Z-rotation by π/2 then
+  // Y-rotation chains via the parent <group> below.
+  const rotationY = baseRotationY + axisRotationY
+  const activate = useHandleDrag({
+    kind: 'drag',
+    cursor,
+    dragControls,
+    handleIndex,
+    node,
+    rideObject,
+    setIsDragging,
+    onStart: ({
+      camera: dragCamera,
+      event,
+      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)
+      const hitWorld = new Vector3()
+      if (!intersectPlane(event.nativeEvent.clientX, event.nativeEvent.clientY, plane, hitWorld)) {
+        return null
+      }
+      const hitLocal = hitWorld.clone().applyMatrix4(initialFrameInverse)
+      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
+          : descriptor.anchor === 'center'
+            ? 2
+            : descriptor.anchor === 'min'
+              ? 1
+              : -1
+      return {
+        overrideId,
+        onBegin: () => {
+          if (measureLabel) {
+            useEditor.getState().setActiveHandleDrag({ nodeId, label: measureLabel })
+          }
+        },
+        onEnd: () => {
+          if (measureLabel) {
+            useEditor.getState().setActiveHandleDrag(null)
+          }
+        },
+        move: ({ event: moveEvent, intersectPlane: intersectMovePlane }) => {
+          const intersection = new Vector3()
+          if (!intersectMovePlane(moveEvent.clientX, moveEvent.clientY, plane, intersection)) {
+            return null
+          }
+          const intersectionLocal = intersection.clone().applyMatrix4(initialFrameInverse)
+          const currentPointer =
+            descriptor.axis === 'x'
+              ? intersectionLocal.x
+              : descriptor.axis === 'y'
+                ? intersectionLocal.y
+                : intersectionLocal.z
+          const delta = currentPointer - initialPointer
+          const rawNext = initialValue + delta * factor
+          const snappedNext =
+            gridSnapStep && gridSnapStep > 0 ? snapScalar(rawNext, gridSnapStep) : rawNext
+          const next = Math.min(maxBound, Math.max(minBound, snappedNext))
+          return descriptor.apply(initialNode as never, next, sceneApi) as Partial<AnyNode>
+        },
+      }
+    },
+  })
+  // For axis === 'y' (vertical handles), tilt the chevron up via local
+  // 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).
+  const innerRotation: [number, number, number] =
+    descriptor.axis === 'y'
+      ? [0, Math.PI / 2, position[1] < 0 ? -Math.PI / 2 : Math.PI / 2]
+      : [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
+  // round footprint ring.
+  const decoration = descriptor.decoration
+  const showDecoration = Boolean(decoration) && (isHovered || isDragging)
+  // Dimension chip — shows the live value the drag is steering. `node`
+  // is already the effective (override-merged) node, so currentValue
+  // returns the in-flight value during a drag and the label tracks
+  // smoothly without an extra subscription.
+  // `measureLabel` handles route their readout to the floating dimension
+  // pill, so suppress the inline chip here to avoid showing it twice.
+  const showLabel = (isHovered || isDragging) && !measureLabel
+  const labelText = showLabel ? formatDimension(descriptor.currentValue(node), unit) : ''
+  // `tracker` shape on a linear-resize handle: render a dashed vertical
+  // leader from the floor up to a small cube at `placement.position`. The
+  // cube is the drag target and reuses the same `activate` pointer handler
+  // as the chevron path, so all the override/commit plumbing is unchanged.
+  // Only valid for axis='y' resize handles — the leader is rendered at
+  // (0,0,0)→(0,position.y,0) in the same group as the cube, so for x/z
+  // axes the leader would still climb vertically and look wrong.
+  const shape =
+    descriptor.kind === 'linear-resize' && descriptor.shape === 'tracker' ? 'tracker' : 'arrow'
+  if (shape === 'tracker') {
+    // Descriptors can pin the leader's bottom Y above the floor — e.g.
+    // chimney body height starts at the deck plane, not at y=0, so the
+    // dashed leader spans only the body's visible extent.
+    const trackerDescriptor = descriptor as LinearResizeHandle<AnyNode>
+    const baseY = trackerDescriptor.trackerBaseY?.(node as never, placementSceneApi) ?? 0
+    // Leader spans base ↔ cube either direction. Upward (cube above base:
+    // wall / chimney height) it stops at the cube as before. Downward
+    // (cube below base: a downspout's length cube under the gutter
+    // outlet) it pokes `TRACKER_THROUGH` past the cube so the dashes
+    // thread through it instead of the leader collapsing to nothing.
+    const cubeY = position[1]
+    const cubeBelowBase = cubeY < baseY
+    const leaderBottomY = Math.min(baseY, cubeY) - (cubeBelowBase ? TRACKER_THROUGH : 0)
+    const leaderHeight = Math.max(Math.max(baseY, cubeY) - leaderBottomY, 0)
+    return (
+      <>
+        {showDecoration && decoration ? (
+          <GuideRing
+            radius={decoration.radius(node as never)}
+            y={decoration.y?.(node as never) ?? 0}
+          />
+        ) : null}
+        {showLabel ? (
+          <DimensionLabel
+            position={[position[0], position[1] + 0.22, position[2]]}
+            text={labelText}
+          />
+        ) : null}
+        <TrackerShape
+          basePosition={[position[0], leaderBottomY, position[2]]}
+          baseScale={zoom}
+          cubePosition={position}
+          cursor={cursor}
+          hover={isHovered}
+          leaderHeight={leaderHeight}
+          onHoverChange={setIsHovered}
+          onPointerDown={activate}
+        />
+      </>
+    )
+  }
+  return (
+    <>
+      {showDecoration && decoration ? (
+        <GuideRing
+          radius={decoration.radius(node as never)}
+          y={decoration.y?.(node as never) ?? 0}
+        />
+      ) : null}
+      <HandleArrow
+        cursor={cursor}
+        hover={isHovered}
+        indicatorRotation={innerRotation}
+        onHoverChange={setIsHovered}
+        onPointerDown={activate}
+        placement={{ position, rotation: [0, rotationY, 0], baseScale }}
+        shape="chevron"
+      >
+        {showLabel ? <DimensionLabel position={[0, 0.22, 0]} text={labelText} /> : null}
+      </HandleArrow>
+    </>
+  )
+}
+// Thin horizontal ring used as a visual guide alongside a resize arrow —
+// 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 }) {
+  const safeRadius = Math.max(radius, 0.01)
+  const ringGeometry = useMemo(() => {
+    const inner = Math.max(safeRadius - 0.015, 0.001)
+    const outer = safeRadius + 0.015
+    return new RingGeometry(inner, outer, 96)
+  }, [safeRadius])
+  const ringMaterial = useMemo(
+    () =>
+      new MeshBasicNodeMaterial({
+        color: new Color(ARROW_COLOR),
+        side: DoubleSide,
+        transparent: true,
+        opacity: 0.95,
+        depthTest: false,
+        depthWrite: false,
+      }),
+    [],
+  )
+  useEffect(() => () => ringGeometry.dispose(), [ringGeometry])
+  useEffect(() => () => ringMaterial.dispose(), [ringMaterial])
+  return (
+    <mesh
+      frustumCulled={false}
+      geometry={ringGeometry}
+      material={ringMaterial}
+      position={[0, y, 0]}
+      renderOrder={1009}
+      rotation={[-Math.PI / 2, 0, 0]}
+    />
+  )
+}
+const ROTATION_GUIDE_COLOR = ARROW_COLOR
+const ROTATION_GUIDE_SEGMENTS = 48
+// Live rotation readout shown while a whole-node rotate gizmo is dragged.
+// Mirrors the wall-draft angle arc: a filled wedge + outline swept from the
+// pointer's bearing at grab (`startAngle`) to its current bearing
+// (`endAngle`) around the rotation pivot, plus a degree chip at the wedge's
+// midpoint. All coordinates are world-space — the guide is portalled to the
+// scene root so it stays fixed while the node mesh rotates underneath it.
+export type RotationGuideData = {
+  center: [number, number, number]
+  startAngle: number
+  endAngle: number
+  radius: number
+  labelPos: [number, number, number]
+  /** Swept magnitude in radians, for the degree chip. */
+  sweep: number
+}
+export function RotationGuide({ data }: { data: RotationGuideData }) {
+  const { center, startAngle, endAngle, radius, labelPos, sweep } = data
+  const { outline, fill } = useMemo(() => {
+    const span = endAngle - startAngle
+    const count = Math.max(8, Math.ceil((Math.abs(span) / Math.PI) * ROTATION_GUIDE_SEGMENTS))
+    const arc = Array.from({ length: count + 1 }, (_, index) => {
+      const angle = startAngle + (span * index) / count
+      return new Vector3(
+        center[0] + Math.cos(angle) * radius,
+        center[1],
+        center[2] + Math.sin(angle) * radius,
+      )
+    })
+    const centerV = new Vector3(center[0], center[1], center[2])
+    const outlineGeo = new BufferGeometry().setFromPoints([centerV, ...arc, centerV])
+    const positions: number[] = []
+    for (let i = 0; i < arc.length - 1; i++) {
+      const a = arc[i]
+      const b = arc[i + 1]
+      if (!a || !b) continue
+      positions.push(centerV.x, centerV.y, centerV.z, a.x, a.y, a.z, b.x, b.y, b.z)
+    }
+    const fillGeo = new BufferGeometry()
+    fillGeo.setAttribute('position', new Float32BufferAttribute(positions, 3))
+    return { outline: outlineGeo, fill: fillGeo }
+  }, [center, startAngle, endAngle, radius])
+  useEffect(() => () => outline.dispose(), [outline])
+  useEffect(() => () => fill.dispose(), [fill])
+  return (
+    <>
+      <mesh
+        frustumCulled={false}
+        geometry={fill}
+        layers={EDITOR_LAYER}
+        raycast={NO_RAYCAST}
+        renderOrder={1008}
+      >
+        <meshBasicMaterial
+          color={ROTATION_GUIDE_COLOR}
+          depthTest={false}
+          depthWrite={false}
+          opacity={0.18}
+          side={DoubleSide}
+          transparent
+        />
+      </mesh>
+      <RotationGuideOutline geometry={outline} />
+      <DimensionLabel position={labelPos} text={formatAngleRadians(sweep)} />
+    </>
+  )
+}
+function RotationGuideOutline({ geometry }: { geometry: BufferGeometry }) {
+  return (
+    // @ts-expect-error - R3F accepts Three line primitives, matching the wall draft arc.
+    <line frustumCulled={false} geometry={geometry} layers={EDITOR_LAYER} renderOrder={1009}>
+      <lineBasicNodeMaterial
+        color={ROTATION_GUIDE_COLOR}
+        depthTest={false}
+        depthWrite={false}
+        linewidth={2}
+        opacity={0.95}
+        transparent
+      />
+    </line>
+  )
+}
+// Live whole-node rotation readout for a single-node rotate gizmo, rendered as
+// a CHILD of the node frame (sibling of its guide ring). Because it lives in
+// the node's own frame, it is automatically concentric and coplanar with the
+// ring — on flat ground the frame's XZ is world-horizontal, on a pitched roof
+// it follows the slope, with no world-space basis math.
+//
+// The wedge fills the node-local XZ plane at the ring's height `y`. Its leading
+// edge sits at the rotate handle's bearing `handleAngle` (which is fixed in the
+// node frame, so it tracks the orbiting handle), and it opens BACKWARD by the
+// swept `delta` — so the trailing edge stays pinned to the grab direction in
+// world while the node spins. `orbitRadius` is the handle's in-plane distance
+// from the pivot; the fill is pulled inside it so it reads as the handle
+// swinging around rather than overlapping the icon.
+function RotationWedge({
+  delta,
+  handleAngle,
+  orbitRadius,
+  y,
+}: {
+  delta: number
+  handleAngle: number
+  orbitRadius: number
+  y: number
+}) {
+  const radius = Math.min(Math.max(orbitRadius * 0.72, 0.3), 1.6)
+  const { outline, fill } = useMemo(() => {
+    const start = handleAngle - delta
+    const span = delta
+    const count = Math.max(8, Math.ceil((Math.abs(span) / Math.PI) * ROTATION_GUIDE_SEGMENTS))
+    const arc = Array.from({ length: count + 1 }, (_, index) => {
+      const angle = start + (span * index) / count
+      return new Vector3(Math.cos(angle) * radius, 0, Math.sin(angle) * radius)
+    })
+    const centerV = new Vector3(0, 0, 0)
+    const outlineGeo = new BufferGeometry().setFromPoints([centerV, ...arc, centerV])
+    const positions: number[] = []
+    for (let i = 0; i < arc.length - 1; i++) {
+      const a = arc[i]
+      const b = arc[i + 1]
+      if (!a || !b) continue
+      positions.push(0, 0, 0, a.x, a.y, a.z, b.x, b.y, b.z)
+    }
+    const fillGeo = new BufferGeometry()
+    fillGeo.setAttribute('position', new Float32BufferAttribute(positions, 3))
+    return { outline: outlineGeo, fill: fillGeo }
+  }, [delta, handleAngle, radius])
+  useEffect(() => () => outline.dispose(), [outline])
+  useEffect(() => () => fill.dispose(), [fill])
+  const labelRadius = radius + 0.22
+  const midAngle = handleAngle - delta / 2
+  const labelPos: [number, number, number] = [
+    Math.cos(midAngle) * labelRadius,
+    0,
+    Math.sin(midAngle) * labelRadius,
+  ]
+  return (
+    <group position={[0, y, 0]}>
+      <mesh
+        frustumCulled={false}
+        geometry={fill}
+        layers={EDITOR_LAYER}
+        raycast={NO_RAYCAST}
+        renderOrder={1008}
+      >
+        <meshBasicMaterial
+          color={ROTATION_GUIDE_COLOR}
+          depthTest={false}
+          depthWrite={false}
+          opacity={0.18}
+          side={DoubleSide}
+          transparent
+        />
+      </mesh>
+      <RotationGuideOutline geometry={outline} />
+      <DimensionLabel position={labelPos} text={formatAngleRadians(Math.abs(delta))} />
+    </group>
+  )
+}
+// Angular drag: project pointer to a horizontal plane at the arrow's Y
+// and measure the signed angle around the node's local origin (in world
+// XZ). Pass the normalised delta to `apply` — the descriptor owns the
+// per-field math (sweep handles write `sweepAngle` AND `rotation` from
+// the same delta to keep the opposite edge world-fixed).
+function ArcArrow({
+  descriptor,
+  node,
+  liveNode,
+  freezeOffset,
+  handleIndex,
+  dragControls,
+  rideObject,
+}: {
+  descriptor: ArcResizeHandle<AnyNode>
+  /** Effective node for placement (preDrag snapshot when another arrow is active). */
+  node: AnyNode
+  /** Always the live (override-merged) node — used inside drag handlers. */
+  liveNode: AnyNode
+  /** Node-local offset that undoes the mesh's `position` drift; null when not frozen. */
+  freezeOffset: [number, number, number] | null
+  handleIndex: number
+  dragControls: HandleDragControls
+  rideObject: Object3D
+}) {
+  const [isHovered, setIsHovered] = useState(false)
+  const [isDragging, setIsDragging] = useState(false)
+  // 'rotate' descriptors (whole-node rotation handles like the elevator
+  // corner) render a two-headed curved arrow; everything else (stair
+  // sweep, etc.) keeps the chevron.
+  const isRotateShape = descriptor.shape === 'rotate'
+  // '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
+  // suppressed.
+  const isNodeNormalRot = descriptor.rotationPlane === 'node-normal'
+  const { camera } = useThree()
+  const zoom = camera instanceof OrthographicCamera ? 1 / camera.zoom : 1
+  // The rotate icon is denser than the chevron; pump scale a touch so the
+  // ribbon reads at the same on-screen size as the other handles.
+  const arrowScale = isRotateShape ? ARROW_SCALE * 1.05 : ARROW_SCALE
+  const baseScale = zoom * arrowScale
+  // Live rotation amount (radians swept since grab) — non-null only while a
+  // `shape: 'rotate'` gizmo is mid-drag. Drives the in-frame wedge readout.
+  const [rotationDelta, setRotationDelta] = useState<number | null>(null)
+  const placementSceneApi = useMemo(() => createSceneApi(useScene), [])
+  const basePosition = descriptor.placement.position(node, placementSceneApi)
+  // See the LinearArrow note on freezeOffset — for rotation drags the
+  // delta collapses to zero (position doesn't change), so the rotate
+  // gizmo naturally rotates with the mesh while another arrow is being
+  // dragged. The offset only kicks in for asymmetric resize drags that
+  // recompute `position` to anchor the opposite edge.
+  const position: [number, number, number] = freezeOffset
+    ? [
+        basePosition[0] - freezeOffset[0],
+        basePosition[1] - freezeOffset[1],
+        basePosition[2] - freezeOffset[2],
+      ]
+    : [basePosition[0], basePosition[1], basePosition[2]]
+  const rotationY = descriptor.placement.rotationY?.(node, placementSceneApi) ?? 0
+  // Rotation gizmo: hover signals "grabbable", active drag signals
+  // "grabbed". `ew-resize` was wrong — it implies linear width drag.
+  const hoverCursor: Cursor = 'grab'
+  const dragCursor: Cursor = 'grabbing'
+  // Optional guide ring (elevator rotation circle) shown while the arc
+  // arrow is hovered or dragging. Same recipe as the linear / radial
+  // decoration path.
+  const decoration = descriptor.decoration
+  const showDecoration = Boolean(decoration) && (isHovered || isDragging)
+  const activate = useHandleDrag({
+    kind: 'drag',
+    cursor: dragCursor,
+    dragControls,
+    handleIndex,
+    node,
+    rideObject,
+    setIsDragging,
+    onStart: ({ event, initialNode, intersectPlane, rideObject: dragRideObject, sceneApi }) => {
+      const centerWorld =
+        descriptor.rotationCenter !== undefined
+          ? new Vector3(...descriptor.rotationCenter(node as never, sceneApi)).applyMatrix4(
+              dragRideObject.matrixWorld,
+            )
+          : new Vector3().setFromMatrixPosition(dragRideObject.matrixWorld)
+      const arrowWorld = new Vector3(...position).applyMatrix4(dragRideObject.matrixWorld)
+      const planeY = arrowWorld.y
+      const axis = isNodeNormalRot
+        ? new Vector3().setFromMatrixColumn(dragRideObject.matrixWorld, 2).normalize()
+        : new Vector3(0, 1, 0)
+      const plane = isNodeNormalRot
+        ? new Plane().setFromNormalAndCoplanarPoint(axis, centerWorld)
+        : new Plane(new Vector3(0, 1, 0), -planeY)
+      let basisU: Vector3
+      if (isNodeNormalRot) {
+        const up = new Vector3(0, 1, 0)
+        basisU = up.clone().addScaledVector(axis, -up.dot(axis))
+        if (basisU.lengthSq() < 1e-6) {
+          const x = new Vector3(1, 0, 0)
+          basisU = x.addScaledVector(axis, -x.dot(axis))
+        }
+        basisU.normalize()
+      } else {
+        basisU = new Vector3(1, 0, 0)
+      }
+      const basisV = isNodeNormalRot
+        ? new Vector3().crossVectors(axis, basisU).normalize()
+        : new Vector3(0, 0, 1)
+      const angleOf = (p: Vector3) => {
+        const d = new Vector3().subVectors(p, centerWorld)
+        return Math.atan2(d.dot(basisV), d.dot(basisU))
+      }
+      const hitWorld = new Vector3()
+      if (!intersectPlane(event.nativeEvent.clientX, event.nativeEvent.clientY, plane, hitWorld)) {
+        return null
+      }
+      const initialAngle = angleOf(hitWorld)
+      return {
+        onEnd: () => setRotationDelta(null),
+        move: ({ event: moveEvent, intersectPlane: intersectMovePlane }) => {
+          const hit = new Vector3()
+          if (!intersectMovePlane(moveEvent.clientX, moveEvent.clientY, plane, hit)) return null
+          const currentAngle = angleOf(hit)
+          let delta = currentAngle - initialAngle
+          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 (isRotateShape && !isNodeNormalRot) {
+            setRotationDelta(Math.abs(delta) < 0.0087 ? null : delta)
+          }
+          return descriptor.apply(initialNode as never, delta, sceneApi) as Partial<AnyNode>
+        },
+      }
+    },
+  })
+  // 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)}
+          y={decoration.y?.(node as never) ?? 0}
+        />
+      ) : null}
+      {/* Live rotation readout. Rendered HERE (a child of the node frame, the
+          same frame the guide ring lives in) rather than portalled to world
+          space, so the wedge is automatically concentric and coplanar with the
+          ring on any surface — flat ground or a pitched roof. */}
+      {rotationDelta !== null ? (
+        <RotationWedge
+          delta={rotationDelta}
+          handleAngle={Math.atan2(position[2], position[0])}
+          orbitRadius={Math.hypot(position[0], position[2])}
+          y={decoration?.y?.(node as never) ?? 0}
+        />
+      ) : null}
+      <HandleArrow
+        activeCursor={dragCursor}
+        cursor={hoverCursor}
+        hover={isHovered}
+        onHoverChange={setIsHovered}
+        onPointerDown={activate}
+        placement={{
+          position,
+          // The curved arrow is built flat in XZ. For a wall-normal spin, tilt
+          // it up about X so it lies in the item-local XY plane (the wall face).
+          rotation: isNodeNormalRot ? [Math.PI / 2, 0, rotationY] : [0, rotationY, 0],
+          baseScale,
+        }}
+        shape={isRotateShape ? 'curved-arrow' : 'chevron'}
+      />
+    </>
+  )
+}
+// 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
+// importing editor internals from the node-def layer.
+function TapActionArrow({
+  descriptor,
+  node,
+}: {
+  descriptor: TapActionHandle<AnyNode>
+  node: AnyNode
+}) {
+  const [isHovered, setIsHovered] = useState(false)
+  const { camera } = useThree()
+  const zoom = camera instanceof OrthographicCamera ? 1 / camera.zoom : 1
+  const placementSceneApi = useMemo(() => createSceneApi(useScene), [])
+  const position = descriptor.placement.position(node, placementSceneApi)
+  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 onActivate = useHandleDrag({
+    kind: 'tap',
+    onTap: () => {
+      setIsHovered(false)
+      descriptor.onActivate(node as never, createSceneApi(useScene), createEditorApi())
+    },
+  })
+  if (shape === 'corner-picker') {
+    const height = descriptor.nodeHeight?.(node) ?? 1
+    return (
+      <CornerPickerShape
+        baseScale={zoom}
+        cursor={cursor}
+        height={height}
+        hover={isHovered}
+        onHoverChange={setIsHovered}
+        onPointerDown={onActivate}
+        position={position}
+      />
+    )
+  }
+  // Default 'arrow' shape — the standard chevron.
+  const baseScale = zoom * ARROW_SCALE
+  return (
+    <HandleArrow
+      cursor={cursor}
+      hover={isHovered}
+      onHoverChange={setIsHovered}
+      onPointerDown={onActivate}
+      placement={{ position, rotation: [0, rotationY, 0], baseScale }}
+      shape="chevron"
+    />
+  )
+}
+// Wall corner-picker visual: dashed vertical leader from floor up to
+// `height` + billboarded hex disc (the click target) + outer ring. The
+// hex disc is the only mesh with a pointer-down handler; the dashes and
+// ring are decorative.
+const CORNER_DASH_SIZE = 0.1
+const CORNER_GAP_SIZE = 0.07
+const CORNER_DASH_THICKNESS = 0.006
+const CORNER_FLOOR_OFFSET = 0.01
+function buildDashedVerticalGeometry(height: number) {
+  const dashes: BufferGeometry[] = []
+  let y = 0
+  while (y < height) {
+    const end = Math.min(y + CORNER_DASH_SIZE, height)
+    const length = end - y
+    const cylinder = new CylinderGeometry(CORNER_DASH_THICKNESS, CORNER_DASH_THICKNESS, length, 8)
+    cylinder.translate(0, y + length / 2, 0)
+    dashes.push(cylinder)
+    y = end + CORNER_GAP_SIZE
+  }
+  const merged = mergeGeometries(dashes, false) ?? dashes[0]
+  for (const dash of dashes) dash.dispose()
+  return merged
+}
+function CornerPickerShape({
+  position,
+  height,
+  baseScale,
+  cursor,
+  hover,
+  onHoverChange,
+  onPointerDown,
+}: {
+  position: readonly [number, number, number]
+  height: number
+  baseScale: number
+  cursor: Cursor
+  hover: boolean
+  onHoverChange: (hovered: boolean) => void
+  onPointerDown: (event: ThreeEvent<PointerEvent>) => void
+}) {
+  const dashedGeometry = useMemo(() => buildDashedVerticalGeometry(height), [height])
+  useEffect(() => () => dashedGeometry.dispose(), [dashedGeometry])
+  const dashMaterial = useMemo(
+    () =>
+      new MeshBasicNodeMaterial({
+        color: new Color(ARROW_COLOR),
+        transparent: true,
+        opacity: 0.85,
+        depthTest: false,
+        depthWrite: false,
+      }),
+    [],
+  )
+  const ringMaterial = useMemo(
+    () =>
+      new MeshBasicNodeMaterial({
+        color: new Color(ARROW_COLOR),
+        side: DoubleSide,
+        transparent: true,
+        opacity: 1,
+        depthTest: false,
+        depthWrite: false,
+      }),
+    [],
+  )
+  useEffect(() => {
+    const next = hover ? ARROW_HOVER_COLOR : ARROW_COLOR
+    dashMaterial.color.set(next)
+    ringMaterial.color.set(next)
+  }, [dashMaterial, ringMaterial, hover])
+  useEffect(() => () => dashMaterial.dispose(), [dashMaterial])
+  useEffect(() => () => ringMaterial.dispose(), [ringMaterial])
+  const billboardRef = useRef<Group>(null)
+  const { camera } = useThree()
+  // Billboard the disc to the camera so the picker remains readable at any
+  // viewing angle. The disc lives under the building-rotated tool group
+  // (and possibly a rotated level), so copying `camera.quaternion` onto
+  // the local quaternion no longer yields camera-aligned WORLD rotation
+  // when the parent has a rotation of its own — compute the local
+  // quaternion that, composed with the parent's world rotation, equals
+  // the camera's world rotation.
+  const parentWorldQuat = useMemo(() => new Quaternion(), [])
+  const invParentWorldQuat = useMemo(() => new Quaternion(), [])
+  useFrame(() => {
+    const group = billboardRef.current
+    if (!group) return
+    if (group.parent) {
+      group.parent.getWorldQuaternion(parentWorldQuat)
+      invParentWorldQuat.copy(parentWorldQuat).invert()
+      group.quaternion.copy(invParentWorldQuat).multiply(camera.quaternion)
+    } else {
+      group.quaternion.copy(camera.quaternion)
+    }
+  })
+  const scale = (hover ? 1.25 : 1) * baseScale
+  return (
+    <>
+      <mesh
+        frustumCulled={false}
+        geometry={dashedGeometry}
+        material={dashMaterial}
+        position={position}
+        renderOrder={1001}
+      />
+      <group position={[position[0], CORNER_FLOOR_OFFSET, position[2]]} ref={billboardRef}>
+        <HandleArrow
+          cursor={cursor}
+          hover={hover}
+          hoverScale={1.25}
+          onHoverChange={onHoverChange}
+          onPointerDown={onPointerDown}
+          placement={{ position: [0, 0, 0], baseScale }}
+          shape="corner-picker"
+        />
+        <mesh material={ringMaterial} renderOrder={1002} scale={scale}>
+          <ringGeometry args={[CORNER_HEX_RADIUS, CORNER_HEX_RADIUS * 1.18, 6]} />
+        </mesh>
+      </group>
+    </>
+  )
+}
+// Tracker visual for the `linear-resize` handle's `shape: 'tracker'` option.
+// Mirrors the corner picker (dashed vertical leader from the floor) but caps
+// the leader with a small draggable cube instead of a hex disc, and the cube
+// sits at the TOP of the leader rather than the floor — the visual reads as
+// "this cube is the wall top; drag it to raise/lower." All interactivity
+// (pointer-down → linear-resize drag) is wired by the parent `LinearArrow`.
+function TrackerShape({
+  basePosition,
+  baseScale,
+  cubePosition,
+  cursor,
+  hover,
+  leaderHeight,
+  onHoverChange,
+  onPointerDown,
+}: {
+  basePosition: readonly [number, number, number]
+  baseScale: number
+  cubePosition: readonly [number, number, number]
+  cursor: Cursor
+  hover: boolean
+  leaderHeight: number
+  onHoverChange: (hovered: boolean) => void
+  onPointerDown: (event: ThreeEvent<PointerEvent>) => void
+}) {
+  // `leaderHeight === 0` (wallHeight collapsed to floor) would make the
+  // dashed builder return an empty geometry — skip the mesh entirely in
+  // that case so the cube still renders by itself.
+  const hasLeader = leaderHeight > 0.0001
+  const dashedGeometry = useMemo(
+    () => (hasLeader ? buildDashedVerticalGeometry(leaderHeight) : null),
+    [hasLeader, leaderHeight],
+  )
+  useEffect(() => () => dashedGeometry?.dispose(), [dashedGeometry])
+  const dashMaterial = useMemo(
+    () =>
+      new MeshBasicNodeMaterial({
+        color: new Color(ARROW_COLOR),
+        transparent: true,
+        opacity: 0.85,
+        depthTest: false,
+        depthWrite: false,
+      }),
+    [],
+  )
+  useEffect(() => {
+    const next = hover ? ARROW_HOVER_COLOR : ARROW_COLOR
+    dashMaterial.color.set(next)
+  }, [dashMaterial, hover])
+  useEffect(() => () => dashMaterial.dispose(), [dashMaterial])
+  return (
+    <>
+      {dashedGeometry ? (
+        <mesh
+          frustumCulled={false}
+          geometry={dashedGeometry}
+          material={dashMaterial}
+          position={basePosition}
+          renderOrder={1001}
+        />
+      ) : null}
+      <HandleArrow
+        cursor={cursor}
+        hover={hover}
+        hoverScale={1.25}
+        onHoverChange={onHoverChange}
+        onPointerDown={onPointerDown}
+        placement={{ position: cubePosition, baseScale }}
+        shape="tracker"
+      />
+    </>
+  )
+}