Selection Managers

Two-layer selection architecture: viewer manager (hierarchy) + editor manager (phase-aware).

Applies to: packages/viewer/src/components/viewer/selection-manager.tsx, apps/editor/components/editor/selection-manager.tsx.

There are two selection managers. They are separate components, not the same component configured differently.

Component	Location	Knows about
`SelectionManager`	`packages/viewer/src/components/viewer/selection-manager.tsx`	Viewer state only
`SelectionManager` (editor)	`apps/editor/components/editor/selection-manager.tsx`	Phase, mode, tool state

The viewer's manager is the default. The editor mounts its own manager as a child of <Viewer>, overriding the default behaviour via the viewer-isolation pattern.

How Selection Works

Event flow:

useNodeEvents(node, type) on a renderer mesh
  → emitter.emit('wall:click', NodeEvent)
  → SelectionManager listens via emitter.on(…)
  → calls useViewer.setSelection(…)
  → outliner sync re-runs → Three.js outline updates

useNodeEvents returns R3F pointer handlers. Spread them onto the mesh:

const events = useNodeEvents(node, 'wall')
return <mesh ref={ref} {...events} />

Events are suppressed during camera drag (useViewer.getState().cameraDragging).

Viewer Selection Manager

Hierarchical path: Building → Level → Zone → Elements

At each level, only the next tier is selectable. Clicking outside deselects. The path is stored in useViewer:

type SelectionPath = {
  buildingId: string | null
  levelId: string | null
  zoneId: string | null
  selectedIds: string[]   // walls, items, slabs, etc.
}

setSelection has a hierarchy guard: setting levelId without buildingId resets children. Use resetSelection() to clear everything.

Multi-select: Ctrl/Meta + click toggles an ID in selectedIds. Regular click replaces it.

Editor Selection Manager

Extends selection with phase awareness from useEditor. The viewer's SelectionManager is not mounted in the editor; this one takes its place (injected as a child of <Viewer>).

phase: 'site'      → selectable: buildings
phase: 'structure' → selectable: walls, zones, slabs, ceilings, roofs, doors, windows
  structureLayer: 'zones'    → only zones
  structureLayer: 'elements' → all structure types
phase: 'furnish'   → selectable: furniture items only

Clicking a node of a different phase auto-switches the phase. Double-click drills into a context level.

In Select mode, 3D and 2D canvas selection share the same modifier vocabulary:

Ctrl/Meta + click toggles the clicked object in selectedIds.
Shift + click also toggles the clicked canvas object so users can multi-select from either viewport. The scene graph keeps file-browser semantics: Shift + click selects the visible range between the last selected row and the clicked row.
Ctrl/Meta + left-drag on a selected movable object starts direct move from the canvas.
Ctrl/Meta + right-drag on a selected rotatable object starts direct rotation from the canvas. Rotation snaps to the default angle increment unless Shift is held during the drag.

The floating helper in packages/editor/src/components/ui/helpers/helper-manager.tsx mirrors these rules from current selection state and held modifiers. Keep that helper and the shortcut dialog in sync when changing selection gestures.

Rules

Never add selection logic to renderers. Renderers spread useNodeEvents events and stop there. All selection decisions live in the selection manager.
Never add editor phase logic to the viewer's SelectionManager. Phase, mode, and tool awareness belong exclusively in the editor's selection manager.
useViewer is the single source of truth for selection state. Both managers read and write through setSelection / resetSelection. Nothing else should mutate selection directly.
Outliner arrays are mutated in-place (not replaced) for performance. Don't assign new arrays to outliner.selectedObjects or outliner.hoveredObjects.
Hover is a separate scalar (hoveredId: string | null), not part of selectedIds. Update it via setHoveredId.

Adding Selectability to a New Node Type

Add the type to SelectableNodeType in the viewer store / selection manager.
Make sure its renderer calls useNodeEvents(node, type) and spreads the handlers.
Add a case to whichever selection strategy needs it (viewer hierarchy level or editor phase).
Ensure useRegistry is called in the renderer so the outliner can highlight it.

4.6 KiB Raw Blame History