@pascal-app/editor 0.9.1 → 0.9.2

package/src/index.tsx

@@ -11,8 +11,57 @@ export { default as Editor } from './components/editor'
 // they're referenced throughout the editor's own internals; the public
 // surface uses the shorter, shell-friendly names from the unified
 // preset-system spec.
+export { BakeExporter } from './components/editor/bake-exporter'
 export { FloatingActionMenu as FloatingMenu } from './components/editor/floating-action-menu'
-export { formatMeasurement, MeasurementPill } from './components/editor/measurement-pill'
+// Embed surface — the editor's real in-canvas affordances, so a host can mount
+// authentic selection handles, interactive build tools, and the mover on top
+// of a bare `<Viewer>` without the full `<Editor>` shell.
+//  - `NodeArrowHandles` renders the selected node's registry resize/rotate/move
+//    handles.
+//  - `MoveTool` runs the kind-owned mover once a translate handle arms
+//    `useEditor.movingNode`.
+//  - `ToolManager` mounts the active registry build tool (wall / door / window /
+//    …) for interactive placement when `useEditor` is in build mode with a
+//    tool, plus the snap/alignment guide layers. Mount it only while a tool is
+//    active to avoid its select-mode boundary editors.
+//  - `Grid` is the interactive drafting plane: it raycasts the pointer and
+//    emits the `grid:move` / `grid:click` events the build tools consume (the
+//    wall tool is driven entirely by them; door/window use them for free-follow
+//    alongside the viewer's `wall:*` mesh events). Without it the tools mount
+//    but their cursor never tracks the pointer. Mount it while a tool is active.
+// All read `useViewer` selection + `useEditor` state, and cooperate with host
+// camera controls via the `useViewer.inputDragging` / `useEditor.movingNode`
+// flags. Tools place onto `useViewer.selection.levelId`, so the host must set a
+// building + level selection first.
+export { Grid } from './components/editor/grid'
+export {
+  DimensionPill,
+  type DimensionPillPart,
+  formatMeasurement,
+  MeasurementPill,
+} from './components/editor/measurement-pill'
+// In-world arrow handle primitives (chevron geometry, invisible hit area,
+// shared material, palette + scale constants). Re-exported so kind-owned
+// 3D selection affordances in `@pascal-app/nodes` (duct side-move / height /
+// extend arrows) reuse the same UI family as the wall / fence side handles.
+export {
+  ARROW_COLOR,
+  ARROW_HOVER_COLOR,
+  ARROW_SCALE,
+  createArrowHandleGeometry,
+  createArrowHitAreaGeometry,
+  HandleArrow,
+  type HandleArrowInputShape,
+  type HandleArrowPlacement,
+  type HandleArrowProps,
+  InvisibleHandleHitArea,
+  NO_RAYCAST,
+  NodeArrowHandles,
+  swallowNextClick,
+  useArrowMaterial,
+  useInvisibleHitAreaMaterial,
+} from './components/editor/node-arrow-handles'
+export { QuickMeasurementCard } from './components/editor/quick-measurement-card'
 export {
   type SnapshotCameraData,
   ThumbnailGenerator,
@@ -32,9 +81,11 @@ export {
 // shared/segment-angle.ts) once every Stage D port is in.
 export {
   createFenceOnCurrentLevel,
+  createSplineFenceOnCurrentLevel,
   type FencePlanPoint,
   snapFenceDraftPoint,
 } from './components/tools/fence/fence-drafting'
+export { MoveTool } from './components/tools/item/move-tool'
 // Placement-math helpers — shared by kind-owned placement tools in
 // `@pascal-app/nodes` (wall curve sagitta snap, door / window placement,
 // item drop) so kinds don't reach into editor internals.
@@ -62,9 +113,11 @@ export { CursorSphere } from './components/tools/shared/cursor-sphere'
 export { DragBoundingBox } from './components/tools/shared/drag-bounding-box'
 export { getFloorStackPreviewPosition } from './components/tools/shared/floor-stack-preview'
 export { useFreshPlacementVisibility } from './components/tools/shared/fresh-placement-visibility'
+export { PlacementBox } from './components/tools/shared/placement-box'
 // Phase 5 Stage D — PolygonEditor for slab/ceiling boundary + hole editors.
 export {
   PolygonEditor,
+  type PolygonEditorPlanPointSnapContext,
   type PolygonEditorProps,
 } from './components/tools/shared/polygon-editor'
 export {
@@ -95,19 +148,24 @@ export {
   DEFAULT_STAIR_TYPE,
   DEFAULT_STAIR_WIDTH,
 } from './components/tools/stair/stair-defaults'
+export { ToolManager } from './components/tools/tool-manager'
 export {
+  chainEndJoinsExistingWall,
   createWallOnCurrentLevel,
   getSegmentGridStep,
   isSegmentLongEnough,
+  resolveEndpointWallSplit,
   snapPointToGrid,
   snapScalarToGrid,
   snapWallDraftPoint,
   snapWallDraftPointDetailed,
-  WALL_FINE_GRID_STEP,
+  WALL_CONNECT_SNAP_RADIUS,
   WALL_GRID_STEP,
+  WALL_JOIN_SNAP_RADIUS,
   type WallDraftSnapKind,
   type WallDraftSnapResult,
   type WallPlanPoint,
+  type WallSnapRadii,
 } from './components/tools/wall/wall-drafting'
 // `ToolbarLeft` / `ToolbarRight` are the headless-spec aliases for the
 // existing `ViewerToolbarLeft` / `ViewerToolbarRight` exports — the
@@ -164,6 +222,13 @@ export {
 } from './components/ui/sidebar/panels/settings-panel'
 export type { SitePanelProps } from './components/ui/sidebar/panels/site-panel'
 export type { SidebarTab } from './components/ui/sidebar/tab-bar'
+export {
+  resolveAssetSnapTarget,
+  resolveNodeSnapTarget,
+  type SnapTarget,
+  SnapTargetBadge,
+  SnapTargetIcon,
+} from './components/ui/snap-target-badge'
 export type { SaveStatus } from './hooks/use-auto-save'
 // useDragAction is the React-side glue for the registry's DragAction
 // primitive. Public so registry-driven kinds (Phase 5+ Stage D ports)
@@ -172,8 +237,28 @@ export { type UseDragActionArgs, useDragAction } from './hooks/use-drag-action'
 // Phase 5 Stage D — extras for kind-owned placement tools (FenceTool etc.).
 export { markToolCancelConsumed } from './hooks/use-keyboard'
 export { type Selection, useSelection } from './hooks/use-selection'
+export {
+  clearPlacementSurface,
+  getPlacementSurface,
+  type PlacementSurface,
+  publishPlacementSurface,
+} from './lib/active-placement-surface'
+export {
+  CEILING_ALIGNMENT_THRESHOLD_M,
+  type CeilingPlanSnapInput,
+  type CeilingPlanSnapResult,
+  clearCeilingSnapFeedback,
+  resolveCeilingPlanPointSnap,
+} from './lib/ceiling-plan-snap'
 export { EDITOR_LAYER } from './lib/constants'
 // Helper libs used by the kind-owned roof / stair / elevator panels.
+export {
+  CONTINUATION_PROFILES,
+  type ContinuationContext,
+  type ContinuationMode,
+  continuationContextOf,
+  nextContinuation,
+} from './lib/continuation'
 export {
   resolveCurrentBuildingId,
   resolveElevatorNodeSupportY,
@@ -201,15 +286,55 @@ export {
   getFloorplanWallThickness,
 } from './lib/floorplan'
 export { commitFreshPlacementSubtree } from './lib/fresh-planar-placement'
+export { exportSceneToGlb } from './lib/glb-export'
+export {
+  boundaryReshapeScope,
+  curveReshapeScope,
+  endpointReshapeScope,
+  holeEditScope,
+  movingNodeOf,
+} from './lib/interaction/scope'
 export {
   buildResetSurfaceMaterialUpdates,
   buildRoofSurfaceMaterialPatch,
   buildSingleSurfaceMaterialPatch,
   buildStairSurfaceMaterialPatch,
-  buildWallSurfaceMaterialPatch,
   getActivePaintMaterialLabel,
   hasActivePaintMaterial,
 } from './lib/material-paint'
+export {
+  CREATABLE_MEASUREMENT_KINDS,
+  type CreatableMeasurementKind,
+  DEFAULT_CREATABLE_MEASUREMENT_KIND,
+  isCreatableMeasurementKind,
+  normalizeCreatableMeasurementKind,
+} from './lib/measurement-kind'
+export {
+  measurementPolygonLabelAnchor,
+  triangulateMeasurementPolygon,
+} from './lib/measurement-label'
+export {
+  buildMeasurementAngleArcPoints,
+  cubicMetersToVolumeUnit,
+  formatAreaLabel,
+  formatLinearMeasurement,
+  formatVolumeLabel,
+  getAreaUnitLabel,
+  getLinearUnitLabel,
+  getVolumeUnitLabel,
+  type LinearUnit,
+  linearControlValueToMeters,
+  linearUnitToMeters,
+  MEASUREMENT_ACTIVE_COLOR,
+  MEASUREMENT_DANGLING_COLOR,
+  MEASUREMENT_FLOORPLAN_COLOR,
+  MEASUREMENT_PERSISTENT_COLOR,
+  measurementFloorplanPresentationColor,
+  measurementPresentationColor,
+  metersToLinearUnit,
+  squareMetersToAreaUnit,
+} from './lib/measurements'
+export { consumePlacementDragRelease } from './lib/placement-drag-release'
 export {
   addFreshPlacementMetadata,
   getPlacementMetadataRecord,
@@ -221,10 +346,36 @@ export {
   type PlanarPoint,
   resolvePlanarCursorPosition,
 } from './lib/planar-cursor-placement'
+export {
+  type EditorHostPanel,
+  type EditorHostPanelWorkspace,
+  editorHostPanelRegistry,
+  registerEditorHostPanel,
+} from './lib/plugin-panels'
+export {
+  createQuickMeasurementPointerScheduler,
+  quickMeasurementContext,
+  resolveQuickMeasurementReport,
+} from './lib/quick-measurement'
 export { clearRoofDuplicateMetadata, duplicateRoofSubtree } from './lib/roof-duplication'
+// Roof wall-face hit resolution + overlap guard — shared by the
+// kind-owned door / window tools in `@pascal-app/nodes` and the item
+// placement coordinator's roof-wall strategy.
+export { hasRoofFaceChildOverlap, type RoofWallHit, resolveRoofWallHit } from './lib/roof-wall-hit'
 export type { SceneGraph } from './lib/scene'
 export { applySceneGraphToEditor } from './lib/scene'
+export { movementSfxStepKey } from './lib/sfx/movement-tick'
 export { triggerSFX } from './lib/sfx-bus'
+export {
+  clearSlabSnapFeedback,
+  resolveSlabEdgeBandSnap,
+  resolveSlabPlanPointSnap,
+  SLAB_ALIGNMENT_THRESHOLD_M,
+  type SlabEdgeBandSnapInput,
+  type SlabEdgeBandSnapResult,
+  type SlabPlanSnapInput,
+  type SlabPlanSnapResult,
+} from './lib/slab-plan-snap'
 export { duplicateStairSubtree } from './lib/stair-duplication'
 export {
   getBuildingLevelsForLevel,
@@ -234,13 +385,22 @@ export {
   resolveStairPlacementLevelId,
   resolveStairToLevelId,
 } from './lib/stair-levels'
+export {
+  clearSurfacePlanSnapFeedback,
+  resolveSurfacePlanPointSnap,
+  SURFACE_ALIGNMENT_THRESHOLD_M,
+  type SurfacePlanSnapInput,
+  type SurfacePlanSnapResult,
+} from './lib/surface-plan-snap'
 // `cn` (twMerge + clsx) — used by kind-owned panels in `@pascal-app/
 // nodes` so they don't need their own copy / their own tailwind-merge
 // dependency.
 export { cn } from './lib/utils'
 export {
   getActiveBuildingPose,
+  projectAlignmentGuidesWorldToActiveBuildingLocal,
   resolveAlignmentForActiveBuilding,
+  resolveAlignmentForFloorplanView,
   snapBuildingLocalToWorldGrid,
   snapWorldXZForActiveBuilding,
 } from './lib/world-grid-snap'
@@ -248,22 +408,75 @@ export { default as useAlignmentGuides } from './store/use-alignment-guides'
 export { default as useAudio } from './store/use-audio'
 export { type CommandAction, useCommandRegistry } from './store/use-command-registry'
 export type {
+  CaptureMode,
   FloorplanSelectionTool,
-  MovingFenceEndpoint,
-  MovingWallEndpoint,
+  SnapshotCropMode,
+  SnapshotStandardAspect,
   SplitOrientation,
   Tool,
   ToolDefaults,
   ViewMode,
   WorkspaceMode,
 } from './store/use-editor'
-export { default as useEditor } from './store/use-editor'
+export {
+  default as useEditor,
+  getActiveContinuationContext,
+  getContinuation,
+  isAlignmentGuideActive,
+  isAngleSnapActive,
+  isGridSnapActive,
+  isMagneticSnapActive,
+} from './store/use-editor'
+export { default as useFacingPose, type FacingPose } from './store/use-facing-pose'
+export { default as useFenceCurveDraft } from './store/use-fence-curve-draft'
+export {
+  default as useInteractionScope,
+  getEditingHole,
+  getIsCurveReshape,
+  getMovingNode,
+  useActiveHandleDrag,
+  useEditingHole,
+  useEndpointReshape,
+  useIsCurveReshape,
+  useMovingNode,
+  useReshapingNode,
+} from './store/use-interaction-scope'
+export {
+  commitMeasurementDraft,
+  finishMeasurementDraft,
+  handleMeasurementDraftEscape,
+  type MeasurementAxis,
+  type MeasurementAxisGuide,
+  type MeasurementDraftOwner,
+  type MeasurementDraftPayload,
+  type MeasurementDraftStage,
+  type MeasurementKind,
+  type MeasurementPoint,
+  type MeasurementSurfacePoint,
+  measurementPolygonMidpoints,
+  useMeasurementDraft,
+} from './store/use-measurement-draft'
+export {
+  default as useOpeningGuides,
+  type OpeningGuide3D,
+  type OpeningGuideVec3,
+} from './store/use-opening-guides'
 export {
   type PaletteView,
   type PaletteViewProps,
   usePaletteViewRegistry,
 } from './store/use-palette-view-registry'
 export { default as usePlacementPreview } from './store/use-placement-preview'
+export {
+  activateQuickMeasurementHudSource,
+  clearQuickMeasurementHudSource,
+  publishQuickMeasurementHudSource,
+  type QuickMeasurementHudEntry,
+  type QuickMeasurementHudSource,
+  selectQuickMeasurementHudEntry,
+  useQuickMeasurementHud,
+} from './store/use-quick-measurement-hud'
+export { default as useSegmentDraftChain } from './store/use-segment-draft-chain'
 export { useUploadStore } from './store/use-upload'
 export { useWallMoveGhosts, type WallMoveGhostBridge } from './store/use-wall-move-ghosts'
 export {

package/src/lib/active-placement-surface.ts

@@ -0,0 +1,35 @@
+import { Vector3 } from 'three'
+
+// The surface the active placement/move ghost is currently snapped to: a contact
+// point (world space) and the surface's outward unit normal. Published each frame
+// by the placement tools (the item coordinator + the drawn-kind tools) and read
+// by the grid so its snap patch sits at the ghost's height AND orients to the
+// surface — horizontal on a floor / shelf top, vertical in a wall plane.
+//
+// A plain module singleton (not a store): both writer and reader run inside
+// `useFrame`, so reactivity would only add overhead. The vectors are reused, so
+// readers must consume them within the same frame.
+export type PlacementSurface = {
+  point: Vector3
+  normal: Vector3
+}
+
+const surface: PlacementSurface = {
+  point: new Vector3(),
+  normal: new Vector3(0, 1, 0),
+}
+let active = false
+
+export function publishPlacementSurface(point: Vector3, normal: Vector3): void {
+  surface.point.copy(point)
+  surface.normal.copy(normal)
+  active = true
+}
+
+export function clearPlacementSurface(): void {
+  active = false
+}
+
+export function getPlacementSurface(): PlacementSurface | null {
+  return active ? surface : null
+}

package/src/lib/ceiling-plan-snap.ts

@@ -0,0 +1,24 @@
+import {
+  clearSurfacePlanSnapFeedback,
+  resolveSurfacePlanPointSnap,
+  SURFACE_ALIGNMENT_THRESHOLD_M,
+  type SurfacePlanSnapInput,
+  type SurfacePlanSnapResult,
+} from './surface-plan-snap'
+
+const CEILING_SNAP_MOVING_ID = '__ceiling_snap__'
+
+export const CEILING_ALIGNMENT_THRESHOLD_M = SURFACE_ALIGNMENT_THRESHOLD_M
+export type CeilingPlanSnapInput = SurfacePlanSnapInput
+export type CeilingPlanSnapResult = SurfacePlanSnapResult
+
+export function clearCeilingSnapFeedback() {
+  clearSurfacePlanSnapFeedback()
+}
+
+export function resolveCeilingPlanPointSnap(input: CeilingPlanSnapInput): CeilingPlanSnapResult {
+  return resolveSurfacePlanPointSnap({
+    ...input,
+    movingId: input.movingId ?? CEILING_SNAP_MOVING_ID,
+  })
+}

package/src/lib/contextual-help.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from 'bun:test'
+import { resolveSelectModeHelpHints } from './contextual-help'
+
+describe('resolveSelectModeHelpHints', () => {
+  test('stays hidden in idle select mode with no selection', () => {
+    expect(
+      resolveSelectModeHelpHints({
+        selectedCount: 0,
+        hasMovableSelection: false,
+        hasRotatableSelection: false,
+        commandPressed: false,
+        shiftPressed: false,
+      }),
+    ).toEqual([])
+  })
+
+  test('shows multi-select guidance when a modifier is held without selection', () => {
+    expect(
+      resolveSelectModeHelpHints({
+        selectedCount: 0,
+        hasMovableSelection: false,
+        hasRotatableSelection: false,
+        commandPressed: true,
+        shiftPressed: false,
+      }),
+    ).toEqual([
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: true,
+      },
+    ])
+  })
+
+  test('shows direct manipulation tips for selected movable and rotatable nodes', () => {
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 1,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: false,
+      shiftPressed: false,
+    })
+
+    expect(hints).toContainEqual({
+      keys: ['Left click'],
+      label: 'Drag selected movable object',
+    })
+    expect(hints).toContainEqual({
+      keys: ['Cmd/Ctrl', 'Right click'],
+      label: 'Drag left or right to rotate selected object',
+    })
+    // Cmd/Ctrl and Shift click both toggle selection membership (3D selection
+    // manager and 2D floorplan alike) — advertised as a single or-group row.
+    expect(hints).toContainEqual({
+      keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+      label: 'Add or remove objects from the selection',
+      active: false,
+    })
+  })
+
+  test('multi-selection advertises the group move + rotate gestures', () => {
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 3,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: false,
+      shiftPressed: false,
+    })
+
+    expect(hints).toEqual([
+      {
+        keys: ['Left click'],
+        label: 'Click or drag the selection to move it as one',
+      },
+      { keys: ['R / T'], label: 'Rotate the selection ±45°' },
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: false,
+      },
+      { keys: ['Esc'], label: 'Clear the selection (or click outside)' },
+    ])
+  })
+
+  test('holding a modifier keeps the same rows and only lights the selection one', () => {
+    // Guides/snapping are governed by the snapping mode (Shift toggles it),
+    // so no modifier-specific "freely / with guides / bypass" variants exist.
+    const hints = resolveSelectModeHelpHints({
+      selectedCount: 1,
+      hasMovableSelection: true,
+      hasRotatableSelection: true,
+      commandPressed: true,
+      shiftPressed: true,
+    })
+
+    expect(hints).toEqual([
+      {
+        keys: ['Left click'],
+        label: 'Drag selected movable object',
+      },
+      {
+        keys: ['Cmd/Ctrl', 'Right click'],
+        label: 'Drag left or right to rotate selected object',
+      },
+      {
+        keys: [['Cmd/Ctrl', 'Shift'], 'Left click'],
+        label: 'Add or remove objects from the selection',
+        active: true,
+      },
+    ])
+  })
+})

package/src/lib/contextual-help.ts

@@ -0,0 +1,144 @@
+export type ContextualShortcutHint = {
+  // A combo of keys pressed together (rendered joined by "+"). An entry may
+  // itself be an array of alternatives (rendered joined by "/"), e.g.
+  // [['Cmd/Ctrl', 'Shift'], 'Left click'] → "⌘ / ⇧ + click".
+  keys: Array<string | string[]>
+  label: string
+  // Optional secondary line under the label for a terser qualifier
+  // (e.g. "disable 15° snap"). The HUD wraps both lines rather than truncating.
+  subtitle?: string
+  active?: boolean
+}
+
+// `activeHandleDrag.label` value a rotate gizmo sets while dragging, so the
+// contextual HUD can surface the Shift = free-rotation toggle for the duration
+// (mirrors how wall drafting advertises Shift). Distinct from resize handles,
+// which route their own measurement label here.
+export const ROTATE_HANDLE_DRAG_LABEL = 'rotate-handle'
+
+// `activeHandleDrag.label` a plain resize / radial-resize arrow sets while
+// dragging (when it carries no dimension `measureLabel`). It exists only so the
+// interaction scope is non-idle during a resize, which keeps the idle
+// select-mode hints off-screen — a resize is its own action, not a selection.
+export const RESIZE_HANDLE_DRAG_LABEL = 'resize-handle'
+
+// `activeHandleDrag.label`s for the multi-selection group drags: the body
+// drag sessions (2D floorplan + 3D ground plane) and the rotate gizmo. Kept
+// here (not in the session/gizmo modules) so `snapping-mode.ts` can resolve
+// the group move to the 'item' snap context without importing component code.
+export const GROUP_MOVE_DRAG_LABEL = 'group-move-handle'
+export const GROUP_ROTATE_DRAG_LABEL = 'group-rotate-handle'
+
+// Hints shown while a rotate gizmo is mid-drag: Shift bypasses the angle step
+// (free rotation), the same toggle wall drafting exposes. `active` lights the
+// pill while Shift is held.
+export function resolveRotateHandleHelpHints(shiftPressed: boolean): ContextualShortcutHint[] {
+  return [
+    {
+      keys: [SHIFT_KEY],
+      label: shiftPressed ? 'Rotating freely (no angle step)' : 'Hold to rotate freely',
+      active: shiftPressed,
+    },
+  ]
+}
+
+export type SelectModeHelpContext = {
+  selectedCount: number
+  hasMovableSelection: boolean
+  hasRotatableSelection: boolean
+  commandPressed: boolean
+  shiftPressed: boolean
+  // When a single MEP node is selected its in-world handle rig (click a dot to
+  // reveal move arrows) is the real editing path, so the panel leads with the
+  // handle-specific hints instead of just the generic Cmd-drag tips.
+  mepSelection?: 'run' | 'fitting' | null
+}
+
+const COMMAND_KEY = 'Cmd/Ctrl'
+const LEFT_CLICK = 'Left click'
+const RIGHT_CLICK = 'Right click'
+const SHIFT_KEY = 'Shift'
+const CLICK = 'Click'
+const ALT_KEY = 'Alt'
+const ROTATE_KEYS = 'R / T'
+const ESC_KEY = 'Esc'
+
+export function resolveSelectModeHelpHints({
+  selectedCount,
+  hasMovableSelection,
+  hasRotatableSelection,
+  commandPressed,
+  shiftPressed,
+  mepSelection = null,
+}: SelectModeHelpContext): ContextualShortcutHint[] {
+  const hints: ContextualShortcutHint[] = []
+
+  if (selectedCount === 0) {
+    if (!commandPressed && !shiftPressed) return hints
+
+    hints.push({
+      keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+      label: 'Add or remove objects from the selection',
+      active: true,
+    })
+    return hints
+  }
+
+  // Multi-selection — advertise the group gestures: drag any member to slide
+  // the whole selection (2D floor plan body drag + the 3D move gizmo), R / T
+  // to step-rotate the group around its bounding-box center.
+  if (selectedCount > 1) {
+    hints.push({
+      keys: [LEFT_CLICK],
+      label: 'Click or drag the selection to move it as one',
+    })
+    hints.push({ keys: [ROTATE_KEYS], label: 'Rotate the selection ±45°' })
+    hints.push({
+      keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+      label: 'Add or remove objects from the selection',
+      active: commandPressed || shiftPressed,
+    })
+    hints.push({ keys: [ESC_KEY], label: 'Clear the selection (or click outside)' })
+    return hints
+  }
+
+  // MEP handle workflow — duct/pipe runs and fittings are edited through the
+  // in-world arrow rig that a click on the handle dot reveals, so surface those
+  // hints first. A run endpoint's side / up-down arrows swing the run and Alt
+  // detaches the joint mid-drag; a fitting's cluster adds rotate arcs, with
+  // R / T (and Alt to switch axis) for keyboard rotation.
+  if (mepSelection === 'run') {
+    hints.push({ keys: [CLICK], label: 'Click a handle dot to show move arrows' })
+    hints.push({ keys: [ALT_KEY], label: 'Detach the joint while dragging an arrow' })
+  } else if (mepSelection === 'fitting') {
+    hints.push({ keys: [CLICK], label: 'Click the handle dot to show move + rotate handles' })
+    hints.push({ keys: [ROTATE_KEYS], label: 'Rotate ±45°' })
+    hints.push({ keys: [ALT_KEY], label: 'Switch the rotation axis (Y → X → Z)' })
+  }
+
+  // The rows are the same whatever modifier is held — guides/snapping are
+  // governed by the snapping mode (Shift toggles it), not by the modifier of
+  // this gesture, so there are no modifier-specific variants to advertise.
+  // Holding Cmd/Ctrl or Shift just lights the selection row.
+  if (hasMovableSelection) {
+    hints.push({
+      keys: [LEFT_CLICK],
+      label: 'Drag selected movable object',
+    })
+  }
+
+  if (hasRotatableSelection) {
+    hints.push({
+      keys: [COMMAND_KEY, RIGHT_CLICK],
+      label: 'Drag left or right to rotate selected object',
+    })
+  }
+
+  hints.push({
+    keys: [[COMMAND_KEY, SHIFT_KEY], LEFT_CLICK],
+    label: 'Add or remove objects from the selection',
+    active: commandPressed || shiftPressed,
+  })
+
+  return hints
+}